theorum 0.1.4 → 0.1.5

package/src/kernel/registry/catalog.ts

@@ -1,181 +0,0 @@
-/**
- * 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

@@ -1,223 +0,0 @@
-/**
- * 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

@@ -1,165 +0,0 @@
-/**
- * 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

@@ -1,31 +0,0 @@
-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 };