theorum 0.1.2 → 0.1.4

package/src/kernel/registry/catalog.ts

@@ -0,0 +1,181 @@
+/**
+ * Tool catalog and MIME helpers.
+ *
+ * Model wire metadata is host-owned on `profile.model.config`. This module only
+ * keeps builtin/custom tool descriptors and shared MIME utilities.
+ *
+ * @module
+ */
+
+import { TheorumError } from '../../guardrails/error.ts';
+import type {
+  BuiltinToolId,
+  Catalog,
+  GeminiInputKind,
+  ModelId,
+  ModelSpec,
+  Profile,
+  ThinkingLevel,
+  ToolCatalogEntry,
+  ToolId,
+} from '../types.ts';
+
+const ASK_USER_SCHEMA = {
+  type: 'object',
+  properties: {
+    kind: { type: 'string', enum: ['confirm', 'choice', 'text'] },
+    prompt: { type: 'string' },
+    options: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['kind', 'prompt'],
+};
+
+/** Harness tools that always ship with THEORUM. */
+const HARNESS_TOOLS: Record<ToolId, ToolCatalogEntry> = {
+  askUser: { kind: 'custom', ui: true, schema: ASK_USER_SCHEMA },
+};
+
+/** Live tool catalog. Starts with harness tools; presets/hosts register more. */
+const CATALOG: Catalog = {
+  tools: { ...HARNESS_TOOLS },
+};
+
+/** Register or replace tool descriptors (idempotent per id). */
+function registerTools(entries: Record<string, ToolCatalogEntry>): void {
+  Object.assign(CATALOG.tools, entries);
+}
+
+/** Look up one registered tool descriptor. */
+function getTool(id: ToolId): ToolCatalogEntry | undefined {
+  return CATALOG.tools[id];
+}
+
+/** Ids of all registered provider builtins. */
+function listBuiltinIds(): BuiltinToolId[] {
+  return Object.entries(CATALOG.tools)
+    .filter(([, entry]) => entry.kind === 'builtin')
+    .map(([id]) => id);
+}
+
+/** Restore harness-only tools (tests / host reloads). */
+function resetTools(): void {
+  for (const id of Object.keys(CATALOG.tools)) {
+    delete CATALOG.tools[id];
+  }
+  Object.assign(CATALOG.tools, HARNESS_TOOLS);
+}
+
+/** Gemini Interactions inline MIME → part type (adapter wire map). */
+const GEMINI_INPUT_KINDS: Record<string, GeminiInputKind> = {
+  'image/png': 'image',
+  'image/jpeg': 'image',
+  'image/jpg': 'image',
+  'image/webp': 'image',
+  'image/heic': 'image',
+  'image/heif': 'image',
+  'audio/wav': 'audio',
+  'audio/x-wav': 'audio',
+  'audio/mpeg': 'audio',
+  'audio/mp3': 'audio',
+  'audio/aiff': 'audio',
+  'audio/aac': 'audio',
+  'audio/ogg': 'audio',
+  'audio/flac': 'audio',
+  'audio/webm': 'audio',
+  'audio/mp4': 'audio',
+  'audio/pcm': 'audio',
+  'video/mp4': 'video',
+  'video/mpeg': 'video',
+  'video/quicktime': 'video',
+  'video/x-msvideo': 'video',
+  'video/x-flv': 'video',
+  'video/mpg': 'video',
+  'video/webm': 'video',
+  'video/wmv': 'video',
+  'video/x-ms-wmv': 'video',
+  'video/3gpp': 'video',
+  'application/pdf': 'document',
+  'text/plain': 'document',
+  'text/csv': 'document',
+  'text/markdown': 'document',
+  'text/html': 'document',
+  'application/json': 'document',
+};
+
+function mimeEssence(mime: string): string {
+  const [base] = mime.split(';');
+  return (base ?? '').trim().toLowerCase();
+}
+
+function mimeAllowed(accept: string[], mime: string): boolean {
+  const actual = mimeEssence(mime);
+  return accept.some((rule) => {
+    const allowed = mimeEssence(rule);
+    if (allowed.endsWith('/*')) {
+      return actual.startsWith(allowed.slice(0, -1));
+    }
+    return allowed === actual;
+  });
+}
+
+function geminiKindForMime(mime: string): GeminiInputKind | undefined {
+  return GEMINI_INPUT_KINDS[mimeEssence(mime)];
+}
+
+/** Require a host-declared model spec for an allowed profile model id. */
+function requireModelSpec(profile: Profile, modelId: ModelId): ModelSpec {
+  const spec = profile.model.config[modelId];
+  if (!spec) {
+    throw new TheorumError(`Profile ${profile.id} has no model spec for '${modelId}'`);
+  }
+  return spec;
+}
+
+function clampLevels(entry: ModelSpec | undefined, level: ThinkingLevel): ThinkingLevel {
+  if (!entry?.thinkingLevels || entry.thinkingLevels.length === 0) {
+    return level;
+  }
+  if (entry.thinkingLevels.includes(level)) {
+    return level;
+  }
+  const fallback = entry.thinking.off;
+  if (entry.thinkingLevels.includes(fallback)) {
+    return fallback;
+  }
+  const first = entry.thinkingLevels[0];
+  return first ?? level;
+}
+
+/** Clamp a requested thinking level to what the model spec accepts. */
+function clampThinkingLevel(spec: ModelSpec, level: ThinkingLevel): ThinkingLevel {
+  return clampLevels(spec, level);
+}
+
+/** Look up a model spec by provider-native API id within a host specs map. */
+function modelEntryByApiId(specs: Record<string, ModelSpec>, apiId: string): ModelSpec | undefined {
+  return Object.values(specs).find((m) => m.apiId === apiId);
+}
+
+/** Clamp thinking level using a provider-native API id within a host specs map. */
+function clampThinkingLevelForApiId(
+  specs: Record<string, ModelSpec>,
+  apiId: string,
+  level: ThinkingLevel,
+): ThinkingLevel {
+  return clampLevels(modelEntryByApiId(specs, apiId), level);
+}
+
+export {
+  CATALOG,
+  clampThinkingLevel,
+  clampThinkingLevelForApiId,
+  geminiKindForMime,
+  getTool,
+  listBuiltinIds,
+  mimeAllowed,
+  mimeEssence,
+  modelEntryByApiId,
+  registerTools,
+  requireModelSpec,
+  resetTools,
+};

package/src/kernel/registry/ingress.ts

@@ -0,0 +1,223 @@
+/**
+ * Kernel ingress: input parts, image pins, and speech-role checks.
+ *
+ * Owned by the kernel so `resolveTurn` does not import provider adapters.
+ *
+ * @module
+ */
+
+import { TheorumError } from '../../guardrails/error.ts';
+import { wrapUserData } from '../engine/boundary.ts';
+import { synthesizeRepairPrompt } from '../engine/repair.ts';
+import type {
+  BuiltinToolId,
+  GeminiInputKind,
+  ImageResponseFormat,
+  InteractionPart,
+  ModelId,
+  Profile,
+  TurnBlob,
+  TurnRequest,
+} from '../types.ts';
+import { assertAttachmentLimits, requireMediaLimits } from './attachments.ts';
+import { geminiKindForMime, mimeAllowed, mimeEssence } from './catalog.ts';
+
+function listedValue(allowed: string[] | undefined, value: string | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+  if (!allowed || allowed.length === 0) {
+    return value;
+  }
+  if (allowed.includes(value)) {
+    return value;
+  }
+  return undefined;
+}
+
+function resolveSlotOrPin(
+  profileId: string,
+  label: string,
+  slotValue: string | undefined,
+  pin: string | undefined,
+  allow: string[] | undefined,
+): string | undefined {
+  if (slotValue !== undefined) {
+    const fromSlot = listedValue(allow, slotValue);
+    if (!fromSlot) {
+      throw new TheorumError(`Unknown image ${label} for ${profileId}`);
+    }
+    return fromSlot;
+  }
+  if (pin === undefined) {
+    return undefined;
+  }
+  const fromPin = listedValue(allow, pin);
+  if (!fromPin) {
+    throw new TheorumError(`Unknown image ${label} for ${profileId}`);
+  }
+  return fromPin;
+}
+
+function assertImageRole(profile: Profile): NonNullable<Profile['outputs']['image']> {
+  const pins = profile.outputs.image;
+  if (!pins) {
+    throw new TheorumError(
+      `Profile ${profile.id} requests image output but does not set outputs.image`,
+    );
+  }
+  assertExclusiveNativeOutput(profile, 'image');
+  return pins;
+}
+
+function assertSpeechRole(profile: Profile): void {
+  if (!profile.outputs.speech) {
+    return;
+  }
+  assertExclusiveNativeOutput(profile, 'speech');
+  if (profile.outputs.speech.format === 'mp3' && profile.model.protocol === 'geminiInteractions') {
+    throw new TheorumError(
+      `Profile ${profile.id}: outputs.speech.format 'mp3' requires protocol 'openAi' ` +
+        `(geminiInteractions speech returns PCM and emits WAV)`,
+    );
+  }
+}
+
+function assertExclusiveNativeOutput(profile: Profile, kind: 'image' | 'speech'): void {
+  const other = kind === 'image' ? 'speech' : 'image';
+  if (profile.outputs[other]) {
+    throw new TheorumError(
+      `Profile ${profile.id} cannot mix outputs.${kind} with outputs.${other}`,
+    );
+  }
+  if (profile.outputs.structured !== null && profile.outputs.structured !== undefined) {
+    throw new TheorumError(
+      `Profile ${profile.id} cannot mix structured JSON with native ${kind} output`,
+    );
+  }
+}
+
+function resolveImageFormat(
+  profile: Profile,
+  _model: ModelId,
+  slots?: Record<string, string>,
+): ImageResponseFormat | null {
+  if (!profile.outputs.image) {
+    return null;
+  }
+  const pins = assertImageRole(profile);
+  const aspectRatio = resolveSlotOrPin(
+    profile.id,
+    'aspect',
+    slots?.aspectRatio,
+    pins.aspectRatio,
+    profile.inputs.slots?.aspectRatio,
+  );
+  const size = resolveSlotOrPin(
+    profile.id,
+    'size',
+    slots?.size,
+    pins.size,
+    profile.inputs.slots?.size,
+  );
+  if (!(aspectRatio && size)) {
+    throw new TheorumError(`Unknown image aspect or size for ${profile.id}`);
+  }
+  return {
+    type: 'image',
+    mimeType: pins.mimeType ?? 'image/jpeg',
+    aspectRatio,
+    size,
+  };
+}
+
+function assertGeminiMime(mime: string): GeminiInputKind {
+  const kind = geminiKindForMime(mime);
+  if (!kind) {
+    throw new TheorumError(`MIME '${mime}' is not a Gemini input type`);
+  }
+  return kind;
+}
+
+function mediaParts(
+  profile: Profile,
+  model: ModelId,
+  blobs: TurnBlob[],
+  channel: 'attachments' | 'voice',
+): InteractionPart[] {
+  const accept =
+    channel === 'voice' ? profile.inputs.voice?.accept : profile.inputs.attachments?.accept;
+  if (!accept) {
+    throw new TheorumError(`Profile ${profile.id} does not accept ${channel}`);
+  }
+  const maxInputImages = profile.outputs.image?.maxInputImages;
+  const imageCount = blobs.filter((blob) => geminiKindForMime(blob.mimeType) === 'image').length;
+  if (maxInputImages !== undefined && imageCount > maxInputImages) {
+    throw new TheorumError(`At most ${maxInputImages} reference images on ${model}`);
+  }
+  return blobs.map((blob) => {
+    const kind = assertGeminiMime(blob.mimeType);
+    if (!mimeAllowed(accept, blob.mimeType)) {
+      throw new TheorumError(`MIME '${blob.mimeType}' is not accepted on ${profile.id}`);
+    }
+    const essence = mimeEssence(blob.mimeType);
+    return {
+      type: kind,
+      mimeType: essence === 'image/jpg' ? 'image/jpeg' : essence,
+      data: blob.data,
+    };
+  });
+}
+
+function extractTextPart(profile: Profile, req: TurnRequest): InteractionPart | null {
+  const { text, repair, history } = req.input ?? {};
+  if (profile.inputs.text === false) {
+    if (text) {
+      throw new TheorumError(`Profile ${profile.id} does not accept text input`);
+    }
+    return null;
+  }
+  let promptText = text;
+  if (repair) {
+    promptText = synthesizeRepairPrompt({ profile, repair, history });
+  }
+  if (!promptText) {
+    return null;
+  }
+  return { type: 'text', text: wrapUserData(promptText) };
+}
+
+function extractMediaParts(profile: Profile, model: ModelId, req: TurnRequest): InteractionPart[] {
+  const { attachments, voice } = req.input ?? {};
+  const files = attachments ?? [];
+  const clips = voice ?? [];
+  if (files.length + clips.length > 0) {
+    assertAttachmentLimits([...files, ...clips], requireMediaLimits(profile));
+  }
+  const parts: InteractionPart[] = [];
+  if (files.length > 0) {
+    parts.push(...mediaParts(profile, model, files, 'attachments'));
+  }
+  if (clips.length > 0) {
+    parts.push(...mediaParts(profile, model, clips, 'voice'));
+  }
+  return parts;
+}
+
+function resolveInputParts(profile: Profile, model: ModelId, req: TurnRequest): InteractionPart[] {
+  const parts: InteractionPart[] = [];
+  const textPart = extractTextPart(profile, req);
+  if (textPart) {
+    parts.push(textPart);
+  }
+  parts.push(...extractMediaParts(profile, model, req));
+  return parts;
+}
+
+function assertImageGrounding(profile: Profile, model: ModelId, builtins: BuiltinToolId[]): void {
+  if (profile.outputs.image?.allowsGrounding === false && builtins.length > 0) {
+    throw new TheorumError(`Grounding tools are not valid on ${model}`);
+  }
+}
+
+export { assertImageGrounding, assertSpeechRole, resolveImageFormat, resolveInputParts };

package/src/kernel/registry/profiles.ts

@@ -0,0 +1,165 @@
+/**
+ * Runtime profile registry for host-owned THEORUM profiles.
+ *
+ * THEORUM ships profile types and defaults, not application profiles. Host apps
+ * register their profiles at process startup or test setup.
+ *
+ * @module
+ */
+
+import { TheorumError } from '../../guardrails/error.ts';
+import type { ModelId, Profile } from '../types.ts';
+
+const profiles = new Map<string, Profile>();
+
+/** Host-authored profile definition, with defaults applied to omitted sections. */
+export type ProfileDefinition = {
+  id: Profile['id'];
+  identity?: Partial<Profile['identity']>;
+  model: Partial<Profile['model']> & Pick<Profile['model'], 'allow' | 'config'>;
+  tools?: Partial<Profile['tools']>;
+  inputs?: Partial<Profile['inputs']>;
+  outputs?: Partial<Profile['outputs']>;
+  guardrails?: Partial<Profile['guardrails']>;
+};
+
+function assertModelSpecs(
+  profileId: string,
+  allow: ModelId[],
+  config: Profile['model']['config'],
+): void {
+  for (const id of allow) {
+    if (!config[id]) {
+      throw new TheorumError(`Profile ${profileId} allowlists '${id}' without a model spec`);
+    }
+  }
+}
+
+function buildDefaultIdentity(
+  id: Profile['id'],
+  identity?: Partial<Profile['identity']>,
+): Profile['identity'] {
+  return {
+    handle: identity?.handle ?? id,
+    chat: identity?.chat,
+    system: identity?.system,
+    systemByRole: identity?.systemByRole,
+  };
+}
+
+function buildDefaultModel(profileId: string, model: ProfileDefinition['model']): Profile['model'] {
+  assertModelSpecs(profileId, model.allow, model.config);
+  return {
+    protocol: model.protocol ?? 'geminiInteractions',
+    provider: model.provider ?? 'google',
+    allow: model.allow,
+    config: model.config,
+    thinking: model.thinking ?? 'minimal',
+    controls: model.controls ?? [],
+    maxSteps: model.maxSteps ?? 1,
+    key: model.key ?? 'freeA',
+    select: model.select,
+  };
+}
+
+function buildDefaultInputs(inputs?: Partial<Profile['inputs']>): Profile['inputs'] {
+  return {
+    text: inputs?.text ?? true,
+    attachments: inputs?.attachments,
+    voice: inputs?.voice,
+    maxFiles: inputs?.maxFiles,
+    maxBytes: inputs?.maxBytes,
+    maxTurnBytes: inputs?.maxTurnBytes,
+    limitsByMime: inputs?.limitsByMime,
+    slots: inputs?.slots,
+  };
+}
+
+function buildDefaultOutputs(outputs?: Partial<Profile['outputs']>): Profile['outputs'] {
+  return {
+    structured: outputs?.structured ?? null,
+    image: outputs?.image,
+    speech: outputs?.speech,
+    validation: outputs?.validation,
+    streaming: outputs?.streaming,
+  };
+}
+
+function buildDefaultGuardrails(
+  guardrails?: Partial<Profile['guardrails']>,
+): Profile['guardrails'] {
+  return {
+    quota: guardrails?.quota,
+    canary: guardrails?.canary ?? true,
+    sanitizeInput: guardrails?.sanitizeInput ?? true,
+    redactSensitive: guardrails?.redactSensitive ?? true,
+    egress: guardrails?.egress,
+  };
+}
+
+/** Define a typed profile with stable defaults for optional properties. */
+function defineProfile(input: ProfileDefinition): Profile {
+  return {
+    id: input.id,
+    identity: buildDefaultIdentity(input.id, input.identity),
+    model: buildDefaultModel(input.id, input.model),
+    tools: { allow: input.tools?.allow ?? [] },
+    inputs: buildDefaultInputs(input.inputs),
+    outputs: buildDefaultOutputs(input.outputs),
+    guardrails: buildDefaultGuardrails(input.guardrails),
+  };
+}
+
+/** Register one host-owned profile in the process-local registry. */
+function registerProfile(profileInput: Profile | ProfileDefinition): void {
+  const profile = defineProfile(profileInput);
+  assertModelSpecs(profile.id, profile.model.allow, profile.model.config);
+  const { attachments, voice, maxFiles, maxBytes, maxTurnBytes } = profile.inputs;
+  if (attachments || voice) {
+    if (!(maxFiles && maxBytes && maxTurnBytes)) {
+      throw new TheorumError(`Profile ${profile.id} must set maxFiles, maxBytes, and maxTurnBytes`);
+    }
+  }
+  profiles.set(profile.id, profile);
+}
+
+/** Register several host-owned profiles in order. */
+function registerProfiles(profilesList: Array<Profile | ProfileDefinition>): void {
+  for (const p of profilesList) {
+    registerProfile(p);
+  }
+}
+
+/** Return whether a profile id is currently registered. */
+function hasProfile(id: string): boolean {
+  return profiles.has(id);
+}
+
+/** List all currently registered profiles. */
+function listProfiles(): Profile[] {
+  return Array.from(profiles.values());
+}
+
+/** Clear the process-local registry; intended for tests and host reloads. */
+function clearProfiles(): void {
+  profiles.clear();
+}
+
+/** Fetch a registered profile or throw a `TheorumError`. */
+function getProfile(id: string): Profile {
+  const profile = profiles.get(id);
+  if (!profile) {
+    throw new TheorumError(`Unknown profile '${id}'`);
+  }
+  return profile;
+}
+
+export {
+  clearProfiles,
+  defineProfile,
+  getProfile,
+  hasProfile,
+  listProfiles,
+  registerProfile,
+  registerProfiles,
+};

package/src/kernel/registry/provider-request.ts

@@ -0,0 +1,31 @@
+import type { ProviderCompleteRequest, ResolvedGeneration } from '../types.ts';
+
+/** Build the provider request projection shared by execution and tracing. */
+function providerCompleteRequest(
+  generation: ResolvedGeneration,
+  system: string,
+): ProviderCompleteRequest {
+  return {
+    model: generation.model,
+    apiId: generation.apiId,
+    openRouterId: generation.openRouterId,
+    previousInteractionId: generation.previousInteractionId,
+    store: generation.store,
+    thinking: generation.thinking,
+    summaries: generation.summaries,
+    maxOutputTokens: generation.maxOutputTokens,
+    temperature: generation.temperature,
+    builtins: generation.builtins,
+    system,
+    input: generation.input,
+    history: generation.history,
+    dynamicTools: generation.dynamicTools,
+    dynamicToolLoader: generation.dynamicToolLoader,
+    structured: generation.structured,
+    image: generation.image,
+    speech: generation.speech,
+    geminiBucket: generation.geminiBucket,
+  };
+}
+
+export { providerCompleteRequest };