@odla-ai/ai 0.1.4 → 0.2.1

package/dist/index.d.cts

@@ -924,6 +924,38 @@ interface OdlaDbKeyResolverOptions {
  *  odla-ai throws its own ConfigError) rather than surfacing odla-db's 404. */
 declare function odlaDbKeyResolver(db: OdlaDbClient, opts?: OdlaDbKeyResolverOptions): KeyResolver;
 
+interface InitFromPlatformOptions {
+    /** Platform base URL (e.g. "https://odla.ai"). */
+    platform: string;
+    /** The REGISTRY app id — not the env's tenant id. */
+    appId: string;
+    /** Which environment's config to use ("dev", "prod", …). */
+    env: string;
+    /** The app's own tenant client — key reads go through `db.secrets.get`. */
+    db: OdlaDbClient;
+    /** Transport override (tests / non-global fetch). */
+    fetch?: typeof fetch;
+    /** public-config cache TTL in ms (default 60s; 0 disables caching). */
+    ttlMs?: number;
+    /** Extra init() options (catalog, injected providers, …). `resolveKey` is
+     *  owned by this helper; `defaultModel` is used only when the platform
+     *  config sets no model. */
+    initOptions?: Omit<InitOptions, "resolveKey">;
+}
+interface PlatformAi {
+    ai: Ai;
+    provider: ProviderId;
+    model?: string;
+}
+/** Drop all cached platform configs (tests, or to force an immediate refetch). */
+declare function clearPlatformAiCache(): void;
+/** Build an `Ai` from the app's platform registration: provider/model from
+ *  public-config (cached ~60s), API key from the tenant's odla-db secrets at
+ *  call time. On cache refresh the existing `Ai` (and its warm key-resolver
+ *  cache) is reused unless provider/model changed. Note the first call's
+ *  `db`/`initOptions` are captured for the cache entry's lifetime. */
+declare function initFromPlatform(opts: InitFromPlatformOptions): Promise<PlatformAi>;
+
 type FetchLike = typeof fetch;
 interface ProvisionContext {
     /** The odla-db worker URL — always human-supplied, never hardcoded. */
@@ -1008,4 +1040,4 @@ interface EntityCrudSkillOptions {
 /** Build a CRUD Skill for one odla-db entity. */
 declare function entityCrudSkill(opts: EntityCrudSkillOptions): Skill;
 
-export { AGENT_SCHEMA, ANTHROPIC_MODELS, type AgentRun, type AgentRunInput, type Ai, type AudioBlock, type AudioMediaType, type AudioSource, AuthError, type Capabilities, CapabilityError, type Catalog, type ChatInput, type ComposedPersona, ConfigError, type ContentBlockDelta, type ContentBlockDeltaEvent, type ContentBlockStartEvent, type ContentBlockStopEvent, ContextWindowError, DEFAULT_CATALOG, DEFAULT_SECRET_NAMES, type DocumentBlock, type DocumentSource, type Effort, type EntityCrudSkillOptions, type EvalCase, type EvalReport, type EvalResult, type EvaluateOptions, type ExtractCall, type ExtractTool, GOOGLE_MODELS, type GradeContext, type GradeResult, type Grader, type ImageBlock, type ImageMediaType, type ImageSource, InMemoryScope, type Inference, type InitOptions, InvalidRequestError, type KeyMap, type KeyOptions, type KeyResolver, type MemoryScope, type MessageDeltaEvent, type MessageStartEvent, type MessageStopEvent, type ModelKind, type ModelSpec, NS, OPENAI_MODELS, OdlaAIError, type OdlaDbClient, type OdlaDbKeyResolverOptions, OdlaDbMemory, type OdlaDbMemoryOptions, type OdlaEntityRef, type OdlaLookup, type OdlaOp, type OdlaQuery, type OdlaScalar, type OracleContentBlock, type OracleErrorEvent, type OracleErrorShape, type OracleErrorType, type OracleEvent, type OracleMessage, type OracleRequest, type OracleResponse, type OracleRole, type OracleStopReason, type OracleTool, type OracleUsage, type PersistRunOptions, type Persona, type Provider, ProviderError, type ProviderFactory, type ProviderId, type ProvisionAgentAppOptions, type ProvisionContext, type ProvisionedApp, type QueryRunsOptions, RateLimitError, type ResponseFormat, type SearchCall, type Skill, type StoppedReason, TaintError, type TaintLabel, type TaintSet, type TextBlock, type ThinkingBlock, type ThinkingMode, type ToolCallRecord, type ToolChoice, type ToolContext, type ToolDef, type ToolHandler, type ToolOutput, type ToolResultBlock, type ToolUseBlock, addUsage, assertSinkAcceptsTaint, blocksOf, buildCatalog, chatCapabilities, clearProviderCache, composeSkills, createApp, emptyUsage, entityCrudSkill, evaluate, exactMatch, extractText, extractToolUses, generateLlmsTxt, getProvider, includes, init, isAudioBlock, isDocumentBlock, isImageBlock, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, llmJudge, looksLikeKey, mintAppKey, normalizeError, odlaDbKeyResolver, persistRun, providersInCatalog, provisionAgentApp, pushAgentSchema, putSecret, queryRuns, redact, registerProvider, resolveModel, runAgent, structuredMatch, taint, toOracleTool, validateRequest };
+export { AGENT_SCHEMA, ANTHROPIC_MODELS, type AgentRun, type AgentRunInput, type Ai, type AudioBlock, type AudioMediaType, type AudioSource, AuthError, type Capabilities, CapabilityError, type Catalog, type ChatInput, type ComposedPersona, ConfigError, type ContentBlockDelta, type ContentBlockDeltaEvent, type ContentBlockStartEvent, type ContentBlockStopEvent, ContextWindowError, DEFAULT_CATALOG, DEFAULT_SECRET_NAMES, type DocumentBlock, type DocumentSource, type Effort, type EntityCrudSkillOptions, type EvalCase, type EvalReport, type EvalResult, type EvaluateOptions, type ExtractCall, type ExtractTool, GOOGLE_MODELS, type GradeContext, type GradeResult, type Grader, type ImageBlock, type ImageMediaType, type ImageSource, InMemoryScope, type Inference, type InitFromPlatformOptions, type InitOptions, InvalidRequestError, type KeyMap, type KeyOptions, type KeyResolver, type MemoryScope, type MessageDeltaEvent, type MessageStartEvent, type MessageStopEvent, type ModelKind, type ModelSpec, NS, OPENAI_MODELS, OdlaAIError, type OdlaDbClient, type OdlaDbKeyResolverOptions, OdlaDbMemory, type OdlaDbMemoryOptions, type OdlaEntityRef, type OdlaLookup, type OdlaOp, type OdlaQuery, type OdlaScalar, type OracleContentBlock, type OracleErrorEvent, type OracleErrorShape, type OracleErrorType, type OracleEvent, type OracleMessage, type OracleRequest, type OracleResponse, type OracleRole, type OracleStopReason, type OracleTool, type OracleUsage, type PersistRunOptions, type Persona, type PlatformAi, type Provider, ProviderError, type ProviderFactory, type ProviderId, type ProvisionAgentAppOptions, type ProvisionContext, type ProvisionedApp, type QueryRunsOptions, RateLimitError, type ResponseFormat, type SearchCall, type Skill, type StoppedReason, TaintError, type TaintLabel, type TaintSet, type TextBlock, type ThinkingBlock, type ThinkingMode, type ToolCallRecord, type ToolChoice, type ToolContext, type ToolDef, type ToolHandler, type ToolOutput, type ToolResultBlock, type ToolUseBlock, addUsage, assertSinkAcceptsTaint, blocksOf, buildCatalog, chatCapabilities, clearPlatformAiCache, clearProviderCache, composeSkills, createApp, emptyUsage, entityCrudSkill, evaluate, exactMatch, extractText, extractToolUses, generateLlmsTxt, getProvider, includes, init, initFromPlatform, isAudioBlock, isDocumentBlock, isImageBlock, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, llmJudge, looksLikeKey, mintAppKey, normalizeError, odlaDbKeyResolver, persistRun, providersInCatalog, provisionAgentApp, pushAgentSchema, putSecret, queryRuns, redact, registerProvider, resolveModel, runAgent, structuredMatch, taint, toOracleTool, validateRequest };

package/dist/index.d.ts

@@ -924,6 +924,38 @@ interface OdlaDbKeyResolverOptions {
  *  odla-ai throws its own ConfigError) rather than surfacing odla-db's 404. */
 declare function odlaDbKeyResolver(db: OdlaDbClient, opts?: OdlaDbKeyResolverOptions): KeyResolver;
 
+interface InitFromPlatformOptions {
+    /** Platform base URL (e.g. "https://odla.ai"). */
+    platform: string;
+    /** The REGISTRY app id — not the env's tenant id. */
+    appId: string;
+    /** Which environment's config to use ("dev", "prod", …). */
+    env: string;
+    /** The app's own tenant client — key reads go through `db.secrets.get`. */
+    db: OdlaDbClient;
+    /** Transport override (tests / non-global fetch). */
+    fetch?: typeof fetch;
+    /** public-config cache TTL in ms (default 60s; 0 disables caching). */
+    ttlMs?: number;
+    /** Extra init() options (catalog, injected providers, …). `resolveKey` is
+     *  owned by this helper; `defaultModel` is used only when the platform
+     *  config sets no model. */
+    initOptions?: Omit<InitOptions, "resolveKey">;
+}
+interface PlatformAi {
+    ai: Ai;
+    provider: ProviderId;
+    model?: string;
+}
+/** Drop all cached platform configs (tests, or to force an immediate refetch). */
+declare function clearPlatformAiCache(): void;
+/** Build an `Ai` from the app's platform registration: provider/model from
+ *  public-config (cached ~60s), API key from the tenant's odla-db secrets at
+ *  call time. On cache refresh the existing `Ai` (and its warm key-resolver
+ *  cache) is reused unless provider/model changed. Note the first call's
+ *  `db`/`initOptions` are captured for the cache entry's lifetime. */
+declare function initFromPlatform(opts: InitFromPlatformOptions): Promise<PlatformAi>;
+
 type FetchLike = typeof fetch;
 interface ProvisionContext {
     /** The odla-db worker URL — always human-supplied, never hardcoded. */
@@ -1008,4 +1040,4 @@ interface EntityCrudSkillOptions {
 /** Build a CRUD Skill for one odla-db entity. */
 declare function entityCrudSkill(opts: EntityCrudSkillOptions): Skill;
 
-export { AGENT_SCHEMA, ANTHROPIC_MODELS, type AgentRun, type AgentRunInput, type Ai, type AudioBlock, type AudioMediaType, type AudioSource, AuthError, type Capabilities, CapabilityError, type Catalog, type ChatInput, type ComposedPersona, ConfigError, type ContentBlockDelta, type ContentBlockDeltaEvent, type ContentBlockStartEvent, type ContentBlockStopEvent, ContextWindowError, DEFAULT_CATALOG, DEFAULT_SECRET_NAMES, type DocumentBlock, type DocumentSource, type Effort, type EntityCrudSkillOptions, type EvalCase, type EvalReport, type EvalResult, type EvaluateOptions, type ExtractCall, type ExtractTool, GOOGLE_MODELS, type GradeContext, type GradeResult, type Grader, type ImageBlock, type ImageMediaType, type ImageSource, InMemoryScope, type Inference, type InitOptions, InvalidRequestError, type KeyMap, type KeyOptions, type KeyResolver, type MemoryScope, type MessageDeltaEvent, type MessageStartEvent, type MessageStopEvent, type ModelKind, type ModelSpec, NS, OPENAI_MODELS, OdlaAIError, type OdlaDbClient, type OdlaDbKeyResolverOptions, OdlaDbMemory, type OdlaDbMemoryOptions, type OdlaEntityRef, type OdlaLookup, type OdlaOp, type OdlaQuery, type OdlaScalar, type OracleContentBlock, type OracleErrorEvent, type OracleErrorShape, type OracleErrorType, type OracleEvent, type OracleMessage, type OracleRequest, type OracleResponse, type OracleRole, type OracleStopReason, type OracleTool, type OracleUsage, type PersistRunOptions, type Persona, type Provider, ProviderError, type ProviderFactory, type ProviderId, type ProvisionAgentAppOptions, type ProvisionContext, type ProvisionedApp, type QueryRunsOptions, RateLimitError, type ResponseFormat, type SearchCall, type Skill, type StoppedReason, TaintError, type TaintLabel, type TaintSet, type TextBlock, type ThinkingBlock, type ThinkingMode, type ToolCallRecord, type ToolChoice, type ToolContext, type ToolDef, type ToolHandler, type ToolOutput, type ToolResultBlock, type ToolUseBlock, addUsage, assertSinkAcceptsTaint, blocksOf, buildCatalog, chatCapabilities, clearProviderCache, composeSkills, createApp, emptyUsage, entityCrudSkill, evaluate, exactMatch, extractText, extractToolUses, generateLlmsTxt, getProvider, includes, init, isAudioBlock, isDocumentBlock, isImageBlock, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, llmJudge, looksLikeKey, mintAppKey, normalizeError, odlaDbKeyResolver, persistRun, providersInCatalog, provisionAgentApp, pushAgentSchema, putSecret, queryRuns, redact, registerProvider, resolveModel, runAgent, structuredMatch, taint, toOracleTool, validateRequest };
+export { AGENT_SCHEMA, ANTHROPIC_MODELS, type AgentRun, type AgentRunInput, type Ai, type AudioBlock, type AudioMediaType, type AudioSource, AuthError, type Capabilities, CapabilityError, type Catalog, type ChatInput, type ComposedPersona, ConfigError, type ContentBlockDelta, type ContentBlockDeltaEvent, type ContentBlockStartEvent, type ContentBlockStopEvent, ContextWindowError, DEFAULT_CATALOG, DEFAULT_SECRET_NAMES, type DocumentBlock, type DocumentSource, type Effort, type EntityCrudSkillOptions, type EvalCase, type EvalReport, type EvalResult, type EvaluateOptions, type ExtractCall, type ExtractTool, GOOGLE_MODELS, type GradeContext, type GradeResult, type Grader, type ImageBlock, type ImageMediaType, type ImageSource, InMemoryScope, type Inference, type InitFromPlatformOptions, type InitOptions, InvalidRequestError, type KeyMap, type KeyOptions, type KeyResolver, type MemoryScope, type MessageDeltaEvent, type MessageStartEvent, type MessageStopEvent, type ModelKind, type ModelSpec, NS, OPENAI_MODELS, OdlaAIError, type OdlaDbClient, type OdlaDbKeyResolverOptions, OdlaDbMemory, type OdlaDbMemoryOptions, type OdlaEntityRef, type OdlaLookup, type OdlaOp, type OdlaQuery, type OdlaScalar, type OracleContentBlock, type OracleErrorEvent, type OracleErrorShape, type OracleErrorType, type OracleEvent, type OracleMessage, type OracleRequest, type OracleResponse, type OracleRole, type OracleStopReason, type OracleTool, type OracleUsage, type PersistRunOptions, type Persona, type PlatformAi, type Provider, ProviderError, type ProviderFactory, type ProviderId, type ProvisionAgentAppOptions, type ProvisionContext, type ProvisionedApp, type QueryRunsOptions, RateLimitError, type ResponseFormat, type SearchCall, type Skill, type StoppedReason, TaintError, type TaintLabel, type TaintSet, type TextBlock, type ThinkingBlock, type ThinkingMode, type ToolCallRecord, type ToolChoice, type ToolContext, type ToolDef, type ToolHandler, type ToolOutput, type ToolResultBlock, type ToolUseBlock, addUsage, assertSinkAcceptsTaint, blocksOf, buildCatalog, chatCapabilities, clearPlatformAiCache, clearProviderCache, composeSkills, createApp, emptyUsage, entityCrudSkill, evaluate, exactMatch, extractText, extractToolUses, generateLlmsTxt, getProvider, includes, init, initFromPlatform, isAudioBlock, isDocumentBlock, isImageBlock, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, llmJudge, looksLikeKey, mintAppKey, normalizeError, odlaDbKeyResolver, persistRun, providersInCatalog, provisionAgentApp, pushAgentSchema, putSecret, queryRuns, redact, registerProvider, resolveModel, runAgent, structuredMatch, taint, toOracleTool, validateRequest };

package/dist/index.js

@@ -472,6 +472,27 @@ Secrets are read-only from the app key (odlaDbKeyResolver \u2192 db.secrets.get)
 are WRITTEN only with the operator/dev token via provisionAgentApp/putSecret. Keys
 are AES-GCM-encrypted at rest in odla-db and never returned to browser clients.
 
+## Platform wiring (odla.ai apps registry)
+
+Apps registered on the odla platform get LLM access as an APP SETTING \u2014
+never put provider keys in your Worker's wrangler vars/secrets. Provider +
+default model are per-environment registry config (set in Studio's AI card
+or \`@odla-ai/apps\` setAi); the API key lives in the platform vault (the
+env's odla-db tenant secrets, write-only for operators). One call reads both:
+
+    import { initFromPlatform } from "@odla-ai/ai";
+    import { init as odlaInit } from "@odla-ai/db";
+
+    const db = odlaInit({ appId: TENANT, adminToken: env.ODLA_API_KEY, endpoint: "https://db.odla.ai" });
+    const { ai, provider, model } = await initFromPlatform({
+      platform: "https://odla.ai", appId: APP_ID, env: "prod", db });
+    // ai.chat / ai.stream / ai.extract \u2014 provider/model from public-config
+    // (cached ~60s, so Studio changes apply without redeploys); the key is
+    // fetched from the vault at call time via odlaDbKeyResolver.
+
+The only secret the Worker carries is its odla-db app key. Rotating the LLM
+key = writing the secret again; switching provider/model = a Studio edit.
+
 ## Errors
 
 Every error is an OdlaAIError subclass with a stable \`code\` \u2014 branch on err.code:
@@ -899,15 +920,15 @@ var DEFAULT_SECRET_NAMES = {
 function odlaDbKeyResolver(db, opts = {}) {
   const nameFor = opts.secretName ?? ((p) => DEFAULT_SECRET_NAMES[p]);
   const useCache = opts.cache ?? true;
-  const cache2 = /* @__PURE__ */ new Map();
+  const cache3 = /* @__PURE__ */ new Map();
   return async (provider) => {
     if (useCache) {
-      const hit = cache2.get(provider);
+      const hit = cache3.get(provider);
       if (hit !== void 0) return hit;
     }
     try {
       const key = await db.secrets.get(nameFor(provider));
-      if (useCache) cache2.set(provider, key);
+      if (useCache) cache3.set(provider, key);
       return key;
     } catch {
       return void 0;
@@ -915,6 +936,51 @@ function odlaDbKeyResolver(db, opts = {}) {
   };
 }
 
+// src/store/platform.ts
+var cache2 = /* @__PURE__ */ new Map();
+function clearPlatformAiCache() {
+  cache2.clear();
+}
+async function fetchAiConfig(opts) {
+  const doFetch = opts.fetch ?? fetch;
+  const base = opts.platform.replace(/\/$/, "");
+  const url = `${base}/registry/apps/${encodeURIComponent(opts.appId)}/public-config?env=${encodeURIComponent(opts.env)}`;
+  const res = await doFetch(url);
+  if (!res.ok) throw new ProviderError(`platform public-config fetch failed: ${res.status} for ${opts.appId}/${opts.env}`);
+  const cfg = await res.json();
+  const ai = cfg.ai;
+  if (!ai || typeof ai.provider !== "string") {
+    throw new ConfigError(
+      `ai service is not enabled/configured for "${opts.appId}" (${opts.env}) \u2014 enable it in Studio or via @odla-ai/apps setAi(appId, env, { provider }).`
+    );
+  }
+  if (!(ai.provider in DEFAULT_SECRET_NAMES)) {
+    throw new ConfigError(`platform ai config names unknown provider "${ai.provider}" for "${opts.appId}" (${opts.env}).`);
+  }
+  const model = typeof ai.model === "string" && ai.model ? ai.model : void 0;
+  return { provider: ai.provider, ...model ? { model } : {} };
+}
+async function initFromPlatform(opts) {
+  const ttl = opts.ttlMs ?? 6e4;
+  const key = `${opts.platform}|${opts.appId}|${opts.env}`;
+  const now = Date.now();
+  const hit = ttl > 0 ? cache2.get(key) : void 0;
+  if (hit && hit.expiresAt > now) return hit.value;
+  const { provider, model } = await fetchAiConfig(opts);
+  if (hit && hit.value.provider === provider && hit.value.model === model) {
+    hit.expiresAt = now + ttl;
+    return hit.value;
+  }
+  const ai = init({
+    ...opts.initOptions,
+    resolveKey: odlaDbKeyResolver(opts.db),
+    defaultModel: model ?? opts.initOptions?.defaultModel
+  });
+  const value = { ai, provider, ...model ? { model } : {} };
+  if (ttl > 0) cache2.set(key, { value, expiresAt: now + ttl });
+  return value;
+}
+
 // src/store/provision.ts
 async function post(ctx, path, body) {
   const f = ctx.fetch ?? fetch;
@@ -1124,6 +1190,7 @@ export {
   blocksOf,
   buildCatalog,
   chatCapabilities,
+  clearPlatformAiCache,
   clearProviderCache,
   composeSkills,
   createApp,
@@ -1137,6 +1204,7 @@ export {
   getProvider,
   includes,
   init,
+  initFromPlatform,
   isAudioBlock,
   isDocumentBlock,
   isImageBlock,