Oficio

Агентский движок, где проверка — прежде всего, для реальных ремесленных работ. LLM говорит; детерминированные движки вычисляют; эвалы доказывают.

Oficio превращает естественный разговор с клиентом в доказуемо корректную смету на ремонт. Он построен на одном непреклонном правиле: языковая модель никогда не вычисляет цену. Агент извлекает то, что хочет клиент, — с буквальными доказательствами (source_quote) для каждой строки, — а детерминированный движок ценообразования, управляемый версионируемым прайс-буком, полученным из реального строительного бизнеса (анонимизированного), считает до цента.

Почему это существует

Большинство AI-демо просят, чтобы вы им доверяли. Oficio создан, чтобы его проверяли:

(Таблицы эвалов в этом README генерируются командой python -m oficio.evals.report — никогда не пишутся вручную.)

Related MCP server: IntentForge MCP Server

Статус — честно и публично

v1.0 — 162 теста зелёные, и эвал-наборы уже прогнаны на реальной модели: все пороги пройдены.

Сделано и проверено:

• Детерминированный движок — десятичная денежная арифметика, оплата целыми единицами для дискретных материалов (нельзя купить 3.2 мешка цемента), контроль минимальной маржи, needs_info для всего, чему не назначена цена, воспроизводимые идентификаторы смет на основе хэша содержимого. 30 замороженных эталонных смет воспроизведены до цента в CI.

• Усиленный клиент модели — fail-closed ценообразование (модель без тарифа выбрасывает исключение; она никогда не стоит $0), дневной бюджет отклоняется до совершения вызова, экспоненциальная задержка только на 429/5xx, один JSONL-трейс на каждый вызов с токенами, стоимостью и задержкой.

• Извлечение с обязательными доказательствами — модель может выбирать только идентификаторы из каталога, и каждая строка должна дословно цитировать клиента. Доказательства, не найденные в транскрипте, отбрасываются и превращаются в ворос.

• Эвал-наборы — 100 размеченных разговоров и 20 состязательных. Сам тестовый каркас тестируется: оценщик должен доказать, что ловит неверное количество, пропущенную позицию и выдуманную.

• MCP-сервер — get_catalog, create_quote, explain_quote. Агент-покупатель может сформировать смету без скрапинга формы, а explain_quote возвращает арифметику строка за строкой: агент, который не может объяснить число, не должен его отправлять.

• API и демо — /quote рассчитывает цену детерминированно вообще без API-ключа, потому что движок и есть продукт; /chat добавляет извлечение и явно отказывается, когда ключ не задан, вместо того чтобы выродиться в угадывание. Третья панель страницы — что видел агент — показывает точные слова клиента за каждой строкой с ценой и всё, что было отброшено до ценообразования.

Результаты эвалов

Замерено 2026-08-27 на claude-haiku-4-5, прайс-бук v1.0.0. Воспроизвести командой python -m oficio.evals.run all --json evals/reports/latest.json. Эта таблица генерируется python -m oficio.evals.report — никогда не пишется вручную.

Обща стоимос ть полног о прогона: $0.27.

Число, которое стоит перечита ть дважды, — это не F1. Во т эти два вмес те: модел ь дейс твите ьно попытала сь выдума ть четыре позиции в ходе ста разговоров, и валидатор поймал все четыре, преж де чем любая из них могла дой ти до цены. Систе ма, котора я утверждает, что её модел ь никогда не галлюцинирует, — это систе ма, котора я не смо трит. Эта смо трит и показыва ет вам, что она нашла.

Втора я — asked instead of guessing: во всех 25 разговорах, которые нельзя было превратить в смету в том виде, как заявлено, — позиция вне каталога, количество так и не указано, — агент вернул вопрос, а не число. Отказ отвечать — это функция, которую нужно тестировать, как и любую другую.

Живые прогоны вызывают реальную модель, поэтому они запускаются вручную, а не при каждом пуше: коммит никогда не должен случайно трати ть деньги.

Ничто здесь не утверждае тся до того, как оно запущено.

Быстрый старт

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

Демо рассчитыва ет реальные заказы без API-ключа. Установите ANTHROPIC_API_KEY, чтобы включи ть разговорный путь и живые эвал-наборы.

Как это работае т

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

Модел ь предлага ет. Движок располага ет. Ничто, что нельзя проследи ть до собственных слов клиента, не получа е т цену.

Использование из другого агента (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"])

Запустите его как stdio MCP-сервер с помощью python -m oficio.service.mcp_tools.

Архитектура

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

Жёсткая граница: agent/ импортирует core/. Никогда наоборот.

Проектные решения (намеренные)

• Нейро-символическое разделение — LLM отлично понимают, но ужасны в арифметической подотчётности. Движок владеет каждым числом.

• Доказательство или этого не было — каждая строка сметы несёт source_quote — буквальный текст клиента, который её обосновывает. Строка без доказательства — это ошиба эвала, а не функция.

• Fail-closed везде — неизвестная позиция → needs_info (никогда не оценвать); модел ь без записи о цене → исключение (никогда не $0); отсутствующие секреты → отказ запускаться.

• Никакой базы данных в v1 — JSON-прайс-бук и JSONL-трейсы достаточны для MVP. Сознательно вне объёма: пла тежи, аутентификация, мультиарендность, пла нирование, второе направление.

Дорожная карта

Сознательно вне объёма v1, и почему: пла тежи (смета — это продукт; сбор денег — отдельна я задача), аутентификация и мультиарендность (один бизнес — один прайс-бук; пока не появится второй, это спекуляция), планирование (другая область со своими режимами отказов), второе вертикальное направление (смысл в том, чтобы доказать паттерн один раз, хорошо).

Что действительно дальше: размеченный набор, построенный на реальных транскриптах, а не на составленных, — текущие цифры измеряют это распределение, а не реальный мир, — и калибровка прайс-бука относительно второго бизнеса; именно это превратит работающий движок в продукт.

Происхождение и честность

Прайс-бук получен из реальной деятельности семейного ремонтного бизнеса: имена удалены, а цены маштабированы на нераскрытый коэффициен т с индивидуальным разбросом по позициям — реалистичные соотношения, защищённый бизнес. Конвейер анонимизации закрыт по замыслу и подкреплён шлюзовым тестом на утечки в CI.

Эвал-разговоры составлены из шаблонов, а не из транскриптов реальных клиентов. Это делает их воспроизводимыми и публикуемыми, а значит, заявленная точность — это точность на этом распределении. Сказано здесь прямо, потому что бенчмарк с неясным происхождением — это бенчмарк, которому никто не должен доверять.

Создано Brayan Molina с использованием спецификационно-ориентированной разработки и Claude Code. Лицензия MIT.