@ultimat3/ai 24.0.0 → 25.1.0

package/src/index.ts

@@ -12,29 +12,49 @@ export type { AgentJobOptions } from './agent-job';
 export { agentJob } from './agent-job';
 export type {
   BudgetKeys,
+  BudgetLedger,
   BudgetLedgerInput,
   BudgetLimits,
   BudgetReport,
   BudgetStore,
   BudgetTake,
+  MemoryBudgetStore,
   SpendEstimate,
 } from './budget';
 export {
-  BudgetLedger,
   budgetKeysFor,
   currentBudget,
   estimateSpend,
-  MemoryBudgetStore,
+  memoryBudgetStore,
   withBudget,
 } from './budget';
-export type { Embedder, HashEmbedderInput } from './embeddings';
+export type {
+  AiDocumentBlock,
+  AiDocumentSource,
+  AiImageBlock,
+  AiImageSource,
+  AiMediaBlock,
+  ImageMediaType,
+} from './content-blocks';
+export {
+  IMAGE_MEDIA_TYPES,
+  IMAGE_TOKEN_ESTIMATE,
+  isMediaBlock,
+  MAX_DOCUMENT_BASE64_CHARS,
+  MAX_IMAGE_BASE64_CHARS,
+} from './content-blocks';
+export type { ContentRefusal } from './content-errors';
+export { AiContentUnsupportedError } from './content-errors';
+export type { EchoProvider, EchoProviderInput } from './echo-provider';
+export { echoProvider } from './echo-provider';
+export type { Embedder, HashEmbedder, HashEmbedderInput } from './embeddings';
 export {
   cosine,
   embedBatched,
   embedOne,
-  HashEmbedder,
-  normalize,
-  tokenize,
+  hashEmbedder,
+  normalizeVector,
+  wordTokens,
 } from './embeddings';
 export type { AiErrorCode } from './errors';
 export {
@@ -94,8 +114,14 @@ export {
   resetEvals,
 } from './evals';
 export type { AiFetch } from './fetch-seam';
-export type { CreateGatewayInput, Gateway, GatewayCache, RetryPolicy } from './gateway';
-export { backoffMs, cacheKeyFor, createGateway, DEFAULT_RETRY, isRetryable } from './gateway';
+export type { Gateway, GatewayCache, ProviderGatewayInput, RetryPolicy } from './gateway';
+export {
+  backoffMs,
+  DEFAULT_GATEWAY_RETRY,
+  isRetryable,
+  promptCacheKey,
+  providerGateway,
+} from './gateway';
 export type { HiveDef, HiveSplitArgs } from './hive';
 export { hive } from './hive';
 export { HiveEmptyError } from './hive-errors';
@@ -104,11 +130,19 @@ export type { LlmAction, LlmBudget, LlmDef, LlmVarsArgs } from './llm';
 export { llm } from './llm';
 export type { LlmCache, LlmScopeArgs, LlmSemanticCache } from './llm-cache';
 export type { LlmStreamChunk } from './llm-stream';
-export type { Effort, ModelId, ModelReasoning, ModelSpec, ThinkingMode } from './models';
+export type { ModelSource } from './model-resolve';
+export { AiModelUnresolvedError } from './model-resolve';
+export type {
+  ContentKind,
+  DeclaredReasoning,
+  Effort,
+  ModelId,
+  ModelReasoning,
+  ModelSpec,
+  ThinkingMode,
+} from './models';
 export {
-  ANTHROPIC_MODEL_IDS,
   assertModel,
-  DEFAULT_MODEL,
   EFFORTS,
   isModelRegistered,
   modelIds,
@@ -118,11 +152,10 @@ export {
   registerModel,
   resetModels,
 } from './models';
-export { OPENAI_MODEL_IDS, registerOpenAiModels } from './openai-models';
 export type { OpenAiProviderInput } from './openai-provider';
 export { openAiProvider } from './openai-provider';
-export type { PgVectorStoreInput } from './pg-vector';
-export { PgVectorStore } from './pg-vector';
+export type { PostgresVectorStore, PostgresVectorStoreInput } from './pg-vector';
+export { postgresVectorStore } from './pg-vector';
 export type {
   PgHybridArgs,
   PgSearchArgs,
@@ -137,18 +170,19 @@ export {
 } from './pg-vector-sql';
 export type { DefinePromptInput, Prompt, PromptVars } from './prompt';
 export {
-  contentHash,
   definePrompt,
   describePrompts,
   getPrompt,
+  promptHash,
   promptVersions,
   resetPrompts,
 } from './prompt';
+export { promptFences } from './prompt-fence';
 export type {
   AiContentBlock,
   AiMessage,
+  AnthropicProvider,
   AnthropicProviderInput,
-  EchoProviderInput,
   GenerateRequest,
   GenerateResult,
   Provider,
@@ -158,9 +192,8 @@ export type {
   TokenUsage,
 } from './provider';
 export {
-  AnthropicProvider,
+  anthropicProvider,
   costOf,
-  EchoProvider,
   estimateCost,
   estimateInputTokens,
   estimateTextTokens,
@@ -179,17 +212,22 @@ export type {
   Reranker,
   RetrieveInput,
 } from './rag';
-export { assembleContext, chunk, indexDocument, passthroughReranker, retrieve } from './rag';
+export {
+  assembleContext,
+  chunkDocument,
+  indexDocument,
+  passthroughReranker,
+  retrieve,
+} from './rag';
 export { assertNoSecrets } from './redaction';
-export type { RemoteEmbedderInput } from './remote-embedder';
-export { RemoteEmbedder } from './remote-embedder';
+export type { RemoteEmbedder, RemoteEmbedderInput } from './remote-embedder';
+export { remoteEmbedder } from './remote-embedder';
 export type { AiRuntimeInput, Redactor } from './runtime';
 export {
   aiEmbedder,
   aiGateway,
   aiRedactor,
   configureAi,
-  MAX_SEMANTIC_CACHE_SCOPES,
   semanticCacheFor,
 } from './runtime';
 export type { Scorer } from './scorers';
@@ -212,6 +250,7 @@ export type {
 export { asProjectableAction, runLlmToolCall, toLlmTool, toLlmTools } from './tools';
 export type {
   HybridSearchInput,
+  MemoryVectorStore,
   MemoryVectorStoreInput,
   MetadataFilter,
   SearchHit,
@@ -219,7 +258,7 @@ export type {
   VectorRecord,
   VectorStore,
 } from './vector';
-export { fuse, MemoryVectorStore } from './vector';
+export { fuse, memoryVectorStore } from './vector';
 export type { VectorScope } from './vector-scope';
-export { NO_TENANT, tenantOf, UNSCOPED, VectorUnscopedError } from './vector-scope';
+export { NO_VECTOR_TENANT, tenantOf, UNSCOPED, VectorUnscopedError } from './vector-scope';
 export type { StreamState } from './wire';

package/src/llm-cache.ts

@@ -74,7 +74,7 @@ export interface PromptCache {
  * writing its own `scope`, and the locale has to survive that — so it lives in the unconditional
  * half of the store key, beside the prompt hash.
  *
- * `ctx.actor` is never absent (`createContext` defaults it to `anonymousActor()`), so every
+ * `ctx.actor` is never absent (`ctxOf` defaults it to `anonymousActor()`), so every
  * anonymous caller shares one partition — which is what the anonymous actor already means
  * everywhere else in the framework.
  */

package/src/llm.ts

@@ -4,7 +4,7 @@
  * The eight primitives are the whole vocabulary. A model call is a server-authoritative
  * operation with an input schema, an output schema and a policy, which is the definition of
  * an `action` — so this file is a FACTORY over `action()`, never a new kind of thing. That is
- * why `summarize.tool()`, `.openapi()`, `.client()`, `.job()` and `.contract()` all exist
+ * why `summarize.openapi()`, `.client()`, `.job()`, `.contract()` and its MCP tool all exist
  * without a line here: the value is an action, so it projects like one, and an app gains an
  * MCP tool backed by a model the moment it declares one.
  *
@@ -14,7 +14,7 @@
  *
  * `.stream()` is the same action over a different transport, and it is here rather than beside
  * the gateway for one reason: everything that makes `llm()` worth using — policy, input parse,
- * budget scope, semantic cache, span, `.tool()` — is lost the moment a feature has to reach past
+ * budget scope, semantic cache, span, MCP tool — is lost the moment a feature has to reach past
  * it to `aiGateway()` for tokens on a screen. `./llm-stream.ts` holds the plumbing and states the
  * two decisions a stream forces (no repair turn, budget reserved exactly as before); what a
  * streamed answer must satisfy is decided in this file, next to the non-streaming version of the
@@ -29,7 +29,7 @@ import type { Money } from '@ultimat3/money';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, validateAsync } from '@ultimat3/schema';
 import type { BudgetLimits } from './budget';
-import { budgetKeysFor, currentBudget, withBudget } from './budget';
+import { budgetKeysFor, currentBudget, screenedMoney, withBudget } from './budget';
 import {
   LlmOutputInvalidError,
   LlmRefusedError,
@@ -41,8 +41,9 @@ import type { LlmCache } from './llm-cache';
 import { openCache } from './llm-cache';
 import type { LlmSink, LlmStreamChunk } from './llm-stream';
 import { currentLlmSink, llmStream, streamOneTurn, withLlmSink } from './llm-stream';
+import { modelForCall } from './model-resolve';
 import type { ModelId } from './models';
-import { DEFAULT_MODEL, moreCapableThan } from './models';
+import { moreCapableThan } from './models';
 import type { Prompt, PromptVars } from './prompt';
 import type { AiMessage, GenerateRequest, GenerateResult } from './provider';
 import { isTruncated } from './provider';
@@ -101,7 +102,7 @@ export interface LlmDef<
 }
 
 /**
- * An `action` with one extra way to be called. Every projection an action has, it has — `.tool()`,
+ * An `action` with one extra way to be called. Every projection an action has, it has — its MCP tool,
  * `.openapi()`, `.client()`, `.job()`, `.contract()` — plus a transport for the case an action's
  * single return value cannot serve: text on a screen before the answer is finished.
  */
@@ -191,7 +192,10 @@ async function generate<
   // The prompt ref is the identity every failure here is about, and unlike the action's
   // export name it exists before registration and can never twin.
   const name = prompt.ref;
-  const model = def.model ?? prompt.model ?? DEFAULT_MODEL;
+  // Screened first: a bad declaration is refused whether or not a gateway exists.
+  const limits = limitsOf(def.budget);
+  // The declaration, its prompt, then the gateway's `defaultModel` — the app's three places.
+  const model = modelForCall('llm', name, def.model, prompt.model);
   // `vars()` is the one declared place a model call loads data, so it is the one place the
   // framework can refuse a `Secret` and the one place an app's redactor can see the row before it
   // leaves the process. Both run here, between the load and the request, and neither is optional
@@ -249,8 +253,6 @@ async function generate<
     // A ledger derived from the ambient one, so a per-call budget can only TIGHTEN the actor
     // and org ceilings this call runs inside, never widen them. The gateway reserves against
     // it before the provider is touched — that is where `X_AI_BUDGET_EXCEEDED` comes from.
-    // Screened first, as before: a bad declaration is refused whether or not a gateway exists.
-    const limits = limitsOf(def.budget);
     // Rooted in the GATEWAY's own ceilings when no scope is open — an empty root ignored them.
     const gateway = aiGateway(name);
     // Keyed on the CALLER, so the gateway's `actor` / `org` ceilings count this call against them.
@@ -280,7 +282,7 @@ async function generate<
             // The fix names a model the caller can paste, and only ever a MORE capable one:
             // "the first id that differs" answered a refusal on the default model with the next
             // entry down the ladder, which is a retry that cannot succeed.
-            alternative: moreCapableThan(result.model),
+            alternative: moreCapableThan(result.model, request),
             category: result.stopDetails?.category,
             explanation: result.stopDetails?.explanation,
           });
@@ -346,7 +348,7 @@ async function streamedAnswer<TOutput extends StandardSchemaV1>(
     throw new LlmRefusedError({
       prompt: name,
       model: result.model,
-      alternative: moreCapableThan(result.model),
+      alternative: moreCapableThan(result.model, request),
       category: result.stopDetails?.category,
       explanation: result.stopDetails?.explanation,
     });
@@ -392,7 +394,9 @@ function limitsOf(budget: LlmBudget | undefined): BudgetLimits {
     ...(budget?.tokensIn === undefined
       ? {}
       : { tokensIn: finiteCount('llm', 'budget.tokensIn', budget.tokensIn) }),
-    ...(budget?.costPerCall === undefined ? {} : { costPerCall: budget.costPerCall }),
+    ...(budget?.costPerCall === undefined
+      ? {}
+      : { costPerCall: screenedMoney('llm', 'budget.costPerCall', budget.costPerCall) }),
   };
 }
 

package/src/model-resolve.ts

@@ -0,0 +1,79 @@
+// Which model a call runs on, decided in ONE place. The app names it in one of three places — the
+// declaration's `model`, its prompt's, `providerGateway({ defaultModel })` — and the framework has
+// no fourth: a call that names none is refused here, naming all three, never routed to a vendor.
+
+import { UltimateError } from '@ultimat3/core';
+import type { ModelId } from './models';
+import { aiGateway } from './runtime';
+
+/** Where a model was resolved. Bounded, and the first word of the refusal's cause. */
+export type ModelSite = 'llm' | 'agent' | 'gateway' | 'provider' | 'echo-provider';
+
+/** The three places, spelled once so the refusal and the docs cannot drift apart. */
+const PLACES =
+  'model: modelId on the llm()/agent() declaration, model: modelId in its definePrompt, or providerGateway({ …, defaultModel: modelId })';
+
+/**
+ * The first declared candidate, in the caller's precedence order (a declaration, then its prompt,
+ * then the gateway's `defaultModel`). None declared is `X_AI_MODEL_UNRESOLVED`: which model, and so
+ * which vendor, is the app's call and never the framework's.
+ */
+export function resolveModel(
+  site: ModelSite,
+  ...candidates: readonly (ModelId | undefined)[]
+): ModelId {
+  for (const candidate of candidates) if (candidate !== undefined) return candidate;
+  throw new AiModelUnresolvedError(site);
+}
+
+/** A call that named no model: its own code, because the fix is a declaration, not a request. */
+export class AiModelUnresolvedError extends UltimateError {
+  constructor(site: ModelSite) {
+    super({
+      code: 'X_AI_MODEL_UNRESOLVED',
+      cause: `${site} resolved no model: no declaration, prompt or providerGateway({ defaultModel }) named one, and the framework chooses none (modelId: an id your app registerModel-ed and a configured provider lists)`,
+      fix: `${PLACES}   # one of the three`,
+    });
+  }
+}
+
+/**
+ * The model an `llm()` or `agent()` call runs on. The gateway is asked only when neither the
+ * declaration nor its prompt names one — and with none installed that is `X_AI_GATEWAY_MISSING`
+ * for `prompt`, because the third place does not exist yet: the boot call is the whole fix.
+ */
+export function modelForCall(
+  site: 'llm' | 'agent',
+  prompt: string,
+  declared: ModelId | undefined,
+  promptModel: ModelId | undefined,
+): ModelId {
+  if (declared !== undefined || promptModel !== undefined) {
+    return resolveModel(site, declared, promptModel);
+  }
+  return resolveModel(site, aiGateway(prompt).defaultModel);
+}
+
+/** Which of the app's three places a model came from. */
+export type ModelSource = 'declaration' | 'prompt' | 'gateway';
+
+const SOURCES: readonly ModelSource[] = ['declaration', 'prompt', 'gateway'];
+
+/**
+ * The same answer as `resolveModel`, over the same three candidates in the same order, WITHOUT
+ * refusing — and with where it came from. For a fact published about a declaration
+ * (`describeAgents()`): a reader describing an app is not a call, so a declaration that names no
+ * model yet (the gateway is installed later) is described as `undefined`, never thrown over.
+ */
+export function describedModel(
+  declared: ModelId | undefined,
+  prompt: ModelId | undefined,
+  gateway: ModelId | undefined,
+): { readonly model: ModelId | undefined; readonly from: ModelSource | undefined } {
+  const candidates = [declared, prompt, gateway];
+  for (const [at, candidate] of candidates.entries()) {
+    const from = SOURCES[at];
+    if (candidate !== undefined && from !== undefined) return { model: candidate, from };
+  }
+  return { model: undefined, from: undefined };
+}