langfx.js 0.1.0-alpha.0

package/dist/tool-call.d.ts

@@ -0,0 +1,27 @@
+/** A complete model-requested call. Arguments still require tool validation. */
+export declare class ToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    constructor(id: string, name: string, args: Readonly<Record<string, unknown>>);
+}
+export interface ToolDeclaration {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+/** Display-only events. Completed arguments still require registered-tool validation.
+ * Wait for the successful final stream chunk before executing any calls.
+ */
+export type ToolCallStreamEvent = {
+    readonly type: 'toolCallStart';
+    readonly id: string;
+    readonly name: string;
+} | {
+    readonly type: 'toolCallDelta';
+    readonly id: string;
+    readonly delta: string;
+} | {
+    readonly type: 'toolCallEnd';
+    readonly call: ToolCall;
+};

package/dist/tool-call.js

@@ -0,0 +1,16 @@
+/** A complete model-requested call. Arguments still require tool validation. */
+export class ToolCall {
+    id;
+    name;
+    args;
+    constructor(id, name, args) {
+        this.id = id;
+        this.name = name;
+        this.args = args;
+        if (!id || !name)
+            throw new TypeError('Tool calls require an ID and name.');
+        if (!args || typeof args !== 'object' || Array.isArray(args))
+            throw new TypeError('Tool arguments must be an object.');
+    }
+}
+//# sourceMappingURL=tool-call.js.map

package/dist/tool-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call.js","sourceRoot":"","sources":["../src/tool-call.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,OAAO,QAAQ;IAER,EAAE;IACF,IAAI;IACJ,IAAI;IAHf,YACW,EAAU,EACV,IAAY,EACZ,IAAuC;kBAFvC,EAAE;oBACF,IAAI;oBACJ,IAAI;QAEb,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,SAAS,CAAC,oCAAoC,CAAC,CAAC;QAC5E,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,mCAAmC,CAAC,CAAC;IACzH,CAAC;CACF"}

package/dist/tools.d.ts

@@ -0,0 +1,43 @@
+import { Action, Session } from './agentic.js';
+import type { RunOptions } from './agentic.js';
+import type { Schema } from './schema.js';
+import type { ToolCall, ToolDeclaration } from './tool-call.js';
+export interface ToolOptions<I, O> {
+    readonly name: string;
+    readonly description: string;
+    readonly input: Schema<I>;
+    /** Agent sends validated outputs as JSON; use plain objects/arrays, not Set, Map or class instances. */
+    readonly output: Schema<O>;
+    readonly execute: (input: I, session: Session) => Promise<O>;
+}
+export interface RegisteredTool {
+    readonly declaration: ToolDeclaration;
+    prepare(args: unknown): (session: Session) => Promise<unknown>;
+}
+export declare class Tool<I, O> implements RegisteredTool {
+    private readonly options;
+    readonly declaration: ToolDeclaration;
+    constructor(options: ToolOptions<I, O>);
+    /** Validate before any app function runs; returned closure holds validated args. */
+    prepare(args: unknown): (session: Session) => Promise<O>;
+}
+export interface AgentOptions {
+    readonly prompt: string;
+    readonly instructions?: string;
+    readonly tools?: readonly RegisteredTool[];
+    readonly limits?: {
+        readonly maxSteps?: number;
+        readonly maxToolCalls?: number;
+        readonly maxExecutionTime?: number;
+    };
+    readonly allowTool?: (call: ToolCall, session: Session) => boolean | Promise<boolean>;
+}
+export declare class Agent extends Action<string> {
+    private readonly options;
+    private readonly tools;
+    private readonly maxSteps;
+    private readonly maxToolCalls;
+    constructor(options: AgentOptions);
+    invoke(session?: Session, options?: RunOptions): Promise<string>;
+    call(session: Session): Promise<string>;
+}

package/dist/tools.js

@@ -0,0 +1,155 @@
+import { Action, Session } from './agentic.js';
+import { checkCancelled } from './cancellation.js';
+import { BudgetExceededError, EmptyGenerationError, ToolDeniedError, ToolExecutionError } from './errors.js';
+import { ComplexMessage, SystemMessage, ToolMessage, UserMessage } from './message.js';
+export class Tool {
+    options;
+    declaration;
+    constructor(options) {
+        this.options = options;
+        if (!/^[A-Za-z_][A-Za-z0-9_-]{0,63}$/.test(options.name))
+            throw new TypeError('Invalid tool name.');
+        this.declaration = Object.freeze({ name: options.name, description: options.description, inputSchema: options.input.jsonSchema });
+    }
+    /** Validate before any app function runs; returned closure holds validated args. */
+    prepare(args) {
+        let input;
+        try {
+            input = this.options.input.parse(args);
+        }
+        catch (cause) {
+            throw new ToolExecutionError(`Invalid arguments for tool ${this.declaration.name}.`, { cause });
+        }
+        return async (session) => {
+            checkCancelled(session.signal);
+            try {
+                const output = this.options.output.parse(await this.options.execute(input, session));
+                checkCancelled(session.signal);
+                return output;
+            }
+            catch (cause) {
+                checkCancelled(session.signal);
+                throw new ToolExecutionError(`Tool ${this.declaration.name} failed.`, { cause });
+            }
+        };
+    }
+}
+class ExecuteTool extends Action {
+    toolName;
+    execute;
+    constructor(toolName, execute) {
+        super();
+        this.toolName = toolName;
+        this.execute = execute;
+    }
+    get name() { return `Tool:${this.toolName}`; }
+    call(session) { return this.execute(session); }
+}
+export class Agent extends Action {
+    options;
+    tools;
+    maxSteps;
+    maxToolCalls;
+    constructor(options) {
+        super();
+        this.options = options;
+        this.maxSteps = options.limits?.maxSteps ?? 8;
+        this.maxToolCalls = options.limits?.maxToolCalls ?? 12;
+        if (!Number.isInteger(this.maxSteps) || this.maxSteps < 1 || !Number.isInteger(this.maxToolCalls) || this.maxToolCalls < 0) {
+            throw new RangeError('Agent limits require positive maxSteps and non-negative maxToolCalls.');
+        }
+        const tools = options.tools ?? [];
+        this.tools = new Map(tools.map(tool => [tool.declaration.name, tool]));
+        if (this.tools.size !== tools.length)
+            throw new TypeError('Tool names must be unique.');
+    }
+    invoke(session, options = {}) {
+        const configured = this.options.limits?.maxExecutionTime ?? 60;
+        const seconds = Math.min(configured, options.maxExecutionTime ?? configured);
+        return super.invoke(session, { ...options, maxExecutionTime: seconds });
+    }
+    async call(session) {
+        const messages = [];
+        if (this.options.instructions)
+            messages.push(new SystemMessage(this.options.instructions));
+        messages.push(new UserMessage(this.options.prompt));
+        const usedIds = new Set();
+        let calls = 0;
+        for (let step = 0; step < this.maxSteps; step++) {
+            checkCancelled(session.signal);
+            const response = await session.query(new ComplexMessage(messages), {
+                tools: [...this.tools.values()].map(tool => tool.declaration), returnsMessage: true,
+            });
+            messages.push(response);
+            if (!response.toolCalls.length) {
+                if (!response.text)
+                    throw new EmptyGenerationError('Agent received neither text nor tool calls.');
+                checkCancelled(session.signal);
+                return response.text;
+            }
+            // Reserve the entire batch and validate it before allowing side effects.
+            if (step + 1 >= this.maxSteps)
+                throw new BudgetExceededError('No model step remains to consume tool results.');
+            if (calls + response.toolCalls.length > this.maxToolCalls)
+                throw new BudgetExceededError('Agent tool-call limit exceeded.');
+            const prepared = response.toolCalls.map(call => {
+                if (usedIds.has(call.id))
+                    throw new ToolExecutionError(`Duplicate tool-call ID: ${call.id}`);
+                usedIds.add(call.id);
+                const tool = this.tools.get(call.name);
+                if (!tool)
+                    throw new ToolExecutionError(`Unknown tool: ${call.name}`);
+                return { call, execute: tool.prepare(call.args) };
+            });
+            for (const { call } of prepared) {
+                if (this.options.allowTool && !await this.options.allowTool(call, session))
+                    throw new ToolDeniedError(`Tool denied: ${call.name}`);
+                checkCancelled(session.signal);
+            }
+            calls += prepared.length;
+            for (const { call, execute } of prepared) {
+                const output = await new ExecuteTool(call.name, execute).invoke(session);
+                let text;
+                try {
+                    validateJsonOutput(output);
+                    text = JSON.stringify(output, (_key, value) => {
+                        if (value === undefined || typeof value === 'function' || typeof value === 'symbol'
+                            || typeof value === 'bigint' || typeof value === 'number' && !Number.isFinite(value)) {
+                            throw new TypeError('Tool output contains a non-JSON value.');
+                        }
+                        return value;
+                    });
+                }
+                catch (cause) {
+                    throw new ToolExecutionError('Tool output is not JSON serializable.', { cause });
+                }
+                if (text === undefined)
+                    throw new ToolExecutionError('Tool output must be JSON serializable.');
+                messages.push(new ToolMessage(text, call.id, { metadata: { toolName: call.name } }));
+            }
+        }
+        throw new BudgetExceededError('Agent model-step limit exceeded.');
+    }
+}
+/** Reject containers that JSON.stringify would silently erase or transform. */
+function validateJsonOutput(value, ancestors = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean'
+        || typeof value === 'number' && Number.isFinite(value))
+        return;
+    if (typeof value !== 'object')
+        throw new TypeError('Tool output contains a non-JSON value.');
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError('Tool output requires plain JSON objects and arrays.');
+    }
+    if (ancestors.has(value))
+        throw new TypeError('Tool output contains a cycle.');
+    if (Object.getOwnPropertySymbols(value).some(key => Object.prototype.propertyIsEnumerable.call(value, key))) {
+        throw new TypeError('Tool output contains a symbol key.');
+    }
+    ancestors.add(value);
+    for (const child of Array.isArray(value) ? value : Object.values(value))
+        validateJsonOutput(child, ancestors);
+    ancestors.delete(value);
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/docs/ANTHROPIC.md

@@ -0,0 +1,43 @@
+# Anthropic Messages adapter
+
+`Anthropic extends LanguageModel` is available through `lf.llms.Anthropic`, `langfx.js/llms`, and `langfx.js/llms/anthropic`. It implements text calls, complete client tools/results, and text/tool SSE streaming. Tests and browser demos use mocked HTTP, not live inference.
+
+```ts
+import { Anthropic } from 'langfx.js/llms/anthropic';
+
+const lm = new Anthropic({
+  model: 'your-model-id',
+  apiKey: async signal => obtainAppCredential(signal), // application-owned
+  maxTokens: 4096,
+});
+const message = await lm.call('Explain closures.');
+for await (const chunk of lm.stream('Explain generators.')) {
+  console.log(chunk.delta.text);
+}
+```
+
+The default endpoint is `https://api.anthropic.com/v1/messages`. `baseUrl` overrides the version root and `transport` accepts the same injected fetch-like interface as Gemini. No environment variables or global credentials are read. A supplied API key is sent in `x-api-key`; the version header is `2023-06-01`. `maxTokens` defaults to 4096. Omitting a key supports a host-authenticated gateway/transport. Direct browser requests depend on the endpoint's CORS/auth configuration; this adapter does not enable a browser-access override header automatically. The fixture browser demo makes no external requests. See Anthropic's [API overview](https://platform.claude.com/docs/en/api/overview).
+
+Leading system sections become top-level `system` blocks. Adjacent equal-role turns are merged. Client tools use `input_schema`, `tool_use`, and immediately following user `tool_result` blocks. IDs must correlate and every pending call must have a result before another conversation turn. Tool choice supports auto, any, none, or a registered name. Raw supported response blocks are retained in scoped metadata so their ordering survives caching and application-owned transcripts. Reuse of continuation data across a different model or endpoint rejects. This follows the [tool-result protocol](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls).
+
+SSE parsing handles fragmented UTF-8 and line boundaries. The adapter checks message/block event order, processes cumulative usage, and requires a complete message_stop before final success. Unknown top-level event types are ignored for forward compatibility; unsupported block/delta types reject. Early exit and failures close the reader. The base model retries only eligible failures before any chunk is emitted. See [stream event definitions](https://platform.claude.com/docs/en/build-with-claude/streaming).
+
+Authentication errors, rate limits, and transient server errors map to the shared error classes. Truncation rejects with IncompleteGenerationError; refusal rejects with ContentFilteredError. Provider error bodies are not exposed in error messages. In-band overload/rate errors retain classification. Generic transport errors remain unclassified and do not automatically retry.
+
+Usage totals include input_tokens, cache_creation_input_tokens, and cache_read_input_tokens, plus output_tokens. Missing totals stay unknown. These counts do not imply a single token price or include unreported failed-attempt usage. See Anthropic's [prompt-cache usage fields](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).
+
+## Current limits
+
+- Images are supported only in user messages; other modalities reject before transport.
+- Prompt-based JSON queries and structured JSON field streaming work through the existing Mapping/parser. Native structured output is not yet implemented and rejects explicitly.
+- Complete client tool calls work with Agent and explicit conversation transcripts. Tool streaming emits start, argument-delta, and completion events; the final aggregated message preserves complete tool calls and continuation blocks. See [tool streaming](TOOL_STREAMING.md).
+- Thinking/redacted-thinking blocks, citations deltas, server tools, managed agents, automatic continuation on pause_turn, and cloud-platform authentication are not implemented. Unsupported response blocks never silently degrade to text.
+- Model availability, live CORS/auth behavior, and model-specific option compatibility remain unverified. No model ID is hardcoded as a default.
+
+Run `npm run check` for fixture contracts and `npm run serve:example` for the window/worker mocked tool-loop demo. Live-provider testing remains a separate step requiring application-provided credentials.
+
+## Image inputs
+
+User messages accept ordered text and `Image` parts, including templates and `LfQuery`. HTTP(S) URI images become `image` blocks with URL sources; bytes and Blob/File images use base64 sources with explicit media types. The adapter does not download URL images. See the [Anthropic vision protocol](https://platform.claude.com/docs/en/build-with-claude/vision).
+
+Inline images require PNG, JPEG, GIF, or WebP MIME types and 1 byte–5 MiB per image (a conservative local adapter bound, not a model limit). Blob reads observe cancellation. Other modalities and images in system, assistant, or tool messages reject. Image contents are not decoded or validated locally; model support and provider limits still apply. Image inputs also work with text output streaming. Tests use mocked transport, not live inference.

package/docs/API_DESIGN.md

@@ -0,0 +1,200 @@
+# Proposed TypeScript API
+
+This document describes the target API. The core, Gemini adapter, bounded Agent loop, structured JSON field streams, opt-in retries, and an in-memory cache are implemented; other providers and other future examples remain design sketches. See [implementation status](IMPLEMENTATION_STATUS.md) and the runnable examples in the README. **Python API consistency is a primary design goal.** Keep the same public concepts, class hierarchy, construction style, method responsibilities, and default return values wherever JavaScript permits. Classes are the primary API, not a later convenience layer.
+
+The implementation can use plain data, explicit schemas, and invocation-local state internally without exposing a different client/factory programming model. No separate `createClient` is required: a `LanguageModel` object is already the model abstraction.
+
+## Python-to-TypeScript mapping
+
+| Python | Proposed TypeScript | Reason for any difference |
+| --- | --- | --- |
+| `lf.llms.Gemini(model=...)` | `new lf.llms.Gemini({ model })` | JavaScript constructor/options syntax |
+| `lf.LanguageModel` subclass | `class CustomModel extends lf.LanguageModel` | Preserve inheritance and custom-provider extension |
+| `lf.query(prompt, Schema, lm=lm)` | `await lf.query(prompt, Schema, { lm })` | Same positional schema and direct typed result; async I/O |
+| `lf.query(prompt, lm=lm)` | `await lf.query(prompt, { lm })` | Unstructured overload returns text |
+| `returns_message=True` | `returnsMessage: true` | Optional message/result metadata, not a mandatory envelope |
+| `lf.Template("Hello {{name}}")` | `new lf.Template("Hello {{name}}")` | Keep basic template syntax; full Jinja is out of scope |
+| `lf.LangFunc(...)` | `new lf.LangFunc(...)` / subclass | Keep the prompt → model → transform pipeline |
+| `lm(prompt)` / `langfunc(...)` | `await lm.call(prompt)` / `await langfunc.call(...)` | Ordinary JavaScript class instances are not callable |
+| `lm.sample(prompts)` / `lm.stream(prompt)` | `await lm.sample(prompts)` / `lm.stream(prompt)` | Promise results and async iteration |
+| `lf.query_stream(...)` | `lf.queryStream(...)` | Mechanical snake_case → camelCase naming |
+| `lf.Action` with `async call(session, ...)` | `class X extends lf.Action<T>` with `async call(session, ...)` | Preserve the implementation hook |
+| `await action(session, ...)` | `await action.invoke(session, ...)` | Separate public lifecycle wrapper from the overridden `call` hook |
+| `lf.Session(...)` | `new lf.Session(...)` | Preserve session construction, queries, events, and traces |
+| `lf.UserMessage(...)`, `lf.Image.from_uri(...)` | `new lf.UserMessage(...)`, `lf.Image.fromUri(...)` | Preserve public message/modality classes |
+| `lf.context(...)` | Model/session defaults and explicit overrides | Deliberate browser concurrency boundary; no mutable ambient context |
+| `pg.Object` schema inferred from annotations | Explicit `lf.Schema<T>` or class with declared schema | TypeScript annotations alone supply no runtime validator |
+
+Use camelCase consistently for multiword methods/options (`maxTokens`, `cacheSeed`, `systemMessage`). Keep `lm`, `schema`, and existing class names. One async API replaces Python's sync/async pairs; synchronous wrappers and `a`-prefixed duplicates are deliberately excluded. These naming and context choices are design decisions, not requirements of TypeScript.
+
+## Execution model: one async API for I/O
+
+**Design decision:** keep Python's familiar unprefixed names, with asynchronous semantics for operations that may perform I/O. Do not port synchronous wrappers, blocking bridges, or duplicate `a`-prefixed methods/functions. This applies to public APIs and protected provider hooks.
+
+| Python pair | TypeScript API | Return contract |
+| --- | --- | --- |
+| `LanguageModel.__call__` / `acall` | `lm.call(...)` | `Promise<Message>` |
+| `sample` / `asample` | `lm.sample(...)` | `Promise<SamplingResult[]>` |
+| `stream` / `astream` | `lm.stream(...)` | `AsyncIterable<StreamChunk>` |
+| `lf.query` / `lf.aquery` | `lf.query(...)` | `Promise<T>` (or text/message according to the overload) |
+| `lf.query_stream` / `lf.aquery_stream` | `lf.queryStream(...)` | `AsyncIterable` of text or structured events |
+| `LangFunc.__call__` / `acall` | `langFunc.call(...)` | `Promise<Message>` |
+| `Session.query` / `Session.aquery` | `session.query(...)` | Same Promise overloads as `lf.query` |
+
+Call Promise-returning methods with `await`; consume streams with `for await...of`. Stream methods return the async iterable directly, not a Promise of an iterable. Model calls retain these contracts even for a cache hit or a fake/local model. Protected `_sample` returns a Promise and `_stream` returns an async iterable; neither has a separate synchronous or `a`-prefixed counterpart.
+
+JavaScript local computation is still synchronous. Constructors, message manipulation, `Template.render`, local JSON parsing, and `Schema.parse` return ordinary values and throw ordinary errors. In contrast, Langfx's LLM-assisted `parse` helper will be async when ported, because it calls a model. Media loading and persistent storage are async where they perform I/O; creating a URI descriptor is synchronous.
+
+`Action.invoke` and its `call` hook, tool execution, and future embedding/MCP/evaluation operations follow the same async I/O rule. Do not introduce a second naming family for local implementations of those interfaces. Async does not imply parallel execution; concurrency remains explicitly controlled by the caller or session.
+
+## Model construction and extension
+
+```ts
+import * as lf from 'langfx.js';
+
+// modelId and transport are supplied by the application.
+const lm = new lf.llms.Gemini({ model: modelId, transport });
+const answer = await lf.query('What is 1 + 1?', { lm }); // string
+const response = await lm.call('What is 1 + 1?');       // Message
+console.log(answer, response.text);
+```
+
+`OpenAI`, `Anthropic`, and `Gemini` extend `LanguageModel`. The base owns normalization, cache lookup, retries, usage, and cancellation. Providers implement protected async `_sample` and `_stream` hooks; callers use public `call`, `sample`, and `stream`. The initial retry/cache options and deliberate scope differences are documented in [retries and cache](RETRIES_AND_CACHE.md). This mirrors Python's base-class/template-method organization while removing synchronous bridging. A minimal custom model implements `_sample`; unsupported streaming is reported explicitly unless one-event emulation is requested.
+
+Keep `SamplingOptions`, `SamplingResult`, `Sample`, `StreamChunk`, `ToolCall`, and the error hierarchy recognizable. Provider option types extend the common sampling options. Constructors accept an options object; flat sampling options may be routed to a typed options value just as in Python. Call-time overrides never mutate shared model defaults.
+
+`sample` retains a list-of-prompts input and list-of-results output. P0 can limit each prompt to one candidate while preserving the result structure. Capabilities describe supported modalities, tools, schemas, and streaming. Unsupported requested capabilities fail clearly.
+
+Offer `lf.llms` namespace access and direct imports such as `langfx.js/llms/gemini`. Root namespace exports must stay free of registration/network side effects and pass a single-provider tree-shaking check. Heavy optional/native adapters remain separate imports. Named model conveniences can be thin subclasses later; omitting a large historical model catalog does not require omitting provider classes. Defer `LanguageModel.get` until explicit provider registration/resolution is designed.
+
+## Typed queries and runtime schemas
+
+```ts
+import * as lf from 'langfx.js';
+import { fromZod } from 'langfx.js/schema/zod';
+import { z } from 'zod';
+
+const ImageDescription = fromZod(z.object({
+  items: z.array(z.object({ name: z.string(), color: z.string() })),
+}));
+
+const image = lf.Image.fromFile(file);
+const desc = await lf.query(
+  'Describe objects in {{image}} from top to bottom.',
+  ImageDescription,
+  { lm, vars: { image }, signal: controller.signal },
+);
+renderItems(desc.items); // Direct typed value, like Python lf.query.
+
+const message = await lf.query('Describe {{image}}.', ImageDescription, {
+  lm, vars: { image }, returnsMessage: true,
+});
+renderItems(message.result.items);
+```
+
+The optional Zod adapter is implemented through the separate `langfx.js/schema/zod` entry point. `Schema<T>` pairs a model-facing JSON Schema with `parse(value: unknown): T`. It is an adapter contract, not a new schema language. `query(prompt, schema, options)` returns `Promise<T>`; without a schema it returns `Promise<string>`. The `returnsMessage: true` overload returns `Promise<Message<T>>` with a validated `result`, provenance, and available usage metadata. Detailed invocation tracking is available through Session; ordinary queries do not require `.value` access.
+
+A schema-bearing class can be accepted through an explicit `static schema: Schema<MyClass>` whose validator constructs a class instance. This preserves object-oriented output where desired without inferring field schemas from erased annotations, requiring decorators, or importing a symbolic object system. Generic `query<MyClass>(...)` alone does not establish validation. Dynamic MCP schemas produce `unknown` until validated/refined by application code.
+
+Both native structured output and prompt-JSON output use the same final validator. Retain Python's `nativeStructuredOutput` option: false selects prompt-based output (Python by default, JSON with `protocol: 'json'`), true requires provider-native support. An unsupported native request fails before sending; it does not silently retry another mode. Python is the default for prompt-based structured queries; `protocol: 'python'` supports a restricted constructor-data grammar with explicit factories. See [Python protocol](PYTHON_PROTOCOL.md). Bounded repair remains P1.
+
+## Template, LangFunc, and messages
+
+```ts
+const greeting = new lf.Template('Hello {{name}}!', { name: 'world' });
+const rendered = greeting.render({ name: 'Ada' }); // Message
+
+const explain = new lf.LangFunc('Explain {{topic}}.', { lm });
+const response = await explain.call({ vars: { topic: 'rainbows' } });
+console.log(response.text);
+```
+
+Port `Template.render`, composition, bound variables, `fromRawStr`, and basic `{{name}}`/property-path substitution. Interpolated Template, Message, and Modality objects retain their structure. Do not evaluate arbitrary expressions or claim full Jinja compatibility: filters, statements, loops, inheritance, and partial unresolved expressions remain outside P0. JavaScript prompt functions or an optional tagged-template helper cover more elaborate composition.
+
+For consistency with Python, query string inputs use this Template subset. Wrap literal text in `UserMessage` or use `Template.fromRawStr` when braces must not be interpreted. Separate `vars` from model/run options to prevent variable names from colliding with configuration keys. Missing variables raise a rendering error in P0.
+
+`LangFunc extends Template` and retains `transformInput`/`transformOutput` subclass hooks. `call` returns `Promise<Message>`, resolving to the output Message as in Python; `stream` returns `AsyncIterable<StreamChunk>`. Store per-call input/output in invocation records rather than shared last-call fields, so a reusable instance is concurrency-safe.
+
+Retain `Message`, `UserMessage`, `AIMessage`, `SystemMessage`, `ToolMessage`, and `ComplexMessage` as public classes. `ComplexMessage` can compose role-scoped turns; normalize to an ordered message array at the provider boundary. Ordered content parts, not marker-bearing text, are the internal source of truth. Keep text/result/metadata/provenance access and explicit conversion methods. Python symbolic mutation APIs are not required.
+
+Retain `Modality`, `Mime`, `Image`, `Audio`, `Video`, and `PDF` concepts. `Image.fromUri` constructs a descriptor without fetching; browser-specific `fromFile`/`fromBytes` complement it. Filesystem `fromPath` belongs to a host adapter. Tool calls/results preserve correlation IDs; provider continuation data remains opaque and scoped to its originating provider. Cache annotations stay separate from visible text.
+
+## Action and Session
+
+```ts
+class Summarize extends lf.Action<string> {
+  constructor(readonly text: string) { super(); }
+
+  override async call(session: lf.Session): Promise<string> {
+    return session.query('Summarize {{text}}.', {
+      vars: { text: this.text },
+    });
+  }
+}
+
+class Compare extends lf.Action<string[]> {
+  constructor(readonly documents: readonly string[]) { super(); }
+
+  override async call(session: lf.Session): Promise<string[]> {
+    return session.concurrentMap(
+      this.documents,
+      (text, branch) => new Summarize(text).invoke(branch),
+      { maxConcurrency: 3 },
+    );
+  }
+}
+
+const session = new lf.Session({ lm });
+const unsubscribe = session.subscribe(event => updateTrace(event));
+try {
+  const summaries = await new Compare(documents).invoke(session, {
+    signal: controller.signal,
+    maxExecutionTime: 30, // Seconds, preserving Python's option semantics.
+  });
+  renderSummaries(summaries);
+  inspectTrace(session.root);
+} finally {
+  unsubscribe();
+  await session.dispose();
+}
+```
+
+`Action.call` is the author-implemented hook. `Action.invoke` performs lifecycle tracking, deadlines, cancellation, and error recording before calling that hook. Users invoke actions through `invoke`, never directly through `call`. This explicit wrapper replaces Python `__call__`; making a class instance itself callable would require unnecessary function/proxy machinery. Omitting the session creates an owned session, and `invoke(undefined, { lm })` supplies its model.
+
+The hook receives an invocation-bound Session view. It shares the root trace store and budget but carries immutable parent ancestry and effective settings. `session.query`, nested `invoke(session)`, and `session.concurrentMap` therefore attribute work correctly without a process-global current action. A view is not a new independent conversation or root session. A view cannot be used to start work after its owning invocation ends.
+
+`Session.query` matches `lf.query` overloads and direct return values, with session defaults and trace attribution. Keep `root`, `allQueries`, `allActions`, `allLogs`, `usageSummary`, metadata, progress, and logging concepts. `concurrentMap` passes a bound branch view, limits concurrency, and cancels/settles cooperative siblings according to its error policy.
+
+An action object holds configuration; each invocation owns mutable state/result/error. Override precedence is model defaults → session/invocation defaults → explicit call options. Children cannot extend parent deadlines or increase the remaining shared budget. Avoid ambiguous `action.result` or `action.invocation` access during concurrent reuse; inspect per-run trace records.
+
+Session observers are UI notifications backed by a bounded trace store. A slow/throwing observer must not corrupt action execution. Disposal releases owned work/listeners/transports without closing a shared externally owned model. No JavaScript `with` or implicit async-context emulation is required.
+
+## Tools and bounded agents
+
+Keep Python's `ToolCall`, tool declarations, tool choice, and result messages. Add a small explicit `Tool<Input, Output>` class holding a name, input/output schemas, and an app-owned async execution function; it replaces Python schema reflection, not LanguageModel or Action.
+
+The proposed convenience loop is an `Agent extends Action<string>` with instructions, registered tools, and run limits. Construct it with `new Agent(...)` and execute through `invoke(session, options)`. `Tool` and `Agent` are additions, not claims of existing Python classes. Low-level Actions and tool calls remain independently usable.
+
+The loop performs request → complete tool calls → schema validation → policy/budget check → registered function execution → correlated result messages → next request. It returns the final answer directly; denial, limit exhaustion, cancellation, and failure have distinct errors/trace outcomes. Tools execute sequentially by default; parallel execution is opt-in. Never execute partial streamed arguments or automatically replay side-effectful tools.
+
+Model-selected Action classes require explicit declared schemas and an allowlisted mapping from discriminator/name to constructors. A model-provided class name must not trigger dynamic imports or arbitrary construction.
+
+## Streaming, persistence, and release checks
+
+Keep StreamChunk's delta, aggregated message, candidate index, final marker, usage, and finish reason. `queryStream` with a schema retains ObjectStart, FieldStart, StringFieldDelta, FieldEnd, ObjectEnd, GenerationComplete, and ParsingFailed semantics; replace Python path/schema/class objects with portable equivalents. Add a distinct cancellation terminal outcome. Partial data is never typed as validated `T`. The implemented discriminated event union uses camelCase `type` values, adds `generationFailed` for provider/transport failures, and represents paths as arrays of string keys and numeric indices. See [structured streaming](STREAMING.md) for the concrete contract.
+
+Close/abort upstream readers in `finally`, including early consumer exit. A fully consumed structured query stream reports one terminal outcome (early consumer exit closes it without a delivered terminal event); raw model/text streams retain their chunk-and-thrown-error contract; non-streaming calls reject on failure. Invalid setup may throw before iteration begins. Preserve classified errors and sanitized provider details. Test escape/UTF-8 fragmentation, stream termination, tool correlation, and usage aggregation.
+
+Serialize versioned message/history/trace data, not executable class definitions or closures. Public classes can implement explicit serialization without reproducing the PyGlove registry. Saved conversations start new runs; durable resume and exactly-once execution remain separate concerns.
+
+Before stabilizing the API, pair each supported Python example with a TypeScript example: provider construction and substitution, custom LanguageModel subclass, typed/direct query return, returnsMessage, Template composition, LangFunc transforms, nested Action/Session traces, and streaming. Type-check these examples during implementation. Every divergence must be either a mechanical language mapping or a documented scope/runtime decision.
+
+## Mapping classes
+
+Prompt-based structured queries use `LfQuery<T> → Mapping<T> → LangFunc → Template`, following Python's reusable mapping pipeline. `query` is the convenience wrapper; direct `Mapping.call` returns `Message<T>`, with the typed value in `result`. `MappingExample` describes request/example input, optional output/schema/context/metadata. Few-shot examples require JSON-compatible parser inputs in JSON mode, or class instances supported by the Python codec in Python mode.
+
+`render`, `transformInput`, `postprocessResponse`, `parseResult`, and `postprocessResult` provide synchronous customization hooks; model execution remains async. Native structured output bypasses Mapping, as in Python. Mapping supports JSON and a restricted Python-style data protocol; it excludes arbitrary protocol registration, Python code evaluation, automatic repair, defaults on failure, and PyGlove contextual behavior. See [Mapping](MAPPING.md) for concrete supported behavior and streaming boundaries.
+
+## Conversation history scope
+
+Memory, ConversationHistory, and a memory namespace are out of scope for now. Applications own any cross-invocation conversation history and can supply explicit Message/ComplexMessage transcripts to models. Agent transcripts remain local to each invocation.

package/docs/GEMINI.md

@@ -0,0 +1,68 @@
+# Gemini adapter and tool loop
+
+`Gemini` is the first concrete LanguageModel adapter. `GoogleGenAI` is also exported as a subclass for users familiar with Python's Developer API naming. This implementation does not include Vertex AI authentication or its endpoint layout.
+
+```ts
+import * as lf from 'langfx.js';
+// Or: import { Gemini } from 'langfx.js/llms/gemini';
+
+const lm = new lf.llms.Gemini({ model: modelId, apiKey });
+const answer = await lf.query('Explain rainbows.', { lm });
+
+for await (const chunk of lm.stream('Explain rainbows.')) {
+  renderText(chunk.aggregated.text);
+}
+```
+
+The application supplies `modelId` and credentials. No default model, environment-variable lookup, SDK initialization, or network request occurs during import or construction. An async `apiKey(signal)` resolver, fetch-compatible `transport(url, init)`, and `baseUrl` support host authentication and compatible gateways. `baseUrl` is the API-version prefix; the adapter appends `/models/{model}:generateContent` or the SSE equivalent. Browser endpoint access still depends on CORS/auth; do not embed a shared organization credential in a public application.
+
+## Supported and tested boundary
+
+Text and image input; generated text; complete function calls and correlated results; native structured JSON requests; sampling temperature/maxTokens; tool choice; reported usage; text SSE; cancellation; HTTP error classification. Images use explicit MIME types and inline bytes/Blob or provider-readable file URIs. The adapter does not upload or download URI media for the application.
+
+The transport uses the Developer API's generateContent and streamGenerateContent methods. Structured output uses responseJsonSchema, tool declarations use parametersJsonSchema, and same-model follow-up turns retain original provider parts, including opaque signatures. [Gemini API reference](https://ai.google.dev/api/generate-content)
+
+The adapter deliberately accepts a conservative schema subset: basic types, object properties/required/additionalProperties, array items/count bounds, numeric bounds, titles/descriptions, string/number enum or const, and anyOf. Unsupported keywords fail before the request. The `$schema` dialect annotation is omitted from the wire; const is represented as a singleton enum. Local validation still runs for completed typed queries. Recursive references, formats, patterns, and other unsupported constraints can use prompt-JSON generation plus the local validator instead of native schema enforcement.
+
+Complete function calls are supported during streaming, with start/end display events and final continuation metadata. Partial function arguments, generated media, multiple candidates, and provider-side hosted tools are not implemented. Retry and local response-cache support come from LanguageModel. See [tool streaming](TOOL_STREAMING.md). They are not silently emulated. Truncated or filtered generations fail rather than being treated as successful answers. Token usage remains unknown if the provider omits required counters. Usage totals are passed through, not reconstructed from visible text.
+
+## Registered application tools
+
+```ts
+import * as lf from 'langfx.js';
+import { fromZod } from 'langfx.js/schema/zod';
+import { z } from 'zod';
+
+const add = new lf.Tool({
+  name: 'add',
+  description: 'Add two numbers.',
+  input: fromZod(z.object({ a: z.number(), b: z.number() })),
+  output: fromZod(z.number()),
+  async execute({ a, b }, session) {
+    // Pass session.signal to application I/O when needed.
+    return a + b;
+  },
+});
+
+const session = new lf.Session({ lm });
+try {
+  const answer = await new lf.Agent({
+    prompt: 'What is 2 + 3?',
+    tools: [add],
+    limits: { maxSteps: 4, maxToolCalls: 2, maxExecutionTime: 30 },
+  }).invoke(session);
+  console.log(answer, session.allActions);
+} finally {
+  await session.dispose();
+}
+```
+
+An Agent is an Action with prompt/configuration fields. Limits default to 8 model requests, 12 tool calls, and 60 seconds per invocation. Explicit shorter run/parent deadlines still apply. Each concurrent invocation owns its transcript, call IDs, and counters. These are loop-local limits, not a global allowance for arbitrary nested agents or model calls inside app tools. Exact token/cost budgeting remains future work.
+
+Before any batch executes, every call must resolve to a registered tool, have a unique ID, pass input validation and the optional `allowTool(call, session)` policy, and fit the remaining call budget. At least one model step must remain to consume the results. Tools execute sequentially as named trace actions. Output validation and JSON serialization happen before adding the result message. Errors/denials stop the run; side effects are never automatically replayed or rolled back. A host policy may await its own approval UI; the library does not supply that UI.
+
+## Verification
+
+`npm run example:agent` executes the actual Gemini encoder/decoder and a local tool against deterministic HTTP response fixtures. `npm run serve:example` runs the same loop in a browser and module worker. Both Safari checks passed. The tests also cover signatures, missing/provider call IDs, multipart tool results, UTF-8/SSE fragmentation, abort/reader cleanup, error paths, and loop isolation/budgets.
+
+The seven-request live smoke suite passed on `gemini-3.7-flash` on 2026-09-16, including JSON/Python queries, text/Python streaming, and a streamed local-tool round trip. See [live testing](LIVE_TESTING.md). This verifies those cases in Node; browser CORS, media, native structured output, and other model configurations remain unverified.