> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Getting started with the Moorcheh Python SDK

## Welcome to Moorcheh Python SDK

The Moorcheh Python SDK provides a simple and intuitive interface to integrate Moorcheh's powerful semantic search and generative AI capabilities into your Python applications. With full API coverage, automatic authentication handling, and robust error management, the SDK makes it easy to build intelligent applications.

## Installation

Install the SDK using pip:

```bash theme={null}
pip install moorcheh-sdk
```

## Quick Start

### Authentication

Get your API key from [console.moorcheh.ai/api-keys](https://console.moorcheh.ai/api-keys).

Set your API key as an environment variable:

```bash theme={null}
export MOORCHEH_API_KEY="your_api_key_here"
```

Or pass it directly to the client (not recommended for production):

```python theme={null}
from moorcheh_sdk import MoorchehClient

with MoorchehClient(api_key="your-api-key-here") as client:
    # Your code here
    pass
```

### Basic Example

Here's a complete example showing how to create a namespace, upload documents, search, and generate an answer:

```python theme={null}
import time
from moorcheh_sdk import MoorchehClient

# Use the context manager for automatic cleanup
with MoorchehClient() as client:
    namespace = "sdk-quickstart-ns"
    
    # 1. Create a text namespace
    print(f"Creating namespace: {namespace}")
    client.namespaces.create(namespace_name=namespace, type="text")

    # 2. Upload documents
    docs = [
        {"id": "qs-doc-1", "text": "Moorcheh is a semantic search engine designed for speed and accuracy."},
        {"id": "qs-doc-2", "text": "The Python SDK allows developers to easily integrate Moorcheh's features."}
    ]
    print("Uploading documents...")
    client.documents.upload(namespace_name=namespace, documents=docs)
    
    # Wait briefly for indexing (asynchronous process)
    time.sleep(5)

    # 3. Perform a semantic search
    print("Searching...")
    search_results = client.similarity_search.query(
        namespaces=[namespace], 
        query="What is the SDK?"
    )
    for result in search_results.get('results', []):
        print(f"Found: {result['text']} (Score: {result['score']})")

    # 4. Generate an AI answer
    print("Generating answer...")
    gen_ai_response = client.answer.generate(
        namespace=namespace,
        query="In one sentence, what is the purpose of the Python SDK?"
    )
    print(f"AI Answer: {gen_ai_response['answer']}")

    # 5. Clean up
    print("Deleting namespace...")
    client.namespaces.delete(namespace)
```

<Warning>
  If you are using Moorcheh v1.2.2 or earlier, you can check the [legacy MoorchehClient](/python-sdk/legacy-client).
</Warning>

## Key Features

<CardGroup cols={2}>
  <Card title="Full API Coverage" icon="webhook">
    Manage namespaces, ingest data, perform searches, and generate AI answers.
  </Card>

  <Card title="Simplified Authentication" icon="key">
    Automatic handling of API keys via environment variables.
  </Card>

  <Card title="Robust Error Handling" icon="shield-check">
    Custom exceptions for specific API errors, allowing for graceful failure and recovery.
  </Card>

  <Card title="Context Management" icon="code">
    The client is designed to be used as a context manager (with statement) for efficient handling of network resources.
  </Card>
</CardGroup>

## SDK Structure

The SDK is organized into logical modules that mirror the API structure:

<CardGroup cols={2}>
  <Card title="Namespace Management" icon="folder" href="/python-sdk/namespaces/create">
    Create, list, and delete namespaces
  </Card>

  <Card title="Data Operations" icon="database" href="/python-sdk/data/upload-text">
    Upload and manage text or vector data
  </Card>

  <Card title="File storage" icon="file" href="/python-sdk/files/upload-file">
    Upload, list, and delete raw file objects in document storage
  </Card>

  <Card title="Search & Discovery" icon="magnifying-glass" href="/python-sdk/search/query">
    Perform semantic search across namespaces
  </Card>

  <Card title="AI Generation" icon="sparkles" href="/python-sdk/ai/generate">
    Generate AI-powered answers from your data
  </Card>
</CardGroup>

## Basic Workflow

<Steps>
  <Step title="Initialize Client">
    Create a MoorchehClient instance, preferably using a context manager
  </Step>

  <Step title="Create a Namespace">
    Create a namespace to organize your data (text or vector type)
  </Step>

  <Step title="Upload Data">
    Upload text documents or vector embeddings to your namespace
  </Step>

  <Step title="Search">
    Perform semantic search to retrieve relevant data
  </Step>

  <Step title="Generate Answers">
    Use AI models to generate contextual answers from your data
  </Step>
</Steps>

## Client Initialization

The MoorchehClient is the main entry point to the SDK. Learn more about [client initialization and configuration](/python-sdk/client).

## Next Steps

* [Client Initialization](/python-sdk/client) - Learn how to configure the MoorchehClient
* [Namespace Management](/python-sdk/namespaces/create) - Create and manage namespaces
* [Data Management](/python-sdk/data/upload-text) - Upload and manage your data
* [File storage](/python-sdk/files/upload-file) - Upload, list, and delete files in document storage
* [Search & AI](/python-sdk/search/query) - Perform searches and get AI answers
* [Best Practices](/python-sdk/best-practices) - Learn best practices and error handling