Oficio

실전 거래를 위한 검증 우선 에이전트 엔진. LLM이 말하고, 결정적 엔진이 계산하며, 평가가 증명합니다.

Oficio는 고객과의 자연스러운 대화를 증명 가능한 정확성의 리모델링 견적으로 전환합니다. 단 하나의 타협 없는 원칙 위에 구축되었습니다: 언어 모델은 절대 가격을 계산하지 않습니다. 에이전트는 고객이 원하는 것을 추출하고 — 모든 항목에 문자 그대로의 증거(source_quote)를 첨부하며 — 실제 건설 업체(비식별화됨)에서 파생된 버전 관리되는 가격표에 기반한 결정적 가격 엔진이 1센트까지 계산합니다.

왜 존재하는가

대부분의 AI 데모는 당신이 그들을 믿기를 요구합니다. Oficio는 대신 검증되도록 설계되었습니다:

(이 README의 평가 표는 python -m oficio.evals.report로 생성되며 — 수작업으로 작성되지 않습니다.)

Related MCP server: IntentForge MCP Server

상태 — 정직하고 공개적으로

v1.0 — 162개 테스트 통과, 평가 스위트가 실제 모델로 실행되었습니다: 모든 게이트를 통과했습니다.

완료 및 검증됨:

• 결정적 엔진 — Decimal 금액 계산, 개별 자재의 정수 단위 청구(시멘트 3.2포대를 살 수는 없습니다), 최소 마진 강제, 가격이 없는 항목은 needs_info, 콘텐츠 해시 기반 재현 가능한 견적 ID. CI에서 30개의 고정 골든 견적을 1센트까지 재현합니다.

• 강화된 모델 클라이언트 — 오류 시 차단되는 가격 책정(가격표에 없는 모델은 예외를 발생시키며 결코 $0이 되지 않습니다), 호출 전에 일일 예산 초과 거부, 429/5xx에 대해서만 지수 백오프, 호출당 하나의 JSONL 추적(tokens, 비용, 지연 시간 포함).

• 필수 증거가 있는 추출 — 모델은 카탈로그에서만 ID를 선택할 수 있으며, 모든 항목은 고객의 말을 그대로 인용해야 합니다. 대화 기록에서 찾을 수 없는 증거는 버려지고 질문으로 전환됩니다.

• 평가 스위트 — 레이블된 대화 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"])

python -m oficio.service.mcp_tools로 stdio MCP 서버로 실행합니다.

아키텍처

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가 포함됩니다. 증거가 없는 항목은 기능이 아니라 평가 실패입니다.

• 모든 곳에서 오류 시 차단 — 알 수 없은 항목 → needs_info (절대 추정하지 않음); 가격 항목이 없은 모델 → 예외 (절대 $0이 아님); 비밀 정보 누락 → 시작 거부.

• v1에 데이터베이스 없음 — JSON 가격표와 JSONL 추적으로 MVP에는 충분합니다. 의도적으로 범위에서 제외: 결제, 인증, 멀티 테넌시, 스케줄링, 두 번째 업종.

로드맵

v1에서 의도적으로 범위를 벗어난 것과 그 이유: 결제 (견적이 제품이며, 수금은 별개의 문제), 인증 및 멀티 테넌시 (하나의 업체, 하나의 가격표 — 두 번째 업체가 존자하기 전까지는 추측입니다), 스케줄링 (고유한 실패 모드를 가진 다른 도메인), 두 번째 업종 (요점은 패턴을 한 번, 제대로 증명하는 것입니다).

실제로 다음 단계: 구성된 대화가 아닌 실제 대화 기록에서 구축한 레이블 세트 — 현재 수치는 이 분포를 측정하지 실제 환경을 측정하지 않습니다 — 그리고 두 번째 업체에 대한 가격표 보정, 그것이 작동하는 엔진을 제품으로 바꿀 것입니다.

출처 및 정직성

가격표는 가족 리모델링 업체의 실제 운영에서 파생되었으며, 이름은 제거되고 가격은 항목별 변동과 함께 공개되지 않은 계수로 조정되었습니다 — 현실적인 비율, 보호된 사업. 비식별화 파이프라인은 설계상 비공개이며 CI의 누출 게이트 테스트로 강제됩니다.

평가 대화는 템플릿에서 구성된 것이지 실제 고객의 대화 기록이 아닙니다. 그 덕분에 재현 가능하고 게시 가능하며, 보고된 정확도는 이 분포에 대한 정확도임을 의미합니다. 출처가 모호한 벤치마크는 누구도 신뢰해서는 안 되는 벤치마크이기 때문에 여기에 분명히 밝힙니다.

Brayan Molina가 스펙 주도 개발과 Claude Code로 구축했습니다. MIT 라이선스.