theorum 0.1.4 → 0.1.5

package/esm/_dnt.polyfills.d.ts

@@ -0,0 +1,110 @@
+declare global {
+    interface Object {
+        /**
+         * Determines whether an object has a property with the specified name.
+         * @param o An object.
+         * @param v A property name.
+         */
+        hasOwn(o: object, v: PropertyKey): boolean;
+    }
+}
+export {};
+/**
+ * Based on [import-meta-ponyfill](https://github.com/gaubee/import-meta-ponyfill),
+ * but instead of using npm to install additional dependencies,
+ * this approach manually consolidates cjs/mjs/d.ts into a single file.
+ *
+ * Note that this code might be imported multiple times
+ * (for example, both dnt.test.polyfills.ts and dnt.polyfills.ts contain this code;
+ *  or Node.js might dynamically clear the cache and then force a require).
+ * Therefore, it's important to avoid redundant writes to global objects.
+ * Additionally, consider that commonjs is used alongside esm,
+ * so the two ponyfill functions are stored independently in two separate global objects.
+ */
+import { createRequire } from "node:module";
+import { type URL } from "node:url";
+declare global {
+    interface ImportMeta {
+        /** A string representation of the fully qualified module URL. When the
+         * module is loaded locally, the value will be a file URL (e.g.
+         * `file:///path/module.ts`).
+         *
+         * You can also parse the string as a URL to determine more information about
+         * how the current module was loaded. For example to determine if a module was
+         * local or not:
+         *
+         * ```ts
+         * const url = new URL(import.meta.url);
+         * if (url.protocol === "file:") {
+         *   console.log("this module was loaded locally");
+         * }
+         * ```
+         */
+        url: string;
+        /**
+         * A function that returns resolved specifier as if it would be imported
+         * using `import(specifier)`.
+         *
+         * ```ts
+         * console.log(import.meta.resolve("./foo.js"));
+         * // file:///dev/foo.js
+         * ```
+         *
+         * @param specifier The module specifier to resolve relative to `parent`.
+         * @param parent The absolute parent module URL to resolve from.
+         * @returns The absolute (`file:`) URL string for the resolved module.
+         */
+        resolve(specifier: string, parent?: string | URL | undefined): string;
+        /** A flag that indicates if the current module is the main module that was
+         * called when starting the program under Deno.
+         *
+         * ```ts
+         * if (import.meta.main) {
+         *   // this was loaded as the main module, maybe do some bootstrapping
+         * }
+         * ```
+         */
+        main: boolean;
+        /** The absolute path of the current module.
+         *
+         * This property is only provided for local modules (ie. using `file://` URLs).
+         *
+         * Example:
+         * ```
+         * // Unix
+         * console.log(import.meta.filename); // /home/alice/my_module.ts
+         *
+         * // Windows
+         * console.log(import.meta.filename); // C:\alice\my_module.ts
+         * ```
+         */
+        filename: string;
+        /** The absolute path of the directory containing the current module.
+         *
+         * This property is only provided for local modules (ie. using `file://` URLs).
+         *
+         * * Example:
+         * ```
+         * // Unix
+         * console.log(import.meta.dirname); // /home/alice
+         *
+         * // Windows
+         * console.log(import.meta.dirname); // C:\alice
+         * ```
+         */
+        dirname: string;
+    }
+}
+type NodeRequest = ReturnType<typeof createRequire>;
+type NodeModule = NonNullable<NodeRequest["main"]>;
+interface ImportMetaPonyfillCommonjs {
+    (require: NodeRequest, module: NodeModule): ImportMeta;
+}
+interface ImportMetaPonyfillEsmodule {
+    (importMeta: ImportMeta): ImportMeta;
+}
+interface ImportMetaPonyfill extends ImportMetaPonyfillCommonjs, ImportMetaPonyfillEsmodule {
+}
+export declare let import_meta_ponyfill_commonjs: ImportMetaPonyfillCommonjs;
+export declare let import_meta_ponyfill_esmodule: ImportMetaPonyfillEsmodule;
+export declare let import_meta_ponyfill: ImportMetaPonyfill;

package/esm/_dnt.polyfills.js

@@ -0,0 +1,144 @@
+// https://github.com/tc39/proposal-accessible-object-hasownproperty/blob/main/polyfill.js
+if (!Object.hasOwn) {
+    Object.defineProperty(Object, "hasOwn", {
+        value: function (object, property) {
+            if (object == null) {
+                throw new TypeError("Cannot convert undefined or null to object");
+            }
+            return Object.prototype.hasOwnProperty.call(Object(object), property);
+        },
+        configurable: true,
+        enumerable: false,
+        writable: true,
+    });
+}
+/**
+ * Based on [import-meta-ponyfill](https://github.com/gaubee/import-meta-ponyfill),
+ * but instead of using npm to install additional dependencies,
+ * this approach manually consolidates cjs/mjs/d.ts into a single file.
+ *
+ * Note that this code might be imported multiple times
+ * (for example, both dnt.test.polyfills.ts and dnt.polyfills.ts contain this code;
+ *  or Node.js might dynamically clear the cache and then force a require).
+ * Therefore, it's important to avoid redundant writes to global objects.
+ * Additionally, consider that commonjs is used alongside esm,
+ * so the two ponyfill functions are stored independently in two separate global objects.
+ */
+//@ts-ignore
+import { createRequire } from "node:module";
+//@ts-ignore
+import { fileURLToPath, pathToFileURL } from "node:url";
+//@ts-ignore
+import { dirname } from "node:path";
+const defineGlobalPonyfill = (symbolFor, fn) => {
+    if (!Reflect.has(globalThis, Symbol.for(symbolFor))) {
+        Object.defineProperty(globalThis, Symbol.for(symbolFor), {
+            configurable: true,
+            get() {
+                return fn;
+            },
+        });
+    }
+};
+export let import_meta_ponyfill_commonjs = (Reflect.get(globalThis, Symbol.for("import-meta-ponyfill-commonjs")) ??
+    (() => {
+        const moduleImportMetaWM = new WeakMap();
+        return (require, module) => {
+            let importMetaCache = moduleImportMetaWM.get(module);
+            if (importMetaCache == null) {
+                const importMeta = Object.assign(Object.create(null), {
+                    url: pathToFileURL(module.filename).href,
+                    main: require.main == module,
+                    resolve: (specifier, parentURL = importMeta.url) => {
+                        return pathToFileURL((importMeta.url === parentURL
+                            ? require
+                            : createRequire(parentURL))
+                            .resolve(specifier)).href;
+                    },
+                    filename: module.filename,
+                    dirname: module.path,
+                });
+                moduleImportMetaWM.set(module, importMeta);
+                importMetaCache = importMeta;
+            }
+            return importMetaCache;
+        };
+    })());
+defineGlobalPonyfill("import-meta-ponyfill-commonjs", import_meta_ponyfill_commonjs);
+export let import_meta_ponyfill_esmodule = (Reflect.get(globalThis, Symbol.for("import-meta-ponyfill-esmodule")) ??
+    ((importMeta) => {
+        const resolveFunStr = String(importMeta.resolve);
+        const shimWs = new WeakSet();
+        //@ts-ignore
+        const mainUrl = ("file:///" + process.argv[1].replace(/\\/g, "/"))
+            .replace(/\/{3,}/, "///");
+        const commonShim = (importMeta) => {
+            if (typeof importMeta.main !== "boolean") {
+                importMeta.main = importMeta.url === mainUrl;
+            }
+            if (typeof importMeta.filename !== "string") {
+                importMeta.filename = fileURLToPath(importMeta.url);
+                importMeta.dirname = dirname(importMeta.filename);
+            }
+        };
+        if (
+        // v16.2.0+, v14.18.0+: Add support for WHATWG URL object to parentURL parameter.
+        resolveFunStr === "undefined" ||
+            // v20.0.0+, v18.19.0+"" This API now returns a string synchronously instead of a Promise.
+            resolveFunStr.startsWith("async")
+        // enable by --experimental-import-meta-resolve flag
+        ) {
+            import_meta_ponyfill_esmodule = (importMeta) => {
+                if (!shimWs.has(importMeta)) {
+                    shimWs.add(importMeta);
+                    const importMetaUrlRequire = {
+                        url: importMeta.url,
+                        require: createRequire(importMeta.url),
+                    };
+                    // note: the parameter types must be explicitly annotated because
+                    // `@types/node` also declares `ImportMeta.resolve`, which makes
+                    // the contextual type an overload set that provides no inference
+                    importMeta.resolve = function resolve(specifier, parentURL = importMeta.url) {
+                        return pathToFileURL((importMetaUrlRequire.url === parentURL
+                            ? importMetaUrlRequire.require
+                            : createRequire(parentURL)).resolve(specifier)).href;
+                    };
+                    commonShim(importMeta);
+                }
+                return importMeta;
+            };
+        }
+        else {
+            /// native support
+            import_meta_ponyfill_esmodule = (importMeta) => {
+                if (!shimWs.has(importMeta)) {
+                    shimWs.add(importMeta);
+                    commonShim(importMeta);
+                }
+                return importMeta;
+            };
+        }
+        return import_meta_ponyfill_esmodule(importMeta);
+    }));
+defineGlobalPonyfill("import-meta-ponyfill-esmodule", import_meta_ponyfill_esmodule);
+export let import_meta_ponyfill = ((...args) => {
+    const _MODULE = (() => {
+        if (typeof require === "function" && typeof module === "object") {
+            return "commonjs";
+        }
+        else {
+            // eval("typeof import.meta");
+            return "esmodule";
+        }
+    })();
+    if (_MODULE === "commonjs") {
+        //@ts-ignore
+        import_meta_ponyfill = (r, m) => import_meta_ponyfill_commonjs(r, m);
+    }
+    else {
+        //@ts-ignore
+        import_meta_ponyfill = (im) => import_meta_ponyfill_esmodule(im);
+    }
+    //@ts-ignore
+    return import_meta_ponyfill(...args);
+});

package/esm/_dnt.shims.d.ts

@@ -0,0 +1,5 @@
+import { Deno } from "@deno/shim-deno";
+export { Deno } from "@deno/shim-deno";
+export declare const dntGlobalThis: Omit<typeof globalThis, "Deno"> & {
+    Deno: typeof Deno;
+};

package/esm/_dnt.shims.js

@@ -0,0 +1,61 @@
+import { Deno } from "@deno/shim-deno";
+export { Deno } from "@deno/shim-deno";
+const dntGlobals = {
+    Deno,
+};
+export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
+function createMergeProxy(baseObj, extObj) {
+    return new Proxy(baseObj, {
+        get(_target, prop, _receiver) {
+            if (prop in extObj) {
+                return extObj[prop];
+            }
+            else {
+                return baseObj[prop];
+            }
+        },
+        set(_target, prop, value) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            baseObj[prop] = value;
+            return true;
+        },
+        deleteProperty(_target, prop) {
+            let success = false;
+            if (prop in extObj) {
+                delete extObj[prop];
+                success = true;
+            }
+            if (prop in baseObj) {
+                delete baseObj[prop];
+                success = true;
+            }
+            return success;
+        },
+        ownKeys(_target) {
+            const baseKeys = Reflect.ownKeys(baseObj);
+            const extKeys = Reflect.ownKeys(extObj);
+            const extKeysSet = new Set(extKeys);
+            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
+        },
+        defineProperty(_target, prop, desc) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            Reflect.defineProperty(baseObj, prop, desc);
+            return true;
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (prop in extObj) {
+                return Reflect.getOwnPropertyDescriptor(extObj, prop);
+            }
+            else {
+                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
+            }
+        },
+        has(_target, prop) {
+            return prop in extObj || prop in baseObj;
+        },
+    });
+}

package/{mod.ts → esm/mod.d.ts}

@@ -36,60 +36,20 @@
  *
  * @module
  */
-
-export { publicError, TheorumError } from './src/guardrails/error.ts';
-export type { QuotaSlotStatus } from './src/guardrails/quota.ts';
-export {
-  clientIp,
-  quotaMessage,
-  releaseSlot,
-  resetSlots,
-  skipQuota,
-  takeSlot,
-} from './src/guardrails/quota.ts';
-export {
-  PROJECT_ID_MAX,
-  sanitizeProjectId,
-  sanitizeText,
-  sanitizeTurnRequest,
-} from './src/guardrails/sanitize.ts';
-export { runTurn } from './src/kernel/engine/runner.ts';
-export {
-  CATALOG,
-  clampThinkingLevel,
-  clampThinkingLevelForApiId,
-  geminiKindForMime,
-  getTool,
-  listBuiltinIds,
-  mimeAllowed,
-  mimeEssence,
-  modelEntryByApiId,
-  registerTools,
-  requireModelSpec,
-  resetTools,
-} from './src/kernel/registry/catalog.ts';
-export type { ProfileDefinition } from './src/kernel/registry/profiles.ts';
-export {
-  clearProfiles,
-  defineProfile,
-  getProfile,
-  hasProfile,
-  listProfiles,
-  registerProfile,
-  registerProfiles,
-} from './src/kernel/registry/profiles.ts';
-export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.ts';
-export { getStructured, registerStructured } from './src/kernel/registry/schemas.ts';
-export { executeTool } from './src/kernel/registry/tools.ts';
-export type * from './src/kernel/types.ts';
-export {
-  jsonlSink,
-  memorySink,
-  noopSink,
-  resolveTraceDir,
-  sinkFromDir,
-  writeTrace,
-} from './src/observability/trace.ts';
-export type { TraceRecord } from './src/observability/trace-record.ts';
-export type { CreateProviderOptions, GeminiTransport, GeminiVault } from './src/providers/mod.ts';
-export { createProvider } from './src/providers/mod.ts';
+import "./_dnt.polyfills.js";
+export { publicError, describeError, TheorumError, toErrorEvent } from './src/guardrails/error.js';
+export type { QuotaSlotStatus } from './src/guardrails/quota.js';
+export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
+export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';
+export { runTurn } from './src/kernel/engine/runner.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
+export type { ProfileDefinition } from './src/kernel/registry/profiles.js';
+export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
+export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';
+export { getStructured, registerStructured } from './src/kernel/registry/schemas.js';
+export { executeTool } from './src/kernel/registry/tools.js';
+export type * from './src/kernel/types.js';
+export { jsonlSink, memorySink, noopSink, resolveTraceDir, sinkFromDir, writeTrace, } from './src/observability/trace.js';
+export type { TraceRecord } from './src/observability/trace-record.js';
+export type { CreateProviderOptions, GeminiTransport, GeminiVault } from './src/providers/mod.js';
+export { createProvider } from './src/providers/mod.js';

package/esm/mod.js

@@ -0,0 +1,50 @@
+/**
+ * THEORUM public API.
+ *
+ * Import this entrypoint when an application wants the complete kernel surface:
+ * profile registration, turn execution, provider constructors, guardrails,
+ * observability sinks, and public type contracts.
+ *
+ * @example
+ * ```ts
+ * import { defineProfile, registerProfile, runTurn } from "jsr:@theorum/core";
+ *
+ * const profile = defineProfile({
+ *   id: "assistant.basic",
+ *   model: {
+ *     allow: ["gemini35FlashLite"],
+ *     config: {
+ *       gemini35FlashLite: {
+ *         apiId: "gemini-3.5-flash-lite",
+ *         thinking: { on: "high", off: "minimal" },
+ *         thinkingLevels: ["minimal", "low", "medium", "high"],
+ *         summaries: { on: "auto", off: "none" },
+ *         maxOutputTokens: 8192,
+ *         temperature: 1,
+ *         keyBuiltins: [],
+ *       },
+ *     },
+ *   },
+ *   tools: { allow: [] },
+ *   inputs: { text: true },
+ *   outputs: {},
+ *   guardrails: { quota: { perDay: 100 } },
+ * });
+ *
+ * registerProfile(profile);
+ * ```
+ *
+ * @module
+ */
+import "./_dnt.polyfills.js";
+export { publicError, describeError, TheorumError, toErrorEvent } from './src/guardrails/error.js';
+export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
+export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';
+export { runTurn } from './src/kernel/engine/runner.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
+export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
+export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';
+export { getStructured, registerStructured } from './src/kernel/registry/schemas.js';
+export { executeTool } from './src/kernel/registry/tools.js';
+export { jsonlSink, memorySink, noopSink, resolveTraceDir, sinkFromDir, writeTrace, } from './src/observability/trace.js';
+export { createProvider } from './src/providers/mod.js';

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/src/cli/commands/profile.d.ts

@@ -0,0 +1,2 @@
+export declare function listProfilesCommand(): void;
+export declare function showProfileCommand(profileId: string): void;

package/esm/src/cli/commands/profile.js

@@ -0,0 +1,53 @@
+import { getProfile, listProfiles } from '../../kernel/registry/profiles.js';
+function formatProfileInputs(p) {
+    const inputs = [];
+    if (p.inputs.text !== false)
+        inputs.push('text');
+    if (p.inputs.voice)
+        inputs.push('voice');
+    if (p.inputs.attachments)
+        inputs.push(`attachments [${p.inputs.attachments.accept?.join(', ')}]`);
+    return inputs.join(' | ');
+}
+function printProfileCard(p) {
+    const tools = p.tools.allow?.length ? p.tools.allow.join(', ') : 'none';
+    const models = p.model.allow?.join(', ') || 'default';
+    const structured = typeof p.outputs.structured === 'string'
+        ? p.outputs.structured
+        : p.outputs.structured
+            ? 'custom'
+            : 'none';
+    console.log(` • Profile: ${p.id.padEnd(16)} (handle: ${p.identity.handle})`);
+    console.log(`   - Models:     ${models}`);
+    console.log(`   - Inputs:     ${formatProfileInputs(p)}`);
+    console.log(`   - Tools:      ${tools}`);
+    console.log(`   - Structured: ${structured}`);
+    console.log(`   - Key Bucket: ${p.model.key ?? 'freeA'}`);
+    console.log('-'.repeat(70));
+}
+export function listProfilesCommand() {
+    const profiles = listProfiles();
+    console.log('\n Registered Theorum Profiles:');
+    console.log('='.repeat(70));
+    if (profiles.length === 0) {
+        console.log('  (No profiles registered in runtime)');
+        console.log(`${'='.repeat(70)}\n`);
+        return;
+    }
+    for (const p of profiles) {
+        printProfileCard(p);
+    }
+    console.log(`Total: ${profiles.length} profiles registered.\n`);
+}
+export function showProfileCommand(profileId) {
+    try {
+        const profile = getProfile(profileId);
+        console.log(`\n Profile Details: ${profileId}`);
+        console.log('='.repeat(70));
+        console.log(JSON.stringify(profile, null, 2));
+        console.log(`${'='.repeat(70)}\n`);
+    }
+    catch (err) {
+        console.error(`\n Error: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}

package/esm/src/cli/commands/run.d.ts

@@ -0,0 +1,10 @@
+import type { ModelProvider } from '../../kernel/types.js';
+export interface RunOptions {
+    profile: string;
+    prompt?: string;
+    mode?: string;
+    search?: boolean;
+    map?: boolean;
+    provider?: ModelProvider;
+}
+export declare function runCommand(options: RunOptions): Promise<void>;

package/esm/src/cli/commands/run.js

@@ -0,0 +1,55 @@
+import * as dntShim from "../../../_dnt.shims.js";
+import { runTurn } from '../../kernel/engine/runner.js';
+import { getProfile } from '../../kernel/registry/profiles.js';
+function handleRunEvent(event) {
+    if (event.type === 'thought' && event.text) {
+        dntShim.Deno.stdout.write(new TextEncoder().encode(`\x1b[2m${event.text}\x1b[0m`));
+    }
+    else if (event.type === 'text' && event.text) {
+        dntShim.Deno.stdout.write(new TextEncoder().encode(event.text));
+    }
+    else if (event.type === 'tool' && event.tool) {
+        console.log(`\n\x1b[33m⚡ [Tool Call] ${event.tool.name}\x1b[0m:`, event.tool.arguments);
+    }
+    else if (event.type === 'structured' && event.structured) {
+        console.log('\n\x1b[32m✓ [Structured Output]\x1b[0m:');
+        console.log(JSON.stringify(event.structured, null, 2));
+    }
+    else if (event.type === 'media' && event.media) {
+        console.log(`\n\x1b[34m🖼 [Media Output]\x1b[0m (${event.media.mimeType})`);
+    }
+    else if (event.type === 'error' && event.error) {
+        console.error(`\n\x1b[31m✗ Error\x1b[0m: ${event.error}`);
+    }
+}
+export async function runCommand(options) {
+    getProfile(options.profile);
+    const provider = options.provider;
+    if (!provider) {
+        console.error('\n\x1b[31mExecution Failed\x1b[0m: Theorum CLI does not create providers or read keys. Run turns from a host app with an explicit ModelProvider.\n');
+        return;
+    }
+    const prompt = options.prompt || 'Hello! Please introduce your capabilities.';
+    const tools = {};
+    if (options.search)
+        tools.googleSearch = true;
+    if (options.map)
+        tools.googleMaps = true;
+    const req = {
+        profile: options.profile,
+        select: options.mode,
+        tools: Object.keys(tools).length > 0 ? tools : undefined,
+        input: { text: prompt },
+    };
+    console.log(`\n▶ [RUNNING TURN] Profile: ${options.profile} (${options.mode ?? 'default'})`);
+    console.log(`Prompt: "${prompt}"\n`);
+    try {
+        for await (const event of runTurn(req, provider)) {
+            handleRunEvent(event);
+        }
+        console.log('\n');
+    }
+    catch (err) {
+        console.error(`\n\x1b[31mExecution Failed\x1b[0m: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}

package/esm/src/cli/commands/test.d.ts

@@ -0,0 +1,15 @@
+import type { ModelProvider, TurnRequest } from '../../kernel/types.js';
+import { type MatrixOptions } from '../matrix/synthesizer.js';
+export interface TestRunResult {
+    passed: boolean;
+    name: string;
+    durationSec: number;
+    tokensTotal?: number;
+    error?: string;
+}
+export declare function executeSingleTest(req: TurnRequest, testName: string, provider?: ModelProvider): Promise<TestRunResult>;
+export declare function testProfileCommand(profileId?: string, options?: MatrixOptions & {
+    all?: boolean;
+    matrix?: boolean;
+    provider?: ModelProvider;
+}): Promise<boolean>;