@fastpaca/cria 0.0.1 → 1.1.3

package/dist/openai/index.d.ts

@@ -0,0 +1,73 @@
+import type OpenAI from "openai";
+import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";
+import type { ResponseInputItem } from "openai/resources/responses/responses";
+import type { CompletionRequest, CompletionResult, ModelProvider, PromptChildren, PromptElement, PromptRenderer, Tokenizer } from "../types";
+/**
+ * Renderer that outputs ChatCompletionMessageParam[] for the OpenAI Chat Completions API.
+ * Pass this to render() to get messages compatible with client.chat.completions.create().
+ *
+ * @example
+ * ```ts
+ * import { render } from "@fastpaca/cria";
+ * import { chatCompletions } from "@fastpaca/cria/openai";
+ *
+ * const messages = await render(prompt, { tokenizer, budget, renderer: chatCompletions });
+ * const response = await openai.chat.completions.create({ model: "gpt-4", messages });
+ * ```
+ */
+export declare const chatCompletions: PromptRenderer<ChatCompletionMessageParam[]>;
+/**
+ * Renderer that outputs ResponseInputItem[] for the OpenAI Responses API.
+ * Use this with reasoning models that support native reasoning.
+ *
+ * @example
+ * ```ts
+ * import { render } from "@fastpaca/cria";
+ * import { responses } from "@fastpaca/cria/openai";
+ *
+ * const input = await render(prompt, { tokenizer, budget, renderer: responses });
+ * const response = await openai.responses.create({ model: "o3", input });
+ * ```
+ */
+export declare const responses: PromptRenderer<ResponseInputItem[]>;
+interface OpenAIProviderProps {
+    /** OpenAI client instance */
+    client: OpenAI;
+    /** Model to use (e.g. "gpt-4o", "gpt-4o-mini") */
+    model: string;
+    /** Optional tokenizer to use for budgeting; defaults to a tiktoken-based tokenizer */
+    tokenizer?: Tokenizer;
+    /** Child components that will have access to this provider */
+    children?: PromptChildren;
+}
+/**
+ * ModelProvider implementation that wraps an OpenAI client.
+ * Use this with the DSL's `.provider()` method.
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from "openai";
+ * import { cria } from "@fastpaca/cria";
+ * import { Provider } from "@fastpaca/cria/openai";
+ *
+ * const client = new OpenAI();
+ * const provider = new Provider(client, "gpt-4o");
+ *
+ * const prompt = cria
+ *   .prompt()
+ *   .provider(provider, (p) =>
+ *     p.summary(content, { id: "summary", store })
+ *   )
+ *   .build();
+ * ```
+ */
+export declare class Provider implements ModelProvider {
+    readonly name = "openai";
+    private readonly client;
+    private readonly model;
+    constructor(client: OpenAI, model: string);
+    completion(request: CompletionRequest): Promise<CompletionResult>;
+}
+export declare function OpenAIProvider({ client, model, tokenizer, children, }: OpenAIProviderProps): PromptElement;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/openai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openai/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAEV,0BAA0B,EAK3B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAEV,iBAAiB,EAElB,MAAM,sCAAsC,CAAC;AAY9C,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,aAAa,EACb,cAAc,EACd,SAAS,EACV,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,0BAA0B,EAAE,CAKxE,CAAC;AAiHF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,EAAE,cAAc,CAAC,iBAAiB,EAAE,CAKzD,CAAC;AA4IF,UAAU,mBAAmB;IAC3B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AA8BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,QAAS,YAAW,aAAa;IAC5C,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAKnC,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAmBxE;AAED,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EACN,KAAK,EACL,SAAS,EACT,QAAa,GACd,EAAE,mBAAmB,GAAG,aAAa,CA8BrC"}

package/dist/openai/index.js

@@ -0,0 +1,306 @@
+import { markdownRenderer } from "../renderers/markdown";
+import { coalesceTextParts, collectMessageNodes, collectSemanticParts, partsToText, safeStringify, } from "../renderers/shared";
+import { tiktokenTokenizer } from "../tokenizers";
+/**
+ * Renderer that outputs ChatCompletionMessageParam[] for the OpenAI Chat Completions API.
+ * Pass this to render() to get messages compatible with client.chat.completions.create().
+ *
+ * @example
+ * ```ts
+ * import { render } from "@fastpaca/cria";
+ * import { chatCompletions } from "@fastpaca/cria/openai";
+ *
+ * const messages = await render(prompt, { tokenizer, budget, renderer: chatCompletions });
+ * const response = await openai.chat.completions.create({ model: "gpt-4", messages });
+ * ```
+ */
+export const chatCompletions = {
+    name: "openai-chat-completions",
+    tokenString: markdownRenderer.tokenString,
+    render: (element) => renderToChatCompletions(element),
+    empty: () => [],
+};
+function renderToChatCompletions(root) {
+    const messageNodes = collectMessageNodes(root);
+    const result = [];
+    for (const messageNode of messageNodes) {
+        result.push(...messageNodeToParams(messageNode));
+    }
+    return result;
+}
+function messageNodeToParams(messageNode) {
+    const parts = coalesceTextParts(collectSemanticParts(messageNode.children));
+    if (messageNode.role === "system") {
+        return [toSystemMessage(parts)];
+    }
+    if (messageNode.role === "user") {
+        return [toUserMessage(parts)];
+    }
+    // Assistant message: may contain tool calls, and tool results become separate messages
+    // Preserve original part ordering - only separate out tool results
+    const assistantParts = parts.filter((p) => p.type !== "tool-result");
+    const toolResultParts = parts.filter((p) => p.type === "tool-result");
+    const result = [];
+    if (assistantParts.length > 0 || toolResultParts.length === 0) {
+        result.push(toAssistantMessage(assistantParts));
+    }
+    for (const toolResult of toolResultParts) {
+        result.push(toToolMessage(toolResult));
+    }
+    return result;
+}
+function toSystemMessage(parts) {
+    return {
+        role: "system",
+        content: partsToText(parts, { wrapReasoning: true }),
+    };
+}
+function toUserMessage(parts) {
+    return {
+        role: "user",
+        content: partsToText(parts, { wrapReasoning: true }),
+    };
+}
+function toAssistantMessage(parts) {
+    const textContent = partsToText(parts, { wrapReasoning: true });
+    const toolCalls = parts
+        .filter((part) => part.type === "tool-call")
+        .map((part) => ({
+        id: part.toolCallId,
+        type: "function",
+        function: {
+            name: part.toolName,
+            arguments: safeStringify(part.input),
+        },
+    }));
+    const result = {
+        role: "assistant",
+    };
+    if (textContent.length > 0) {
+        result.content = textContent;
+    }
+    if (toolCalls.length > 0) {
+        result.tool_calls = toolCalls;
+    }
+    return result;
+}
+function toToolMessage(part) {
+    return {
+        role: "tool",
+        tool_call_id: part.toolCallId,
+        content: safeStringify(part.output),
+    };
+}
+// ============================================================================
+// Responses API Renderer (for reasoning models)
+// ============================================================================
+/**
+ * Renderer that outputs ResponseInputItem[] for the OpenAI Responses API.
+ * Use this with reasoning models that support native reasoning.
+ *
+ * @example
+ * ```ts
+ * import { render } from "@fastpaca/cria";
+ * import { responses } from "@fastpaca/cria/openai";
+ *
+ * const input = await render(prompt, { tokenizer, budget, renderer: responses });
+ * const response = await openai.responses.create({ model: "o3", input });
+ * ```
+ */
+export const responses = {
+    name: "openai-responses",
+    tokenString: markdownRenderer.tokenString,
+    render: (element) => renderToResponses(element),
+    empty: () => [],
+};
+function renderToResponses(root) {
+    const result = [];
+    collectResponseItems(root, result);
+    return result;
+}
+/**
+ * Convert a message element's parts into ResponseInputItems.
+ * Handles text, reasoning, tool calls, and tool results.
+ */
+function collectMessageResponseItems(element, acc) {
+    const parts = coalesceTextParts(collectSemanticParts(element.children));
+    const role = mapRoleForResponses(element.role);
+    let textBuffer = "";
+    let reasoningIndex = 0;
+    const flushTextBuffer = () => {
+        if (textBuffer.length > 0) {
+            acc.push({ role, content: textBuffer });
+            textBuffer = "";
+        }
+    };
+    for (const part of parts) {
+        switch (part.type) {
+            case "text":
+                textBuffer += part.text;
+                break;
+            case "reasoning": {
+                flushTextBuffer();
+                acc.push({
+                    id: element.id
+                        ? `${element.id}-reasoning-${reasoningIndex}`
+                        : `reasoning_${reasoningIndex}`,
+                    type: "reasoning",
+                    summary: [{ type: "summary_text", text: part.text }],
+                });
+                reasoningIndex += 1;
+                break;
+            }
+            case "tool-call":
+                flushTextBuffer();
+                acc.push({
+                    type: "function_call",
+                    call_id: part.toolCallId,
+                    name: part.toolName,
+                    arguments: safeStringify(part.input),
+                });
+                break;
+            case "tool-result":
+                flushTextBuffer();
+                acc.push({
+                    type: "function_call_output",
+                    call_id: part.toolCallId,
+                    output: safeStringify(part.output),
+                });
+                break;
+            default:
+                // Exhaustive check - all SemanticPart types handled above
+                break;
+        }
+    }
+    flushTextBuffer();
+}
+function collectResponseItems(element, acc) {
+    switch (element.kind) {
+        case "message": {
+            collectMessageResponseItems(element, acc);
+            break;
+        }
+        case "reasoning": {
+            // Native reasoning support in Responses API
+            if (element.text.length > 0) {
+                const reasoningItem = {
+                    id: element.id ?? `rs_${Date.now()}`,
+                    type: "reasoning",
+                    summary: [{ type: "summary_text", text: element.text }],
+                };
+                acc.push(reasoningItem);
+            }
+            break;
+        }
+        case "tool-call": {
+            const toolCall = {
+                type: "function_call",
+                call_id: element.toolCallId,
+                name: element.toolName,
+                arguments: safeStringify(element.input),
+            };
+            acc.push(toolCall);
+            break;
+        }
+        case "tool-result": {
+            const toolResult = {
+                type: "function_call_output",
+                call_id: element.toolCallId,
+                output: safeStringify(element.output),
+            };
+            acc.push(toolResult);
+            break;
+        }
+        default: {
+            // Recurse into children for regions without semantic kind
+            for (const child of element.children) {
+                if (typeof child !== "string") {
+                    collectResponseItems(child, acc);
+                }
+            }
+        }
+    }
+}
+const RESPONSE_ROLE_MAP = {
+    system: "system",
+    developer: "developer",
+    user: "user",
+};
+function mapRoleForResponses(role) {
+    return RESPONSE_ROLE_MAP[role] ?? "assistant";
+}
+const VALID_OPENAI_ROLES = new Set(["user", "assistant", "system"]);
+/**
+ * ModelProvider implementation that wraps an OpenAI client.
+ * Use this with the DSL's `.provider()` method.
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from "openai";
+ * import { cria } from "@fastpaca/cria";
+ * import { Provider } from "@fastpaca/cria/openai";
+ *
+ * const client = new OpenAI();
+ * const provider = new Provider(client, "gpt-4o");
+ *
+ * const prompt = cria
+ *   .prompt()
+ *   .provider(provider, (p) =>
+ *     p.summary(content, { id: "summary", store })
+ *   )
+ *   .build();
+ * ```
+ */
+export class Provider {
+    name = "openai";
+    client;
+    model;
+    constructor(client, model) {
+        this.client = client;
+        this.model = model;
+    }
+    async completion(request) {
+        const messages = request.system
+            ? [{ role: "system", content: request.system }]
+            : [];
+        for (const msg of request.messages) {
+            if (VALID_OPENAI_ROLES.has(msg.role)) {
+                messages.push({ role: msg.role, content: msg.content });
+            }
+        }
+        const response = await this.client.chat.completions.create({
+            model: this.model,
+            messages,
+        });
+        const text = response.choices[0]?.message?.content ?? "";
+        return { text };
+    }
+}
+export function OpenAIProvider({ client, model, tokenizer, children = [], }) {
+    const provider = {
+        name: "openai",
+        tokenizer: tokenizer ?? tiktokenTokenizer(model),
+        async completion(request) {
+            const messages = request.system
+                ? [{ role: "system", content: request.system }]
+                : [];
+            for (const msg of request.messages) {
+                if (VALID_OPENAI_ROLES.has(msg.role)) {
+                    messages.push({ role: msg.role, content: msg.content });
+                }
+            }
+            const response = await client.chat.completions.create({
+                model,
+                messages,
+            });
+            const text = response.choices[0]?.message?.content ?? "";
+            return { text };
+        },
+    };
+    return {
+        priority: 0,
+        children,
+        context: { provider },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/openai/index.js.map

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

package/dist/render.d.ts

@@ -1,44 +1,48 @@
-import { type PromptElement, type Tokenizer } from "./types";
-/** Options for the render function. */
-interface RenderOptions {
-    /** Function to count tokens in a string (e.g., tiktoken) */
-    tokenizer: Tokenizer;
-    /** Maximum token count for the final output */
+import { FitError, type MaybePromise, type PromptElement, type PromptRenderer, type Tokenizer } from "./types";
+export interface RenderOptions {
+    tokenizer?: Tokenizer;
+    /** Token budget. Omit for unlimited. */
+    budget?: number;
+    renderer?: PromptRenderer<unknown>;
+    hooks?: RenderHooks;
+}
+export interface FitStartEvent {
+    element: PromptElement;
     budget: number;
+    totalTokens: number;
+}
+export interface FitIterationEvent {
+    iteration: number;
+    priority: number;
+    totalTokens: number;
+}
+export interface StrategyAppliedEvent {
+    target: PromptElement;
+    result: PromptElement | null;
+    priority: number;
+    iteration: number;
+}
+export interface FitCompleteEvent {
+    result: PromptElement | null;
+    iterations: number;
+    totalTokens: number;
+}
+export interface FitErrorEvent {
+    error: FitError;
+    iteration: number;
+    priority: number;
+    totalTokens: number;
+}
+export interface RenderHooks {
+    onFitStart?: (event: FitStartEvent) => MaybePromise<void>;
+    onFitIteration?: (event: FitIterationEvent) => MaybePromise<void>;
+    onStrategyApplied?: (event: StrategyAppliedEvent) => MaybePromise<void>;
+    onFitComplete?: (event: FitCompleteEvent) => MaybePromise<void>;
+    onFitError?: (event: FitErrorEvent) => MaybePromise<void>;
 }
-/**
- * Renders a PromptElement tree to a fitted string.
- *
- * This is the main entry point for Cria. Takes a JSX tree and returns a string
- * that fits within the specified token budget.
- *
- * **Pipeline:**
- * 1. `flatten`: Walks the tree, collects text into ordered PromptFragment[]
- * 2. `fitToBudget`: Applies strategies starting from lowest priority until under budget
- * 3. `join`: Concatenates fragment content into final string
- *
- * @param element - The root PromptElement (from JSX)
- * @param options - Tokenizer and budget configuration
- * @returns The fitted prompt string
- * @throws {FitError} When the prompt cannot fit within budget
- *
- * @example
- * ```tsx
- * import { render, Region, Omit } from "@fastpaca/cria";
- *
- * const prompt = (
- *   <Region priority={0}>
- *     System prompt
- *     <Omit priority={2}>Optional context</Omit>
- *   </Region>
- * );
- *
- * const result = render(prompt, {
- *   tokenizer: (text) => Math.ceil(text.length / 4),
- *   budget: 1000,
- * });
- * ```
- */
-export declare function render(element: PromptElement, { tokenizer, budget }: RenderOptions): string;
+type RenderOutput<TOptions extends RenderOptions> = TOptions extends {
+    renderer: PromptRenderer<infer TOutput>;
+} ? TOutput : string;
+export declare function render<TOptions extends RenderOptions>(element: MaybePromise<PromptElement>, { tokenizer, budget, renderer, hooks }: TOptions): Promise<RenderOutput<TOptions>>;
 export {};
 //# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAIlB,KAAK,SAAS,EACf,MAAM,SAAS,CAAC;AAEjB,uCAAuC;AACvC,UAAU,aAAa;IACrB,4DAA4D;IAC5D,SAAS,EAAE,SAAS,CAAC;IACrB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,aAAa,EACtB,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,aAAa,GACnC,MAAM,CAQR"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,SAAS,EACf,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,QAAQ,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAC1D,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAClE,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IACxE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAChE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,KAAK,YAAY,CAAC,QAAQ,SAAS,aAAa,IAAI,QAAQ,SAAS;IACnE,QAAQ,EAAE,cAAc,CAAC,MAAM,OAAO,CAAC,CAAC;CACzC,GACG,OAAO,GACP,MAAM,CAAC;AAEX,wBAAsB,MAAM,CAAC,QAAQ,SAAS,aAAa,EACzD,OAAO,EAAE,YAAY,CAAC,aAAa,CAAC,EACpC,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,QAAQ,GAC/C,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CA4CjC"}