PyGubernator

General-purpose Python agent framework with pystator integration: lifecycle state machines, LLM agents with tools, pipelines, Kafka/in-memory transport, and batch/stream runners.

Install

pip install pygubernator

Optional extras:

pip install pygubernator[api]       # control plane: FastAPI, DB, Kafka, tracing
pip install pygubernator[ui]          # serve embedded UI (FastAPI + static)
pip install pygubernator[workflow]    # DAG engine, LiteLLM, Google/Slack/Obsidian tools, pycharter/pycatalyst
pip install pygubernator[dev]         # api + ui + workflow + tests/lint
pip install pygubernator[docs]        # MkDocs site (also in [dev])
pip install pygubernator[all]         # api + ui + workflow + collab

Local llama.cpp models: pip install llama-cpp-python (not bundled in an extra).

Quick start

from pygubernator import Message, InMemoryTransport, run_stream
from pygubernator.agents import PipelineAgent
# … define agents and run run_stream / run_batch with a transport

Optional control-plane layers

pygubernator remains stateless at its core. Optional layers can be installed as extras:

pip install "pygubernator[api,ui,workflow]"

• API layer: FastAPI control plane (pygubernator api, optional --host / --port / --no-reload), SQLAlchemy + Alembic, PostgreSQL driver, OpenTelemetry, Kafka client
• Workflow layer: workflow engine, LLM/agent nodes, Google Sheets/Docs, Slack, Obsidian (aiofiles), pycharter/pycatalyst presets
• UI layer: Next.js control plane (pygubernator ui dev|serve|build, same flags as pycharter/pystator: --api-url, --host/--port for serve, --api-url/--port for dev)

Main control-plane routes:

• /api/v1/agents (registry + versions + activation)
• /api/v1/runs (list/detail/control/replay, create runs via POST)
• /api/v1/observability (events/metrics/traces)
• /api/v1/policies (policy assignments/alerts/audit)

Registry-Driven Agents

PyGubernator supports a turnkey workflow where agents registered in the API can be instantiated and executed with automatic observability:

from pygubernator.spec import create_llm_agent_from_version
from pygubernator.runners import run_batch_with_db
from pygubernator.llm._provider import LiteLLMProvider
from pygubernator.db.session import SessionLocal
from pygubernator.db.models import AgentVersion

# Load version from database
db = SessionLocal()
version = db.get(AgentVersion, version_id)

# Create agent from stored metadata
agent = create_llm_agent_from_version(
    version=version,
    llm_provider_factory=lambda m: LiteLLMProvider(model=m or "gpt-4o-mini")
)

# Execute with automatic run lifecycle and event persistence
result = await run_batch_with_db(
    agent=agent,
    transport=transport,
    topic="input",
    db_session_factory=SessionLocal,
    agent_id=version.agent_id,
    agent_version_id=version.id
)

Key features:

• Spec / assembly (pygubernator.spec): Build agents from version-like records (create_llm_agent_from_version)
• Automatic run_id threading: Events automatically correlated to runs
• Convenience helpers: run_stream_with_db / run_batch_with_db manage run lifecycle
• HTTP client: ControlPlaneClient for API operations (optional)
• Tool loading: Tools loaded from version metadata

Full documentation (MkDocs): https://optophi.github.io/pygubernator/ — or locally: pip install -e ".[docs]" then pygubernator docs serve (default http://127.0.0.1:5010).

See Integration guide and Run lifecycle in the repository.

Configuration

Settings can be loaded from environment variables with the prefix PYGUBERNATOR_, for example:

• PYGUBERNATOR_AGENT_ID
• PYGUBERNATOR_LLM_MODEL
• PYGUBERNATOR_KAFKA_BOOTSTRAP_SERVERS
• PYGUBERNATOR_KAFKA_GROUP_ID (default consumer group name: pygubernator)

Use AgentSettings.from_env() to populate AgentSettings.

For control-plane services, pygubernator also supports a pygubernator.cfg file (same style as pycharter/pystator). Resolution order:

1. environment variables
2. ./pygubernator.cfg
3. ~/.pygubernator/pygubernator.cfg
4. project root config (near alembic.ini)

See pygubernator.cfg.example for:

• PYGUBERNATOR_DATABASE_URL
• PYGUBERNATOR_UI_THEME / PYGUBERNATOR_UI_APP_NAME
• PYGUBERNATOR_AUTH_USERS / PYGUBERNATOR_AUTH_JWT_SECRET

Authentication bootstrap:

• Configure initial users in PYGUBERNATOR_AUTH_USERS (env or pygubernator.cfg).
• Set PYGUBERNATOR_AUTH_JWT_SECRET (env or pygubernator.cfg) before using /api/v1/auth/login.
• Use Authorization: Bearer <token> for protected HTTP API routes. The Python ControlPlaneClient can also send an X-API-Token header when constructed with a token (see pygubernator.client).

Documentation (MkDocs)

Same layout as pycharter / pystator: mkdocs.yml at the repo root, sources under docs/, API pages via mkdocstrings.

pip install -e ".[dev]"   # includes [docs]
pygubernator docs serve   # http://127.0.0.1:5010
pygubernator docs build   # output ./site/
make docs                 # mkdocs build via Makefile

Published site: https://optophi.github.io/pygubernator/ (configure GitHub Pages + workflow as needed).

Development

make install-dev
make check

Git: ignored files must not be committed

.gitignore only affects untracked files. If something was committed before it was ignored (or was added with git add -f), Git keeps tracking it until you remove it from the index:

make git-untrack-ignored
# or: ./scripts/git-untrack-ignored.sh
git status   # expect many "deleted" (index-only) paths — working tree unchanged
git commit -m "chore: stop tracking gitignored build/local files"

After that, git add and git commit will not re-add those paths. Keep using pygubernator.cfg.example in the repo; copy to pygubernator.cfg locally (ignored).

Contributing and security

• CONTRIBUTING.md — dev setup, tests, and PRs
• SECURITY.md — reporting vulnerabilities privately
• CODE_OF_CONDUCT.md — community standards

Publishing

Version is managed with setuptools-scm. Prefer GitHub tag pushes (e.g. v0.1.0) and Trusted Publishing to PyPI; see .github/workflows/publish.yml and the Makefile publish / publish-test targets.

Rename note

This package was previously developed as pykairos. The PyPI distribution and import package are now pygubernator. Replace imports (import pygubernator), pip install pygubernator, and migrate environment variables from PYKAIROS_* to PYGUBERNATOR_*. The base exception type is GubernatorError (formerly KairosError).