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 |
P2.01 — FX rates
Section titled “P2.01 — FX rates”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.mdInputs;../architecture/backend-scope.mdsection 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.
P2.02 — Model catalog sync
Section titled “P2.02 — Model catalog sync”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_idis stored separately from our public id -
Spec:
../architecture/backend-scope.mdsection 5;../architecture/db-schema.md4.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.mdInputs; 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.
P2.04 — Markup rules engine
Section titled “P2.04 — Markup rules engine”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.mdMarkup 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).
P2.05 — Daily rates job
Section titled “P2.05 — Daily rates job”Who: Agent · Needs: P2.01–P2.04
For each enabled model, token type and enabled currency:
- take the cost
- convert with today’s FX
- apply the markup
- round up the price per 1M tokens to the currency’s
rate_sig_figssignificant figures (revised 2026-11-01;pricing-model.md, Rounding) - append to
published_ratesand updatecurrent_rates
Publish only for models that are on. Keep the pre-rounding rate so the rounding can be explained.
- Spec:
../product/pricing-model.mdDaily Rate Computation, Rounding, Model availability;../architecture/db-schema.md4.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.mdWorkspace Discounts;../product/build-inventory.mdCross-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.