@ego-z/contracts 0.15.12 → 0.15.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.12",
+  "version": "0.15.13",
   "description": "Wire-format type contracts shared between EgoZ backend, SDK, MCP and console. Type-only — no runtime artifacts.",
   "types": "./src/index.d.ts",
   "exports": {

package/src/ask.d.ts

@@ -90,6 +90,36 @@ export interface AskRequestBody {
      */
     externalUserId?: string;
 
+    /**
+     * Run THIS turn on a specific chat model, instead of the project's
+     * configured default.
+     *
+     * Only honoured on a project whose owner has turned model switching on and
+     * curated a menu (Console → LLM Settings). Read the menu from
+     * `GET /egoz/models`, which returns every model this project offers along
+     * with which one is the default, and echo an `id` back here verbatim.
+     *
+     *   - omitted        → the project's default model, exactly as before.
+     *   - `"openai:gpt-4o-mini"` → the canonical, always-unambiguous form.
+     *   - `"gpt-4o-mini"`        → accepted while that id is offered by only
+     *                             one provider on this project.
+     *
+     * A model this project does not offer — and ANY value at all on a project
+     * where switching is off — is rejected with `ModelNotAllowed` (400). It is
+     * deliberately not ignored: a caller whose override is silently dropped
+     * believes it took effect, and the only trace of the truth is a model
+     * field on a usage row nobody reads until the invoice arrives.
+     *
+     * Scope, and what it does NOT change:
+     *   - Embeddings are pinned to the project. The knowledge base's vectors
+     *     were written in one embedding space, and retrieving against another
+     *     returns confident nonsense — so RAG is unaffected by this field.
+     *   - A voice call ignores it. A call is a latency budget; the tenant's
+     *     `voiceModel` still wins there. The value is still validated, so a
+     *     bad one is a 400 rather than a surprise.
+     */
+    model?: string;
+
     /** Override the tenant's default response format for this single call. */
     responseFormat?: ResponseFormat;
 

package/src/index.d.ts

@@ -74,6 +74,10 @@
  *                        create / update / clone bodies,
  *                        `ActiveTenantPersonalityWire`. Shared:
  *                        `PersonalityTraitsWire`, `PresetType`.
+ *   - `model.d.ts`    — `GET /egoz/models`: the menu of chat models a
+ *                        project offers for `AskRequestBody.model`.
+ *                        `SwitchableModelWire`,
+ *                        `SwitchableModelsResponseData`.
  *   - `user-memory.d.ts` — Per-end-user learning (Phase 15 / exURM).
  *                        `UserMemoryWire`, `UserMemoryUserSummaryWire`,
  *                        `UpdateUserMemoryFactBody`, list / detail / fact /
@@ -93,6 +97,7 @@
 
 export * from './envelope';
 export * from './ask';
+export * from './model';
 export * from './stream';
 export * from './questions';
 export * from './tool';

package/src/model.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @ego-z/contracts — `GET /egoz/models` wire types.
+ *
+ * The menu of chat models a project offers for `AskRequestBody.model`. Read
+ * this to build a model picker; echo an entry's `id` back verbatim.
+ *
+ * ── Why this endpoint exists at all ──────────────────────────────────────
+ *
+ * The alternative was for integrators to hardcode the model ids their picker
+ * offers. That list is a copy of one a project owner edits in the Console,
+ * with nothing connecting the two: the day the owner drops a model, every
+ * caller's picker keeps offering it and every pick 400s, in someone else's
+ * deployment, with no signal on the Console side that anything broke.
+ *
+ * ── Authentication ───────────────────────────────────────────────────────
+ *
+ * Same trusted-server pattern as `/ask`: the tenant API key in `X-API-Key`
+ * (plus `X-Tenant-Id`). It is deliberately NOT anonymous — the menu names a
+ * project's providers and model tiers, which is commercial detail, not public
+ * information.
+ *
+ * ── What it is not ───────────────────────────────────────────────────────
+ *
+ * Not a provider catalogue. It returns exactly what the owner curated, and
+ * makes no call to OpenAI/Anthropic/Azure to do so — a hot path on every chat
+ * panel open must not fan out to third parties. The Console's model dropdowns
+ * are the surface that browses live catalogues
+ * (`GET /egoz/tenants/:tenantId/models`); this one publishes the decision.
+ */
+
+/** One model this project will run. */
+export interface SwitchableModelWire {
+    /**
+     * Canonical handle, `"<provider>:<model>"` (e.g. `"openai:gpt-4o-mini"`).
+     * Send this back as `AskRequestBody.model`. Stable for as long as the
+     * owner keeps the entry on the menu.
+     */
+    id: string;
+    /** BYOK provider that will serve the turn — `"openai"`, `"anthropic"`, … */
+    provider: string;
+    /**
+     * Provider-side model id. On Azure this is the DEPLOYMENT name, which is
+     * private to the tenant — do not assume it matches a public model name.
+     */
+    model: string;
+    /** True for the model used when `AskRequestBody.model` is omitted. Exactly one entry has it. */
+    isDefault: boolean;
+}
+
+/** `data` payload of `GET /egoz/models`. */
+export interface SwitchableModelsResponseData {
+    /**
+     * Whether `AskRequestBody.model` will be honoured. When `false`, `models`
+     * still holds exactly one entry — the project default — so a picker can
+     * render the same way either way and simply has nothing to switch to.
+     *
+     * Sending `model` while this is `false` is an error, not a no-op.
+     */
+    switchable: boolean;
+    /** `id` of the default entry. Convenience — it is also the entry with `isDefault: true`. */
+    defaultId: string;
+    /** The default first, then the owner's curated alternatives. Never empty. */
+    models: SwitchableModelWire[];
+}