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

# Getting Started

> End-to-end Python client workflow: health, namespace, upload, poll, search

## Prerequisites

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

Confirm the server is running:

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

with MoorchehClient("http://localhost:8080") as client:
    health = client.health()
    assert health["status"] == "ok"
```

See [health](/on-prem/python-client/health) for quota fields.

## Full example — text namespace

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

with MoorchehClient("http://localhost:8080") as client:
    # 1. Check quota
    health = client.health()
    print(f"Items: {health['items']} / {health['max_items']}")

    # 2. Create a text namespace
    try:
        client.namespaces.create("docs", type="text")
    except MoorchehApiError as e:
        if e.status_code != 409:  # 409 = namespace already exists
            raise

    # 3. Upload documents (async job)
    resp = client.documents.upload("docs", documents=[
        {"id": "doc-1", "text": "Hello Moorcheh", "team": "ai"},
    ])

    # 4. Poll until upload completes
    job_id = resp["job_id"]
    while True:
        job = client.documents.upload_job_status("docs", job_id)
        if job["status"] == "completed":
            if job["failed"]:
                print("Upload errors:", job.get("last_error"))
            break
        time.sleep(0.5)

    # 5. Search (use #team:ai in query for metadata filter)
    hits = client.similarity_search.query(
        namespaces=["docs"],
        query="hello moorcheh #team:ai",
        top_k=5,
    )

    for r in hits["results"]:
        print(r["id"], r["score"], r["label"], r.get("text"))
```

## Vector namespace (optional)

```python theme={null}
with MoorchehClient("http://localhost:8080") as client:
    client.namespaces.create("embeddings", type="vector", vector_dimension=768)

    resp = client.vectors.upload("embeddings", vectors=[
        {"id": "vec-1", "vector": [0.1] * 768, "source": "demo"},
    ])

    # Poll upload job, then search with a vector query
    hits = client.similarity_search.query(
        namespaces=["embeddings"],
        query=[0.1] * 768,
        top_k=5,
    )
```

## CLI equivalent

```bash theme={null}
moorcheh status
moorcheh namespace-create --name docs --type text
moorcheh upload-documents --namespace-name docs --documents-file docs.json
moorcheh upload-job-status --namespace-name docs --job-id <job_id>
moorcheh search --query "hello moorcheh" --namespaces docs --top-k 5
```

## Method reference

| Step             | Python (resource style)                   | Docs                                                               |
| ---------------- | ----------------------------------------- | ------------------------------------------------------------------ |
| Health / quota   | `client.health()`                         | [health](/on-prem/python-client/health)                            |
| Create namespace | `client.namespaces.create(...)`           | [create](/on-prem/python-client/namespaces/create)                 |
| Upload documents | `client.documents.upload(...)`            | [upload](/on-prem/python-client/data/upload-documents)             |
| Poll upload      | `client.documents.upload_job_status(...)` | [upload job status](/on-prem/python-client/data/upload-job-status) |
| Upload file      | `client.files.upload(...)`                | [upload files](/on-prem/python-client/files/upload-files)          |
| Poll file job    | `client.files.job_status(...)`            | [file job status](/on-prem/python-client/files/file-job-status)    |
| Search           | `client.similarity_search.query(...)`     | [search](/on-prem/python-client/search/query)                      |

## Tips

<Warning>
  * Text upload and text search require a configured embedding provider (`moorcheh configure`)
  * Global item cap is **100,000** across all namespaces — check `health()` or handle **409** on upload
  * Document upload, file upload, and namespace delete are **async** — poll the job until `status` is `"completed"`
  * Item ids are unique **per namespace**, not globally
</Warning>

## Next steps

* [Python client overview](/on-prem/python-client/introduction) — all resources and error handling
* [Quickstart](/on-prem/quickstart) — CLI walkthrough
* [API reference](/on-prem/api-references/health) — full HTTP API docs