Open source · Apache 2.0 · Python 3.11+
Phronesis (φρόνησις): voor Aristoteles, praktische wijsheid - het vermogen om goed te beraadslagen en met oordeel te handelen in concrete situaties. Een LLM heeft episteme (kennis). Een agent heeft phronesis nodig.
from phronesis.agents import agent
from phronesis.providers import anthropic
@agent(
model=anthropic(model="claude-sonnet-4-6"),
system_prompt="You investigate questions thoroughly and cite sources.",
)
def researcher() -> str:
"""Investigate a question and synthesize a cited answer."""
result = await researcher.run("What is phronesis in Aristotelian ethics?")
print(result.output)from phronesis.agents import agent
from phronesis.providers import anthropic
@agent(
model=anthropic(model="claude-sonnet-4-6"),
system_prompt="You investigate questions thoroughly and cite sources.",
)
def researcher() -> str:
"""Investigate a question and synthesize a cited answer."""
result = await researcher.run("What is phronesis in Aristotelian ethics?")
print(result.output)Waarom Phronesis
LLM's weten dingen - dat is episteme. Maar agents moeten beslissen en handelen met oordeel in concrete situaties. Dat is phronesis. De meeste agent-frameworks behandelen agents als verbeterde chatbots geplakt aan een tool-use-loop. Phronesis behandelt ze als beraadslagende systemen met expliciete contracten: getypeerde invoer, gedeclareerde effecten, begrensd geheugen, benoemde uitvoeringspatronen.
Bestaande frameworks dwingen een keuze af. Aan de ene kant schrijf je willekeurige besturingsstroom als code: maximale expressiviteit, en een multi-agentsysteem dat niemand zes maanden later kan debuggen. Aan de andere kant wordt alles beschreven in YAML of grafenbouwers: in één oogopslag leesbaar, onmogelijk zodra je iets niet-triviaals nodig hebt. Phronesis scheidt declaratieve specificatie van runtime-uitvoering. Agents, tools, geheugen en pipelines zijn getypeerde, onveranderlijke, JSON-serialiseerbare specs. Uitvoeringspatronen komen uit een gesloten, welomschreven catalogus - expressiviteit zonder chaos.
Elke run is observable via OpenTelemetry, elke spec is versioneerbaar, elk contract is een runtime-check, geen commentaar in een prompt. Dat is het verschil tussen een framework dat demo's produceert en een dat systemen produceert die je kunt opereren.
By the numbers
A closed, named catalog - from Sequence and Parallel to Reflexion and Tree Search.
Every mode with a deterministic cassette, plus a full multi-agent mini-app.
Branch coverage gated at 90% - the build fails below the floor.
Agents, tools, memory, providers, MCP, pipelines, observability and more.
mypy --strict across the entire source tree, no escape hatches.
Permissive license, public roadmap, no enterprise gates.
Code-tour
Een agent bindt een model, tools en geheugen onder één declaratieve spec.
from phronesis import ToolEffect
from phronesis.agents import agent
from phronesis.providers import anthropic
from phronesis.tools import tool
@tool(effects=(ToolEffect.NETWORK,))
async def search_web(query: str, limit: int = 5) -> list[str]:
"""Search the web and return ranked snippets."""
...
@agent(
model=anthropic(model="claude-sonnet-4-6"),
tools=(search_web,),
system_prompt="You are a careful research assistant.",
max_iterations=8,
)
def assistant() -> str:
"""Answer questions grounded in live search results."""from phronesis import ToolEffect
from phronesis.agents import agent
from phronesis.providers import anthropic
from phronesis.tools import tool
@tool(effects=(ToolEffect.NETWORK,))
async def search_web(query: str, limit: int = 5) -> list[str]:
"""Search the web and return ranked snippets."""
...
@agent(
model=anthropic(model="claude-sonnet-4-6"),
tools=(search_web,),
system_prompt="You are a careful research assistant.",
max_iterations=8,
)
def assistant() -> str:
"""Answer questions grounded in live search results."""Principes
Agents worden geconfigureerd uit onderdelen - model, tools, geheugen, prompts - niet via subklassen. Je stelt samen; je overschrijft niet.
Streaming, concurrency en annulering zijn basisaannames. Er is geen synchrone schaduw-API om te onderhouden.
Pydantic v2 overal. Types zijn geen documentatie - het zijn runtime-contracten die het framework afdwingt.
Definities zijn JSON-serialiseerbaar en reproduceerbaar. Uitvoeringsstaat leeft apart, observable en bevraagbaar.
OpenTelemetry-spans voor elke agent-run, tool-aanroep en pipeline-stap - vanaf de eerste commit, niet er achteraf opgeschroefd.
Sequence, Parallel, ReActLoop, Consensus, Debate, Handoff. Benoemde modi waarover je kunt redeneren - geen willekeurige besturingsstroom.
Wat zit erin
De primitieven waarmee elke agent wordt gebouwd.
Hoe agents onthouden en wat ze delen.
Hoe agents samen systemen vormen.
Engineering
mypy --strict and Pydantic v2 specs across the whole source tree. No untyped escape hatches.
1,600+ tests with branch coverage gated at 90% - the build fails below it, never above it on paper.
Record once, replay forever: cassette-backed runs make agent behavior reproducible in tests and CI without a network.
OpenTelemetry spans for every agent run, tool call, pipeline stage, and MCP session - correlated by stable ids.
Agents, tools, and pipelines are frozen, JSON-serializable dataclasses - versionable, diffable, reproducible.
ruff format and a strict ruff check gate every commit, alongside the type and test suites.
Installeren
$pip install phronesis-framework
Projectstatus
De API zal veranderen. We werken openbaar om een framework te bouwen dat agentsystemen serieus neemt - getypeerd, samenstelbaar, observable. Geen productie-claims, geen verzonnen case studies, geen enterprise-poorten. Alleen de code en een eerlijke toewijding aan het ontwerp.
Feedback, ideeën en bijdragen zijn welkom via GitHub Discussions en Issues. De roadmap, de ruwe randjes en de open vragen staan allemaal in de repository.
