agentram 0.1.2 → 0.1.5

package/README.md

@@ -53,9 +53,10 @@ If using the Claude plugin, `.mcp.json` sets `AGENTRAM_AUTO_INIT=true`, so these
 
 ## Terminal UI CLI
 
-AgentRAM also includes a dependency-free terminal UI with a Claude Code-like chat frame and button menu:
+AgentRAM includes a terminal UI with Claude-like slash autocomplete. It uses `prompt_toolkit` when installed and falls back to plain `input()` otherwise:
 
 ```bash
+pip install -e ".[tui]"
 agentram
 ```
 
@@ -170,7 +171,7 @@ Run TUI:
 agentram tui
 ```
 
-Supported TUI slash commands:
+Supported TUI slash commands. Plain text only records/retrieves RAM; use `/ask` to call bound models:
 
 ```text
 /help
@@ -385,12 +386,13 @@ agentram_build_coding_orchestration
 agentram_run_coding_orchestration
 ```
 
-TUI slash commands:
+TUI slash commands. Plain text only records/retrieves RAM; use `/ask` to call bound models:
 
 ```text
 /bind-model claude claude-3-5-sonnet-latest role=reviewer api_key_env=ANTHROPIC_API_KEY
 /models
 /orchestrate review CLI orchestration
+/ask xin chào
 ```
 
 Storage:
@@ -844,3 +846,39 @@ Use `.env.example` as the shareable template.
 - Model-based ingestion is best run through daemon/wrapper configuration.
 - Wrapper CLI records command-level events, not deep internal agent tool events.
 - Rich file/tool hooks need direct agent hooks or disciplined MCP calls.
+
+
+### Why TUI May Not Respond Like A Model
+
+Plain text in `agentram tui` records a user message and retrieves RAM context. It does not call paid/local models by default. To get a model response:
+
+1. Put the real API key in an environment variable.
+2. Bind the model using the env var name, not the raw key.
+3. Use `/ask` or `agentram orchestrate --execute`.
+
+Example:
+
+```bash
+set OPENAI_API_KEY=sk-your-key
+agentram tui
+```
+
+Inside TUI:
+
+```text
+/bind-model openai-compatible Agentic --role coder --base-url http://localhost:8000/v1 --api-key-env OPENAI_API_KEY
+/ask xin chào
+```
+
+Do not paste raw API keys into `/bind-model`. `api_key_env` means environment variable name, e.g. `OPENAI_API_KEY`.
+
+
+### Optional Rich TUI
+
+For live slash-command dropdown and command metadata, install the optional TUI extra:
+
+```bash
+pip install agentram[tui]
+```
+
+Without `prompt_toolkit`, AgentRAM still works with basic terminal input; `/` then Enter opens the full slash palette.

package/agentram/cli.py

@@ -18,6 +18,30 @@ SUBAGENTS: dict[str, str] = {
     "documenter": "Update README or usage notes from current implementation. Keep docs concise and runnable.",
 }
 
+SLASH_COMMANDS: list[tuple[str, str]] = [
+    ("/help", "Show commands"),
+    ("/init", "Create .agentram files"),
+    ("/status", "Show RAM status"),
+    ("/retrieve <query>", "Print relevant RAM context"),
+    ("/goal", "Show Goal Stack"),
+    ("/set-goal key=value ...", "Update mission/current_goal/current_task/etc"),
+    ("/drift <task>", "Check goal drift"),
+    ("/events", "Show latest events"),
+    ("/replay", "Replay events into memory"),
+    ("/agents", "List Claude-style subagent presets"),
+    ("/agent <name> <task>", "Build Claude Code subagent prompt"),
+    ("/models", "List bound coding models"),
+    ("/bind-model provider model", "Bind model endpoint"),
+    ("/orchestrate <task>", "Build multi-model agent plan"),
+    ("/ask <prompt>", "Execute bound models and return outputs"),
+    ("/claude-install [path]", "Install .claude commands and agents"),
+    ("/note <text>", "Save decision note"),
+    ("/clear", "Clear chat"),
+    ("/exit", "Quit"),
+    ("Plain text", "Capture coding chat message and retrieve context"),
+]
+
+
 SLASH_HELP = """Slash commands:
 /help                         Show commands
 /init                         Create .agentram files
@@ -33,6 +57,7 @@ SLASH_HELP = """Slash commands:
 /models                       List bound coding models
 /bind-model provider model    Bind model endpoint
 /orchestrate <task>           Build multi-model agent plan
+/ask <prompt>                 Execute bound models and return outputs
 /claude-install [path]        Install .claude commands and agents
 /note <text>                  Save decision note
 /clear                        Clear chat
@@ -150,10 +175,19 @@ def run_command(args: argparse.Namespace) -> int:
 
 def run_tui(context: McpContext) -> None:
     context.init_storage()
-    messages = ["system > AgentRAM coding-agent CLI ready", f"system > RAM root: {context.ram_root}", "system > Type /help, /agent reviewer <task>, or plain coding request."]
+    prompt_session = create_prompt_session()
+    input_hint = "live slash autocomplete enabled" if prompt_session else "basic input fallback; install prompt_toolkit for live slash dropdown"
+    messages = [
+        "system > AgentRAM coding-agent CLI ready",
+        f"system > RAM root: {context.ram_root}",
+        f"system > {input_hint}",
+    ]
     while True:
         draw_screen(context, messages)
-        user_input = input("You > ").strip()
+        try:
+            user_input = read_tui_input(prompt_session).strip()
+        except (EOFError, KeyboardInterrupt):
+            return
         if user_input in {"0", "q", "quit", "exit", "/exit", "/quit"}:
             return
         if user_input in BUTTONS:
@@ -169,9 +203,46 @@ def run_tui(context: McpContext) -> None:
         del messages[:-10]
 
 
+
+def slash_command_names() -> list[str]:
+    return [command.split()[0] for command, _ in SLASH_COMMANDS if command.startswith("/")]
+
+
+def slash_command_meta() -> dict[str, str]:
+    return {command.split()[0]: description for command, description in SLASH_COMMANDS if command.startswith("/")}
+
+
+def create_prompt_session() -> Any | None:
+    try:
+        from prompt_toolkit import PromptSession
+        from prompt_toolkit.completion import WordCompleter
+    except ImportError:
+        return None
+
+    completer = WordCompleter(
+        slash_command_names(),
+        meta_dict=slash_command_meta(),
+        ignore_case=True,
+        sentence=True,
+    )
+    return PromptSession(
+        completer=completer,
+        complete_while_typing=True,
+        reserve_space_for_menu=12,
+        bottom_toolbar="Type / for slash commands · /agents for subagents · /ask to call bound models",
+    )
+
+
+def read_tui_input(prompt_session: Any | None) -> str:
+    if prompt_session is None:
+        return input("You > ")
+    return prompt_session.prompt("You > ")
+
 def handle_chat_input(context: McpContext, text: str, messages: list[str] | None = None) -> str:
     if not text:
         return SLASH_HELP
+    if text == "/":
+        return slash_palette_text()
     if text.startswith("/"):
         return handle_slash_command(context, text, messages)
     call_tool(
@@ -213,15 +284,14 @@ def handle_slash_command(context: McpContext, text: str, messages: list[str] | N
         return models_text(context)
     if command == "/bind-model":
         if len(rest) < 2:
-            return "Usage: /bind-model <provider> <model> [role=coder] [base_url=...] [api_key_env=...] [modalities=text,image]"
-        options = {"provider": rest[0], "model": rest[1]}
-        for item in rest[2:]:
-            if "=" in item:
-                key, value = item.split("=", 1)
-                options[key.replace("-", "_")] = value
-        return bind_model_text(context, options)
+            return "Usage: /bind-model <provider> <model> [--role coder] [--base-url URL] [--api-key-env ENV_NAME]"
+        return bind_model_text(context, parse_bind_model_args(rest))
     if command == "/orchestrate":
-        return orchestrate_text(context, raw_rest, execute=False)
+        execute = "--execute" in rest
+        task = raw_rest.replace("--execute", "").strip()
+        return orchestrate_text(context, task, execute=execute)
+    if command == "/ask":
+        return orchestrate_text(context, raw_rest, execute=True)
     if command == "/agent":
         if not rest:
             return "Usage: /agent <memory|planner|reviewer|documenter> <task>"
@@ -313,8 +383,34 @@ def replay_text(context: McpContext, arguments: dict[str, object]) -> str:
 
 
 def agents_text() -> str:
-    lines = ["Subagent presets:"]
-    lines.extend(f"- {name}: {description}" for name, description in SUBAGENTS.items())
+    rows = [
+        ("agentram-memory", "Memory", "Records durable notes. Never edits code."),
+        ("agentram-planner", "Planner", "Checks Goal Stack and decomposes work."),
+        ("agentram-reviewer", "Reviewer", "Reviews changes, tests, and drift risk."),
+        ("agentram-docs", "Docs", "Updates README and usage docs."),
+    ]
+    lines = ["Claude Code subagents", ""]
+    for name, label, description in rows:
+        lines.append(f"  {name.ljust(22)} {label}")
+        lines.append(f"    {description}")
+    lines.append("")
+    lines.append("Use: /agent reviewer <task>")
+    lines.append("Install: /claude-install .")
+    return "\n".join(lines)
+
+
+def slash_palette_text(filter_text: str = "") -> str:
+    normalized = filter_text.strip().lower().lstrip("/")
+    rows = []
+    for command, description in SLASH_COMMANDS:
+        command_key = command.lower().lstrip("/")
+        if normalized and normalized not in command_key:
+            continue
+        rows.append((command, description))
+    command_width = max([len(command) for command, _ in rows] + [12])
+    lines = ["Slash commands", ""]
+    for command, description in rows:
+        lines.append(f"  {command.ljust(command_width)}  {description}")
     return "\n".join(lines)
 
 
@@ -350,7 +446,32 @@ def models_text(context: McpContext) -> str:
     return "\n".join(lines)
 
 
+def parse_bind_model_args(parts: list[str]) -> dict[str, object]:
+    options: dict[str, object] = {"provider": parts[0], "model": parts[1]}
+    index = 2
+    while index < len(parts):
+        item = parts[index]
+        if item.startswith("--"):
+            key = item[2:].replace("-", "_")
+            if index + 1 < len(parts) and not parts[index + 1].startswith("--"):
+                options[key] = parts[index + 1]
+                index += 2
+            else:
+                options[key] = True
+                index += 1
+        elif "=" in item:
+            key, value = item.split("=", 1)
+            options[key.replace("-", "_")] = value
+            index += 1
+        else:
+            index += 1
+    return options
+
+
 def bind_model_text(context: McpContext, options: dict[str, object]) -> str:
+    api_key_env = str(options.get("api_key_env", ""))
+    if api_key_env.startswith(("sk-", "gsk_", "sk_")):
+        return "Do not paste raw API key into api_key_env. Set env var first, e.g. OPENAI_API_KEY=sk-..., then use api_key_env=OPENAI_API_KEY."
     modalities_value = str(options.get("modalities", "text"))
     arguments = {
         "id": str(options.get("id", "")) or None,
@@ -459,7 +580,7 @@ def draw_screen(context: McpContext, messages: list[str]) -> None:
     left_width = 30
     right_width = width - left_width - 3
     print("+" + "-" * (width - 2) + "+")
-    print(box_text("AgentRAM Code Agent CLI  |  RAM + Claude subagents + slash commands", width))
+    print(box_text("◆ AgentRAM Code  |  RAM + Claude subagents + slash commands", width))
     print("+" + "-" * (width - 2) + "+")
 
     sidebar = sidebar_lines(context)
@@ -470,7 +591,7 @@ def draw_screen(context: McpContext, messages: list[str]) -> None:
         right = chat[index] if index < len(chat) else ""
         print("| " + left[: left_width - 2].ljust(left_width - 2) + "| " + right[: right_width - 2].ljust(right_width - 2) + "|")
     print("+" + "-" * (left_width - 1) + "+" + "-" * (right_width) + "+")
-    print(box_text("Input: plain coding request, /help, /agent reviewer <task>, /claude-install .", width))
+    print(box_text("Input: type / for live dropdown. Enter '/' for full palette. /ask calls models.", width))
     print("+" + "-" * (width - 2) + "+")
 
 
@@ -501,10 +622,11 @@ def sidebar_lines(context: McpContext) -> list[str]:
         "  9 help     0 exit",
         "",
         "CLAUDE",
+        "  / = command palette",
+        "  /agents",
         "  /claude-install .",
         "  /models",
-        "  /bind-model claude <model>",
-        "  /orchestrate <task>",
+        "  /ask <prompt>",
     ]
 
 
@@ -515,7 +637,7 @@ def trim(text: str, limit: int) -> str:
 def menu_lines() -> list[str]:
     return [
         "1=/init 2=/status 3=/retrieve 4=/goal 5=/set-goal 6=/drift 7=/events 8=/replay 9=/help",
-        "Plain text captures coding request. Claude: /claude-install ., /agents, /agent reviewer <task>",
+        "Plain text saves RAM only. Use /ask <prompt> to call bound models.",
     ]
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentram",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Async, model-agnostic Working RAM for coding agents.",
   "license": "MIT",
   "homepage": "https://github.com/trancongnghia/AGENT_RAM#readme",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentram"
-version = "0.1.2"
+version = "0.1.5"
 description = "Async, model-agnostic RAM layer for agentic coding tools."
 readme = "README.md"
 license = "MIT"
@@ -21,6 +21,9 @@ classifiers = [
 requires-python = ">=3.10"
 dependencies = []
 
+[project.optional-dependencies]
+tui = ["prompt_toolkit>=3.0"]
+
 [project.urls]
 Homepage = "https://github.com/your-org/agentram"
 Repository = "https://github.com/your-org/agentram"