@prompty/core 2.0.0-alpha.3 → 2.0.0-alpha.4

package/dist/index.d.ts

@@ -788,7 +788,7 @@ declare class Model {
      */
     id: string;
     /**
-     * The provider of the model (e.g., 'openai', 'azure', 'anthropic')
+     * The provider of the model (e.g., 'openai', 'foundry', 'anthropic')
      */
     provider?: string | undefined;
     /**
@@ -1088,7 +1088,7 @@ declare class ObjectProperty extends Property {
  * Template format definition
  *
  */
-declare class Format {
+declare class FormatConfig {
     /**
      * The shorthand property name for this type, if any.
      */
@@ -1106,56 +1106,56 @@ declare class Format {
      */
     options?: Record<string, unknown> | undefined;
     /**
-     * Initializes a new instance of Format.
+     * Initializes a new instance of FormatConfig.
      */
-    constructor(init?: Partial<Format>);
+    constructor(init?: Partial<FormatConfig>);
     /**
-     * Load a Format instance from a dictionary.
+     * Load a FormatConfig instance from a dictionary.
      * @param data - The dictionary containing the data.
      * @param context - Optional context with pre/post processing callbacks.
-     * @returns The loaded Format instance.
+     * @returns The loaded FormatConfig instance.
      */
-    static load(data: Record<string, unknown>, context?: LoadContext): Format;
+    static load(data: Record<string, unknown>, context?: LoadContext): FormatConfig;
     /**
-     * Save the Format instance to a dictionary.
+     * Save the FormatConfig instance to a dictionary.
      * @param context - Optional context with pre/post processing callbacks.
      * @returns The dictionary representation of this instance.
      */
     save(context?: SaveContext): Record<string, unknown>;
     /**
-     * Convert the Format instance to a YAML string.
+     * Convert the FormatConfig instance to a YAML string.
      * @param context - Optional context with pre/post processing callbacks.
      * @returns The YAML string representation of this instance.
      */
     toYaml(context?: SaveContext): string;
     /**
-     * Convert the Format instance to a JSON string.
+     * Convert the FormatConfig instance to a JSON string.
      * @param context - Optional context with pre/post processing callbacks.
      * @param indent - Number of spaces for indentation. Defaults to 2.
      * @returns The JSON string representation of this instance.
      */
     toJson(context?: SaveContext, indent?: number): string;
     /**
-     * Load a Format instance from a JSON string.
+     * Load a FormatConfig instance from a JSON string.
      * @param json - The JSON string to parse.
      * @param context - Optional context with pre/post processing callbacks.
-     * @returns The loaded Format instance.
+     * @returns The loaded FormatConfig instance.
      */
-    static fromJson(json: string, context?: LoadContext): Format;
+    static fromJson(json: string, context?: LoadContext): FormatConfig;
     /**
-     * Load a Format instance from a YAML string.
+     * Load a FormatConfig instance from a YAML string.
      * @param yaml - The YAML string to parse.
      * @param context - Optional context with pre/post processing callbacks.
-     * @returns The loaded Format instance.
+     * @returns The loaded FormatConfig instance.
      */
-    static fromYaml(yaml: string, context?: LoadContext): Format;
+    static fromYaml(yaml: string, context?: LoadContext): FormatConfig;
 }
 
 /**
  * Template parser definition
  *
  */
-declare class Parser$1 {
+declare class ParserConfig {
     /**
      * The shorthand property name for this type, if any.
      */
@@ -1169,49 +1169,49 @@ declare class Parser$1 {
      */
     options?: Record<string, unknown> | undefined;
     /**
-     * Initializes a new instance of Parser.
+     * Initializes a new instance of ParserConfig.
      */
-    constructor(init?: Partial<Parser$1>);
+    constructor(init?: Partial<ParserConfig>);
     /**
-     * Load a Parser instance from a dictionary.
+     * Load a ParserConfig instance from a dictionary.
      * @param data - The dictionary containing the data.
      * @param context - Optional context with pre/post processing callbacks.
-     * @returns The loaded Parser instance.
+     * @returns The loaded ParserConfig instance.
      */
-    static load(data: Record<string, unknown>, context?: LoadContext): Parser$1;
+    static load(data: Record<string, unknown>, context?: LoadContext): ParserConfig;
     /**
-     * Save the Parser instance to a dictionary.
+     * Save the ParserConfig instance to a dictionary.
      * @param context - Optional context with pre/post processing callbacks.
      * @returns The dictionary representation of this instance.
      */
     save(context?: SaveContext): Record<string, unknown>;
     /**
-     * Convert the Parser instance to a YAML string.
+     * Convert the ParserConfig instance to a YAML string.
      * @param context - Optional context with pre/post processing callbacks.
      * @returns The YAML string representation of this instance.
      */
     toYaml(context?: SaveContext): string;
     /**
-     * Convert the Parser instance to a JSON string.
+     * Convert the ParserConfig instance to a JSON string.
      * @param context - Optional context with pre/post processing callbacks.
      * @param indent - Number of spaces for indentation. Defaults to 2.
      * @returns The JSON string representation of this instance.
      */
     toJson(context?: SaveContext, indent?: number): string;
     /**
-     * Load a Parser instance from a JSON string.
+     * Load a ParserConfig instance from a JSON string.
      * @param json - The JSON string to parse.
      * @param context - Optional context with pre/post processing callbacks.
-     * @returns The loaded Parser instance.
+     * @returns The loaded ParserConfig instance.
      */
-    static fromJson(json: string, context?: LoadContext): Parser$1;
+    static fromJson(json: string, context?: LoadContext): ParserConfig;
     /**
-     * Load a Parser instance from a YAML string.
+     * Load a ParserConfig instance from a YAML string.
      * @param yaml - The YAML string to parse.
      * @param context - Optional context with pre/post processing callbacks.
-     * @returns The loaded Parser instance.
+     * @returns The loaded ParserConfig instance.
      */
-    static fromYaml(yaml: string, context?: LoadContext): Parser$1;
+    static fromYaml(yaml: string, context?: LoadContext): ParserConfig;
 }
 
 /**
@@ -1233,11 +1233,11 @@ declare class Template {
     /**
      * Template rendering engine used for slot filling prompts (e.g., mustache, jinja2)
      */
-    format: Format;
+    format: FormatConfig;
     /**
      * Parser used to process the rendered template into API-compatible format
      */
-    parser: Parser$1;
+    parser: ParserConfig;
     /**
      * Initializes a new instance of Template.
      */
@@ -1801,6 +1801,75 @@ declare class OpenApiTool extends Tool {
      */
     static fromYaml(yaml: string, context?: LoadContext): OpenApiTool;
 }
+/**
+ * A tool that references another .prompty file to be invoked as a tool.
+ *
+ * In `single` mode, the child prompty is executed with a single LLM call.
+ * In `agentic` mode, the child prompty runs a full agent loop with its own tools.
+ *
+ */
+declare class PromptyTool extends Tool {
+    /**
+     * The shorthand property name for this type, if any.
+     */
+    static readonly shorthandProperty: string | undefined;
+    /**
+     * The kind identifier for prompty tools
+     */
+    kind: string;
+    /**
+     * Path to the child .prompty file, relative to the parent
+     */
+    path: string;
+    /**
+     * Execution mode: 'single' for one LLM call, 'agentic' for full agent loop
+     */
+    mode: string;
+    /**
+     * Initializes a new instance of PromptyTool.
+     */
+    constructor(init?: Partial<PromptyTool>);
+    /**
+     * Load a PromptyTool instance from a dictionary.
+     * @param data - The dictionary containing the data.
+     * @param context - Optional context with pre/post processing callbacks.
+     * @returns The loaded PromptyTool instance.
+     */
+    static load(data: Record<string, unknown>, context?: LoadContext): PromptyTool;
+    /**
+     * Save the PromptyTool instance to a dictionary.
+     * @param context - Optional context with pre/post processing callbacks.
+     * @returns The dictionary representation of this instance.
+     */
+    save(context?: SaveContext): Record<string, unknown>;
+    /**
+     * Convert the PromptyTool instance to a YAML string.
+     * @param context - Optional context with pre/post processing callbacks.
+     * @returns The YAML string representation of this instance.
+     */
+    toYaml(context?: SaveContext): string;
+    /**
+     * Convert the PromptyTool instance to a JSON string.
+     * @param context - Optional context with pre/post processing callbacks.
+     * @param indent - Number of spaces for indentation. Defaults to 2.
+     * @returns The JSON string representation of this instance.
+     */
+    toJson(context?: SaveContext, indent?: number): string;
+    /**
+     * Load a PromptyTool instance from a JSON string.
+     * @param json - The JSON string to parse.
+     * @param context - Optional context with pre/post processing callbacks.
+     * @returns The loaded PromptyTool instance.
+     */
+    static fromJson(json: string, context?: LoadContext): PromptyTool;
+    /**
+     * Load a PromptyTool instance from a YAML string.
+     * @param yaml - The YAML string to parse.
+     * @param context - Optional context with pre/post processing callbacks.
+     * @returns The loaded PromptyTool instance.
+     */
+    static fromYaml(yaml: string, context?: LoadContext): PromptyTool;
+}
 
 /**
  * A Prompty is a markdown file format for LLM prompts. The frontmatter defines
@@ -2125,6 +2194,13 @@ declare function run(agent: Prompty, messages: Message[], options?: {
 declare function execute(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: {
     raw?: boolean;
 }): Promise<unknown>;
+/**
+ * Resolve tool bindings: inject values from parentInputs into tool arguments.
+ *
+ * For each binding on the matched tool, looks up `binding.input` in parentInputs
+ * and sets `args[binding.name]` to that value. Returns a new args object.
+ */
+declare function resolveBindings(agent: Prompty, toolName: string, args: Record<string, unknown>, parentInputs?: Record<string, unknown>): Record<string, unknown>;
 /**
  * Run a prompt with automatic tool-call execution loop.
  */
@@ -2162,9 +2238,11 @@ declare class MustacheRenderer implements Renderer {
 /**
  * Prompty chat parser — splits rendered text into abstract messages.
  *
- * Recognizes role markers (`system:`, `user:`, `assistant:`, `developer:`)
- * and inline markdown images. Supports nonce-based sanitization when
- * `Format.strict` is enabled.
+ * Recognizes role markers (`system:`, `user:`, `assistant:`, `developer:`).
+ * Supports nonce-based sanitization when `FormatConfig.strict` is enabled.
+ *
+ * Images should be passed via `kind: image` input properties rather than
+ * inline markdown syntax. Inline `![alt](url)` is preserved as literal text.
  *
  * @module
  */
@@ -2176,8 +2254,6 @@ declare class PromptyChatParser implements Parser {
     private parseMessages;
     private buildMessage;
     private parseAttrs;
-    private parseContent;
-    private resolveImage;
 }
 
 /**
@@ -2324,4 +2400,74 @@ declare class PromptyTracer {
     private sanitizeName;
 }
 
-export { Prompty as AgentDefinition, AnonymousConnection, ApiKeyConnection, ArrayProperty, type AudioPart, Binding, Connection, type ContentPart, CustomTool, type Executor, type FilePart, Format, FoundryConnection, FunctionTool, type ImagePart, InvokerError, LoadContext, McpApprovalMode, McpTool, Message, Model, ModelOptions, MustacheRenderer, NunjucksRenderer, OAuthConnection, ObjectProperty, OpenApiTool, type Parser, type Processor, Prompty as PromptAgent, Prompty, PromptyChatParser, PromptyStream, PromptyTracer, Property, RICH_KINDS, ROLES, ReferenceConnection, RemoteConnection, type Renderer, type Role, SaveContext, Parser$1 as SchemaParser, type SpanEmitter, Template, type TextPart, ThreadMarker, Tool, type ToolCall, Tracer, type TracerBackend, type TracerFactory, clearCache, clearConnections, consoleTracer, dictContentToPart, dictToMessage, execute, executeAgent, getConnection, getExecutor, getParser, getProcessor, getRenderer, load, parse, prepare, process, registerConnection, registerExecutor, registerParser, registerProcessor, registerRenderer, render, run, runAgent, sanitizeValue, text, textMessage, toSerializable, trace, traceMethod, traceSpan, validateInputs };
+/**
+ * OpenTelemetry trace backend for Prompty.
+ *
+ * Plugs into the Tracer registry and emits OTel spans with structured
+ * attributes. Requires `@opentelemetry/api` — install as a peer dependency.
+ *
+ * Usage:
+ * ```typescript
+ * import { Tracer } from "@prompty/core";
+ * import { otelTracer } from "@prompty/core/tracing/otel";
+ * import * as otelApi from "@opentelemetry/api";
+ *
+ * Tracer.add("otel", otelTracer(otelApi));
+ * // or with custom tracer name:
+ * Tracer.add("otel", otelTracer(otelApi, { tracerName: "my.service" }));
+ * ```
+ *
+ * @module
+ */
+
+/** The subset of `@opentelemetry/api` needed by this module. */
+interface OtelApi {
+    trace: {
+        getTracer(name: string): {
+            startSpan(name: string): OtelSpan;
+        };
+        setSpan(context: unknown, span: OtelSpan): unknown;
+    };
+    context: {
+        active(): unknown;
+        with<T>(context: unknown, fn: () => T): T;
+    };
+    SpanStatusCode: {
+        OK: number;
+        ERROR: number;
+    };
+}
+interface OtelSpan {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    recordException(exception: Error): void;
+    end(): void;
+}
+/** Options for {@link otelTracer}. */
+interface OtelTracerOptions {
+    /** OTel tracer name. Defaults to `"prompty"`. */
+    tracerName?: string;
+}
+/**
+ * Create an OTel trace backend compatible with `Tracer.add()`.
+ *
+ * Each call to the returned factory starts a new OTel span named after the
+ * Prompty pipeline step. The backend receives `(key, value)` events and
+ * sets them as span attributes. On `__end__`, the span is ended.
+ *
+ * Special handling:
+ * - `error` key sets `StatusCode.ERROR` and records the exception.
+ * - `__end__` key ends the span.
+ * - All other values are serialized and expanded into dotted attributes.
+ *
+ * @param api - The `@opentelemetry/api` module. Pass `require("@opentelemetry/api")`
+ *   or the result of `await import("@opentelemetry/api")`.
+ * @param options - Optional configuration.
+ * @returns A `TracerFactory` suitable for `Tracer.add()`.
+ */
+declare function otelTracer(api: OtelApi, options?: OtelTracerOptions): TracerFactory;
+
+export { Prompty as AgentDefinition, AnonymousConnection, ApiKeyConnection, ArrayProperty, type AudioPart, Binding, Connection, type ContentPart, CustomTool, type Executor, type FilePart, FormatConfig, FoundryConnection, FunctionTool, type ImagePart, InvokerError, LoadContext, McpApprovalMode, McpTool, Message, Model, ModelOptions, MustacheRenderer, NunjucksRenderer, OAuthConnection, ObjectProperty, OpenApiTool, type OtelApi, type OtelTracerOptions, type Parser, ParserConfig, type Processor, Prompty as PromptAgent, Prompty, PromptyChatParser, PromptyStream, PromptyTool, PromptyTracer, Property, RICH_KINDS, ROLES, ReferenceConnection, RemoteConnection, type Renderer, type Role, SaveContext, type SpanEmitter, Template, type TextPart, ThreadMarker, Tool, type ToolCall, Tracer, type TracerBackend, type TracerFactory, clearCache, clearConnections, consoleTracer, dictContentToPart, dictToMessage, execute, executeAgent, getConnection, getExecutor, getParser, getProcessor, getRenderer, load, otelTracer, parse, prepare, process, registerConnection, registerExecutor, registerParser, registerProcessor, registerRenderer, render, resolveBindings, run, runAgent, sanitizeValue, text, textMessage, toSerializable, trace, traceMethod, traceSpan, validateInputs };