moorcheh-client 0.1.0__tar.gz

moorcheh_client-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: moorcheh-client
+Version: 0.1.0
+Summary: Moorcheh client and runtime launcher for on-prem server containers.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Provides-Extra: web
+Requires-Dist: Flask>=3.0.0; extra == "web"
+
+# moorcheh-client (Python)
+
+This directory publishes the **`moorcheh-client`** distribution on PyPI. The importable module is still `moorcheh` (`from moorcheh import MoorchehApiClient`).
+
+## Install
+
+- `pip install moorcheh-client` (from this directory: `pip install .`)
+
+Default server image: `moorcheh/server:latest` (override with `moorcheh up --server-image …` or `MOORCHEH_SERVER_IMAGE` to pin a specific release).
+
+## Data directory
+
+`moorcheh up` stores your vectors and documents at:
+
+- `~/.moorcheh/data` (e.g. `C:\Users\<you>\.moorcheh\data` on Windows)
+- `moorcheh_data_store.json`, `namespace_registry.json`
+
+`moorcheh down` stops containers but **keeps** `~/.moorcheh`. Back up that folder to save everything.
+
+## CLI Commands
+
+- `moorcheh up` — start Moorcheh; uses host Ollama on `127.0.0.1:11434` when already running
+- `moorcheh down` — stop Moorcheh containers (does not stop host Ollama)
+- `moorcheh status` — `GET /health` (items, max_items, remaining)
+- `moorcheh namespace-create` — create a text or vector namespace
+- `moorcheh namespace-list` — list namespaces and per-namespace `item_count`
+- `moorcheh upload-documents` — `POST /namespaces/{namespace_name}/documents` (async job)
+- `moorcheh upload-vectors` — `POST /namespaces/{namespace_name}/vectors` (async job)
+- `moorcheh upload-job-status` — poll upload job (documents or vectors)
+- `moorcheh items-get` — get items by id within a namespace
+- `moorcheh items-delete` — delete items by id within a namespace
+- `moorcheh namespace-delete` — delete a namespace and all its items
+- `moorcheh search` — semantic search
+
+## Global item limit (100k)
+
+Moorcheh stores at most **100,000 items total** across all namespaces (text + vectors).
+
+- Check quota: `moorcheh status` → `items`, `max_items`, `remaining`
+- Uploads that would add **new** ids over the cap return **409** (entire batch rejected)
+- Re-uploading an existing id in the same namespace is an update and does not use extra quota
+- Deleting items or a namespace frees quota immediately
+
+Item ids are **unique per namespace** (the same id string may exist in different namespaces).
+
+## Examples
+
+```bash
+moorcheh up
+moorcheh status
+moorcheh namespace-create --name docs --type text
+moorcheh namespace-create --name products_vec --type vector --vector-dimension 768
+moorcheh upload-documents --namespace-name docs --documents-file docs-upload.json
+moorcheh upload-vectors --namespace-name products_vec --vectors-file vectors-upload.json
+moorcheh upload-job-status --namespace-name docs --job-id job-abc123
+moorcheh items-get --namespace-name docs --ids-json "[\"doc-1\"]"
+moorcheh items-delete --namespace-name docs --ids-json "[\"doc-1\"]"
+moorcheh search --query "on prem retrieval" --namespaces docs --top-k 5
+```
+
+Documents upload payload (`docs-upload.json`):
+
+```json
+{
+  "documents": [
+    {
+      "id": "doc-1",
+      "text": "Moorcheh on-prem retrieval test",
+      "team": "ai"
+    }
+  ]
+}
+```
+
+## Python API
+
+```python
+from moorcheh import MoorchehApiClient, MoorchehApiError
+
+client = MoorchehApiClient("http://localhost:8080")
+health = client.health()
+print(health["items"], health["remaining"])
+
+try:
+    client.upload_namespace_vectors("products_vec", {"vectors": [...]})
+except MoorchehApiError as e:
+    if e.is_item_limit_exceeded:
+        print(e.body)  # items, max_items, requested_new
+```
+
+## Optional Flask Demo App
+
+```bash
+pip install .[web]
+python client/app.py
+```
+
+## Ollama: host vs Docker
+
+By default, `moorcheh up` uses Ollama on `http://127.0.0.1:11434` when it is already running (typical on Windows/macOS). It does **not** start a second Ollama container in that case.
+
+```bash
+moorcheh up
+# Using Ollama already running at http://127.0.0.1:11434 (moorcheh-ollama container not started)
+```
+
+Force behavior:
+
+```bash
+moorcheh up --use-host-ollama    # never start moorcheh-ollama
+moorcheh up --bundled-ollama     # always start moorcheh-ollama container
+moorcheh up --bundled-ollama --ollama-port 11435   # bundled Ollama on another host port
+```
+
+## Port conflict fallback
+
+If **8080** is busy:
+
+```bash
+moorcheh up --server-port 8081
+moorcheh status --base-url http://localhost:8081
+```
+
+`moorcheh up` removes stale `moorcheh-onprem-server` (and `moorcheh-ollama` only when starting bundled Ollama). Data persists under `~/.moorcheh/data` across restarts.

moorcheh_client-0.1.0/README.md

@@ -0,0 +1,124 @@
+# moorcheh-client (Python)
+
+This directory publishes the **`moorcheh-client`** distribution on PyPI. The importable module is still `moorcheh` (`from moorcheh import MoorchehApiClient`).
+
+## Install
+
+- `pip install moorcheh-client` (from this directory: `pip install .`)
+
+Default server image: `moorcheh/server:latest` (override with `moorcheh up --server-image …` or `MOORCHEH_SERVER_IMAGE` to pin a specific release).
+
+## Data directory
+
+`moorcheh up` stores your vectors and documents at:
+
+- `~/.moorcheh/data` (e.g. `C:\Users\<you>\.moorcheh\data` on Windows)
+- `moorcheh_data_store.json`, `namespace_registry.json`
+
+`moorcheh down` stops containers but **keeps** `~/.moorcheh`. Back up that folder to save everything.
+
+## CLI Commands
+
+- `moorcheh up` — start Moorcheh; uses host Ollama on `127.0.0.1:11434` when already running
+- `moorcheh down` — stop Moorcheh containers (does not stop host Ollama)
+- `moorcheh status` — `GET /health` (items, max_items, remaining)
+- `moorcheh namespace-create` — create a text or vector namespace
+- `moorcheh namespace-list` — list namespaces and per-namespace `item_count`
+- `moorcheh upload-documents` — `POST /namespaces/{namespace_name}/documents` (async job)
+- `moorcheh upload-vectors` — `POST /namespaces/{namespace_name}/vectors` (async job)
+- `moorcheh upload-job-status` — poll upload job (documents or vectors)
+- `moorcheh items-get` — get items by id within a namespace
+- `moorcheh items-delete` — delete items by id within a namespace
+- `moorcheh namespace-delete` — delete a namespace and all its items
+- `moorcheh search` — semantic search
+
+## Global item limit (100k)
+
+Moorcheh stores at most **100,000 items total** across all namespaces (text + vectors).
+
+- Check quota: `moorcheh status` → `items`, `max_items`, `remaining`
+- Uploads that would add **new** ids over the cap return **409** (entire batch rejected)
+- Re-uploading an existing id in the same namespace is an update and does not use extra quota
+- Deleting items or a namespace frees quota immediately
+
+Item ids are **unique per namespace** (the same id string may exist in different namespaces).
+
+## Examples
+
+```bash
+moorcheh up
+moorcheh status
+moorcheh namespace-create --name docs --type text
+moorcheh namespace-create --name products_vec --type vector --vector-dimension 768
+moorcheh upload-documents --namespace-name docs --documents-file docs-upload.json
+moorcheh upload-vectors --namespace-name products_vec --vectors-file vectors-upload.json
+moorcheh upload-job-status --namespace-name docs --job-id job-abc123
+moorcheh items-get --namespace-name docs --ids-json "[\"doc-1\"]"
+moorcheh items-delete --namespace-name docs --ids-json "[\"doc-1\"]"
+moorcheh search --query "on prem retrieval" --namespaces docs --top-k 5
+```
+
+Documents upload payload (`docs-upload.json`):
+
+```json
+{
+  "documents": [
+    {
+      "id": "doc-1",
+      "text": "Moorcheh on-prem retrieval test",
+      "team": "ai"
+    }
+  ]
+}
+```
+
+## Python API
+
+```python
+from moorcheh import MoorchehApiClient, MoorchehApiError
+
+client = MoorchehApiClient("http://localhost:8080")
+health = client.health()
+print(health["items"], health["remaining"])
+
+try:
+    client.upload_namespace_vectors("products_vec", {"vectors": [...]})
+except MoorchehApiError as e:
+    if e.is_item_limit_exceeded:
+        print(e.body)  # items, max_items, requested_new
+```
+
+## Optional Flask Demo App
+
+```bash
+pip install .[web]
+python client/app.py
+```
+
+## Ollama: host vs Docker
+
+By default, `moorcheh up` uses Ollama on `http://127.0.0.1:11434` when it is already running (typical on Windows/macOS). It does **not** start a second Ollama container in that case.
+
+```bash
+moorcheh up
+# Using Ollama already running at http://127.0.0.1:11434 (moorcheh-ollama container not started)
+```
+
+Force behavior:
+
+```bash
+moorcheh up --use-host-ollama    # never start moorcheh-ollama
+moorcheh up --bundled-ollama     # always start moorcheh-ollama container
+moorcheh up --bundled-ollama --ollama-port 11435   # bundled Ollama on another host port
+```
+
+## Port conflict fallback
+
+If **8080** is busy:
+
+```bash
+moorcheh up --server-port 8081
+moorcheh status --base-url http://localhost:8081
+```
+
+`moorcheh up` removes stale `moorcheh-onprem-server` (and `moorcheh-ollama` only when starting bundled Ollama). Data persists under `~/.moorcheh/data` across restarts.

moorcheh_client-0.1.0/moorcheh/__init__.py

@@ -0,0 +1,6 @@
+"""Moorcheh Python client package."""
+
+from moorcheh.api import MoorchehApiClient, MoorchehApiError
+
+__all__ = ["MoorchehApiClient", "MoorchehApiError", "__version__"]
+__version__ = "0.1.0"

moorcheh_client-0.1.0/moorcheh/__main__.py

@@ -0,0 +1,4 @@
+from moorcheh.cli import main
+
+if __name__ == "__main__":
+    main()

moorcheh_client-0.1.0/moorcheh/api.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+
+
+class MoorchehApiError(Exception):
+    """HTTP error from the Moorcheh API (includes parsed JSON body when available)."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+    @property
+    def is_item_limit_exceeded(self) -> bool:
+        return self.status_code == 409 and bool(self.body)
+
+
+class MoorchehApiClient:
+    def __init__(self, base_url: str, timeout: int = 30) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _raise_for_status(self, response: requests.Response) -> None:
+        if response.ok:
+            return
+        body: dict[str, Any] | None = None
+        try:
+            parsed = response.json()
+            if isinstance(parsed, dict):
+                body = parsed
+        except requests.JSONDecodeError:
+            body = None
+        message = (
+            str(body.get("message"))
+            if body and body.get("message") is not None
+            else response.text or response.reason
+        )
+        raise MoorchehApiError(message, response.status_code, body)
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        response = requests.post(
+            f"{self.base_url}{path}",
+            json=payload,
+            timeout=self.timeout,
+        )
+        self._raise_for_status(response)
+        return response.json()
+
+    def _get(self, path: str) -> dict[str, Any]:
+        response = requests.get(f"{self.base_url}{path}", timeout=self.timeout)
+        self._raise_for_status(response)
+        return response.json()
+
+    def health(self) -> dict[str, Any]:
+        """
+        GET /health — includes global item quota:
+        items, max_items, remaining, model, status.
+        """
+        return self._get("/health")
+
+    def create_namespace(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._post("/namespaces", payload)
+
+    def list_namespaces(self) -> dict[str, Any]:
+        return self._get("/namespaces")
+
+    def delete_namespace(self, namespace_name: str) -> dict[str, Any]:
+        response = requests.delete(
+            f"{self.base_url}/namespaces/{namespace_name}",
+            timeout=self.timeout,
+        )
+        self._raise_for_status(response)
+        return response.json()
+
+    def delete_namespace_job_status(self, namespace_name: str, job_id: str) -> dict[str, Any]:
+        return self._get(f"/namespaces/{namespace_name}/delete-jobs/{job_id}")
+
+    def upload_namespace_documents(self, namespace_name: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST documents (async job). May raise MoorchehApiError with status 409 if global item cap exceeded."""
+        return self._post(f"/namespaces/{namespace_name}/documents", payload)
+
+    def upload_namespace_vectors(self, namespace_name: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST vectors (async job). May raise MoorchehApiError with status 409 if global item cap exceeded."""
+        return self._post(f"/namespaces/{namespace_name}/vectors", payload)
+
+    def get_namespace_items(self, namespace_name: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._post(f"/namespaces/{namespace_name}/items/get", payload)
+
+    def delete_namespace_items(self, namespace_name: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Delete by item id within namespace (ids are unique per namespace, not globally)."""
+        return self._post(f"/namespaces/{namespace_name}/items/delete", payload)
+
+    def upload_job_status(self, namespace_name: str, job_id: str) -> dict[str, Any]:
+        """Poll document or vector upload job status."""
+        return self._get(f"/namespaces/{namespace_name}/upload-jobs/{job_id}")
+
+    def upload_namespace_documents_job_status(self, namespace_name: str, job_id: str) -> dict[str, Any]:
+        return self.upload_job_status(namespace_name, job_id)
+
+    def search(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._post("/search", payload)

moorcheh_client-0.1.0/moorcheh/cli.py

@@ -0,0 +1,365 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from moorcheh.api import MoorchehApiClient, MoorchehApiError
+from moorcheh.docker_runtime import (
+    DEFAULT_OLLAMA_IMAGE,
+    DEFAULT_OLLAMA_MODEL,
+    DEFAULT_SERVER_IMAGE,
+    ComposeCommandError,
+    down,
+    up,
+)
+
+
+def _print_json(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, indent=2))
+
+
+def _parse_json(text: str, field_name: str) -> dict[str, Any]:
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{field_name} must be valid JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValueError(f"{field_name} must be a JSON object")
+    return data
+
+
+def _parse_json_array(text: str, field_name: str) -> list[Any]:
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{field_name} must be valid JSON: {exc}") from exc
+    if not isinstance(data, list):
+        raise ValueError(f"{field_name} must be a JSON array")
+    return data
+
+
+def _api_client(base_url: str) -> MoorchehApiClient:
+    return MoorchehApiClient(base_url=base_url)
+
+
+def cmd_up(args: argparse.Namespace) -> int:
+    bundled_ollama: bool | None
+    if args.bundled_ollama and args.use_host_ollama:
+        raise ValueError("Use only one of --bundled-ollama or --use-host-ollama")
+    if args.bundled_ollama:
+        bundled_ollama = True
+    elif args.use_host_ollama:
+        bundled_ollama = False
+    else:
+        bundled_ollama = None
+
+    result, started_bundled_ollama, data_dir = up(
+        server_image=args.server_image,
+        ollama_image=args.ollama_image,
+        server_port=args.server_port,
+        ollama_port=args.ollama_port,
+        ollama_model=args.ollama_model,
+        bundled_ollama=bundled_ollama,
+        ollama_host=args.ollama_host,
+    )
+    if result.stdout.strip():
+        print(result.stdout.strip())
+    if result.stderr.strip():
+        print(result.stderr.strip(), file=sys.stderr)
+    print(f"Data directory: {data_dir}")
+    if started_bundled_ollama:
+        print(
+            f"Started Moorcheh server + Ollama container (Ollama on host port {args.ollama_port})"
+        )
+    else:
+        print(
+            f"Using Ollama already running at http://{args.ollama_host}:{args.ollama_port} "
+            "(moorcheh-ollama container not started)"
+        )
+    print(f"Moorcheh API: http://localhost:{args.server_port}")
+    return 0
+
+
+def cmd_down(args: argparse.Namespace) -> int:
+    bundled_ollama: bool | None
+    if args.bundled_ollama and args.use_host_ollama:
+        raise ValueError("Use only one of --bundled-ollama or --use-host-ollama")
+    if args.bundled_ollama:
+        bundled_ollama = True
+    elif args.use_host_ollama:
+        bundled_ollama = False
+    else:
+        bundled_ollama = None
+
+    include_ollama: bool | None
+    if bundled_ollama is True:
+        include_ollama = True
+    elif bundled_ollama is False:
+        include_ollama = False
+    else:
+        include_ollama = None
+
+    result = down(include_ollama=include_ollama)
+    if result.stdout.strip():
+        print(result.stdout.strip())
+    if result.stderr.strip():
+        print(result.stderr.strip(), file=sys.stderr)
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    client = _api_client(args.base_url)
+    health = client.health()
+    items = health.get("items")
+    max_items = health.get("max_items")
+    remaining = health.get("remaining")
+    if items is not None and max_items is not None:
+        print(
+            f"items: {items} / {max_items}  |  remaining: {remaining}  |  model: {health.get('model')}"
+        )
+    _print_json(health)
+    return 0
+
+
+def cmd_namespace_create(args: argparse.Namespace) -> int:
+    client = _api_client(args.base_url)
+    payload: dict[str, Any] = {
+        "namespace_name": args.name,
+        "type": args.type,
+    }
+    if args.vector_dimension is not None:
+        payload["vector_dimension"] = args.vector_dimension
+    _print_json(client.create_namespace(payload))
+    return 0
+
+
+def cmd_namespace_list(args: argparse.Namespace) -> int:
+    client = _api_client(args.base_url)
+    _print_json(client.list_namespaces())
+    return 0
+
+
+def cmd_namespace_delete(args: argparse.Namespace) -> int:
+    client = _api_client(args.base_url)
+    _print_json(client.delete_namespace(args.namespace_name))
+    return 0
+
+
+def cmd_namespace_delete_job_status(args: argparse.Namespace) -> int:
+    client = _api_client(args.base_url)
+    _print_json(client.delete_namespace_job_status(args.namespace_name, args.job_id))
+    return 0
+
+
+def cmd_upload_documents(args: argparse.Namespace) -> int:
+    client = _api_client(args.base_url)
+    documents_path = Path(args.documents_file)
+    payload = json.loads(documents_path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("documents file must contain a JSON object with a 'documents' array")
+    _print_json(client.upload_namespace_documents(args.namespace_name, payload))
+    return 0
+
+
+def cmd_upload_vectors(args: argparse.Namespace) -> int:
+    client = _api_client(args.base_url)
+    vectors_path = Path(args.vectors_file)
+    payload = json.loads(vectors_path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("vectors file must contain a JSON object with a 'vectors' array")
+    _print_json(client.upload_namespace_vectors(args.namespace_name, payload))
+    return 0
+
+
+def cmd_upload_job_status(args: argparse.Namespace) -> int:
+    client = _api_client(args.base_url)
+    _print_json(client.upload_job_status(args.namespace_name, args.job_id))
+    return 0
+
+
+def cmd_items_get(args: argparse.Namespace) -> int:
+    client = _api_client(args.base_url)
+    ids = _parse_json_array(args.ids_json, "ids_json")
+    if any(not isinstance(item, str) for item in ids):
+        raise ValueError("ids_json must be an array of strings")
+    payload = {"ids": ids}
+    _print_json(client.get_namespace_items(args.namespace_name, payload))
+    return 0
+
+
+def cmd_items_delete(args: argparse.Namespace) -> int:
+    client = _api_client(args.base_url)
+    ids = _parse_json_array(args.ids_json, "ids_json")
+    if any(not isinstance(item, str) for item in ids):
+        raise ValueError("ids_json must be an array of strings")
+    payload = {"ids": ids}
+    _print_json(client.delete_namespace_items(args.namespace_name, payload))
+    return 0
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    metadata = _parse_json(args.metadata_json, "metadata_json")
+    client = _api_client(args.base_url)
+    query: Any
+    if args.query_vector_json is not None:
+        query = json.loads(args.query_vector_json)
+        if not isinstance(query, list):
+            raise ValueError("query_vector_json must be a JSON array")
+    else:
+        if not args.query:
+            raise ValueError("query is required when query_vector_json is not provided")
+        query = args.query
+    namespaces = [n.strip() for n in args.namespaces.split(",") if n.strip()]
+    payload: dict[str, Any] = {
+        "query": query,
+        "top_k": args.top_k,
+        "threshold": args.threshold,
+        "metadata": metadata,
+        "namespaces": namespaces,
+    }
+    _print_json(
+        client.search(payload)
+    )
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="moorcheh", description="Moorcheh on-prem client and runtime CLI.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_up = sub.add_parser("up", help="Start server + ollama containers.")
+    p_up.add_argument("--server-image", default=DEFAULT_SERVER_IMAGE)
+    p_up.add_argument("--ollama-image", default=DEFAULT_OLLAMA_IMAGE)
+    p_up.add_argument("--server-port", type=int, default=8080)
+    p_up.add_argument(
+        "--ollama-port",
+        type=int,
+        default=11434,
+        help="Host port to probe for existing Ollama, or to publish bundled Ollama on.",
+    )
+    p_up.add_argument(
+        "--ollama-host",
+        default="127.0.0.1",
+        help="Host to probe for existing Ollama (default: 127.0.0.1).",
+    )
+    p_up.add_argument(
+        "--bundled-ollama",
+        action="store_true",
+        help="Always start the moorcheh-ollama Docker container.",
+    )
+    p_up.add_argument(
+        "--use-host-ollama",
+        action="store_true",
+        help="Never start moorcheh-ollama; server uses Ollama on the host (port 11434).",
+    )
+    p_up.add_argument("--ollama-model", default=DEFAULT_OLLAMA_MODEL)
+    p_up.set_defaults(func=cmd_up)
+
+    p_down = sub.add_parser("down", help="Stop and remove runtime containers.")
+    p_down.add_argument("--bundled-ollama", action="store_true")
+    p_down.add_argument("--use-host-ollama", action="store_true")
+    p_down.set_defaults(func=cmd_down)
+
+    p_status = sub.add_parser("status", help="Check server health endpoint.")
+    p_status.add_argument("--base-url", default="http://localhost:8080")
+    p_status.set_defaults(func=cmd_status)
+
+    p_namespace_create = sub.add_parser("namespace-create", help="Create a namespace.")
+    p_namespace_create.add_argument("--base-url", default="http://localhost:8080")
+    p_namespace_create.add_argument("--name", required=True)
+    p_namespace_create.add_argument("--type", choices=["text", "vector"], required=True)
+    p_namespace_create.add_argument("--vector-dimension", type=int)
+    p_namespace_create.set_defaults(func=cmd_namespace_create)
+
+    p_namespace_list = sub.add_parser("namespace-list", help="List namespaces.")
+    p_namespace_list.add_argument("--base-url", default="http://localhost:8080")
+    p_namespace_list.set_defaults(func=cmd_namespace_list)
+
+    p_namespace_delete = sub.add_parser("namespace-delete", help="Call DELETE /namespaces/{namespace_name}.")
+    p_namespace_delete.add_argument("--base-url", default="http://localhost:8080")
+    p_namespace_delete.add_argument("--namespace-name", required=True)
+    p_namespace_delete.set_defaults(func=cmd_namespace_delete)
+
+    p_namespace_delete_job_status = sub.add_parser(
+        "namespace-delete-job-status",
+        help="Call GET /namespaces/{namespace_name}/delete-jobs/{job_id}.",
+    )
+    p_namespace_delete_job_status.add_argument("--base-url", default="http://localhost:8080")
+    p_namespace_delete_job_status.add_argument("--namespace-name", required=True)
+    p_namespace_delete_job_status.add_argument("--job-id", required=True)
+    p_namespace_delete_job_status.set_defaults(func=cmd_namespace_delete_job_status)
+
+    p_upload_documents = sub.add_parser("upload-documents", help="Call POST /namespaces/{namespace_name}/documents.")
+    p_upload_documents.add_argument("--base-url", default="http://localhost:8080")
+    p_upload_documents.add_argument("--namespace-name", required=True)
+    p_upload_documents.add_argument("--documents-file", required=True, help="Path to JSON body with {'documents': [...]} payload.")
+    p_upload_documents.set_defaults(func=cmd_upload_documents)
+
+    p_upload_vectors = sub.add_parser("upload-vectors", help="Call POST /namespaces/{namespace_name}/vectors.")
+    p_upload_vectors.add_argument("--base-url", default="http://localhost:8080")
+    p_upload_vectors.add_argument("--namespace-name", required=True)
+    p_upload_vectors.add_argument("--vectors-file", required=True, help="Path to JSON body with {'vectors': [...]} payload.")
+    p_upload_vectors.set_defaults(func=cmd_upload_vectors)
+
+    p_upload_job_status = sub.add_parser(
+        "upload-job-status",
+        help="Poll document or vector upload job (GET .../upload-jobs/{job_id}).",
+    )
+    p_upload_job_status.add_argument("--base-url", default="http://localhost:8080")
+    p_upload_job_status.add_argument("--namespace-name", required=True)
+    p_upload_job_status.add_argument("--job-id", required=True)
+    p_upload_job_status.set_defaults(func=cmd_upload_job_status)
+
+    p_items_get = sub.add_parser("items-get", help="Call POST /namespaces/{namespace_name}/items/get.")
+    p_items_get.add_argument("--base-url", default="http://localhost:8080")
+    p_items_get.add_argument("--namespace-name", required=True)
+    p_items_get.add_argument("--ids-json", required=True, help='JSON array string, e.g. ["id1","id2"].')
+    p_items_get.set_defaults(func=cmd_items_get)
+
+    p_items_delete = sub.add_parser("items-delete", help="Call POST /namespaces/{namespace_name}/items/delete.")
+    p_items_delete.add_argument("--base-url", default="http://localhost:8080")
+    p_items_delete.add_argument("--namespace-name", required=True)
+    p_items_delete.add_argument("--ids-json", required=True, help='JSON array string, e.g. ["id1","id2"].')
+    p_items_delete.set_defaults(func=cmd_items_delete)
+
+    p_search = sub.add_parser("search", help="Call /search endpoint.")
+    p_search.add_argument("--base-url", default="http://localhost:8080")
+    p_search.add_argument("--query", help="Text query.")
+    p_search.add_argument("--query-vector-json", help="JSON array string vector query.")
+    p_search.add_argument("--namespaces", default="", help="Comma-separated namespace list.")
+    p_search.add_argument("--top-k", type=int, default=5)
+    p_search.add_argument("--threshold", type=float, default=0.0)
+    p_search.add_argument("--metadata-json", default="{}")
+    p_search.set_defaults(func=cmd_search)
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        code = args.func(args)
+    except ComposeCommandError as exc:
+        if exc.stdout.strip():
+            print(exc.stdout.strip())
+        if exc.stderr.strip():
+            print(exc.stderr.strip(), file=sys.stderr)
+        print(f"Error: docker compose failed (exit {exc.returncode})", file=sys.stderr)
+        raise SystemExit(1) from exc
+    except MoorchehApiError as exc:
+        if exc.body:
+            _print_json(exc.body)
+        print(f"Error ({exc.status_code}): {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+    except Exception as exc:  # pragma: no cover - surfaced to CLI user
+        print(f"Error: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+    raise SystemExit(code)
+
+
+if __name__ == "__main__":
+    main()

moorcheh_client-0.1.0/moorcheh/compose/docker-compose.yml

@@ -0,0 +1,33 @@
+services:
+  ollama:
+    profiles: ["bundled-ollama"]
+    image: ${OLLAMA_IMAGE:-ollama/ollama:latest}
+    container_name: moorcheh-ollama
+    ports:
+      - "${OLLAMA_PORT:-11434}:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+
+  server:
+    image: ${MOORCHEH_SERVER_IMAGE:-moorcheh/server:latest}
+    container_name: moorcheh-onprem-server
+    depends_on:
+      ollama:
+        condition: service_started
+        required: false
+    ports:
+      - "${SERVER_PORT:-8080}:8080"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      SERVER_HOST: 0.0.0.0
+      SERVER_PORT: 8080
+      OLLAMA_URL: ${OLLAMA_URL:-http://ollama:11434}
+      OLLAMA_MODEL: ${OLLAMA_MODEL:-nomic-embed-text}
+      DATA_FILE: /app/data/moorcheh_data_store.json
+      NAMESPACE_REGISTRY_FILE: /app/data/namespace_registry.json
+    volumes:
+      - ${MOORCHEH_DATA_DIR}:/app/data
+
+volumes:
+  ollama_data:

moorcheh_client-0.1.0/moorcheh/docker_runtime.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import urllib.error
+import urllib.request
+from importlib import resources
+from pathlib import Path
+
+
+DEFAULT_SERVER_IMAGE = "moorcheh/server:latest"
+DEFAULT_OLLAMA_IMAGE = "ollama/ollama:latest"
+DEFAULT_OLLAMA_MODEL = "nomic-embed-text"
+DEFAULT_OLLAMA_HOST = "127.0.0.1"
+DEFAULT_OLLAMA_PORT = 11434
+HOST_OLLAMA_URL = "http://host.docker.internal:11434"
+
+# Must match container_name in compose/docker-compose.yml
+COMPOSE_CONTAINER_NAMES = ("moorcheh-ollama", "moorcheh-onprem-server")
+
+MOORCHEH_DATA_DIR_ENV = "MOORCHEH_DATA_DIR"
+
+
+def default_data_dir() -> Path:
+    """Per-user data directory: ~/.moorcheh/data (e.g. C:\\Users\\you\\.moorcheh\\data on Windows)."""
+    return Path.home() / ".moorcheh" / "data"
+
+
+def ensure_data_dir() -> Path:
+    """Create and return ~/.moorcheh/data for the current user."""
+    path = default_data_dir().resolve()
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def docker_bind_path(path: Path) -> str:
+    """Absolute host path for docker compose bind mounts (forward slashes on Windows)."""
+    return path.resolve().as_posix()
+
+
+class ComposeCommandError(RuntimeError):
+    """docker compose failed; includes captured stdout/stderr."""
+
+    def __init__(self, command: list[str], returncode: int, stdout: str, stderr: str) -> None:
+        self.command = command
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+        message = stderr.strip() or stdout.strip() or f"exit code {returncode}"
+        super().__init__(message)
+
+
+def compose_file_path() -> str:
+    return str(resources.files("moorcheh").joinpath("compose/docker-compose.yml"))
+
+
+def ollama_is_reachable(host: str = DEFAULT_OLLAMA_HOST, port: int = DEFAULT_OLLAMA_PORT, timeout: float = 2.0) -> bool:
+    """Return True if an Ollama HTTP server responds on host:port."""
+    url = f"http://{host}:{port}/"
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as response:
+            return 200 <= response.status < 300
+    except (urllib.error.URLError, TimeoutError, ValueError):
+        return False
+
+
+def should_use_bundled_ollama(
+    *,
+    bundled_ollama: bool | None,
+    ollama_host: str,
+    ollama_port: int,
+) -> bool:
+    """
+    bundled_ollama: True = always start container; False = always use host;
+    None = auto-detect (use host Ollama when already reachable).
+    """
+    if bundled_ollama is True:
+        return True
+    if bundled_ollama is False:
+        return False
+    return not ollama_is_reachable(ollama_host, ollama_port)
+
+
+def run_compose(command: list[str], env: dict[str, str] | None = None) -> subprocess.CompletedProcess[str]:
+    full_env = os.environ.copy()
+    if env:
+        full_env.update(env)
+
+    cmd = ["docker", "compose", "-f", compose_file_path(), *command]
+    result = subprocess.run(
+        cmd,
+        text=True,
+        capture_output=True,
+        env=full_env,
+    )
+    if result.returncode != 0:
+        raise ComposeCommandError(cmd, result.returncode, result.stdout, result.stderr)
+    return result
+
+
+def remove_stale_compose_containers(*, include_ollama: bool) -> None:
+    """Remove leftover containers that block fixed container_name in compose."""
+    names = list(COMPOSE_CONTAINER_NAMES) if include_ollama else ("moorcheh-onprem-server",)
+    for name in names:
+        subprocess.run(
+            ["docker", "rm", "-f", name],
+            capture_output=True,
+            text=True,
+        )
+
+
+def up(
+    server_image: str,
+    ollama_image: str,
+    server_port: int,
+    ollama_port: int,
+    ollama_model: str,
+    *,
+    bundled_ollama: bool | None = None,
+    ollama_host: str = DEFAULT_OLLAMA_HOST,
+) -> tuple[subprocess.CompletedProcess[str], bool, Path]:
+    """
+    Start the Moorcheh stack. Returns (compose result, whether bundled Ollama was started, data_dir).
+
+    When host Ollama is already running on ollama_host:ollama_port, only the server
+    container is started and OLLAMA_URL points at host.docker.internal:11434.
+    """
+    use_bundled = should_use_bundled_ollama(
+        bundled_ollama=bundled_ollama,
+        ollama_host=ollama_host,
+        ollama_port=ollama_port,
+    )
+    remove_stale_compose_containers(include_ollama=use_bundled)
+
+    resolved_data_dir = ensure_data_dir()
+    base_env = {
+        "MOORCHEH_SERVER_IMAGE": server_image,
+        "OLLAMA_IMAGE": ollama_image,
+        "SERVER_PORT": str(server_port),
+        "OLLAMA_MODEL": ollama_model,
+        MOORCHEH_DATA_DIR_ENV: docker_bind_path(resolved_data_dir),
+    }
+
+    if use_bundled:
+        result = run_compose(
+            ["--profile", "bundled-ollama", "up", "-d"],
+            env={
+                **base_env,
+                "OLLAMA_PORT": str(ollama_port),
+                "OLLAMA_URL": "http://ollama:11434",
+            },
+        )
+    else:
+        result = run_compose(
+            ["up", "-d", "server"],
+            env={
+                **base_env,
+                "OLLAMA_URL": HOST_OLLAMA_URL,
+            },
+        )
+    return result, use_bundled, resolved_data_dir
+
+
+def down(*, include_ollama: bool | None = None) -> subprocess.CompletedProcess[str]:
+    """
+    Stop compose services. When include_ollama is False, only stops the server
+    (leaves a bundled ollama container running if it was started separately).
+    None = stop all services defined in the compose file (including profile services
+    that were started).
+    """
+    env = {MOORCHEH_DATA_DIR_ENV: docker_bind_path(ensure_data_dir())}
+    if include_ollama is False:
+        return run_compose(["stop", "server"], env=env)
+    return run_compose(["--profile", "bundled-ollama", "down"], env=env)

moorcheh_client-0.1.0/moorcheh_client.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: moorcheh-client
+Version: 0.1.0
+Summary: Moorcheh client and runtime launcher for on-prem server containers.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Provides-Extra: web
+Requires-Dist: Flask>=3.0.0; extra == "web"
+
+# moorcheh-client (Python)
+
+This directory publishes the **`moorcheh-client`** distribution on PyPI. The importable module is still `moorcheh` (`from moorcheh import MoorchehApiClient`).
+
+## Install
+
+- `pip install moorcheh-client` (from this directory: `pip install .`)
+
+Default server image: `moorcheh/server:latest` (override with `moorcheh up --server-image …` or `MOORCHEH_SERVER_IMAGE` to pin a specific release).
+
+## Data directory
+
+`moorcheh up` stores your vectors and documents at:
+
+- `~/.moorcheh/data` (e.g. `C:\Users\<you>\.moorcheh\data` on Windows)
+- `moorcheh_data_store.json`, `namespace_registry.json`
+
+`moorcheh down` stops containers but **keeps** `~/.moorcheh`. Back up that folder to save everything.
+
+## CLI Commands
+
+- `moorcheh up` — start Moorcheh; uses host Ollama on `127.0.0.1:11434` when already running
+- `moorcheh down` — stop Moorcheh containers (does not stop host Ollama)
+- `moorcheh status` — `GET /health` (items, max_items, remaining)
+- `moorcheh namespace-create` — create a text or vector namespace
+- `moorcheh namespace-list` — list namespaces and per-namespace `item_count`
+- `moorcheh upload-documents` — `POST /namespaces/{namespace_name}/documents` (async job)
+- `moorcheh upload-vectors` — `POST /namespaces/{namespace_name}/vectors` (async job)
+- `moorcheh upload-job-status` — poll upload job (documents or vectors)
+- `moorcheh items-get` — get items by id within a namespace
+- `moorcheh items-delete` — delete items by id within a namespace
+- `moorcheh namespace-delete` — delete a namespace and all its items
+- `moorcheh search` — semantic search
+
+## Global item limit (100k)
+
+Moorcheh stores at most **100,000 items total** across all namespaces (text + vectors).
+
+- Check quota: `moorcheh status` → `items`, `max_items`, `remaining`
+- Uploads that would add **new** ids over the cap return **409** (entire batch rejected)
+- Re-uploading an existing id in the same namespace is an update and does not use extra quota
+- Deleting items or a namespace frees quota immediately
+
+Item ids are **unique per namespace** (the same id string may exist in different namespaces).
+
+## Examples
+
+```bash
+moorcheh up
+moorcheh status
+moorcheh namespace-create --name docs --type text
+moorcheh namespace-create --name products_vec --type vector --vector-dimension 768
+moorcheh upload-documents --namespace-name docs --documents-file docs-upload.json
+moorcheh upload-vectors --namespace-name products_vec --vectors-file vectors-upload.json
+moorcheh upload-job-status --namespace-name docs --job-id job-abc123
+moorcheh items-get --namespace-name docs --ids-json "[\"doc-1\"]"
+moorcheh items-delete --namespace-name docs --ids-json "[\"doc-1\"]"
+moorcheh search --query "on prem retrieval" --namespaces docs --top-k 5
+```
+
+Documents upload payload (`docs-upload.json`):
+
+```json
+{
+  "documents": [
+    {
+      "id": "doc-1",
+      "text": "Moorcheh on-prem retrieval test",
+      "team": "ai"
+    }
+  ]
+}
+```
+
+## Python API
+
+```python
+from moorcheh import MoorchehApiClient, MoorchehApiError
+
+client = MoorchehApiClient("http://localhost:8080")
+health = client.health()
+print(health["items"], health["remaining"])
+
+try:
+    client.upload_namespace_vectors("products_vec", {"vectors": [...]})
+except MoorchehApiError as e:
+    if e.is_item_limit_exceeded:
+        print(e.body)  # items, max_items, requested_new
+```
+
+## Optional Flask Demo App
+
+```bash
+pip install .[web]
+python client/app.py
+```
+
+## Ollama: host vs Docker
+
+By default, `moorcheh up` uses Ollama on `http://127.0.0.1:11434` when it is already running (typical on Windows/macOS). It does **not** start a second Ollama container in that case.
+
+```bash
+moorcheh up
+# Using Ollama already running at http://127.0.0.1:11434 (moorcheh-ollama container not started)
+```
+
+Force behavior:
+
+```bash
+moorcheh up --use-host-ollama    # never start moorcheh-ollama
+moorcheh up --bundled-ollama     # always start moorcheh-ollama container
+moorcheh up --bundled-ollama --ollama-port 11435   # bundled Ollama on another host port
+```
+
+## Port conflict fallback
+
+If **8080** is busy:
+
+```bash
+moorcheh up --server-port 8081
+moorcheh status --base-url http://localhost:8081
+```
+
+`moorcheh up` removes stale `moorcheh-onprem-server` (and `moorcheh-ollama` only when starting bundled Ollama). Data persists under `~/.moorcheh/data` across restarts.

moorcheh_client-0.1.0/moorcheh_client.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+moorcheh/__init__.py
+moorcheh/__main__.py
+moorcheh/api.py
+moorcheh/cli.py
+moorcheh/docker_runtime.py
+moorcheh/compose/docker-compose.yml
+moorcheh_client.egg-info/PKG-INFO
+moorcheh_client.egg-info/SOURCES.txt
+moorcheh_client.egg-info/dependency_links.txt
+moorcheh_client.egg-info/entry_points.txt
+moorcheh_client.egg-info/requires.txt
+moorcheh_client.egg-info/top_level.txt

moorcheh_client-0.1.0/moorcheh_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

moorcheh_client-0.1.0/moorcheh_client.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+moorcheh = moorcheh.cli:main

moorcheh_client-0.1.0/moorcheh_client.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests>=2.31.0
+
+[web]
+Flask>=3.0.0

moorcheh_client-0.1.0/moorcheh_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+moorcheh

moorcheh_client-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "moorcheh-client"
+version = "0.1.0"
+description = "Moorcheh client and runtime launcher for on-prem server containers."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "requests>=2.31.0",
+]
+
+[project.optional-dependencies]
+web = [
+  "Flask>=3.0.0",
+]
+
+[project.scripts]
+moorcheh = "moorcheh.cli:main"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["moorcheh*"]
+
+[tool.setuptools.package-data]
+moorcheh = ["compose/docker-compose.yml"]

moorcheh_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+