百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
P

puff

> 编程语言
开源

☁ Puff ☁ - 深层堆栈框架。

326 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

☁ Puff ☁ - 深层堆栈框架。

☁ Puff ☁

The deep stack runtime for Python. An all-in-one async runtime for AI Agents, GraphQL, ASGI, WSGI, Postgres, PubSub, Redis, Distributed Tasks, and HTTP2 Client.

Now with a built-in Agent Runtime — one binary, one process, everything agents need.

[![Crates.io][crates-badge]][crates-url] [![MIT licensed][mit-badge]][mit-url] [crates-badge]: https://img.shields.io/crates/v/puff_rs.svg [crates-url]: https://crates.io/crates/puff_rs [mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg [mit-url]: https://github.com/hansonkd/puff/blob/master/LICENSE

  • What is Puff?
    • Quick Start
    • Puff ♥ Agents NEW in v2
    • Puff ♥ Python
    • Puff ♥ Django
    • Puff ♥ Graphql
    • Puff ♥ Pytest
    • Puff ♥ AsyncIO
    • Puff ♥ Django + GraphQL
    • Puff ♥ Distributed Tasks
    • Puff ♥ HTTP
    • Links
      • CHANGELOG
      • Deepstack
      • Using the CLI
      • Flask
      • FastAPI
      • Django
      • Building an RPC with Puff

What is Puff?

Puff is a batteries included "deep stack" for Python. It's an experiment to minimize the barrier between Python and Rust to unlock the full potential of high level languages. Build your own Runtime using standard CPython and extend it with Rust. Imagine if GraphQL, Postgres, Redis, PubSub, Distributed Tasks, and now AI Agents were part of the standard library. That's Puff.

The old approach for integrating Rust in Python would be to make a Python package that uses rust and import it from Python. This approach has some flaws as the rust packages can't cooperate. Puff gives Rust its own layer, so you can build a cohesive set of tools in Rust that all work flawlessly together without having to re-enter Python.

Puff v2 takes this further. Every agent framework today is pure Python, stitching together HTTP calls to external services, serializing everything, managing state through hope. Puff already has the infrastructure — Postgres for memory, Redis for caching, pub/sub for coordination, task queues for background work, WebSockets for streaming. It just needed to be pointed at the right problem. Now it has a built-in agent runtime where LLM calls stream through Rust, tools execute on real threads, and everything runs in one process.

High level overview is that Puff gives Python

  • AI Agent Runtime — define agents with tools, memory, and orchestration patterns
  • Multi-provider LLM Gateway — Anthropic, OpenAI, Ollama with streaming, retry, and fallback
  • Skills + CLI Tools — curated capability packages with whitelisted CLI commands
  • Three-tier Memory — Redis conversations, Postgres+pgvector long-term, working memory
  • Multi-agent Orchestration — Router, Supervisor, Chain, Parallel patterns
  • Free-threaded Python on Rust's Tokio (replaces greenlets)
  • High performance HTTP Server - combine Axum with Python WSGI apps (Flask, Django, etc.)
  • Rust / Python natively in the same process, no sockets or serialization.
  • AsyncIO / uvloop / ASGI integration with Rust
  • An easy-to-use GraphQL service
  • Multi-node pub-sub
  • Rust level Redis Pool
  • Rust level Postgres Pool with pgvector
  • Websockets
  • HTTP Client
  • Distributed, at-least-once, priority and scheduled task queue
  • semi-compatible with Psycopg2 (hopefully good enough for most of Django)
  • A safe convenient way to drop into rust for maximum performance

The idea is Rust and Python are near perfect complements to each other and building a framework to let them talk leads to greater efficiency in terms of productivity, scalability and performance.

Python Rust
✅ High-Level ✅ Low-Level
✅ Lots of tools and packages ✅ Lots of tools and packages
✅ Easy to get started ✅ Easy to get started
Interpreted (productivity at the cost of speed) Compiled (speed at the cost of productivity)
✅ Easy to get master ❌ The learning curve gets steep quickly.
✅ Fast iteration to prototype ❌ Requires planning for correctness
✅ Google a problem, copy paste, it works. ❌ Less examples floating in the wild
❌ Weak type system ✅ Great Type System
✅ Free-threaded mode (3.13+) unlocks parallelism ✅ High Performance
❌ Not-so safe ✅ Safe

The Zen of deepstack is recognizing that no language is the ultimate answer. Seek progress instead of perfection by using Python for rapid development and Rust to optimize the most critical paths once you find them later. Find the balance.

Quick Start

Install Rust to compile Puff for your platform.

Install Rust

Follow the instructions to install Cargo for your platform.

bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install Puff

Use cargo to install Puff.

bash
cargo install puff-rs

Puff requires Python >= 3.10. Python's Poetry is optional.

Your Puff Project needs to find your Python project. Even if they are in the same folder, they need to be added to the PYTHONPATH.

One way to set up a Puff project is like this:

bash
poetry new my_puff_proj_py
cd my_puff_proj_py
poetry add puff-py

Now from my_puff_proj_py you can run your project with poetry run puff to access puff from poetry.

The Python project doesn't need to be inside off your Rust package. It only needs to be on the PYTHONPATH or inside an virtualenv. If you don't want to use poetry, you will have to set up something like a virtual environment when running Puff.

Puff ♥ Agents

Puff v2 is a deep stack agent runtime. Define agents in Python, back them with Rust-speed infrastructure, serve them with one command. Every piece of infrastructure an agent needs — LLM calls, tool execution, memory, multi-agent coordination, streaming — is baked in, not bolted on.

python
from puff import Agent

# Define an agent with a system prompt and model
support = Agent(
    name="customer-support",
    model="claude-sonnet-4-6",
    system_prompt="You are a helpful customer support agent for Acme Corp.",
    skills=["./skills/github", "./skills/database"],
    memory=True,
)

Skills: CLI Tools as Agent Capabilities

Tools are organized as skills — curated packages of whitelisted CLI commands with context for the agent. No arbitrary shell access. Every command pattern is explicitly allowed.

toml
# skills/github/skill.toml
[skill]
name = "github"
description = "Interact with GitHub repositories"

[[tools]]
name = "list-prs"
description = "List open pull requests"
command = "gh pr list --json number,title,author,url"
output = "json"

[[tools]]
name = "create-pr"
description = "Create a new pull request"
command = "gh pr create"
args = { title = { type = "str" }, body = { type = "str" } }
requires_approval = true    # human-in-the-loop for mutations

[permissions]
allow = ["gh pr *", "gh issue *"]
deny = ["gh repo delete *"]

Skills can include a context.md that gets injected into the agent's system prompt — domain knowledge that helps the agent use the tools effectively.

Multi-Agent Orchestration

Multiple agents working together. Router dispatches to specialists. Supervisor delegates and reviews. Chain pipes output through a sequence. Parallel runs agents simultaneously on real threads.

python
from puff import Agent, Router

billing  = Agent(name="billing",  model="claude-haiku-4-5", skills=["./skills/billing"])
technical = Agent(name="technical", model="claude-sonnet-4-6", skills=["./skills/docs"])

support_desk = Router(
    name="support-desk",
    agents=[billing, technical],
    router_prompt="Route billing/payment to billing, technical issues to technical.",
    model="claude-haiku-4-5",
)

Agent Server

One command starts everything — REST API, WebSocket streaming, health checks:

bash
puff agent --port 8080
bash
# Start a conversation
curl -X POST http://localhost:8080/api/conversations \
  -d '{"agent": "support-desk", "message": "I was double-charged"}'

# Real-time streaming via WebSocket
wscat -c ws://localhost:8080/ws/conversations/abc-123

Three-Tier Memory

Agents remember things. Conversation history in Redis, long-term facts in Postgres with pgvector for semantic search. Puff manages it automatically — the developer never touches it.

LLM Gateway

All LLM calls go through Rust. Streaming SSE parsed at native speed. Multi-provider (Anthropic, OpenAI, Ollama) with automatic retry, exponential backoff, and provider fallback chains. Cost tracked per call, per agent, per conversation.

toml
# puff.toml
[llm]
default_model = "claude-sonnet-4-6"

[llm.providers.anthropic]
api_key_env = "ANTHROPIC_API_KEY"

[llm.providers.openai]
api_key_env = "OPENAI_API_KEY"

[llm.fallback]
"claude-sonnet-4-6" = ["gpt-4o"]

[memory]
auto_extract = true
recall_k = 10

Eval

Test your agents like you test your code:

bash
$ puff agent-ask --agent support-desk
> I was charged twice for order #123
Looking into that for you...

Puff ♥ Python

Python programs in Puff are run by building a Program in Rust and registering the Python function there.

The Python method is bootstrapped and run on a thread in the Puff runtime.

Create a puff.toml

toml
[[commands]]
function = "my_puff_proj_py.hello_world"
command_name = "hello_world"

Python:

…

Puff ♥ Django

While it can run any WSGI app, Puff has a special affection for Django. Puff believes that business logic should be implemented on a higher level layer and Rust should be used as an optimization. Django is a perfect high level framework to use with Puff as it handles migrations, admin, etc. Puff mimics the psycopg2 drivers and cache so that Django uses the Puff Database and Redis pool.

Transform your sync Django project into a highly concurrent Puff program with a few lines of code. Puff wraps the management commands so migrate, etc. all work as expected. Simply run poetry run run_cargo django [command] instead of using ./manage.py [command]. For example poetry run run_cargo django migrate. Don't use django's dev server, instead use Puff's with poetry run run_cargo serve.

Create a puff.toml

toml
django = true
wsgi = "my_django_application.wsgi.application"

[[postgres]]
name = "default"

[[redis]]
name = "default"

Use Puff everywhere in your Django app. Even create Django management commands that use Rust!

See puff-py repo for a more complete Django example.

Puff ♥ Graphql

Puff exposes Graphql Mutations, Queries and Subscriptions based on Python Class definitions. A core "killer feature" of the Puff Graphql engine is that it works on a "layer base" instead of a Node base. This allows each step of Graphql to gather the c

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rust

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言