hyperspell-brain 0.4.0__py3-none-any.whl

hyperbrain/__init__.py

@@ -0,0 +1,3 @@
+"""hyperbrain — an agent-first CLI for the Hyperspell company brain."""
+
+__version__ = "0.4.0"

hyperbrain/cli.py

@@ -0,0 +1,141 @@
+"""hyperbrain — agent-first CLI for the Hyperspell company brain.
+
+Root command: wires global options into a per-invocation AppCtx, then dispatches
+to the command modules. Designed so an agent can call any subcommand
+non-interactively and parse JSON from stdout.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import typer
+
+from . import __version__, config
+from .context import AppCtx
+from .output import FORMAT_OPTION, Format, emit, pick, set_output_options
+from .commands import api as api_cmd
+from .commands import ask as ask_cmd
+from .commands import auth as auth_cmd
+from .commands import brain as brain_cmd
+from .commands import completion as completion_cmd
+from .commands import config as config_cmd
+from .commands import connections as connections_cmd
+from .commands import doctor as doctor_cmd
+from .commands import guide as guide_cmd
+from .commands import integrations as integrations_cmd
+from .commands import login as login_cmd
+from .commands import memories as memories_cmd
+from .commands import remember as remember_cmd
+from .commands import search as search_cmd
+from .commands import structure as structure_cmd
+from .commands import update as update_cmd
+
+app = typer.Typer(
+    name="hyperbrain",
+    help="Agent-first CLI for the Hyperspell company brain. JSON by default; pipe-friendly.",
+    no_args_is_help=True,
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    api_key: Optional[str] = typer.Option(
+        None, "--api-key", envvar="HYPERSPELL_API_KEY", help="API key (or device JWT)."
+    ),
+    api_url: Optional[str] = typer.Option(
+        None, "--api-url", envvar="HYPERSPELL_BASE_URL", help="API base URL."
+    ),
+    as_user: Optional[str] = typer.Option(
+        None, "--as-user", help="Act as this user (X-As-User; API-key auth only)."
+    ),
+    output_format: Format = typer.Option(
+        Format.AUTO,
+        "--format",
+        "-o",
+        help="Output format: auto (table on TTY, else json), json, table.",
+    ),
+    fields: Optional[str] = typer.Option(
+        None,
+        "--fields",
+        help="Comma-separated top-level keys to keep in the output (token economy).",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Suppress the stdout data channel; branch on the exit code instead.",
+    ),
+    _v: bool = typer.Option(
+        False, "--version", callback=_version, is_eager=True, help="Show version and exit."
+    ),
+) -> None:
+    """Resolve credentials/endpoint once and stash them for subcommands."""
+    set_output_options(fields=fields, quiet=quiet)
+    ctx.obj = AppCtx(
+        resolved=config.resolve(api_key=api_key, api_url=api_url, as_user=as_user),
+        fmt=output_format,
+    )
+
+
+# Top-level verbs.
+app.command()(login_cmd.login)
+app.command()(ask_cmd.ask)
+app.command()(search_cmd.search)
+app.command()(remember_cmd.remember)
+app.command(name="api")(api_cmd.api)
+app.command()(update_cmd.update)
+app.command()(doctor_cmd.doctor)
+app.command()(completion_cmd.completion)
+app.command(name="help")(guide_cmd.help)
+
+# Grouped nouns.
+app.add_typer(memories_cmd.app, name="memories")
+app.add_typer(connections_cmd.app, name="connections")
+app.add_typer(integrations_cmd.app, name="integrations")
+app.add_typer(brain_cmd.app, name="brain")
+app.add_typer(structure_cmd.app, name="structure")
+app.add_typer(config_cmd.app, name="config")
+app.add_typer(auth_cmd.app, name="auth")
+
+
+def _describe(cmd: Any, name: str) -> dict[str, Any]:
+    """Recursively describe a click command tree using duck-typing (no click import)."""
+    node: dict[str, Any] = {"name": name, "help": (getattr(cmd, "help", "") or "").strip()}
+    params = []
+    for p in getattr(cmd, "params", []):
+        kind = getattr(p, "param_type_name", "parameter")  # 'option' | 'argument'
+        entry: dict[str, Any] = {"name": p.name, "kind": kind, "required": bool(p.required)}
+        if kind == "option":
+            entry["flags"] = list(getattr(p, "opts", []))
+            entry["help"] = getattr(p, "help", "") or ""
+        params.append(entry)
+    if params:
+        node["params"] = params
+    subcommands = getattr(cmd, "commands", None)  # dict on click Groups
+    if isinstance(subcommands, dict):
+        node["commands"] = [_describe(sub, sub_name) for sub_name, sub in subcommands.items()]
+    return node
+
+
+@app.command()
+def schema(
+    ctx: typer.Context,
+    fmt: Optional[Format] = FORMAT_OPTION,
+) -> None:
+    """Dump the full command tree as JSON, so an agent can introspect capabilities."""
+    root = typer.main.get_command(app)
+    emit(_describe(root, "hyperbrain"), pick(ctx, fmt))
+
+
+if __name__ == "__main__":
+    app()

hyperbrain/client.py

@@ -0,0 +1,93 @@
+"""SDK client construction + a raw-request escape hatch.
+
+Most commands use the typed ``hyperspell`` SDK. A handful of endpoints the SDK
+doesn't model yet — context-document *trees* and the ``/admin/*`` surface — are
+reached through the SDK's own underlying httpx client via :func:`raw`, so they
+share the same auth, base URL, retries, and timeouts.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any, Iterator
+
+from hyperspell import (
+    APIConnectionError,
+    APIStatusError,
+    AuthenticationError,
+    Hyperspell,
+    HyperspellError,
+    NotFoundError,
+)
+
+from . import config
+from .output import Exit, fail
+
+
+def build(resolved: config.Resolved) -> Hyperspell:
+    """Construct an authenticated SDK client, or exit cleanly if unauthenticated."""
+    if not resolved.credential:
+        raise fail(
+            "No credential found. Pass --api-key, set HYPERSPELL_API_KEY, "
+            "or run `hyperbrain login` to populate ~/.hyperspell/config.toml.",
+            Exit.AUTH,
+        )
+    return Hyperspell(
+        api_key=resolved.credential,
+        user_id=resolved.user_id,
+        base_url=resolved.base_url,
+    )
+
+
+def raw(
+    client: Hyperspell,
+    method: str,
+    path: str,
+    *,
+    body: dict[str, Any] | None = None,
+    params: dict[str, Any] | None = None,
+) -> Any:
+    """Call an endpoint the SDK doesn't model, reusing its auth + transport.
+
+    Returns parsed JSON (dict/list) and never raises for a non-2xx — callers get
+    the decoded error body so they can surface the API's own message.
+    """
+    options: dict[str, Any] = {"cast_to": object}
+    if body is not None:
+        options["body"] = body
+    if params is not None:
+        options["options"] = {"params": params}
+    verb = method.lower()
+    fn = getattr(client, verb, None)
+    if fn is None:
+        raise fail(f"Unsupported HTTP method: {method}", Exit.USAGE)
+    return fn(path, **options)
+
+
+@contextlib.contextmanager
+def api_errors() -> Iterator[None]:
+    """Translate SDK exceptions into structured stderr errors + stable exit codes."""
+    try:
+        yield
+    except AuthenticationError as exc:
+        raise fail(f"Authentication failed: {exc}", Exit.AUTH) from exc
+    except NotFoundError as exc:
+        raise fail(f"Not found: {exc}", Exit.NOT_FOUND) from exc
+    except APIStatusError as exc:
+        detail = _detail(exc)
+        raise fail(f"API error {exc.status_code}: {detail}", Exit.API) from exc
+    except APIConnectionError as exc:
+        raise fail(f"Could not reach the API: {exc}", Exit.API) from exc
+    except HyperspellError as exc:
+        raise fail(str(exc), Exit.ERROR) from exc
+
+
+def _detail(exc: APIStatusError) -> str:
+    """Pull the API's own error message out of a non-2xx response when present."""
+    try:
+        body = exc.response.json()
+    except Exception:
+        return str(exc)
+    if isinstance(body, dict):
+        return str(body.get("detail") or body.get("error") or body)
+    return str(body)

hyperbrain/commands/_query.py

@@ -0,0 +1,55 @@
+"""Shared retrieval logic behind `brain ask` and `brain search`.
+
+Both hit ``POST /memories/query``; ``ask`` flips ``answer=true`` and dials up
+effort, while ``search`` returns ranked documents only. ``effort`` is passed via
+``extra_body`` because the pinned SDK predates that field — the API honors it.
+"""
+
+from __future__ import annotations
+
+from hyperspell import Hyperspell
+
+from .. import client as client_mod
+
+VALID_EFFORT = {"minimal", "low", "medium", "high"}
+
+
+def default_sources(client: Hyperspell) -> list[str]:
+    """Sources to query when the caller didn't pick any: everything this token has.
+
+    Reads the app's connected integrations from ``/auth/me`` (plus ``vault``,
+    which is always available) so "ask the brain" really means the whole brain.
+    The API drops any source it doesn't support, so a generous list is safe.
+    """
+    me = client_mod.raw(client, "GET", "/auth/me")
+    integs = []
+    if isinstance(me, dict):
+        integs = me.get("available_integrations") or []
+    return sorted({*integs, "vault"})
+
+
+def run_query(
+    client: Hyperspell,
+    *,
+    query: str,
+    answer: bool,
+    effort: str,
+    sources: list[str] | None,
+    max_results: int,
+    collection: str | None,
+):
+    """Execute a query and return the SDK's QueryResult."""
+    options: dict[str, object] = {}
+    if collection:
+        options["filter"] = {"collection": collection}
+
+    kwargs: dict[str, object] = {
+        "query": query,
+        "answer": answer,
+        "max_results": max_results,
+        "sources": sources if sources else default_sources(client),
+        "extra_body": {"effort": effort},
+    }
+    if options:
+        kwargs["options"] = options
+    return client.memories.search(**kwargs)

hyperbrain/commands/api.py

@@ -0,0 +1,89 @@
+"""`hyperbrain api` — a raw authenticated request to any Hyperspell endpoint.
+
+The escape hatch that lets an agent reach anything the API exposes, not just the
+verbs we've modeled. Reuses the resolved credential + transport, returns parsed
+JSON, and never invents arguments — you give it the method, path, and body.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+
+from .. import client as client_mod
+from .. import context, output
+
+_METHODS = ("GET", "POST", "PATCH", "PUT", "DELETE")
+# Methods that carry a request body (and may read it from stdin).
+_BODY_METHODS = ("POST", "PATCH", "PUT", "DELETE")
+
+
+def api(
+    ctx: typer.Context,
+    method: str = typer.Argument(..., help=f"HTTP method: {', '.join(_METHODS)}."),
+    path: str = typer.Argument(..., help="API path, e.g. /memories/list or /admin/apps/foo/..."),
+    data: Optional[str] = typer.Option(
+        None, "--data", "-d", help="JSON request body. Omit to read stdin (write methods)."
+    ),
+    file: Optional[Path] = typer.Option(
+        None, "--file", "-f", help="Read the JSON request body from a file."
+    ),
+    query: Optional[list[str]] = typer.Option(
+        None, "--query", "-q", help="Query param as key=value (repeatable)."
+    ),
+    fmt: Optional[output.Format] = output.FORMAT_OPTION,
+) -> None:
+    """Make a raw authenticated request to any endpoint and print the JSON response."""
+    verb = method.upper()
+    if verb not in _METHODS:
+        raise output.fail(f"Method must be one of {_METHODS}.", output.Exit.USAGE)
+    if not path.startswith("/"):
+        raise output.fail("Path must start with '/'.", output.Exit.USAGE)
+
+    body = _resolve_body(verb, data, file)
+    params = _parse_query(query)
+
+    app_ctx = context.get(ctx)
+    cli = client_mod.build(app_ctx.resolved)
+    with client_mod.api_errors():
+        result = client_mod.raw(cli, verb, path, body=body, params=params)
+    output.emit(result, output.pick(ctx, fmt))
+
+
+def _resolve_body(verb: str, data: Optional[str], file: Optional[Path]) -> Optional[dict[str, Any]]:
+    raw_text: Optional[str] = None
+    if file is not None:
+        if not file.exists():
+            raise output.fail(f"File not found: {file}", output.Exit.NOT_FOUND)
+        raw_text = file.read_text()
+    elif data is not None:
+        raw_text = data
+    elif verb in _BODY_METHODS and not sys.stdin.isatty():
+        piped = sys.stdin.read()
+        raw_text = piped if piped.strip() else None
+
+    if raw_text is None:
+        return None
+    try:
+        parsed = json.loads(raw_text)
+    except json.JSONDecodeError as exc:
+        raise output.fail(f"Request body is not valid JSON: {exc}", output.Exit.USAGE) from exc
+    if not isinstance(parsed, dict):
+        raise output.fail("Request body must be a JSON object.", output.Exit.USAGE)
+    return parsed
+
+
+def _parse_query(query: Optional[list[str]]) -> Optional[dict[str, str]]:
+    if not query:
+        return None
+    params: dict[str, str] = {}
+    for item in query:
+        key, sep, value = item.partition("=")
+        if not sep:
+            raise output.fail(f"--query '{item}' must be key=value.", output.Exit.USAGE)
+        params[key] = value
+    return params

hyperbrain/commands/ask.py

@@ -0,0 +1,79 @@
+"""`brain ask` — ask the company brain a question and get a synthesized answer."""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import typer
+
+from .. import client as client_mod
+from .. import context, output
+from ._query import VALID_EFFORT, run_query
+
+
+def ask(
+    ctx: typer.Context,
+    query: str = typer.Argument(..., help="The question to ask the company brain."),
+    effort: str = typer.Option(
+        "high",
+        "--effort",
+        "-e",
+        help="Compute to spend: minimal | low | medium | high. Higher = better recall, more latency.",
+    ),
+    source: Optional[list[str]] = typer.Option(
+        None,
+        "--source",
+        "-s",
+        help="Restrict to these sources (repeatable). Default: all connected sources.",
+    ),
+    collection: Optional[str] = typer.Option(None, "--collection", help="Scope to a collection."),
+    max_results: int = typer.Option(10, "--max-results", "-n", help="Max source documents to use."),
+    answer_only: bool = typer.Option(
+        False, "--answer-only", help="Emit just the answer string, not the JSON envelope."
+    ),
+    fmt: Optional[output.Format] = output.FORMAT_OPTION,
+) -> None:
+    """Synthesize an answer from the brain, with the supporting documents."""
+    if effort not in VALID_EFFORT:
+        raise output.fail(
+            f"Invalid --effort {effort!r}; choose one of {sorted(VALID_EFFORT)}.",
+            output.Exit.USAGE,
+        )
+    app = context.get(ctx)
+    cli = client_mod.build(app.resolved)
+    with client_mod.api_errors():
+        result = run_query(
+            cli,
+            query=query,
+            answer=True,
+            effort=effort,
+            sources=source,
+            max_results=max_results,
+            collection=collection,
+        )
+    if answer_only:
+        typer.echo(getattr(result, "answer", None) or "")
+        return
+    resolved = output.pick(ctx, fmt)
+    if resolved is output.Format.TABLE or (resolved is output.Format.AUTO and sys.stdout.isatty()):
+        _render_answer(result)
+    else:
+        output.emit(result, resolved)
+
+
+def _render_answer(result: object) -> None:
+    """Human-friendly terminal view: the prose answer plus its sources."""
+    from rich.console import Console
+    from rich.panel import Panel
+
+    console = Console()
+    answer = getattr(result, "answer", None) or "[dim](no answer returned)[/dim]"
+    console.print(Panel(answer, title="answer", border_style="cyan"))
+    docs = getattr(result, "documents", None) or []
+    if docs:
+        console.print("[bold]sources[/bold]")
+        for i, doc in enumerate(docs, 1):
+            title = getattr(doc, "title", None) or getattr(doc, "resource_id", "") or "?"
+            src = getattr(doc, "source", "")
+            console.print(f"  {i}. [cyan]{src}[/cyan] {title}")

hyperbrain/commands/auth.py

@@ -0,0 +1,43 @@
+"""`brain auth` — inspect the resolved credential and verify it against the API."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from .. import client as client_mod
+from .. import context, output
+
+app = typer.Typer(help="Authentication status.", no_args_is_help=True)
+
+
+def _redact(cred: str | None) -> str | None:
+    if not cred:
+        return None
+    return f"{cred[:6]}…{cred[-4:]}" if len(cred) > 12 else "set"
+
+
+@app.command()
+def status(
+    ctx: typer.Context,
+    check: bool = typer.Option(
+        True, "--check/--no-check", help="Verify the credential against the API (/auth/me)."
+    ),
+    fmt: Optional[output.Format] = output.FORMAT_OPTION,
+) -> None:
+    """Show where the credential came from and (by default) whether it works."""
+    app_ctx = context.get(ctx)
+    r = app_ctx.resolved
+    result: dict[str, object] = {
+        "authenticated": bool(r.credential),
+        "credential": _redact(r.credential),
+        "credential_source": r.source,
+        "base_url": r.base_url,
+        "user_id": r.user_id,
+    }
+    if check and r.credential:
+        cli = client_mod.build(r)
+        with client_mod.api_errors():
+            result["identity"] = client_mod.raw(cli, "GET", "/auth/me")
+    output.emit(result, output.pick(ctx, fmt))

hyperbrain/commands/brain.py

@@ -0,0 +1,147 @@
+"""`brain generate` and friends — the synthesized three-tier company brain.
+
+These hit endpoints the SDK doesn't model yet, so they go through the raw escape
+hatch. ``generate`` kicks off an async Temporal workflow and (by default) polls
+progress to completion, streaming phase updates to stderr so stdout stays a
+clean channel for the final tree JSON.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from typing import Any, Optional
+
+import typer
+
+from .. import client as client_mod
+from .. import context, output
+
+app = typer.Typer(
+    help="Generate and fetch the synthesized company-brain tree.", no_args_is_help=True
+)
+
+TERMINAL = {"completed", "published", "failed"}
+POLL_INTERVAL_S = 3.0
+DEFAULT_TIMEOUT_S = 900  # 15 min — matches the documented worst-case synthesis time
+
+
+@app.command()
+def generate(
+    ctx: typer.Context,
+    source: Optional[list[str]] = typer.Option(
+        None, "--source", "-s", help="Sources to include (repeatable). Default: all synced data."
+    ),
+    workstream: Optional[str] = typer.Option(
+        None, "--workstream", help="Generate for this workstream only (skip auto-detection)."
+    ),
+    user_id: Optional[str] = typer.Option(
+        None, "--user-id", help="Scope the personal tier to this user's data."
+    ),
+    wait: bool = typer.Option(
+        True,
+        "--wait/--no-wait",
+        help="Poll to completion (default) or return the tree_id and exit.",
+    ),
+    timeout: int = typer.Option(DEFAULT_TIMEOUT_S, "--timeout", help="Max seconds to wait."),
+    fmt: Optional[output.Format] = output.FORMAT_OPTION,
+) -> None:
+    """Kick off a company-brain tree generation."""
+    app_ctx = context.get(ctx)
+    cli = client_mod.build(app_ctx.resolved)
+    resolved_fmt = output.pick(ctx, fmt)
+
+    body: dict[str, Any] = {}
+    if source:
+        body["sources"] = source
+    if workstream:
+        body["workstream_name"] = workstream
+    if user_id:
+        body["user_id"] = user_id
+
+    with client_mod.api_errors():
+        started = client_mod.raw(cli, "POST", "/context-documents/tree", body=body)
+    tree_id = _field(started, "tree_id")
+    if not wait or not tree_id:
+        output.emit(started, resolved_fmt)
+        return
+
+    final = _poll(cli, tree_id, timeout)
+    status = (_field(final, "status") or "").lower()
+    if status == "failed":
+        raise output.fail(f"Tree {tree_id} generation failed.", output.Exit.API)
+    # Emit the finished tree itself, not just the progress record.
+    with client_mod.api_errors():
+        tree = client_mod.raw(cli, "GET", f"/context-documents/tree/by-id/{tree_id}")
+    output.emit(tree, resolved_fmt)
+
+
+@app.command()
+def latest(
+    ctx: typer.Context,
+    fmt: Optional[output.Format] = output.FORMAT_OPTION,
+) -> None:
+    """Fetch the most recent completed/published tree."""
+    app_ctx = context.get(ctx)
+    cli = client_mod.build(app_ctx.resolved)
+    with client_mod.api_errors():
+        result = client_mod.raw(cli, "GET", "/context-documents/tree/latest")
+    output.emit(result, output.pick(ctx, fmt))
+
+
+@app.command()
+def get(
+    ctx: typer.Context,
+    tree_id: str = typer.Argument(..., help="The tree ID."),
+    fmt: Optional[output.Format] = output.FORMAT_OPTION,
+) -> None:
+    """Fetch a tree by ID."""
+    app_ctx = context.get(ctx)
+    cli = client_mod.build(app_ctx.resolved)
+    with client_mod.api_errors():
+        result = client_mod.raw(cli, "GET", f"/context-documents/tree/by-id/{tree_id}")
+    output.emit(result, output.pick(ctx, fmt))
+
+
+@app.command()
+def progress(
+    ctx: typer.Context,
+    tree_id: str = typer.Argument(..., help="The tree ID."),
+    fmt: Optional[output.Format] = output.FORMAT_OPTION,
+) -> None:
+    """Check generation progress for a tree (single snapshot)."""
+    app_ctx = context.get(ctx)
+    cli = client_mod.build(app_ctx.resolved)
+    with client_mod.api_errors():
+        result = client_mod.raw(cli, "GET", f"/context-documents/tree/{tree_id}/progress")
+    output.emit(result, output.pick(ctx, fmt))
+
+
+def _poll(cli: Any, tree_id: str, timeout: int) -> Any:
+    """Poll progress until terminal or timeout, narrating phase changes to stderr."""
+    deadline = time.monotonic() + timeout
+    last = None
+    while True:
+        with client_mod.api_errors():
+            snap = client_mod.raw(cli, "GET", f"/context-documents/tree/{tree_id}/progress")
+        status = (_field(snap, "status") or "").lower()
+        phase = _field(snap, "phase")
+        done, total = _field(snap, "completed_docs"), _field(snap, "total_docs")
+        line = f"[{status}] {phase or '...'}" + (f" {done}/{total}" if total else "")
+        if line != last:
+            print(line, file=sys.stderr, flush=True)
+            last = line
+        if status in TERMINAL:
+            return snap
+        if time.monotonic() >= deadline:
+            raise output.fail(
+                f"Timed out after {timeout}s waiting for tree {tree_id} (last status: {status}).",
+                output.Exit.API,
+            )
+        time.sleep(POLL_INTERVAL_S)
+
+
+def _field(obj: Any, key: str) -> Any:
+    if isinstance(obj, dict):
+        return obj.get(key)
+    return getattr(obj, key, None)