@justram/pie 0.1.0

package/dist/core/events.js

@@ -0,0 +1 @@
+export {};

package/dist/core/extract.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from "@mariozechner/pi-ai";
+import type { ExtractOptions, ExtractStream } from "./types.js";
+export declare function extract<T>(input: string | Message[], options: ExtractOptions<T>): ExtractStream<T>;
+export declare function extractSync<T>(input: string | Message[], options: ExtractOptions<T>): Promise<T>;

package/dist/core/extract.js

@@ -0,0 +1,384 @@
+import { EventStream, isContextOverflow, validateToolArguments } from "@mariozechner/pi-ai";
+import { buildMessages, findToolCall, getTextContent, parseJsonFromText } from "../utils/helpers.js";
+import { computeCacheKey } from "./cache/key.js";
+import { createMemoryCache } from "./cache/memory.js";
+import { AbortError, ExtractError, MaxTurnsError } from "./errors.js";
+import { normalizeToolSchema } from "./schema/normalize.js";
+import { createValidationEmitter, runValidators } from "./validators/index.js";
+const RESPOND_TOOL_NAME = "respond";
+const RESPOND_TOOL_DESCRIPTION = "Return structured data that matches the schema.";
+const DEFAULT_MAX_TOKENS = 32000;
+const DEFAULT_CACHE = createMemoryCache();
+export function extract(input, options) {
+    const maxTurns = options.maxTurns ?? 3;
+    const stream = new EventStream((event) => event.type === "complete" || event.type === "error", (event) => event.type === "complete" ? { data: event.result, turns: event.turns, usage: event.usage } : undefined);
+    const abortController = createAbortController(options.signal);
+    void runExtraction(input, options, maxTurns, stream, abortController.signal).catch(() => {
+        // Error event already emitted in runExtraction.
+    });
+    return Object.assign(stream, {
+        abort: () => abortController.abort(new AbortError()),
+    });
+}
+export async function extractSync(input, options) {
+    const maxTurns = options.maxTurns ?? 3;
+    const result = await runExtraction(input, options, maxTurns, null, options.signal);
+    return result.data;
+}
+async function runExtraction(input, options, maxTurns, eventStream, signal) {
+    eventStream?.push({ type: "start", maxTurns });
+    const model = options.model;
+    if (!model) {
+        const error = new ExtractError('Missing required option "model".');
+        eventStream?.push({ type: "error", error, turns: 0 });
+        throw error;
+    }
+    if (signal?.aborted) {
+        const error = toAbortError(signal.reason);
+        eventStream?.push({ type: "error", error, turns: 0 });
+        throw error;
+    }
+    // Warn if thinking is requested but model doesn't support it
+    const thinkingRequested = options.thinking && options.thinking !== "off";
+    if (thinkingRequested && !model.reasoning) {
+        eventStream?.push({
+            type: "warning",
+            code: "thinking_unsupported",
+            message: `Model "${model.provider}:${model.id}" does not support extended thinking. The 'thinking' option will be ignored.`,
+        });
+    }
+    const { cacheKey, cacheStore, cacheTtl, cacheRevalidate } = resolveCache(input, options);
+    if (cacheKey && cacheStore) {
+        const entry = await cacheStore.get(cacheKey);
+        if (entry) {
+            const age = Date.now() - entry.timestamp;
+            const expired = cacheTtl !== undefined && age > cacheTtl;
+            if (!expired) {
+                if (cacheRevalidate) {
+                    const emitter = createValidationEmitter((e) => eventStream?.push(e));
+                    try {
+                        await runValidators(entry.data, options, emitter, signal);
+                        eventStream?.push({ type: "cache_hit", key: cacheKey, age });
+                        eventStream?.push({ type: "complete", result: entry.data, turns: entry.turns, usage: entry.usage });
+                        return { data: entry.data, turns: entry.turns, usage: entry.usage };
+                    }
+                    catch {
+                        await cacheStore.delete(cacheKey);
+                    }
+                }
+                else {
+                    eventStream?.push({ type: "cache_hit", key: cacheKey, age });
+                    eventStream?.push({ type: "complete", result: entry.data, turns: entry.turns, usage: entry.usage });
+                    return { data: entry.data, turns: entry.turns, usage: entry.usage };
+                }
+            }
+        }
+        eventStream?.push({ type: "cache_miss", key: cacheKey });
+    }
+    const messages = buildMessages(input, options.attachments);
+    const { schema: toolSchema, unwrapKey } = normalizeToolSchema(model, options.schema);
+    const tool = {
+        name: RESPOND_TOOL_NAME,
+        description: RESPOND_TOOL_DESCRIPTION,
+        parameters: toolSchema,
+    };
+    const validationTool = {
+        name: RESPOND_TOOL_NAME,
+        description: RESPOND_TOOL_DESCRIPTION,
+        parameters: toolSchema,
+    };
+    const streamFn = options.streamFn;
+    if (!streamFn) {
+        const error = new ExtractError('Missing required option "streamFn".');
+        eventStream?.push({ type: "error", error, turns: 0 });
+        throw error;
+    }
+    const maxTokens = Math.min(model.maxTokens, DEFAULT_MAX_TOKENS);
+    const totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, cost: 0 };
+    let lastError;
+    for (let turn = 1; turn <= maxTurns; turn++) {
+        if (signal?.aborted) {
+            const error = toAbortError(signal.reason);
+            eventStream?.push({ type: "error", error, turns: turn - 1 });
+            throw error;
+        }
+        eventStream?.push({ type: "turn_start", turn });
+        const context = {
+            systemPrompt: [
+                options.prompt,
+                "When you are ready, call the 'respond' tool with your structured answer.",
+                "Do not include extra commentary in the tool call arguments.",
+            ].join("\n\n"),
+            messages,
+            tools: [tool],
+        };
+        eventStream?.push({ type: "llm_start" });
+        let assistant;
+        try {
+            // Convert "off" or undefined to undefined (disabled), otherwise pass through
+            const reasoning = options.thinking && options.thinking !== "off" ? options.thinking : undefined;
+            assistant = await callLlm(streamFn, model, context, {
+                apiKey: options.apiKey,
+                signal,
+                maxTokens,
+                reasoning,
+                thinkingBudgets: options.thinkingBudgets,
+                onModelSelected: (selected) => eventStream?.push({ type: "llm_selected", model: selected }),
+            }, eventStream);
+        }
+        catch (error) {
+            const err = toError(error);
+            eventStream?.push({ type: "error", error: err, turns: turn });
+            throw err;
+        }
+        const turnUsage = mapUsage(assistant.usage);
+        accumulateUsage(totalUsage, turnUsage);
+        eventStream?.push({ type: "llm_end", message: assistant, usage: turnUsage });
+        const toolCall = findToolCall(assistant, RESPOND_TOOL_NAME);
+        if (toolCall) {
+            eventStream?.push({ type: "tool_call", toolCall });
+            eventStream?.push({ type: "json_extracted", source: "tool_call" });
+        }
+        let args = toolCall?.arguments;
+        let jsonSource = toolCall ? "tool_call" : null;
+        if (!toolCall) {
+            args = parseJsonFromText(assistant);
+            if (args !== null) {
+                jsonSource = "text";
+                eventStream?.push({ type: "json_extracted", source: "text" });
+            }
+        }
+        if (args === null) {
+            eventStream?.push({ type: "thinking", text: getTextContent(assistant) });
+            messages.push(assistant);
+            messages.push(createContinueMessage());
+            eventStream?.push({ type: "turn_end", turn, hasResult: false });
+            continue;
+        }
+        const emitter = createValidationEmitter((e) => eventStream?.push(e));
+        let data;
+        try {
+            emitter.start("schema");
+            const normalizedArgs = normalizeToolArguments(args, unwrapKey);
+            const validationToolCall = {
+                type: "toolCall",
+                id: toolCall?.id ?? "respond_fallback",
+                name: RESPOND_TOOL_NAME,
+                arguments: normalizedArgs,
+            };
+            const validated = validateToolArguments(validationTool, validationToolCall);
+            data = unwrapToolArguments(validated, unwrapKey);
+            emitter.pass("schema");
+        }
+        catch (error) {
+            const err = toError(error);
+            lastError = err;
+            emitter.fail("schema", err.message);
+            messages.push(assistant);
+            if (jsonSource === "tool_call") {
+                messages.push(createSchemaToolResult(toolCall?.id ?? "respond_fallback", err));
+            }
+            else {
+                messages.push(createSchemaFeedbackMessage(err));
+            }
+            eventStream?.push({ type: "turn_end", turn, hasResult: false });
+            continue;
+        }
+        try {
+            await runValidators(data, options, emitter, signal);
+            eventStream?.push({ type: "turn_end", turn, hasResult: true });
+            const result = {
+                data,
+                turns: turn,
+                usage: { ...totalUsage },
+            };
+            if (cacheKey && cacheStore) {
+                try {
+                    await cacheStore.set(cacheKey, { data, timestamp: Date.now(), turns: turn, usage: { ...totalUsage } });
+                    eventStream?.push({ type: "cache_set", key: cacheKey });
+                }
+                catch {
+                    // Cache write failure shouldn't fail extraction.
+                }
+            }
+            eventStream?.push({ type: "complete", result: data, turns: turn, usage: { ...totalUsage } });
+            return result;
+        }
+        catch (error) {
+            const err = toError(error);
+            lastError = err;
+            messages.push(assistant);
+            if (jsonSource === "tool_call") {
+                messages.push(createSchemaToolResult(toolCall?.id ?? "respond_fallback", err));
+            }
+            else {
+                messages.push(createSchemaFeedbackMessage(err));
+            }
+            eventStream?.push({ type: "turn_end", turn, hasResult: false });
+        }
+    }
+    const err = new MaxTurnsError(`Extraction failed after ${maxTurns} turns`, maxTurns, lastError);
+    eventStream?.push({ type: "error", error: err, turns: maxTurns });
+    throw err;
+}
+function resolveCache(input, options) {
+    const raw = options.cache;
+    if (!raw) {
+        return { cacheKey: null, cacheStore: null, cacheRevalidate: false };
+    }
+    const cacheOptions = typeof raw === "boolean" ? {} : raw;
+    const store = cacheOptions.store ?? DEFAULT_CACHE;
+    const revalidate = cacheOptions.revalidate ?? false;
+    // If caller provides function validators, we only allow caching when revalidate is enabled.
+    if ((options.validate || options.validateAsync) && !revalidate) {
+        return { cacheKey: null, cacheStore: null, cacheRevalidate: false };
+    }
+    const inputText = typeof input === "string" ? input : JSON.stringify(input);
+    const key = cacheOptions.key
+        ? cacheOptions.key(inputText, options)
+        : computeCacheKey(inputText, options);
+    return { cacheKey: key, cacheStore: store, cacheTtl: cacheOptions.ttl, cacheRevalidate: revalidate };
+}
+async function callLlm(streamFn, model, context, options, eventStream) {
+    if (!streamFn) {
+        throw new Error("streamFn is required");
+    }
+    const s = streamFn(model, context, options);
+    let message = null;
+    for await (const event of s) {
+        if (event.type === "text_delta") {
+            eventStream?.push({ type: "llm_delta", delta: event.delta });
+        }
+        if (event.type === "thinking_delta") {
+            eventStream?.push({ type: "thinking", text: event.delta });
+        }
+        if (event.type === "done") {
+            message = event.message;
+        }
+        if (event.type === "error") {
+            throw createLlmError(event.error, model);
+        }
+    }
+    return message ?? (await s.result());
+}
+function mapUsage(usage) {
+    return {
+        inputTokens: usage.input,
+        outputTokens: usage.output,
+        totalTokens: usage.totalTokens,
+        cost: usage.cost.total,
+    };
+}
+function createLlmError(error, model) {
+    const provider = error.provider ?? model.provider;
+    const modelId = error.model ?? model.id;
+    const api = error.api ?? model.api;
+    const stopReason = error.stopReason ?? "error";
+    const details = error.errorMessage?.trim();
+    const contentDetails = getTextContent(error);
+    const genericErrorPatterns = [/unknown error occurred/i, /unkown error ocurred/i, /^llm error$/i];
+    const isGeneric = details ? genericErrorPatterns.some((pattern) => pattern.test(details)) : false;
+    const hint = isGeneric
+        ? " Provider returned a generic error; this often means the model is not enabled for your account, the API key lacks access, or quota was exceeded. If this model works in another client, verify you are using the same provider and credentials."
+        : "";
+    const isOverflow = isContextOverflow(error, model.contextWindow);
+    const overflowHint = isOverflow
+        ? ` Input exceeds the model context window (${model.contextWindow} tokens). Reduce input length or attachments.`
+        : "";
+    const metadata = [
+        `provider=${provider}`,
+        `model=${modelId}`,
+        `api=${api}`,
+        `stopReason=${stopReason}`,
+        model.baseUrl ? `baseUrl=${model.baseUrl}` : null,
+    ]
+        .filter((value) => Boolean(value))
+        .join(", ");
+    const message = details
+        ? `LLM request failed (${metadata}). Provider message: ${details}.${hint}${overflowHint}`
+        : `LLM request failed (${metadata}).${hint}${overflowHint}`;
+    const contentSuffix = contentDetails && contentDetails !== details ? ` Provider content: ${contentDetails}` : "";
+    return new ExtractError(`${message}${contentSuffix}`);
+}
+function accumulateUsage(target, extra) {
+    target.inputTokens += extra.inputTokens;
+    target.outputTokens += extra.outputTokens;
+    target.totalTokens += extra.totalTokens;
+    target.cost += extra.cost;
+}
+function normalizeToolArguments(args, unwrapKey) {
+    if (!unwrapKey) {
+        return args;
+    }
+    if (args && typeof args === "object" && !Array.isArray(args) && unwrapKey in args) {
+        return args;
+    }
+    return { [unwrapKey]: args };
+}
+function unwrapToolArguments(data, unwrapKey) {
+    if (!unwrapKey) {
+        return data;
+    }
+    if (!data || typeof data !== "object" || !(unwrapKey in data)) {
+        throw new Error(`Validation failed for tool "${RESPOND_TOOL_NAME}": missing "${unwrapKey}" field.`);
+    }
+    return data[unwrapKey];
+}
+function toError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error(typeof error === "string" ? error : "Unknown error");
+}
+function toAbortError(reason) {
+    if (reason instanceof AbortError) {
+        return reason;
+    }
+    if (reason instanceof Error) {
+        return new AbortError(reason.message);
+    }
+    return new AbortError(typeof reason === "string" ? reason : "Extraction aborted");
+}
+function createContinueMessage() {
+    return {
+        role: "user",
+        content: "Continue. Call the 'respond' tool when ready with your structured response.",
+        timestamp: Date.now(),
+    };
+}
+function createSchemaToolResult(toolCallId, error) {
+    return {
+        role: "toolResult",
+        toolCallId,
+        toolName: RESPOND_TOOL_NAME,
+        content: [{ type: "text", text: `Validation error: ${error.message}` }],
+        isError: true,
+        timestamp: Date.now(),
+    };
+}
+function createSchemaFeedbackMessage(error) {
+    return {
+        role: "user",
+        content: [
+            "Validation error in your previous JSON output:",
+            error.message,
+            "",
+            "Continue. Call the 'respond' tool when ready with your corrected structured response.",
+        ].join("\n"),
+        timestamp: Date.now(),
+    };
+}
+function createAbortController(signal) {
+    const controller = new AbortController();
+    if (!signal) {
+        return controller;
+    }
+    if (signal.aborted) {
+        controller.abort(signal.reason);
+        return controller;
+    }
+    signal.addEventListener("abort", () => {
+        controller.abort(signal.reason);
+    }, { once: true });
+    return controller;
+}

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,5 @@
+export interface FrontmatterParseResult {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export declare function parseFrontmatter(content: string): FrontmatterParseResult;

package/dist/core/frontmatter.js

@@ -0,0 +1,58 @@
+export function parseFrontmatter(content) {
+    const frontmatter = {};
+    const normalized = content.replace(/\r\n/g, "\n");
+    if (!normalized.startsWith("---")) {
+        return { frontmatter, body: normalized };
+    }
+    const endIndex = normalized.indexOf("\n---", 3);
+    if (endIndex === -1) {
+        return { frontmatter, body: normalized };
+    }
+    const frontmatterBlock = normalized.slice(4, endIndex);
+    const body = normalized.slice(endIndex + 4).trim();
+    const lines = frontmatterBlock.split("\n");
+    let currentKey = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        const listMatch = trimmed.match(/^-\s+(.*)$/);
+        if (listMatch && currentKey) {
+            const existing = frontmatter[currentKey];
+            if (!Array.isArray(existing)) {
+                frontmatter[currentKey] = [];
+            }
+            frontmatter[currentKey].push(parseScalar(listMatch[1]));
+            continue;
+        }
+        const keyMatch = trimmed.match(/^([\w-]+):\s*(.*)$/);
+        if (keyMatch) {
+            currentKey = keyMatch[1];
+            const rawValue = keyMatch[2];
+            if (rawValue.length === 0) {
+                frontmatter[currentKey] = null;
+            }
+            else {
+                frontmatter[currentKey] = parseScalar(rawValue);
+            }
+            continue;
+        }
+        currentKey = null;
+    }
+    return { frontmatter, body };
+}
+function parseScalar(value) {
+    let parsed = value.trim();
+    if ((parsed.startsWith('"') && parsed.endsWith('"')) || (parsed.startsWith("'") && parsed.endsWith("'"))) {
+        parsed = parsed.slice(1, -1);
+    }
+    const lower = parsed.toLowerCase();
+    if (lower === "true")
+        return true;
+    if (lower === "false")
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(parsed))
+        return Number(parsed);
+    return parsed;
+}

package/dist/core/helpers.d.ts

@@ -0,0 +1,5 @@
+import type { AssistantMessage, ImageContent, Message, ToolCall } from "@mariozechner/pi-ai";
+export declare function buildMessages(input: string | Message[], attachments?: ImageContent[]): Message[];
+export declare function findToolCall(message: AssistantMessage, toolName: string): ToolCall | undefined;
+export declare function getTextContent(message: AssistantMessage): string;
+export declare function parseJsonFromText(message: AssistantMessage): unknown | null;

package/dist/core/helpers.js

@@ -0,0 +1,80 @@
+export function buildMessages(input, attachments) {
+    if (typeof input !== "string") {
+        return input;
+    }
+    const content = attachments?.length
+        ? [{ type: "text", text: input }, ...attachments]
+        : input;
+    const message = {
+        role: "user",
+        content,
+        timestamp: Date.now(),
+    };
+    return [message];
+}
+export function findToolCall(message, toolName) {
+    for (const content of message.content) {
+        if (content.type === "toolCall" && content.name === toolName) {
+            return content;
+        }
+    }
+    return undefined;
+}
+export function getTextContent(message) {
+    return message.content
+        .filter((content) => content.type === "text")
+        .map((content) => content.text)
+        .join("\n")
+        .trim();
+}
+export function parseJsonFromText(message) {
+    const text = getTextContent(message);
+    if (!text) {
+        return null;
+    }
+    const candidates = collectJsonCandidates(text);
+    for (const candidate of candidates) {
+        const parsed = tryParseJson(candidate);
+        if (parsed !== null) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function collectJsonCandidates(text) {
+    const candidates = [];
+    const fenced = extractFencedJson(text);
+    if (fenced) {
+        candidates.push(fenced);
+    }
+    candidates.push(text);
+    const objectCandidate = sliceBetween(text, "{", "}");
+    if (objectCandidate) {
+        candidates.push(objectCandidate);
+    }
+    const arrayCandidate = sliceBetween(text, "[", "]");
+    if (arrayCandidate) {
+        candidates.push(arrayCandidate);
+    }
+    return candidates;
+}
+function extractFencedJson(text) {
+    const match = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+    return match ? match[1].trim() : null;
+}
+function sliceBetween(text, open, close) {
+    const start = text.indexOf(open);
+    const end = text.lastIndexOf(close);
+    if (start === -1 || end === -1 || end <= start) {
+        return null;
+    }
+    return text.slice(start, end + 1).trim();
+}
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/schema/normalize.d.ts

@@ -0,0 +1,7 @@
+import type { Api, Model } from "@mariozechner/pi-ai";
+import type { TSchema } from "@sinclair/typebox";
+export type NormalizedToolSchema = {
+    schema: TSchema;
+    unwrapKey: string | null;
+};
+export declare function normalizeToolSchema(model: Model<Api>, schema: TSchema): NormalizedToolSchema;