pygubernator 0.0.5

General-purpose Python agent framework with pystator integration

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[llm]      # LiteLLM provider
pip install pygubernator[kafka]    # Kafka transport
pip install pygubernator[charter]   # pycharter
pip install pygubernator[catalyst]  # pycatalyst
pip install pygubernator[all]

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,db,postgres,ui]"

• API layer: FastAPI control plane (pygubernator api, optional --host / --port / --no-reload)
• Persistence layer: SQLAlchemy models + migrations under src/pygubernator/db/
• 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

See Integration Guide and Run Lifecycle for details.

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 API routes (X-API-Token is not supported).

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).