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 Jul 9, 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:
Newer release available (3.11.2)

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 Jul 9, 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.1.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.1-py3-none-any.whl (4.7 MB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for penguiflow-3.11.1.tar.gz
Algorithm Hash digest
SHA256 4643f30f5f1d0a8e8ca00f6dc1fc7bdd0f00688e7183bd5f41004caf362f998b
MD5 092df72bc326584d713ab738d6beb4c7
BLAKE2b-256 84a2643f83ad0c5f8c605bd412fdedd8aaccf7eb01a67e0aa5b54f02b99ff21f

See more details on using hashes here.

Provenance

The following attestation bundles were made for penguiflow-3.11.1.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.1-py3-none-any.whl.

File metadata

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

File hashes

Hashes for penguiflow-3.11.1-py3-none-any.whl
Algorithm Hash digest
SHA256 03317c68b308ad8e5cc7520128d96a89816f65cc6e4f0f984a1723eb2463e06a
MD5 9381701beb3a5fd4a490225ddf37a8d2
BLAKE2b-256 88b32033bacac74c7a6f1578dbc6b73b64b337663fa2cea0f7c47b221fd1f081

See more details on using hashes here.

Provenance

The following attestation bundles were made for penguiflow-3.11.1-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

3.11.2

2 files

This release

3.11.1 This release

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