deyta-cli 0.1.0__py3-none-any.whl

deyta_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

deyta_cli/cli.py

@@ -0,0 +1,65 @@
+"""Deyta CLI — unified entry point for Deyta's services.
+
+Command altitudes:
+  - platform/runtime (top-level, never service-prefixed): init, serve, status, stop,
+    up, down, login, logout, context.
+  - data plane (flat in MVP): namespace/ns, memory, plus ingest/query shorthands.
+
+The CLI is a thin HTTP client; all Khora work happens in the `deyta serve` daemon.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .commands import auth, context, db, init, memory, namespace, serve, update, version
+from .commands import aliases
+
+app = typer.Typer(
+    help="Deyta — unified CLI for Deyta's services (memory powered by Khora).",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    host: str = typer.Option(
+        None,
+        "--host",
+        help="Target server URL. Overrides DEYTA_HOST and the active context.",
+        envvar="DEYTA_HOST",
+    ),
+) -> None:
+    """Resolve the target host once and stash it for every command."""
+    ctx.obj = {"host": host}
+
+
+# ---- platform / runtime ---------------------------------------------------- #
+app.command("init")(init.init)
+app.command("serve")(serve.serve)
+app.command("status")(serve.status)
+app.command("stop")(serve.stop)
+app.command("up")(serve.up)
+app.command("down")(serve.down)
+app.command("login")(auth.login)
+app.command("logout")(auth.logout)
+app.command("version")(version.version)
+app.command("update")(update.update)
+app.add_typer(context.app, name="context")
+
+# ---- datastores (Docker) --------------------------------------------------- #
+app.add_typer(db.app, name="db")
+
+# ---- data plane ------------------------------------------------------------ #
+app.add_typer(namespace.app, name="namespace")
+app.add_typer(namespace.app, name="ns")  # alias
+app.add_typer(memory.app, name="memory")
+
+# ---- top-level shorthands -------------------------------------------------- #
+app.command("ingest")(aliases.ingest)
+app.command("query")(aliases.query)
+
+
+if __name__ == "__main__":
+    app()

deyta_cli/client.py

@@ -0,0 +1,108 @@
+"""Thin HTTP client to a Deyta daemon (local ``deyta serve`` or, later, cloud).
+
+The CLI never imports Khora. Every command builds a request, hands it to this
+client, and renders the response. The base URL is resolved once (``--host`` >
+``DEYTA_HOST`` > current context > localhost), so pointing the same commands at a
+cloud platform is purely a matter of which context is active.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from . import config
+
+
+class DeytaClientError(Exception):
+    """User-facing client error (connection refused, HTTP error, etc.)."""
+
+
+class DeytaClient:
+    def __init__(self, host: str | None = None, *, timeout: float = 300.0) -> None:
+        self.host = config.resolve_host(host).rstrip("/")
+        self._timeout = timeout
+        token = config.auth_token(config.current_context()["name"])
+        self._headers = {"Authorization": f"Bearer {token}"} if token else {}
+
+    # ---- low-level -------------------------------------------------------- #
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        url = f"{self.host}{path}"
+        try:
+            with httpx.Client(timeout=self._timeout, headers=self._headers) as c:
+                resp = c.request(method, url, **kwargs)
+        except httpx.ConnectError as exc:
+            raise DeytaClientError(
+                f"No Deyta server at {self.host}. Run `deyta serve` first."
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise DeytaClientError(f"Request to {url} failed: {exc}") from exc
+        if resp.status_code >= 400:
+            raise DeytaClientError(_error_detail(resp))
+        return resp.json() if resp.content else None
+
+    # ---- health ----------------------------------------------------------- #
+    def health(self) -> dict[str, Any]:
+        return self._request("GET", "/health")
+
+    def is_up(self) -> bool:
+        try:
+            self.health()
+            return True
+        except DeytaClientError:
+            return False
+
+    # ---- namespaces ------------------------------------------------------- #
+    def create_namespace(self, name: str) -> dict[str, Any]:
+        return self._request("POST", "/namespaces", json={"name": name})
+
+    def list_namespaces(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/namespaces")["namespaces"]
+
+    def get_namespace(self, namespace_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/namespaces/{namespace_id}")
+
+    def delete_namespace(self, namespace_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/namespaces/{namespace_id}")
+
+    # ---- memory ----------------------------------------------------------- #
+    def remember(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/remember", json=payload)
+
+    def recall(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/recall", json=payload)
+
+    def forget(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/forget", json=payload)
+
+    def ingest(self, payload: dict[str, Any]) -> Iterator[dict[str, Any]]:
+        """Stream ingest progress as Server-Sent Events.
+
+        Yields ``{"type": "progress", "processed", "total"}`` events followed by a
+        single ``{"type": "result", ...}`` (or ``{"type": "error", ...}``) event.
+        """
+        url = f"{self.host}/ingest"
+        try:
+            with httpx.Client(timeout=None, headers=self._headers) as c:
+                with c.stream("POST", url, json=payload) as resp:
+                    if resp.status_code >= 400:
+                        resp.read()
+                        raise DeytaClientError(_error_detail(resp))
+                    for line in resp.iter_lines():
+                        if line.startswith("data: "):
+                            yield json.loads(line[len("data: ") :])
+        except httpx.ConnectError as exc:
+            raise DeytaClientError(
+                f"No Deyta server at {self.host}. Run `deyta serve` first."
+            ) from exc
+
+
+def _error_detail(resp: httpx.Response) -> str:
+    try:
+        body = resp.json()
+        return str(body.get("detail", body))
+    except (json.JSONDecodeError, ValueError):
+        return f"HTTP {resp.status_code}: {resp.text[:200]}"

deyta_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Typer command groups for the Deyta CLI."""

deyta_cli/commands/_common.py

@@ -0,0 +1,84 @@
+"""Shared helpers for command implementations."""
+
+from __future__ import annotations
+
+import typer
+
+from .. import config, docker, render
+from ..client import DeytaClient
+
+
+def get_host(ctx: typer.Context) -> str | None:
+    obj = ctx.obj or {}
+    return obj.get("host")
+
+
+def get_client(ctx: typer.Context) -> DeytaClient:
+    return DeytaClient(get_host(ctx))
+
+
+def require_project(ctx: typer.Context) -> config.ProjectConfig:
+    """Load ``deyta.toml`` or exit with guidance."""
+    cfg = config.load_project_config()
+    if cfg is None:
+        render.error("No deyta.toml found. Run `deyta init` first.")
+        raise typer.Exit(1)
+    return cfg
+
+
+def resolve_namespace(cfg: config.ProjectConfig, ns_opt: str | None) -> str:
+    """Resolve a ``--namespace`` option (or the active namespace) to a UUID."""
+    target = ns_opt or cfg.active
+    if not target:
+        render.error(
+            "No namespace selected. Create one with `deyta ns create <name>` "
+            "and `deyta ns use <name>`, or pass --namespace."
+        )
+        raise typer.Exit(1)
+    return cfg.resolve_namespace(target)
+
+
+def resolve_ontology(
+    cfg: config.ProjectConfig,
+    entity_types: str | None,
+    relationship_types: str | None,
+) -> tuple[list[str], list[str]]:
+    """Flags override the project default ontology; otherwise fall back to config."""
+    ents = _split(entity_types) if entity_types else cfg.entity_types
+    rels = _split(relationship_types) if relationship_types else cfg.relationship_types
+    return ents, rels
+
+
+def _split(csv: str) -> list[str]:
+    return [item.strip() for item in csv.split(",") if item.strip()]
+
+
+def bring_up_datastores() -> None:
+    """Start Postgres + Neo4j and wait until healthy, with live progress.
+
+    Exits with a clear message on Docker errors or if they don't come up in time.
+    """
+    try:
+        render.info("Starting datastores (Postgres + Neo4j)…")
+        docker.up(detach=True)
+    except docker.DockerError as exc:
+        render.error(str(exc))
+        raise typer.Exit(1) from exc
+
+    with render.console.status("[bold]Waiting for datastores…[/]", spinner="dots") as status:
+
+        def tick(states: dict[str, str]) -> None:
+            parts = "  ".join(f"{svc}=[bold]{st}[/]" for svc, st in states.items())
+            status.update(
+                f"[bold]Waiting for datastores to be ready[/] "
+                f"— Neo4j can take ~30s  {parts}"
+            )
+
+        healthy = docker.wait_healthy(on_tick=tick)
+
+    if not healthy:
+        render.error(
+            "Datastores didn't become healthy in time. Check `deyta db status` / `deyta db logs`."
+        )
+        raise typer.Exit(1)
+    render.success("Datastores healthy (postgres :5434, neo4j bolt :7688).")

deyta_cli/commands/aliases.py

@@ -0,0 +1,47 @@
+"""Top-level shorthands for the hottest memory verbs.
+
+`deyta ingest` == `deyta memory ingest`; `deyta query` == `deyta memory recall`.
+These delegate to the same ``run_*`` helpers so behavior never drifts.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from . import memory
+
+
+def ingest(
+    ctx: typer.Context,
+    path: Path = typer.Argument(..., help="File or directory to ingest."),
+    namespace: str = typer.Option(None, "--namespace", "-n"),
+    recursive: bool = typer.Option(True, "--recursive/--no-recursive"),
+    include: str = typer.Option(None, "--include", help="Glob (e.g. '**/*.md')."),
+    entity_types: str = typer.Option(None, "--entity-types"),
+    relationship_types: str = typer.Option(None, "--relationship-types"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+) -> None:
+    """Ingest files from a path (alias for `memory ingest`)."""
+    memory.run_ingest(
+        ctx, path, namespace, recursive, include, entity_types, relationship_types, dry_run
+    )
+
+
+def query(
+    ctx: typer.Context,
+    text: str = typer.Argument(..., help="Query text."),
+    namespace: str = typer.Option(None, "--namespace", "-n"),
+    mode: str = typer.Option("hybrid", "--mode", help="hybrid|vector|graph|keyword|all"),
+    limit: int = typer.Option(10, "--limit", "-k"),
+    min_similarity: float = typer.Option(0.0, "--min-similarity"),
+    since: str = typer.Option(None, "--since"),
+    until: str = typer.Option(None, "--until"),
+    as_json: bool = typer.Option(False, "--json"),
+    as_context: bool = typer.Option(False, "--context"),
+) -> None:
+    """Recall from memory (alias for `memory recall`)."""
+    memory.run_recall(
+        ctx, text, namespace, mode, limit, min_similarity, since, until, as_json, as_context
+    )

deyta_cli/commands/auth.py

@@ -0,0 +1,25 @@
+"""`deyta login` / `logout` — cloud auth. Stubbed in MVP; the seam is real.
+
+When the cloud platform ships, `login` will run a browser OAuth flow, write a token
+to ~/.config/deyta/auth.json, and add a `cloud` context. Today it explains that.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import render
+
+
+def login() -> None:
+    """Authenticate to the Deyta cloud platform (not yet available)."""
+    render.info(
+        "[yellow]Cloud is not yet available.[/] When it ships, `deyta login` will "
+        "authenticate you and add a `cloud` context. For now, run everything locally "
+        "with `deyta serve`."
+    )
+
+
+def logout() -> None:
+    """Sign out of the Deyta cloud platform (not yet available)."""
+    render.info("[yellow]Cloud is not yet available.[/] Nothing to sign out of.")

deyta_cli/commands/context.py

@@ -0,0 +1,53 @@
+"""`deyta context …` — switch the CLI between local and (future) cloud targets.
+
+A context is just a named ``host`` (plus a target kind). Switching contexts is the
+persistent local<->cloud toggle; ``--host`` / ``DEYTA_HOST`` override it per-command.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import config, render
+
+app = typer.Typer(help="Manage local/cloud contexts.", no_args_is_help=True)
+
+
+@app.command("list")
+def context_list() -> None:
+    """List configured contexts."""
+    data = config.load_contexts()
+    current = data["current_context"]
+    from rich.table import Table
+
+    table = Table(title="Contexts")
+    table.add_column("", style="green", width=1)
+    table.add_column("name", style="bold")
+    table.add_column("target")
+    table.add_column("host", style="dim")
+    for name, ctx in data["contexts"].items():
+        marker = "●" if name == current else ""
+        table.add_row(marker, name, ctx.get("target", "?"), ctx.get("host", ""))
+    render.console.print(table)
+
+
+@app.command("current")
+def context_current() -> None:
+    """Show the active context."""
+    ctx = config.current_context()
+    render.info(f"[bold]{ctx['name']}[/]  →  {ctx.get('host')}  ({ctx.get('target')})")
+
+
+@app.command("use")
+def context_use(name: str = typer.Argument(..., help="Context name to switch to.")) -> None:
+    """Switch the active context."""
+    data = config.load_contexts()
+    if name not in data["contexts"]:
+        render.error(
+            f"Unknown context {name!r}. Known: {', '.join(data['contexts'])}. "
+            "(Cloud contexts arrive with `deyta login`.)"
+        )
+        raise typer.Exit(1)
+    data["current_context"] = name
+    config.save_contexts(data)
+    render.success(f"Switched to context {name!r} ({data['contexts'][name].get('host')}).")

deyta_cli/commands/db.py

@@ -0,0 +1,58 @@
+"""`deyta db …` — manage the Docker datastores for the postgres backend."""
+
+from __future__ import annotations
+
+import typer
+
+from .. import docker, render
+from ._common import bring_up_datastores
+
+app = typer.Typer(help="Manage the Postgres + Neo4j datastores (Docker).", no_args_is_help=True)
+
+
+@app.command("up")
+def db_up(
+    detach: bool = typer.Option(True, "--detach/--no-detach", "-d", help="Run detached."),
+) -> None:
+    """Start Postgres + Neo4j via Docker Compose."""
+    if detach:
+        bring_up_datastores()  # starts + waits for health with a live spinner
+        return
+    try:
+        docker.up(detach=False)  # foreground: stream logs, no health wait
+    except docker.DockerError as exc:
+        render.error(str(exc))
+        raise typer.Exit(1) from exc
+
+
+@app.command("down")
+def db_down() -> None:
+    """Stop the datastores."""
+    try:
+        docker.down()
+        render.success("Datastores stopped.")
+    except docker.DockerError as exc:
+        render.error(str(exc))
+        raise typer.Exit(1) from exc
+
+
+@app.command("status")
+def db_status() -> None:
+    """Show datastore container status."""
+    try:
+        render.info(docker.status())
+    except docker.DockerError as exc:
+        render.error(str(exc))
+        raise typer.Exit(1) from exc
+
+
+@app.command("logs")
+def db_logs(
+    follow: bool = typer.Option(False, "--follow", "-f", help="Follow log output."),
+) -> None:
+    """Show datastore logs."""
+    try:
+        docker.logs(follow=follow)
+    except docker.DockerError as exc:
+        render.error(str(exc))
+        raise typer.Exit(1) from exc

deyta_cli/commands/init.py

@@ -0,0 +1,148 @@
+"""`deyta init` — scaffold a project's deyta.toml interactively."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import questionary
+import typer
+
+from .. import config, render
+
+# Curated OpenAI model menus (with an escape hatch to type any model id).
+_OTHER = "__other__"
+_EMBEDDING_MODELS = [
+    ("text-embedding-3-small (1536 dims, cheapest)", "text-embedding-3-small"),
+    ("text-embedding-3-large (3072 dims, best quality)", "text-embedding-3-large"),
+]
+_LLM_MODELS = [
+    ("gpt-4o-mini (fast, cheap — default)", "gpt-4o-mini"),
+    ("gpt-4o (higher quality)", "gpt-4o"),
+    ("gpt-4.1-mini", "gpt-4.1-mini"),
+    ("gpt-4.1", "gpt-4.1"),
+]
+
+
+def _pick_model(message: str, options: list[tuple[str, str]], default_value: str) -> str | None:
+    choices = [questionary.Choice(label, value=value) for label, value in options]
+    choices.append(questionary.Choice("Other (enter a model id)…", value=_OTHER))
+    picked = questionary.select(message, choices=choices, default=_default_choice(choices, default_value)).ask()
+    if picked is None:
+        return None
+    if picked == _OTHER:
+        return questionary.text("Model id:").ask()
+    return picked
+
+
+def _default_choice(choices: list[questionary.Choice], value: str):
+    return next((c for c in choices if c.value == value), None)
+
+
+def init(
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing deyta.toml."),
+) -> None:
+    """Create a deyta.toml in the current directory."""
+    root = Path.cwd()
+    cfg_path = root / config.PROJECT_CONFIG_NAME
+    if cfg_path.exists() and not force:
+        render.error(f"{config.PROJECT_CONFIG_NAME} already exists. Use --force to overwrite.")
+        raise typer.Exit(1)
+
+    # 1. Backend ----------------------------------------------------------- #
+    backend = questionary.select(
+        "Backend:",
+        choices=[
+            questionary.Choice(
+                "Standard (PostgreSQL + pgvector + Neo4j) — Docker",
+                value=config.BACKEND_POSTGRES,
+            ),
+            questionary.Choice(
+                "Embedded (SQLite + LanceDB) — no Docker",
+                value=config.BACKEND_EMBEDDED,
+            ),
+        ],
+    ).ask()
+    if backend is None:
+        raise typer.Exit(1)
+
+    cfg = config.ProjectConfig(root=root, backend=backend)
+    if backend == config.BACKEND_EMBEDDED:
+        db_path = questionary.text("Embedded DB path:", default="./khora.db").ask()
+        cfg.db_path = db_path or "./khora.db"
+
+    # 2. Models: defaults or customize ------------------------------------ #
+    mode = questionary.select(
+        "Model configuration:",
+        choices=[
+            questionary.Choice(
+                f"Use defaults (OpenAI · {config.DEFAULT_EMBEDDING_MODEL} · {config.DEFAULT_LLM_MODEL})",
+                value="default",
+            ),
+            questionary.Choice("Customize (choose provider and models)", value="custom"),
+        ],
+    ).ask()
+    if mode is None:
+        raise typer.Exit(1)
+
+    if mode == "custom":
+        provider = questionary.select(
+            "Model provider:",
+            choices=[
+                questionary.Choice("OpenAI", value="openai"),
+                questionary.Choice(
+                    "Anthropic (coming soon)", value="anthropic", disabled="not yet supported"
+                ),
+            ],
+        ).ask()
+        if provider is None:
+            raise typer.Exit(1)
+        cfg.provider = provider
+
+        embedding_model = _pick_model(
+            "Embedding model:", _EMBEDDING_MODELS, config.DEFAULT_EMBEDDING_MODEL
+        )
+        if not embedding_model:
+            raise typer.Exit(1)
+        cfg.embedding_model = embedding_model
+        cfg.embedding_dimension = config.EMBEDDING_DIMENSIONS.get(embedding_model, 1536)
+
+        llm_model = _pick_model(
+            "Retrieval / extraction model:", _LLM_MODELS, config.DEFAULT_LLM_MODEL
+        )
+        if not llm_model:
+            raise typer.Exit(1)
+        cfg.llm_model = llm_model
+    # else: ProjectConfig already carries the OpenAI defaults.
+
+    # 3. API key ----------------------------------------------------------- #
+    _capture_api_key()
+
+    # 5. Write ------------------------------------------------------------- #
+    cfg.save()
+    render.success(f"Wrote {config.PROJECT_CONFIG_NAME}")
+    render.info(
+        f"  backend: [bold]{cfg.backend}[/]  ·  embeddings: [bold]{cfg.embedding_model}[/] "
+        f"({cfg.embedding_dimension}d)  ·  model: [bold]{cfg.llm_model}[/]"
+    )
+    if backend == config.BACKEND_POSTGRES:
+        render.info("Next: `deyta up` to start Postgres + Neo4j and the daemon.")
+    else:
+        render.info("Next: `deyta up` to start the daemon.")
+
+
+def _capture_api_key() -> None:
+    """Store the OpenAI API key as DEYTA_OPENAI_API_KEY in the user-global .env.
+
+    deyta only ever uses its own namespaced secret — never an ambient
+    ``OPENAI_API_KEY`` — so the key is always captured here explicitly.
+    """
+    key = questionary.password("OpenAI API key (leave blank to set later):").ask()
+    if key:
+        path = config.global_env_path()
+        config.write_env(path, {"DEYTA_OPENAI_API_KEY": key})
+        render.success(f"Saved DEYTA_OPENAI_API_KEY to {path} (shared across projects).")
+    else:
+        render.info(
+            "[yellow]![/] No key set. Add DEYTA_OPENAI_API_KEY to "
+            f"{config.global_env_path()} before `deyta serve`."
+        )