Skip to content

Phase 2 — Pricing Core

Goal: the daily rate pipeline. It needs FX rates, the model catalog and gateway cost inputs, then the markup rules, and produces a published per-token rate in credits per model, token type and currency.

Done when: in staging, the daily rates job publishes a rate for at least one enabled model in at least one currency, and the request path can read it.

The jobs here are written as plain functions with tests. They are registered with the scheduled-job dispatcher in P4.02, and can be run by hand until then.

ID Task Who Needs Status
P2.01 FX rates Agent P1.03 merged — code #12; needs updating for multiple providers (Mansa, Frankfurter, manual), official and parallel rates, and rate basis (decided 2026-11-02; Q3.7)
P2.02 Model catalog sync Agent P1.03, P1.09, P0.13 merged — code #42 (the catalog sync job; skips without a bound gateway)
P2.03 Bifrost adapter: model list and cost inputs Agent P1.09, P0.13 merged — code #71 (listModels from /api/models/details; allow-list code #70, live since the route-split upgrade, 2026-11-05)
P2.04 Markup rules engine Agent P1.03 merged — code #10, code #59 (#16 closed, replaced by #59)
P2.05 Daily rates job Agent P2.01–P2.04 merged — code #42; published rates record fx_markup_rule_id (code #74); FX age by the run’s date code #103
P2.06 Discount and credit-move rate helpers Agent P2.04 merged — through code #12 and code #59 (#11 closed: its commit reached main through #12); staff credit moves use it since code #74

Who: Agent · Needs: P1.03

Fetch rates for every enabled currency against USD from its providers in order (Mansa hourly, Frankfurter, manual), storing the official and parallel rates with the provider on each row (pricing-model.md FX Rates and Providers; db-schema.md fx_rates). Each provider’s adapter maps its own field names to our columns, with a test; confirm Mansa’s on a real response first. Support a manual override (admin screen 44 uses it later), and flag a rate that is stale or moves outside a sane band.

  • Spec: ../product/pricing-model.md Inputs; ../architecture/backend-scope.md section 5; ../architecture/observability.md (rates job alerts)
  • Done when: the job stores today’s rates with their provider, a test covers a provider being down (the next provider is tried; with none left, yesterday’s rate is kept and flagged), an inverted parallel quote is refused, the daily value is the median of the day’s samples for the currency’s basis, and an override wins over the fetched rate.

Who: Agent · Needs: P1.03, P1.09, P0.13

Read the configured models through the Gateway interface into models:

  • new models start off

  • models no longer listed get in_catalog = false

  • gateway_model_id is stored separately from our public id

  • Spec: ../architecture/backend-scope.md section 5; ../architecture/db-schema.md 4.3; decisions log, v1 model list, Model availability enforcement

  • Done when: a sync against staging Bifrost fills models, a second run changes nothing, and a removed model is marked out of catalog without being deleted.

P2.03 — Bifrost adapter: model list and cost inputs

Section titled “P2.03 — Bifrost adapter: model list and cost inputs”

Who: Agent · Needs: P1.09, P0.13

Implement listModels in the Bifrost adapter. It returns the cost input per model and token type, taken as the highest across the providers Bifrost fronts for that model. It reaches Bifrost through the management binding. This is the adapter’s first method; the rest come in P3.01 and P5.07.

  • Spec: ../product/pricing-model.md Inputs; P0.13’s verification results
  • Done when: the costs returned for staging models match Bifrost’s pricing, and a model with cost 0 is reported as unpriced rather than as zero.

Revised 2026-10-26: includes the FX markup (scope fx, percentage, global or per currency), applied to the FX leg of every price; a missing FX markup is an error (decisions log, FX markup). Who: Agent · Needs: P1.03

Resolve the markup for a model and currency. Rules are flat or percentage, scoped global, currency, model or transfers; the most specific wins and broader scopes are the fallback. No markup values are hard-coded.

  • Spec: ../product/pricing-model.md Markup Configuration; decisions log, Markup configuration
  • Done when: unit tests cover every scope combination, flat versus percentage, and “no rule” (an explicit error, never a silent zero).

Who: Agent · Needs: P2.01–P2.04

For each enabled model, token type and enabled currency:

  1. take the cost
  2. convert with today’s FX
  3. apply the markup
  4. round up the price per 1M tokens to the currency’s rate_sig_figs significant figures (revised 2026-11-01; pricing-model.md, Rounding)
  5. append to published_rates and update current_rates

Publish only for models that are on. Keep the pre-rounding rate so the rounding can be explained.

  • Spec: ../product/pricing-model.md Daily Rate Computation, Rounding, Model availability; ../architecture/db-schema.md 4.3
  • Done when:
    • staging has current rates
    • the job is idempotent within a day
    • a model with no cost input or no markup rule produces no rate and is reported
    • tests pin the rounding

P2.06 — Discount and credit-move rate helpers

Section titled “P2.06 — Discount and credit-move rate helpers”

Who: Agent · Needs: P2.04

Two pure functions, used in later phases:

  • Workspace discount at hold time: a model-specific discount wins, discounts never stack.
  • Credit-move rate: mid-market rates chained through USD, with the FX markup applied on each non-USD leg against the customer (decisions log, FX markup). Moves are staff-only (Credit moves are support-only).
  • Spec: ../product/pricing-model.md Workspace Discounts; ../product/build-inventory.md Cross-currency moves
  • Done when: unit tests cover ZAR→ZMW via USD with the FX markup on each leg, and model-specific versus workspace-wide discounts.