gravity-cli 0.1.0__py3-none-any.whl

gravity_cli/templates/structured/manifest.yaml

@@ -0,0 +1,33 @@
+contract: v1
+name: {{name}}
+version: 1.0.0
+description: "a structured langgraph agent, scaffolded by gravity init"
+
+runtime:
+  framework: langgraph
+  python: "3.13"
+  entrypoint: src/agent.py:graph
+  timeout_seconds: 300
+
+dependencies:
+  lockfile: requirements.lock
+
+inputs:
+  - name: query
+    type: text
+    label: "What should the agent do?"
+    required: true
+  - name: tone
+    type: static-dropdown
+    label: "Reply tone"
+    options: [formal, friendly, brief]
+    default: friendly
+
+permissions:
+  tools:
+    - example.echo
+  models:
+    tier: standard
+
+resources:
+  memory_mb: 512

gravity_cli/templates/structured/requirements.txt

@@ -0,0 +1,3 @@
+langgraph>=1.0,<2.0
+langchain-openai>=1.0,<2.0
+langchain-mcp-adapters>=0.3,<0.4

gravity_cli/templates/structured/src/agent.py

@@ -0,0 +1,15 @@
+# src/agent.py — assembles the graph from src/nodes/, state.py and prompts.py.
+from langgraph.graph import END, StateGraph
+from nodes.agent import build_node
+from state import State
+
+
+# ← the object manifest.runtime.entrypoint points at. An async factory the
+# runner calls fresh for every run — never build the graph at import time.
+async def graph():
+    run_agent = await build_node()
+    workflow = StateGraph(State)
+    workflow.add_node("agent", run_agent)
+    workflow.set_entry_point("agent")
+    workflow.add_edge("agent", END)
+    return workflow.compile()

gravity_cli/templates/structured/src/gateway.py

@@ -0,0 +1,26 @@
+"""Model and tool clients in one place. Functions, not module-level clients: env vars are set per run."""
+import os
+
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_openai import ChatOpenAI
+
+
+def make_model() -> ChatOpenAI:
+    # The run token is the api key; the llm gateway swaps it for the real one.
+    return ChatOpenAI(
+        model="openai/gpt-6-luna",
+        base_url=os.environ["GRAVITY_LLM_URL"],
+        api_key=os.environ["GRAVITY_RUN_TOKEN"],
+    )
+
+
+def make_mcp_client() -> MultiServerMCPClient:
+    return MultiServerMCPClient(
+        {
+            "gravity": {
+                "transport": "streamable_http",
+                "url": os.environ["GRAVITY_GATEWAY_URL"],
+                "headers": {"Authorization": f"Bearer {os.environ['GRAVITY_RUN_TOKEN']}"},
+            }
+        }
+    )

gravity_cli/templates/structured/src/nodes/agent.py

@@ -0,0 +1,20 @@
+"""The one node this scaffold ships with. Imports are absolute from src/ (AGENT_STANDARD.md §4)."""
+from gateway import make_mcp_client, make_model
+from langgraph.prebuilt import create_react_agent
+from prompts import SYSTEM_PROMPT
+
+
+async def build_node():
+    tools = await make_mcp_client().get_tools()
+    react = create_react_agent(make_model(), tools, prompt=SYSTEM_PROMPT)
+
+    async def run_agent(state):
+        query = state["inputs"].get("query", "")
+        tone = state["inputs"].get("tone", "friendly")
+        result = await react.ainvoke(
+            {"messages": [{"role": "user", "content": f"[{tone} tone] {query}"}]}
+        )
+        # state["result"] is what the platform returns to the consumer.
+        return {"result": result["messages"][-1].content}
+
+    return run_agent

gravity_cli/templates/structured/src/prompts.py

@@ -0,0 +1,6 @@
+"""Prompts, as their own file — grows naturally as an agent's nodes grow."""
+
+SYSTEM_PROMPT = (
+    "you help with whatever the user's query asks, using the tools "
+    "available to you. match the requested tone."
+)

gravity_cli/templates/structured/src/state.py

@@ -0,0 +1,10 @@
+"""Typed state, in its own module — split out once an agent has more than
+one node worth naming."""
+from typing import TypedDict
+
+
+class State(TypedDict):
+    inputs: dict
+    # No `messages` here on purpose: this agent answers one question per run.
+    # Declaring it is how an agent opts into conversation — see the `chat` template.
+    result: str  # set by the last node; the platform returns it

gravity_cli/timeline.py

@@ -0,0 +1,254 @@
+"""`gravity run`'s live view: the runner's JSON events as a timeline, then a result card."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from rich.console import Console, Group
+from rich.live import Live
+from rich.panel import Panel
+from rich.spinner import Spinner
+from rich.table import Table
+from rich.text import Text
+
+EVENT_PREFIX = "@@gravity "  # must match _runner_script.EVENT_PREFIX
+
+
+@dataclass
+class Row:
+    kind: str  # step | model | tool
+    label: str
+    detail: str = ""
+    ms: int | None = None
+    status: str = "running"  # running | awaiting | ok | refused | failed
+    key: str | None = None  # the tool call's run id, so its end updates its row
+
+
+def _seconds(ms: int | None) -> str:
+    return f"{ms / 1000:.1f}s" if ms is not None else ""
+
+
+def _pick(data: Any, keys=("identifier", "url", "id")) -> str | None:
+    """The most useful reference in a tool's output (an issue key, a URL, an id)."""
+    if isinstance(data, dict):
+        for k in keys:
+            if isinstance(data.get(k), str | int):
+                return str(data[k])
+        for v in data.values():
+            if found := _pick(v, keys):
+                return found
+    elif isinstance(data, list):
+        for v in data:
+            if found := _pick(v, keys):
+                return found
+    return None
+
+
+def _tool_detail(output: str) -> str:
+    try:
+        data = json.loads(output)
+    except (json.JSONDecodeError, TypeError):
+        return ""
+    if isinstance(data, dict) and data.get("successful") is False:
+        return f"error: {data.get('error')}"
+    # A listing reads as how many it found, not as its first item's id.
+    records = _first_records(data)
+    if records is not None and len(records) != 1:
+        return f"{len(records)} found"
+    return _pick(data) or ""
+
+
+def _first_records(data: Any) -> list | None:
+    """The first list of objects in a payload, if it has one."""
+    if isinstance(data, list):
+        return data if data and all(isinstance(i, dict) for i in data) else None
+    if isinstance(data, dict):
+        for v in data.values():
+            if (found := _first_records(v)) is not None:
+                return found
+    return None
+
+
+class Timeline:
+    def __init__(self, console: Console, *, agent: str, run_token: str, tools: list[str]):
+        self.console = console
+        self.rows: list[Row] = []
+        self.gravity_name = {t.replace(".", "_"): t for t in tools}
+        self.outcome: dict | None = None
+        self.shown_from = 0  # rows above this are already on screen, above a prompt
+        short = f"{run_token[:4]}…{run_token[-4:]}" if len(run_token) > 12 else run_token
+        console.print()
+        console.print(
+            f"  [bold]{agent}[/bold] [dim]· run {short} · {len(tools)} "
+            f"tool{'s' if len(tools) != 1 else ''} declared[/dim]\n"
+        )
+
+    # events
+
+    def handle(self, ev: dict) -> None:
+        t = ev.get("type")
+        if t == "step.started":
+            self.rows.append(Row("step", ev["node"]))
+        elif t == "step.finished":
+            for row in reversed(self.rows):
+                if row.kind == "step" and row.label == ev["node"] and row.status == "running":
+                    row.status, row.ms = "ok", ev.get("ms")
+                    break
+        elif t == "model.called":
+            self.rows.append(Row("model", ev.get("model") or "model", ms=ev.get("ms"), status="ok"))
+        elif t == "tool.started":
+            self.rows.append(Row("tool", self._name(ev["tool"]), key=ev.get("id")))
+        elif t in ("tool.called", "tool.failed"):
+            label, detail, status = self._outcome(ev)
+            row = self._row(ev.get("id"))
+            if row is None:
+                self.rows.append(Row("tool", label, detail, ev.get("ms"), status))
+            else:
+                row.label, row.detail, row.ms, row.status = label, detail, ev.get("ms"), status
+        elif t in ("run.finished", "run.failed"):
+            self.outcome = ev
+            for row in self.rows:
+                if row.status == "running":
+                    row.status = "ok" if t == "run.finished" else "failed"
+
+    def _name(self, exposed: str) -> str:
+        return self.gravity_name.get(exposed, exposed)
+
+    def _row(self, key: str | None) -> Row | None:
+        return next((r for r in self.rows if key and r.key == key), None)
+
+    def _outcome(self, ev: dict) -> tuple[str, str, str]:
+        """(label, detail, status) for a finished call; a refusal may arrive as an exception or as output."""
+        name = self._name(ev["tool"])
+        text = ev.get("error") if ev["type"] == "tool.failed" else ev.get("output", "")
+        text = text or ""
+        if "TOOL_NOT_DECLARED" in text:
+            # Never declared, so not in our name map; the refusal names it.
+            named = re.search(r"'([a-z0-9_.]+)' is not in", text)
+            return (named.group(1) if named else name, "refused — not in permissions.tools", "refused")
+        if "APPROVAL_REJECTED" in text:
+            return name, "not approved — did not run", "refused"
+        if "APPROVAL_TIMEOUT" in text:
+            return name, "approval timed out — did not run", "refused"
+        failed = re.search(r"\b(TOOL_UNAVAILABLE|NEEDS_RECONNECT|RUN_NOT_ACTIVE|UNAUTHORIZED)\b", text)
+        if failed:
+            # A gateway error returned as output, not raised: still a failure.
+            return name, text[failed.start():][:80], "failed"
+        if ev["type"] == "tool.failed":
+            return name, text[:80], "failed"
+        detail = _tool_detail(text)
+        return name, detail, "failed" if detail.startswith("error:") else "ok"
+
+    def awaiting(self, key: str | None, summary: str) -> None:
+        """A call the gateway is holding for approval."""
+        row = self._row(key)
+        if row is not None:
+            row.status, row.detail = "awaiting", summary
+
+    def continue_below(self, key: str | None) -> None:
+        """After a prompt, redraw from the paused step, not the whole run."""
+        row = self._row(key)
+        at = self.rows.index(row) if row is not None else len(self.rows)
+        steps = [i for i, r in enumerate(self.rows[:at]) if r.kind == "step"]
+        self.shown_from = steps[-1] if steps else at
+
+    def approved(self, key: str | None) -> None:
+        row = self._row(key)
+        if row is not None:
+            row.status, row.detail = "running", "approved — running"
+
+    # drawing
+
+    def render(self) -> Table:
+        grid = Table.grid(padding=(0, 2))
+        grid.add_column(width=4)
+        grid.add_column(min_width=24)
+        grid.add_column(min_width=18, style="cyan")
+        grid.add_column(justify="right", style="dim")
+        for row in self.rows[self.shown_from:]:
+            indent = "" if row.kind == "step" else "  "
+            if row.kind == "step":
+                icon = Spinner("dots", style="yellow") if row.status == "running" else Text("●", "bold blue")
+                label = Text(row.label, "bold")
+            elif row.kind == "model":
+                icon, label = Text(indent + "◆", "magenta"), Text(row.label, "magenta")
+            else:
+                icon = {
+                    "running": Spinner("dots", style="yellow"),
+                    "awaiting": Text(indent + "⏸", "bold yellow"),
+                    "ok": Text(indent + "✓", "bold green"),
+                    "refused": Text(indent + "✗", "bold red"),
+                    "failed": Text(indent + "✗", "bold red"),
+                }[row.status]
+                label = Text(row.label, "red" if row.status in ("refused", "failed") else "")
+            detail = Text(
+                row.detail,
+                {"refused": "red", "failed": "red", "awaiting": "yellow"}.get(row.status, "cyan"),
+            )
+            grid.add_row(icon, label, detail, _seconds(row.ms))
+        return grid
+
+    def live(self) -> Live:
+        return Live(self.render(), console=self.console, refresh_per_second=12, get_renderable=self.render)
+
+    def finish(self) -> int:
+        """Print the result card and the final line; returns the exit code."""
+        out = self.outcome or {"type": "run.failed", "error": "the runner exited without a result"}
+        # The live view ends mid-line; the first newline closes it.
+        self.console.line(2)
+        if out["type"] == "run.failed":
+            where = "loading the agent" if out.get("stage") == "load" else "the run"
+            self.console.print(
+                Panel(Text(out.get("error", ""), "red"), title=f"[red]failed in {where}", border_style="red")
+            )
+            return 1
+        if not out.get("has_result"):
+            self.console.print(
+                "  [yellow]⚠[/yellow]  the final state has no [bold]result[/bold] — a consumer would "
+                "get nothing (AGENT_STANDARD.md §3)"
+            )
+        else:
+            self.console.print(Panel(_render_value(out.get("result")), title="result", border_style="green", expand=False))
+        self.console.print(f"  [green]✔[/green] done in {_seconds(out.get('ms'))}\n")
+        return 0
+
+
+def _render_value(value: Any):
+    """A result as prose, a key/value list, or a table of records."""
+    if isinstance(value, str) or value is None:
+        return Text(str(value or ""))
+    if isinstance(value, list):
+        return _render_list(value)
+    if not isinstance(value, dict):
+        return Text(json.dumps(value, default=str))
+    parts = []
+    for key, v in value.items():
+        if key == "source":
+            continue
+        if isinstance(v, list) and v:
+            parts += [Text(key, "bold"), _render_list(v)]
+        elif isinstance(v, dict):
+            parts.append(Text.assemble((f"{key}  ", "bold"), json.dumps(v, default=str)[:200]))
+        elif v not in (None, "", []):
+            parts.append(Text.assemble((f"{key}  ", "bold"), str(v)))
+    return Group(*parts)
+
+
+def _render_list(items: list):
+    if all(isinstance(i, dict) for i in items):
+        columns: list[str] = []
+        for item in items:
+            for k, v in item.items():
+                # URLs don't fit a terminal table; the id beside them does.
+                if k not in columns and k != "url" and not isinstance(v, dict | list):
+                    columns.append(k)
+        table = Table(box=None, pad_edge=False, show_edge=False, header_style="dim")
+        for c in columns[:6]:
+            table.add_column(c)
+        for item in items:
+            table.add_row(*(str(item.get(c) if item.get(c) is not None else "") for c in columns[:6]))
+        return table
+    return Text("\n".join(f"• {i}" for i in items))