Skip to main content

Python Quickstart

This is the current repo-local quickstart for the Pavri Python SDK.

It verifies the SDK startup path that exists today:

  1. install the SDK from the monorepo
  2. wrap an agent with secure()
  3. inspect the attached runtime, registration, and policy state

The Python SDK transport is still an in-process scaffold in Sprint 2, so this quickstart validates local runtime behavior rather than a live dashboard or store query. The live Python gRPC -> gateway -> ingest export path is deferred; the backend pipeline itself is already verified by the Go service and MVP-stack tests.

Prerequisites​

  • Python 3.12+
  • a clone of this repository

Install The SDK​

cd /path/to/pavri
python -m venv .venv
source .venv/bin/activate
pip install -e sdk/python

Wrap An Agent​

Create quickstart.py:

from pavri import PavriConfig, secure
from pavri.core import get_runtime


class OrdersAgent:
    name = "orders-agent"


agent = OrdersAgent()
agent = secure(
    agent,
    PavriConfig(
        agent_name="orders-agent",
        org_id="org-local",
        session_id="session-local-1",
        plugin="generic",
        environment="development",
        team="platform",
    ),
)

runtime = get_runtime(agent)
assert runtime is not None

print(runtime.status().model_dump(mode="json", exclude_none=True))
print(
    {
        "agent_id": runtime.registration.agent_id,
        "fingerprint": runtime.fingerprint.fingerprint_id,
        "plugin": runtime.descriptor.plugin_name,
        "policy_revision": runtime.registration.welcome_snapshot_revision,
    }
)

Run it:

python quickstart.py

Expected output shape:

{'connected': True, 'agent_id': 'fp_...', 'policy_revision': 1, 'telemetry_buffered': 0, 'plugin_name': 'generic', ...}
{'agent_id': 'fp_...', 'fingerprint': 'fp_...', 'plugin': 'generic', 'policy_revision': 1}

Framework Drafts​

Use explicit plugin hints today:

LangGraph​

from pavri import PavriConfig, secure

graph = build_langgraph_agent()
secure(graph, PavriConfig(agent_name="orders-graph", plugin="langgraph"))

CrewAI​

from pavri import PavriConfig, secure

crew = build_crewai_crew()
secure(crew, PavriConfig(agent_name="ops-crew", plugin="crewai"))

These draft examples cover the current adapter-selection boundary. Full framework callback and middleware guides remain deferred until the live framework component coverage lands.

Backend Pipeline Status​

If you want to run the Sprint 2 backend stack locally, use:

  • docs/runbooks/local-mvp-stack.md
  • services/gateway/README.md
  • services/ingest/README.md
  • services/policy/README.md
  • services/store/README.md

Current boundary:

  • done: Go backend services, gateway forwarding, JetStream publish, ClickHouse persistence, PostgreSQL-backed policy bootstrap/watch
  • done: Python SDK local startup, deterministic fingerprinting, registration scaffold, local policy bootstrap, startup telemetry scaffold
  • deferred: live Python exporter traffic into the Sprint 2 Go backend
  • deferred: dashboard inventory verification, which is scheduled with the dashboard implementation work