Metadata-Version: 2.4
Name: pygubernator
Version: 0.0.5
Summary: General-purpose Python agent framework with pystator integration
Author-email: StatFYI <contact@statfyi.com>
License: MIT
Project-URL: Homepage, https://github.com/optophi/pygubernator
Project-URL: Repository, https://github.com/optophi/pygubernator
Project-URL: Issues, https://github.com/optophi/pygubernator/issues
Project-URL: Documentation, https://github.com/optophi/pygubernator#readme
Project-URL: Contributing, https://github.com/optophi/pygubernator/blob/main/CONTRIBUTING.md
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: pystator>=0.0.1
Provides-Extra: kafka
Requires-Dist: confluent-kafka>=2.3.0; extra == "kafka"
Provides-Extra: llm
Requires-Dist: litellm>=1.0.0; extra == "llm"
Provides-Extra: openai-compat
Requires-Dist: httpx>=0.27.0; extra == "openai-compat"
Provides-Extra: local
Requires-Dist: llama-cpp-python>=0.2.0; extra == "local"
Provides-Extra: charter
Requires-Dist: pycharter>=0.1.0; extra == "charter"
Provides-Extra: catalyst
Requires-Dist: pycatalyst>=0.1.0; extra == "catalyst"
Provides-Extra: api
Requires-Dist: fastapi>=0.115.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.30.0; extra == "api"
Requires-Dist: pydantic>=2.8.0; extra == "api"
Requires-Dist: pydantic-settings>=2.3.0; extra == "api"
Requires-Dist: httpx>=0.27.0; extra == "api"
Requires-Dist: PyJWT>=2.9.0; extra == "api"
Requires-Dist: networkx>=3.0; extra == "api"
Provides-Extra: db
Requires-Dist: sqlalchemy>=2.0.32; extra == "db"
Requires-Dist: alembic>=1.13.2; extra == "db"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.9; extra == "postgres"
Provides-Extra: ui
Requires-Dist: fastapi>=0.115.0; extra == "ui"
Requires-Dist: uvicorn[standard]>=0.30.0; extra == "ui"
Requires-Dist: httpx>=0.27.0; extra == "ui"
Requires-Dist: aiofiles>=24.1.0; extra == "ui"
Provides-Extra: observability
Requires-Dist: opentelemetry-api>=1.27.0; extra == "observability"
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "observability"
Provides-Extra: workflow
Requires-Dist: pydantic>=2.8.0; extra == "workflow"
Requires-Dist: jinja2>=3.1.0; extra == "workflow"
Requires-Dist: httpx>=0.27.0; extra == "workflow"
Requires-Dist: networkx>=3.0; extra == "workflow"
Provides-Extra: all
Requires-Dist: pygubernator[api,catalyst,charter,db,kafka,llm,local,observability,openai-compat,postgres,ui,workflow]; extra == "all"
Provides-Extra: dev
Requires-Dist: pygubernator[api,db,llm,observability,postgres,ui]; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.9.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: jupyterlab>=4.2.0; extra == "dev"
Requires-Dist: ipykernel>=6.29.0; extra == "dev"
Dynamic: license-file

# PyGubernator

General-purpose Python **agent** framework with [**pystator**](https://pypi.org/project/pystator/) integration: lifecycle state machines, LLM agents with tools, pipelines, Kafka/in-memory transport, and batch/stream runners.

## Install

```bash
pip install pygubernator
```

Optional extras:

```bash
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

```python
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:

```bash
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:

```python
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](docs/integration-guide.md) and [Run Lifecycle](docs/run-lifecycle.md) 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

```bash
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:

```bash
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](CONTRIBUTING.md) — dev setup, tests, and PRs
- [SECURITY.md](SECURITY.md) — reporting vulnerabilities privately
- [CODE_OF_CONDUCT.md](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`).
