deepset-mcp 0.0.6__py3-none-any.whl → 0.0.8__py3-none-any.whl

deepset_mcp/tools/indexes.py

@@ -2,24 +2,53 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import yaml
+from pydantic import BaseModel
+
 from deepset_mcp.api.exceptions import BadRequestError, ResourceNotFoundError, UnexpectedAPIError
-from deepset_mcp.api.indexes.models import Index, IndexList
-from deepset_mcp.api.pipeline import PipelineValidationResult
+from deepset_mcp.api.indexes.models import Index
+from deepset_mcp.api.pipeline.models import PipelineValidationResult
 from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.shared_models import PaginatedResponse
+
+
+class IndexValidationResultWithYaml(BaseModel):
+    """Model for index validation result that includes the original YAML."""
+
+    validation_result: PipelineValidationResult
+    "Result of validating the index configuration"
+    yaml_config: str
+    "Original YAML configuration that was validated"
+
+
+class IndexOperationWithErrors(BaseModel):
+    """Model for index operations that complete with validation errors."""
 
+    message: str
+    "Descriptive message about the index operation"
+    validation_result: PipelineValidationResult
+    "Validation errors encountered during the operation"
+    index: Index
+    "Index object after the operation completed"
 
-async def list_indexes(*, client: AsyncClientProtocol, workspace: str) -> IndexList | str:
-    """Use this to list available indexes on the deepset platform in your workspace.
 
-    :param client: Deepset API client to use for requesting indexes.
-    :param workspace: Workspace of which to list indexes.
+async def list_indexes(
+    *, client: AsyncClientProtocol, workspace: str, after: str | None = None
+) -> PaginatedResponse[Index] | str:
+    """Retrieves a list of all indexes available within the currently configured deepset workspace.
+
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :param after: The cursor to fetch the next page of results.
+        If there are more results to fetch, the cursor will appear as `next_cursor` on the response.
+    :returns: List of indexes or error message.
     """
     try:
-        result = await client.indexes(workspace=workspace).list()
-    except ResourceNotFoundError as e:
-        return f"Error listing indexes. Error: {e.message} ({e.status_code})"
-
-    return result
+        return await client.indexes(workspace=workspace).list(after=after)
+    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 indexes: {e}"
 
 
 async def get_index(*, client: AsyncClientProtocol, workspace: str, index_name: str) -> Index | str:
@@ -37,6 +66,33 @@ async def get_index(*, client: AsyncClientProtocol, workspace: str, index_name:
     return response
 
 
+async def validate_index(
+    *, client: AsyncClientProtocol, workspace: str, yaml_configuration: str
+) -> IndexValidationResultWithYaml | str:
+    """Validates the provided index 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.indexes(workspace=workspace).validate(yaml_configuration)
+        return IndexValidationResultWithYaml(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 index: {e}"
+
+
 async def create_index(
     *,
     client: AsyncClientProtocol,
@@ -55,7 +111,7 @@ async def create_index(
     """
     try:
         result = await client.indexes(workspace=workspace).create(
-            name=index_name, yaml_config=yaml_configuration, description=description
+            index_name=index_name, yaml_config=yaml_configuration, description=description
         )
     except ResourceNotFoundError:
         return f"There is no workspace named '{workspace}'. Did you mean to configure it?"
@@ -72,35 +128,78 @@ async def update_index(
     client: AsyncClientProtocol,
     workspace: str,
     index_name: str,
-    updated_index_name: str | None = None,
-    yaml_configuration: str | None = None,
-) -> dict[str, str | Index] | str:
-    """Updates an existing index in your deepset platform workspace.
+    original_config_snippet: str,
+    replacement_config_snippet: str,
+    skip_validation_errors: bool = True,
+) -> Index | IndexOperationWithErrors | str:
+    """
+    Updates an index configuration in the specified workspace with a replacement configuration snippet.
 
-    This function can update either the name or the configuration of an existing index, or both.
-    At least one of updated_index_name or yaml_configuration must be provided.
+    This function validates the replacement configuration snippet before applying it to the index.
+    If the validation fails and skip_validation_errors is False, it returns error messages.
+    Otherwise, the replacement snippet is used to update the index's configuration.
 
-    :param client: Deepset API client to use.
-    :param workspace: Workspace in which to update the index.
-    :param index_name: Unique name of the index to update.
-    :param updated_index_name: Updated name of the index.
-    :param yaml_configuration: YAML configuration to update the index with.
+    :param client: The async client for API communication.
+    :param workspace: The workspace name.
+    :param index_name: Name of the index 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 index even if validation fails.
+                                  If False, stops update when validation fails.
+    :returns: Updated index or error message.
     """
-    if not updated_index_name and not yaml_configuration:
-        return "You must provide either a new name or a new configuration to update the index."
-
     try:
-        result = await client.indexes(workspace=workspace).update(
-            index_name=index_name, updated_index_name=updated_index_name, yaml_config=yaml_configuration
+        original_index = await client.indexes(workspace=workspace).get(index_name=index_name)
+    except ResourceNotFoundError:
+        return f"There is no index named '{index_name}'. Did you mean to create it?"
+    except (BadRequestError, UnexpectedAPIError) as e:
+        return f"Failed to fetch index '{index_name}': {e}"
+
+    if original_index.yaml_config is None:
+        return f"The index '{index_name}' does not have a YAML configuration."
+
+    occurrences = original_index.yaml_config.count(original_config_snippet)
+
+    if occurrences == 0:
+        return f"No occurrences of the provided configuration snippet were found in the index '{index_name}'."
+
+    if occurrences > 1:
+        return (
+            f"Multiple occurrences ({occurrences}) of the provided configuration snippet were found in the index "
+            f"'{index_name}'. Specify a more precise snippet to proceed with the update."
         )
+
+    updated_yaml_configuration = original_index.yaml_config.replace(
+        original_config_snippet, replacement_config_snippet, 1
+    )
+
+    try:
+        validation_response = await client.indexes(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 "Index validation failed:\n" + "\n".join(error_messages)
+
+        await client.indexes(workspace=workspace).update(index_name=index_name, yaml_config=updated_yaml_configuration)
+
+        # Get the full index after update
+        index = await client.indexes(workspace=workspace).get(index_name)
+
+        # If validation failed but we proceeded anyway, return the special model
+        if not validation_response.valid:
+            return IndexOperationWithErrors(
+                message="The operation completed with errors", validation_result=validation_response, index=index
+            )
+
+        # Otherwise return just the index
+        return index
+
     except ResourceNotFoundError:
         return f"There is no index named '{index_name}'. Did you mean to create it?"
     except BadRequestError as e:
-        return f"Failed to update index '{index_name}': {e}"
+        return f"Failed to update the index '{index_name}': {e}"
     except UnexpectedAPIError as e:
-        return f"Failed to update index '{index_name}': {e}"
-
-    return {"message": f"Index '{index_name}' updated successfully.", "index": result}
+        return f"Failed to update the index '{index_name}': {e}"
 
 
 async def deploy_index(

deepset_mcp/tools/object_store.py

@@ -5,7 +5,7 @@
 from collections.abc import Callable
 from typing import Any
 
-from deepset_mcp.tools.tokonomics import RichExplorer
+from deepset_mcp.tokonomics import RichExplorer
 
 
 def create_get_from_object_store(explorer: RichExplorer) -> Callable[..., Any]:

deepset_mcp/tools/pipeline.py

@@ -5,30 +5,33 @@
 import asyncio
 
 import yaml
+from pydantic import BaseModel
 
 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,
+    LogLevel,
+    PipelineLog,
     PipelineValidationResult,
-    PipelineValidationResultWithYaml,
 )
 from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.shared_models import PaginatedResponse
 
 
-async def list_pipelines(*, client: AsyncClientProtocol, workspace: str) -> PipelineList | str:
+async def list_pipelines(
+    *, client: AsyncClientProtocol, workspace: str, after: str | None = None
+) -> PaginatedResponse[DeepsetPipeline] | 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.
+    :param after: The cursor to fetch the next page of results.
+        If there are more results to fetch, the cursor will appear as `next_cursor` on the response.
     :returns: List of pipelines or error message.
     """
     try:
-        return await client.pipelines(workspace=workspace).list()
+        return await client.pipelines(workspace=workspace).list(after=after)
     except ResourceNotFoundError:
         return f"There is no workspace named '{workspace}'. Did you mean to configure it?"
     except (BadRequestError, UnexpectedAPIError) as e:
@@ -51,6 +54,15 @@ async def get_pipeline(*, client: AsyncClientProtocol, workspace: str, pipeline_
         return f"Failed to fetch pipeline '{pipeline_name}': {e}"
 
 
+class PipelineValidationResultWithYaml(BaseModel):
+    """Model for pipeline validation result that includes the original YAML."""
+
+    validation_result: PipelineValidationResult
+    "Result of validating the pipeline configuration"
+    yaml_config: str
+    "Original YAML configuration that was validated"
+
+
 async def validate_pipeline(
     *, client: AsyncClientProtocol, workspace: str, yaml_configuration: str
 ) -> PipelineValidationResultWithYaml | str:
@@ -78,6 +90,17 @@ async def validate_pipeline(
         return f"Failed to validate pipeline: {e}"
 
 
+class PipelineOperationWithErrors(BaseModel):
+    """Model for pipeline operations that complete with validation errors."""
+
+    message: str
+    "Descriptive message about the pipeline operation"
+    validation_result: PipelineValidationResult
+    "Validation errors encountered during the operation"
+    pipeline: DeepsetPipeline
+    "Pipeline object after the operation completed"
+
+
 async def create_pipeline(
     *,
     client: AsyncClientProtocol,
@@ -207,8 +230,14 @@ async def update_pipeline(
 
 
 async def get_pipeline_logs(
-    *, client: AsyncClientProtocol, workspace: str, pipeline_name: str, limit: int = 30, level: LogLevel | None = None
-) -> PipelineLogList | str:
+    *,
+    client: AsyncClientProtocol,
+    workspace: str,
+    pipeline_name: str,
+    limit: int = 30,
+    level: LogLevel | None = None,
+    after: str | None = None,
+) -> PaginatedResponse[PipelineLog] | str:
     """Fetches logs for a specific pipeline.
 
     Retrieves log entries for the specified pipeline, with optional filtering by log level.
@@ -219,12 +248,13 @@ async def get_pipeline_logs(
     :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.
+    :param after: The cursor to fetch the next page of results.
 
     :returns: Pipeline logs or error message.
     """
     try:
         return await client.pipelines(workspace=workspace).get_logs(
-            pipeline_name=pipeline_name, limit=limit, level=level
+            pipeline_name=pipeline_name, limit=limit, level=level, after=after
         )
     except ResourceNotFoundError:
         return f"There is no pipeline named '{pipeline_name}' in workspace '{workspace}'."

deepset_mcp/tools/pipeline_template.py

@@ -3,16 +3,15 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import numpy as np
+from pydantic import BaseModel
 
 from deepset_mcp.api.exceptions import ResourceNotFoundError, UnexpectedAPIError
 from deepset_mcp.api.pipeline_template.models import (
     PipelineTemplate,
-    PipelineTemplateList,
-    PipelineTemplateSearchResult,
-    PipelineTemplateSearchResults,
     PipelineType,
 )
 from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.shared_models import PaginatedResponse
 from deepset_mcp.tools.model_protocol import ModelProtocol
 
 
@@ -21,27 +20,22 @@ async def list_templates(
     client: AsyncClientProtocol,
     workspace: str,
     limit: int = 100,
-    field: str = "created_at",
-    order: str = "DESC",
     pipeline_type: PipelineType | str | None = None,
-) -> PipelineTemplateList | str:
+    # after: str | None = None TODO
+) -> PaginatedResponse[PipelineTemplate] | str:
     """Retrieves a list of all available pipeline and indexing 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 pipeline_type: The type of pipeline to return.
 
     :returns: List of pipeline templates or error message.
     """
     try:
-        return await client.pipeline_templates(workspace=workspace).list_templates(
+        return await client.pipeline_templates(workspace=workspace).list(
             limit=limit,
-            field=field,
-            order=order,
-            filter=f"pipeline_type eq '{pipeline_type}'" if pipeline_type else None,
+            filter=f"pipeline_type eq '{pipeline_type}'" if pipeline_type else None,  # TODO: after=after
         )
     except ResourceNotFoundError:
         return f"There is no workspace named '{workspace}'. Did you mean to configure it?"
@@ -66,6 +60,26 @@ async def get_template(*, client: AsyncClientProtocol, workspace: str, template_
         return f"Failed to fetch pipeline template '{template_name}': {e}"
 
 
+class PipelineTemplateSearchResult(BaseModel):
+    """Model representing a search result for pipeline templates."""
+
+    template: PipelineTemplate
+    "Pipeline template that matched the search criteria"
+    similarity_score: float
+    "Relevance score indicating how well the template matches the search"
+
+
+class PipelineTemplateSearchResults(BaseModel):
+    """Response model for pipeline template search results."""
+
+    results: list[PipelineTemplateSearchResult]
+    "List of pipeline templates matching the search criteria"
+    query: str
+    "Original search query string"
+    total_found: int
+    "Total number of templates found matching the search criteria"
+
+
 async def search_templates(
     *,
     client: AsyncClientProtocol,
@@ -87,18 +101,21 @@ async def search_templates(
     :returns: Search results with similarity scores or error message.
     """
     try:
-        response = await client.pipeline_templates(workspace=workspace).list_templates(
-            filter=f"pipeline_type eq '{pipeline_type}'"
-        )
+        response = await client.pipeline_templates(workspace=workspace).list()
+        templates = response.data
+
+        # Filter by pipeline_type if specified
+        if pipeline_type:
+            templates = [t for t in templates if t.pipeline_type == pipeline_type]
     except UnexpectedAPIError as e:
         return f"Failed to retrieve pipeline templates: {e}"
 
-    if not response.data:
+    if not templates:
         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.template_name, f"{template.template_name} {template.description}") for template in templates
     ]
     template_names: list[str] = [t[0] for t in template_texts]
 
@@ -122,7 +139,7 @@ async def search_templates(
     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)
+        template = next((t for t in templates if t.template_name == template_name), None)
         if template:
             search_results.append(PipelineTemplateSearchResult(template=template, similarity_score=float(sim)))
 

deepset_mcp/tools/secrets.py

@@ -13,19 +13,29 @@ class EnvironmentSecret(BaseModel):
     """Model representing a secret or an integration."""
 
     name: str
+    "Human-readable name of the secret or integration"
     id: str
+    "Unique identifier for the secret or integration"
     invalid: bool | None = None
+    "Whether the secret or integration is invalid (None for secrets)"
 
 
 class EnvironmentSecretList(BaseModel):
     """Model representing a list of secrets and integrations."""
 
     data: list[EnvironmentSecret]
+    "List of secrets and integrations for the current page"
     has_more: bool
+    "Whether there are more items available beyond this page"
     total: int
+    "Total number of secrets and integrations"
+    next_cursor: str | None = None
+    "Cursor for fetching the next page of results"
 
 
-async def list_secrets(*, client: AsyncClientProtocol, limit: int = 10) -> EnvironmentSecretList | str:
+async def list_secrets(
+    *, client: AsyncClientProtocol, limit: int = 10, after: str | None = None
+) -> EnvironmentSecretList | 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.
@@ -33,29 +43,35 @@ async def list_secrets(*, client: AsyncClientProtocol, limit: int = 10) -> Envir
 
     :param client: The deepset API client
     :param limit: Maximum number of secrets to return (default: 10)
+    :param after: The cursor to fetch the next page of results
 
     :returns: List of secrets or error message
     """
     try:
-        secrets_list = await client.secrets().list(limit=limit)
-        integrations_list = await client.integrations().list()
+        secrets_list = await client.secrets().list(limit=limit, after=after)
 
         env_secrets = [EnvironmentSecret(name=secret.name, id=secret.secret_id) for secret in secrets_list.data]
-        for integration in integrations_list.integrations:
-            env_vars = TOKEN_DOMAIN_MAPPING.get(integration.provider_domain, [])
-            for env_var in env_vars:
-                env_secrets.append(
-                    EnvironmentSecret(
-                        name=env_var,
-                        id=str(integration.model_registry_token_id),
-                        invalid=integration.invalid,
+
+        # Only fetch integrations if no cursor is provided (first page)
+        # This optimizes performance by skipping the integrations call for subsequent pages
+        if after is None:
+            integrations_list = await client.integrations().list()
+            for integration in integrations_list:
+                env_vars = TOKEN_DOMAIN_MAPPING.get(integration.provider_domain, [])
+                for env_var in env_vars:
+                    env_secrets.append(
+                        EnvironmentSecret(
+                            name=env_var,
+                            id=str(integration.model_registry_token_id),
+                            invalid=integration.invalid,
+                        )
                     )
-                )
 
         return EnvironmentSecretList(
             data=env_secrets,
             has_more=secrets_list.has_more,
             total=len(env_secrets),
+            next_cursor=secrets_list.next_cursor,
         )
     except ResourceNotFoundError as e:
         return f"Error: {str(e)}"
@@ -82,7 +98,7 @@ async def get_secret(*, client: AsyncClientProtocol, secret_id: str) -> Environm
     except ResourceNotFoundError:
         try:
             integrations_list = await client.integrations().list()
-            for integration in integrations_list.integrations:
+            for integration in integrations_list:
                 if str(integration.model_registry_token_id) == secret_id:
                     env_vars = TOKEN_DOMAIN_MAPPING.get(integration.provider_domain, [])
                     if env_vars:

deepset_mcp/tools/workspace.py

@@ -7,10 +7,10 @@
 from deepset_mcp.api.exceptions import BadRequestError, ResourceNotFoundError, UnexpectedAPIError
 from deepset_mcp.api.protocols import AsyncClientProtocol
 from deepset_mcp.api.shared_models import NoContentResponse
-from deepset_mcp.api.workspace.models import Workspace, WorkspaceList
+from deepset_mcp.api.workspace.models import Workspace
 
 
-async def list_workspaces(*, client: AsyncClientProtocol) -> WorkspaceList | str:
+async def list_workspaces(*, client: AsyncClientProtocol) -> list[Workspace] | str:
     """Retrieves a list of all workspaces available to the user.
 
     This tool provides an overview of all workspaces that the user has access to.

deepset_mcp-0.0.8.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: deepset-mcp
+Version: 0.0.8
+Summary: Collection of MCP tools and Agents to work with the deepset AI platform. Create, debug or learn about pipelines on the platform. Useable from the CLI, Cursor, Claude Code, or other MCP clients.
+Project-URL: Homepage, https://deepset.ai
+Author-email: Mathis Lucka <mathis.lucka@deepset.ai>, Tanay Soni <tanay.soni@deepset.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: Agents,Haystack,LLM,MCP,deepset,pipelines
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Freely Distributable
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: fastapi
+Requires-Dist: glom
+Requires-Dist: httpx
+Requires-Dist: mcp>=1.10.1
+Requires-Dist: model2vec
+Requires-Dist: numpy
+Requires-Dist: orjson
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt[crypto]
+Requires-Dist: pyyaml
+Requires-Dist: rich
+Requires-Dist: typer
+Provides-Extra: redis
+Requires-Dist: redis>=4.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# deepset-mcp
+
+**The official MCP server and Python SDK for the deepset AI platform**
+
+deepset-mcp enables AI agents to build and debug pipelines on the [deepset AI platform](https://www.deepset.ai/products-and-services/deepset-ai-platform) through 30+ specialized tools. It also provides a Python SDK for programmatic access to many platform resources.
+
+## Documentation
+
+📖 **[View the full documentation](https://deepset-ai.github.io/deepset-mcp-server/)**
+
+## Quick Links
+
+- 🔗 **[deepset AI Platform](https://www.deepset.ai/products-and-services/deepset-ai-platform)**
+- 📚 **[Installation Guide](https://deepset-ai.github.io/deepset-mcp-server/installation/)**
+- 🛠️ **[MCP Server Guide](https://deepset-ai.github.io/deepset-mcp-server/guides/mcp_server/)**
+- 🐍 **[Python SDK Guide](https://deepset-ai.github.io/deepset-mcp-server/guides/api_sdk/)**
+
+## Development
+
+### Installation
+
+Install the project using [uv](https://docs.astral.sh/uv/):
+
+```bash
+# Install uv first
+pipx install uv
+
+# Install project with all dependencies
+uv sync --locked --all-extras --all-groups
+```
+
+### Code Quality & Testing
+
+Run code quality checks and tests using the Makefile:
+
+```bash
+# Install dependencies
+make install
+
+# Code quality
+make lint          # Run ruff linting
+make format        # Format code with ruff
+make types         # Run mypy type checking
+
+# Testing
+make test          # Run unit tests (default)
+make test-unit     # Run unit tests only
+make test-integration     # Run integration tests
+make test-all      # Run all tests
+
+# Clean up
+make clean         # Remove cache files
+```
+
+### Documentation
+
+Documentation is built using [MkDocs](https://www.mkdocs.org/) with the Material theme:
+
+- Configuration: `mkdocs.yml`
+- Content: `docs/` directory
+- Auto-generated API docs via [mkdocstrings](https://mkdocstrings.github.io/)
+- Deployed via GitHub Pages (automated via GitHub Actions on push to main branch)
+