Oficio

Die verifikationsorientierte Agent-Engine für reale Gewerke. Das LLM spricht; deterministische Engines rechnen; Evals beweisen es.

Oficio verwandelt ein natürliches Gespräch mit einem Kunden in ein nachweislich korrektes Umbau-Angebot. Es basiert auf einer einzigen kompromisslosen Regel: Das Sprachmodell berechnet niemals einen Preis. Der Agent extrahiert, was der Kunde möchte — mit wörtlichem Beleg (source_quote) für jede Position — und eine deterministische Preis-Engine, gesteuert von einem versionierten Preisbuch, das von einem echten Bauunternehmen (anonymisiert) abgeleitet ist, rechnet bis auf den Cent genau.

Warum es das gibt

Die meisten KI-Demos verlangen, dass man ihnen vertraut. Oficio ist stattdessen darauf ausgelegt, verifiziert zu werden:

(Eval-Tabellen in dieser README werden von python -m oficio.evals.report generiert — niemals von Hand geschrieben.)

Related MCP server: IntentForge MCP Server

Status — ehrlich und öffentlich

v1.0 — 162 Tests grün, und die Eval-Suites sind jetzt gegen das echte Modell gelaufen: jedes Gate bestanden.

Umgesetzt und verifiziert:

• Deterministische Engine — Dezimale Geldberechnung, Abrechnung ganzer Einheiten für diskrete Materialien (man kann nicht 3,2 Sack Zement kaufen), Margen-Untergrenze, needs_info für alles Unbepreiste, inhaltsgehashte reproduzierbare Angebots-IDs. 30 eingefrorene goldene Angebote bis auf den Cent in CI reproduziert.

• Gehärteter Modell-Client — Fail-Closed-Preisfindung (ein nicht tarifiertes Modell wirft einen Fehler; es kostet nie $0), Tagesbudget wird vor dem Aufruf verweigert, exponentielles Backoff nur bei 429/5xx, eine JSONL-Trace pro Aufruf mit Tokens, Kosten und Latenz.

• Extraktion mit verpflichtenden Belegen — das Modell darf nur IDs aus dem Katalog wählen, und jede Position muss den Kunden wörtlich zitieren. Belege, die im Transkript nicht gefunden werden, werden verworfen und in eine Frage umgewandelt.

• Eval-Suites — 100 beschriftete Gespräche und 20 adversariale. Der Prüfstand selbst wird getestet: Der Bewerter muss nachweisen, dass er eine falsche Menge, eine übersehene Position und eine erfundene erkennt.

• MCP-Server — get_catalog, create_quote, explain_quote. Ein kaufender Agent kann ein Angebot erstellen, ohne ein Formular zu scrapen, und explain_quote liefert die Rechnung Position für Position: Ein Agent, der eine Zahl nicht erklären kann, sollte sie nicht senden.

• API und Demo — /quote bepreist deterministisch ganz ohne API-Schlüssel, denn die Engine ist das Produkt; /chat ergänzt die Extraktion und verweigert klar, wenn kein Schlüssel gesetzt ist, anstatt zu einer Schätzung zu verkommen. Das dritte Panel der Seite, was der Agent gesehen hat, zeigt die exakten Kundenworte hinter jeder bepreisten Position und alles, was vor der Preisberechnung verworfen wurde.

Eval-Ergebnisse

Gemessen am 27.08.2026 gegen claude-haiku-4-5, Preisbuch v1.0.0. Reproduzierbar mit python -m oficio.evals.run all --json evals/reports/latest.json. Diese Tabelle wird von python -m oficio.evals.report generiert — niemals von Hand geschrieben.

Gesamtkosten des vollständigen Laufs: $0.27.

Die Zahl, die man zweimal lesen sollte, ist nicht der F1. Es sind diese beiden zusammen: Das Modell hat tatsächlich versucht, über die hundert Gespräche hinweg vier Positionen zu erfinden, und der Validator hat alle vier erwischt, bevor auch nur eine einen Preis erreichen konnte. Ein System, das behauptet, sein Modell halluziniere nie, ist ein System, das nicht hinschaut. Dieses hier schaut hin und zeigt, was es gefunden hat.

Die andere ist asked instead of guessing: In allen 25 Gesprächen, die nicht wie angegeben bepreist werden konnten — ein Artikel außerhalb des Katalogs, eine nie genannte Menge — gab der Agent eine Frage statt einer Zahl zurück. Die Verweigerung einer Antwort ist ein Feature, das wie jedes andere getestet werden muss.

Live-Läufe rufen das echte Modell auf und werden daher manuell ausgelöst statt bei jedem Push: Ein Commit sollte niemals versehentlich Geld ausgeben können.

Hier wird nichts behauptet, bevor es läuft.

Quickstart

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

Die Demo bepreist echte Aufträge ohne API-Schlüssel. Setzen Sie ANTHROPIC_API_KEY, um den Konversationspfad und die Live-Eval-Suites zu aktivieren.

So funktioniert es

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

Das Modell schlägt vor. Die Engine verfügt. Nichts, was sich nicht auf die eigenen Worte des Kunden zurückführen lässt, erhält einen Preis.

Nutzung aus einem anderen Agenten (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"])

Führen Sie es als stdio-MCP-Server mit python -m oficio.service.mcp_tools aus.

Architektur

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

Harte Grenze: agent/ importiert core/. Niemals umgekehrt.

Designentscheidungen (bewusst)

• Neuro-symbolische Trennung — LLMs sind hervorragend im Verstehen und schlecht bei arithmetischer Rechenschaft. Die Engine besitzt jede Zahl.

• Beleg oder es ist nicht passiert — jede Angebotsposition trägt source_quote, den wörtlichen Kundentext, der sie rechtfertigt. Eine Position ohne Beleg ist ein Eval-Fehler, kein Feature.

• Überall Fail-Closed — unbekannter Artikel → needs_info (niemals schätzen); Modell ohne Preiseintrag → Ausnahme (niemals $0); fehlende Secrets → Start verweigern.

• Keine Datenbank in v1 — ein JSON-Preisbuch und JSONL-Traces reichen für das MVP. Bewusst nicht im Umfang: Zahlungen, Authentifizierung, Multi-Tenancy, Terminplanung, eine zweite Vertikale.

Roadmap

Bewusst nicht im Umfang von v1, und warum: Zahlungen (das Angebot ist das Produkt; das Einziehen ist ein separates Problem), Authentifizierung und Multi-Tenancy (ein Unternehmen, ein Preisbuch — bis ein zweites existiert, ist es Spekulation), Terminplanung (eine andere Domäne mit eigenen Fehlermodi), eine zweite Vertikale (der Punkt ist, das Muster einmal gut zu beweisen).

Was wirklich als Nächstes kommt: ein beschrifteter Datensatz aus echten Transkripten statt zusammengestellter — die aktuellen Zahlen messen diese Verteilung, nicht die freie Wildbahn — sowie die Kalibrierung des Preisbuchs an einem zweiten Unternehmen, was eine funktionierende Engine in ein Produkt verwandeln würde.

Herkunft und Ehrlichkeit

Das Preisbuch leitet sich aus dem laufenden Betrieb eines Familienunternehmens für Umbauten ab, mit entfernten Namen und Preisen, die um einen nicht genannten Faktor mit positionsbezogenem Jitter skaliert wurden — realistische Verhältnisse, geschütztes Geschäft. Die Anonymisierungs-Pipeline ist bewusst privat und wird durch einen Leak-Gate-Test in CI durchgesetzt.

Die Eval-Gespräche sind aus Vorlagen zusammengesetzt, nicht aus Transkripten echter Kunden. Das macht sie reproduzierbar und veröffentlichbar, und es bedeutet, dass die berichtete Genauigkeit eine Genauigkeit gegenüber dieser Verteilung ist. Hier deutlich gesagt, denn ein Benchmark mit vager Herkunft ist ein Benchmark, dem niemand vertrauen sollte.

Erstellt von Brayan Molina mit spezifikationsgetriebener Entwicklung und Claude Code. MIT-Lizenz.