langfx.js 0.1.0-alpha.0

package/dist/mapping.js

@@ -0,0 +1,190 @@
+import * as python from './python.js';
+import { OutputValidationError } from './errors.js';
+import { LangFunc } from './langfunc.js';
+import { AIMessage, ComplexMessage, Message, Modality, SystemMessage, UserMessage } from './message.js';
+import { resolveSchema } from './schema.js';
+import { Template, renderPrompt } from './template.js';
+export class MappingError extends OutputValidationError {
+    lmResponse;
+    /** A failed eviction must not hide the original mapping failure. */
+    cacheInvalidationError;
+    constructor(lmResponse, cause) {
+        super('Model output did not satisfy the response mapping.', { cause });
+        this.lmResponse = lmResponse;
+    }
+}
+export class MappingExample {
+    input;
+    output;
+    schema;
+    context;
+    metadata;
+    hasOutput;
+    constructor(options) {
+        this.input = options.input;
+        this.output = options.output;
+        this.schema = options.schema;
+        this.context = options.context;
+        this.metadata = Object.freeze({ ...options.metadata });
+        this.hasOutput = Object.hasOwn(options, 'output');
+    }
+}
+/** Reusable JSON mapping pipeline. Local rendering/parsing hooks stay synchronous. */
+export class Mapping extends LangFunc {
+    static templateStr = '{{instructions}}{{request}}';
+    preambleOverride;
+    input;
+    protocol;
+    schema;
+    examples;
+    systemMessage;
+    constructor(options) {
+        super(options.templateStr, options);
+        this.protocol = options.protocol ?? 'python';
+        if (!['json', 'python'].includes(this.protocol))
+            throw new TypeError('Unsupported mapping protocol.');
+        this.preambleOverride = options.preamble;
+        this.input = options.input;
+        this.schema = resolveSchema(options.schema);
+        if (this.protocol === 'python')
+            python.schemaText(this.schema);
+        this.examples = Object.freeze([...(options.examples ?? [])]);
+        this.systemMessage = options.systemMessage;
+    }
+    get mappingRequest() { return new MappingExample({ input: this.input, schema: this.schema }); }
+    get preamble() { return this.preambleOverride ?? new Template(''); }
+    get inputTitle() { return 'INPUT'; }
+    get outputTitle() { return 'OUTPUT'; }
+    get schemaTitle() { return 'SCHEMA'; }
+    renderWith(variables, stack) {
+        const vars = { ...this.variables, ...variables, inputTitle: this.inputTitle, outputTitle: this.outputTitle, schemaTitle: this.schemaTitle };
+        const instructionParts = [];
+        const preamble = this.preamble.render(vars);
+        if (preamble.text.trim())
+            instructionParts.push(preamble);
+        const examples = this.examples.flatMap(example => this.renderExample(example, vars));
+        const multimodal = examples.some(example => example.sections.some(section => section.parts.some(part => part instanceof Modality)));
+        // Providers require image data in user turns. Keep text-only prompt parity.
+        if (!multimodal)
+            instructionParts.push(...examples);
+        instructionParts.push(new UserMessage(`${this.schemaTitle}:\n${indent(this.protocol === 'python' ? python.schemaText(this.schema) : JSON.stringify(this.schema.jsonSchema))}`));
+        if (this.systemMessage !== undefined)
+            instructionParts.push(renderPrompt(this.systemMessage, vars));
+        const turns = [...renderPrompt(this.mappingRequest.input, vars).sections];
+        while (turns[0]?.role === 'system')
+            instructionParts.push(turns.shift());
+        const instructions = new SystemMessage(joinData(instructionParts));
+        const input = new UserMessage([`${this.inputTitle}:\n  `, ...indentParts(turns), `\n\n${this.outputTitle}:`]);
+        const request = multimodal ? new ComplexMessage([...examples, input]) : input;
+        return super.renderWith({ ...vars, instructions, request }, stack);
+    }
+    renderExample(example, variables = {}) {
+        if (!example.hasOutput)
+            throw new TypeError('Few-shot examples require an output.');
+        const schema = resolveSchema(example.schema ?? this.schema);
+        const text = this.protocol === 'python' ? python.formatExample(schema, example.output) : JSON.stringify(example.output, (_key, value) => {
+            if (value === undefined || ['function', 'symbol', 'bigint'].includes(typeof value) || (typeof value === 'number' && !Number.isFinite(value)))
+                throw new TypeError('Example output must be JSON data.');
+            return value;
+        });
+        if (this.protocol === 'python')
+            python.parse(schema, text);
+        else
+            schema.parse(JSON.parse(text));
+        const input = typeof example.input === 'string' ? new UserMessage(example.input) : renderPrompt(example.input, variables);
+        return [new UserMessage([
+                `${this.schemaTitle}:\n${indent(this.protocol === 'python' ? python.schemaText(schema) : JSON.stringify(schema.jsonSchema))}\n\n`,
+                ...(example.context === undefined ? [] : [`CONTEXT:\n${indent(example.context)}\n\n`]),
+                `${this.inputTitle}:\n  `, ...indentParts(input.sections),
+                `\n\n${this.outputTitle}:\n${indent(text)}`,
+            ])];
+    }
+    postprocessResponse(response) { return response; }
+    parseResult(response) { return this.protocol === 'python' ? python.parse(this.schema, response.text) : this.schema.parse(JSON.parse(response.text)); }
+    postprocessResult(result) { return result; }
+    transformOutput(response) {
+        try {
+            const processed = this.postprocessResponse(response);
+            const result = this.postprocessResult(this.parseResult(processed));
+            return new AIMessage(processed.parts, { result, source: response, metadata: { ...response.metadata, ...processed.metadata } });
+        }
+        catch (cause) {
+            throw new MappingError(response, cause);
+        }
+    }
+    async call(options = {}) {
+        const { lm = this.lm, vars, ...sampling } = options;
+        if (!lm)
+            throw new TypeError('Mapping.call requires a LanguageModel.');
+        const response = await lm.call(this.transformInput(this.render(vars)), sampling);
+        try {
+            return this.transformOutput(response);
+        }
+        catch (cause) {
+            return failMapping(lm, response, cause);
+        }
+    }
+}
+/** Query specialization for JSON and restricted Python constructor protocols. */
+export class LfQuery extends Mapping {
+    get inputTitle() { return this.protocol === 'python' ? 'REQUEST' : 'INPUT_OBJECT'; }
+    get outputTitle() { return this.protocol === 'python' ? 'OUTPUT PYTHON OBJECT' : 'JSON'; }
+    get schemaTitle() { return this.protocol === 'python' ? 'OUTPUT PYTHON TYPE' : 'SCHEMA'; }
+    get preamble() {
+        if (this.protocol === 'python')
+            return this.preambleOverride ?? new Template(`Please respond to the last {{inputTitle}} with {{outputTitle}} only according to {{schemaTitle}}.
+
+{{schemaTitle}}:
+  Answer
+
+  \`\`\`python
+  class Answer:
+    final_answer: int
+  \`\`\`
+
+{{inputTitle}}:
+  1 + 1 =
+
+{{outputTitle}}:
+  \`\`\`python
+  output = Answer(
+    final_answer=2
+  )
+  \`\`\``);
+        return this.preambleOverride ?? new Template(`Please respond to the last {{inputTitle}} with {{outputTitle}} according to {{schemaTitle}}:
+
+INSTRUCTIONS:
+  1. Return only JSON matching the JSON Schema, without Markdown fences or a result wrapper.
+  2. Use null only when the schema permits it; do not invent missing facts.
+
+{{schemaTitle}}:
+  {{exampleSchema}}
+
+{{inputTitle}}:
+  1 + 1 =
+
+{{outputTitle}}:
+  {{exampleOutput}}`, {
+            exampleSchema: JSON.stringify({ type: 'object', properties: { final_answer: { type: 'integer' } }, required: ['final_answer'] }),
+            exampleOutput: JSON.stringify({ final_answer: 2 }),
+        });
+    }
+}
+function indent(text) { return text.split('\n').map(line => line ? `  ${line}` : '').join('\n'); }
+function indentParts(messages) {
+    return messages.flatMap(message => message.sections.flatMap(section => section.parts.map(part => typeof part === 'string' ? part.replace(/\n/g, '\n  ') : part)));
+}
+function joinData(messages) {
+    return messages.flatMap((message, index) => [...(index ? ['\n\n'] : []), ...message.sections.flatMap(section => [...section.parts])]);
+}
+export async function failMapping(lm, response, cause) {
+    const error = cause instanceof MappingError ? cause : new MappingError(response, cause);
+    try {
+        await lm.invalidateCache(response);
+    }
+    catch (cleanupError) {
+        error.cacheInvalidationError = cleanupError;
+    }
+    throw error;
+}
+//# sourceMappingURL=mapping.js.map

package/dist/mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":"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"}

package/dist/message.d.ts

@@ -0,0 +1,56 @@
+import type { ToolCall } from './tool-call.js';
+export type Role = 'user' | 'assistant' | 'system' | 'tool';
+export type MediaSource = {
+    readonly kind: 'uri';
+    readonly uri: string;
+} | {
+    readonly kind: 'bytes';
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: 'blob';
+    readonly blob: Blob;
+};
+export declare class Modality {
+    readonly mimeType: string;
+    readonly source: MediaSource;
+    constructor(mimeType: string, source: MediaSource);
+}
+export declare class Image extends Modality {
+    static fromUri(uri: string, mimeType?: string): Image;
+    static fromBytes(bytes: Uint8Array, mimeType: string): Image;
+    static fromFile(file: Blob): Image;
+}
+export type MessagePart = string | Modality | Message;
+export interface MessageOptions<T = unknown> {
+    readonly result?: T;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly source?: Message;
+}
+export declare class Message<T = unknown> {
+    readonly role: Role;
+    readonly parts: readonly MessagePart[];
+    readonly result: T;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly source: Message | undefined;
+    constructor(content: string | readonly MessagePart[], role?: Role, options?: MessageOptions<T>);
+    get toolCalls(): readonly ToolCall[];
+    get text(): string;
+    /** Flatten embedded role-scoped turns without changing their order. */
+    get sections(): readonly Message[];
+}
+export declare class UserMessage<T = unknown> extends Message<T> {
+    constructor(content: string | readonly MessagePart[], options?: MessageOptions<T>);
+}
+export declare class AIMessage<T = unknown> extends Message<T> {
+    constructor(content: string | readonly MessagePart[], options?: MessageOptions<T>);
+}
+export declare class SystemMessage extends Message {
+    constructor(content: string | readonly MessagePart[], options?: MessageOptions);
+}
+export declare class ToolMessage extends Message {
+    readonly toolCallId: string;
+    constructor(content: string | readonly MessagePart[], toolCallId: string, options?: MessageOptions);
+}
+export declare class ComplexMessage extends Message {
+    constructor(messages: readonly Message[]);
+}

package/dist/message.js

@@ -0,0 +1,86 @@
+export class Modality {
+    mimeType;
+    source;
+    constructor(mimeType, source) {
+        this.mimeType = mimeType;
+        if (!mimeType)
+            throw new TypeError('A MIME type is required.');
+        this.source = Object.freeze(source.kind === 'bytes'
+            ? { kind: 'bytes', bytes: source.bytes.slice() } : { ...source });
+    }
+}
+export class Image extends Modality {
+    static fromUri(uri, mimeType = 'image/*') {
+        return new Image(mimeType, { kind: 'uri', uri });
+    }
+    static fromBytes(bytes, mimeType) {
+        return new Image(mimeType, { kind: 'bytes', bytes });
+    }
+    static fromFile(file) {
+        if (!file.type.startsWith('image/'))
+            throw new TypeError('Expected an image MIME type.');
+        return new Image(file.type, { kind: 'blob', blob: file });
+    }
+}
+export class Message {
+    role;
+    parts;
+    result;
+    metadata;
+    source;
+    constructor(content, role = 'user', options = {}) {
+        this.role = role;
+        this.parts = Object.freeze(typeof content === 'string' ? [content] : [...content]);
+        this.result = options.result;
+        this.metadata = Object.freeze({ ...options.metadata });
+        this.source = options.source;
+    }
+    get toolCalls() {
+        return this.metadata['toolCalls'] ?? [];
+    }
+    get text() {
+        return this.parts.map(part => typeof part === 'string' ? part : part instanceof Message ? part.text : '').join('');
+    }
+    /** Flatten embedded role-scoped turns without changing their order. */
+    get sections() {
+        if (!this.parts.some(part => part instanceof Message))
+            return [this];
+        const sections = [];
+        let buffer = [];
+        const flush = () => {
+            if (buffer.length)
+                sections.push(new Message(buffer, this.role, { metadata: this.metadata }));
+            buffer = [];
+        };
+        for (const part of this.parts) {
+            if (part instanceof Message) {
+                flush();
+                sections.push(...part.sections);
+            }
+            else
+                buffer.push(part);
+        }
+        flush();
+        return sections;
+    }
+}
+export class UserMessage extends Message {
+    constructor(content, options = {}) { super(content, 'user', options); }
+}
+export class AIMessage extends Message {
+    constructor(content, options = {}) { super(content, 'assistant', options); }
+}
+export class SystemMessage extends Message {
+    constructor(content, options = {}) { super(content, 'system', options); }
+}
+export class ToolMessage extends Message {
+    toolCallId;
+    constructor(content, toolCallId, options = {}) {
+        super(content, 'tool', { ...options, metadata: { ...options.metadata, toolCallId } });
+        this.toolCallId = toolCallId;
+    }
+}
+export class ComplexMessage extends Message {
+    constructor(messages) { super(messages); }
+}
+//# sourceMappingURL=message.js.map

package/dist/message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"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"}

package/dist/python-preview.d.ts

@@ -0,0 +1,24 @@
+import type { JsonStreamEvent } from './json-stream.js';
+/** Best-effort, factory-free previews. The complete Python parser remains authoritative. */
+export declare class PythonPreview {
+    private readonly maxDepth;
+    private buffer;
+    private scan;
+    private literal;
+    private stopped;
+    private current;
+    private readonly reader;
+    constructor(maxDepth: number);
+    feed(text: string, final?: boolean): Generator<JsonStreamEvent>;
+    private token;
+    /** Consume each string code unit once; incomplete escapes remain buffered. */
+    private stringToken;
+    private advance;
+    private expect;
+    private root;
+    private value;
+    /** Delay ambiguous first-element events until a comma or colon resolves the syntax. */
+    private capture;
+    private sequence;
+    private object;
+}