# Moorcheh Python SDK
[](https://www.moorcheh.ai/)
[](https://badge.fury.io/py/moorcheh-sdk) [](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/moorcheh-sdk/)
[](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 Poetry:
```bash
git clone https://github.com/moorcheh-ai/moorcheh-python-sdk.git
cd moorcheh-python-sdk
poetry install --with dev
```
## 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.
### Provide the Key:
The recommended way is to set the MOORCHEH_API_KEY environment variable:
Linux/macOS/Git Bash:
```bash
export MOORCHEH_API_KEY="YOUR_API_KEY_HERE"
```
Windows PowerShell:
```powershell
$env:MOORCHEH_API_KEY = "YOUR_API_KEY_HERE"
```
Windows CMD:
```bash
set MOORCHEH_API_KEY=YOUR_API_KEY_HERE
```
The client will automatically read this environment variable upon initialization.
Alternatively, you can pass the key directly to the constructor (MoorchehClient(api_key="...")), but using environment variables is generally preferred for security.
## Quick Start:
This example demonstrates the basic usage after installing the SDK.
```python
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("\nListing 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"\nUploading 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"\nSearching '{namespace_name}' for 'Moorcheh'...")
search_res = client.search(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.get_generative_answer(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.delete_documents(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.delete_namespace(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 Poetry (this includes development tools like pytest):
```bash
poetry install --with dev
```
Set your MOORCHEH_API_KEY environment variable.
Run examples using poetry run:
```bash
poetry run python examples/quickstart.py
```
Run tests using poetry run:
```bash
poetry run pytest tests/
```
## API Client Methods
The `MoorchehClient` class provides the following methods corresponding to the API v1 endpoints:
### Namespace Management:
```python
create_namespace(namespace_name, type, vector_dimension=None)
```
```python
list_namespaces()
```
```python
delete_namespace(namespace_name)
```
### Data Ingestion:
```python
upload_documents(namespace_name, documents) - For text namespaces (async processing).
```
```python
upload_vectors(namespace_name, vectors) - For vector namespaces (sync processing).
```
### Semantic Search
```python
search(namespaces, query, top_k=10, threshold=None, kiosk_mode=False) - Handles text or vector queries.
```
### Generative AI Response
```python
get_generative_answer(namespace, query, top_k=5, ...)
- Gets a context-aware answer from an LLM.
```
### Data Deletion:
```python
delete_documents(namespace_name, ids)
```
```python
delete_vectors(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://console.moorcheh.ai/docs](https://console.moorcheh.ai/docs)
## 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.
Raw data
{
"_id": null,
"home_page": "https://www.moorcheh.ai",
"name": "moorcheh-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "moorcheh, semantic search, vector search, ai, sdk",
"author": "Majid Fekri majid.fekri@edgeaiinnovations.com",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/39/07/15d18773d23e6b36abace0cd691e1b651e4e6982b1d3fc1b347018aed4e6/moorcheh_sdk-1.2.1.tar.gz",
"platform": null,
"description": "# Moorcheh Python SDK\n\n[](https://www.moorcheh.ai/)\n[](https://badge.fury.io/py/moorcheh-sdk) [](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/moorcheh-sdk/)\n[](https://pepy.tech/project/moorcheh-sdk)\n\n 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.\n\nThis SDK simplifies the process of creating namespaces, ingesting data (text or vectors), performing searches, and managing your resources via Python.\n\n## Features\n\n* **Namespace Management:** Create, list, and delete text or vector namespaces.\n* **Data Ingestion:** Upload text documents (with automatic embedding) or pre-computed vectors.\n* **Semantic Search:** Perform fast and accurate similarity searches using text or vector queries. Filter results using `top_k` and `threshold`.\n* **Gen-AI Response:** build an entire rag system in one shot.\n* **Data Deletion:** Remove specific documents or vectors from your namespaces by ID.\n* **Pythonic Interface:** Object-oriented client with clear methods and type hinting.\n* **Error Handling:** Custom exceptions for specific API errors (Authentication, Not Found, Invalid Input, etc.).\n\n## Installation\n\nInstall the SDK using pip:\n\n```bash\npip install moorcheh-sdk\n```\n\n## Development\n\nIf you want to contribute or run the examples locally, clone the repository and install using Poetry:\n```bash\ngit clone https://github.com/moorcheh-ai/moorcheh-python-sdk.git\ncd moorcheh-python-sdk\npoetry install --with dev\n```\n\n## Authentication\nThe 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. \n\n### Provide the Key: \nThe recommended way is to set the MOORCHEH_API_KEY environment variable:\n\nLinux/macOS/Git Bash:\n```bash\nexport MOORCHEH_API_KEY=\"YOUR_API_KEY_HERE\"\n```\nWindows PowerShell:\n```powershell\n$env:MOORCHEH_API_KEY = \"YOUR_API_KEY_HERE\"\n```\nWindows CMD:\n```bash\nset MOORCHEH_API_KEY=YOUR_API_KEY_HERE\n```\nThe client will automatically read this environment variable upon initialization.\n\nAlternatively, you can pass the key directly to the constructor (MoorchehClient(api_key=\"...\")), but using environment variables is generally preferred for security. \n\n## Quick Start:\nThis example demonstrates the basic usage after installing the SDK.\n```python\nimport os\nimport logging\nfrom moorcheh_sdk import MoorchehClient, MoorchehError, ConflictError\n\n# Configure basic logging to see SDK messages\nlogging.basicConfig(level=logging.INFO)\n\n# Ensure MOORCHEH_API_KEY is set as an environment variable\napi_key = os.environ.get(\"MOORCHEH_API_KEY\")\nif not api_key:\n print(\"Error: MOORCHEH_API_KEY environment variable not set.\")\n exit()\n\ntry:\n # Use the client as a context manager for automatic connection closing\n with MoorchehClient(api_key=api_key) as client:\n # 1. Create a namespace\n namespace_name = \"my-first-namespace\"\n print(f\"Attempting to create namespace: {namespace_name}\")\n try:\n client.create_namespace(namespace_name=namespace_name, type=\"text\")\n print(f\"Namespace '{namespace_name}' created.\")\n except ConflictError:\n print(f\"Namespace '{namespace_name}' already exists.\")\n except MoorchehError as e:\n print(f\"Error creating namespace: {e}\")\n exit()\n\n # 2. List namespaces\n print(\"\\nListing namespaces...\")\n ns_list = client.list_namespaces()\n print(\"Available namespaces:\")\n for ns in ns_list.get('namespaces', []):\n print(f\" - {ns.get('namespace_name')} (Type: {ns.get('type')})\")\n\n # 3. Upload a document\n print(f\"\\nUploading document to '{namespace_name}'...\")\n docs = [{\"id\": \"doc1\", \"text\": \"This is the first document about Moorcheh.\"}]\n upload_res = client.upload_documents(namespace_name=namespace_name, documents=docs)\n print(f\"Upload status: {upload_res.get('status')}\")\n\n # Add a small delay for processing before searching\n import time\n print(\"Waiting briefly for processing...\")\n time.sleep(2)\n\n # 4. Search the namespace\n print(f\"\\nSearching '{namespace_name}' for 'Moorcheh'...\")\n search_res = client.search(namespaces=[namespace_name], query=\"Moorcheh\", top_k=1)\n print(\"Search results:\")\n print(search_res)\n\n # 5. Get a Generative AI Answer\n print(f\"\\nGetting a GenAI answer from '{namespace_name}'...\")\n gen_ai_res = client.get_generative_answer(namespace=namespace_name, query=\"What is Moorcheh?\")\n print(\"Generative Answer:\")\n print(gen_ai_res)\n\n # 6. Delete the document\n print(f\"\\nDeleting document 'doc1' from '{namespace_name}'...\")\n delete_res = client.delete_documents(namespace_name=namespace_name, ids=[\"doc1\"])\n print(f\"Delete status: {delete_res.get('status')}\")\n\n # 7. Delete the namespace (optional cleanup)\n # print(f\"\\nDeleting namespace '{namespace_name}'...\")\n # client.delete_namespace(namespace_name)\n # print(\"Namespace deleted.\")\n\nexcept MoorchehError as e:\n print(f\"\\nAn SDK error occurred: {e}\")\nexcept Exception as e:\n print(f\"\\nAn unexpected error occurred: {e}\")\n```\n(Note: For more detailed examples covering vector operations, error handling, and logging configuration, please see the examples/ directory in the source repository.)\n\n## Development Setup\nIf you want to contribute, run tests, or run the example scripts directly from the source code:\n\nClone the repository:\n```bash\ngit clone https://github.com/moorcheh-ai/moorcheh-python-sdk.git\ncd moorcheh-python-sdk\n```\n\nInstall dependencies using Poetry (this includes development tools like pytest):\n```bash\npoetry install --with dev\n```\n\nSet your MOORCHEH_API_KEY environment variable.\nRun examples using poetry run:\n```bash\npoetry run python examples/quickstart.py\n```\n\nRun tests using poetry run:\n```bash\npoetry run pytest tests/\n```\n\n## API Client Methods\nThe `MoorchehClient` class provides the following methods corresponding to the API v1 endpoints:\n### Namespace Management:\n```python\ncreate_namespace(namespace_name, type, vector_dimension=None)\n```\n```python\nlist_namespaces()\n```\n```python\ndelete_namespace(namespace_name)\n```\n### Data Ingestion:\n```python\nupload_documents(namespace_name, documents) - For text namespaces (async processing).\n```\n```python\nupload_vectors(namespace_name, vectors) - For vector namespaces (sync processing).\n```\n### Semantic Search\n```python\nsearch(namespaces, query, top_k=10, threshold=None, kiosk_mode=False) - Handles text or vector queries.\n```\n### Generative AI Response\n```python\nget_generative_answer(namespace, query, top_k=5, ...) \n- Gets a context-aware answer from an LLM.\n```\n\n### Data Deletion:\n```python\ndelete_documents(namespace_name, ids)\n```\n```python\ndelete_vectors(namespace_name, ids)\n```\n### Analysis (Planned):\n```python\nget_eigenvectors(namespace_name, n_eigenvectors=1) - Not yet implemented\n```\n```python\nget_graph(namespace_name) - Not yet implemented\n```\n```python\nget_umap_image(namespace_name, n_dimensions=2) - Not yet implemented\n```\n(Refer to method docstrings or full documentation for detailed parameters and return types.)\n\n## Documentation\nFull API reference and further examples can be found at: [https://console.moorcheh.ai/docs](https://console.moorcheh.ai/docs)\n\n## Contributing\nContributions are welcome! Please refer to the contributing guidelines (CONTRIBUTING.md) for details on setting up the development environment, running tests, and submitting pull requests.\n\n## License\nThis project is licensed under the MIT License - See the LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for the Moorcheh Semantic Search API",
"version": "1.2.1",
"project_urls": {
"Homepage": "https://www.moorcheh.ai",
"Repository": "https://github.com/moorcheh-ai/moorcheh-python-sdk"
},
"split_keywords": [
"moorcheh",
" semantic search",
" vector search",
" ai",
" sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "60333cda9ad7f7ab803758fe2c7f46c4121417e2a68f5c787bf500906b1e999d",
"md5": "1899bec9d21ac683de033230171f7e15",
"sha256": "462b8e763b2dd1b8acac142dbb3d1d779c0bd384229b2dc53da71fe8c440c1e8"
},
"downloads": -1,
"filename": "moorcheh_sdk-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1899bec9d21ac683de033230171f7e15",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 16784,
"upload_time": "2025-09-06T18:06:46",
"upload_time_iso_8601": "2025-09-06T18:06:46.525955Z",
"url": "https://files.pythonhosted.org/packages/60/33/3cda9ad7f7ab803758fe2c7f46c4121417e2a68f5c787bf500906b1e999d/moorcheh_sdk-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "390715d18773d23e6b36abace0cd691e1b651e4e6982b1d3fc1b347018aed4e6",
"md5": "f4102cba07dc100fd3d7e82f5190a685",
"sha256": "e94972b2337c4872859393d462dc76ab6ae9cfe911c9b9af2c1aea8b6dddb44d"
},
"downloads": -1,
"filename": "moorcheh_sdk-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "f4102cba07dc100fd3d7e82f5190a685",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 16194,
"upload_time": "2025-09-06T18:06:47",
"upload_time_iso_8601": "2025-09-06T18:06:47.429506Z",
"url": "https://files.pythonhosted.org/packages/39/07/15d18773d23e6b36abace0cd691e1b651e4e6982b1d3fc1b347018aed4e6/moorcheh_sdk-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 18:06:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "moorcheh-ai",
"github_project": "moorcheh-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "moorcheh-sdk"
}
JSON
