gravity-cli 0.1.0__tar.gz

gravity_cli-0.1.0/.env.example

@@ -0,0 +1,21 @@
+# Copy to ~/.gravity/.env (Windows: %USERPROFILE%\.gravity\.env) and fill in.
+# Every gravity command loads that file. Never commit the filled-in copy.
+# What each variable does: README.md, "Environment variables".
+
+# --- gravity run / schedule / adapt -------------------------------------
+# Your gateway dev token. Required to run an agent. A local gateway prints
+# one at startup, or uses its LOCAL_DEV_TOKEN.
+GRAVITY_DEV_TOKEN=
+
+# The gateway's MCP endpoint. Leave unset for a local gateway on port 8000.
+# GRAVITY_GATEWAY_URL=https://<hosted gateway host>/mcp
+
+# The model endpoint. Leave unset: it follows the gateway (<gateway>/v1).
+# GRAVITY_LLM_URL=
+
+# --- push / tools / agents / runs / logs / whoami ------------------------
+# The control plane. Leave unset for a local one at http://localhost:3010.
+# GRAVITY_API_URL=https://<control plane host>
+
+# Development only: the control plane's dev token, instead of `gravity login`.
+# GRAVITY_API_TOKEN=

gravity_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call: # release.yml runs the same checks before publishing
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --locked # fails if uv.lock is out of date with pyproject.toml
+      - run: uv run ruff check .
+
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - run: uv sync --locked
+      - name: CLI tests
+        run: uv run pytest
+      - name: gravity-schema tests
+        working-directory: packages/gravity-schema
+        run: uv run pytest
+
+  package:
+    # Build both packages, install them into a clean environment the way a builder
+    # would, and use them: catches files missing from the wheel before PyPI does.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build --all-packages
+      - name: Smoke test the built wheels
+        env:
+          GRAVITY_CONFIG_DIR: ${{ runner.temp }}/gravity-config
+        run: |
+          uv venv "$RUNNER_TEMP/smoke"
+          uv pip install --python "$RUNNER_TEMP/smoke/bin/python" --find-links dist gravity-cli
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/smoke/bin/gravity" --help > /dev/null
+          "$RUNNER_TEMP/smoke/bin/gravity" init smoke-agent
+          "$RUNNER_TEMP/smoke/bin/gravity" validate smoke-agent
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ci-dist
+          path: dist/
+          if-no-files-found: error

gravity_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,110 @@
+name: Release
+
+# Push a tag to release both packages at the same version:
+#   v0.1.0rc1  -> TestPyPI   (any tag containing "rc")
+#   v0.1.0     -> PyPI
+# Publishing uses PyPI trusted publishing: no API token is stored anywhere.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Tag matches both package versions and the schema pin
+        run: |
+          python3 - <<'EOF'
+          import os, sys, tomllib
+          tag = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          cli = tomllib.load(open("pyproject.toml", "rb"))["project"]
+          schema = tomllib.load(open("packages/gravity-schema/pyproject.toml", "rb"))["project"]
+          pin = next(d for d in cli["dependencies"] if d.startswith("gravity-schema"))
+          problems = [
+              f"{name} is {version}, the tag says {tag}"
+              for name, version in [("gravity-cli", cli["version"]), ("gravity-schema", schema["version"])]
+              if version != tag
+          ]
+          if pin != f"gravity-schema=={tag}":
+              problems.append(f"gravity-cli depends on {pin!r}, expected gravity-schema=={tag}")
+          for p in problems:
+              print(f"::error::{p}")
+          sys.exit(1 if problems else 0)
+          EOF
+      - run: uv build --all-packages
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # One job per package: a pending trusted publisher can create only one new project per
+  # login, so each package logs in on its own, under its own environment.
+  testpypi:
+    if: contains(github.ref_name, 'rc')
+    needs: build
+    strategy:
+      matrix:
+        include:
+          - { package: gravity_schema, environment: testpypi-schema }
+          - { package: gravity_cli, environment: testpypi }
+    runs-on: ubuntu-latest
+    environment: ${{ matrix.environment }}
+    permissions:
+      id-token: write # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - run: mkdir upload && mv dist/${{ matrix.package }}-* upload/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: upload/
+
+  pypi:
+    if: ${{ !contains(github.ref_name, 'rc') }}
+    needs: build
+    strategy:
+      matrix:
+        include:
+          - { package: gravity_schema, environment: pypi-schema }
+          - { package: gravity_cli, environment: pypi }
+    runs-on: ubuntu-latest
+    environment: ${{ matrix.environment }}
+    permissions:
+      id-token: write # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - run: mkdir upload && mv dist/${{ matrix.package }}-* upload/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: upload/
+
+  github-release:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY" --generate-notes

gravity_cli-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.gravity/
+.env
+.env.*
+!.env.example

gravity_cli-0.1.0/AGENT_STANDARD.md

@@ -0,0 +1,339 @@
+# Agent submission standard — `contract: v1`
+
+What a valid agent directory looks like, exactly what ships, and which check
+catches which mistake. Follow this and `gravity build` passes, the deploy
+succeeds, and the runtime loads it. Deviate and the failure happens at a stage
+you can't see — after upload, on our infrastructure.
+
+Start from `gravity init <name>`; every template already conforms
+(`minimal`, `structured`, `deepagent`, `chat`).
+
+The manifest rules below are enforced by `python/gravity-schema`, the one
+model shared by the CLI, the runner and the server. Where this document and
+that package disagree, the package wins and this document has a bug.
+
+## 1. Layout
+
+```
+my-agent/
+├── manifest.yaml        required   the contract (§2)
+├── requirements.txt     required   your direct deps — may be empty, must exist
+├── requirements.lock    generated  by `gravity validate`/`build`, for the TARGET platform (§5)
+├── src/                 required   all your code; the entrypoint lives here
+│   └── agent.py                    `graph` is defined here (§3)
+└── tests/               optional   shipped if present
+```
+
+**Only these are bundled.** `gravity build` zips exactly `manifest.yaml`,
+`requirements.txt`, `requirements.lock`, and the contents of `src/` and
+`tests/` (minus `__pycache__`). Anything else — `.venv/`, `build/`, notebooks,
+a `data/` folder — is not shipped, and code that reads it will fail at runtime.
+
+## 2. `manifest.yaml`
+
+```yaml
+contract: v1                      # only value accepted
+name: my-agent                    # lowercase slug, ≤64 chars — appears in URLs
+version: 1.0.0                    # strict semver; bump to republish — a version can't be overwritten
+description: One line.            # ≤500 chars
+
+runtime:
+  framework: langgraph            # only value accepted
+  python: "3.13"                  # 3.10–3.13; the lockfile is compiled for it
+  entrypoint: src/agent.py:graph  # file:object — see §3
+  timeout_seconds: 300            # 10–900
+
+dependencies:
+  lockfile: requirements.lock     # leave as-is
+
+inputs:                           # becomes the consumer's form; arrives as state["inputs"]
+  - name: query                   # the key in state["inputs"]
+    type: text                    # text | textarea | number | boolean | static-dropdown | email | url | date | file
+    label: "What should I do?"    # what the consumer sees
+    required: true
+    # options: [a, b]             # static-dropdown only
+    # accept: [pdf, csv]          # file only — extensions without the dot
+    # default: ...                # never on a file input
+
+permissions:
+  tools:                          # every tool your code calls, by Gravity name (§4), ≤50
+    - example.echo
+  models:
+    tier: standard                # standard | premium
+
+resources:
+  memory_mb: 512                  # 128–4096; a request the platform clamps
+
+triggers:                         # optional — what starts a run
+  manual: true                    # default
+  # schedule:
+  #   cron: "0 9 * * 1"           # 5 fields: digits, * / , - only (no @daily, no MON)
+  #   consumer_can_change: true
+
+approvals:                        # optional — tools that pause the run for the consumer's yes
+  required_for: []                # each must also be in permissions.tools
+
+# state:                          # optional — memory across runs, per consumer
+#   max_kb: 256                   # 1–256; leave out and the agent gets none
+```
+
+**`approvals` is enforced by the gateway.** A listed tool is held until a
+human answers: in `gravity run` you're asked (`Approve? [y/N]`, default no;
+no answer is a no); in the product it's the consumer's approval inbox. Not
+approved, the call returns `APPROVAL_REJECTED` (or `APPROVAL_TIMEOUT` after 4
+minutes) and never runs — handle that and fall back, as `meeting-notes`
+keeps the recap as a draft. Your code can't skip the question: the gateway
+holds the call, not the agent. Hosted, with tools from `gravity.tools()`, the
+run pauses durably instead of holding the call (§8).
+
+`triggers` and `state` are part of the contract so a published agent never
+has to change to use them. `gravity schedule` fires `triggers.schedule` locally, and an agent
+that declares `state` gets `state["memory"]` from its last finished run (saved only when a run
+finishes, never over `max_kb`); hosted, EventBridge fires the schedule and the gateway keeps the memory. An agent
+that nothing can start (`manual: false` with no schedule) is rejected.
+
+`slots` (optional) declares swappable adapters: `slots.<slot>.adapters.<name>: [tools]`, one file
+per adapter at `src/adapters/<slot>/<name>.py`. A run is granted `permissions.tools` plus only the
+picked adapter's tools; the pick arrives as `state["inputs"][<slot>]`. See `BUILDER_GUIDE.md` §9.
+
+The same schema is validated twice — by `gravity validate` on your machine
+and again by the server on push — because an attacker won't use the CLI.
+
+## 3. The entrypoint
+
+`runtime.entrypoint` names a file under `src/` and a module-level object in
+it. The runtime accepts two forms:
+
+```python
+async def graph():                # ✓ recommended — an async factory
+    ...
+    return workflow.compile()
+
+graph = asyncio.run(_build())     # ✓ a graph compiled at import
+graph = _build()                  # ✓ also fine — a coroutine is awaited
+```
+
+**Prefer the factory**, which is what the templates do. The runner calls it
+fresh for every run, on that run's own event loop, after the run's env vars
+are set. Read the env vars *inside* it: helper modules under `src/` are
+imported once and cached, so an env var read at their top level can outlive
+the run it belonged to.
+
+A graph compiled at import also works: the platform imports your module on a
+worker thread precisely so `asyncio.run()` gets its own event loop. If you
+ever see *"asyncio.run() cannot be called from a running event loop,"* the
+runner is too old, not your agent.
+
+**State.** The runtime invokes `graph.astream({"inputs": {...}}, stream_mode="updates")`
+— the keyword is passed only when your `astream` accepts it, so a hand-rolled
+object with a plain `astream(state)` works too (accepting `**kwargs` is the
+safe habit). The dict is the
+dict is the consumer's form answers keyed by `inputs[].name`. Your state
+therefore needs:
+
+```python
+class State(TypedDict):
+    inputs: dict                  # required — the consumer's form answers
+    result: Any                   # required in the FINAL state — what the consumer gets
+    ...                           # anything else is yours
+```
+
+**Result.** When the graph finishes, `state["result"]` is what the platform
+returns to the consumer. Any JSON-serialisable value — a string, a dict. A
+graph that finishes without setting `result` returns nothing.
+
+**Conversation.** Declaring a `messages` key in your state opts the agent
+into conversation: the platform passes the transcript in on every turn and
+stores what comes back. Don't declare it in a one-shot agent — see the
+`chat` template.
+
+Optional convention the platform surfaces if present: `source: "live" | "stub"`
+— whether real tool calls happened or a mock answered.
+
+## 4. Imports, tools, models
+
+**Imports: absolute, rooted at `src/`.** The runtime puts `src/` on
+`sys.path` and loads your entrypoint as a top-level module. So:
+
+```python
+from tools.scoring import score   # ✓  src/tools/scoring.py
+from nodes.agent import build     # ✓  src/nodes/agent.py
+from .nodes.agent import build    # ✗  relative imports don't resolve
+from src.nodes.agent import build # ✗  src/ is the root, not a package
+```
+
+`gravity run` loads the same way, so a local run is a faithful preview.
+
+**Tools** come only through the gateway, over MCP, and only the ones in
+`permissions.tools`:
+
+```python
+client = MultiServerMCPClient({"gravity": {
+    "transport": "streamable_http",
+    "url": os.environ["GRAVITY_GATEWAY_URL"],
+    "headers": {"Authorization": f"Bearer {os.environ['GRAVITY_RUN_TOKEN']}"},
+}})
+tools = await client.get_tools()  # exactly permissions.tools, nothing else
+```
+
+Tool names are `<app>.<action>`, lowercase, from `gravity tools` — Gravity's
+names, never a vendor's (`gmail.read`, not `GMAIL_FETCH_EMAILS`). The gateway
+hands them to your model with `_` for `.` (`gmail_read`), because
+OpenAI-family models reject dots in function names. The sandbox allows no
+other egress — `requests.get(...)` to anywhere times out. Declare what you
+need; don't reach around it.
+
+**Models** go through the LLM gateway with the same token:
+
+```python
+model = ChatOpenAI(model="openai/gpt-6-luna",
+                   base_url=os.environ["GRAVITY_LLM_URL"],
+                   api_key=os.environ["GRAVITY_RUN_TOKEN"])
+```
+
+Those three env vars — `GRAVITY_GATEWAY_URL`, `GRAVITY_LLM_URL`,
+`GRAVITY_RUN_TOKEN` — are the entire Gravity surface, plus the `gravity`
+package for tools on the platform (§8). No `OPENAI_API_KEY`: locally and in
+production, models go through the gateway.
+
+## 5. Dependencies
+
+List direct deps in `requirements.txt` with version ranges. `gravity validate`
+compiles `requirements.lock` **for the target** — `aarch64-manylinux2014`,
+Python `runtime.python`, binary wheels only — not for your laptop. The deploy
+installs from the lock and nothing else.
+
+Don't hand-edit the lock. Don't compile it yourself; a native compile on
+Windows or macOS pins the wrong wheels and only fails at deploy.
+
+## 6. Local runs
+
+`gravity run --input k=v` runs your graph in your own venv against a real
+gateway, exactly as production does: tools over `GRAVITY_GATEWAY_URL`,
+models over `GRAVITY_LLM_URL`, both with `GRAVITY_RUN_TOKEN`. You set a
+different token once, `GRAVITY_DEV_TOKEN`, in `~/.gravity/.env`: each run
+trades it for a run token scoped to your `permissions.tools`, so an
+undeclared tool is refused locally exactly as it will be when hosted. Your
+agent only ever sees the run token. `GRAVITY_GATEWAY_URL` defaults to
+`http://127.0.0.1:8000/mcp` and `GRAVITY_LLM_URL` to the same host's `/v1`.
+
+## 7. What's checked where
+
+| Stage | Catches |
+|---|---|
+| `gravity validate` / `build` (local) | manifest schema · entrypoint file + object exist (static) · `requirements.txt` present · lockfile compiles for aarch64 · undeclared network imports (warning) |
+| `gravity push` (server) | manifest re-validated with the same rules · `permissions.tools` all exist in the catalog · version not already published |
+| deploy | every pin in the lock installs on ARM64 |
+| first run | module imports · `graph` resolves to something with `astream()` · state has `inputs` · final state has `result` |
+
+The further right a failure lands, the longer you wait to see it. `build`
+passing means everything in the first column is fine; it does not run your
+code. `gravity run` does.
+
+## 8. On the platform: `import gravity`
+
+Hosted runs are durable: they pause for approvals, survive a lost session,
+and remember the thread between runs. The platform does that around your
+graph. `gravity` is preinstalled in the image; don't put it in
+`requirements.txt`.
+
+**Tools: `await gravity.tools()`** instead of your own `MultiServerMCPClient`.
+The same LangChain tools under the same names (`gmail_read`), from the same env
+vars. Off the platform (`gravity run`, tests) it is exactly the client in §4,
+but only if your venv has it: it stays out of `requirements.txt` and `gravity run`
+doesn't add it, so install it yourself (`uv pip install -e <repo>/code-first/python/gravity-sdk`)
+or `gravity run` fails with `No module named 'gravity'`.
+On the platform, each tool in `approvals.required_for` is wrapped: calling it
+checkpoints the run and stops it until the consumer decides, with no
+connection held open. Approved, the call runs with the arguments the consumer
+saw. Declined, it returns
+`APPROVAL_REJECTED: '<tool>' was not approved, so it did not run`, the same
+text as today, so keep your fallback.
+
+```python
+tools = {t.name: t for t in await gravity.tools()}
+await tools["slack_send"].ainvoke({"channel": cid, "markdown_text": text})
+```
+
+When the run resumes, the node that made the call **runs again from its
+start**: everything before the call happens twice.
+
+- Put a gated call at the end of its own node, after nothing expensive or side-effecting.
+- Several gated calls in one node work, each approved in turn. On each resume the
+  earlier calls are repeated, and the gateway answers a repeat with the stored result
+  instead of doing it again, so each side effect still happens once. Work *between*
+  the calls repeats too, so keep it cheap.
+- Two approvals at once: make them parallel nodes. The consumer sees both together.
+- Any `interrupt()` of your own fails the run with `UNSUPPORTED_INTERRUPT` (for now).
+
+**Persistence is the platform's.** Compile with no checkpointer and no store
+(`workflow.compile()`); the platform injects its own, and one you pass is
+replaced. State is kept per thread. A key the next run doesn't send keeps its
+value (a monitor's `seen`, a draft). For memory shared by one consumer's
+threads, use `langgraph.config.get_store()` (`aget` / `aput` / `asearch` by
+namespace and filter; no semantic search).
+
+**Conversation.** `messages` must use the `add_messages` reducer:
+`messages: Annotated[list, add_messages]`. Each turn the platform sends only
+the new user turn. The history comes from the thread's checkpoint, and a
+plain `list` would replace it with that one message.
+
+**`kind` and `outputs`.**
+
+```yaml
+kind: transform            # transform | interactive (default) | monitor
+outputs:                   # what the consumer may ask the result to become
+  deck:    {renderer: pptx, label: "Pitch deck"}
+  readout: {renderer: docx, label: "Read-out document"}
+  summary: {renderer: markdown, label: "Summary", destinations: [download, gmail.draft, gmail.send]}
+```
+
+- `transform`: all input at the start, the result at the end. The platform
+  delivers it, so the agent needs no write tools.
+- `interactive`: calls tools mid-flow and may converse over several turns.
+- `monitor`: runs on a schedule or a webhook, on one thread, remembering the
+  last run. It needs `triggers.schedule` or a webhook.
+
+`destinations` is where an output may go: `download` (the default),
+`gmail.draft` or `gmail.send`. With `gmail.send` the consumer decides when:
+on the Start or Schedule form, or by asking in chat and confirming. A
+scheduled agent can email every run after that one confirm. The email goes
+to one address, with the output's content in the message body and no
+attachment; a thread sends at most 200 a day. The platform sends it, not the
+agent, so the agent needs no Gmail tool and no approval for it.
+
+Renderers: `markdown`, `docx`, `pptx`, `rows` (the first table, as CSV). Each
+consumer picks outputs and destinations per run. The agent writes one
+**corpus** into its final state, and every output is rendered from it:
+
+```python
+corpus = gravity.Corpus(
+    title="Acme: seed round", subtitle="2026", summary="**Why now**: ...",
+    sections=[gravity.Section(
+        heading="Market", body="markdown", bullets=["..."],
+        facts=[gravity.Fact(label="TAM", value="$18B", source="s1")],   # value: text or a number
+        table=gravity.Table(columns=["Segment", "Teams"], rows=[["Founders", "1.2M"]]),
+        notes="speaker notes / read-out text",
+        sections=[gravity.Section(heading="one level of nesting, same shape")],
+    )],
+    sources=[gravity.Source(id="s1", title="Report", url="https://example.com")],
+)
+return {**corpus.to_state(), "result": {"title": corpus.title}}
+```
+
+A plain dict of the same shape works too. The models catch a typo when the
+corpus is built rather than when it's rendered. Set `result` as well: it's
+what the run returns.
+
+## 9. Checklist
+
+- [ ] `manifest.yaml` with `contract: v1`, every tool you call under `permissions.tools`
+- [ ] `requirements.txt` exists (empty is fine)
+- [ ] `src/agent.py` defines module-level `graph`: an `async def` factory (recommended) or a compiled graph
+- [ ] env vars read inside `graph()`, not at module level
+- [ ] state has `inputs`; final state sets `result`; `messages` only if the agent is conversational, with `add_messages`
+- [ ] tools from `await gravity.tools()`; compiled with no checkpointer; nothing expensive before a gated call (§8)
+- [ ] all imports under `src/` are absolute from `src/`
+- [ ] no direct network calls — tools via the gateway, models via the LLM URL
+- [ ] nothing your code needs lives outside `src/` or `tests/`
+- [ ] `gravity build` passes; `gravity run` produces a `result`