honcho-cli 0.1.0__py3-none-any.whl

honcho_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Honcho CLI — a terminal for Honcho."""
+
+__version__ = "0.1.0"

honcho_cli/_help.py

@@ -0,0 +1,130 @@
+"""Themed help rendering for honcho CLI.
+
+Single source of truth for:
+
+- Rich-utils theme constants (dim borders, brand color)
+- HonchoTyperGroup: subclass applied via ``cls=`` at every Typer app in
+  this package — replaces Click's terse ``Usage: …`` line with
+  pattern/example rows and prints a curated welcome at the top-level.
+
+Lives in its own module so every ``commands/*.py`` can import it without
+pulling in ``main.py`` (which would create an import cycle).
+"""
+
+from __future__ import annotations
+
+import click
+import typer.rich_utils as ru
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from typer.core import TyperGroup
+
+from honcho_cli import __version__
+from honcho_cli.branding import BANNER, BRAND
+from honcho_cli.output import use_json
+
+
+# Theme Typer's rich help renderer. Module-level side effect limited to
+# styling — no behavior changes that could surprise other Typer users.
+ru.STYLE_COMMANDS_PANEL_BORDER = "dim"
+ru.STYLE_OPTIONS_PANEL_BORDER = "dim"
+ru.STYLE_ERRORS_PANEL_BORDER = "dim"
+ru.STYLE_OPTION = f"bold {BRAND}"
+ru.STYLE_SWITCH = f"bold {BRAND}"
+ru.STYLE_USAGE = "dim"
+ru.STYLE_USAGE_COMMAND = f"bold {BRAND}"
+
+
+def _cmd_table(rows: list[tuple[str, str]]) -> Table:
+    t = Table(show_header=False, box=None, padding=(0, 2, 0, 0), expand=False)
+    t.add_column("cmd", style=f"bold {BRAND}", no_wrap=True)
+    t.add_column("desc", style="default")
+    for cmd, desc in rows:
+        t.add_row(cmd, desc)
+    return t
+
+
+def _welcome_panel(title: str, rows: list[tuple[str, str]]) -> Panel:
+    return Panel(
+        _cmd_table(rows),
+        title=f"[dim]{title}[/dim]",
+        title_align="left",
+        border_style="dim",
+        box=box.ROUNDED,
+        padding=(0, 1),
+        expand=False,
+    )
+
+
+def print_welcome(console: Console) -> None:
+    """Render the curated 3-panel welcome (banner + getting started / memory / commands)."""
+    if use_json():
+        return
+    console.print(f"[bold {BRAND}]{BANNER}[/bold {BRAND}]")
+    console.print(f"  [dim]v{__version__}[/dim]\n", highlight=False)
+
+    start_rows = [
+        ("honcho init",   "configure API key and server URL"),
+        ("honcho doctor", "verify connection and workspace health"),
+    ]
+    cmd_rows = [
+        ("[dim]pattern[/dim]", r"[dim]honcho <command> \[args] \[-w workspace] \[-p peer] \[-s session][/dim]"),
+        ("[dim]example[/dim]", "[dim]honcho peer chat \"what does alice prefer?\" -p alice -w agents[/dim]"),
+        ("", ""),
+        ("workspace",  "list · create · search · delete · inspect · queue-status"),
+        ("peer",       "list · create · search · inspect · card · chat"),
+        ("",           "get-metadata · set-metadata · representation"),
+        ("session",    "list · create · search · delete · inspect · add-peers"),
+        ("",           "context · get-metadata · set-metadata · peers"),
+        ("",           "remove-peers · representation · summaries"),
+        ("message",    "list · create · get"),
+        ("conclusion", "list · create · search · delete"),
+        ("config",     "inspect current configuration"),
+    ]
+    memory_rows = [
+        ("honcho peer chat \"...\" -p <peer> -w <workspace>","query the Dialectic about a peer"),
+        ("honcho peer inspect -p <peer> -w <workspace>","dashboard: peer card + recent conclusions + configuration"),
+        ("honcho peer representation -p <peer> -w <workspace>", "global peer representation"),
+        ("honcho peer representation -p <peer> -w <workspace> -s <session>", "session-scoped peer representation"),
+        ("honcho peer card -p <peer> -w <workspace>", "synthesized identity: traits, preferences, instructions"),
+        ("honcho conclusion list -p <peer> -w <workspace>",  "browse peer conclusions"),
+    ]
+
+    option_rows = [
+        ("-w / --workspace", "scope to a workspace"),
+        ("-p / --peer",      "scope to a peer"),
+        ("-s / --session",   "scope to a session"),
+        ("--json",           "force JSON output for scripts and agents"),
+        ("--help",           "show help for any command (e.g. honcho peer --help)"),
+    ]
+
+    console.print(_welcome_panel("getting started", start_rows))
+    console.print(_welcome_panel("commands", cmd_rows))
+    console.print(_welcome_panel("memory", memory_rows))
+    console.print(_welcome_panel("options", option_rows))
+    console.print()
+
+
+class HonchoTyperGroup(TyperGroup):
+    """Typer group with pattern/example usage and top-level welcome.
+
+    Applied via ``cls=`` on every ``typer.Typer(...)`` in this package,
+    so no class-level monkey-patching is needed.
+    """
+
+    def get_usage(self, ctx):
+        """Replace Click's 'Usage: …' with pattern/example rows."""
+        original = click.Command.get_usage(self, ctx)
+        pattern = original.replace("Usage: ", "", 1) if original.startswith("Usage: ") else original
+        subs = self.list_commands(ctx)
+        example = f"{ctx.command_path} {subs[0]}" if subs else f"{ctx.command_path} --help"
+        return f"pattern: {pattern}\nexample: {example}"
+
+    def format_help(self, ctx, formatter):
+        """Top-level --help renders the welcome; sub-groups fall through to Typer."""
+        if ctx.parent is None:
+            print_welcome(Console())
+            return
+        super().format_help(ctx, formatter)

honcho_cli/branding.py

@@ -0,0 +1,17 @@
+"""Honcho CLI brand constants — colours, icons, and the ASCII banner.
+"""
+
+BRAND = "#B6DAFD"
+
+BANNER = """
+██╗  ██╗ ██████╗ ███╗   ██╗ ██████╗██╗  ██╗ ██████╗
+██║  ██║██╔═══██╗████╗  ██║██╔════╝██║  ██║██╔═══██╗
+███████║██║   ██║██╔██╗ ██║██║     ███████║██║   ██║
+██╔══██║██║   ██║██║╚██╗██║██║     ██╔══██║██║   ██║
+██║  ██║╚██████╔╝██║ ╚████║╚██████╗██║  ██║╚██████╔╝
+╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝╚═╝  ╚═╝ ╚═════╝
+""".strip("\n")
+
+ICON_OK = "[green]✓[/green]"
+ICON_FAIL = "[red]✗[/red]"
+ICON_RUN = f"[{BRAND}]→[/{BRAND}]"

honcho_cli/commands/conclusion.py

@@ -0,0 +1,219 @@
+"""Conclusion commands: list, search, create, delete."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import typer
+
+from honcho_cli.commands.workspace import _handle_error
+from honcho_cli.output import print_error, print_result, status, use_json
+from honcho_cli.validation import validate_resource_id
+
+from honcho_cli._help import HonchoTyperGroup
+from honcho_cli.common import add_common_options, get_client, get_resolved_config, handle_cmd_flags
+
+app = typer.Typer(cls=HonchoTyperGroup, help="List, search, create, and delete peer conclusions (Honcho's memory atoms).")
+add_common_options(app)
+
+
+def _require_observer(observer: str | None) -> str:
+    """Resolve observer peer ID; emit combined error if peer+workspace both missing."""
+    config = get_resolved_config()
+    obs = observer or config.peer_id
+    if not obs:
+        if not config.workspace_id:
+            print_error(
+                "NO_SCOPE",
+                "No peer or workspace scoped. Pass --peer/-p and --workspace/-w, or set HONCHO_PEER_ID and HONCHO_WORKSPACE_ID.",
+            )
+        else:
+            print_error("NO_PEER", "Peer required. Pass --peer/-p: honcho conclusion <cmd> -p <peer>")
+        raise typer.Exit(1)
+    return obs
+
+
+@app.command("list")
+def list_conclusions(
+    observer: Optional[str] = typer.Option(None, "--observer", help="Observer peer ID"),
+    observed: Optional[str] = typer.Option(None, "--observed", help="Observed peer ID"),
+    limit: int = typer.Option(10, "--limit", help="Max results"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    peer: Optional[str] = typer.Option(None, "--peer", "-p", help="Override peer ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """List conclusions."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, peer=peer)
+    observer = _require_observer(observer)
+    client, config = get_client()
+
+    p = client.peer(observer)
+
+    try:
+        if observed:
+            scope = p.conclusions_of(observed)
+        else:
+            scope = p.conclusions
+
+        conclusions = scope.list(size=limit).items
+        items = [
+            {
+                "id": c.id,
+                "content": c.content if use_json() else c.content[:200],
+                "workspace_id": config.workspace_id,
+                "observer_id": c.observer_id,
+                "observed_id": c.observed_id,
+                "session_id": c.session_id,
+                "created_at": str(c.created_at),
+            }
+            for c in conclusions
+        ]
+        print_result(items, columns=["id", "content", "workspace_id", "observer_id", "observed_id", "session_id", "created_at"], title="Conclusions")
+    except Exception as e:
+        _handle_error(e, "conclusion", "list")
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(help="Search query"),
+    observer: Optional[str] = typer.Option(None, "--observer", help="Observer peer ID"),
+    observed: Optional[str] = typer.Option(None, "--observed", help="Observed peer ID"),
+    top_k: int = typer.Option(10, help="Max results"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    peer: Optional[str] = typer.Option(None, "--peer", "-p", help="Override peer ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Semantic search over conclusions."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, peer=peer)
+    observer = _require_observer(observer)
+    client, config = get_client()
+
+    p = client.peer(observer)
+
+    try:
+        if observed:
+            scope = p.conclusions_of(observed)
+        else:
+            scope = p.conclusions
+
+        results = scope.query(query, top_k=top_k)
+        items = [
+            {
+                "id": c.id,
+                "content": c.content if use_json() else c.content[:200],
+                "workspace_id": config.workspace_id,
+                "observer_id": c.observer_id,
+                "observed_id": c.observed_id,
+                "session_id": c.session_id,
+                "created_at": str(c.created_at),
+            }
+            for c in results
+        ]
+        print_result(items, columns=["id", "content", "workspace_id", "session_id", "created_at"], title=f"Conclusion search: {query}")
+    except Exception as e:
+        _handle_error(e, "conclusion", "search")
+
+
+@app.command()
+def create(
+    content: str = typer.Argument(help="Conclusion content or JSON payload"),
+    observer: Optional[str] = typer.Option(None, "--observer", help="Observer peer ID"),
+    observed: Optional[str] = typer.Option(None, "--observed", help="Observed peer ID"),
+    session_id: Optional[str] = typer.Option(None, "--session", "-s", help="Session context"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    peer: Optional[str] = typer.Option(None, "--peer", "-p", help="Override peer ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Create a conclusion."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, peer=peer, session=session_id)
+    observer = _require_observer(observer)
+    client, config = get_client()
+
+    # If content looks like JSON, try to parse it
+    try:
+        payload = json.loads(content)
+        if isinstance(payload, dict):
+            content = payload.get("content", content)
+    except json.JSONDecodeError:
+        pass
+
+    p = client.peer(observer)
+
+    try:
+        if observed:
+            scope = p.conclusions_of(observed)
+        else:
+            scope = p.conclusions
+
+        params: dict[str, object] = {"content": content}
+        if config.session_id:
+            params["session_id"] = config.session_id
+        results = scope.create([params])
+        result = results[0] if results else None
+        if result is None:
+            print_error("CREATE_FAILED", "Conclusion create returned no results")
+            raise typer.Exit(1)
+        print_result({
+            "id": result.id,
+            "content": result.content,
+            "workspace_id": config.workspace_id,
+            "observer_id": result.observer_id,
+            "observed_id": result.observed_id,
+            "session_id": result.session_id,
+            "created_at": str(result.created_at),
+        })
+    except Exception as e:
+        _handle_error(e, "conclusion", "create")
+
+
+@app.command()
+def delete(
+    conclusion_id: str = typer.Argument(help="Conclusion ID to delete"),
+    observer: Optional[str] = typer.Option(None, "--observer", help="Observer peer ID"),
+    observed: Optional[str] = typer.Option(None, "--observed", help="Observed peer ID"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    peer: Optional[str] = typer.Option(None, "--peer", "-p", help="Override peer ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Delete a conclusion."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, peer=peer)
+    validate_resource_id(conclusion_id, "conclusion")
+    client, config = get_client()
+
+    if not observer:
+        observer = config.peer_id
+    if not observer:
+        print_error("NO_PEER", "Peer required. Pass --peer/-p: honcho conclusion <cmd> -p <peer>")
+        raise typer.Exit(1)
+
+    p = client.peer(observer)
+
+    if not yes:
+        # SDK doesn't expose a get-by-id on ConclusionScope, so we can't
+        # preview content cheaply — don't paginate the list just to
+        # decorate the prompt. Show identifying fields only.
+        if not use_json():
+            typer.echo(
+                f"  id:       {conclusion_id}\n"
+                f"  observer: {observer}\n"
+                f"  observed: {observed or '(self)'}"
+            )
+        typer.confirm(f"Delete conclusion '{conclusion_id}'?", abort=True)
+
+    try:
+        if observed:
+            scope = p.conclusions_of(observed)
+        else:
+            scope = p.conclusions
+
+        scope.delete(conclusion_id)
+        status(f"Conclusion '{conclusion_id}' deleted")
+        print_result({"deleted": conclusion_id})
+    except Exception as e:
+        _handle_error(e, "conclusion", conclusion_id)

honcho_cli/commands/config_cmd.py

@@ -0,0 +1,31 @@
+"""Config inspection command: ``honcho config``.
+
+Writing to ``~/.honcho/config.json`` is done only via ``honcho init``, which
+manages the two CLI-owned keys (``apiKey`` + ``environmentUrl``).
+Workspace / peer / session scoping is per-command via flags / env vars, not
+persisted defaults.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from honcho_cli._help import HonchoTyperGroup
+from honcho_cli.common import handle_cmd_flags
+from honcho_cli.config import CLIConfig
+from honcho_cli.output import print_result
+
+app = typer.Typer(cls=HonchoTyperGroup, help="Inspect CLI configuration.", invoke_without_command=True)
+
+
+@app.callback(invoke_without_command=True)
+def config(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Show current config (api key redacted)."""
+    if ctx.invoked_subcommand is not None:
+        return
+    handle_cmd_flags(json_output=json_output)
+    cfg = CLIConfig.load()
+    print_result(cfg.redacted())

honcho_cli/commands/message.py

@@ -0,0 +1,161 @@
+"""Message commands: list, get, create."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Optional
+
+import typer
+
+from honcho.api_types import MessageCreateParams
+
+from honcho_cli.commands.session import _get_session_id
+from honcho_cli.commands.workspace import _handle_error
+from honcho_cli.output import print_error, print_result, status
+from honcho_cli.validation import validate_resource_id
+
+from honcho_cli._help import HonchoTyperGroup
+from honcho_cli.common import add_common_options, get_client, handle_cmd_flags
+
+app = typer.Typer(cls=HonchoTyperGroup, help="List, create, and get messages within a session.")
+add_common_options(app)
+
+
+@app.command("list")
+def list_messages(
+    session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),
+    last: int = typer.Option(20, "--last", help="Number of recent messages"),
+    reverse: bool = typer.Option(False, "--reverse", help="Show oldest first (default is newest first)"),
+    brief: bool = typer.Option(False, "--brief", help="Show only IDs, peer, token count, and created_at (no content)"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    peer: Optional[str] = typer.Option(None, "--peer", "-p", help="Filter by peer ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """List messages in a session. Scoped to a peer with -p."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, peer=peer, session=session)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+    sess = client.session(sid)
+
+    try:
+        filters = {"peer_id": config.peer_id} if config.peer_id else None
+        # Fetch newest-first so [:last] always gives the most recent N messages,
+        # then flip to oldest-at-top / newest-at-bottom for readable display.
+        # --reverse keeps the raw server order (oldest first, descending in table).
+        msgs = sess.messages(filters=filters, reverse=True).items[:last]
+        if not reverse:
+            msgs = list(reversed(msgs))
+
+        # Detect duplicate content
+        content_hashes: dict[str, list[str]] = {}
+        for m in msgs:
+            h = hashlib.md5(m.content.encode()).hexdigest()
+            content_hashes.setdefault(h, []).append(m.id)
+        dupes = {h: ids for h, ids in content_hashes.items() if len(ids) > 1}
+        if dupes:
+            dupe_count = sum(len(ids) - 1 for ids in dupes.values())
+            status(f"Warning: {dupe_count} duplicate message(s) detected (identical content, different IDs)")
+
+        if brief:
+            items = [
+                {
+                    "id": m.id,
+                    "peer_id": m.peer_id,
+                    "token_count": m.token_count,
+                    "created_at": str(m.created_at),
+                }
+                for m in msgs
+            ]
+            print_result(items, columns=["id", "peer_id", "token_count", "created_at"], title="Messages")
+        else:
+            items = [
+                {
+                    "id": m.id,
+                    "peer_id": m.peer_id,
+                    "content": m.content,
+                    "token_count": m.token_count,
+                    "metadata": m.metadata,
+                    "created_at": str(m.created_at),
+                }
+                for m in msgs
+            ]
+            print_result(items, columns=["id", "peer_id", "content", "created_at"], title="Messages")
+    except Exception as e:
+        _handle_error(e, "message", "list")
+
+
+@app.command("create")
+def create_message(
+    content: str = typer.Argument(help="Message content"),
+    peer_id: str = typer.Option(..., "--peer", "-p", help="Peer ID of the message sender"),
+    metadata: Optional[str] = typer.Option(None, "--metadata", help="JSON metadata to associate with the message"),
+    session_id: Optional[str] = typer.Option(None, "--session", "-s", help="Session ID"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Create a message in a session."""
+    handle_cmd_flags(json_output=json_output, workspace=workspace, session=session_id)
+    sid = _get_session_id(None)
+    validate_resource_id(peer_id, "peer")
+    client, config = get_client()
+    sess = client.session(sid)
+
+    parsed_metadata = None
+    if metadata:
+        try:
+            parsed_metadata = json.loads(metadata)
+        except json.JSONDecodeError as e:
+            print_error("INVALID_JSON", f"--metadata must be valid JSON: {e}", {})
+            raise typer.Exit(1)
+
+    try:
+        msgs = sess.add_messages(MessageCreateParams(
+            peer_id=peer_id,
+            content=content,
+            metadata=parsed_metadata,
+        ))
+        msg = msgs[0]
+        print_result({
+            "id": msg.id,
+            "peer_id": msg.peer_id,
+            "content": msg.content,
+            "token_count": msg.token_count,
+            "created_at": str(msg.created_at),
+        })
+    except Exception as e:
+        _handle_error(e, "message", "create")
+
+
+@app.command("get")
+def get_message(
+    message_id: str = typer.Argument(help="Message ID"),
+    session_id: Optional[str] = typer.Option(None, "--session", "-s", help="Session ID"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Get a single message by ID."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace)
+    validate_resource_id(message_id, "message")
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+
+    try:
+        sess = client.session(sid)
+        msg = sess.get_message(message_id)
+
+        print_result({
+            "id": msg.id,
+            "peer_id": msg.peer_id,
+            "content": msg.content,
+            "token_count": msg.token_count,
+            "metadata": msg.metadata,
+            "created_at": str(msg.created_at),
+        })
+    except SystemExit:
+        raise
+    except Exception as e:
+        _handle_error(e, "message", message_id)