@oribos/model-router 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @oribos/model-router
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Route `'provider/model'` strings to model instances — the model-routing capability package. A
+parse, a catalog, and the provider packages you already installed; the core keeps no registry
+and no magic strings:
+
+```ts
+import { Agent } from '@oribos/core/agent';
+import { createModelRouter } from '@oribos/model-router';
+import { groq } from '@ai-sdk/groq';
+
+const route = createModelRouter({
+  catalog, // a snapshot of https://models.dev/api.json pastes as-is
+  providers: { groq: (id) => groq(id) }, // your installed provider packages
+});
+
+const agent = new Agent({ name: 'assistant', model: route('groq/llama-3.3-70b-versatile') });
+```
+
+## How it works
+
+- **Parse.** `parseModelString` splits on the **first** slash: model ids may themselves contain
+  slashes (deepinfra-style ids, and groq-hosted ids like `openai/gpt-oss-120b`), so only the
+  first segment is the provider. Anything without that shape is refused — the string stays this
+  package's vocabulary, never the core's.
+- **Resolve.** `createModelRouter({ catalog, providers })` checks the parsed string against the
+  catalog — the provider must be carried, the model id must be listed — then hands the id to your
+  factory and validates the result through the core's model contract (`assertModel`). What the
+  catalog adds over bare parsing is **existence**: unknown providers, unlisted models, and
+  providers whose package you haven't registered are refused at resolution time with actionable
+  errors — including the provider's `npm` package from the catalog when a factory is missing.
+- **Pins kept.** No registry anywhere — the catalog and the factories are caller-brought data,
+  nothing registers and no router exists until you build one. The catalog is a vendored-shape
+  type (`ModelCatalog`); a models.dev snapshot pastes as-is, extra fields pass through. Provider
+  package dependencies travel with you, never with this package or the core. Unconfigured, the
+  package costs nothing and adds nothing to the core.
+
+See `docs/architecture/model.md` (「Provider 生态」) and `examples/model-router` (a committed
+catalog snapshot cut, scripted offline provider stubs).

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * `@oribos/model-router` — the model-routing capability package: `'provider/model'` strings
+ * against a models.dev-style catalog (`docs/architecture/model.md` 篇级字符串路由行,ADR-0017
+ * 追赶面中层;#185).
+ *
+ * The carrying seam is data, not the core: the core's "no registry, no magic string" pins stay
+ * untouched (ADR-0004) — this package owns the parse and the catalog, and both are the caller's
+ * to bring. `parseModelString` splits a routing string on its first slash (model ids may
+ * themselves contain slashes — deepinfra-style ids like `meta-llama/llama-4-scout`); a router
+ * built with `createModelRouter` checks the string against a catalog pasted in as-is (a snapshot
+ * of `https://models.dev/api.json` satisfies the shape) and hands the model id to the factory
+ * you registered for that provider — your installed AI SDK provider package, its dependency
+ * staying yours. What the catalog adds over bare parsing is existence: unknown providers and
+ * unlisted models are refused at resolution time with actionable errors, including the
+ * provider's `npm` package from the catalog when a provider is known but no factory is
+ * registered for it.
+ *
+ * Resolution validates through the core's model contract (`assertModel`) — a factory result that
+ * is not a language model instance of the supported specification version surfaces as the core's
+ * own contract error, never as a mid-run surprise. Zero cost when unconfigured: the package adds
+ * nothing to the core, and a router that is never built never runs.
+ *
+ * Package face: [`parseModelString`], [`ParsedModelString`], [`InvalidModelStringError`],
+ * [`createModelRouter`], [`ModelRouter`], [`ModelRouterConfig`], [`ModelCatalog`],
+ * [`CatalogProviderEntry`], [`CatalogModelEntry`], [`ModelProviderFactory`],
+ * [`UnknownModelProviderError`], [`UnknownModelError`], [`ModelProviderMissingError`].
+ */
+import type { Model } from '@oribos/core/model';
+/** A routing string split into its provider and model halves. */
+export interface ParsedModelString {
+    /** The provider id — everything before the first `/`. */
+    readonly providerId: string;
+    /** The model id — everything after the first `/`, slashes included. */
+    readonly modelId: string;
+}
+/** `parseModelString` on a value that is not a `'provider/model'` string. */
+export declare class InvalidModelStringError extends Error {
+    constructor(value: string);
+}
+/**
+ * Splits a `'provider/model'` routing string on its **first** slash: model ids may themselves
+ * contain slashes (deepinfra-style ids like `meta-llama/llama-4-scout`), so only the first
+ * segment is the provider. Pure — no catalog, no providers, just the parse.
+ */
+export declare function parseModelString(value: string): ParsedModelString;
+/** One model's catalog entry. Only the record key is load-bearing; the rest is pasted through. */
+export interface CatalogModelEntry {
+    /** The model's display name, if the catalog carries one. */
+    readonly name?: string | undefined;
+    /** The model's window limits, if the catalog carries them. */
+    readonly limit?: {
+        readonly context?: number;
+        readonly output?: number;
+    } | undefined;
+    /** models.dev snapshots carry more fields than routing consumes; they paste through untouched. */
+    readonly [key: string]: unknown;
+}
+/**
+ * One provider's catalog entry: which npm package serves it, and which model ids exist under it.
+ * A snapshot of `https://models.dev/api.json` satisfies this shape as-is.
+ */
+export interface CatalogProviderEntry {
+    /** The AI SDK provider package that serves this provider — surfaced in missing-factory errors. */
+    readonly npm?: string | undefined;
+    /** The provider's display name, if the catalog carries one. */
+    readonly name?: string | undefined;
+    /** The provider's model ids — the existence check routing resolves against. */
+    readonly models: Readonly<Record<string, CatalogModelEntry>>;
+    /** models.dev snapshots carry more fields than routing consumes; they paste through untouched. */
+    readonly [key: string]: unknown;
+}
+/** The catalog: provider id → provider entry. Data the caller brings (e.g. a models.dev cut). */
+export type ModelCatalog = Readonly<Record<string, CatalogProviderEntry>>;
+/**
+ * The seam your installed provider package rides: called with the model id exactly as the
+ * catalog keys it, returns the language model instance (`(id) => groq(id)` for `@ai-sdk/groq`).
+ * The provider package's dependency travels with you, never with this package or the core.
+ */
+export type ModelProviderFactory = (modelId: string) => unknown;
+/** `createModelRouter` config: the catalog (data) and your factories (the installed packages). */
+export interface ModelRouterConfig {
+    /** Provider id → provider entry; a models.dev snapshot pastes as-is. */
+    readonly catalog: ModelCatalog;
+    /** Provider id → factory from your installed AI SDK provider package. */
+    readonly providers: Readonly<Record<string, ModelProviderFactory>>;
+}
+/** A router: a routing string in, a contract-validated model instance out. */
+export type ModelRouter = (value: string) => Model;
+/** Routing a string whose provider id the catalog does not carry. */
+export declare class UnknownModelProviderError extends Error {
+    constructor(value: string, catalog: ModelCatalog);
+}
+/** Routing a string whose provider the catalog carries but whose model id it does not list. */
+export declare class UnknownModelError extends Error {
+    constructor(value: string, providerId: string, provider: CatalogProviderEntry);
+}
+/** Routing a provider the catalog carries but no factory is registered for. */
+export declare class ModelProviderMissingError extends Error {
+    constructor(providerId: string, provider: CatalogProviderEntry);
+}
+/**
+ * Builds a router from a catalog and your installed provider packages: `'groq/llama-3.3-70b'` in,
+ * the model instance `groq('llama-3.3-70b')` out — after the catalog has vouched that both the
+ * provider and the model id exist. The result is validated through the core's model contract, so
+ * a factory that does not return a language model of the supported specification version fails
+ * here, at resolution time. Everything — the catalog, the factories — is caller-brought; nothing
+ * registers anywhere, and no router exists until you build one.
+ */
+export declare function createModelRouter(config: ModelRouterConfig): ModelRouter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAIhD,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,6EAA6E;AAC7E,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,YAAY,KAAK,EAAE,MAAM,EAMxB;CACF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAajE;AAID,kGAAkG;AAClG,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACrF,kGAAkG;IAClG,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC7D,kGAAkG;IAClG,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,iGAAiG;AACjG,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;AAI1E;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;AAEhE,kGAAkG;AAClG,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;CACpE;AAED,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,CAAC;AAEnD,qEAAqE;AACrE,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,YAAY,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAO/C;CACF;AAED,+FAA+F;AAC/F,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAO5E;CACF;AAED,+EAA+E;AAC/E,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,YAAY,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAO7D;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAaxE"}

package/dist/index.js

@@ -0,0 +1,105 @@
+/**
+ * `@oribos/model-router` — the model-routing capability package: `'provider/model'` strings
+ * against a models.dev-style catalog (`docs/architecture/model.md` 篇级字符串路由行,ADR-0017
+ * 追赶面中层;#185).
+ *
+ * The carrying seam is data, not the core: the core's "no registry, no magic string" pins stay
+ * untouched (ADR-0004) — this package owns the parse and the catalog, and both are the caller's
+ * to bring. `parseModelString` splits a routing string on its first slash (model ids may
+ * themselves contain slashes — deepinfra-style ids like `meta-llama/llama-4-scout`); a router
+ * built with `createModelRouter` checks the string against a catalog pasted in as-is (a snapshot
+ * of `https://models.dev/api.json` satisfies the shape) and hands the model id to the factory
+ * you registered for that provider — your installed AI SDK provider package, its dependency
+ * staying yours. What the catalog adds over bare parsing is existence: unknown providers and
+ * unlisted models are refused at resolution time with actionable errors, including the
+ * provider's `npm` package from the catalog when a provider is known but no factory is
+ * registered for it.
+ *
+ * Resolution validates through the core's model contract (`assertModel`) — a factory result that
+ * is not a language model instance of the supported specification version surfaces as the core's
+ * own contract error, never as a mid-run surprise. Zero cost when unconfigured: the package adds
+ * nothing to the core, and a router that is never built never runs.
+ *
+ * Package face: [`parseModelString`], [`ParsedModelString`], [`InvalidModelStringError`],
+ * [`createModelRouter`], [`ModelRouter`], [`ModelRouterConfig`], [`ModelCatalog`],
+ * [`CatalogProviderEntry`], [`CatalogModelEntry`], [`ModelProviderFactory`],
+ * [`UnknownModelProviderError`], [`UnknownModelError`], [`ModelProviderMissingError`].
+ */
+import { assertModel } from '@oribos/core/model';
+/** `parseModelString` on a value that is not a `'provider/model'` string. */
+export class InvalidModelStringError extends Error {
+    constructor(value) {
+        super(`not a 'provider/model' string: ${JSON.stringify(value)} — expected '<provider>/<model>', ` +
+            "split on the first '/' (the model id may itself contain slashes)");
+        this.name = 'InvalidModelStringError';
+    }
+}
+/**
+ * Splits a `'provider/model'` routing string on its **first** slash: model ids may themselves
+ * contain slashes (deepinfra-style ids like `meta-llama/llama-4-scout`), so only the first
+ * segment is the provider. Pure — no catalog, no providers, just the parse.
+ */
+export function parseModelString(value) {
+    const slash = value.indexOf('/');
+    const providerId = slash === -1 ? '' : value.slice(0, slash);
+    const modelId = slash === -1 ? '' : value.slice(slash + 1);
+    if (providerId === '' ||
+        modelId === '' ||
+        providerId.trim() !== providerId ||
+        modelId.trim() !== modelId) {
+        throw new InvalidModelStringError(value);
+    }
+    return { providerId, modelId };
+}
+/** Routing a string whose provider id the catalog does not carry. */
+export class UnknownModelProviderError extends Error {
+    constructor(value, catalog) {
+        super(`unknown provider in ${JSON.stringify(value)} — the catalog carries ` +
+            `${Object.keys(catalog).length} provider(s); cut a wider catalog (a models.dev snapshot ` +
+            'pastes as-is) or fix the provider id');
+        this.name = 'UnknownModelProviderError';
+    }
+}
+/** Routing a string whose provider the catalog carries but whose model id it does not list. */
+export class UnknownModelError extends Error {
+    constructor(value, providerId, provider) {
+        super(`unknown model in ${JSON.stringify(value)} — the catalog lists ` +
+            `${Object.keys(provider.models).length} model(s) for '${providerId}'; cut a wider ` +
+            'catalog or fix the model id');
+        this.name = 'UnknownModelError';
+    }
+}
+/** Routing a provider the catalog carries but no factory is registered for. */
+export class ModelProviderMissingError extends Error {
+    constructor(providerId, provider) {
+        const via = typeof provider.npm === 'string' ? ` (the catalog names its package: ${provider.npm})` : '';
+        super(`no provider factory registered for '${providerId}'${via} — install the provider package ` +
+            `and register it: createModelRouter({ catalog, providers: { '${providerId}': (id) => … } })`);
+        this.name = 'ModelProviderMissingError';
+    }
+}
+/**
+ * Builds a router from a catalog and your installed provider packages: `'groq/llama-3.3-70b'` in,
+ * the model instance `groq('llama-3.3-70b')` out — after the catalog has vouched that both the
+ * provider and the model id exist. The result is validated through the core's model contract, so
+ * a factory that does not return a language model of the supported specification version fails
+ * here, at resolution time. Everything — the catalog, the factories — is caller-brought; nothing
+ * registers anywhere, and no router exists until you build one.
+ */
+export function createModelRouter(config) {
+    const { catalog, providers } = config;
+    return (value) => {
+        const { providerId, modelId } = parseModelString(value);
+        const provider = catalog[providerId];
+        if (provider === undefined)
+            throw new UnknownModelProviderError(value, catalog);
+        if (provider.models[modelId] === undefined) {
+            throw new UnknownModelError(value, providerId, provider);
+        }
+        const factory = providers[providerId];
+        if (factory === undefined)
+            throw new ModelProviderMissingError(providerId, provider);
+        return assertModel(factory(modelId));
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@oribos/model-router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.0",
+  "description": "Oribos model-router capability package — route 'provider/model' strings to model instances against a models.dev-style catalog you paste in. Parse and resolve only; the provider packages and the catalog stay yours, and the core keeps no registry and no magic strings.",
+  "keywords": [
+    "ai-agents",
+    "llm",
+    "typescript",
+    "agent-framework",
+    "model-router",
+    "models-dev"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xnicholas/oribos-framework.git",
+    "directory": "packages/model-router"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@oribos/core": "^0.9.0"
+  },
+  "devDependencies": {
+    "@oribos/testing": "0.0.0",
+    "@oribos/core": "0.9.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check:dist": "node ../../scripts/check-dist.mjs",
+    "check:export-surface": "node ../../scripts/check-export-surface.mjs",
+    "check:runtime-deps": "node ../../scripts/check-runtime-deps.mjs",
+    "check:byte-budget": "node ../../scripts/check-byte-budget.mjs",
+    "byte-budget:update": "node ../../scripts/check-byte-budget.mjs --update",
+    "check:deps-budget": "node ../../scripts/check-deps-budget.mjs",
+    "deps-budget:update": "node ../../scripts/check-deps-budget.mjs --update"
+  }
 }