Skip to content

Docs/improve docs #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Neelpatel1604 merged 5 commits into from
Feb 13, 2026
Merged

Docs/improve docs #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1603194
docs: complete README overhaul
Xenogents Feb 11, 2026
234ad76
docs: move dev setup from readme to contributing
Xenogents Feb 11, 2026
3ac5935
docs: fix formatting issue with badges
Xenogents Feb 11, 2026
8d809f0
docs: add back required params to api methods
Xenogents Feb 13, 2026
912e596
docs: add llms.txt
Xenogents Feb 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,21 @@ This document provides guidelines for contributing to this project.
git clone https://github.com/YOUR_USERNAME/moorcheh-python-sdk.git
cd moorcheh-python-sdk
```
3. Set Up Environment: Follow the "Development Setup" instructions in the README.md file, which uses Poetry to create a virtual environment and install dependencies (including development tools).
3. Set Up Environment: Install dependencies using uv (this includes development tools like pytest).
```bash
poetry install --with dev
uv sync
```

4. Create a Branch: Create a new branch for your changes. Use a descriptive name (e.g., fix/issue-123, feat/add-graph-endpoint).
```bash
git checkout -b your-branch-name
```

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

# Making Changes
* **Code Style:** Please follow standard Python coding conventions (PEP 8). We recommend using tools like black for formatting and ruff or flake8 for linting (consider adding these to dev-dependencies in pyproject.toml if you haven't already).
* **Testing:**
Expand All @@ -28,7 +35,7 @@ git checkout -b your-branch-name
2. Integration Tests: Add or update tests for any bugs you fix to prevent regressions.
3. Ensure all tests pass before submitting a pull request. Run tests using:
```bash
poetry run pytest tests/
uv run pytest tests/
```
* **Documentation:** Update docstrings, examples, and the README.md as necessary to reflect your changes.
* **Commit Messages:** Write clear and concise commit messages explaining the "what" and "why" of your changes.
Expand Down
299 changes: 121 additions & 178 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,206 +1,149 @@
# 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:

<p align="center">
<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>
</p>

<div align="center">
<h1>The Information-Theoretic Search Engine for RAG & Agentic Memory</h1>
</div>

<p align="center">
<a href="https://moorcheh.ai/">Learn more</a>
·
<a href="https://www.youtube.com/@moorchehai/videos">Tutorials</a>
·
<a href="https://lnkd.in/gE_Pz_kb">Join Discord</a>
</p>

<p align="center">
<a href="https://lnkd.in/gE_Pz_kb"><img src="https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white" alt="Moorcheh Discord"></a>
<a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
<a href="https://pypi.org/project/moorcheh-sdk/"><img alt="Python Version" src="https://img.shields.io/pypi/v/moorcheh-sdk.svg?color=%2334D058"></a>
<a href="https://pepy.tech/project/moorcheh-sdk"><img alt="Downloads" src="https://static.pepy.tech/personalized-badge/moorcheh-sdk?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads"></a>
<a href="https://x.com/moorcheh_ai" target="_blank"><img src="https://img.shields.io/twitter/url/https/twitter.com/langchain.svg?style=social&label=Follow%20%40Moorcheh.ai" alt="Twitter / X"></a>
</p>

## Why Moorcheh?
- **32x Compression Ratio** over traditional Vector DBs
- **85% Reduced End-to-End Latency** over Pinecone vector search + Cohere reranker
- **0$ Storage Cost** true serverless architecture scaling to 0 when idle
- [Read the full paper](https://www.arxiv.org/abs/2601.11557)

[Moorcheh](https://moorcheh.ai/) is the universal memory layer for agentic AI, providing fast deterministic semantic search with zero‑ops scalability. Its MIB + ITS stack preserves relevance while reducing storage cost and decreasing latency, providing high‑accuracy semantic search without the overhead of managing clusters, making it ideal for production‑grade RAG, agentic memory, and semantic analytics.

## 🛠️ Key Capabilities

* **Bring any data:** Ingest raw text, files, or vectors with a unified API.
* **One-shot RAG:** Go from ingestion to grounded answers in a single flow.
* **Zero-ops scale:** Serverless architecture that scales up and down automatically.
* **Infrastructure as code:** Deploy into your cloud with native [IaC templates](https://moorcheh.ai/plans).
* **Agentic memory:** Stateful context for assistants and long-running agents.
* **Developer-ready:** Async support, type hints, and clear error handling.

## 🚀 Quickstart Guide

### Hosted Platform
Use our [hosted platform](https://console.moorcheh.ai) to get up and running fast with managed indexing, zero-ops scaling, and usage-based billing.

### Self-Hosted

1. 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
2. Sign up and generate an API key through the [Moorcheh](https://moorcheh.ai) platform dashboard.

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:
3. 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.
## Basic Usage
```python
import os
from moorcheh_sdk import MoorchehClient, MoorchehError, ConflictError
from moorcheh_sdk import MoorchehClient

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.)
with MoorchehClient(api_key=api_key) as client:
# Create a namespace
namespace_name = "my-first-namespace"
client.namespaces.create(namespace_name=namespace_name, type="text")

## Development Setup
If you want to contribute, run tests, or run the example scripts directly from the source code:
# Upload a document
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')}")

Clone the repository:
```bash
git clone https://github.com/moorcheh-ai/moorcheh-python-sdk.git
cd moorcheh-python-sdk
```
# Add a small delay for processing before searching
import time
print("Waiting briefly for processing...")
time.sleep(2)

Install dependencies using uv (this includes development tools like pytest):
```bash
uv sync
```
# Perform semantic search on the namespace
search_res = client.similarity_search.query(namespaces=[namespace_name], query="Moorcheh", top_k=1)
print("Search results:")
print(search_res)

Set your MOORCHEH_API_KEY environment variable.
Run examples using uv run:
```bash
uv run python examples/quickstart.py
# Get a Generative AI Answer
gen_ai_res = client.answer.generate(namespace=namespace_name, query="What is Moorcheh?")
print("Generative Answer:")
print(gen_ai_res)
```

Run tests using uv run:
```bash
uv run pytest tests/
```
For more detailed examples covering vector operations, error handling, and logging configuration, please see the [examples directory](https://github.com/moorcheh-ai/moorcheh-python-sdk/tree/main/examples).

## 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/)
The `MoorchehClient` and `AsyncMoorchehClient` classes provide the same method signatures. Below is a list of the available methods.

| Methods | Required Parameters | Description |
| ------------------------- | -------------------------------------- | -------------------------------------------------- |
| `namespaces.create` | namespace_name, type, vector_dimension | Create a text or vector namespace. |
| `namespaces.list` | N/A | List all available namespaces. |
| `namespaces.delete` | namespace_name | Delete a namespace by name. |
| `documents.upload` | namespace_name, documents | Upload text documents to a text namespace. |
| `documents.get` | namespace_name, ids | Retrieve documents by ID. |
| `documents.upload_file` | namespace_name, file_path | Upload a file for server-side ingestion. |
| `documents.delete` | namespace_name, ids | Delete documents by ID. |
| `documents.delete_files` | namespace_name, file_names | Delete uploaded files by filename. |
| `vectors.upload` | namespace_name, vectors=[{id, vector}] | Upload vectors to a vector namespace. |
| `vectors.delete` | namespace_name, ids | Delete vectors by ID. |
| `similarity_search.query` | namespaces, query | Run semantic search with text or vector queries. |
| `answer.generate` | namespaces, query | Generate a grounded answer from a namespace. |

For fully detailed method functionality, please see the [API Reference](https://docs.moorcheh.ai/api-reference/introduction).

## 🔗 Integrations
- **[LlamaIndex](https://developers.llamaindex.ai/python/framework/integrations/vector_stores/moorchehdemo)**: Use Moorcheh as a vector store inside LlamaIndex pipelines.
- **[LangChain](https://docs.langchain.com/oss/python/integrations/vectorstores/moorcheh)**: Plug Moorcheh into LangChain retrievers and RAG chains.
- **[n8n](https://n8n.io/integrations/moorcheh)**: Automate workflows that ingest, search, or answer with Moorcheh.
- **[MCP](https://github.com/moorcheh-ai/moorcheh-mcp)**: Connect Moorcheh to external tools via Model Context Protocol.


## Roadmap (Planned)

| Item | Required Parameters | Description |
| ------------------ | -------------------------------- | ----------------------------------------------------------------- |
| `get_eigenvectors` | namespace_name, n_eigenvectors | Expose top eigenvectors for semantic structure analysis. |
| `get_graph` | namespace_name | Provide a graph view of relationships across data in a namespace. |
| `get_umap_image` | namespace_name, n_dimensions | Generate a 2D UMAP projection image for quick visual exploration. |

## Documentation & Support
Have questions or feedback? We're here to help:
- Docs: [https://docs.moorcheh.ai](https://docs.moorcheh.ai)
- Discord: [Join our Discord server](https://lnkd.in/gE_Pz_kb)
- Appointment: [Book a Discovery Call](https://www.edgeaiinnovations.com/appointments)
- Email: support@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.
Contributions are welcome! Please refer to the contributing guidelines ([CONTRIBUTING.md](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.
Loading