deepset-mcp 0.0.2__py3-none-any.whl

deepset_mcp/api/indexes/resource.py

@@ -0,0 +1,138 @@
+from deepset_mcp.api.exceptions import UnexpectedAPIError
+from deepset_mcp.api.indexes.models import Index, IndexList
+from deepset_mcp.api.indexes.protocols import IndexResourceProtocol
+from deepset_mcp.api.pipeline.models import PipelineValidationResult, ValidationError
+from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.transport import raise_for_status
+
+
+class IndexResource(IndexResourceProtocol):
+    """Resource for interacting with deepset indexes."""
+
+    def __init__(self, client: AsyncClientProtocol, workspace: str) -> None:
+        """Initialize the index resource.
+
+        :param client: The async REST client.
+        :param workspace: The workspace to use.
+        """
+        self._client = client
+        self._workspace = workspace
+
+    async def list(self, limit: int = 10, page_number: int = 1) -> IndexList:
+        """List all indexes.
+
+        :param limit: Maximum number of indexes to return.
+        :param page_number: Page number for pagination.
+
+        :returns: List of indexes.
+        """
+        params = {
+            "limit": limit,
+            "page_number": page_number,
+        }
+
+        response = await self._client.request(f"/v1/workspaces/{self._workspace}/indexes", params=params)
+
+        raise_for_status(response)
+
+        return IndexList.model_validate(response.json)
+
+    async def get(self, index_name: str) -> Index:
+        """Get a specific index.
+
+        :param index_name: Name of the index.
+
+        :returns: Index details.
+        """
+        response = await self._client.request(f"/v1/workspaces/{self._workspace}/indexes/{index_name}")
+
+        raise_for_status(response)
+
+        return Index.model_validate(response.json)
+
+    async def create(self, name: str, yaml_config: str, description: str | None = None) -> Index:
+        """Create a new index with the given name and configuration.
+
+        :param name: Name of the index
+        :param yaml_config: YAML configuration for the index
+        :param description: Optional description for the index
+        :returns: Created index details
+        """
+        data = {
+            "name": name,
+            "config_yaml": yaml_config,
+        }
+        if description is not None:
+            data["description"] = description
+
+        response = await self._client.request(f"v1/workspaces/{self._workspace}/indexes", method="POST", data=data)
+
+        raise_for_status(response)
+
+        return Index.model_validate(response.json)
+
+    async def update(
+        self, index_name: str, updated_index_name: str | None = None, yaml_config: str | None = None
+    ) -> Index:
+        """Update name and/or configuration of an existing index.
+
+        :param index_name: Name of the index to update
+        :param updated_index_name: Optional new name for the index
+        :param yaml_config: Optional new YAML configuration
+        :returns: Updated index details
+        """
+        data = {}
+        if updated_index_name is not None:
+            data["name"] = updated_index_name
+        if yaml_config is not None:
+            data["config_yaml"] = yaml_config
+
+        if not data:
+            raise ValueError("At least one of updated_index_name or yaml_config must be provided")
+
+        response = await self._client.request(
+            f"/v1/workspaces/{self._workspace}/indexes/{index_name}", method="PATCH", data=data
+        )
+
+        raise_for_status(response)
+
+        return Index.model_validate(response.json)
+
+    async def delete(self, index_name: str) -> None:
+        """Delete an index.
+
+        :param index_name: Name of the index to delete.
+        """
+        response = await self._client.request(f"/v1/workspaces/{self._workspace}/indexes/{index_name}", method="DELETE")
+
+        raise_for_status(response)
+
+    async def deploy(self, index_name: str) -> PipelineValidationResult:
+        """Deploy an index.
+
+        :param index_name: Name of the index to deploy.
+        :returns: PipelineValidationResult containing deployment status and any errors.
+        :raises UnexpectedAPIError: If the API returns an unexpected status code.
+        """
+        resp = await self._client.request(
+            endpoint=f"v1/workspaces/{self._workspace}/indexes/{index_name}/deploy",
+            method="POST",
+        )
+
+        # If successful (status 200), the deployment was successful
+        if resp.success:
+            return PipelineValidationResult(valid=True)
+
+        # Handle validation errors (422)
+        if resp.status_code == 422 and resp.json is not None and isinstance(resp.json, dict) and "details" in resp.json:
+            errors = [ValidationError(code=error["code"], message=error["message"]) for error in resp.json["details"]]
+            return PipelineValidationResult(valid=False, errors=errors)
+
+        # Handle other 4xx errors (400, 404, 424)
+        if 400 <= resp.status_code < 500:
+            # For non-validation errors, create a generic error
+            error_message = resp.text if resp.text else f"HTTP {resp.status_code} error"
+            errors = [ValidationError(code="DEPLOYMENT_ERROR", message=error_message)]
+            return PipelineValidationResult(valid=False, errors=errors)
+
+        raise UnexpectedAPIError(status_code=resp.status_code, message=resp.text, detail=resp.json)

deepset_mcp/api/integrations/__init__.py

@@ -0,0 +1 @@
+"""Integration API resources and models."""

deepset_mcp/api/integrations/models.py

@@ -0,0 +1,49 @@
+"""Models for the integrations API."""
+
+from enum import StrEnum
+from uuid import UUID
+
+from pydantic import BaseModel
+
+
+class IntegrationProvider(StrEnum):
+    """Supported integration providers."""
+
+    AWS_BEDROCK = "aws-bedrock"
+    AZURE_DOCUMENT_INTELLIGENCE = "azure-document-intelligence"
+    AZURE_OPENAI = "azure-openai"
+    COHERE = "cohere"
+    DEEPL = "deepl"
+    GOOGLE = "google"
+    HUGGINGFACE = "huggingface"
+    NVIDIA = "nvidia"
+    OPENAI = "openai"
+    SEARCHAPI = "searchapi"
+    SNOWFLAKE = "snowflake"
+    UNSTRUCTURED = "unstructured"
+    VOYAGE_AI = "voyage-ai"
+    WANDB_AI = "wandb-ai"
+    MONGODB = "mongodb"
+    TOGETHER_AI = "together-ai"
+
+
+class Integration(BaseModel):
+    """Model representing an integration."""
+
+    invalid: bool
+    model_registry_token_id: UUID
+    provider: IntegrationProvider
+    provider_domain: str
+
+
+class IntegrationList(BaseModel):
+    """Model representing a list of integrations."""
+
+    integrations: list[Integration]
+
+    def __len__(self) -> int:
+        """Return the length of the list.
+
+        :returns: Number of integrations.
+        """
+        return len(self.integrations)

deepset_mcp/api/integrations/protocols.py

@@ -0,0 +1,27 @@
+"""Protocol definitions for integrations resource."""
+
+from typing import TYPE_CHECKING, Protocol
+
+from deepset_mcp.api.integrations.models import Integration, IntegrationList, IntegrationProvider
+
+if TYPE_CHECKING:
+    pass
+
+
+class IntegrationResourceProtocol(Protocol):
+    """Protocol for integration resource operations."""
+
+    async def list(self) -> IntegrationList:
+        """Retrieve all integrations.
+
+        :returns: IntegrationList containing all available integrations.
+        """
+        ...
+
+    async def get(self, provider: IntegrationProvider) -> Integration:
+        """Retrieve a specific integration by provider.
+
+        :param provider: The integration provider to retrieve.
+        :returns: Integration instance for the specified provider.
+        """
+        ...

deepset_mcp/api/integrations/resource.py

@@ -0,0 +1,57 @@
+"""Resource implementation for integrations API."""
+
+import logging
+from typing import TYPE_CHECKING
+
+from deepset_mcp.api.integrations.models import Integration, IntegrationList, IntegrationProvider
+from deepset_mcp.api.integrations.protocols import IntegrationResourceProtocol
+from deepset_mcp.api.transport import raise_for_status
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from deepset_mcp.api.protocols import AsyncClientProtocol
+
+
+class IntegrationResource(IntegrationResourceProtocol):
+    """Manages interactions with the deepset integrations API."""
+
+    def __init__(self, client: "AsyncClientProtocol") -> None:
+        """Initialize an IntegrationResource instance.
+
+        :param client: The async client protocol instance.
+        """
+        self._client = client
+
+    async def list(self) -> IntegrationList:
+        """Retrieve all integrations.
+
+        :returns: IntegrationList containing all available integrations.
+        """
+        resp = await self._client.request(
+            endpoint="v1/model_registry_tokens",
+            method="GET",
+        )
+
+        raise_for_status(resp)
+
+        if resp.json is not None:
+            integrations = [Integration.model_validate(item) for item in resp.json]
+            return IntegrationList(integrations=integrations)
+        else:
+            return IntegrationList(integrations=[])
+
+    async def get(self, provider: IntegrationProvider) -> Integration:
+        """Retrieve a specific integration by provider.
+
+        :param provider: The integration provider to retrieve.
+        :returns: Integration instance for the specified provider.
+        """
+        resp = await self._client.request(
+            endpoint=f"v1/model_registry_tokens/{provider.value}",
+            method="GET",
+        )
+
+        raise_for_status(resp)
+
+        return Integration.model_validate(resp.json)

deepset_mcp/api/pipeline/__init__.py

@@ -0,0 +1,17 @@
+from .models import (
+    DeepsetPipeline,
+    PipelineLog,
+    PipelineLogList,
+    PipelineValidationResult,
+    ValidationError,
+)
+from .resource import PipelineResource
+
+__all__ = [
+    "DeepsetPipeline",
+    "PipelineValidationResult",
+    "ValidationError",
+    "PipelineResource",
+    "PipelineLog",
+    "PipelineLogList",
+]

deepset_mcp/api/pipeline/log_level.py

@@ -0,0 +1,9 @@
+from enum import StrEnum
+
+
+class LogLevel(StrEnum):
+    """Log level filter options for pipeline logs."""
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"

deepset_mcp/api/pipeline/models.py

@@ -0,0 +1,235 @@
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, Field, model_validator
+from rich.repr import Result
+
+from deepset_mcp.api.shared_models import DeepsetUser
+
+
+class PipelineServiceLevel(StrEnum):
+    """Describes the service level of a pipeline."""
+
+    PRODUCTION = "PRODUCTION"
+    DEVELOPMENT = "DEVELOPMENT"
+    DRAFT = "DRAFT"
+
+
+class DeepsetPipeline(BaseModel):
+    """Model representing a pipeline on the deepset platform."""
+
+    id: str = Field(alias="pipeline_id")
+    name: str
+    status: str
+    service_level: PipelineServiceLevel
+
+    created_at: datetime
+    last_updated_at: datetime | None = Field(None, alias="last_edited_at")  # Map API's last_edited_at
+
+    created_by: DeepsetUser
+    last_updated_by: DeepsetUser | None = Field(None, alias="last_edited_by")  # Map API's last_edited_by
+
+    yaml_config: str | None = None
+
+    class Config:
+        """Configuration for serialization and deserialization."""
+
+        populate_by_name = True  # Allow both alias and model field names
+        json_encoders = {
+            # When serializing back to JSON, convert datetimes to ISO format
+            datetime: lambda dt: dt.isoformat()
+        }
+
+    def __rich_repr__(self) -> Result:
+        """Used to display the model in an LLM friendly way."""
+        yield "name", self.name
+        yield "service_level", self.service_level.value
+        yield "status", self.status
+        yield "created_by", f"{self.created_by.given_name} {self.created_by.family_name} ({self.created_by.id})"
+        yield "created_at", self.created_at.strftime("%m/%d/%Y %I:%M:%S %p")
+        yield (
+            "last_updated_by",
+            f"{self.last_updated_by.given_name} {self.last_updated_by.family_name} ({self.last_updated_by.id})"
+            if self.last_updated_by
+            else None,
+        )
+        yield "last_updated_at", self.last_updated_at.strftime("%m/%d/%Y %I:%M:%S %p") if self.last_updated_at else None
+        yield "yaml_config", self.yaml_config if self.yaml_config is not None else "Get full pipeline to see config."
+
+
+class ValidationError(BaseModel):
+    """Model representing a validation error from the pipeline validation API."""
+
+    code: str
+    message: str
+
+
+class PipelineValidationResult(BaseModel):
+    """Result of validating a pipeline configuration."""
+
+    valid: bool
+    errors: list[ValidationError] = []
+
+    def __rich_repr__(self) -> Result:
+        """Used to display the model in an LLM friendly way."""
+        yield "valid", self.valid
+        yield "errors", [f"{e.message} ({e.code})" for e in self.errors]
+
+
+class TraceFrame(BaseModel):
+    """Model representing a single frame in a stack trace."""
+
+    filename: str
+    line_number: int
+    name: str
+
+
+class ExceptionInfo(BaseModel):
+    """Model representing exception information."""
+
+    type: str
+    value: str
+    trace: list[TraceFrame]
+
+
+class PipelineLog(BaseModel):
+    """Model representing a single log entry from a pipeline."""
+
+    log_id: str
+    message: str
+    logged_at: datetime
+    level: str
+    origin: str
+    exceptions: list[ExceptionInfo] | None = None
+    extra_fields: dict[str, Any] = Field(default_factory=dict)
+
+
+class PipelineLogList(BaseModel):
+    """Model representing a paginated list of pipeline logs."""
+
+    data: list[PipelineLog]
+    has_more: bool
+    total: int
+
+
+# Search-related models
+
+
+class OffsetRange(BaseModel):
+    """Model representing an offset range."""
+
+    start: int
+    end: int
+
+
+class DeepsetAnswer(BaseModel):
+    """Model representing a search answer."""
+
+    answer: str  # Required field
+    context: str | None = None
+    document_id: str | None = None
+    document_ids: list[str] | None = None
+    file: dict[str, Any] | None = None
+    files: list[dict[str, Any]] | None = None
+    meta: dict[str, Any] | None = None
+    offsets_in_context: list[OffsetRange] | None = None
+    offsets_in_document: list[OffsetRange] | None = None
+    prompt: str | None = None
+    result_id: UUID | None = None
+    score: float | None = None
+    type: str | None = None
+
+
+class DeepsetDocument(BaseModel):
+    """Model representing a search document."""
+
+    content: str  # Required field
+    meta: dict[str, Any]  # Required field - can hold any value
+    embedding: list[float] | None = None
+    file: dict[str, Any] | None = None
+    id: str | None = None
+    result_id: UUID | None = None
+    score: float | None = None
+
+
+class DeepsetSearchResponse(BaseModel):
+    """Model representing a single search result."""
+
+    debug: dict[str, Any] | None = Field(default=None, alias="_debug")
+    answers: list[DeepsetAnswer] = Field(default_factory=list)
+    documents: list[DeepsetDocument] = Field(default_factory=list)
+    prompts: dict[str, str] | None = None
+    query: str | None = None
+    query_id: UUID | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_response(cls, data: dict[str, Any]) -> dict[str, Any]:
+        """Normalize the response from the search and search-stream endpoints.
+
+        The search endpoint returns a list of results, but we only ever use the first result.
+        We are not sending batch queries, so there will never be more than one result.
+        We use this validator to transform the data so that we can use the same response model for search and
+            search-stream endpoints.
+        """
+        # Handle non-stream format with 'results' array
+        if "results" in data and isinstance(data["results"], list):
+            if len(data["results"]) > 0:
+                first_result = data["results"][
+                    0
+                ]  # we only ever care for the first result as we don't use batch queries
+                normalized = {
+                    "query_id": data.get("query_id", first_result.get("query_id")),
+                    "query": first_result.get("query"),
+                    "answers": first_result.get("answers", []),
+                    "documents": first_result.get("documents", []),
+                    "prompts": first_result.get("prompts"),
+                    "_debug": first_result.get("_debug") or first_result.get("debug"),
+                }
+                return normalized
+            else:
+                return {}
+        else:
+            return data
+
+
+class StreamDelta(BaseModel):
+    """Model representing a streaming delta."""
+
+    text: str
+    meta: dict[str, Any] | None = None
+
+
+class DeepsetStreamEvent(BaseModel):
+    """Model representing a stream event."""
+
+    query_id: str | UUID | None = None
+    type: str  # "delta", "result", or "error"
+    delta: StreamDelta | None = None
+    result: DeepsetSearchResponse | None = None
+    error: str | None = None
+
+
+class PipelineList(BaseModel):
+    """Response model for listing pipelines."""
+
+    data: list[DeepsetPipeline]
+    has_more: bool
+    total: int
+
+
+class PipelineValidationResultWithYaml(BaseModel):
+    """Model for pipeline validation result that includes the original YAML."""
+
+    validation_result: PipelineValidationResult
+    yaml_config: str
+
+
+class PipelineOperationWithErrors(BaseModel):
+    """Model for pipeline operations that complete with validation errors."""
+
+    message: str
+    validation_result: PipelineValidationResult
+    pipeline: DeepsetPipeline

deepset_mcp/api/pipeline/protocols.py

@@ -0,0 +1,83 @@
+from collections.abc import AsyncIterator
+from typing import Any, Protocol
+
+from deepset_mcp.api.pipeline.log_level import LogLevel
+from deepset_mcp.api.pipeline.models import (
+    DeepsetPipeline,
+    DeepsetSearchResponse,
+    DeepsetStreamEvent,
+    PipelineList,
+    PipelineLogList,
+    PipelineValidationResult,
+)
+from deepset_mcp.api.shared_models import NoContentResponse
+
+
+class PipelineResourceProtocol(Protocol):
+    """Protocol defining the implementation for PipelineResource."""
+
+    async def validate(self, yaml_config: str) -> PipelineValidationResult:
+        """Validate a pipeline's YAML configuration against the API."""
+        ...
+
+    async def get(self, pipeline_name: str, include_yaml: bool = True) -> DeepsetPipeline:
+        """Fetch a single pipeline by its name."""
+        ...
+
+    async def list(
+        self,
+        page_number: int = 1,
+        limit: int = 10,
+    ) -> PipelineList:
+        """List pipelines in the configured workspace with optional pagination."""
+        ...
+
+    async def create(self, name: str, yaml_config: str) -> NoContentResponse:
+        """Create a new pipeline with a name and YAML config."""
+        ...
+
+    async def update(
+        self,
+        pipeline_name: str,
+        updated_pipeline_name: str | None = None,
+        yaml_config: str | None = None,
+    ) -> NoContentResponse:
+        """Update name and/or YAML config of an existing pipeline."""
+        ...
+
+    async def get_logs(
+        self,
+        pipeline_name: str,
+        limit: int = 30,
+        level: LogLevel | None = None,
+    ) -> PipelineLogList:
+        """Fetch logs for a specific pipeline."""
+        ...
+
+    async def deploy(self, pipeline_name: str) -> PipelineValidationResult:
+        """Deploy a pipeline."""
+        ...
+
+    async def search(
+        self,
+        pipeline_name: str,
+        query: str,
+        debug: bool = False,
+        view_prompts: bool = False,
+        params: dict[str, Any] | None = None,
+        filters: dict[str, Any] | None = None,
+    ) -> DeepsetSearchResponse:
+        """Search using a pipeline."""
+        ...
+
+    def search_stream(
+        self,
+        pipeline_name: str,
+        query: str,
+        debug: bool = False,
+        view_prompts: bool = False,
+        params: dict[str, Any] | None = None,
+        filters: dict[str, Any] | None = None,
+    ) -> AsyncIterator[DeepsetStreamEvent]:
+        """Search using a pipeline with response streaming."""
+        ...