Oficio

El motor de agentes que antepone la verificación para oficios reales. El LLM habla; los motores deterministas calculan; las evaluaciones lo demuestran.

Oficio convierte una conversación natural con un cliente en un presupuesto de reforma demostrablemente correcto. Se basa en una regla inquebrantable: el modelo de lenguaje nunca calcula un precio. El agente extrae lo que el cliente quiere — con evidencia literal (source_quote) en cada línea — y un motor de precios determinista, impulsado por un tarifario versionado derivado de un negocio real de construcción (anonimizado), calcula al céntimo.

Por qué existe esto

La mayoría de las demos de IA te piden que confíes en ellas. Oficio está diseñado para ser verificado en su lugar:

(Las tablas de evaluación de este README las genera python -m oficio.evals.report — nunca se escriben a mano.)

Related MCP server: IntentForge MCP Server

Estado — honesto y público

v1.0 — 162 pruebas en verde, y las suites de evaluación ya se han ejecutado contra el modelo real: todos los controles han pasado.

Hecho y verificado:

• Motor determinista — matemática monetaria decimal, facturación por unidades completas para materiales discretos (no puedes comprar 3.2 sacos de cemento), aplicación de un margen mínimo, needs_info para cualquier cosa sin precio, ids de presupuesto reproducibles mediante hash de contenido. 30 presupuestos de referencia congelados reproducidos al céntimo en CI.

• Cliente de modelo endurecido — precios con cierre ante fallos (un modelo sin tarifa lanza una excepción; nunca cuesta $0), límite de gasto diario rechazado antes de realizar la llamada, retroceso exponencial solo en 429/5xx, una traza JSONL por llamada con tokens, coste y latencia.

• Extracción con evidencia obligatoria — el modelo solo puede elegir ids del catálogo, y cada línea debe citar al cliente textualmente. La evidencia que no se encuentra en la transcripción se descarta y se convierte en una pregunta.

• Suites de evaluación — 100 conversaciones etiquetadas y 20 adversariales. El propio banco de pruebas se pone a prueba: el evaluador debe demostrar que detecta una cantidad incorrecta, un artículo omitido y uno inventado.

• Servidor MCP — get_catalog, create_quote, explain_quote. Un agente de compras puede presupuestar sin hacer scraping de un formulario, y explain_quote devuelve la aritmética línea por línea: un agente que no puede explicar un número no debería enviarlo.

• API y demo — /quote calcula precios de forma determinista sin ninguna clave API, porque el motor es el producto; /chat añade la extracción y se niega claramente cuando no hay clave configurada en lugar de degradarse a una suposición. El tercer panel de la página, lo que vio el agente, muestra las palabras exactas del cliente detrás de cada línea con precio y todo lo que se descartó antes de calcular el precio.

Resultados de la evaluación

Medido el 2026-08-27 contra claude-haiku-4-5, tarifario v1.0.0. Reprodúcelo con python -m oficio.evals.run all --json evals/reports/latest.json. Esta tabla la genera python -m oficio.evals.report — nunca se escribe a mano.

Coste total de la ejecución completa: $0.27.

El número que merece la pena leer dos veces no es el F1. Son estos dos juntos: el modelo sí intentó inventar cuatro líneas a lo largo de las cien conversaciones, y el validador atrapó las cuatro antes de que ninguna pudiera llegar a un precio. Un sistema que afirma que su modelo nunca alucina es un sistema que no está mirando. Este mira, y te muestra lo que encontró.

El otro es asked instead of guessing: en las 25 conversaciones que no podían presupuestarse tal como se formularon — un artículo fuera del catálogo, una cantidad que nunca se indicó — el agente devolvió una pregunta en lugar de un número. Negarse a responder es una funcionalidad que hay que probar como cualquier otra.

Las ejecuciones en vivo llaman al modelo real, por lo que se activan manualmente en lugar de en cada push: un commit nunca debería poder gastar dinero por accidente.

Aquí no se afirma nada antes de que se ejecute.

Inicio rápido

git clone https://github.com/brayans7/oficio && cd oficio
pip install -e ".[dev,agent]"
pytest                                   # 162 tests, including the price-book leak gate
uvicorn oficio.service.api:app --reload  # then open http://localhost:8000

La demo presupuesta trabajos reales sin clave API. Configura ANTHROPIC_API_KEY para habilitar la ruta conversacional y las suites de evaluación en vivo.

Cómo funciona

customer conversation
        │
        ▼
   extraction (LLM)          ← catalog-bounded; every line must quote the customer verbatim
        │                      no evidence in the transcript → dropped, becomes a question
        ▼
      JobSpec                ← validated: known ids, positive quantities, real evidence
        │
        ▼
   quote engine              ← deterministic. Decimal math, versioned price book,
        │                      whole units for discrete materials, margin floor enforced
        ▼
   QuoteResult               ← content-hashed id: same inputs, same quote, forever

El modelo propone. El motor dispone. Nada que no pueda rastrearse hasta las propias palabras del cliente recibe un precio.

Usarlo desde otro agente (MCP)

from oficio.service.mcp_tools import call_tool

catalog = call_tool("get_catalog", {"category": "flooring"})
quote = call_tool("create_quote", {"line_items": [
    {"item_id": "ceramic_tile_standard", "qty": 12,
     "source_quote": "I need new floor tile for the kitchen"},
]})
print(call_tool("explain_quote", {"quote": quote})["summary"])

Ejecútalo como servidor MCP stdio con python -m oficio.service.mcp_tools.

Arquitectura

src/oficio/
  core/     # deterministic: schemas, price book, quote engine — pure, no LLM imports
  agent/    # conversational: extraction w/ evidence, model routing, cost meter, guardrails
  evals/    # labeled datasets, runner, report generator — the public proof
  service/  # MCP tools for agents, FastAPI + demo page for humans
data/
  pricebook.v1.json   # anonymized real-world price book (labor + materials)
  evals/              # 100 labeled conversations + 20 attacks

Límite estricto: agent/ importa core/. Nunca al revés.

Decisiones de diseño (deliberadas)

• División neuro-simbólica — los LLM son excelentes a la hora de comprender y pésimos a la hora de responder de la aritmética. El motor es dueño de cada número.

• Evidencia o no sucedió — cada línea del presupuesto lleva source_quote, el texto literal del cliente que la justifica. Una línea sin evidencia es un fallo de evaluación, no una funcionalidad.

• Cierre ante fallos en todas partes — artículo desconocido → needs_info (nunca estimar); modelo sin entrada de precio → excepción (nunca $0); si faltan secretos → negarse a iniciar.

• Sin base de datos en v1 — un tarifario JSON y trazas JSONL son suficientes para el MVP. Deliberadamente fuera de alcance: pagos, autenticación, multitenencia, planificación, una segunda vertical.

Hoja de ruta

Deliberadamente fuera de alcance para v1, y por qué: pagos (el presupuesto es el producto; cobrar es un problema aparte), autenticación y multitenencia (un negocio, un tarifario — hasta que exista un segundo, es especulación), planificación (un dominio distinto con sus propios modos de fallo), una segunda vertical (la idea es demostrar el patrón una vez, y bien).

Lo que sigue de verdad: un conjunto etiquetado construido a partir de transcripciones reales en lugar de compuestas — los números actuales miden esta distribución, no la realidad — y la calibración del tarifario contra un segundo negocio, que es lo que convertiría un motor que funciona en un producto.

Procedencia y honestidad

El tarifario se deriva de las operaciones en vivo de un negocio familiar de reformas, con los nombres eliminados y los precios escalados por un factor no revelado con fluctuación por artículo — proporciones realistas, negocio protegido. El proceso de anonimización es privado por diseño y se aplica mediante una prueba de control de fugas en CI.

Las conversaciones de evaluación están compuestas a partir de plantillas, no son transcripciones de clientes reales. Eso las hace reproducibles y publicables, y significa que la precisión declarada es precisión contra esta distribución. Dicho claramente aquí porque un benchmark cuya procedencia es vaga es un benchmark en el que nadie debería confiar.

Construido por Brayan Molina con desarrollo dirigido por especificaciones y Claude Code. Licencia MIT.