theorum 0.1.2

package/esm/src/kernel/engine/tree.d.ts

@@ -0,0 +1,2 @@
+declare function mapStrings(value: unknown, map: (text: string) => string): unknown;
+export { mapStrings };

package/esm/src/kernel/engine/tree.js

@@ -0,0 +1,17 @@
+function mapStrings(value, map) {
+    if (typeof value === 'string') {
+        return map(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => mapStrings(item, map));
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            out[key] = mapStrings(nested, map);
+        }
+        return out;
+    }
+    return value;
+}
+export { mapStrings };

package/esm/src/kernel/mod.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Profile, turn, tool, provider, egress, and event contracts for THEORUM.
+ *
+ * This entrypoint is type-first. Host applications import from here when they
+ * want to declare profiles, tool schemas, provider adapters, turn requests, or
+ * trace-safe event handlers without importing provider implementations.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { runTurn } from './engine/runner.js';
+export { defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
+export { projectProfile, resolveTurn } from './registry/resolve.js';
+export { getStructured, registerStructured } from './registry/schemas.js';
+export { executeTool } from './registry/tools.js';
+export type * from './types.js';

package/esm/src/kernel/mod.js

@@ -0,0 +1,15 @@
+/**
+ * Profile, turn, tool, provider, egress, and event contracts for THEORUM.
+ *
+ * This entrypoint is type-first. Host applications import from here when they
+ * want to declare profiles, tool schemas, provider adapters, turn requests, or
+ * trace-safe event handlers without importing provider implementations.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { runTurn } from './engine/runner.js';
+export { defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
+export { projectProfile, resolveTurn } from './registry/resolve.js';
+export { getStructured, registerStructured } from './registry/schemas.js';
+export { executeTool } from './registry/tools.js';

package/esm/src/kernel/registry/catalog.d.ts

@@ -0,0 +1,24 @@
+import type { Catalog, GeminiInputKind, ImageAspectRatio, ImageSize, ModelCatalogEntry, ThinkingLevel } from '../types.js';
+declare const IMAGE_INPUT_MIMES: string[];
+declare const VOICE_INPUT_MIMES: string[];
+/** Default chat media caps. Host profiles may copy or override these limits. */
+declare const CHAT_MEDIA_LIMITS: {
+    readonly maxFiles: 10;
+    readonly maxBytes: number;
+    readonly maxTurnBytes: number;
+};
+/** Gemini Interactions inline MIME → part type. Profiles allowlist from this set. */
+declare const GEMINI_INPUT_KINDS: Record<string, GeminiInputKind>;
+declare function mimeEssence(mime: string): string;
+declare function mimeAllowed(accept: string[], mime: string): boolean;
+declare function geminiKindForMime(mime: string): GeminiInputKind | undefined;
+declare const IMAGE_FLASH_LITE_ASPECT_RATIOS: ImageAspectRatio[];
+declare const IMAGE_FLASH_LITE_SIZES: ImageSize[];
+declare const CATALOG: Catalog;
+export { CATALOG, CHAT_MEDIA_LIMITS, GEMINI_INPUT_KINDS, geminiKindForMime, IMAGE_FLASH_LITE_ASPECT_RATIOS, IMAGE_FLASH_LITE_SIZES, IMAGE_INPUT_MIMES, mimeAllowed, mimeEssence, VOICE_INPUT_MIMES, };
+export declare const MODEL_CATALOG: Record<import("../types.js").ModelId, ModelCatalogEntry>;
+export declare function modelEntry(modelId: string): ModelCatalogEntry;
+/** Clamp a requested thinking level to what the selected model accepts. */
+export declare function clampThinkingLevel(modelId: string, level: ThinkingLevel): ThinkingLevel;
+export declare function modelEntryByApiId(apiId: string): ModelCatalogEntry | undefined;
+export declare function clampThinkingLevelForApiId(apiId: string, level: ThinkingLevel): ThinkingLevel;

package/esm/src/kernel/registry/catalog.js

@@ -0,0 +1,213 @@
+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'],
+};
+const DEFAULT_TEMPERATURE = 1;
+const FLASH_LITE_MAX_OUTPUT_TOKENS = 8192;
+const PRO_PREVIEW_MAX_OUTPUT_TOKENS = 64_000;
+const IMAGE_FLASH_LITE_MAX_OUTPUT_TOKENS = 4096;
+const TTS_FLASH_MAX_OUTPUT_TOKENS = 2048;
+const SONAR_MAX_OUTPUT_TOKENS = 8192;
+const IMAGE_INPUT_MIMES = ['image/png', 'image/jpeg', 'image/webp', 'image/heic', 'image/heif'];
+const VOICE_INPUT_MIMES = ['audio/webm', 'audio/wav', 'audio/mpeg', 'audio/mp4'];
+const KIB = 1024;
+const MIB = KIB * KIB;
+/** Default chat media caps. Host profiles may copy or override these limits. */
+const CHAT_MEDIA_LIMITS = {
+    maxFiles: 10,
+    maxBytes: 8 * MIB,
+    maxTurnBytes: 32 * MIB,
+};
+/** Gemini Interactions inline MIME → part type. Profiles allowlist from this set. */
+const GEMINI_INPUT_KINDS = {
+    '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) {
+    const [base] = mime.split(';');
+    return (base ?? '').trim().toLowerCase();
+}
+function mimeAllowed(accept, mime) {
+    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) {
+    return GEMINI_INPUT_KINDS[mimeEssence(mime)];
+}
+const IMAGE_FLASH_LITE_ASPECT_RATIOS = [
+    '1:1',
+    '3:2',
+    '2:3',
+    '3:4',
+    '4:3',
+    '4:5',
+    '5:4',
+    '9:16',
+    '16:9',
+    '21:9',
+];
+const IMAGE_FLASH_LITE_SIZES = ['1K'];
+const FLASH_LITE_THINKING_LEVELS = ['minimal', 'low', 'medium', 'high'];
+const PRO_PREVIEW_THINKING_LEVELS = ['low', 'medium', 'high'];
+const IMAGE_FLASH_LITE_THINKING_LEVELS = ['minimal', 'high'];
+const TTS_THINKING_LEVELS = ['minimal'];
+const OPENROUTER_SEARCH_THINKING_LEVELS = ['low', 'medium', 'high'];
+const GENERIC_MODEL_ENTRY = {
+    apiId: '',
+    thinking: { on: 'high', off: 'low' },
+    thinkingLevels: ['low', 'medium', 'high'],
+    summaries: { on: 'auto', off: 'none' },
+    maxOutputTokens: FLASH_LITE_MAX_OUTPUT_TOKENS,
+    temperature: DEFAULT_TEMPERATURE,
+    freeBuiltins: [],
+};
+const CATALOG = {
+    models: {
+        gemini31FlashLite: {
+            apiId: 'gemini-3.1-flash-lite',
+            thinking: { on: 'high', off: 'minimal' },
+            thinkingLevels: FLASH_LITE_THINKING_LEVELS,
+            summaries: { on: 'auto', off: 'none' },
+            maxOutputTokens: FLASH_LITE_MAX_OUTPUT_TOKENS,
+            temperature: DEFAULT_TEMPERATURE,
+            freeBuiltins: ['googleMaps', 'urlContext'],
+        },
+        gemini31ProPreview: {
+            apiId: 'gemini-3.1-pro-preview',
+            thinking: { on: 'high', off: 'low' },
+            thinkingLevels: PRO_PREVIEW_THINKING_LEVELS,
+            summaries: { on: 'auto', off: 'none' },
+            maxOutputTokens: PRO_PREVIEW_MAX_OUTPUT_TOKENS,
+            temperature: DEFAULT_TEMPERATURE,
+            freeBuiltins: [],
+        },
+        gemini35FlashLite: {
+            apiId: 'gemini-3.5-flash-lite',
+            thinking: { on: 'high', off: 'minimal' },
+            thinkingLevels: FLASH_LITE_THINKING_LEVELS,
+            summaries: { on: 'auto', off: 'none' },
+            maxOutputTokens: FLASH_LITE_MAX_OUTPUT_TOKENS,
+            temperature: DEFAULT_TEMPERATURE,
+            freeBuiltins: ['googleMaps', 'urlContext'],
+        },
+        gemini31FlashLiteImage: {
+            apiId: 'gemini-3.1-flash-lite-image',
+            thinking: { on: 'high', off: 'minimal' },
+            thinkingLevels: IMAGE_FLASH_LITE_THINKING_LEVELS,
+            summaries: { on: 'none', off: 'none' },
+            maxOutputTokens: IMAGE_FLASH_LITE_MAX_OUTPUT_TOKENS,
+            temperature: DEFAULT_TEMPERATURE,
+            freeBuiltins: [],
+            image: {
+                maxInputImages: 14,
+                inputMimes: IMAGE_INPUT_MIMES,
+                sizes: IMAGE_FLASH_LITE_SIZES,
+                aspectRatios: IMAGE_FLASH_LITE_ASPECT_RATIOS,
+                outputMime: 'image/jpeg',
+                allowsGrounding: false,
+            },
+        },
+        gemini31FlashTts: {
+            apiId: 'gemini-3.1-flash-tts-preview',
+            thinking: { on: 'minimal', off: 'minimal' },
+            thinkingLevels: TTS_THINKING_LEVELS,
+            summaries: { on: 'none', off: 'none' },
+            maxOutputTokens: TTS_FLASH_MAX_OUTPUT_TOKENS,
+            temperature: DEFAULT_TEMPERATURE,
+            freeBuiltins: [],
+        },
+        sonar: {
+            apiId: 'sonar',
+            openRouterId: 'perplexity/sonar',
+            thinking: { on: 'high', off: 'low' },
+            thinkingLevels: OPENROUTER_SEARCH_THINKING_LEVELS,
+            summaries: { on: 'none', off: 'none' },
+            maxOutputTokens: SONAR_MAX_OUTPUT_TOKENS,
+            temperature: DEFAULT_TEMPERATURE,
+            freeBuiltins: [],
+        },
+    },
+    // Off until the turn sets tools[id]. Profile allow is only the ceiling.
+    tools: {
+        googleSearch: { kind: 'builtin', ui: true },
+        googleMaps: { kind: 'builtin', ui: true },
+        urlContext: { kind: 'builtin', ui: true },
+        askUser: { kind: 'custom', ui: true, schema: ASK_USER_SCHEMA },
+    },
+};
+export { CATALOG, CHAT_MEDIA_LIMITS, GEMINI_INPUT_KINDS, geminiKindForMime, IMAGE_FLASH_LITE_ASPECT_RATIOS, IMAGE_FLASH_LITE_SIZES, IMAGE_INPUT_MIMES, mimeAllowed, mimeEssence, VOICE_INPUT_MIMES, };
+export const MODEL_CATALOG = CATALOG.models;
+export function modelEntry(modelId) {
+    return (MODEL_CATALOG[modelId] ?? {
+        ...GENERIC_MODEL_ENTRY,
+        apiId: modelId,
+        openRouterId: modelId,
+    });
+}
+function clampLevels(entry, level) {
+    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 selected model accepts. */
+export function clampThinkingLevel(modelId, level) {
+    return clampLevels(modelEntry(modelId), level);
+}
+export function modelEntryByApiId(apiId) {
+    return Object.values(MODEL_CATALOG).find((m) => m.apiId === apiId);
+}
+export function clampThinkingLevelForApiId(apiId, level) {
+    const entry = modelEntryByApiId(apiId);
+    return clampLevels(entry, level);
+}

package/esm/src/kernel/registry/profiles.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 type { Profile } from '../types.js';
+/** 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'>;
+    tools?: Partial<Profile['tools']>;
+    inputs?: Partial<Profile['inputs']>;
+    outputs?: Partial<Profile['outputs']>;
+    guardrails?: Partial<Profile['guardrails']>;
+};
+/** Backwards-compatible alias for callers using the older name. */
+export type DefineProfileInput = ProfileDefinition;
+/** Define a typed profile with stable defaults for optional properties. */
+declare function defineProfile(input: DefineProfileInput): Profile;
+/** Register one host-owned profile in the process-local registry. */
+declare function registerProfile(profileInput: Profile | ProfileDefinition): void;
+/** Register several host-owned profiles in order. */
+declare function registerProfiles(profilesList: Array<Profile | ProfileDefinition>): void;
+/** Return whether a profile id is currently registered. */
+declare function hasProfile(id: string): boolean;
+/** List all currently registered profiles. */
+declare function listProfiles(): Profile[];
+/** Clear the process-local registry; intended for tests and host reloads. */
+declare function clearProfiles(): void;
+/** Fetch a registered profile or throw a `TheorumError`. */
+declare function getProfile(id: string): Profile;
+export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, };

package/esm/src/kernel/registry/profiles.js

@@ -0,0 +1,111 @@
+/**
+ * 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.js';
+const profiles = new Map();
+function buildDefaultIdentity(id, identity) {
+    return {
+        handle: identity?.handle ?? id,
+        chat: identity?.chat,
+        system: identity?.system,
+        systemByRole: identity?.systemByRole,
+    };
+}
+function buildDefaultModel(model) {
+    return {
+        protocol: model.protocol ?? 'geminiInteractions',
+        provider: model.provider ?? 'google',
+        allow: model.allow,
+        thinking: model.thinking ?? 'minimal',
+        controls: model.controls ?? [],
+        maxSteps: model.maxSteps ?? 1,
+        key: model.key ?? 'freeA',
+        select: model.select,
+        override: model.override,
+    };
+}
+function buildDefaultInputs(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) {
+    return {
+        structured: outputs?.structured ?? null,
+        media: outputs?.media ?? false,
+        voice: outputs?.voice,
+        validation: outputs?.validation,
+        streaming: outputs?.streaming,
+    };
+}
+function buildDefaultGuardrails(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) {
+    return {
+        id: input.id,
+        identity: buildDefaultIdentity(input.id, input.identity),
+        model: buildDefaultModel(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) {
+    const profile = defineProfile(profileInput);
+    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) {
+    for (const p of profilesList) {
+        registerProfile(p);
+    }
+}
+/** Return whether a profile id is currently registered. */
+function hasProfile(id) {
+    return profiles.has(id);
+}
+/** List all currently registered profiles. */
+function listProfiles() {
+    return Array.from(profiles.values());
+}
+/** Clear the process-local registry; intended for tests and host reloads. */
+function clearProfiles() {
+    profiles.clear();
+}
+/** Fetch a registered profile or throw a `TheorumError`. */
+function getProfile(id) {
+    const profile = profiles.get(id);
+    if (!profile) {
+        throw new TheorumError(`Unknown profile '${id}'`);
+    }
+    return profile;
+}
+export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, };

package/esm/src/kernel/registry/resolve.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Profile resolution for THEORUM turns.
+ *
+ * This module validates caller overrides, selects models and tools, normalizes
+ * input parts, and produces the provider request state consumed by `runTurn`.
+ *
+ * @module
+ */
+import type { Profile, ProjectedProfile, ResolvedGeneration, ToolId, TurnRequest } from '../types.js';
+declare function assertToolAllowed(profile: Profile, name: ToolId): void;
+/** Resolve a host `TurnRequest` into provider-ready generation state. */
+declare function resolveTurn(req: TurnRequest): {
+    profile: Profile;
+    generation: ResolvedGeneration;
+};
+/** UI projection: catalog ∩ profile. Swatches are not included. */
+/** Project a registered profile into a safe host/UI inspection object. */
+declare function projectProfile(id: Profile['id']): ProjectedProfile;
+declare function pickSystemRole(profile: Profile, requested?: string): string;
+export { assertToolAllowed, pickSystemRole, projectProfile, resolveTurn };