learnstat 0.2.0__py3-none-any.whl

learnstat/cli.py

@@ -0,0 +1,338 @@
+"""Command-line interface: ``learnstat`` (guided start), ``setup``, ``profile|check|watch|run|repl|config``."""
+
+from __future__ import annotations
+
+import argparse
+import codeop
+import os
+import sys
+import time
+from pathlib import Path
+
+from .commands import is_command
+from .session import Session, set_session
+
+
+def _confirm(question: str) -> bool:
+    try:
+        return input(f"{question} [y/N] ").strip().lower() in ("y", "yes")
+    except EOFError:
+        return False
+
+
+def _session(args, interactive: bool = True) -> Session:
+    confirm = (lambda q: True) if getattr(args, "yes", False) else (_confirm if interactive else None)
+    s = Session(
+        memory_dir=args.memory_dir,
+        ai=False if args.no_ai else "auto",
+        max_attempts=getattr(args, "max_attempts", 3),
+        auto_fix=not getattr(args, "no_fix", False),
+        confirm=confirm,
+        ai_review=getattr(args, "ai_review", False),
+    )
+    return set_session(s)
+
+
+def cmd_profile(args) -> int:
+    s = _session(args)
+    s.verbose = False
+    df = s.read_csv(args.data, name=args.name) if not args.data.endswith((".xlsx", ".xls")) else s.read_excel(args.data, name=args.name)
+    del df
+    print(s.memory.md_path(s.profile().name).read_text(encoding="utf-8"))
+    return 0
+
+
+def _static_check(s: Session, script: Path, data: list[str]) -> list:
+    code = script.read_text(encoding="utf-8")
+    frames = s.profiles_for_code(code, base_dir=script.parent)
+    for d in data or []:
+        s.verbose = False
+        s.read_csv(d)
+    return s.check(code, show=False, extra_frames=frames)
+
+
+def cmd_check(args) -> int:
+    s = _session(args, interactive=False)
+    found = _static_check(s, Path(args.script), args.data)
+    if not found:
+        print("No suggestions - nothing the rules flag for this data.")
+    for sug in found:
+        print(sug.render())
+        print()
+    return 0
+
+
+def cmd_watch(args) -> int:
+    s = _session(args, interactive=False)
+    script = Path(args.script)
+    print(f"Watching {script} - suggestions appear each time you save. Ctrl+C to stop.")
+    last = None
+    try:
+        while True:
+            mtime = script.stat().st_mtime if script.exists() else None
+            if mtime and mtime != last:
+                last = mtime
+                code = script.read_text(encoding="utf-8")
+                try:
+                    compile(code, str(script), "exec")
+                except SyntaxError as e:
+                    print(f"[{time.strftime('%H:%M:%S')}] SyntaxError line {e.lineno}: {e.msg}")
+                    continue
+                found = _static_check(s, script, args.data)
+                stamp = time.strftime("%H:%M:%S")
+                print(f"[{stamp}] {len(found)} new suggestion(s)")
+                for sug in found:
+                    print(sug.render())
+                    print()
+            time.sleep(args.interval)
+    except KeyboardInterrupt:
+        return 0
+
+
+def cmd_run(args) -> int:
+    s = _session(args)
+    script = Path(args.script)
+    s.ns.update({"__name__": "__main__", "__file__": str(script.resolve())})
+    sys.path.insert(0, str(script.parent.resolve()))
+    for d in args.data or []:
+        s.read_csv(d)
+    code = script.read_text(encoding="utf-8")
+    s.check(code, extra_frames=s.profiles_for_code(code, base_dir=script.parent))
+    result = s.run(code, check=False, filename=str(script))
+    if result.ok and result.changed and args.write_fixed:
+        out = script.with_suffix(".fixed.py")
+        out.write_text(result.final_code, encoding="utf-8")
+        print(f"Corrected copy written to {out} (your original is unchanged).")
+    return 0 if result.ok else 1
+
+
+def cmd_repl(args) -> int:
+    return _repl(_session(args), args.data)
+
+
+def _repl(s: Session, data: str | None) -> int:
+    import numpy as np
+    import pandas as pd
+
+    s.ns.update(pd=pd, np=np)
+    ready = ["pd", "np"]
+    if data:
+        s.ns["df"] = s.read_csv(data)
+        ready.insert(0, "df")
+    print(f"learnstat REPL - AI: {s.ai_status}. Ready: {', '.join(ready)}. Type /help for commands, /ai to change the AI, Ctrl+Z/Ctrl+D to exit.")
+    buffer: list[str] = []
+    while True:
+        try:
+            line = input("... " if buffer else ">>> ")
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return 0
+        if not buffer and is_command(line):
+            print(s.command(line))
+            continue
+        buffer.append(line)
+        src = "\n".join(buffer)
+        try:
+            complete = codeop.compile_command(src, symbol="single") is not None
+        except (SyntaxError, ValueError, OverflowError):
+            complete = True  # let the runner diagnose it
+        if not complete:
+            continue
+        buffer = []
+        result = s.run(src)
+        if result.ok and result.value is not None:
+            print(repr(result.value))
+
+
+def _interactive() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def cmd_config(args) -> int:
+    from . import config
+    from .setup import describe_profile
+
+    action = args.action
+    try:
+        if action == "path":
+            print(config.config_path())
+        elif action == "list":
+            saved, active = config.profiles(), config.active_name()
+            for name, prof in saved.items():
+                print(describe_profile(name, prof, name == active))
+            if not saved:
+                print("No saved AI accounts. Run: learnstat setup")
+        elif action == "show":
+            cfg = config.resolve()
+            stored = config.profiles().get(cfg.profile or "", {})
+            print(f"profile   {cfg.profile or '(none)'}   provider {cfg.provider}")
+            for key in config.KEYS:
+                value = getattr(cfg, key)
+                shown = config.mask(value) if key == "api_key" else value
+                env = config.ENV_VARS[key]
+                source = "env " + env if os.environ.get(env, "").strip() else ("saved" if key in stored else "default")
+                print(f"{key:9} {shown}   [{source}]")
+            print(f"file      {config.config_path()}")
+        elif action in ("use", "remove"):
+            if not args.key:
+                print(f"usage: learnstat config {action} <profile>")
+                return 2
+            path = config.set_active(args.key) if action == "use" else config.remove_profile(args.key)
+            print(f"{action} {args.key} -> {path}")
+        elif action in ("set", "unset"):
+            if not args.key or (action == "set" and args.value is None):
+                print("usage: learnstat config set <api_key|base_url|model> <value>")
+                print("       learnstat config unset <key>")
+                return 2
+            path = config.set_value(args.key, args.value) if action == "set" else config.unset_value(args.key)
+            print(f"{action} {args.key} -> {path}")
+        elif action == "test":
+            from .llm import LLMAssistant
+
+            a = LLMAssistant()
+            if not a.available():
+                print(f"AI not ready: {a.last_error}")
+                return 1
+            print(f"Testing {a.cfg.chat_url} with model {a.model} ...")
+            reply = a.test()
+            if reply is None:
+                print(f"X  {a.last_error}")
+                return 1
+            print(f"OK - {a.cfg.provider_name} / {a.model} replied: {reply[:80]}")
+    except KeyError as e:
+        print(e.args[0])
+        return 2
+    return 0
+
+
+def _ask_data() -> str | None:
+    try:
+        print()
+        path = input("Dataset to load (CSV/Excel path, Enter to skip): ").strip().strip('"')
+    except (EOFError, KeyboardInterrupt):
+        return None
+    if path and not Path(path).exists():
+        print(f"  '{path}' was not found - starting without a dataset.")
+        return None
+    return path or None
+
+
+def _start(args, run_setup: bool) -> int:
+    """The guided start: (optional) AI setup, a quick AI check, then the interactive session."""
+    from . import config
+    from .llm import LLMAssistant
+    from .setup import IO, run_wizard
+
+    if not _interactive():
+        print("learnstat start needs an interactive terminal. Try: learnstat --help")
+        return 2
+    if not args.no_ai:
+        cfg_ready = config.resolve().is_configured
+        if run_setup:
+            run_wizard()
+        elif not cfg_ready and not config.skip_setup():
+            print()
+            print("No AI assistant is set up yet (learnstat also works offline with built-in rules).")
+            try:
+                answer = input("Set one up now? [Y]es / [n]ot now / [never]: ").strip().lower()
+            except (EOFError, KeyboardInterrupt):
+                answer = "n"
+            if answer in ("", "y", "yes"):
+                run_wizard()
+            elif answer == "never":
+                config.set_skip_setup(True)
+        a = LLMAssistant()
+        if a.available():
+            print()
+            print(f"Checking AI: {a.cfg.provider_name} / {a.model} ...", end=" ", flush=True)
+            if a.test(timeout=15) is not None:
+                print("OK")
+            else:
+                print()
+                print(f"X  {a.last_error}")
+                print("   Continuing with offline rules. Type /ai in the session to fix it.")
+    s = _session(args)
+    return _repl(s, args.data or _ask_data())
+
+
+def cmd_setup(args) -> int:
+    if not _interactive():
+        print("learnstat setup is interactive. In scripts use: learnstat config set api_key|base_url|model <value>")
+        return 2
+    from .setup import run_wizard
+
+    run_wizard()
+    from . import config
+    if config.resolve().is_configured:
+        try:
+            print()
+            go = input("Start learnstat now? [Y/n] ").strip().lower() in ("", "y", "yes")
+        except (EOFError, KeyboardInterrupt):
+            go = False
+        if go:
+            return _start(args, run_setup=False)
+    return 0
+
+
+def cmd_start(args) -> int:
+    return _start(args, run_setup=False)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="learnstat", description="AI-assisted learning companion for statistics in Python.")
+    p.add_argument("--memory-dir", default=os.environ.get("LEARNSTAT_MEMORY", ".learnstat"))
+    p.add_argument("--no-ai", action="store_true", help="never call the AI; use offline rules only")
+    p.add_argument("--data", help="dataset to load when starting the interactive session")
+    sub = p.add_subparsers(dest="cmd")
+
+    sp = sub.add_parser("setup", help="guided AI setup: choose company, enter key, pick model, check, then start")
+    sp.add_argument("--data")
+    sp.set_defaults(fn=cmd_setup)
+
+    sp = sub.add_parser("start", help="start the interactive session (also what plain `learnstat` does)")
+    sp.add_argument("--data")
+    sp.set_defaults(fn=cmd_start)
+
+    sp = sub.add_parser("config", help="scripting access to AI settings: list|use|remove|set|unset|show|test|path")
+    sp.add_argument("action", choices=["list", "use", "remove", "set", "unset", "show", "test", "path"])
+    sp.add_argument("key", nargs="?", help="profile name, or api_key / base_url / model")
+    sp.add_argument("value", nargs="?")
+    sp.set_defaults(fn=cmd_config)
+
+    sp = sub.add_parser("profile", help="profile a dataset and write its Markdown memory")
+    sp.add_argument("data")
+    sp.add_argument("--name")
+    sp.set_defaults(fn=cmd_profile)
+
+    for name, fn, help_ in [("check", cmd_check, "suggest improvements for a script without running it"),
+                            ("watch", cmd_watch, "re-check a script every time it is saved")]:
+        sp = sub.add_parser(name, help=help_)
+        sp.add_argument("script")
+        sp.add_argument("--data", action="append", help="dataset file(s) the script analyses")
+        sp.add_argument("--ai-review", action="store_true", help="also ask the AI to review the code")
+        if name == "watch":
+            sp.add_argument("--interval", type=float, default=1.0)
+        sp.set_defaults(fn=fn)
+
+    sp = sub.add_parser("run", help="run a script with suggestions and guarded error recovery")
+    sp.add_argument("script")
+    sp.add_argument("--data", action="append")
+    sp.add_argument("--max-attempts", type=int, default=3)
+    sp.add_argument("--no-fix", action="store_true", help="diagnose errors but never correct them")
+    sp.add_argument("--yes", action="store_true", help="approve side-effecting code and AI corrections without asking")
+    sp.add_argument("--write-fixed", action="store_true", help="write the corrected script to <name>.fixed.py")
+    sp.set_defaults(fn=cmd_run)
+
+    sp = sub.add_parser("repl", help="interactive session with suggestions, recovery and /commands")
+    sp.add_argument("--data")
+    sp.add_argument("--max-attempts", type=int, default=3)
+    sp.set_defaults(fn=cmd_repl)
+
+    args = p.parse_args(argv)
+    if args.cmd is None:
+        return cmd_start(args)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

learnstat/commands.py

@@ -0,0 +1,317 @@
+"""Slash commands that operate on the current analytical context."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable
+
+from .knowledge import Concept, describe_concept, find_topic
+from .suggestions import Suggestion
+
+if TYPE_CHECKING:
+    from .session import Session
+
+HELP = """learnstat commands
+  /describe [id]       explain the reasoning behind the latest (or given) suggestion or error
+  /alternatives [id]   other ways to reach the same analytical goal, with trade-offs
+  /fix                 show the last error diagnosis; retry the failed statement (AI-assisted if available)
+  /learn [topic]       a short lesson on the concept behind the latest suggestion (or a topic)
+  /memory [show|note <text>|decide <text>|refresh]
+                       view or update the dataset's persistent Markdown profile
+  /suggestions         list suggestions from this session
+  /accept [id]         accept a suggestion (records the decision; offers the code - you paste/run it)
+  /reject [id] [why]   keep your approach (the decision is recorded so it is not suggested again)
+  /review              ask the AI to review the last code for issues the rules may miss
+  /ask <question>      ask a question about your data or code (AI)
+  /ai [list|use <name>]  choose the AI company, key and model (guided), or switch saved accounts
+  /status              show AI status and loaded datasets
+  /help                this help"""
+
+
+def _split(text: str) -> tuple[str, str]:
+    text = text.strip()
+    if not text.startswith("/"):
+        return "", text
+    head, _, rest = text[1:].partition(" ")
+    return head.lower(), rest.strip()
+
+
+def _parse_id(rest: str) -> tuple[int | None, str]:
+    parts = rest.split(maxsplit=1)
+    if parts and parts[0].lstrip("#").isdigit():
+        return int(parts[0].lstrip("#")), parts[1] if len(parts) > 1 else ""
+    return None, rest
+
+
+def _concept_text(c: Concept, sections: tuple[str, ...]) -> str:
+    out = [c.title, "=" * len(c.title)]
+    if "concept" in sections:
+        out += ["", "The statistical idea:", "  " + c.concept]
+    if "purpose" in sections:
+        out += ["", "What the suggested function does:", "  " + c.purpose]
+    if "when" in sections:
+        out += ["", "When it is appropriate, and when it is not:", "  " + c.appropriate_when]
+    if "alternatives" in sections and c.alternatives:
+        out += ["", "Alternatives:"] + [f"  - {a}" for a in c.alternatives]
+    if "lesson" in sections and c.lesson:
+        out += ["", c.lesson]
+    if c.docs:
+        out += ["", "Docs: " + ", ".join(c.docs)]
+    return "\n".join(out)
+
+
+def _with_ai(session: "Session", kind: str, s: Suggestion, offline: str) -> str:
+    if not session.assistant:
+        return offline
+    text = session.assistant.explain(kind, s.render(), offline, session.profile_markdown(), s.source_code or session.last_code)
+    if text:
+        return text
+    return offline + f"\n\n(AI explanation unavailable: {session.assistant.last_error}; showing the offline explanation.)"
+
+
+def _target(session: "Session", rest: str) -> tuple[Suggestion | None, str]:
+    sid, rest = _parse_id(rest)
+    s = session.history.get(sid)
+    if sid is not None and s is None:
+        return None, f"No suggestion #{sid}. Use /suggestions to list them."
+    return s, rest
+
+
+# ---------------------------------------------------------------------------
+
+
+def cmd_describe(session: "Session", rest: str) -> str:
+    s, err = _target(session, rest)
+    result = session.last_result
+    if s is None and not rest and result and result.attempts:
+        return _describe_error(session)
+    if s is None:
+        return err or "Nothing to describe yet - write some code first, or try /learn <topic>."
+    facts = (
+        f"Suggestion #{s.id}: {s.title}\n\n"
+        f"In your code:  {s.source_code or '(see above)'}\n"
+        f"For your data: {s.problem}\n"
+        f"Suggested:     {s.alternative}\n"
+        f"Reason:        {s.rationale}\n"
+    )
+    c = describe_concept(s.concept)
+    offline = facts + ("\n" + _concept_text(c, ("concept", "purpose", "when")) if c else "")
+    return _with_ai(session, "describe", s, offline)
+
+
+def _describe_error(session: "Session") -> str:
+    r = session.last_result
+    a = r.attempts[-1]
+    d = a.diagnosis
+    out = [
+        f"Last error: {d.exc_type} ({d.label})",
+        f"  Message:     {d.message}",
+        f"  Statement:   {d.statement.strip()}",
+        f"  Cause:       {d.explanation}",
+    ]
+    if a.fix:
+        out.append(f"  Correction:  {a.fix.description} ({'applied' if a.applied else 'not applied'})")
+    out.append(f"  Next step:   {d.next_step}")
+    out.append(
+        "\nlearnstat separates errors into syntax, name, attribute, argument, column, data-quality, "
+        "statistical-method and environment errors. Only mechanical mistakes are corrected automatically; "
+        "data-quality and statistical problems are explained so that you make the decision."
+    )
+    return "\n".join(out)
+
+
+def cmd_alternatives(session: "Session", rest: str) -> str:
+    s, err = _target(session, rest)
+    if s is None:
+        return err or "No suggestion to give alternatives for yet."
+    c = describe_concept(s.concept)
+    offline = (
+        f"Alternatives for suggestion #{s.id} ({s.title}):\n"
+        f"  - {s.alternative}\n" + ("\n".join(f"  - {a}" for a in c.alternatives) if c else "")
+    )
+    return _with_ai(session, "alternatives", s, offline)
+
+
+def cmd_learn(session: "Session", rest: str) -> str:
+    if rest:
+        c = find_topic(rest)
+        if session.assistant:
+            text = session.assistant.ask(
+                f"Teach me about: {rest}. Keep it under 300 words, use my dataset's columns in the examples and end "
+                "with one exercise.", session.profile_markdown(), session.last_code)
+            if text:
+                return text
+        return _concept_text(c, ("concept", "purpose", "when", "alternatives", "lesson")) if c else (
+            f"No offline lesson matches '{rest}'. Topics: pie charts, skewed data, t-test, correlation, "
+            "missing values, categorical plots, dropna, column names, text numbers, histograms."
+        )
+    s = session.history.get()
+    if s is None:
+        return "Nothing to learn from yet. Try /learn <topic>, e.g. /learn correlation."
+    c = describe_concept(s.concept)
+    offline = _concept_text(c, ("concept", "purpose", "when", "alternatives", "lesson")) if c else s.render()
+    return _with_ai(session, "learn", s, offline)
+
+
+def cmd_fix(session: "Session", rest: str) -> str:
+    r = session.last_result
+    if r is None or (r.ok and not r.attempts):
+        return "No failed code in this session."
+    if r.ok:
+        return "The last run was recovered:\n\n" + r.report()
+    report = r.report()
+    if r.stopped_at_line is None:
+        return report
+    if session.confirm is None:
+        return report + "\n\n(/fix can retry the failed statement when running interactively.)"
+    if not session.confirm(f"Retry from line {r.stopped_at_line}" + (" with AI assistance" if session.assistant else "") + "?"):
+        return report
+    retry = session.executor().run(r.final_code, start_line=r.stopped_at_line)
+    retry.original_code = r.original_code
+    session._after_run(r.final_code, retry)
+    return "Retry " + ("succeeded." if retry.ok else "did not succeed - see the next step above.")
+
+
+def cmd_memory(session: "Session", rest: str) -> str:
+    mem = session.dataset_memory()
+    if mem is None:
+        return "No dataset in memory. Load one with learnstat.read_csv(...) (or session.track(df))."
+    sub, _, arg = rest.partition(" ")
+    path = session.memory.md_path(mem.profile.name)
+    if sub in ("", "summary"):
+        p = mem.profile
+        return (
+            f"Dataset '{p.name}' - {p.n_rows} rows x {p.n_cols} columns, profile {p.fingerprint}\n"
+            f"Issues: {len(p.issues)}, decisions recorded: {len(mem.decisions)}, notes: {len(mem.notes)}\n"
+            f"File: {path}\nUse '/memory show' for the full profile."
+        )
+    if sub == "show":
+        return path.read_text(encoding="utf-8") if path.exists() else "(memory file missing - try /memory refresh)"
+    if sub == "note" and arg:
+        session.memory.add_note(mem, arg)
+        return f"Note saved to {path}."
+    if sub == "decide" and arg:
+        session.memory.record_decision(mem, arg)
+        return f"Decision recorded in {path}."
+    if sub == "refresh":
+        for var, obj in session.ns.items():
+            if session._frame_ids.get(id(obj)) == mem.profile.name:
+                session.track(obj, name=mem.profile.name, source=mem.profile.source, force=True)
+                return f"Re-profiled '{mem.profile.name}'."
+        return "The tracked DataFrame is not in the current namespace; reload it to refresh."
+    return "Usage: /memory [show | note <text> | decide <text> | refresh]"
+
+
+def cmd_suggestions(session: "Session", rest: str) -> str:
+    if not session.history.items:
+        return "No suggestions yet."
+    return "\n".join(
+        f"#{s.id} [{s.status}] line {s.line or '-'}: {s.title}" for s in session.history.items
+    )
+
+
+def cmd_accept(session: "Session", rest: str) -> str:
+    sid, _ = _parse_id(rest)
+    s = session.history.get(sid) if sid else session.history.latest_pending()
+    if s is None:
+        return "No pending suggestion to accept."
+    s.status = "accepted"
+    mem = session.dataset_for(s)
+    if mem:
+        session.memory.record_decision(mem, f"Accepted suggestion '{s.title}': {s.alternative}")
+    if s.code and session.on_accept:
+        session.on_accept(s.code)
+        return f"Accepted #{s.id}. The suggested code was placed in a new cell for you to edit and run."
+    return f"Accepted #{s.id}. Your code was not changed - here is the suggested version to adapt:\n\n{s.code or s.alternative}"
+
+
+def cmd_reject(session: "Session", rest: str) -> str:
+    sid, reason = _parse_id(rest)
+    s = session.history.get(sid) if sid else session.history.latest_pending()
+    if s is None:
+        return "No pending suggestion to reject."
+    s.status = "rejected"
+    mem = session.dataset_for(s)
+    if mem:
+        why = f" Reason: {reason}" if reason else ""
+        session.memory.record_decision(mem, f"Kept original approach despite '{s.title}'.{why}")
+    return f"Rejected #{s.id}; your approach stays as written."
+
+
+def cmd_review(session: "Session", rest: str) -> str:
+    if not session.assistant:
+        return f"AI review is {session.ai_status}."
+    if not session.last_code:
+        return "No code to review yet."
+    found = session._ai_review(session.last_code, [s for s in session.history.items])
+    session.history.extend(found)
+    return "\n".join(s.render() for s in found) or "No additional issues found."
+
+
+def cmd_ask(session: "Session", rest: str) -> str:
+    if not rest:
+        return "Usage: /ask <question>"
+    if not session.assistant:
+        return f"/ask needs AI, which is {session.ai_status}. Try /learn {rest}"
+    return session.assistant.ask(rest, session.profile_markdown(), session.last_code) or (
+        f"AI unavailable: {session.assistant.last_error}"
+    )
+
+
+def cmd_ai(session: "Session", rest: str) -> str:
+    from . import config
+    from .setup import describe_profile, run_wizard, use_saved, IO
+
+    sub, _, arg = rest.partition(" ")
+    if sub == "list":
+        saved, active = config.profiles(), config.active_name()
+        return "\n".join(describe_profile(n, p, n == active) for n, p in saved.items()) or "No saved AI accounts. Run /ai to add one."
+    if sub == "use":
+        if arg not in config.profiles():
+            return f"No saved account '{arg}'. Use /ai list."
+        if not use_saved(IO(), arg):
+            return f"Kept the current AI: {session.ai_status}"
+    elif sub in ("", "setup"):
+        run_wizard()
+    else:
+        return "Usage: /ai            guided setup: company -> key -> model -> check\n       /ai list       saved accounts\n       /ai use <name> switch account"
+    session.connect_ai()
+    return f"AI: {session.ai_status}"
+
+
+def cmd_status(session: "Session", rest: str) -> str:
+    names = ", ".join(session.datasets) or "none"
+    return f"AI: {session.ai_status}\nDatasets: {names}\nMemory directory: {session.memory.directory}"
+
+
+COMMANDS: dict[str, Callable[["Session", str], str]] = {
+    "describe": cmd_describe,
+    "alternatives": cmd_alternatives,
+    "alt": cmd_alternatives,
+    "fix": cmd_fix,
+    "learn": cmd_learn,
+    "memory": cmd_memory,
+    "suggestions": cmd_suggestions,
+    "accept": cmd_accept,
+    "reject": cmd_reject,
+    "review": cmd_review,
+    "ask": cmd_ask,
+    "status": cmd_status,
+    "ai": cmd_ai,
+    "help": lambda s, r: HELP,
+}
+
+
+def dispatch(session: "Session", text: str) -> str:
+    name, rest = _split(text)
+    fn = COMMANDS.get(name)
+    if fn is None:
+        return f"Unknown command '/{name}'.\n\n{HELP}"
+    return fn(session, rest)
+
+
+def is_command(text: str) -> bool:
+    name, _ = _split(text)
+    return bool(name) and name in COMMANDS
+
+
+__all__ = ["dispatch", "is_command", "HELP"]