gravity-cli 0.1.0__py3-none-any.whl

gravity_cli/commands/validate.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import ast
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+from gravity_schema import LOCKFILE_PLATFORM
+from gravity_schema.contract import TOOL_NAME_RE as _TOOL_NAME_RE
+from rich import print as rprint
+
+from ..manifest import ManifestValidationError, load_manifest, render_issues
+
+MANIFEST_FILE = "manifest.yaml"
+
+
+def _uv_bin() -> str | None:
+    """uv on PATH, else the binary the `uv` dependency installed."""
+    found = shutil.which("uv")
+    if found:
+        return found
+    try:
+        from uv import find_uv_bin
+
+        return find_uv_bin()
+    except Exception:  # noqa: BLE001 - no uv at all is a warning, not a crash
+        return None
+
+# The sandbox denies egress except the gateway, so these fail in prod. Flagged, not blocked.
+NETWORK_IMPORTS = {"requests", "urllib3", "socket", "aiohttp", "http.client"}
+
+# Quoted literals shaped like a tool name, from the schema's own pattern.
+TOOL_NAME_RE = re.compile(r"""['"](""" + _TOOL_NAME_RE.pattern.strip("^$") + r""")['"]""")
+
+
+def _check_entrypoint_defines_object(entry_path: Path, entry_object: str) -> list[str]:
+    """Static: parse, never import, and look for a module-level definition of the object."""
+    problems = []
+    if not entry_path.exists():
+        return [f"entrypoint file {entry_path} does not exist"]
+    try:
+        tree = ast.parse(entry_path.read_text(encoding="utf-8"), filename=str(entry_path))
+    except SyntaxError as e:
+        return [f"{entry_path} has a syntax error: {e}"]
+
+    defined_names = set()
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    defined_names.add(target.id)
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            defined_names.add(node.name)
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            defined_names.add(node.target.id)
+
+    if entry_object not in defined_names:
+        problems.append(
+            f"{entry_path} has no module-level `{entry_object}` — "
+            f"check runtime.entrypoint in {MANIFEST_FILE}"
+        )
+    return problems
+
+
+def _check_adapters(project_dir: Path, manifest) -> list[str]:
+    """Declared adapters have files, and adapter files are declared (else they'd run ungranted)."""
+    problems = []
+    for slot, spec in manifest.slots.items():
+        folder = project_dir / "src" / "adapters" / slot
+        on_disk = {f.stem for f in folder.glob("*.py") if f.stem != "__init__"}
+        for name in sorted(set(spec.adapters) - on_disk):
+            problems.append(f"slots.{slot}.adapters.{name}: no file src/adapters/{slot}/{name}.py")
+        for name in sorted(on_disk - set(spec.adapters)):
+            problems.append(
+                f"src/adapters/{slot}/{name}.py is not declared — add `{name}: [<tools>]` "
+                f"under slots.{slot}.adapters in {MANIFEST_FILE} (that grants its tools)"
+            )
+    return problems
+
+
+def _scan_drift(project_dir: Path, declared_tools: list[str]) -> list[str]:
+    warnings = []
+    src_files = list((project_dir).rglob("*.py"))
+    imported_network_libs: set[str] = set()
+    referenced_tool_names: set[str] = set()
+
+    for f in src_files:
+        # Path parts, not a substring: Windows paths use backslashes.
+        if {".venv", "venv", "tests", "__pycache__"} & set(f.parts):
+            continue
+        try:
+            text = f.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+        try:
+            tree = ast.parse(text, filename=str(f))
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Import):
+                    for alias in node.names:
+                        if alias.name in NETWORK_IMPORTS:
+                            imported_network_libs.add(alias.name)
+                elif isinstance(node, ast.ImportFrom) and node.module in NETWORK_IMPORTS:
+                    imported_network_libs.add(node.module)
+        except SyntaxError:
+            continue
+        referenced_tool_names.update(TOOL_NAME_RE.findall(text))
+
+    if imported_network_libs and not declared_tools:
+        warnings.append(
+            f"imports {', '.join(sorted(imported_network_libs))} but permissions.tools is "
+            "empty — the sandbox denies all egress except the gateway, so this will 403/timeout "
+            "in prod. add the tool(s) you need under permissions.tools, or drop the import."
+        )
+
+    undeclared = sorted(referenced_tool_names - set(declared_tools))
+    # Cheap heuristic with false positives: a warning, never a failure.
+    if undeclared:
+        warnings.append(
+            f"found tool-name-shaped string(s) not in permissions.tools: {', '.join(undeclared)} "
+            "— if these are real tool calls, add them under permissions.tools and re-run."
+        )
+    return warnings
+
+
+def validate_command(
+    path: Path = typer.Argument(Path("."), help="Agent folder"),
+):
+    """Local sanity check: manifest, entrypoint, lockfile, adapters, drift scan."""
+    project_dir = path.resolve()
+    manifest_path = project_dir / MANIFEST_FILE
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    try:
+        manifest = load_manifest(manifest_path)
+    except ManifestValidationError as e:
+        render_issues(e)
+        raise typer.Exit(1) from e
+
+    entry_file, entry_object = manifest.entrypoint_parts()
+    errors += _check_entrypoint_defines_object(project_dir / entry_file, entry_object)
+
+    lockfile_path = project_dir / manifest.dependencies.lockfile
+    requirements_path = project_dir / "requirements.txt"
+    if not requirements_path.is_file():
+        errors.append(
+            "no requirements.txt — the deploy installs from the lock compiled from it, "
+            "so it must exist (empty is fine)."
+        )
+    elif uv := _uv_bin():
+        # Resolve for the platform image, not this laptop.
+        result = subprocess.run(
+            [
+                uv, "pip", "compile", "--quiet",
+                "--python-platform", LOCKFILE_PLATFORM,
+                "--python-version", manifest.runtime.python,
+                "--only-binary", ":all:",
+                # Relative: uv writes this command into the lock, so an absolute path
+                # would leak the home dir and change the zip's hash per machine.
+                requirements_path.name, "-o", manifest.dependencies.lockfile,
+            ],
+            cwd=project_dir,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            errors.append(
+                f"`uv pip compile` failed for {LOCKFILE_PLATFORM} / python "
+                f"{manifest.runtime.python}:\n{result.stderr.strip()}\n"
+                "  → every dependency needs a wheel for the platform image; a "
+                "source-only package cannot be built there."
+            )
+        else:
+            rprint(
+                f"[green]✓[/green] {lockfile_path.name} compiled "
+                f"[dim]({LOCKFILE_PLATFORM}, py{manifest.runtime.python})[/dim]"
+            )
+    else:
+        warnings.append("`uv` not found — skipping lockfile compile. install: https://docs.astral.sh/uv/")
+
+    errors += _check_adapters(project_dir, manifest)
+    warnings += _scan_drift(project_dir, sorted(manifest.declared_tools))
+
+    for w in warnings:
+        rprint(f"[yellow]⚠[/yellow]  {w}")
+
+    if errors:
+        for e in errors:
+            rprint(f"[red]✖[/red] {e}")
+        raise typer.Exit(1)
+
+    rprint(f"[green]✓ {manifest.name}@{manifest.version} is valid[/green]")

gravity_cli/config.py

@@ -0,0 +1,91 @@
+"""~/.gravity: config.json (the API URL), .env (loaded on every command), and the
+session, kept in the OS keychain with a 0600 file as the headless fallback."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import stat
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import keyring
+from dotenv import load_dotenv
+
+KEYRING_SERVICE = "gravity-cli"
+
+# GRAVITY_CONFIG_DIR: tests and the platform demo point the CLI at a scratch directory.
+CONFIG_DIR = Path(os.environ.get("GRAVITY_CONFIG_DIR", Path.home() / ".gravity"))
+CONFIG_FILE = CONFIG_DIR / "config.json"
+SESSION_FALLBACK_FILE = CONFIG_DIR / "session.json"
+ENV_FILE = CONFIG_DIR / ".env"
+
+CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+load_dotenv(ENV_FILE)  # no-op if the file doesn't exist yet
+
+# The local control plane; the published CLI needs the production URL.
+DEFAULT_API_URL = "http://localhost:3010"
+
+
+def _read_config() -> dict:
+    try:
+        return json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def api_url() -> str:
+    url = os.environ.get("GRAVITY_API_URL") or _read_config().get("api_url") or DEFAULT_API_URL
+    return str(url).rstrip("/")
+
+
+def set_api_url(url: str) -> None:
+    data = _read_config() | {"api_url": url.rstrip("/")}
+    CONFIG_FILE.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+def first_run() -> bool:
+    """True only the first time gravity runs on this machine."""
+    data = _read_config()
+    if data.get("welcomed"):
+        return False
+    CONFIG_FILE.write_text(json.dumps(data | {"welcomed": True}, indent=2), encoding="utf-8")
+    return True
+
+
+@dataclass
+class Session:
+    access_token: str
+    refresh_token: str
+
+
+# Keychain calls fail on headless/CI boxes with no backend; the 0600 file covers those.
+def save_session(session: Session) -> None:
+    payload = json.dumps(asdict(session))
+    with contextlib.suppress(Exception):
+        keyring.set_password(KEYRING_SERVICE, "session", payload)
+        return
+    SESSION_FALLBACK_FILE.write_text(payload, encoding="utf-8")
+    SESSION_FALLBACK_FILE.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+
+def load_session() -> Session | None:
+    payload = None
+    with contextlib.suppress(Exception):
+        payload = keyring.get_password(KEYRING_SERVICE, "session")
+    if payload is None and SESSION_FALLBACK_FILE.exists():
+        payload = SESSION_FALLBACK_FILE.read_text(encoding="utf-8")
+    if not payload:
+        return None
+    try:
+        data = json.loads(payload)
+        return Session(data["access_token"], data["refresh_token"])
+    except (json.JSONDecodeError, KeyError, TypeError):
+        return None
+
+
+def clear_session() -> None:
+    with contextlib.suppress(Exception):
+        keyring.delete_password(KEYRING_SERVICE, "session")
+    SESSION_FALLBACK_FILE.unlink(missing_ok=True)

gravity_cli/manifest.py

@@ -0,0 +1,19 @@
+"""Manifest loading (owned by gravity-schema) and its terminal rendering."""
+
+from __future__ import annotations
+
+from gravity_schema import Manifest, ManifestIssue, ManifestValidationError
+from gravity_schema import load_manifest_file as load_manifest
+from rich import print as rprint
+
+__all__ = ["Manifest", "ManifestIssue", "ManifestValidationError", "load_manifest", "render_issues"]
+
+
+def render_issues(exc: ManifestValidationError) -> None:
+    """Print every issue, so one round fixes them all."""
+    for issue in exc.issues:
+        where = issue.location or "manifest.yaml"
+        rprint(f"[red]✖[/red] [cyan]{where}[/cyan]  [dim]{issue.code.value}[/dim]")
+        rprint(f"   {issue.message}")
+        if issue.remediation:
+            rprint(f"   [yellow]→[/yellow] {issue.remediation}")

gravity_cli/project.py

@@ -0,0 +1,42 @@
+"""Project-directory helpers shared by validate/run/build/push."""
+
+from __future__ import annotations
+
+import hashlib
+import sys
+from pathlib import Path
+
+# Exactly what `gravity build` zips and ships.
+INCLUDE_DIRS = ("src", "tests")
+INCLUDE_FILES = ("manifest.yaml", "requirements.txt", "requirements.lock")
+
+
+def project_files(project_dir: Path) -> list[Path]:
+    """Every bundled file, sorted, so build and push agree byte-for-byte."""
+    files = [project_dir / n for n in INCLUDE_FILES if (project_dir / n).is_file()]
+    for dirname in INCLUDE_DIRS:
+        base = project_dir / dirname
+        if base.is_dir():
+            files += [f for f in base.rglob("*") if f.is_file() and "__pycache__" not in f.parts]
+    return sorted(files)
+
+
+def source_digest(project_dir: Path) -> str:
+    """sha256 of every bundled file's path and bytes; push refuses if it changed since build."""
+    h = hashlib.sha256()
+    for f in project_files(project_dir):
+        h.update(f.relative_to(project_dir).as_posix().encode())
+        h.update(b"\0")
+        h.update(f.read_bytes())
+        h.update(b"\0")
+    return h.hexdigest()
+
+
+def find_python(project_dir: Path) -> str:
+    """The project's .venv python, else the one running gravity-cli."""
+    venv_python = project_dir / ".venv" / (
+        "Scripts/python.exe" if sys.platform == "win32" else "bin/python"
+    )
+    if venv_python.exists():
+        return str(venv_python)
+    return sys.executable

gravity_cli/templates/chat/.gitignore

@@ -0,0 +1,6 @@
+build/
+.venv/
+__pycache__/
+.pytest_cache/
+.gravity/
+.env

gravity_cli/templates/chat/manifest.yaml

@@ -0,0 +1,28 @@
+contract: v1
+name: {{name}}
+version: 1.0.0
+description: "a conversational langgraph agent - keeps the thread, so you can answer its questions and carry on"
+
+runtime:
+  framework: langgraph
+  python: "3.13"
+  entrypoint: src/agent.py:graph
+  timeout_seconds: 300
+
+dependencies:
+  lockfile: requirements.lock
+
+inputs:
+  - name: message
+    type: text
+    label: "Say something"
+    required: true
+
+permissions:
+  tools:
+    - example.echo
+  models:
+    tier: standard
+
+resources:
+  memory_mb: 512

gravity_cli/templates/chat/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/chat/src/agent.py

@@ -0,0 +1,80 @@
+# src/agent.py - the conversational template. State carries `messages`, which the platform
+# fills with the transcript each turn and stores after, so no checkpointer is needed.
+import os
+from typing import Annotated, TypedDict
+
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_openai import ChatOpenAI
+from langgraph.graph import END, StateGraph
+from langgraph.graph.message import add_messages
+from langgraph.prebuilt import create_react_agent
+
+
+class State(TypedDict):
+    inputs: dict
+    # Declaring this key makes the agent conversational.
+    messages: Annotated[list, add_messages]
+    result: str
+
+
+SYSTEM = (
+    "You are a helpful assistant in an ongoing conversation. The user can reply "
+    "and correct you, so read the earlier turns before answering. If a request is "
+    "ambiguous, ask ONE short clarifying question instead of guessing - you will "
+    "get their answer as the next turn."
+)
+
+
+async def _fetch_tools():
+    """Declared tools; none if no gateway is set. A configured gateway that fails raises, never an empty list."""
+    url = os.environ.get("GRAVITY_GATEWAY_URL")
+    if not url:
+        return []
+    client = MultiServerMCPClient(
+        {
+            "gravity": {
+                "transport": "streamable_http",
+                "url": url,
+                "headers": {"Authorization": f"Bearer {os.environ['GRAVITY_RUN_TOKEN']}"},
+            }
+        }
+    )
+    return await client.get_tools()
+
+
+# the object manifest.runtime.entrypoint points at. An async factory the
+# runner calls fresh for every turn - never build the graph at import time.
+async def graph():
+    model = ChatOpenAI(
+        model="openai/gpt-6-luna",
+        base_url=os.environ["GRAVITY_LLM_URL"],
+        api_key=os.environ["GRAVITY_RUN_TOKEN"],
+    )
+    react = create_react_agent(model, await _fetch_tools(), prompt=SYSTEM)
+
+    async def run_agent(state: State):
+        history = list(state.get("messages") or [])
+        if not history:
+            # Nothing in the thread yet (or a platform that does not thread):
+            # fall back to the form input so the agent still works standalone.
+            history = [{"role": "user", "content": state["inputs"].get("message", "")}]
+
+        result = await react.ainvoke({"messages": history})
+
+        # Return only the new turns: add_messages appends, so the full history would duplicate.
+        fresh = result["messages"][len(history):]
+
+        # The last turn with real text and no pending tool call is the answer.
+        answer = ""
+        for m in reversed(fresh):
+            if getattr(m, "content", "") and not getattr(m, "tool_calls", None):
+                answer = m.content
+                break
+
+        return {"messages": fresh, "result": answer}
+
+    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/deepagent/.gitignore

@@ -0,0 +1,6 @@
+build/
+.venv/
+__pycache__/
+.pytest_cache/
+.gravity/
+.env

gravity_cli/templates/deepagent/manifest.yaml

@@ -0,0 +1,28 @@
+contract: v1
+name: {{name}}
+version: 1.0.0
+description: "a deepagents-harness agent, scaffolded by gravity init"
+
+runtime:
+  framework: langgraph        # deepagents compiles to a langgraph graph
+  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
+
+permissions:
+  tools:
+    - example.echo
+  models:
+    tier: standard
+
+resources:
+  memory_mb: 512

gravity_cli/templates/deepagent/requirements.txt

@@ -0,0 +1,4 @@
+langgraph>=1.0,<2.0
+langchain-openai>=1.0,<2.0
+langchain-mcp-adapters>=0.3,<0.4
+deepagents>=0.5,<0.6

gravity_cli/templates/deepagent/src/agent.py

@@ -0,0 +1,54 @@
+# src/agent.py — the deepagents template. Filesystem access is denied below; flip `mode` if needed.
+import os
+from typing import TypedDict
+
+from deepagents import FilesystemPermission, create_deep_agent
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_openai import ChatOpenAI
+from langgraph.graph import END, StateGraph
+
+
+# A one-node wrapper: deepagents' state has no `inputs` or `result`.
+class State(TypedDict):
+    inputs: dict
+    result: str
+
+
+# ← 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():
+    token = os.environ["GRAVITY_RUN_TOKEN"]
+    # The run token is the api key; the llm gateway swaps it for the real one.
+    model = ChatOpenAI(
+        model="openai/gpt-6-luna",
+        base_url=os.environ["GRAVITY_LLM_URL"],
+        api_key=token,
+    )
+    client = MultiServerMCPClient(
+        {
+            "gravity": {
+                "transport": "streamable_http",
+                "url": os.environ["GRAVITY_GATEWAY_URL"],
+                "headers": {"Authorization": f"Bearer {token}"},
+            }
+        }
+    )
+    deep_agent = create_deep_agent(
+        model=model,
+        tools=await client.get_tools(),
+        system_prompt="you help with whatever the user's query asks, using the tools available to you.",
+        permissions=[
+            FilesystemPermission(operations=["read", "write"], paths=["/**"], mode="deny"),
+        ],
+    )
+
+    async def run_agent(state: State):
+        query = state["inputs"].get("query", "")
+        result = await deep_agent.ainvoke({"messages": [{"role": "user", "content": query}]})
+        return {"result": result["messages"][-1].content}
+
+    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/minimal/.gitignore

@@ -0,0 +1,6 @@
+build/
+.venv/
+__pycache__/
+.pytest_cache/
+.gravity/
+.env

gravity_cli/templates/minimal/manifest.yaml

@@ -0,0 +1,30 @@
+contract: v1                 # runtime contract version — never remove
+name: {{name}}
+version: 1.0.0                # bump to republish; published versions are frozen
+description: "a minimal langgraph agent, scaffolded by gravity init"
+
+runtime:
+  framework: langgraph        # v1: langgraph only
+  python: "3.13"
+  entrypoint: src/agent.py:graph   # file:object — the graph the runner invokes
+  timeout_seconds: 300
+
+dependencies:
+  lockfile: requirements.lock # generated by `gravity validate` (uv) — exact pins
+
+# -> rendered as the consumer's form
+inputs:
+  - name: query
+    type: text
+    label: "What should the agent do?"
+    required: true
+
+# -> becomes the scoped run token; the gateway enforces per call
+permissions:
+  tools:
+    - example.echo
+  models:
+    tier: standard             # model cap — no premium-tier burn on this agent
+
+resources:
+  memory_mb: 512                # a request — the platform clamps, never guarantees

gravity_cli/templates/minimal/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/minimal/src/agent.py

@@ -0,0 +1,58 @@
+# src/agent.py — the minimal template. No Gravity import: only three env vars.
+import os
+from typing import TypedDict
+
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_openai import ChatOpenAI
+from langgraph.graph import END, StateGraph
+from langgraph.prebuilt import create_react_agent
+
+
+# Inputs arrive in state["inputs"]; the final `result` is what the consumer gets.
+# No `messages` key: that would make it a chat agent.
+class State(TypedDict):
+    inputs: dict
+    result: str
+
+
+# ← manifest.runtime.entrypoint. An async factory the runner calls per run; building the
+# graph at import breaks inside the runner's event loop.
+async def graph():
+    token = os.environ["GRAVITY_RUN_TOKEN"]
+
+    # models -> gravity's llm gateway: just a base_url. The run token is the
+    # api key; the gateway swaps it for the real one.
+    model = ChatOpenAI(
+        model="openai/gpt-6-luna",
+        base_url=os.environ["GRAVITY_LLM_URL"],
+        api_key=token,
+    )
+
+    # tools -> gravity's gateway over mcp. It only serves what the manifest
+    # declared, so this list is exactly permissions.tools.
+    client = MultiServerMCPClient(
+        {
+            "gravity": {
+                "transport": "streamable_http",
+                "url": os.environ["GRAVITY_GATEWAY_URL"],
+                "headers": {"Authorization": f"Bearer {token}"},
+            }
+        }
+    )
+    tools = await client.get_tools()
+    react = create_react_agent(
+        model,
+        tools,
+        prompt="you help with whatever the user's query asks, using the tools available to you.",
+    )
+
+    async def run_agent(state: State):
+        query = state["inputs"].get("query", "")
+        result = await react.ainvoke({"messages": [{"role": "user", "content": query}]})
+        return {"result": result["messages"][-1].content}
+
+    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/.gitignore

@@ -0,0 +1,6 @@
+build/
+.venv/
+__pycache__/
+.pytest_cache/
+.gravity/
+.env