Skip to content

Commit 6392449

Browse files
committed
feat(routing): add validated routing policy profiles (RI-04)
1 parent a594938 commit 6392449

12 files changed

Lines changed: 1337 additions & 10 deletions

File tree

‎devlog/_plan/260804_router_intelligence/001_pr_stack_status.md‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ head SHA, PR number/URL, verification result, and review state.
1010
- Bun: `1.3.14`; package version: `2.10.0`
1111
- Worktree: `D:\codex-worktrees\ocx-router-intelligence`
1212
- Push remote: `origin` (Wibias/opencodex); PR target: `lidge-jun/opencodex:dev`
13-
- Programme stack: #1003 (RI-01) and #1004 (RI-02) merged to `dev`; #1005 (RI-03) open.
13+
- Programme stack: #1003 (RI-01), #1004 (RI-02), and #1005 (RI-03) merged to
14+
`dev`; #1011 (RI-04) open.
1415

1516
## Related in-flight PRs (not superseded by this stack)
1617

@@ -41,8 +42,8 @@ other; closing one is a maintainer decision and neither is stale.
4142
|---|---|---|---|---|---|---|
4243
| RI-01 | `feat/ri-01-route-decision-traces` | `e44d234f0` | `b5a8e7c4c` | #1003 | https://github.com/lidge-jun/opencodex/pull/1003 | MERGED |
4344
| RI-02 | `feat/ri-02-request-history-index` | `dev` (post-#1003 merge) | `2a72aa4a9` | #1004 | https://github.com/lidge-jun/opencodex/pull/1004 | MERGED |
44-
| RI-03 | `feat/ri-03-routing-analytics` | `dev` (post-#1004 merge) | pending | #1005 | https://github.com/lidge-jun/opencodex/pull/1005 | OPEN (resync) |
45-
| RI-04 | `feat/ri-04-policy-profile-core` | `feat/ri-03` head | pending | pending | pending | queued |
45+
| RI-03 | `feat/ri-03-routing-analytics` | `dev` (post-#1004 merge) | `a594938c5` | #1005 | https://github.com/lidge-jun/opencodex/pull/1005 | MERGED |
46+
| RI-04 | `feat/ri-04-policy-profile-core` | `dev` (post-#1005 merge) | `31c9f0b28` | #1011 | https://github.com/lidge-jun/opencodex/pull/1011 | OPEN (resync) |
4647
| RI-05 | `feat/ri-05-capability-aware-routing` | `feat/ri-04` head | pending | pending | pending | queued |
4748
| RI-06 | `feat/ri-06-health-aware-routing` | `feat/ri-05` head | pending | pending | pending | queued |
4849
| RI-07 | `feat/ri-07-quota-aware-routing` | `feat/ri-06` head | pending | pending | pending | queued |
@@ -143,3 +144,28 @@ other; closing one is a maintainer decision and neither is stale.
143144
- Focused regression suites: 144/144 pass across 6 files
144145
- `bun run privacy:scan`: passed
145146
- Remaining Low findings: none
147+
148+
### RI-04 - feat/ri-04-policy-profile-core
149+
150+
- Base SHA: `2069e724ec27e176644a11ff55bef307f5ebe3bf` (RI-03 head)
151+
- Reviewed commit: same as final (author self-review before push)
152+
- Findings (self-review): 4 fixed pre-push - (1) `serviceTier` evidence type
153+
was `Unknownable` (number|boolean) but service tiers are strings - trace
154+
type narrowed to `string | "unknown"`; (2) alias validation missed the
155+
reserved `combo/` namespace prefix; (3) trace candidates did not carry
156+
`score` - added `score` to `TraceCandidateInput`/`buildCandidate`;
157+
(4) test expectation for weight normalization used wrong math (unspecified
158+
weights keep defaults; sum 4.35 not 4).
159+
- Final commit: pending (recorded after commit)
160+
- PR: pending
161+
- Verification:
162+
- `bun x tsc --noEmit`: PASSED (0 errors)
163+
- `bun run test tests/routing-profile.test.ts`: 12/12 pass (validation,
164+
normalization, revision digest, collisions, config load, id/alias
165+
resolution, dry-run eligibility/unknown/tie-break, API list+dry-run,
166+
API error codes)
167+
- Focused regression suites: 176/176 pass across 8 files
168+
- `bun run privacy:scan`: passed
169+
- `tests/config.test.ts`: 109/115 pass; the 6 symlink failures reproduce
170+
identically on the pristine base (Windows symlink EPERM, environmental)
171+
- Remaining Low findings: none

‎docs-site/src/content/docs/reference/configuration/routing.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Routing turns the model id sent by a client into one concrete provider and upstr
1111
| --- | --- | --- | --- |
1212
| `defaultProvider` | `string` | `"openai"` | Final provider used when no earlier model rule matches. It must name an enabled configured provider. |
1313
| `combos?` | `Record<string, OcxComboConfig>` | `{}` | Virtual `combo/<id>` models built from ordered provider/model targets. |
14+
| `routingProfiles?` | `Record<string, OcxRoutingProfileConfig>` | `{}` | Virtual `policy/<id>` models that select among an explicit candidate allowlist using hard capability requirements and deterministic scoring. |
1415

1516
## Model resolution order
1617

@@ -82,6 +83,69 @@ namespace, and cannot use reserved bare native families such as `gpt-*`, `o1-*`,
8283
For strategy behavior, retryable failures, cooldowns, encrypted v2 task limits, and management
8384
commands, see [Combos](/guides/combos/).
8485

86+
## Routing policy profiles (`config.routingProfiles`)
87+
88+
Routing policy profiles are the Router Intelligence selection layer: an explicitly requested
89+
`policy/<id>` (or configured alias) chooses among a fixed candidate allowlist using hard capability
90+
requirements and deterministic, explainable scoring. Existing model ids are **never** routed through
91+
a profile implicitly - policy routing only activates when the client requests a policy model id.
92+
93+
Each key is an id matching `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`, always addressable as `policy/<id>`,
94+
with one optional `alias`. Aliases must be unique and cannot collide with configured providers,
95+
combos, codex account namespaces, the `policy/` namespace, or reserved bare native families
96+
(`gpt-*`, `o1-*`, `o3-*`, `o4-*`, `codex-*`).
97+
98+
| Key | Type | Default | Meaning |
99+
| --- | --- | --- | --- |
100+
| `candidates` | `{ provider: string; model: string }[]` | required | Explicit allowlist of `provider/model` refs. No implicit expansion. |
101+
| `alias?` | `string` | — | Optional public model id in place of `policy/<id>`. |
102+
| `require?` | object | `{}` | Hard capability requirements evaluated before scoring (see below). |
103+
| `optimize?` | object | latency 0.55, health 0.25, cost 0.10, quota 0.10 | Scoring weights; normalized deterministically. |
104+
| `limits?` | object | — | Hard limits, e.g. `maxEstimatedCostUsd`. |
105+
| `unknownEvidence?` | object | capability `exclude`, health/quota/cost `penalize` | How unknown evidence is treated per dimension: `allow`, `penalize`, or `exclude`. Unknown never becomes zero. |
106+
107+
`require` supports: `minContextWindow` (positive integer), and the booleans `tools`, `imageInput`,
108+
`structuredOutput`, `localOnly`, `remoteAllowed`, `encryptedCodexTasks`; plus `reasoningEffort` and
109+
`serviceTier` strings.
110+
111+
```json
112+
{
113+
"routingProfiles": {
114+
"fast": {
115+
"alias": "ocx/fast",
116+
"candidates": [
117+
{ "provider": "anthropic", "model": "claude-sonnet-5" },
118+
{ "provider": "openai", "model": "gpt-5.6-sol" }
119+
],
120+
"require": { "tools": true, "minContextWindow": 128000 },
121+
"optimize": { "latency": 0.55, "health": 0.25, "cost": 0.10, "quota": 0.10 },
122+
"limits": { "maxEstimatedCostUsd": 0.50 },
123+
"unknownEvidence": {
124+
"capability": "exclude",
125+
"health": "penalize",
126+
"quota": "penalize",
127+
"cost": "penalize"
128+
}
129+
}
130+
}
131+
}
132+
```
133+
134+
CLI: `ocx route policy list`, `ocx route policy show <id>`, and
135+
`ocx route policy dry-run <id> --model-context <tokens> --tools`. Dry-run evaluates candidates
136+
without sending any upstream request.
137+
138+
### Combos vs policy profiles
139+
140+
- A **combo** is explicit ordered/weighted target routing and failover: the configured order (or
141+
smooth weighted round-robin) decides, and failures advance through the list.
142+
- A **policy profile** is evidence-based selection among configured candidates: hard capability
143+
requirements filter first, then deterministic scoring ranks the survivors.
144+
145+
Both are virtual namespaces with aliases and collision validation; they differ in *how* a candidate
146+
is chosen. Profile scoring expands in capability (RI-05), health (RI-06), quota (RI-07), and cost
147+
(RI-08) dimensions, each recorded in the per-request route-decision trace.
148+
85149
### Catalog eligibility
86150

87151
A combo remains directly routable even when it cannot be listed. `ocx sync`, `/v1/models`, and the

‎src/cli/index.ts‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1007,13 +1007,18 @@ switch (command) {
10071007
break;
10081008
}
10091009
case "route": {
1010-
if (args[1] !== "combo") {
1011-
console.error("Usage: ocx route combo <subcommand>");
1010+
if (args[1] !== "combo" && args[1] !== "policy") {
1011+
console.error("Usage: ocx route <combo|policy> <subcommand>");
10121012
process.exitCode = 2;
10131013
break;
10141014
}
1015-
const { handleComboCommand } = await import("./combo");
1016-
process.exitCode = await handleComboCommand(args.slice(2));
1015+
if (args[1] === "combo") {
1016+
const { handleComboCommand } = await import("./combo");
1017+
process.exitCode = await handleComboCommand(args.slice(2));
1018+
} else {
1019+
const { handleRoutePolicyCommand } = await import("./route-policy");
1020+
process.exitCode = await handleRoutePolicyCommand(args.slice(2));
1021+
}
10171022
break;
10181023
}
10191024
case "agent": {

‎src/cli/route-policy.ts‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
import {
2+
CliUsageError,
3+
printData,
4+
rejectArgs,
5+
runCliAction,
6+
runtimeRequest,
7+
takeFlag,
8+
takeIntegerOption,
9+
type RuntimeApiDeps,
10+
} from "./runtime-api";
11+
12+
const USAGE = `Usage:
13+
ocx route policy list [--json]
14+
ocx route policy show <id> [--json]
15+
ocx route policy dry-run <id> [--model-context <tokens>] [--tools]
16+
[--image] [--structured-output] [--json]`;
17+
18+
interface ProfileRow {
19+
id?: string;
20+
model?: string;
21+
revision?: string;
22+
}
23+
24+
async function list(argv: string[], deps: RuntimeApiDeps): Promise<void> {
25+
const args = [...argv];
26+
const wantsJson = takeFlag(args, "--json");
27+
rejectArgs(args, USAGE);
28+
const result = await runtimeRequest<{ profiles?: ProfileRow[] }>("/api/routing-profiles", {}, deps);
29+
const rows = result.profiles ?? [];
30+
printData(
31+
result,
32+
wantsJson,
33+
rows.length
34+
? rows.map(row => `${String(row.id)} ${String(row.model ?? `policy/${row.id}`)} rev:${String(row.revision ?? "-")}`)
35+
: ["No routing profiles configured."],
36+
);
37+
}
38+
39+
async function show(argv: string[], deps: RuntimeApiDeps): Promise<void> {
40+
const args = [...argv];
41+
const id = args.shift();
42+
const wantsJson = takeFlag(args, "--json");
43+
if (!id) throw new CliUsageError("profile id is required", USAGE);
44+
rejectArgs(args, USAGE);
45+
const result = await runtimeRequest<{ profiles?: ProfileRow[] }>("/api/routing-profiles", {}, deps);
46+
const profile = (result.profiles ?? []).find(candidate => candidate.id === id);
47+
if (!profile) throw new CliUsageError(`unknown routing profile: ${id}`, USAGE);
48+
printData(profile, wantsJson, wantsJson ? undefined : [JSON.stringify(profile, null, 2)]);
49+
}
50+
51+
async function dryRun(argv: string[], deps: RuntimeApiDeps): Promise<void> {
52+
const args = [...argv];
53+
const id = args.shift();
54+
const wantsJson = takeFlag(args, "--json");
55+
if (!id) throw new CliUsageError("profile id is required", USAGE);
56+
const modelContext = takeIntegerOption(args, "--model-context", { min: 1 });
57+
const tools = takeFlag(args, "--tools");
58+
const image = takeFlag(args, "--image");
59+
const structuredOutput = takeFlag(args, "--structured-output");
60+
rejectArgs(args, USAGE);
61+
const result = await runtimeRequest(
62+
"/api/routing-profiles/dry-run",
63+
{
64+
method: "POST",
65+
headers: { "content-type": "application/json" },
66+
body: JSON.stringify({
67+
profile: id,
68+
evidence: {
69+
...(modelContext !== undefined ? { contextWindow: modelContext } : {}),
70+
...(tools ? { toolsRequired: true } : {}),
71+
...(image ? { imageInputRequired: true } : {}),
72+
...(structuredOutput ? { structuredOutputRequired: true } : {}),
73+
},
74+
}),
75+
},
76+
deps,
77+
);
78+
printData(result, wantsJson, wantsJson ? undefined : [JSON.stringify(result, null, 2)]);
79+
}
80+
81+
export async function handleRoutePolicyCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
82+
return runCliAction(async () => {
83+
const [sub, ...rest] = argv;
84+
if (sub === "list") await list(rest, deps);
85+
else if (sub === "show") await show(rest, deps);
86+
else if (sub === "dry-run") await dryRun(rest, deps);
87+
else throw new CliUsageError(`unknown route policy command: ${sub ?? ""}`, USAGE);
88+
});
89+
}

‎src/config.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import {
1313
MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET,
1414
} from "./codex/account-namespace-match";
1515
import { COMBO_NAMESPACE, comboConfigIssues } from "./combos/types";
16+
import { routingProfileIssues } from "./routing/profile";
1617
import {
1718
forgetEphemeralSecretPath,
1819
hardenSecretDir,
@@ -1261,6 +1262,27 @@ const configSchema = z.object({
12611262
}
12621263
}
12631264
}
1265+
const routingProfiles = (config as { routingProfiles?: unknown }).routingProfiles;
1266+
if (routingProfiles !== undefined) {
1267+
if (!routingProfiles || typeof routingProfiles !== "object" || Array.isArray(routingProfiles)) {
1268+
ctx.addIssue({ code: "custom", path: ["routingProfiles"], message: "routingProfiles must be an object" });
1269+
} else {
1270+
for (const [id, raw] of Object.entries(routingProfiles as Record<string, unknown>)) {
1271+
for (const issue of routingProfileIssues(id, raw, {
1272+
providers: config.providers,
1273+
combos: combos as Record<string, import("./types").OcxComboConfig> | undefined,
1274+
routingProfiles: routingProfiles as Record<string, import("./types").OcxRoutingProfileConfig>,
1275+
codexAccountNamespaces: accountNamespaces,
1276+
}, { excludeProfileId: id })) {
1277+
ctx.addIssue({
1278+
code: "custom",
1279+
path: ["routingProfiles", id, ...issue.path],
1280+
message: issue.message,
1281+
});
1282+
}
1283+
}
1284+
}
1285+
}
12641286
});
12651287

12661288
/**

0 commit comments

Comments
 (0)