Skip to main content

gravity-schema

The Gravity agent manifest contract: its models, validation, the capability vocabulary and JSON Schema export. It is the one definition the gravity CLI, the agent runner and Gravity's platform share, so a manifest that passes here passes everywhere. If you build agents, use gravity-cli: it depends on this package, in the same version.

pip install gravity-schema

Two contracts

The manifest's contract picks one, and Gravity runs both side by side.

  • v1 (Manifest): the agent names the tools it calls, such as gmail.send. A manifest without contract is v1.
  • v2 (ManifestV2): the agent names capabilities, such as message.list or issue.create. What it reads goes under sources and what it changes under writes, and the person picks the app (Gmail or Outlook, Linear or Jira) when they set it up. That setup is an Instance.

Load and validate a manifest

from gravity_schema import load_manifest_text

manifest = load_manifest_text("""
contract: v2
name: inbox-digest
version: 1.0.0
description: "A morning digest of my inbox"
runtime: {framework: langgraph, python: "3.12", entrypoint: src/agent.py:graph}
dependencies: {lockfile: requirements.lock}
sources:
  inbox: {capability: message.list, label: "Which inbox?", window: 1d}
writes:
  digest: {capability: message.send, label: "Where should the digest go?"}
approvals: {required_for: [message.send]}
""")
manifest.contract               # 'v2'
manifest.capabilities           # frozenset({'message.list', 'message.send'})

load_manifest_file(path) reads a file instead. Both return whichever contract the manifest declares, and raise ManifestValidationError with its ManifestIssues (each a code, location, message and remediation) when it doesn't fit. Unknown fields are rejected, so a typo is reported rather than ignored.

The capability vocabulary (v2)

VOCABULARY holds every capability and which apps serve it.

from gravity_schema import VOCABULARY

VOCABULARY.apps_for("message.list")     # ('gmail', 'instagram', 'microsoft_teams', 'outlook', ...)

A consumer's setup and a run's grant (v2)

from datetime import UTC, datetime
from gravity_schema import Instance, check_instance, grant, run_token_body

setup = Instance.model_validate({
    "agent": "inbox-digest", "version": "1.0.0",
    "sources": {"inbox": {"app": "gmail"}},
    "writes": {"digest": {"app": "gmail"}},
})
check_instance(manifest, setup)          # []: the setup fits (otherwise, what doesn't)
grant(manifest, setup).as_dict()         # exactly what one run may call, and what waits for approval
run_token_body(manifest, setup, now=datetime.now(UTC))   # {'bindings', 'grant', 'approvals'} for a run token

Explain an agent to its users (v2)

These write plain text from the manifest and the setup, with no model involved.

from gravity_schema import capabilities_summary, permissions

capabilities_summary(manifest)
# {'can': ['Read your messages', 'Send a message'], 'cant': [...], 'also': [...]}
permissions(manifest, setup)
# per app: what it reads, what it changes, what asks first, and what it never does

live describes a running setup.

Draw a setup screen (v2)

setup_plan is the screen a consumer sets an agent up on, shortest first: the agent's parts grouped by the app they use, with the apps each group could switch to, then only the places that must be picked. The rest (time ranges, filters, optional parts, more outputs) is under advanced. Pass connections (app → connected) to mark each group.

from gravity_schema import Instance, VOCABULARY, apply_group_change, setup_plan

setup = Instance.model_validate({"agent": "inbox-digest", "version": "1.0.0",
                                 "sources": {"inbox": {"app": "gmail"}}, "writes": {"digest": {"app": "slack"}}})
plan = setup_plan(manifest, setup, connections={"gmail": True})
plan["groups"]    # [{app: 'gmail', connected: True, parts: [sources.inbox], ...}, {app: 'slack', connected: False, ...}]
plan["places"]    # [{app: 'slack', resource: 'channel', says: 'Choose the channel in Slack', ...}]
plan["advanced"]  # {places, windows, filters, inputs, optional, outputs}

# "Switch Slack to Teams": every part of the group moves; the Slack channel means nothing in Teams, so it is cleared
moved, issues = apply_group_change(manifest, setup, "slack", "microsoft_teams")   # issues: a Teams chat to pick

VOCABULARY.place_maker("googlesheets", "spreadsheet")   # "Create a new ...": {within, within_required, columns}
VOCABULARY.place_maker("slack", "channel")              # None: not made from a name
VOCABULARY.mapped_apps_for("message.send")              # ('gmail', 'instagram', 'microsoft_teams', 'outlook', 'slack')

JSON Schema

from gravity_schema import manifest_json_schema

schema = manifest_json_schema()          # one schema covering v1 and v2

Or from the command line, python -m gravity_schema --out manifest.schema.json. Add --check to exit 1 when that file is out of date.

Versions

gravity-schema and gravity-cli are released together, always in the same version. The changes are in the CLI's changelog (gravity changelog).

Metadata

Release files for gravity-schema 0.13.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gravity-schema 0.13.10
File Size Uploaded Provenance Actions
gravity_schema-0.13.10.tar.gz 1.1 MB With provenance Details for gravity_schema-0.13.10.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gravity-schema 0.13.10
File Interpreter ABI Platform Actions
gravity_schema-0.13.10-py3-none-any.whl Python 3 none any Details for gravity_schema-0.13.10-py3-none-any.whl

Total release size: 2.1 MB

Release files / gravity_schema-0.13.10.tar.gz

Download URL gravity_schema-0.13.10.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
1413a99524a6bbdab2ad0150fd31c88f10bb776a2ec4a1c50c5b4adc493b7dfa
BLAKE2b-256 checksum
How to use checksums
34a800160feca06a6c72b94e062e4a51a4ff76f7cd6cfc8a014b64d10bf49e55
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / gravity_schema-0.13.10-py3-none-any.whl

Download URL gravity_schema-0.13.10-py3-none-any.whl
Size 1.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
440cb383b3cc61ee4bbeb99d5b45b8230401ffd346e8155474f4dbdbfd0859e2
BLAKE2b-256 checksum
How to use checksums
55c5503f8fbadffb39fad9e9c1522d292bfa88c6c9ca06efc72bc8d654587c91
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for gravity-schema 0.13.10

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gravity_schema-0.13.10.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.13.10 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page