Metadata-Version: 2.4
Name: moorcheh-sdk
Version: 1.3.1
Summary: Python SDK for the Moorcheh Semantic Search API
Project-URL: Homepage, https://www.moorcheh.ai
Project-URL: Repository, https://github.com/moorcheh-ai/moorcheh-python-sdk
Author: Majid Fekri majid.fekri@edgeaiinnovations.com
License-Expression: MIT
License-File: LICENSE
Keywords: ai,moorcheh,sdk,semantic search,vector search
Requires-Python: <4,>=3.10
Requires-Dist: httpx<0.29,>=0.28.1
Description-Content-Type: text/markdown

# Moorcheh Python SDK

<a href="https://www.moorcheh.ai/">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/moorcheh-ai/moorcheh-python-sdk/main/assets/moorcheh-logo-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/moorcheh-ai/moorcheh-python-sdk/main/assets/moorcheh-logo-light.svg">
  <img alt="Fallback image description" src="https://raw.githubusercontent.com/moorcheh-ai/moorcheh-python-sdk/main/assets/moorcheh-logo-dark.svg">
</picture>
</a>

[![PyPI version](https://badge.fury.io/py/moorcheh-sdk.svg)](https://badge.fury.io/py/moorcheh-sdk) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/pypi/v/moorcheh-sdk.svg)](https://pypi.org/project/moorcheh-sdk/)
[![Downloads](https://static.pepy.tech/personalized-badge/moorcheh-sdk?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads)](https://pepy.tech/project/moorcheh-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:

```bash
pip install moorcheh-sdk
```

## Development

If you want to contribute or run the examples locally, clone the repository and install using uv:
```bash
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](https://moorcheh.ai) platform dashboard.

The recommended way is to set the MOORCHEH_API_KEY environment variable:

```bash
export MOORCHEH_API_KEY="YOUR_API_KEY_HERE"
```

## Quick Start
This example demonstrates the basic usage after installing the SDK.
```python
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:
```bash
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):
```bash
uv sync
```

Set your MOORCHEH_API_KEY environment variable.
Run examples using uv run:
```bash
uv run python examples/quickstart.py
```

Run tests using uv run:
```bash
uv run pytest tests/
```

## API Client Methods
The `MoorchehClient` class provides the following methods corresponding to the API v1 endpoints:
### Namespace Management:
```python
namespaces.create(namespace_name, type, vector_dimension=None)
```
```python
namespaces.list()
```
```python
namespaces.delete(namespace_name)
```
### Data Ingestion:
```python
documents.upload(namespace_name, documents) - For text namespaces (async processing).
```
```python
vectors.upload(namespace_name, vectors) - For vector namespaces (sync processing).
```
### Semantic Search
```python
similarity_search.query(namespaces, query, top_k=10, threshold=None, kiosk_mode=False) - Handles text or vector queries.
```
### Generative AI Response
```python
answer.generate(namespace, query, top_k=5, ...)
- Gets a context-aware answer from an LLM.
```

### Data Deletion:
```python
documents.delete(namespace_name, ids)
```
```python
vectors.delete(namespace_name, ids)
```
### Analysis (Planned):
```python
get_eigenvectors(namespace_name, n_eigenvectors=1) - Not yet implemented
```
```python
get_graph(namespace_name) - Not yet implemented
```
```python
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/](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.
