Saltar al contenido
Phronesis v0.1.0 alfa ya está disponibleLeer el anuncio
Phronesis

Código abierto · Apache 2.0 · Python 3.11+

Sabiduría práctica para sistemas de agentes de IA.

Phronesis (φρόνησις): para Aristóteles, sabiduría práctica - la capacidad de deliberar bien y actuar con juicio en situaciones concretas. Un LLM tiene episteme (conocimiento). Un agente necesita phronesis.

EmpezarVer en GitHub
hello_phronesis.py
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)

Por qué Phronesis

Un agente no es un chatbot con herramientas.

Los LLM saben cosas - eso es episteme. Pero los agentes deben decidir y actuar con juicio en situaciones concretas. Eso es phronesis. La mayoría de los frameworks de agentes los tratan como chatbots mejorados pegados a un bucle de uso de herramientas. Phronesis los trata como sistemas deliberativos con contratos explícitos: entradas tipadas, efectos declarados, memoria delimitada, patrones de ejecución con nombre.

Los frameworks existentes obligan a elegir. Por un lado, escribes flujo de control arbitrario como código: máxima expresividad y un sistema multiagente que nadie puede depurar seis meses después. Por otro, todo se describe en YAML o constructores de grafos: legible a primera vista, imposible en cuanto necesitas algo no trivial. Phronesis separa la especificación declarativa de la ejecución en tiempo de ejecución. Agentes, herramientas, memoria, pipelines son especificaciones tipadas, inmutables y serializables a JSON. Los patrones de ejecución provienen de un catálogo cerrado y bien definido - expresividad sin caos.

Cada ejecución es observable mediante OpenTelemetry, cada especificación es versionable, cada contrato es una comprobación en tiempo de ejecución, no un comentario en un prompt. Esa es la diferencia entre un framework que produce demos y uno que produce sistemas que puedes operar.

En cifras

Construido como infraestructura, no como una demo.

Phronesis es temprano, pero no es ligero. La superficie es pequeña a propósito - y cada capa carga con sus propios tests, tipos y observabilidad.
19

Modos de ejecución

Un catálogo cerrado y con nombre - de Sequence y Parallel a Reflexion y Tree Search.

22

Ejemplos ejecutables

Cada modo con un cassette determinista, más una mini-app multiagente completa.

1.600+

Tests

Cobertura de ramas con umbral del 90% - el build falla por debajo del mínimo.

14

Módulos estables

Agentes, herramientas, memoria, providers, MCP, pipelines, observabilidad y más.

100%

Superficie tipada

mypy --strict en todo el árbol de código, sin vías de escape.

Apache 2.0

Código abierto

Licencia permisiva, hoja de ruta pública, sin barreras empresariales.

Recorrido por el código

La API en cuatro fragmentos.

Python real, usando la API pública tal como está hoy. El framework está en alfa temprana - la superficie crecerá, pero el diseño seguirá siendo así de delgado.

El decorador @agent vincula un modelo, herramientas tipadas y un system prompt en una única especificación declarativa.

agent.py
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."""

Principios

Seis decisiones, aplicadas en todas partes.

  • Composición sobre herencia

    Los agentes se configuran a partir de piezas - modelo, herramientas, memoria, prompts - no se heredan. Ensamblas; no sobrescribes.

  • Async primero

    Streaming, concurrencia y cancelación son supuestos básicos. No hay una API síncrona paralela que mantener.

  • Fuertemente tipado

    Pydantic v2 y mypy --strict en todo. Los tipos no son documentación - son contratos en tiempo de ejecución que el framework hace cumplir.

  • Specs inmutables, ejecuciones mutables

    Las definiciones son congeladas, serializables a JSON y reproducibles. El estado de ejecución vive aparte, observable y consultable.

  • Observabilidad integrada

    Spans de OpenTelemetry para cada ejecución de agente, llamada a herramienta y etapa de pipeline - desde el primer commit, no atornillado después.

  • Catálogo cerrado de patrones de ejecución

    Sequence, Parallel, Debate, Consensus, Handoff, Reflexion, Tree Search y más - diecinueve modos con nombre sobre los que puedes razonar, no flujo de control arbitrario.

Qué hay dentro

Una superficie pequeña y con principios.

El framework es intencionadamente estrecho. Cada capa se gana su lugar haciendo que un sistema sea más seguro de operar o que el código sea más sencillo de leer seis meses después.

Núcleo

Los primitivos a partir de los que se construye cada agente.

  • Agentes (@agent, sesiones, bucle de tool-calling)
  • Herramientas (tipadas, con efectos declarados)
  • Cliente y servidor MCP
  • Providers (Anthropic, OpenAI, Ollama, vLLM)
  • Constructores de contexto

Estado y memoria

Cómo recuerdan los agentes y cómo reanudan.

  • Memoria (de trabajo, clave-valor, vectorial, episódica)
  • Checkpoints (pausar y reanudar)
  • Sesiones

Orquestación y operación

Cómo se componen los agentes en sistemas que puedes ejecutar.

  • Pipelines
  • 19 modos de ejecución
  • Middleware de provider
  • Cassettes de record / replay
  • Observabilidad con OpenTelemetry

Ingeniería

Las garantías, no las promesas.

Un framework de agentes vale tanto como la disciplina que lo respalda. Estas son las barreras que cada cambio supera antes de aterrizar.

  • Tipado de extremo a extremo

    mypy --strict y specs con Pydantic v2 en todo el árbol de código. Sin vías de escape sin tipar.

  • Probado hasta un mínimo

    Más de 1.600 tests con cobertura de ramas bajo umbral del 90% - el build falla por debajo.

  • Replay determinista

    Graba una vez, reproduce siempre: las ejecuciones respaldadas por cassette hacen el comportamiento de los agentes reproducible en tests y CI sin red.

  • Observable por construcción

    Spans de OpenTelemetry para cada ejecución de agente, llamada a herramienta, etapa de pipeline y sesión MCP - correlacionados por ids estables.

  • Specs inmutables

    Agentes, herramientas y pipelines son dataclasses congeladas y serializables a JSON - versionables, diffables, reproducibles.

  • Limpio de lint

    ruff format y un ruff check estricto vigilan cada commit, junto a las suites de tipos y tests.

Instalar

Un comando. Python 3.11 o superior.

$pip install phronesis-framework
Leer los docsDar estrella en GitHub

Estado del proyecto

Phronesis está en alfa temprana.

La API cambiará. Pero los cimientos ya están aquí: specs tipadas e inmutables; diecinueve modos de ejecución con nombre; record y replay deterministas; OpenTelemetry desde el primer commit; y más de 1.600 tests sostenidos sobre un umbral de cobertura del 90%. Construimos en público - sin afirmaciones de producción, sin casos de estudio inventados, sin barreras empresariales. Solo el código, y un compromiso honesto con su diseño.

Los comentarios, ideas y contribuciones son bienvenidos a través de GitHub Discussions e Issues. La hoja de ruta, los detalles ásperos y las preguntas abiertas están todos en el repositorio.

DebatesAbrir issues