Quoters

One contract, three quoters

The same service written three times, in Go, TypeScript and Python. Each takes a cart in free text and answers a priced quote or a refusal, through the same stages, the same prompts and the same rules.

Overview

A quoter is one stateless HTTP service: a cart goes in (POST /v1/quotes), a quote comes out, or a 422 problem saying which stage refused the cart. Inside, it runs the pipeline of the Architecture page: prepare, guard, parse beside recount, identify, judge, price. Models read; code counts and prices. The web app's BFF talks to one quoter at a time, and any of the three will do.

Why three. The implementations are compared on measurements (accuracy, latency, cost, from the system bench of e2e/), not on opinions. Holding three of them to one suite also shows where the contract or the shared rules are ambiguous: a rule two languages read differently gets written down.

What they share.

• The contract, api/openapi.yaml: routes, bodies, problem codes, headers. Each quoter derives its types from it in its own way (below).
• The prompts, prompts/: every word put to a model, one JSON file per stage. /healthz reports each file's version (the first 8 hex digits of its SHA-256), and the suite fails a quoter that runs other prompts.
• The fake engines (ENGINES=fake): deterministic stand-ins for Jev and the LLMs, with the same rules in the three, driven by #fake: lines in the cart. No key, no cost.
• The end-to-end suite in e2e/, black box, run against each quoter on the fake engines (task e2e:all), and the shared cases.
• The trace shape in Langfuse (Usage, cost and traces): one trace named quote per request, an agent root tagged quoter:… and engines:…, with the user, the session and the cart as prepared for input and the response body as output; one observation per stage, typed for Langfuse's graph (guard a guardrail; parse, recount, identify chains; judge an evaluator); one generation per model call with the cost OpenRouter billed; and four scores on the trace, cost_usd, latency_ms, attempts and outcome. A dashboard reads the three alike.

Each one listens on its own port. The buttons open its /healthz, which names the implementation, the engines, the tracing and the prompt versions.

• Go /healthz quoters/go · :24791 · checking…
• TypeScript /healthz quoters/typescript · :24793 · checking…
• Python /healthz quoters/python · :24792 · checking…

Differences, side by side

Every cell is read from the quoter's code, manifest or Dockerfile. Rows with an amber edge are where the three made different choices of design, not only of library.

How these were measured, on 2 October 2026, with task ci green and every test passing. Lines: non-blank lines, comments included (grep -cv '^\s*$') over *.go, *.ts or *.py; source is cmd/delorean and internal/ for Go, src/ otherwise; tests are *_test.go, test/, tests/. Tests: tests run, as each runner counts them (go test -json, Vitest's JSON report, pytest). Images: docker images for delorean-quoter-go, -typescript and -python as Docker Compose builds them. All three move with the code. Load: task bench:load on 3 October 2026, each image alone with --cpus 1 or 4 and 512 MB, fake engines with FAKE_LATENCY=real, 200 clients in a closed loop; the method and every step are in Testing, Load bench.

Code structure

One section per quoter: a trimmed tree, then thirteen key functions in the same order in the three, so that a step reads across. Links open the file on GitHub at the function's line, on main.

Go

quoters/go/
├── cmd/delorean/main.go     serve | version: config, telemetry, engines, http.Server
├── cmd/bench/               the component benches' command, not the service
└── internal/
    ├── httpapi/             the contract's surface
    │   ├── openapi.gen.go   generated by oapi-codegen: ServerInterface, models
    │   ├── quotes.go        POST /v1/quotes: headers, strict body, pipeline, answer
    │   ├── httpapi.go       New, /healthz, /v1/catalog
    │   ├── middleware.go    X-Request-Id, a log line per request, 404 and 405
    │   └── problem.go       RFC 9457 problems
    ├── prepare/prepare.go   Normalize, the o200k_base Counter
    ├── pipeline/            the order of the stages, every rule that decides
    │   ├── pipeline.go      Quote, read, Merge, Identify, Recounted
    │   ├── reading.go       readAgain, readTwice, judge and its memo
    │   ├── ports.go         the engines' interfaces, Weigh
    │   ├── rejection.go     Rejection and its codes
    │   └── trace.go         the quote's trace, the stages' typed spans
    ├── live/                engines on OpenRouter
    │   ├── parse.go         Parser: one call to trpc-agent-go's OpenAI model
    │   ├── guard.go, identify.go, judge.go   the Jev questions
    │   └── prompts.go       the embedded prompts/, checked and versioned
    ├── decide/              the Jev client: HTTP, DecideAll, WithRetry
    ├── fake/fake.go         ENGINES=fake
    ├── pricing/pricing.go   Catalog.Price, in cents
    ├── telemetry/           the Langfuse exporter (trpc-agent-go), Scores
    ├── config/, cart/       the environment; Film, Mention, Line
    └── bench/               the bench harness: subjects, runs, reports

1. Request handlerinternal/httpapi/quotes.go

   func (s *server) CreateQuote(w http.ResponseWriter, r *http.Request, params CreateQuoteParams)

   The generated ServerInterface's method. Checks the three headers, decodes the body strictly with readCart (valid UTF-8, one object, no unknown field), and gives the pipeline a context.WithTimeout and an Answer callback: s.answer builds the response (200, a *pipeline.Rejection 422, ErrEngine 502) inside the trace, which keeps it as its output.

2. Prepareinternal/prepare/prepare.go

   func Normalize(text string) string

   LF line ends; control and format characters dropped but \n, \t and the two joiners; NFC with golang.org/x/text; trimmed.

3. Token countinternal/prepare/prepare.go

   func (c *Counter) Count(text string) int

   Splits with the o200k_base pattern (regexp2, which has the lookahead it needs) and counts each piece with tokens: tiktoken's merge order, kept in a typed binary heap over a linked list of parts.

4. Quoteinternal/pipeline/pipeline.go

   func (p *Pipeline) Quote(ctx context.Context, req Request) (Quote, error)

   Opens the trace (startTrace), runs read (prepare, guard, the read-again loop, price), fills the report, ends the trace with the answer and hands the measures to Measured. A refusal comes back as the error, a *Rejection carrying its report; an engine failure wraps ErrEngine.

5. Read-again loopinternal/pipeline/reading.go

   func (p *Pipeline) readAgain(ctx context.Context, r *run, text string) (Reading, error)

   Up to ReadAttempts readings: readTwice, identify, judge. Stops at the first judgement at the threshold or above; otherwise the next parse gets a Retry with its raw reading and the failing findings.

6. Guard decisioninternal/pipeline/ports.go

   func Weigh(q GuardQuestions) GuardVerdict

   The verdict of Jev's two answers: injection = steer, valid = (1 − steer) × order, invalid = (1 − steer) × (1 − order); a tie goes to the refusal. The engine calls it (live.Guard.Check); read then refuses below GuardMinConfidence through guardRejection.

7. Parse and recountinternal/pipeline/reading.go

   func (p *Pipeline) readTwice(ctx context.Context, r *run, text string, attempt int, again *Retry) (raw, reading, recount []cart.Mention, err error)

   Two wg.Go goroutines: the parser and the blind recounter, each a live.Parser.Parse (one GenerateContent call on trpc-agent-go's OpenAI model). A parse that fails cancels the recount; Merge refuses a title over the copy limit.

8. Identifyinternal/pipeline/pipeline.go

   func Identify(ctx context.Context, id Identifier, known map[string]Identification, readings ...[]cart.Mention) ([][]cart.Line, Usage, error)

   Asks only the titles known lacks, from the reading and the recount in one call, then remembers them: no title is identified twice in a request. On Jev, live.Identifier.Identify sends one request per title.

9. Judge and its memointernal/pipeline/reading.go

   func (p *Pipeline) judge(ctx context.Context, r *run, n int, text string, judged map[string]Judgement, lines, recounted []cart.Line) (Judgement, error)

   Puts a reading to Jev (live.Judge.Judge: asked and identity per line, missing for the whole) only when judged lacks its readingKey; a reading seen before is reused through inLineOrder. Recounted then adds the count checks.

10. Pricinginternal/pricing/pricing.go

    func (c Catalog) Price(lines []cart.Line) Quote

    Unit prices in integer cents, then the highest saga tier the distinct volumes reach, taken off the saga lines only, rounded half up.

11. Fake enginesinternal/fake/fake.go

    func New() pipeline.Engines

    A guard on injection marks, a reader of one mention per line, an identifier of the English titles, a judge driven by the #fake: lines.

12. Trace setupinternal/telemetry/telemetry.go

    func Start(ctx context.Context) (shutdown func(context.Context) error, enabled bool, err error)

    Starts trpc-agent-go's Langfuse exporter when LANGFUSE_* is set; until then its tracer is a no-op. main then sets Pipeline.Measured to a telemetry.NewScores queue. Each model call is a generation: Parser.call for the LLMs, decide.HTTP.Decide for Jev.

13. Trace shapeinternal/pipeline/trace.go

    func (p *Pipeline) startTrace(ctx context.Context, req Request) (context.Context, trace.Span)

    The agent root named quote, tagged quoter:go and engines:…, with the request id, the prompt versions, the user and the session. startStage types each stage from observationTypes; endTrace sets the body sent, the outcome, the attempts and the total; Scores.Quote queues the four scores.

TypeScript

quoters/typescript/
├── src/
│   ├── main.ts              serve | version: config, tracing, prompts, engines, server
│   ├── config.ts            the environment, checked
│   ├── http/
│   │   ├── app.ts           createApp: Hono routes, the quote's trace, problems
│   │   ├── body.ts          readBody, decodeQuoteRequest
│   │   └── contract.ts      the pipeline's values in the contract's types
│   ├── generated/openapi.ts generated by openapi-typescript
│   ├── prepare/
│   │   ├── normalize.ts     normalize
│   │   └── tokens.ts        TokenCounter, the heap merge
│   ├── pipeline/
│   │   ├── pipeline.ts      Pipeline, Run, the read-again loop
│   │   ├── reading.ts       verdictOf, merge, Identifications, countFindings
│   │   ├── ports.ts         the engines' interfaces, EngineError
│   │   └── rejection.ts     Rejection, Report
│   ├── engines/
│   │   ├── live/index.ts    liveEngines
│   │   ├── live/jev.ts      the Jev client, over fetch
│   │   ├── live/questions.ts jevGuard, jevIdentifier, jevJudge
│   │   ├── live/reader.ts   llmReader: openai SDK, Ajv
│   │   └── fake.ts          ENGINES=fake
│   ├── prompts.ts           loadPrompts, promptVersions
│   ├── pricing.ts           price, in cents
│   ├── telemetry/           langfuse.ts: startTracing, scores; trace.ts: observe
│   └── cart.ts, text.ts, log.ts
└── test/                    Vitest, one file per area

1. Request handlersrc/http/app.ts

   app.post('/v1/quotes', async (c) => …)    // in createApp(config: AppConfig): Hono<Env>

   Checks the headers against HEADER_FORMATS, reads the body with readBody and decodeQuoteRequest, passes AbortSignal.any of the client's signal and the budget's, and runs quote inside traced: a Rejection is caught as 422, an EngineError as 502; contract.ts maps to the generated types.

2. Preparesrc/prepare/normalize.ts

   export function normalize(text: string): string

   toWellFormed() first, so a lone surrogate reads as U+FFFD as in Go, then the same steps: one Unicode-property regex, normalize('NFC'), trim().

3. Token countsrc/prepare/tokens.ts

   TokenCounter.count(text: string): number

   Splits with js-tiktoken's o200k_base pattern and counts each piece's UTF-8 bytes with #countPiece: the same heap merge, a pair keyed as one number, rank × 2³² + start.

4. Quotesrc/pipeline/pipeline.ts

   Pipeline.quote(request: QuoteRequest, signal: AbortSignal): Promise<Quote>

   Runs #read (prepare, guard, the loop) under the request's span, which the HTTP layer opened: the pipeline traces its stages, not the quote. A refusal is thrown, a Rejection with its report attached, as is an EngineError.

5. Read-again loopsrc/pipeline/pipeline.ts

   #readUntilFaithful(run: Run, text: string): Promise<{ price: Price; judgement: Judgement }>

   The same loop, which also prices: the first reading that passes is priced inside it, and after the last attempt it throws unfaithful_reading.

6. Guard decisionsrc/pipeline/reading.ts

   export function verdictOf({ order, steer }: GuardAnswers): GuardVerdict

   The same weighing, on the pipeline's side: the engine (jevGuard) returns the two raw answers. Pipeline.#pass(v) then lets a confident valid verdict through, or throws.

7. Parse and recountsrc/pipeline/pipeline.ts

   #readTwice(run: Run, text: string, retry: Retry | undefined, first: boolean): Promise<Reading>

   Promise.allSettled of the two stages; a parse that fails aborts the recount through an AbortController. Each reader is an llmReader: the openai SDK, the answer checked with Ajv.

8. Identifysrc/pipeline/reading.ts

   class Identifications { unknown(...readings) · learn(titles, identifications) · lines(mentions) }

   The request's memory of titles: unknown lists what to ask, learn checks and keeps Jev's answers, lines gives each mention its film. On Jev, jevIdentifier.

9. Judge and its memosrc/engines/live/questions.ts

   export function jevJudge(jev: Jev, prompts: Prompts['judge']): Judge

   One request per probe of judgeProbes. The memo lives in #readUntilFaithful: a Map<string, Finding[]> by readingKey, reordered by inLineOrder; countFindings adds the count checks anew.

10. Pricingsrc/pricing.ts

    export function price(catalog: Catalog, lines: readonly Line[]): Price

    The same rules as Go's, written with map, filter and reduce; cents in plain numbers, which stay exact at these sizes.

11. Fake enginessrc/engines/fake.ts

    export function fakeEngines(): Engines

    The same five stand-ins as plain objects; the #fake: lines are named in DIRECTIVE.

12. Trace setupsrc/telemetry/langfuse.ts

    export function startTracing(env: Env): Tracing

    Registers a NodeTracerProvider with Langfuse's span processor when LANGFUSE_* is set, and a LangfuseClient whose score sends the scores. Spans come from observe(name, type, fn, metadata?), found in the async context as Go finds them in a context.Context.

13. Trace shapesrc/http/app.ts

    function traced(c: HonoContext<Env>, request: QuoteRequest, run: (traceId: string | undefined) => Promise<Answered>)

    Opens the root with observe('quote', 'agent', …) and withTraceAttributes, sets the tags, the metadata and the normalized cart, runs the quote, then sets the body as output and sends the four scores through config.tracing.score. The stages' types are OBSERVATION_TYPES, in the pipeline.

Python

quoters/python/
├── src/delorean/
│   ├── __main__.py          serve | version | tokenizer
│   ├── config.py            Settings, from the environment
│   ├── api/
│   │   ├── app.py           create_app, Service: the FastAPI routes
│   │   ├── body.py          header, read_cart
│   │   ├── models.py        the contract's bodies, pydantic, by hand
│   │   ├── answers.py       the pipeline's values as bodies
│   │   └── problems.py, middleware.py   RFC 9457 problems; request id, log line
│   ├── prepare.py           normalize, TokenCounter (tiktoken)
│   ├── pipeline/
│   │   ├── pipeline.py      Pipeline, _Run, the read-again loop
│   │   ├── rules.py         guard_verdict, merge, count_findings, facts
│   │   └── ports.py, outcome.py   the engines' protocols; Quote, Rejection, Report
│   ├── engines/
│   │   ├── __init__.py      open_engines
│   │   ├── live/__init__.py open_live_engines: the httpx and OpenAI clients
│   │   ├── live/jev.py      the Jev client, over httpx
│   │   ├── live/questions.py JevGuard, JevIdentifier, JevJudge
│   │   ├── live/reader.py   LlmReader: openai SDK, pydantic
│   │   └── fake.py          ENGINES=fake
│   ├── prompts.py           load_prompts, pydantic models of the files
│   ├── pricing.py           Catalog.price, in cents
│   ├── tasks.py             all_of: a TaskGroup under a Semaphore
│   ├── telemetry.py         Tracer, NoTracer, LangfuseTracer
│   └── cart.py, logs.py
└── tests/                   pytest; test_contract.py holds models.py to the contract

1. Request handlersrc/delorean/api/app.py

   async def Service.create_quote(self, request: Request) -> Response

   Reads the headers with header and the body with read_cart (a pydantic QuoteRequest), runs the pipeline under asyncio.timeout with a respond callback, so the trace's output is the body sent. Service.body matches the outcome: Quote 200, Rejection 422; EngineError or TimeoutError 502.

2. Preparesrc/delorean/prepare.py

   def normalize(text: str) -> str

   The same steps, with unicodedata.category to drop Cc and Cf and unicodedata.normalize("NFC", …).

3. Token countsrc/delorean/prepare.py

   def TokenCounter.count(self, text: str) -> int

   encode_ordinary of tiktoken's o200k_base, whose Rust merge needs no rewrite. TokenCounter.load refuses a missing or altered vocabulary rather than download it.

4. Quotesrc/delorean/pipeline/pipeline.py

   async def Pipeline.quote(self, request: Request) -> Quote | Rejection

   Opens the quote trace, with its tags and metadata, through the Tracer it holds, and measures the outcome before it returns. A refusal is a value returned, not raised; only an EngineError raises.

5. Read-again loopsrc/delorean/pipeline/pipeline.py

   async def Pipeline._read(self, run: _Run, cart: str, trace: Trace) -> Quote | Rejection

   Prepare, guard, then the loop inline: for attempt in range(1, self.read_attempts + 1), each failed attempt leaving a Retry with the parser's answer and the failing findings.

6. Guard decisionsrc/delorean/pipeline/rules.py

   def guard_verdict(answers: GuardAnswers) -> GuardVerdict

   The same weighing, among the pipeline's rules; max keeps the first of equals, and the refusals come first. Pipeline._guard_rejection builds the refusal.

7. Parse and recountsrc/delorean/pipeline/pipeline.py

   async def Pipeline._read_twice(self, run: _Run, text: str, retry: Retry | None) -> tuple[_Parsed, list[Mention]] | Rejection

   The recount started with asyncio.create_task, the parse awaited beside it, the recount cancelled in finally. Each reader is an LlmReader.read: AsyncOpenAI, the answer validated by pydantic.

8. Identifysrc/delorean/pipeline/pipeline.py

   async def Pipeline._identify(self, run: _Run, memory: _Memory, parsed: list[Mention], recounted: list[Mention]) -> tuple[list[Line], list[Line]]

   Asks only the titles memory.identified lacks, through JevIdentifier.identify, then gives both readings their films with rules.lines.

9. Judge and its memosrc/delorean/pipeline/pipeline.py

   async def Pipeline._judge(self, run: _Run, memory: _Memory, text: str, reading: list[Line], recount: list[Line]) -> Judgement

   The memo is memory.judged, keyed by rules.facts(reading), a frozenset; JevJudge.judge runs only on a miss, and rules.count_findings anew.

10. Pricingsrc/delorean/pricing.py

    def Catalog.price(self, lines: Sequence[Line]) -> Price

    The same rules on frozen dataclasses; the discount in integer division, (base * percent + 50) // 100.

11. Fake enginessrc/delorean/engines/fake.py

    def engines(pace: Pace = INSTANT) -> Engines

    The same stand-ins as classes, the recount a FakeReader(recount=True). Picked by open_engines, an async context manager that, for the live engines, owns the HTTP clients.

12. Trace setupsrc/delorean/telemetry.py

    class LangfuseTracer(*, public_key: str, secret_key: str, base_url: str, exporter: SpanExporter | None = None)

    The Langfuse SDK on a TracerProvider of its own, leaving the global OpenTelemetry state alone; NoTracer stands in without configuration. The pipeline calls trace, span and generation.

13. Trace shapesrc/delorean/pipeline/pipeline.py

    def _measure(self, trace: Trace, run: _Run, request: Request, outcome: Quote | Rejection | str) -> None

    Writes the outcome, the attempts and the total as the trace's metadata, and the four scores with trace.score, which _RecordedTrace sends as create_score, id <trace id>-<name>. The root is opened in Pipeline.quote; the stages' kinds are _SPAN_KINDS.

One request, three ways

One cart, 2 x Back to the Future then Back to the Future Part III on the next line, accepted at the first reading. Each cell is the call chain that step takes; amber-edged rows are where the quoters part ways.

Same stages, same calls to the models, same answer: the two saga volumes earn 10 % off the three DVDs (4 500 − 450 = 4 050 cents), after 9 Jev requests and 2 LLM calls in each quoter. They part ways on four things only:

• Where the trace is made. Go and Python open the quote trace in the pipeline and get the response body back through a callback; TypeScript opens it in the HTTP layer, around a pipeline that traces only its stages. The shape in Langfuse is the same.
• Where the guard is weighed. Go's engine returns a verdict; in TypeScript and Python the engine returns the two raw answers, and the pipeline weighs them.
• How a refusal travels. An error value in Go, an exception in TypeScript, a returned value in Python. In all three, an engine failure is a different kind (ErrEngine, EngineError) and answers 502.
• How work runs side by side and stops. Goroutines under a context.Context, promises under an AbortSignal, asyncio tasks under a TaskGroup and cancellation; the order in which a failure, a refusal and the recount decide is the same.