Open source · Apache 2.0 · Python 3.11+
Phronesis (φρόνησις) : pour Aristote, sagesse pratique - la capacité de délibérer avec justesse et d'agir avec discernement dans des situations concrètes. Un LLM possède episteme (connaissance). Un agent a besoin de phronesis.
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)Pourquoi Phronesis
Les LLM savent des choses - c'est épistémè. Mais les agents doivent décider et agir avec discernement dans des situations concrètes. C'est phronesis. La plupart des frameworks d'agents les traitent comme des chatbots améliorés collés à une boucle d'utilisation d'outils. Phronesis les traite comme des systèmes délibératifs avec des contrats explicites : entrées typées, effets déclarés, mémoire bornée, modèles d'exécution nommés.
Les frameworks existants imposent un choix. D'un côté, vous écrivez un flux de contrôle arbitraire en code : expressivité maximale, et un système multi-agents que personne ne peut déboguer six mois plus tard. De l'autre, tout est décrit en YAML ou en constructeurs de graphes : lisible au premier coup d'œil, impossible dès que vous avez besoin de quelque chose de non trivial. Phronesis sépare la spécification déclarative de l'exécution. Les agents, outils, mémoire et pipelines sont des specs typées, immuables, sérialisables en JSON. Les modèles d'exécution proviennent d'un catalogue fermé et bien défini - expressivité sans chaos.
Chaque exécution est observable via OpenTelemetry, chaque spec est versionnable, chaque contrat est une vérification à l'exécution, pas un commentaire dans un prompt. C'est la différence entre un framework qui produit des démos et un qui produit des systèmes que vous pouvez exploiter.
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.
Tour du code
Un agent lie un modèle, des outils et une mémoire dans une seule spec déclarative.
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
Les agents sont configurés à partir de pièces - modèle, outils, mémoire, prompts - pas sous-classés. Vous assemblez ; vous ne surchargez pas.
Streaming, concurrence et annulation sont des hypothèses de base. Il n'y a pas d'API synchrone fantôme à maintenir.
Pydantic v2 partout. Les types ne sont pas de la documentation - ce sont des contrats à l'exécution que le framework applique.
Les définitions sont sérialisables en JSON et reproductibles. L'état d'exécution vit à part, observable et interrogeable.
Spans OpenTelemetry pour chaque exécution d'agent, appel d'outil et étape de pipeline - dès le premier commit, pas greffé après coup.
Sequence, Parallel, ReActLoop, Consensus, Debate, Handoff. Des modes nommés sur lesquels vous pouvez raisonner - pas du flux de contrôle arbitraire.
Ce qu'il y a dedans
Les primitives à partir desquelles chaque agent est construit.
Comment les agents se souviennent et ce qu'ils partagent.
Comment les agents se composent en systèmes.
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.
Installer
$pip install phronesis-framework
Statut du projet
L'API va changer. Nous travaillons publiquement pour construire un framework qui prend au sérieux les systèmes d'agents - typé, composable, observable. Aucune revendication de production, aucune étude de cas inventée, aucune barrière entreprise. Juste le code, et un engagement honnête envers son design.
Retours, idées et contributions sont les bienvenus via GitHub Discussions et Issues. La feuille de route, les aspérités et les questions ouvertes sont toutes dans le dépôt.
