Moorcheh Python SDK

PyPI VersionMIT LicensePython VersionDownloads

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

Features

Everything you need for semantic search

Moorcheh SDK simplifies working with vector similarity search and analysis

Namespace Management

Create, list, and delete text or vector namespaces with ease.

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.

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, etc.).

Installation

Quick and easy setup

Get started with the SDK in just a few steps

Install via package manager

Install the SDK using your preferred package manager.

pnpm add moorcheh-sdk

Development setup

For development or contribution, clone and install using Poetry.

# Clone the repository
git clone https://github.com/mjfekri/moorcheh-python-sdk.git
cd moorcheh-python-sdk

# Install dependencies with poetry
poetry install --with dev

Quick Start

Start using the SDK in minutes

This example demonstrates the basic usage after installing the SDK

Install via package manager

pnpm add moorcheh-sdk

Authentication

# Set the API key as an environment variable (recommended)
import os
os.environ["MOORCHEH_API_KEY"] = "YOUR_API_KEY_HERE"

# Or provide it directly to the constructor
from moorcheh_sdk import MoorchehClient
client = MoorchehClient(api_key="YOUR_API_KEY_HERE")

Creating Namespaces

# Create a text namespace (automatic embeddings)
client.create_namespace(namespace_name="my-text-namespace", type="text")

# Create a vector namespace (for pre-computed vectors)
client.create_namespace(
    namespace_name="my-vector-namespace", 
    type="vector",
    vector_dimension=384
)

Document Management

# Upload text documents
documents = [
    {"id": "doc1", "text": "This document is about artificial intelligence."},
    {"id": "doc2", "text": "Vector databases enable efficient similarity search."}
]
result = client.upload_documents(namespace_name="my-text-namespace", documents=documents)
print(result)  # {'status': 'success'}

# Search across namespaces with a text query
results = client.search(
    namespaces=["my-text-namespace"], 
    query="How do vector databases work?",
    top_k=3,  # Return top 3 results
    threshold=0.7  # Minimum similarity score
)
print(results)

Complete example

import os
import logging
from moorcheh_sdk import MoorchehClient, MoorchehError, ConflictError

# Configure basic logging to see SDK messages
logging.basicConfig(level=logging.INFO)

# Ensure MOORCHEH_API_KEY is set as an environment variable
api_key = os.environ.get("MOORCHEH_API_KEY")
if not api_key:
    print("Error: MOORCHEH_API_KEY environment variable not set.")
    exit()

try:
    # Use the client as a context manager for automatic connection closing
    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.create_namespace(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("
Listing namespaces...")
        ns_list = client.list_namespaces()
        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"
Uploading document to '{namespace_name}'...")
        docs = [{"id": "doc1", "text": "This is the first document about Moorcheh."}]
        upload_res = client.upload_documents(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"
Searching '{namespace_name}' for 'Moorcheh'...")
        search_res = client.search(namespaces=[namespace_name], query="Moorcheh", top_k=1)
        print("Search results:")
        print(search_res)

        # 5. Delete the document
        print(f"
Deleting document 'doc1' from '{namespace_name}'...")
        delete_res = client.delete_documents(namespace_name=namespace_name, ids=["doc1"])
        print(f"Delete status: {delete_res.get('status')}")

API Reference

Client Methods

The MoorchehClient class provides the following methods

Namespace Management

create_namespace

create_namespace(namespace_name, type, vector_dimension=None)

Create a new namespace for storing text or vectors

list_namespaces

list_namespaces()

List all namespaces in your account

delete_namespace

delete_namespace(namespace_name)

Delete a namespace and all its contents

Data Ingestion

upload_documents

upload_documents(namespace_name, documents)

Upload text documents for automatic embedding and indexing

upload_vectors

upload_vectors(namespace_name, vectors)

Upload pre-computed vectors directly

Semantic Search

search

search(namespaces, query, top_k=10, threshold=None, kiosk_mode=False)

Perform similarity search across specified namespaces

Data Deletion

delete_documents

delete_documents(namespace_name, ids)

Delete documents from a text namespace by their IDs

delete_vectors

delete_vectors(namespace_name, ids)

Delete vectors from a vector namespace by their IDs