@ultimat3/ai 23.0.0 → 25.0.0

package/src/index.ts

@@ -11,28 +11,50 @@ export { describeAgents, resetAgents } from './agent-facts';
 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,
-  fnv1a,
-  HashEmbedder,
-  normalize,
-  tokenize,
+  hashEmbedder,
+  normalizeVector,
+  wordTokens,
 } from './embeddings';
 export type { AiErrorCode } from './errors';
 export {
@@ -92,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';
@@ -102,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,
@@ -116,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,
@@ -135,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,
@@ -156,9 +192,8 @@ export type {
   TokenUsage,
 } from './provider';
 export {
-  AnthropicProvider,
+  anthropicProvider,
   costOf,
-  EchoProvider,
   estimateCost,
   estimateInputTokens,
   estimateTextTokens,
@@ -177,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';
@@ -210,6 +250,7 @@ export type {
 export { asProjectableAction, runLlmToolCall, toLlmTool, toLlmTools } from './tools';
 export type {
   HybridSearchInput,
+  MemoryVectorStore,
   MemoryVectorStoreInput,
   MetadataFilter,
   SearchHit,
@@ -217,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 } from './vector-scope';
+export { NO_VECTOR_TENANT, tenantOf, UNSCOPED, VectorUnscopedError } from './vector-scope';
 export type { StreamState } from './wire';

package/src/llm-cache.ts

@@ -16,8 +16,9 @@
  */
 
 import type { Ctx } from '@ultimat3/core';
+import { fingerprint } from '@ultimat3/core';
 import { parseDuration } from '@ultimat3/time';
-import { embedOne, fnv1a } from './embeddings';
+import { embedOne } from './embeddings';
 import { aiEmbedder, semanticCacheFor } from './runtime';
 
 /** What a `scope` may decide from. The same pair `vars()` receives, and for the same reason. */
@@ -73,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.
  */
@@ -119,7 +120,7 @@ export async function openCache<TParsed>(
     },
     remember(value: unknown): Promise<void> {
       return store.remember(
-        `${args.prompt.hash}:${fnv1a(args.rendered).toString(16)}`,
+        `${args.prompt.hash}:${fingerprint(args.rendered)}`,
         embedding,
         value,
         ttlMs === undefined ? {} : { ttlMs },

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
@@ -27,9 +27,9 @@ import type { Ctx, Span, SpanAttributes } from '@ultimat3/core';
 import { finiteCount, withSpan } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
-import { formatIssues, toMcpInputSchema, validateAsync } from '@ultimat3/schema';
+import { formatIssues, validateAsync } from '@ultimat3/schema';
 import type { BudgetLimits } from './budget';
-import { BudgetLedger, currentBudget, withBudget } from './budget';
+import { budgetKeysFor, currentBudget, screenedMoney, withBudget } from './budget';
 import {
   LlmOutputInvalidError,
   LlmRefusedError,
@@ -41,21 +41,16 @@ 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';
 import { assertNoSecrets } from './redaction';
+import type { Respond } from './respond';
+import { parseJsonish, RESPOND, respondFor } from './respond';
 import { aiGateway, aiRedactor } from './runtime';
-import type { LlmTool } from './tools';
-
-/**
- * The tool the model answers through. One name, so the reader never has to guess — and shared
- * with `agent()`, which offers the app's tools alongside it and needs the same name to tell an
- * answer from a tool call.
- */
-export const RESPOND = 'respond';
 
 /** Two attempts total: the answer, then one repair turn. See `LlmOutputInvalidError`. */
 const ATTEMPTS = 2;
@@ -107,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.
  */
@@ -138,8 +133,8 @@ export function llm<
   TOutput extends StandardSchemaV1,
   V extends PromptVars,
 >(def: LlmDef<TInput, TOutput, V>): LlmAction<TInput, TOutput> {
-  const respond = respondToolFor(def.output);
-  // Screened at DECLARATION, beside `respondToolFor`'s own refusal and for the same reason: an
+  const respond = respondFor(def.output);
+  // Screened at DECLARATION, beside `respondFor`'s own refusal and for the same reason: an
   // `llm()` is evaluated at module scope, so a bound that is not one fails the boot rather than
   // the first request. It is the read at `generate` below that makes it urgent — `maxTokens`
   // becomes the pre-flight ESTIMATE, a `NaN` estimate passes every `want > remaining` check, and
@@ -190,14 +185,17 @@ async function generate<
   V extends PromptVars,
 >(
   def: LlmDef<TInput, TOutput, V>,
-  respond: LlmTool,
+  respond: Respond,
   args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
 ): Promise<InferOutput<TOutput>> {
   const { prompt } = def;
   // 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
@@ -250,20 +248,17 @@ async function generate<
       // the provider call in flight, billed and unread, and the repair turn bought a SECOND one.
       signal: args.ctx.signal,
     };
-    const request: GenerateRequest = { ...base, tools: [respond] };
+    const request: GenerateRequest = { ...base, tools: [respond.tool] };
 
     // 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);
-    const ledger = (
-      currentBudget() ??
-      gateway.callLedger?.() ??
-      new BudgetLedger({ limits: {} })
-    ).derive(limits);
+    // Keyed on the CALLER, so the gateway's `actor` / `org` ceilings count this call against them.
+    const ledger = (currentBudget() ?? gateway.callLedger(budgetKeysFor(args.ctx.actor))).derive(
+      limits,
+    );
     const sink = currentLlmSink();
 
     return withBudget(ledger, async () => {
@@ -287,12 +282,12 @@ 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,
           });
         }
-        const parsed = await validateAsync(def.output, structuredOutputOf(result));
+        const parsed = await validateAsync(def.output, respond.read(result));
         if (parsed.issues === undefined) {
           await cache?.remember(parsed.value);
           return parsed.value;
@@ -353,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,
     });
@@ -399,22 +394,9 @@ function limitsOf(budget: LlmBudget | undefined): BudgetLimits {
     ...(budget?.tokensIn === undefined
       ? {}
       : { tokensIn: finiteCount('llm', 'budget.tokensIn', budget.tokensIn) }),
-    ...(budget?.costPerCall === undefined ? {} : { costPerCall: budget.costPerCall }),
-  };
-}
-
-/**
- * The output schema as the only tool the model may answer through — the spec's "structured
- * output drives tool use". `toMcpInputSchema` is the same projection an MCP client sees, so
- * a model and an agent are shown one shape, and a schema it cannot express throws HERE, at
- * declaration time, rather than degrading into a permissive node the model cannot satisfy.
- */
-export function respondToolFor(output: StandardSchemaV1): LlmTool {
-  return {
-    name: RESPOND,
-    description: 'Return the result. Call this exactly once; do not answer in prose.',
-    input_schema: toMcpInputSchema(output),
-    strict: true,
+    ...(budget?.costPerCall === undefined
+      ? {}
+      : { costPerCall: screenedMoney('llm', 'budget.costPerCall', budget.costPerCall) }),
   };
 }
 
@@ -436,23 +418,3 @@ function assistantEcho(result: GenerateResult): string | undefined {
   const replayed = JSON.stringify(call.input);
   return replayed === undefined || replayed === '' ? undefined : replayed;
 }
-
-/**
- * The tool call if the model made one, otherwise the text parsed as JSON — a model that
- * answers in prose is a schema failure, not a crash, so it flows into the repair turn.
- */
-export function structuredOutputOf(result: GenerateResult): unknown {
-  const call = result.toolCalls.find((c) => c.name === RESPOND);
-  if (call !== undefined) return call.input;
-  return parseJsonish(result.text);
-}
-
-function parseJsonish(text: string): unknown {
-  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
-  const body = (fenced?.[1] ?? text).trim();
-  try {
-    return JSON.parse(body);
-  } catch {
-    return undefined;
-  }
-}

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 };
+}