Metadata-Version: 2.4
Name: pygubernator
Version: 0.0.2
Summary: General-purpose Python agent framework with pystator integration
Author-email: StatFYI <contact@statfyi.com>
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
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: charter
Requires-Dist: pycharter>=0.1.0; extra == "charter"
Provides-Extra: catalyst
Requires-Dist: pycatalyst>=0.1.0; extra == "catalyst"
Provides-Extra: all
Requires-Dist: pygubernator[catalyst,charter,kafka,llm]; extra == "all"
Provides-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"

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

## 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`.

## Development

```bash
make install-dev
make check
```

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