terno-agent 0.1.0__py3-none-any.whl

terno_agent/__init__.py

@@ -0,0 +1,7 @@
+"""terno-agent: a multi-agent CLI that answers questions about your database."""
+
+from terno_agent.agents.orchestrator import Orchestrator as Agent
+from terno_agent.config import Config
+
+__version__ = "0.1.0"
+__all__ = ["Agent", "Config", "__version__"]

terno_agent/__main__.py

@@ -0,0 +1,4 @@
+from terno_agent.cli import main
+
+if __name__ == "__main__":
+    main()

terno_agent/agents/__init__.py

@@ -0,0 +1,6 @@
+from terno_agent.agents.base import AgentRun, BaseAgent
+from terno_agent.agents.coder import CoderAgent
+from terno_agent.agents.database import DatabaseAgent
+from terno_agent.agents.orchestrator import Orchestrator
+
+__all__ = ["AgentRun", "BaseAgent", "CoderAgent", "DatabaseAgent", "Orchestrator"]

terno_agent/agents/base.py

@@ -0,0 +1,123 @@
+"""Agent run loop.
+
+A `BaseAgent` ties together an LLM client, a system prompt, and a set of
+tools. The `run` loop is the standard "think → call tools → think" cycle,
+terminating when the model produces a final assistant message with no tool
+calls (or when a per-agent iteration cap is reached).
+
+The agent emits `AgentEvent`s to an optional ``on_event`` hook: streamed
+text deltas, tool calls, tool results, and turn endings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable
+
+from terno_agent.core.events import (
+    EventHook,
+    IterationStart,
+    TextDelta,
+    ToolCallEvent,
+    ToolResultEvent,
+    TurnEnd,
+)
+from terno_agent.core.exceptions import AgentError, ToolError
+from terno_agent.core.messages import (
+    Message,
+    SystemMessage,
+    ToolCall,
+    ToolResult,
+    ToolResultMessage,
+    UserMessage,
+)
+from terno_agent.core.tool import Tool
+from terno_agent.llm.base import LLMClient
+
+Trace = list[Message]
+
+
+@dataclass(slots=True)
+class AgentRun:
+    answer: str
+    trace: Trace = field(default_factory=list)
+    iterations: int = 0
+
+
+class BaseAgent:
+    name: str = "agent"
+    max_iterations: int = 12
+
+    def __init__(
+        self,
+        llm: LLMClient,
+        system_prompt: str,
+        tools: Iterable[Tool] = (),
+        *,
+        on_event: EventHook | None = None,
+    ) -> None:
+        self.llm = llm
+        self.system_prompt = system_prompt
+        self.tools: dict[str, Tool] = {t.schema.name: t for t in tools}
+        self.on_event = on_event
+
+    def run(self, task: str, *, extra_context: str | None = None) -> AgentRun:
+        system = self.system_prompt
+        if extra_context:
+            system += "\n\n---\n" + extra_context
+
+        messages: Trace = [SystemMessage(system), UserMessage(task)]
+
+        for i in range(1, self.max_iterations + 1):
+            self._emit(IterationStart(agent=self.name, iteration=i))
+
+            def _on_text(text: str) -> None:
+                self._emit(TextDelta(agent=self.name, text=text))
+
+            response = self.llm.complete(
+                messages,
+                tools=[t.schema for t in self.tools.values()],
+                on_text_delta=_on_text,
+            )
+            assistant = response.message
+            messages.append(assistant)
+            self._emit(TurnEnd(agent=self.name, message=assistant))
+
+            if not assistant.tool_calls:
+                return AgentRun(answer=assistant.content, trace=messages, iterations=i)
+
+            results: list[ToolResult] = []
+            for tc in assistant.tool_calls:
+                self._emit(ToolCallEvent(agent=self.name, call=tc))
+                result = self._run_tool_call(tc)
+                self._emit(ToolResultEvent(agent=self.name, result=result))
+                results.append(result)
+
+            messages.append(ToolResultMessage(results=results))
+
+        raise AgentError(
+            f"{self.name} exceeded max_iterations ({self.max_iterations}) without finishing."
+        )
+
+    def _run_tool_call(self, tc: ToolCall) -> ToolResult:
+        tool = self.tools.get(tc.name)
+        if tool is None:
+            return ToolResult(call_id=tc.id, content=f"Unknown tool: {tc.name}", is_error=True)
+        try:
+            output = tool.run(**tc.arguments)
+            return ToolResult(call_id=tc.id, content=output, is_error=False)
+        except ToolError as exc:
+            return ToolResult(call_id=tc.id, content=str(exc), is_error=True)
+        except Exception as exc:  # pragma: no cover - defensive
+            return ToolResult(call_id=tc.id, content=f"Unhandled tool error: {exc}", is_error=True)
+
+    def _emit(self, event) -> None:
+        if self.on_event is None:
+            return
+        try:
+            self.on_event(event)
+        except Exception:
+            pass
+
+
+__all__ = ["AgentRun", "BaseAgent", "EventHook", "Trace"]

terno_agent/agents/coder.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from terno_agent.agents.base import BaseAgent
+from terno_agent.llm.base import LLMClient
+from terno_agent.prompts.coder import CODER_PROMPT
+from terno_agent.sandbox.base import Sandbox
+from terno_agent.tools.code_exec import RunPythonTool
+
+
+class CoderAgent(BaseAgent):
+    name = "coder"
+
+    def __init__(
+        self,
+        llm: LLMClient,
+        sandbox: Sandbox,
+        *,
+        timeout_s: int = 30,
+        on_event=None,
+    ) -> None:
+        tools = [RunPythonTool(sandbox, timeout_s=timeout_s)]
+        super().__init__(llm, CODER_PROMPT, tools, on_event=on_event)

terno_agent/agents/database.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from terno_agent.agents.base import BaseAgent
+from terno_agent.db.connection import Database
+from terno_agent.llm.base import LLMClient
+from terno_agent.prompts.database import DATABASE_PROMPT
+from terno_agent.tools.sql import DescribeTableTool, ListTablesTool, SqlQueryTool
+
+
+class DatabaseAgent(BaseAgent):
+    name = "database"
+
+    def __init__(
+        self,
+        llm: LLMClient,
+        db: Database,
+        *,
+        max_rows: int = 200,
+        read_only: bool = True,
+        on_event=None,
+    ) -> None:
+        tools = [
+            ListTablesTool(db),
+            DescribeTableTool(db),
+            SqlQueryTool(db, max_rows=max_rows, read_only=read_only),
+        ]
+        system = DATABASE_PROMPT + "\n\nDatabase context:\n" + db.schema_overview()
+        super().__init__(llm, system, tools, on_event=on_event)

terno_agent/agents/orchestrator.py

@@ -0,0 +1,149 @@
+"""Orchestrator agent.
+
+The orchestrator is itself a `BaseAgent` whose tools are calls to specialist
+sub-agents. The LLM picks which specialist to invoke; we instantiate
+specialists lazily on the first call so they can share the orchestrator's
+LLM client.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from terno_agent.agents.base import AgentRun, BaseAgent
+from terno_agent.agents.coder import CoderAgent
+from terno_agent.agents.database import DatabaseAgent
+from terno_agent.config import Config
+from terno_agent.core.exceptions import ConfigError, ToolError
+from terno_agent.core.tool import ToolSchema
+from terno_agent.db.connection import Database
+from terno_agent.llm.base import LLMClient
+from terno_agent.llm.factory import create_llm_client
+from terno_agent.prompts.orchestrator import ORCHESTRATOR_PROMPT
+from terno_agent.sandbox.base import Sandbox
+from terno_agent.sandbox.factory import create_sandbox
+
+
+@dataclass
+class _DatabaseDelegateTool:
+    agent: DatabaseAgent
+
+    @property
+    def schema(self) -> ToolSchema:
+        return ToolSchema(
+            name="ask_database_agent",
+            description=(
+                "Delegate a task to the Database specialist. It can introspect "
+                "the schema and run read-only SQL. Returns the specialist's "
+                "natural-language answer."
+            ),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "task": {
+                        "type": "string",
+                        "description": "Self-contained task or question for the DB specialist.",
+                    }
+                },
+                "required": ["task"],
+            },
+        )
+
+    def run(self, **kwargs: Any) -> str:
+        task = kwargs.get("task")
+        if not task:
+            raise ToolError("ask_database_agent requires a 'task' argument.")
+        return self.agent.run(task).answer
+
+
+@dataclass
+class _CoderDelegateTool:
+    agent: CoderAgent
+
+    @property
+    def schema(self) -> ToolSchema:
+        return ToolSchema(
+            name="ask_coder_agent",
+            description=(
+                "Delegate a task to the Coder specialist. It writes Python and "
+                "runs it in a sandbox. Pass any rows it needs to operate on "
+                "via 'input_data' as a JSON/CSV string — it cannot see prior "
+                "tool results."
+            ),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "task": {"type": "string", "description": "What the coder should do."},
+                    "input_data": {
+                        "type": "string",
+                        "description": "Optional data the coder should operate on (JSON/CSV/text).",
+                    },
+                },
+                "required": ["task"],
+            },
+        )
+
+    def run(self, **kwargs: Any) -> str:
+        task = kwargs.get("task")
+        if not task:
+            raise ToolError("ask_coder_agent requires a 'task' argument.")
+        data = kwargs.get("input_data")
+        full = task if not data else f"{task}\n\nInput data:\n{data}"
+        return self.agent.run(full).answer
+
+
+class Orchestrator(BaseAgent):
+    name = "orchestrator"
+    max_iterations = 16
+
+    def __init__(
+        self,
+        llm: LLMClient,
+        *,
+        database: Database,
+        sandbox: Sandbox | None,
+        on_event=None,
+    ) -> None:
+        self.database = database
+        self.sandbox = sandbox
+        self._db_agent = DatabaseAgent(llm, database, on_event=on_event)
+        tools = [_DatabaseDelegateTool(self._db_agent)]
+        if sandbox is not None:
+            self._coder_agent = CoderAgent(llm, sandbox, on_event=on_event)
+            tools.append(_CoderDelegateTool(self._coder_agent))
+        else:
+            self._coder_agent = None
+
+        system = ORCHESTRATOR_PROMPT
+        if sandbox is None:
+            system += "\n\nNote: the coder agent is disabled in this session — answer using SQL only."
+        super().__init__(llm, system, tools, on_event=on_event)
+
+    # ----- Construction helpers -------------------------------------------------
+
+    @classmethod
+    def from_env(cls, on_event=None) -> "Orchestrator":
+        return cls.from_config(Config.from_env(), on_event=on_event)
+
+    @classmethod
+    def from_config(cls, config: Config, *, on_event=None) -> "Orchestrator":
+        if not config.database_url:
+            raise ConfigError("TERNO_DATABASE_URL is required.")
+        llm = create_llm_client(
+            provider=config.llm_provider,
+            model=config.llm_model,
+            api_key=config.llm_api_key,
+        )
+        database = Database(config.database_url)
+        sandbox: Sandbox | None
+        if config.sandbox == "none":
+            sandbox = None
+        else:
+            sandbox = create_sandbox(config.sandbox)
+        return cls(llm, database=database, sandbox=sandbox, on_event=on_event)
+
+    # ----- Convenience ---------------------------------------------------------
+
+    def ask(self, question: str) -> AgentRun:
+        return self.run(question)

terno_agent/cli.py

@@ -0,0 +1,323 @@
+"""argparse-based CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from importlib.metadata import PackageNotFoundError, distribution
+from typing import Sequence
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.text import Text
+
+from terno_agent import __version__
+from terno_agent.agents.orchestrator import Orchestrator
+from terno_agent.config import Config
+from terno_agent.core.events import (
+    AgentEvent,
+    IterationStart,
+    TextDelta,
+    ToolCallEvent,
+    ToolResultEvent,
+    TurnEnd,
+)
+from terno_agent.core.exceptions import TernoError
+
+_PACKAGE_NAME = "terno-agent"
+
+
+def _is_editable_install() -> bool:
+    """Return True for development installs (editable or run-from-source).
+
+    Detection follows PEP 610: a non-editable install from a wheel/PyPI either
+    has no ``direct_url.json`` or has ``dir_info.editable = false``. An
+    editable install always sets ``dir_info.editable = true``. Running from
+    source without ``pip install`` will raise ``PackageNotFoundError``, which
+    we also treat as development mode.
+    """
+    try:
+        dist = distribution(_PACKAGE_NAME)
+    except PackageNotFoundError:
+        return True
+    raw = dist.read_text("direct_url.json")
+    if not raw:
+        return False
+    try:
+        info = json.loads(raw)
+    except json.JSONDecodeError:
+        return False
+    return bool((info.get("dir_info") or {}).get("editable"))
+
+
+_AGENT_COLORS = {
+    "orchestrator": "bold magenta",
+    "database": "bold cyan",
+    "coder": "bold green",
+}
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    try:
+        return args.func(args)
+    except TernoError as exc:
+        Console(stderr=True).print(f"[bold red]error:[/] {exc}")
+        return 2
+    except KeyboardInterrupt:
+        print("\ninterrupted", file=sys.stderr)
+        return 130
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="terno",
+        description="Multi-agent CLI that answers questions about your database.",
+    )
+    p.add_argument("--version", action="version", version=f"terno-agent {__version__}")
+    p.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="Suppress agent activity; print only the final answer.",
+    )
+    sub = p.add_subparsers(dest="command")
+
+    ask = sub.add_parser("ask", help="Ask a single question and exit.")
+    ask.add_argument("question", nargs="+", help="The question to ask.")
+    ask.set_defaults(func=_cmd_ask)
+
+    chat = sub.add_parser("chat", help="Start an interactive REPL.")
+    chat.set_defaults(func=_cmd_chat)
+
+    cfg = sub.add_parser("config", help="Show effective configuration.")
+    cfg.set_defaults(func=_cmd_config)
+
+    return p
+
+
+def _cmd_ask(args: argparse.Namespace) -> int:
+    question = " ".join(args.question)
+    console = Console()
+    renderer = None if args.quiet else AgentRenderer(console)
+    agent = Orchestrator.from_env(on_event=renderer)
+    result = agent.ask(question)
+    if renderer is not None:
+        renderer.finalize()
+    if args.quiet:
+        print(result.answer)
+    return 0
+
+
+def _cmd_chat(args: argparse.Namespace) -> int:
+    console = Console()
+    if not _is_editable_install():
+        Console(stderr=True).print(
+            "[bold red]error:[/] `terno chat` is only available in a development install.\n"
+            "Install from source to use the REPL:\n"
+            "  [bold]pip install -e .[/]   or   [bold]uv tool install --editable .[/]\n"
+            "For published installs, use [bold]terno ask \"...\"[/] instead."
+        )
+        return 2
+    renderer = None if args.quiet else AgentRenderer(console)
+    agent = Orchestrator.from_env(on_event=renderer)
+    console.print("[bold]terno-agent REPL[/] — type 'exit' or Ctrl-D to quit.\n")
+    while True:
+        try:
+            line = input("you> ").strip()
+        except EOFError:
+            print()
+            return 0
+        if not line:
+            continue
+        if line.lower() in {"exit", "quit", ":q"}:
+            return 0
+        try:
+            result = agent.ask(line)
+        except TernoError as exc:
+            console.print(f"[bold red]error:[/] {exc}")
+            continue
+        if renderer is not None:
+            renderer.finalize()
+            renderer.reset()
+        if args.quiet:
+            print(f"terno> {result.answer}\n")
+        else:
+            console.print()
+    return 0
+
+
+def _cmd_config(_args: argparse.Namespace) -> int:
+    print(Config.from_env().display())
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# Event renderer
+# --------------------------------------------------------------------------- #
+
+
+class AgentRenderer:
+    """Render `AgentEvent`s to a rich Console.
+
+    Streams assistant text inline; surrounds tool calls and results with
+    syntax-highlighted panels. Designed to be called from any thread.
+    """
+
+    def __init__(self, console: Console) -> None:
+        self.console = console
+        self._stream_open = False
+        self._current_agent: str | None = None
+
+    # callable as the event hook
+    def __call__(self, event: AgentEvent) -> None:
+        if isinstance(event, IterationStart):
+            return
+        if isinstance(event, TextDelta):
+            self._handle_text(event)
+        elif isinstance(event, ToolCallEvent):
+            self._close_stream()
+            self._render_tool_call(event)
+        elif isinstance(event, ToolResultEvent):
+            self._close_stream()
+            self._render_tool_result(event)
+        elif isinstance(event, TurnEnd):
+            self._close_stream()
+
+    def finalize(self) -> None:
+        self._close_stream()
+
+    def reset(self) -> None:
+        self._current_agent = None
+
+    # ----- streaming text ------------------------------------------------- #
+
+    def _handle_text(self, event: TextDelta) -> None:
+        if not event.text:
+            return
+        if not self._stream_open or self._current_agent != event.agent:
+            self._close_stream()
+            tag = self._agent_tag(event.agent)
+            self.console.print(tag, end=" ", highlight=False)
+            self._stream_open = True
+            self._current_agent = event.agent
+        self.console.print(event.text, end="", highlight=False, markup=False)
+
+    def _close_stream(self) -> None:
+        if self._stream_open:
+            self.console.print()  # newline to end the streaming line
+            self._stream_open = False
+
+    def _agent_tag(self, agent: str) -> Text:
+        style = _AGENT_COLORS.get(agent, "bold white")
+        return Text(f"[{agent}]", style=style)
+
+    # ----- tool call/result panels --------------------------------------- #
+
+    def _render_tool_call(self, event: ToolCallEvent) -> None:
+        call = event.call
+        body = _format_call_body(call.name, call.arguments)
+        title = f"[{event.agent}] → {call.name}"
+        self.console.print(
+            Panel(
+                body,
+                title=title,
+                title_align="left",
+                border_style=_AGENT_COLORS.get(event.agent, "white"),
+                padding=(0, 1),
+            )
+        )
+
+    def _render_tool_result(self, event: ToolResultEvent) -> None:
+        result = event.result
+        body = _format_result_body(result.content)
+        style = "red" if result.is_error else "dim"
+        marker = "✗" if result.is_error else "✓"
+        title = f"[{event.agent}] {marker} result"
+        self.console.print(
+            Panel(body, title=title, title_align="left", border_style=style, padding=(0, 1))
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Tool-call / result formatting helpers
+# --------------------------------------------------------------------------- #
+
+
+def _format_call_body(name: str, args: dict) -> object:
+    """Pick the best rich renderable for the tool's payload."""
+    if name == "sql_query" and isinstance(args.get("sql"), str):
+        return Syntax(args["sql"].strip(), "sql", theme="ansi_dark", word_wrap=True)
+    if name == "run_python" and isinstance(args.get("code"), str):
+        return Syntax(args["code"], "python", theme="ansi_dark", word_wrap=True)
+    if name in {"ask_database_agent", "ask_coder_agent"}:
+        task = args.get("task", "")
+        extra = args.get("input_data")
+        body = Text(task, no_wrap=False)
+        if extra:
+            body.append("\n\ninput_data:\n", style="dim")
+            body.append(_truncate(extra, 800))
+        return body
+    pretty = json.dumps(args, indent=2, default=str)
+    return Syntax(pretty, "json", theme="ansi_dark", word_wrap=True)
+
+
+def _format_result_body(content: str) -> object:
+    text = content.strip()
+    if not text:
+        return Text("(empty)", style="dim italic")
+    try:
+        parsed = json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        return Text(_truncate(text, 4000))
+    if isinstance(parsed, dict) and {"columns", "rows"} <= parsed.keys():
+        return _format_query_result(parsed)
+    pretty = json.dumps(parsed, indent=2, default=str)
+    return Syntax(_truncate(pretty, 4000), "json", theme="ansi_dark", word_wrap=True)
+
+
+def _format_query_result(payload: dict) -> object:
+    from rich.table import Table
+
+    columns: list[str] = payload.get("columns") or []
+    rows: list[list] = payload.get("rows") or []
+    table = Table(show_header=True, header_style="bold cyan", expand=False)
+    for col in columns:
+        table.add_column(str(col))
+    preview = rows[:20]
+    for row in preview:
+        table.add_row(*[_cell(v) for v in row])
+    footer = f"{payload.get('row_count', len(rows))} rows"
+    if payload.get("truncated"):
+        footer += " (truncated)"
+    if len(rows) > len(preview):
+        footer += f" — showing first {len(preview)}"
+    table.caption = footer
+    return table
+
+
+def _cell(value: object) -> str:
+    if value is None:
+        return "—"
+    text = str(value)
+    if len(text) > 80:
+        text = text[:77] + "..."
+    return text
+
+
+def _truncate(text: str, limit: int) -> str:
+    if len(text) <= limit:
+        return text
+    return text[:limit] + f"\n... [truncated {len(text) - limit} chars]"
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())