pi-agent
Python tools for building AI agents and managing LLM deployments.
This repository is an open-source Python reimplementation of core ideas from Pi (JS/TS), starting with a provider-agnostic agent runtime that is composable and SDK-friendly.
Status
Phase 1 and an initial Phase 2 slice are implemented:
- Core typed domain model for messages, content blocks, tools, usage, model config
- Async event stream primitive with terminal-result handling
- Agent loop runtime with turn/tool orchestration and steering/follow-up queues
- Stateful
Agentwrapper with prompt/continue/abort/wait APIs - Provider abstraction (
pi_ai) with registry + runtime adapter - Providers:
- mock provider
- OpenAI Responses provider (with streaming deltas)
- OpenAI Completions-compatible provider (with streaming deltas)
- Strict checks and tests (
ruff,mypy,pytest)
Roadmap details are tracked in PLAN.md.
Requirements
- Python
>=3.11 uv
Install
pip install pi-agent
from pi_agent.agent_core import Agent, Model
Development
uv sync
uv run ruff check .
uv run mypy src tests
uv run pytest -q
Package layout
src/pi_agent/agent_core/
types.py # domain model + event types + runtime protocols
event_stream.py # generic async stream + assistant stream specialization
agent_loop.py # turn execution + tool execution loop
agent.py # high-level agent state wrapper
src/pi_agent/pi_ai/
types.py # provider request + provider protocol
registry.py # provider registry + defaults
runtime.py # stream/complete APIs + Agent adapter
providers/mock.py
providers/openai.py
providers/openai_completions.py
End-to-end example
Run:
uv sync --extra openai
export OPENAI_API_KEY=your_key_here
uv run python examples/agent_e2e.py
This example uses OpenAI (gpt-5-mini), routes calls through pi_ai, invokes a tool, and prints the final assistant response.
Streaming example (OpenAI)
Run:
uv sync --extra openai
export OPENAI_API_KEY=your_key_here
uv run python examples/openai_streaming.py
This example prints streaming delta events (text_delta, and tool-call events when present) from the OpenAI provider.
Build and publish
uv build
uvx twine check dist/*
uv publish
Releases
Tag-based releases use .github/workflows/release.yml and expect:
pyproject.tomlversion matches the tag (vX.Y.Z).- A matching
CHANGELOG.mdsection exists (## [X.Y.Z] - YYYY-MM-DD).
Metadata
Release files for pi-agent 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pi_agent-0.1.0.tar.gz | 24.3 kB | Without provenance | Details for pi_agent-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pi_agent-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pi_agent-0.1.0-py3-none-any.whl |
Total release size: 55.8 kB
Release files / pi_agent-0.1.0.tar.gz
| Download URL | pi_agent-0.1.0.tar.gz |
|---|---|
| Size | 24.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7d12ca4e3d95c6eeb9e3e18ec4ae0c6b015e4c104254a198b2c7248322ba48d1
|
|
BLAKE2b-256 checksum How to use checksums |
afb4afac3e838ffa160bacddaba4cdc544ace2148efff0e3f3ee2509c708836f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / pi_agent-0.1.0-py3-none-any.whl
| Download URL | pi_agent-0.1.0-py3-none-any.whl |
|---|---|
| Size | 31.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
76178ad95c729f574100abadce7b08ce15fd1209df170c55e495eb0f4826aae5
|
|
BLAKE2b-256 checksum How to use checksums |
5ebfd6c4871cd360b71007f00a0cf26bbf2d8330a8e5acb2bf6cc25c643f5ec7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for pi-agent 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.