PenguiFlow

PenguiFlow logo

CI Status PyPI version Docs Benchmarks License

A Python-native runtime for typed, steerable, bounded AI agents — and the deterministic pipelines under them.

PenguiFlow runs async node graphs where every hop validates its data, every run stays inside a budget, and the same core powers both a deterministic data pipeline and a tool-using agent. It is asyncio-only and built on Pydantic v2, with no heavy runtime dependencies.

Why PenguiFlow

Many agent and pipeline frameworks are loosely-typed loops: a node returns the wrong shape and you find out several hops later, a planner runs past its budget with no ceiling, a crash loses the run's state, and approving a risky step means not automating it. PenguiFlow treats those as the framework's responsibility, not yours:

  • Typed at every boundary. Each node validates its input and output against Pydantic models, so malformed data is caught at its source instead of downstream.
  • Bounded by design. Bounded queues apply real backpressure; per-trace deadlines, hop budgets, and cancellation keep loops and fan-outs from running away.
  • Steerable mid-run. Pause for human approval (HITL), inject steering events, and resume — without losing the trajectory so far.
  • Durable and observable. An optional StateStore persists events for audit and recovery; every run carries a trace_id, can stream partial output, and records its trajectory.
  • One runtime for agents and pipelines. The ReactPlanner (JSON-first tool orchestration, parallel fan-out and joins, pause/resume) runs on the exact same typed, bounded core as a plain data flow.

Architecture at a glance

┌─────────────────────────────────────────────────────────────┐
│  Agents      ReactPlanner · ToolNode (MCP / UTCP / HTTP)      │
│              JSON tool loop · HITL pause/resume · fan-out/join│
├─────────────────────────────────────────────────────────────┤
│  Flow        async node graph · bounded queues (backpressure)│
│  runtime     routers · subflows · streaming                  │
├─────────────────────────────────────────────────────────────┤
│  Envelope    Message: trace_id · deadline · hop budget · meta │
│  Reliability per-node retries / timeouts · per-trace cancel   │
├─────────────────────────────────────────────────────────────┤
│  Ops         StateStore (durable events) · metrics / hooks    │
└─────────────────────────────────────────────────────────────┘
     emit()  ──►   typed in/out validated at every node   ──►  fetch()

Concepts at a glance

  • Flow: a directed graph (runtime) you run(), emit() into, and fetch() results from.
  • Node: an async function plus a NodePolicy (validation, retries, timeout).
  • Message (recommended for production): Message(payload=..., headers=Headers(tenant=...), trace_id=...) enabling trace correlation, cancellation, deadlines, and streaming.
  • ReactPlanner (agents): a JSON-first planning loop over your tools, with pause/resume, parallel calls, and trajectory logging.
  • StateStore (optional): durability, audit, and event persistence for distributed, ops-ready deployments.

Install

Requirements: Python 3.11+

pip install penguiflow

Common extras:

pip install "penguiflow[planner]"      # ReactPlanner + ToolNode integrations
pip install "penguiflow[llm]"          # native LLM provider SDKs
pip install "penguiflow[a2a-server]"   # A2A HTTP+JSON server bindings
pip install "penguiflow[a2a-client]"   # A2A client bindings

If you use uv:

uv pip install penguiflow

Quickstart

PenguiFlow has two entry points that share the same runtime: a typed pipeline you wire yourself, and an agent scaffolded from a template.

1) Typed pipeline (runtime)

from __future__ import annotations

import asyncio

from pydantic import BaseModel

from penguiflow import ModelRegistry, Node, NodePolicy, create


class In(BaseModel):
    text: str


class Out(BaseModel):
    upper: str


async def to_upper(msg: In, _ctx) -> Out:
    return Out(upper=msg.text.upper())


async def main() -> None:
    node = Node(to_upper, name="to_upper", policy=NodePolicy(validate="both"))

    registry = ModelRegistry()
    registry.register("to_upper", In, Out)

    flow = create(node.to())
    flow.run(registry=registry)

    await flow.emit(In(text="hello"))
    result: Out = await flow.fetch()
    await flow.stop()

    print(result.upper)


if __name__ == "__main__":
    asyncio.run(main())

2) Agent (ReactPlanner via CLI — fastest path)

uv run penguiflow new my-agent --template react
cd my-agent
uv sync
uv run penguiflow dev --project-root .

Documentation

Suggested starting points (in-repo sources):

Stability, versioning, and public API

PenguiFlow is on the 3.x line and follows SemVer with a documented public API surface — additions are additive, and breaking changes are called out in the changelog.

Contributing, security, and support

License

MIT — see LICENSE.

Project links

Data verified by PyPI on Aug 4, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for sbenvenuto from gravatar.com sbenvenuto

Credits

Author: PenguiFlow Team

GitHub Statistics

Data verified by PyPI on Aug 4, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev docs cli a2a-server a2a-grpc a2a-client planner web llm tools-cli tools-websocket pricing pydantic-ai

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

penguiflow-3.11.2.tar.gz (4.7 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

penguiflow-3.11.2-py3-none-any.whl (4.7 MB view details)

Uploaded Python 3

File details

Details for the file penguiflow-3.11.2.tar.gz.

File metadata

  • Download URL: penguiflow-3.11.2.tar.gz
  • Upload date:
  • Size: 4.7 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for penguiflow-3.11.2.tar.gz
Algorithm Hash digest
SHA256 c9a15f838df9a3b567a947708fdddc21256d1c771aa26871471309f466d34e8f
MD5 dec6d748e2f174b6c77932dc8dc03dec
BLAKE2b-256 13eca806b7cdaf93778f2fad6427cc27da0bf19ac81a8a50da3c6650b1a235dc

See more details on using hashes here.

Provenance

The following attestation bundles were made for penguiflow-3.11.2.tar.gz:

Publisher: ci.yml on hurtener/penguiflow

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file penguiflow-3.11.2-py3-none-any.whl.

File metadata

  • Download URL: penguiflow-3.11.2-py3-none-any.whl
  • Upload date:
  • Size: 4.7 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for penguiflow-3.11.2-py3-none-any.whl
Algorithm Hash digest
SHA256 1b627dcebb669ba91b3314c3daf804a50f245599871853fb655f58dcbb0444c5
MD5 89d8a0d69b63745ee5846666763c1a06
BLAKE2b-256 e661044083f4dc5f30fe4aed1eb9d811a951813789a2c5d178759ea85be151ae

See more details on using hashes here.

Provenance

The following attestation bundles were made for penguiflow-3.11.2-py3-none-any.whl:

Publisher: ci.yml on hurtener/penguiflow

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

3.11.2 This release

2 files

3.11.1

2 files

3.11.0

2 files

Pre-release

3.11.0a8

2 files

Pre-release

3.11.0a6

2 files

Pre-release

3.11.0a5

2 files

Pre-release

3.11.0a4

2 files

3.10.1

2 files

3.10.0

2 files

Pre-release

3.10.0a3

2 files

Pre-release

3.10.0a2

2 files

Pre-release

3.10.0a1

2 files

3.9.0

2 files

3.8.1

2 files

3.8.0

2 files

3.7.0

2 files

Pre-release

3.7.0a6

2 files

Pre-release

3.7.0a5

2 files

3.6.4

2 files

3.6.3

2 files

3.6.2

2 files

3.6.1

2 files

3.6.0

2 files

3.5.0

2 files

3.4.0

2 files

3.3.0

2 files

3.2.1

2 files

3.1.1

2 files

3.1.0

2 files

3.0.1

2 files

3.0.0

2 files

2.12.5

2 files

2.12.4

2 files

2.12.3

2 files

2.12.2

2 files

2.12.1

2 files

2.12.0

2 files

2.11.7

2 files

2.11.6

2 files

2.11.5

2 files

2.11.4

2 files

2.11.3

2 files

2.11.2

2 files

2.11.1

2 files

2.11.0

2 files

2.10.2

2 files

2.10.1

2 files

2.9.0

2 files

2.8.1

2 files

2.8.0

2 files

2.7.3

2 files

2.7.1

2 files

2.7.0

2 files

2.6.0

2 files

2.5.0

2 files

2.3.0

2 files

2.2.6

2 files

2.2.5

2 files

2.2.4

2 files

2.2.3

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.0

2 files

2.0.0

2 files

1.0.3

2 files

1.0.2

2 files

1.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page