> ## 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.

# Python Client

> moorcheh-client package for Moorcheh on-prem

## Overview

The **moorcheh-client** package provides a Python client for calling the Moorcheh on-prem API, plus the `moorcheh` CLI for starting the runtime and running the same operations from the shell.

No API keys are required — the client talks directly to your local Moorcheh instance.

## Package

|        |                                                         |
| ------ | ------------------------------------------------------- |
| PyPI   | `moorcheh-client`                                       |
| Import | `from moorcheh import MoorchehClient, MoorchehApiError` |
| CLI    | `moorcheh` (installed with the same package)            |

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

## Start the server

```bash theme={null}
moorcheh up
```

Default API base URL: `http://localhost:8080`

## Client (recommended)

Use `MoorchehClient` with resource modules — same layout as the [cloud Python SDK](https://docs.moorcheh.ai/python-sdk/introduction):

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

with MoorchehClient("http://localhost:8080") as client:
    client.namespaces.create("my-docs", type="text")
    client.documents.upload("my-docs", documents=[{"id": "d1", "text": "..."}])
    client.documents.fetch_text_data("my-docs", limit=100)
    client.similarity_search.query(namespaces=["my-docs"], query="...")
    client.answer.generate(namespace="my-docs", query="...")
```

| Argument   | Default                 | Description                                   |
| ---------- | ----------------------- | --------------------------------------------- |
| `base_url` | `http://localhost:8080` | Moorcheh API URL (trailing slash is stripped) |
| `timeout`  | `30`                    | Request timeout in seconds                    |

## Resources

| Resource                   | Methods                                                           | Description                         |
| -------------------------- | ----------------------------------------------------------------- | ----------------------------------- |
| `client.health()`          | —                                                                 | Server status and global item quota |
| `client.namespaces`        | `create`, `list`, `delete`, `delete_job_status`                   | Namespace management                |
| `client.documents`         | `upload`, `get`, `delete`, `fetch_text_data`, `upload_job_status` | Text documents and chunks           |
| `client.vectors`           | `upload`, `delete`, `upload_job_status`                           | Precomputed vector data             |
| `client.files`             | `upload`, `list`, `get`, `delete`, `job_status`                   | Path-based file upload (on-prem)    |
| `client.similarity_search` | `query`                                                           | Semantic search                     |
| `client.answer`            | `generate`                                                        | RAG or direct LLM answers           |

## Legacy flat client

`MoorchehApiClient` remains available for backward compatibility:

```python theme={null}
from moorcheh import MoorchehApiClient

client = MoorchehApiClient("http://localhost:8080")
client.upload_namespace_documents("my-docs", {"documents": [...]})
```

All flat methods delegate to `MoorchehClient` resources internally.

## Errors

Non-2xx HTTP responses raise `MoorchehApiError` with:

* `status_code` — HTTP status (for example `400`, `404`, `409`)
* `body` — parsed JSON error body when available
* `is_item_limit_exceeded` — `True` for **409** quota errors on uploads

```python theme={null}
from moorcheh import MoorchehClient, MoorchehApiError

try:
    with MoorchehClient() as client:
        client.documents.upload("my-docs", documents=[...])
except MoorchehApiError as exc:
    if exc.is_item_limit_exceeded:
        print("Global item cap reached:", exc.body)
    else:
        print(f"Error ({exc.status_code}): {exc}")
```

## Next steps

* [Getting started](/on-prem/python-client/getting-started) — end-to-end workflow
* [Quickstart](/on-prem/quickstart) — CLI walkthrough
* [API reference](/on-prem/api-references/health) — full HTTP API docs