deepset-mcp 0.0.2__py3-none-any.whl

deepset_mcp/tools/pipeline.py

@@ -0,0 +1,335 @@
+import asyncio
+
+import yaml
+
+from deepset_mcp.api.exceptions import BadRequestError, ResourceNotFoundError, UnexpectedAPIError
+from deepset_mcp.api.pipeline.log_level import LogLevel
+from deepset_mcp.api.pipeline.models import (
+    DeepsetPipeline,
+    DeepsetSearchResponse,
+    PipelineList,
+    PipelineLogList,
+    PipelineOperationWithErrors,
+    PipelineValidationResult,
+    PipelineValidationResultWithYaml,
+)
+from deepset_mcp.api.protocols import AsyncClientProtocol
+
+
+async def list_pipelines(*, client: AsyncClientProtocol, workspace: str) -> PipelineList | str:
+    """Retrieves a list of all pipeline available within the currently configured deepset workspace.
+
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :returns: List of pipelines or error message.
+    """
+    try:
+        return await client.pipelines(workspace=workspace).list()
+    except ResourceNotFoundError:
+        return f"There is no workspace named '{workspace}'. Did you mean to configure it?"
+    except (BadRequestError, UnexpectedAPIError) as e:
+        return f"Failed to list pipelines: {e}"
+
+
+async def get_pipeline(*, client: AsyncClientProtocol, workspace: str, pipeline_name: str) -> DeepsetPipeline | str:
+    """Fetches detailed configuration information for a specific pipeline, identified by its unique `pipeline_name`.
+
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :param pipeline_name: The name of the pipeline to fetch.
+    :returns: Pipeline details or error message.
+    """
+    try:
+        return await client.pipelines(workspace=workspace).get(pipeline_name=pipeline_name)
+    except ResourceNotFoundError:
+        return f"There is no pipeline named '{pipeline_name}' in workspace '{workspace}'."
+    except (BadRequestError, UnexpectedAPIError) as e:
+        return f"Failed to fetch pipeline '{pipeline_name}': {e}"
+
+
+async def validate_pipeline(
+    *, client: AsyncClientProtocol, workspace: str, yaml_configuration: str
+) -> PipelineValidationResultWithYaml | str:
+    """Validates the provided pipeline YAML configuration against the deepset API.
+
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :param yaml_configuration: The YAML configuration to validate.
+    :returns: Validation result with original YAML or error message.
+    """
+    if not yaml_configuration or not yaml_configuration.strip():
+        return "You need to provide a YAML configuration to validate."
+
+    try:
+        yaml.safe_load(yaml_configuration)
+    except yaml.YAMLError as e:
+        return f"Invalid YAML provided: {e}"
+
+    try:
+        response = await client.pipelines(workspace=workspace).validate(yaml_configuration)
+        return PipelineValidationResultWithYaml(validation_result=response, yaml_config=yaml_configuration)
+    except ResourceNotFoundError:
+        return f"There is no workspace named '{workspace}'. Did you mean to configure it?"
+    except (BadRequestError, UnexpectedAPIError) as e:
+        return f"Failed to validate pipeline: {e}"
+
+
+async def create_pipeline(
+    *,
+    client: AsyncClientProtocol,
+    workspace: str,
+    pipeline_name: str,
+    yaml_configuration: str,
+    skip_validation_errors: bool = True,
+) -> DeepsetPipeline | PipelineOperationWithErrors | str:
+    """Creates a new pipeline within the currently configured deepset workspace.
+
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :param pipeline_name: Name of the pipeline to create.
+    :param yaml_configuration: YAML configuration for the pipeline.
+    :param skip_validation_errors: If True (default), creates the pipeline even if validation fails.
+                                  If False, stops creation when validation fails.
+    :returns: Created pipeline or error message.
+    """
+    try:
+        validation_response = await client.pipelines(workspace=workspace).validate(yaml_configuration)
+
+        if not validation_response.valid and not skip_validation_errors:
+            error_messages = [f"{error.code}: {error.message}" for error in validation_response.errors]
+            return "Pipeline validation failed:\n" + "\n".join(error_messages)
+
+        await client.pipelines(workspace=workspace).create(name=pipeline_name, yaml_config=yaml_configuration)
+
+        # Get the full pipeline after creation
+        pipeline = await client.pipelines(workspace=workspace).get(pipeline_name)
+
+        # If validation failed but we proceeded anyway, return the special model
+        if not validation_response.valid:
+            return PipelineOperationWithErrors(
+                message="The operation completed with errors", validation_result=validation_response, pipeline=pipeline
+            )
+
+        # Otherwise return just the pipeline
+        return pipeline
+
+    except ResourceNotFoundError:
+        return f"There is no workspace named '{workspace}'. Did you mean to configure it?"
+    except BadRequestError as e:
+        return f"Failed to create pipeline '{pipeline_name}': {e}"
+    except UnexpectedAPIError as e:
+        return f"Failed to create pipeline '{pipeline_name}': {e}"
+
+
+async def update_pipeline(
+    *,
+    client: AsyncClientProtocol,
+    workspace: str,
+    pipeline_name: str,
+    original_config_snippet: str,
+    replacement_config_snippet: str,
+    skip_validation_errors: bool = True,
+) -> DeepsetPipeline | PipelineOperationWithErrors | str:
+    """
+    Updates a pipeline configuration in the specified workspace with a replacement configuration snippet.
+
+    This function validates the replacement configuration snippet before applying it to the pipeline.
+    If the validation fails and skip_validation_errors is False, it returns error messages.
+    Otherwise, the replacement snippet is used to update the pipeline's configuration.
+
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :param pipeline_name: Name of the pipeline to update.
+    :param original_config_snippet: The configuration snippet to replace.
+    :param replacement_config_snippet: The new configuration snippet.
+    :param skip_validation_errors: If True (default), updates the pipeline even if validation fails.
+                                  If False, stops update when validation fails.
+    :returns: Updated pipeline or error message.
+    """
+    try:
+        original_pipeline = await client.pipelines(workspace=workspace).get(pipeline_name=pipeline_name)
+    except ResourceNotFoundError:
+        return f"There is no pipeline named '{pipeline_name}'. Did you mean to create it?"
+    except (BadRequestError, UnexpectedAPIError) as e:
+        return f"Failed to fetch pipeline '{pipeline_name}': {e}"
+
+    if original_pipeline.yaml_config is None:
+        return f"The pipeline '{pipeline_name}' does not have a YAML configuration."
+
+    occurrences = original_pipeline.yaml_config.count(original_config_snippet)
+
+    if occurrences == 0:
+        return f"No occurrences of the provided configuration snippet were found in the pipeline '{pipeline_name}'."
+
+    if occurrences > 1:
+        return (
+            f"Multiple occurrences ({occurrences}) of the provided configuration snippet were found in the pipeline "
+            f"'{pipeline_name}'. Specify a more precise snippet to proceed with the update."
+        )
+
+    updated_yaml_configuration = original_pipeline.yaml_config.replace(
+        original_config_snippet, replacement_config_snippet, 1
+    )
+
+    try:
+        validation_response = await client.pipelines(workspace=workspace).validate(updated_yaml_configuration)
+
+        if not validation_response.valid and not skip_validation_errors:
+            error_messages = [f"{error.code}: {error.message}" for error in validation_response.errors]
+            return "Pipeline validation failed:\n" + "\n".join(error_messages)
+
+        await client.pipelines(workspace=workspace).update(
+            pipeline_name=pipeline_name, yaml_config=updated_yaml_configuration
+        )
+
+        # Get the full pipeline after update
+        pipeline = await client.pipelines(workspace=workspace).get(pipeline_name)
+
+        # If validation failed but we proceeded anyway, return the special model
+        if not validation_response.valid:
+            return PipelineOperationWithErrors(
+                message="The operation completed with errors", validation_result=validation_response, pipeline=pipeline
+            )
+
+        # Otherwise return just the pipeline
+        return pipeline
+
+    except ResourceNotFoundError:
+        return f"There is no pipeline named '{pipeline_name}'. Did you mean to create it?"
+    except BadRequestError as e:
+        return f"Failed to update the pipeline '{pipeline_name}': {e}"
+    except UnexpectedAPIError as e:
+        return f"Failed to update the pipeline '{pipeline_name}': {e}"
+
+
+async def get_pipeline_logs(
+    *, client: AsyncClientProtocol, workspace: str, pipeline_name: str, limit: int = 30, level: LogLevel | None = None
+) -> PipelineLogList | str:
+    """Fetches logs for a specific pipeline.
+
+    Retrieves log entries for the specified pipeline, with optional filtering by log level.
+    This is useful for debugging pipeline issues or monitoring pipeline execution.
+
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :param pipeline_name: Name of the pipeline to fetch logs for.
+    :param limit: Maximum number of log entries to return (default: 30).
+    :param level: Filter logs by level. If None, returns all levels.
+
+    :returns: Pipeline logs or error message.
+    """
+    try:
+        return await client.pipelines(workspace=workspace).get_logs(
+            pipeline_name=pipeline_name, limit=limit, level=level
+        )
+    except ResourceNotFoundError:
+        return f"There is no pipeline named '{pipeline_name}' in workspace '{workspace}'."
+    except BadRequestError as e:
+        return f"Failed to fetch logs for pipeline '{pipeline_name}': {e}"
+    except UnexpectedAPIError as e:
+        return f"Failed to fetch logs for pipeline '{pipeline_name}': {e}"
+
+
+async def deploy_pipeline(
+    *,
+    client: AsyncClientProtocol,
+    workspace: str,
+    pipeline_name: str,
+    wait_for_deployment: bool = False,
+    timeout_seconds: float = 600,
+    poll_interval: float = 10,
+) -> PipelineValidationResult | str:
+    """Deploys a pipeline to production.
+
+    This function attempts to deploy the specified pipeline in the given workspace.
+    If the deployment fails due to validation errors, it returns a validation result.
+
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :param pipeline_name: Name of the pipeline to deploy.
+    :param wait_for_deployment: If True, waits for the pipeline to reach DEPLOYED status.
+    :param timeout_seconds: Maximum time to wait for deployment when wait_for_deployment is True (default: 600.0).
+    :param poll_interval: Time between status checks in seconds when wait_for_deployment is True (default: 10.0).
+
+    :returns: Deployment validation result or error message.
+    """
+    try:
+        deployment_result = await client.pipelines(workspace=workspace).deploy(pipeline_name=pipeline_name)
+    except ResourceNotFoundError:
+        return f"There is no pipeline named '{pipeline_name}' in workspace '{workspace}'."
+    except BadRequestError as e:
+        return f"Failed to deploy pipeline '{pipeline_name}': {e}"
+    except UnexpectedAPIError as e:
+        return f"Failed to deploy pipeline '{pipeline_name}': {e}"
+
+    if not deployment_result.valid:
+        return deployment_result
+
+    # If not waiting for deployment, return success immediately
+    if not wait_for_deployment:
+        return deployment_result
+
+    start_time = asyncio.get_event_loop().time()
+
+    while True:
+        current_time = asyncio.get_event_loop().time()
+        if current_time - start_time > timeout_seconds:
+            return (
+                f"Pipeline '{pipeline_name}' deployment initiated successfully, but did not reach DEPLOYED status "
+                f"within {timeout_seconds} seconds. You can check the pipeline status manually."
+            )
+
+        try:
+            # Get the current pipeline status
+            pipeline = await client.pipelines(workspace=workspace).get(pipeline_name=pipeline_name, include_yaml=False)
+
+            if pipeline.status == "DEPLOYED":
+                return deployment_result  # Return the successful validation result
+            elif pipeline.status == "FAILED":
+                return f"Pipeline '{pipeline_name}' deployment failed. Current status: FAILED."
+
+            # Wait before next poll
+            await asyncio.sleep(poll_interval)
+
+        except Exception as e:
+            return f"Pipeline '{pipeline_name}' deployment initiated, but failed to check deployment status: {e}"
+
+
+async def search_pipeline(
+    *, client: AsyncClientProtocol, workspace: str, pipeline_name: str, query: str
+) -> DeepsetSearchResponse | str:
+    """Searches using a pipeline.
+
+    Uses the specified pipeline to perform a search with the given query.
+    Before executing the search, checks if the pipeline is deployed (status = DEPLOYED).
+    Returns search results.
+
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :param pipeline_name: Name of the pipeline to use for search.
+    :param query: The search query to execute.
+
+    :returns: Search results or error message.
+    """
+    try:
+        # First, check if the pipeline exists and get its status
+        pipeline = await client.pipelines(workspace=workspace).get(pipeline_name=pipeline_name)
+
+        # Check if pipeline is deployed
+        if pipeline.status != "DEPLOYED":
+            return (
+                f"Pipeline '{pipeline_name}' is not deployed (current status: {pipeline.status}). "
+                f"Please deploy the pipeline first using the deploy_pipeline tool before attempting to search."
+            )
+
+        # Execute the search
+        return await client.pipelines(workspace=workspace).search(pipeline_name=pipeline_name, query=query)
+
+    except ResourceNotFoundError:
+        return f"There is no pipeline named '{pipeline_name}' in workspace '{workspace}'."
+    except BadRequestError as e:
+        return f"Failed to search using pipeline '{pipeline_name}': {e}"
+    except UnexpectedAPIError as e:
+        return f"Failed to search using pipeline '{pipeline_name}': {e}"
+    except Exception as e:
+        return f"An unexpected error occurred while searching with pipeline '{pipeline_name}': {str(e)}"

deepset_mcp/tools/pipeline_template.py

@@ -0,0 +1,116 @@
+import numpy as np
+
+from deepset_mcp.api.exceptions import ResourceNotFoundError, UnexpectedAPIError
+from deepset_mcp.api.pipeline_template.models import (
+    PipelineTemplate,
+    PipelineTemplateList,
+    PipelineTemplateSearchResult,
+    PipelineTemplateSearchResults,
+)
+from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.tools.model_protocol import ModelProtocol
+
+
+async def list_pipeline_templates(
+    *,
+    client: AsyncClientProtocol,
+    workspace: str,
+    limit: int = 100,
+    field: str = "created_at",
+    order: str = "DESC",
+    filter: str | None = None,
+) -> PipelineTemplateList | str:
+    """Retrieves a list of all available pipeline templates.
+
+    :param client: The async client for API requests.
+    :param workspace: The workspace to list templates from.
+    :param limit: Maximum number of templates to return (default: 100).
+    :param field: Field to sort by (default: "created_at").
+    :param order: Sort order, either "ASC" or "DESC" (default: "DESC").
+    :param filter: OData filter expression to filter templates by criteria.
+
+    :returns: List of pipeline templates or error message.
+    """
+    try:
+        return await client.pipeline_templates(workspace=workspace).list_templates(
+            limit=limit, field=field, order=order, filter=filter
+        )
+    except ResourceNotFoundError:
+        return f"There is no workspace named '{workspace}'. Did you mean to configure it?"
+    except UnexpectedAPIError as e:
+        return f"Failed to list pipeline templates: {e}"
+
+
+async def get_pipeline_template(
+    *, client: AsyncClientProtocol, workspace: str, template_name: str
+) -> PipelineTemplate | str:
+    """Fetches detailed information for a specific pipeline template, identified by its `template_name`.
+
+    :param client: The async client for API requests.
+    :param workspace: The workspace to fetch template from.
+    :param template_name: The name of the template to fetch.
+
+    :returns: Pipeline template details or error message.
+    """
+    try:
+        return await client.pipeline_templates(workspace=workspace).get_template(template_name=template_name)
+    except ResourceNotFoundError:
+        return f"There is no pipeline template named '{template_name}' in workspace '{workspace}'."
+    except UnexpectedAPIError as e:
+        return f"Failed to fetch pipeline template '{template_name}': {e}"
+
+
+async def search_pipeline_templates(
+    *, client: AsyncClientProtocol, query: str, model: ModelProtocol, workspace: str, top_k: int = 10
+) -> PipelineTemplateSearchResults | str:
+    """Searches for pipeline templates based on name or description using semantic similarity.
+
+    :param client: The API client to use.
+    :param query: The search query.
+    :param model: The model to use for computing embeddings.
+    :param workspace: The workspace to search templates from.
+    :param top_k: Maximum number of results to return (default: 10).
+
+    :returns: Search results with similarity scores or error message.
+    """
+    try:
+        response = await client.pipeline_templates(workspace=workspace).list_templates(
+            filter="pipeline_type eq 'QUERY'"
+        )
+    except UnexpectedAPIError as e:
+        return f"Failed to retrieve pipeline templates: {e}"
+
+    if not response.data:
+        return PipelineTemplateSearchResults(results=[], query=query, total_found=0)
+
+    # Extract text for embedding from all templates
+    template_texts: list[tuple[str, str]] = [
+        (template.template_name, f"{template.template_name} {template.description}") for template in response.data
+    ]
+    template_names: list[str] = [t[0] for t in template_texts]
+
+    # Compute embeddings
+    query_embedding = model.encode(query)
+    template_embeddings = model.encode([text for _, text in template_texts])
+
+    query_embedding_reshaped = query_embedding.reshape(1, -1)
+
+    # Calculate dot product between target and all templates
+    # This gives us a similarity score for each template
+    similarities = np.dot(template_embeddings, query_embedding_reshaped.T).flatten()
+
+    # Create (template_name, similarity) pairs
+    template_similarities = list(zip(template_names, similarities, strict=False))
+
+    # Sort by similarity score in descending order
+    template_similarities.sort(key=lambda x: x[1], reverse=True)
+
+    top_templates = template_similarities[:top_k]
+    search_results = []
+    for template_name, sim in top_templates:
+        # Find the template object by name
+        template = next((t for t in response.data if t.template_name == template_name), None)
+        if template:
+            search_results.append(PipelineTemplateSearchResult(template=template, similarity_score=float(sim)))
+
+    return PipelineTemplateSearchResults(results=search_results, query=query, total_found=len(search_results))

deepset_mcp/tools/secrets.py

@@ -0,0 +1,45 @@
+from deepset_mcp.api.exceptions import ResourceNotFoundError, UnexpectedAPIError
+from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.secrets.models import Secret, SecretList
+
+
+async def list_secrets(*, client: AsyncClientProtocol, limit: int = 10) -> SecretList | str:
+    """Lists all secrets available in the user's deepset organization.
+
+    Use this tool to retrieve a list of secrets with their names and IDs.
+    This is useful for getting an overview of all secrets before retrieving specific ones.
+
+    :param client: The deepset API client
+    :param limit: Maximum number of secrets to return (default: 10)
+
+    :returns: List of secrets or error message
+    """
+    try:
+        return await client.secrets().list(limit=limit)
+    except ResourceNotFoundError as e:
+        return f"Error: {str(e)}"
+    except UnexpectedAPIError as e:
+        return f"API Error: {str(e)}"
+    except Exception as e:
+        return f"Unexpected error: {str(e)}"
+
+
+async def get_secret(*, client: AsyncClientProtocol, secret_id: str) -> Secret | str:
+    """Retrieves detailed information about a specific secret by its ID.
+
+    Use this tool to get information about a specific secret when you know its ID.
+    The secret value itself is not returned for security reasons, only metadata.
+
+    :param client: The deepset API client
+    :param secret_id: The unique identifier of the secret to retrieve
+
+    :returns: Secret information or error message
+    """
+    try:
+        return await client.secrets().get(secret_id=secret_id)
+    except ResourceNotFoundError as e:
+        return f"Error: {str(e)}"
+    except UnexpectedAPIError as e:
+        return f"API Error: {str(e)}"
+    except Exception as e:
+        return f"Unexpected error: {str(e)}"

deepset_mcp/tools/tokonomics/__init__.py

@@ -0,0 +1,73 @@
+"""
+Tokonomics: Explorable and Referenceable Tools for LLM Agents.
+
+=============================================================
+
+A library that provides token-efficient object exploration and reference
+passing capabilities for LLM agents.
+
+Key Features:
+- TTL-based object storage for temporary results
+- Rich object exploration with multiple rendering modes
+- Reference-based parameter passing (@obj_001.path.to.value)
+- Type-safe decorators that preserve function signatures
+- Configurable preview truncation and custom rendering callbacks
+
+Usage:
+------
+
+Basic explorable tool:
+
+    >>> from deepset_mcp.tools.tokonomics import explorable
+    >>>
+    >>> @explorable
+    >>> def get_data():
+    ...     return {"users": [{"name": "Alice", "age": 30}]}
+    >>>
+    >>> result = get_data()
+    >>> print(result)  # Shows rich preview
+    >>> result.obj_id  # "obj_001"
+    >>> result.value   # Original data
+
+Referenceable tool that accepts references:
+
+    >>> from deepset_mcp.tools.tokonomics import referenceable
+    >>>
+    >>> @referenceable
+    >>> def process_users(users: list) -> str:
+    ...     return f"Processed {len(users)} users"
+    >>>
+    >>> # Use with direct data
+    >>> process_users([{"name": "Bob"}])
+    >>>
+    >>> # Use with reference
+    >>> process_users("@obj_001.users")
+
+Exploration utilities:
+
+    >>> from deepset_mcp.tools.tokonomics import explore, search
+    >>>
+    >>> # Explore object structure
+    >>> explore("obj_001", mode="tree")
+    >>>
+    >>> # Search within objects
+    >>> search("obj_001", "Alice")
+"""
+
+from .decorators import explorable, explorable_and_referenceable, referenceable
+from .explorer import RichExplorer
+from .object_store import Explorable, ObjectRef, ObjectStore
+
+__all__ = [
+    # Core classes
+    "Explorable",
+    "ObjectRef",
+    "ObjectStore",
+    "RichExplorer",
+    # Decorators
+    "explorable",
+    "referenceable",
+    "explorable_and_referenceable",
+]
+
+__version__ = "0.1.0"