@aid-framework/runtime 0.0.0-stage → 0.1.39

package/dist/tools.js

@@ -0,0 +1,201 @@
+/**
+ * Tool dispatch with schema validation.
+ *
+ * The one place this module cannot mirror the reference runtime is the seam itself:
+ * Python infers a tool's JSON schema from `inspect.signature` and a docstring, and
+ * JavaScript has neither. So the schema is declared explicitly and validated against
+ * the tool set here instead -- the runtime's job is to refuse a *wrong* invocation,
+ * and that job is identical either way.
+ *
+ * The validator implements a deliberate subset of JSON Schema: `type`, `required`
+ * and `additionalProperties: false`. That subset is documented rather than silently
+ * partial, and an unknown `type` value is treated as unconstrained instead of
+ * failing, because a schema written for a newer draft must not reject every call.
+ */
+import { ConfigurationError, ToolExecutionError, ToolNotFoundError } from './errors.js';
+import { dumpsSorted, repr } from './internal/json.js';
+import { ToolDefinition, ToolResult } from './types.js';
+/** A registered tool: its public definition plus the code behind it. */
+export class Tool {
+    definition_;
+    handler;
+    constructor(init) {
+        this.definition_ = new ToolDefinition({
+            name: init.name,
+            description: init.description,
+            parameters: (init.parameters ?? { type: 'object', properties: {} }),
+        });
+        this.handler = init.handler;
+        this.checkSchema();
+    }
+    /**
+     * Declare a tool.
+     *
+     * `parameters` is required where Python would infer it. A schema whose `required`
+     * list names a property it does not define is a wiring mistake, and it is reported
+     * here rather than at the first call: that is the same failure Python reports as
+     * "not accepted by the handler", just discovered from the other direction.
+     */
+    static of(init) {
+        return new Tool(init);
+    }
+    get name() {
+        return this.definition_.name;
+    }
+    get definition() {
+        return this.definition_;
+    }
+    checkSchema() {
+        const schema = this.definition_.parameters;
+        for (const property of schema.required ?? []) {
+            if (schema.properties === undefined || !(property in schema.properties)) {
+                throw new ConfigurationError(`tool ${repr(this.name)} declares required parameter ${repr(property)} but its schema does not define it, so it is not accepted by the handler`);
+            }
+        }
+    }
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function typeMatches(expected, value) {
+    const names = Array.isArray(expected) ? expected : [expected];
+    return names.some((name) => singleTypeMatches(name, value));
+}
+function singleTypeMatches(expected, value) {
+    if (typeof expected !== 'string')
+        return true;
+    switch (expected) {
+        case 'string':
+            return typeof value === 'string';
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'number':
+            // A boolean is not a number, even though `true + 0` is 1.
+            return typeof value === 'number';
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'object':
+            return isObject(value);
+        case 'array':
+            return Array.isArray(value);
+        case 'null':
+            return value === null;
+        default:
+            // An unknown type keyword is not a claim we can check, so it matches.
+            return true;
+    }
+}
+/**
+ * Validate `args` against `schema`, returning every problem rather than the first.
+ *
+ * Returning all problems is what makes a single repair turn enough: a model told
+ * about one bad field per round trips once per field.
+ */
+export function validateArguments(schema, args) {
+    if (!isObject(args))
+        return ['arguments must be an object'];
+    const problems = [];
+    const properties = schema.properties ?? {};
+    for (const name of schema.required ?? []) {
+        if (!(name in args))
+            problems.push(`missing required property '${name}'`);
+    }
+    if (schema.additionalProperties === false) {
+        for (const name of Object.keys(args)) {
+            if (!(name in properties))
+                problems.push(`unexpected property '${name}'`);
+        }
+    }
+    for (const [name, rule] of Object.entries(properties)) {
+        if (!(name in args))
+            continue;
+        const value = args[name];
+        if (value === null || value === undefined)
+            continue;
+        if (rule.type !== undefined && !typeMatches(rule.type, value)) {
+            problems.push(`property '${name}' must be of type ${String(rule.type)}`);
+        }
+    }
+    return problems;
+}
+/**
+ * A set of tools, and the dispatcher for them.
+ *
+ * `strict` decides what a crashing handler means. The default is to hand the model
+ * an error result so it can react; strict mode rethrows, because a caller that has
+ * already decided a crash is a bug should not have to inspect a result to find out.
+ */
+export class ToolExecutor {
+    _tools = new Map();
+    _strict;
+    _limiter;
+    constructor(tools = [], options = {}) {
+        this._strict = options.strict ?? false;
+        this._limiter = options.limiter;
+        for (const tool of tools)
+            this.register(tool);
+    }
+    /** The registered names, sorted. */
+    names() {
+        return [...this._tools.keys()].sort();
+    }
+    /** Add a tool. A duplicate name replaces, because a registry is a map. */
+    register(tool) {
+        this._tools.set(tool.name, tool);
+    }
+    /** One tool's public definition. */
+    definition(name) {
+        return this.require(name).definition;
+    }
+    /** Every registered definition, ordered by name. */
+    definitions() {
+        return this.names().map((name) => this.require(name).definition);
+    }
+    /** Whether a name is registered. */
+    has(name) {
+        return this._tools.has(name);
+    }
+    /**
+     * Run one call.
+     *
+     * An unknown tool throws: that is a wiring error in generated code, not something
+     * a model can fix by trying again with the same name.
+     */
+    async execute(call) {
+        // When a limiter is shared with the gateway, the call holds one slot for its whole
+        // duration, released on success, handler error, or cancellation.
+        if (this._limiter === undefined)
+            return this.dispatch(call);
+        return this._limiter.run(() => this.dispatch(call));
+    }
+    async dispatch(call) {
+        const tool = this.require(call.name);
+        const problems = validateArguments(tool.definition.parameters, call.args);
+        if (problems.length > 0) {
+            return ToolResult.fromError(call, `invalid arguments: ${problems.join('; ')} -- ${dumpsSorted(call.args)}`);
+        }
+        try {
+            return ToolResult.fromValue(call, await tool.handler(call.args));
+        }
+        catch (error) {
+            const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+            if (this._strict)
+                throw new ToolExecutionError(detail);
+            return ToolResult.fromError(call, detail);
+        }
+    }
+    /** Run calls in order. Sequential on purpose: a tool set is a transcript, not a race. */
+    async executeAll(calls) {
+        const results = [];
+        for (const call of calls)
+            results.push(await this.execute(call));
+        return results;
+    }
+    require(name) {
+        const tool = this._tools.get(name);
+        if (tool === undefined)
+            throw new ToolNotFoundError(name, this.names());
+        return tool;
+    }
+}
+//# 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/dist/tracing.d.ts

@@ -0,0 +1,104 @@
+/**
+ * OpenTelemetry GenAI tracing.
+ *
+ * The attribute spellings are the GenAI semantic conventions, not house names, so a
+ * span this runtime emits lands in an existing dashboard without a translation
+ * layer. The three `aid.*` attributes are the additions the conventions have no
+ * opinion about: which alias was asked for, what it cost, and how many candidates
+ * were tried before one answered.
+ *
+ * The tracer is resolved from the global provider, so an application that never
+ * configures one gets a no-op tracer and no cost. That matters: a runtime that
+ * demanded a tracer would make tracing a precondition for calling a model.
+ */
+import { type Attributes, type Span, trace } from '@opentelemetry/api';
+/** The operation name the chat completion span carries. */
+export declare const GEN_AI_OPERATION_CHAT = "chat";
+/** Semantic-convention attribute names, keyed by the option that sets them. */
+export declare const ATTRIBUTES: {
+    readonly system: 'gen_ai.system';
+    readonly operation: 'gen_ai.operation.name';
+    readonly requestModel: 'gen_ai.request.model';
+    readonly requestTemperature: 'gen_ai.request.temperature';
+    readonly requestMaxTokens: 'gen_ai.request.max_tokens';
+    readonly responseModel: 'gen_ai.response.model';
+    readonly responseFinishReasons: 'gen_ai.response.finish_reasons';
+    readonly inputTokens: 'gen_ai.usage.input_tokens';
+    readonly outputTokens: 'gen_ai.usage.output_tokens';
+    readonly alias: 'aid.model.alias';
+    readonly costUsd: 'aid.cost.usd';
+    readonly attempts: 'aid.gateway.attempts';
+    readonly toolNames: 'aid.tool.names';
+};
+/** Everything a chat span may record. Unset members are omitted entirely. */
+export interface LlmSpanOptions {
+    readonly operation?: string;
+    readonly model: string;
+    readonly system?: string;
+    readonly requestTemperature?: number;
+    readonly requestMaxTokens?: number;
+    readonly responseModel?: string;
+    readonly responseFinishReasons?: readonly string[];
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly alias?: string;
+    readonly costUsd?: number;
+    readonly attempts?: number;
+    readonly toolNames?: readonly string[];
+    readonly tracerName?: string;
+}
+/** The default tracer name, matching the reference runtime. */
+export declare const DEFAULT_TRACER_NAME = "aid_runtime";
+/** Resolve a tracer from the global provider. */
+export declare function getTracer(name?: string): ReturnType<typeof trace.getTracer>;
+/**
+ * Turn span options into OTel attributes.
+ *
+ * An unset option contributes no key at all rather than a defaulted zero: a span
+ * that reports `gen_ai.usage.input_tokens = 0` for a call whose usage was never
+ * measured is a lie a dashboard will happily average.
+ */
+export declare function spanAttributes(options: LlmSpanOptions): Attributes;
+/** The name a chat span carries: `"{operation} {model}"`. */
+export declare function spanName(options: LlmSpanOptions): string;
+/** A started chat span plus the operations that end it. */
+export interface LlmSpanHandle {
+    readonly span: Span;
+    /** Record usage on an already-started span. */
+    recordUsage(inputTokens: number, outputTokens: number): void;
+    /** Record cost. Does not touch the alias attribute. */
+    recordCost(costUsd: number): void;
+    /** Record an exception once, and mark the span failed. */
+    recordException(error: unknown): void;
+    /** End the span. Idempotent. */
+    end(): void;
+}
+/** Start a chat span with the standard attributes applied. */
+export declare function llmSpan(options: LlmSpanOptions): LlmSpanHandle;
+/**
+ * Run `body` inside a chat span, recording an exception and marking it failed on
+ * throw.
+ *
+ * Automatic exception recording is off (`record_exception: false` /
+ * `set_status_on_exception: false` in the reference runtime) so the exception is
+ * recorded exactly once, by this function, rather than once by the SDK and once by
+ * the caller's wrapper.
+ */
+export declare function withLlmSpan<T>(options: LlmSpanOptions, body: (handle: LlmSpanHandle) => Promise<T>): Promise<T>;
+/** Record usage on an existing span. */
+export declare function recordUsage(span: Span, inputTokens: number, outputTokens: number): void;
+/** Record cost on an existing span. Deliberately leaves the alias attribute alone. */
+export declare function recordCost(span: Span, costUsd: number): void;
+/**
+ * Record an exception once and mark the span failed.
+ *
+ * `error` is `unknown` because a caught value in TypeScript is not guaranteed to be
+ * an `Error`, and a runtime that assumed otherwise would throw while reporting a
+ * failure.
+ */
+export declare function recordException(span: Span, error: unknown): void;
+/** Build an attribute bag from arbitrary named values, passing unknown keys through. */
+export declare function aidAttributes(values: Readonly<Record<string, string | number | boolean>>): {
+    [key: string]: string | number | boolean;
+};
+//# sourceMappingURL=tracing.d.ts.map

package/dist/tracing.d.ts.map

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

package/dist/tracing.js

@@ -0,0 +1,155 @@
+/**
+ * OpenTelemetry GenAI tracing.
+ *
+ * The attribute spellings are the GenAI semantic conventions, not house names, so a
+ * span this runtime emits lands in an existing dashboard without a translation
+ * layer. The three `aid.*` attributes are the additions the conventions have no
+ * opinion about: which alias was asked for, what it cost, and how many candidates
+ * were tried before one answered.
+ *
+ * The tracer is resolved from the global provider, so an application that never
+ * configures one gets a no-op tracer and no cost. That matters: a runtime that
+ * demanded a tracer would make tracing a precondition for calling a model.
+ */
+import { SpanStatusCode, trace } from '@opentelemetry/api';
+/** The operation name the chat completion span carries. */
+export const GEN_AI_OPERATION_CHAT = 'chat';
+/** Semantic-convention attribute names, keyed by the option that sets them. */
+export const ATTRIBUTES = {
+    system: 'gen_ai.system',
+    operation: 'gen_ai.operation.name',
+    requestModel: 'gen_ai.request.model',
+    requestTemperature: 'gen_ai.request.temperature',
+    requestMaxTokens: 'gen_ai.request.max_tokens',
+    responseModel: 'gen_ai.response.model',
+    responseFinishReasons: 'gen_ai.response.finish_reasons',
+    inputTokens: 'gen_ai.usage.input_tokens',
+    outputTokens: 'gen_ai.usage.output_tokens',
+    alias: 'aid.model.alias',
+    costUsd: 'aid.cost.usd',
+    attempts: 'aid.gateway.attempts',
+    toolNames: 'aid.tool.names',
+};
+/** The default tracer name, matching the reference runtime. */
+export const DEFAULT_TRACER_NAME = 'aid_runtime';
+/** Resolve a tracer from the global provider. */
+export function getTracer(name = DEFAULT_TRACER_NAME) {
+    return trace.getTracer(name);
+}
+/**
+ * Turn span options into OTel attributes.
+ *
+ * An unset option contributes no key at all rather than a defaulted zero: a span
+ * that reports `gen_ai.usage.input_tokens = 0` for a call whose usage was never
+ * measured is a lie a dashboard will happily average.
+ */
+export function spanAttributes(options) {
+    const attributes = {};
+    const operation = options.operation ?? GEN_AI_OPERATION_CHAT;
+    attributes[ATTRIBUTES.operation] = operation;
+    attributes[ATTRIBUTES.requestModel] = options.model;
+    if (options.system !== undefined)
+        attributes[ATTRIBUTES.system] = options.system;
+    if (options.requestTemperature !== undefined) {
+        attributes[ATTRIBUTES.requestTemperature] = options.requestTemperature;
+    }
+    if (options.requestMaxTokens !== undefined) {
+        attributes[ATTRIBUTES.requestMaxTokens] = options.requestMaxTokens;
+    }
+    if (options.responseModel !== undefined) {
+        attributes[ATTRIBUTES.responseModel] = options.responseModel;
+    }
+    if (options.responseFinishReasons !== undefined) {
+        attributes[ATTRIBUTES.responseFinishReasons] = [...options.responseFinishReasons];
+    }
+    if (options.inputTokens !== undefined)
+        attributes[ATTRIBUTES.inputTokens] = options.inputTokens;
+    if (options.outputTokens !== undefined)
+        attributes[ATTRIBUTES.outputTokens] = options.outputTokens;
+    if (options.alias !== undefined)
+        attributes[ATTRIBUTES.alias] = options.alias;
+    if (options.costUsd !== undefined)
+        attributes[ATTRIBUTES.costUsd] = options.costUsd;
+    if (options.attempts !== undefined)
+        attributes[ATTRIBUTES.attempts] = options.attempts;
+    if (options.toolNames !== undefined)
+        attributes[ATTRIBUTES.toolNames] = [...options.toolNames];
+    return attributes;
+}
+/** The name a chat span carries: `"{operation} {model}"`. */
+export function spanName(options) {
+    return `${options.operation ?? GEN_AI_OPERATION_CHAT} ${options.model}`;
+}
+/** Start a chat span with the standard attributes applied. */
+export function llmSpan(options) {
+    const tracer = getTracer(options.tracerName ?? DEFAULT_TRACER_NAME);
+    const span = tracer.startSpan(spanName(options), { attributes: spanAttributes(options) });
+    let ended = false;
+    return {
+        span,
+        recordUsage(inputTokens, outputTokens) {
+            span.setAttribute(ATTRIBUTES.inputTokens, inputTokens);
+            span.setAttribute(ATTRIBUTES.outputTokens, outputTokens);
+        },
+        recordCost(costUsd) {
+            span.setAttribute(ATTRIBUTES.costUsd, costUsd);
+        },
+        recordException(error) {
+            recordException(span, error);
+        },
+        end() {
+            if (ended)
+                return;
+            ended = true;
+            span.end();
+        },
+    };
+}
+/**
+ * Run `body` inside a chat span, recording an exception and marking it failed on
+ * throw.
+ *
+ * Automatic exception recording is off (`record_exception: false` /
+ * `set_status_on_exception: false` in the reference runtime) so the exception is
+ * recorded exactly once, by this function, rather than once by the SDK and once by
+ * the caller's wrapper.
+ */
+export async function withLlmSpan(options, body) {
+    const handle = llmSpan(options);
+    try {
+        return await body(handle);
+    }
+    catch (error) {
+        handle.recordException(error);
+        throw error;
+    }
+    finally {
+        handle.end();
+    }
+}
+/** Record usage on an existing span. */
+export function recordUsage(span, inputTokens, outputTokens) {
+    span.setAttribute(ATTRIBUTES.inputTokens, inputTokens);
+    span.setAttribute(ATTRIBUTES.outputTokens, outputTokens);
+}
+/** Record cost on an existing span. Deliberately leaves the alias attribute alone. */
+export function recordCost(span, costUsd) {
+    span.setAttribute(ATTRIBUTES.costUsd, costUsd);
+}
+/**
+ * Record an exception once and mark the span failed.
+ *
+ * `error` is `unknown` because a caught value in TypeScript is not guaranteed to be
+ * an `Error`, and a runtime that assumed otherwise would throw while reporting a
+ * failure.
+ */
+export function recordException(span, error) {
+    const asError = error instanceof Error ? error : new Error(typeof error === 'string' ? error : String(error));
+    span.recordException(asError);
+    span.setStatus({ code: SpanStatusCode.ERROR, message: asError.message });
+}
+/** Build an attribute bag from arbitrary named values, passing unknown keys through. */
+export function aidAttributes(values) {
+    return { ...values };
+}
+//# sourceMappingURL=tracing.js.map

package/dist/tracing.js.map

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