moorcheh-sdk 1.3.0

Python SDK for the Moorcheh Semantic Search API

Moorcheh Python SDK

Python SDK for interacting with the Moorcheh Semantic Search API v1. Moorcheh provides ultra-fast, highly accurate vector similarity search and analysis capabilities based on information-theoretic principles.

This SDK simplifies the process of creating namespaces, ingesting data (text or vectors), performing searches, and managing your resources via Python.

Features

• Namespace Management: Create, list, and delete text or vector namespaces.
• Data Ingestion: Upload text documents (with automatic embedding) or pre-computed vectors.
• Semantic Search: Perform fast and accurate similarity searches using text or vector queries. Filter results using top_k and threshold.
• Gen-AI Response: build an entire rag system in one shot.
• Data Deletion: Remove specific documents or vectors from your namespaces by ID.
• Pythonic Interface: Object-oriented client with clear methods and type hinting.
• Error Handling: Custom exceptions for specific API errors (Authentication, Not Found, Invalid Input, etc.).

Installation

Install the SDK using pip:

pip install moorcheh-sdk

Development

If you want to contribute or run the examples locally, clone the repository and install using uv:

git clone https://github.com/moorcheh-ai/moorcheh-python-sdk.git

cd moorcheh-python-sdk

uv sync 

Authentication

The SDK requires a Moorcheh API key for authentication. Obtain an API Key: Sign up and generate an API key through the Moorcheh.ai platform dashboard.

The recommended way is to set the MOORCHEH_API_KEY environment variable:

export MOORCHEH_API_KEY="YOUR_API_KEY_HERE"

Quick Start

This example demonstrates the basic usage after installing the SDK.

import os
from moorcheh_sdk import MoorchehClient, MoorchehError, ConflictError

api_key = os.environ.get("MOORCHEH_API_KEY")

try:
    with MoorchehClient(api_key=api_key) as client:
        # 1. Create a namespace
        namespace_name = "my-first-namespace"
        print(f"Attempting to create namespace: {namespace_name}")
        try:
            client.namespaces.create(namespace_name=namespace_name, type="text")
            print(f"Namespace '{namespace_name}' created.")
        except ConflictError:
            print(f"Namespace '{namespace_name}' already exists.")
        except MoorchehError as e:
            print(f"Error creating namespace: {e}")
            exit()

        # 2. List namespaces
        print("\nListing namespaces...")
        ns_list = client.namespaces.list()
        print("Available namespaces:")
        for ns in ns_list.get('namespaces', []):
            print(f" - {ns.get('namespace_name')} (Type: {ns.get('type')})")

        # 3. Upload a document
        print(f"\nUploading document to '{namespace_name}'...")
        docs = [{"id": "doc1", "text": "This is the first document about Moorcheh."}]
        upload_res = client.documents.upload(namespace_name=namespace_name, documents=docs)
        print(f"Upload status: {upload_res.get('status')}")

        # Add a small delay for processing before searching
        import time
        print("Waiting briefly for processing...")
        time.sleep(2)

        # 4. Search the namespace
        print(f"\nSearching '{namespace_name}' for 'Moorcheh'...")
        search_res = client.similarity_search.query(namespaces=[namespace_name], query="Moorcheh", top_k=1)
        print("Search results:")
        print(search_res)

        # 5. Get a Generative AI Answer
        print(f"\nGetting a GenAI answer from '{namespace_name}'...")
        gen_ai_res = client.answer.generate(namespace=namespace_name, query="What is Moorcheh?")
        print("Generative Answer:")
        print(gen_ai_res)

        # 6. Delete the document
        print(f"\nDeleting document 'doc1' from '{namespace_name}'...")
        delete_res = client.documents.delete(namespace_name=namespace_name, ids=["doc1"])
        print(f"Delete status: {delete_res.get('status')}")

        # 7. Delete the namespace (optional cleanup)
        # print(f"\nDeleting namespace '{namespace_name}'...")
        # client.namespaces.delete(namespace_name)
        # print("Namespace deleted.")

except MoorchehError as e:
    print(f"\nAn SDK error occurred: {e}")
except Exception as e:
    print(f"\nAn unexpected error occurred: {e}")

(Note: For more detailed examples covering vector operations, error handling, and logging configuration, please see the examples/ directory in the source repository.)

Development Setup

If you want to contribute, run tests, or run the example scripts directly from the source code:

Clone the repository:

git clone https://github.com/moorcheh-ai/moorcheh-python-sdk.git
cd moorcheh-python-sdk

Install dependencies using uv (this includes development tools like pytest):

uv sync

Set your MOORCHEH_API_KEY environment variable. Run examples using uv run:

uv run python examples/quickstart.py

Run tests using uv run:

uv run pytest tests/

API Client Methods

The MoorchehClient class provides the following methods corresponding to the API v1 endpoints:

Namespace Management:

namespaces.create(namespace_name, type, vector_dimension=None)

namespaces.list()

namespaces.delete(namespace_name)

Data Ingestion:

documents.upload(namespace_name, documents) - For text namespaces (async processing).

vectors.upload(namespace_name, vectors) - For vector namespaces (sync processing).

Semantic Search

similarity_search.query(namespaces, query, top_k=10, threshold=None, kiosk_mode=False) - Handles text or vector queries.

Generative AI Response

answer.generate(namespace, query, top_k=5, ...)
- Gets a context-aware answer from an LLM.

Data Deletion:

documents.delete(namespace_name, ids)

vectors.delete(namespace_name, ids)

Analysis (Planned):

get_eigenvectors(namespace_name, n_eigenvectors=1) - Not yet implemented

get_graph(namespace_name) - Not yet implemented

get_umap_image(namespace_name, n_dimensions=2) - Not yet implemented

(Refer to method docstrings or full documentation for detailed parameters and return types.)

Documentation

Full API reference and further examples can be found at: https://docs.moorcheh.ai/

Contributing

Contributions are welcome! Please refer to the contributing guidelines (CONTRIBUTING.md) for details on setting up the development environment, running tests, and submitting pull requests.

License

This project is licensed under the MIT License - See the LICENSE file for details.