@proposit/proposit-core 1.0.2 → 1.1.1

package/dist/lib/pipelines/stage-helpers.d.ts

@@ -0,0 +1,94 @@
+import type { TSchema } from "typebox";
+import type { TDepSpec, TPipeline, TStage, TStageContext } from "./types.js";
+import type { TReasoningEffort, TToolSpec } from "../llm/types.js";
+export declare function deterministicStage<TOutput>(config: {
+    id: string;
+    dependsOn: readonly TDepSpec[];
+    outputSchema: TSchema;
+    fn: (ctx: TStageContext) => Promise<TOutput> | TOutput;
+}): TStage<TOutput>;
+export type TRetryReason = "schema_validation" | "transient" | "rate_limit";
+export type TRetryPolicy = {
+    maxAttempts: number;
+    backoffMs: number;
+    retryOn: readonly TRetryReason[];
+    /** Bound on the per-retry appended validation-error fragment. */
+    maxAppendedErrorBytes?: number;
+};
+export declare const DEFAULT_RETRY_POLICY: TRetryPolicy;
+/**
+ * Thrown by any stage when an `AbortSignal` cancels execution
+ * mid-flight. The executor recognizes this class and marks the stage
+ * as `skipped` (not `failed`); no `ProcessingFailure` is recorded
+ * because a caller-driven cancellation is not a stage failure to
+ * report. Distinguishing abort from a genuine provider error matters
+ * for server-side cancellation observability (slice 2C's SSE bridge
+ * routes these differently).
+ */
+export declare class StageAbortedError extends Error {
+    readonly stageId: string;
+    constructor(args: {
+        stageId: string;
+        message?: string;
+    });
+}
+/**
+ * Thrown by `subPipelineStage`'s wrapper when the nested pipeline
+ * returns `output: null` (any required dep of its finalize was
+ * skipped/failed, or its finalize itself returned null). The wrapper
+ * surfaces this as a stage failure on the outer pipeline so the
+ * caller sees a clean per-stage failure rather than an LLM-flavored
+ * misnomer. Kept separate from `LlmStageRetryExhaustedError` because
+ * no LLM call and no retry are involved.
+ */
+export declare class SubPipelineFailedError extends Error {
+    readonly stageId: string;
+    readonly code: string;
+    readonly failureContext: Record<string, unknown> | undefined;
+    constructor(args: {
+        stageId: string;
+        code: string;
+        message: string;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Thrown internally by `llmStage` after retry exhaustion. The
+ * executor catches it and converts it into a `ProcessingFailure`.
+ */
+export declare class LlmStageRetryExhaustedError extends Error {
+    readonly reason: TRetryReason;
+    readonly code: string;
+    readonly attempts: number;
+    readonly stageId: string;
+    readonly failureContext: Record<string, unknown> | undefined;
+    constructor(args: {
+        stageId: string;
+        reason: TRetryReason;
+        code: string;
+        attempts: number;
+        message: string;
+        context?: Record<string, unknown>;
+    });
+}
+export declare function llmStage<TOutput>(config: {
+    id: string;
+    dependsOn: readonly TDepSpec[];
+    outputSchema: TSchema;
+    model: string;
+    reasoningEffort?: TReasoningEffort;
+    buildPrompt: (ctx: TStageContext) => {
+        system: string;
+        user: string;
+    };
+    tools?: readonly TToolSpec[];
+    retry?: Partial<TRetryPolicy>;
+    maxOutputTokens?: number;
+}): TStage<TOutput>;
+export declare function readStashedTokenUsage(ctx: TStageContext, stageId: string): import("../llm/types.js").TLlmTokenUsage | undefined;
+export declare function subPipelineStage<TOutput>(config: {
+    id: string;
+    dependsOn: readonly TDepSpec[];
+    pipeline: TPipeline<unknown, TOutput>;
+}): TStage<TOutput>;
+//# sourceMappingURL=stage-helpers.d.ts.map

package/dist/lib/pipelines/stage-helpers.d.ts.map

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

package/dist/lib/pipelines/stage-helpers.js

@@ -0,0 +1,354 @@
+// Helpers that compose stages with sensible defaults.
+//
+// - `deterministicStage` — pure (or async-pure) compute, no LLM call.
+// - `llmStage` — wraps an LLM call with structured-output validation
+//   and the framework retry policy (schema-validation + transient).
+// - `subPipelineStage` — recursively executes a nested pipeline as a
+//   single stage in the outer pipeline. Reserved for future
+//   composition; implemented + tested but unused by Phase 1 pipelines.
+import { Value } from "typebox/value";
+import { executePipeline } from "./execute.js";
+// -- Deterministic --
+export function deterministicStage(config) {
+    return {
+        id: config.id,
+        dependsOn: config.dependsOn,
+        outputSchema: config.outputSchema,
+        run: async (ctx) => config.fn(ctx),
+    };
+}
+export const DEFAULT_RETRY_POLICY = {
+    maxAttempts: 2,
+    backoffMs: 500,
+    retryOn: ["schema_validation", "transient"],
+    maxAppendedErrorBytes: 2048,
+};
+const TRUNCATION_SUFFIX = "…<truncated>";
+function truncateValidationError(error, capBytes) {
+    // NOTE: `capBytes` is measured in JavaScript `string.length` —
+    // UTF-16 code units, not UTF-8 bytes. The spec (§6.3) phrases the
+    // cap as "bytes"; for ASCII-heavy validation errors the two are
+    // equal, and for non-ASCII paths a 2048 cap is roughly 2–4 KB of
+    // UTF-8 depending on character distribution. We accept this drift
+    // for V1: realistic TypeBox validation errors are short and
+    // English; a future polish pass can switch to
+    // `new TextEncoder().encode(error).length` if a real workload
+    // shows the distinction matters.
+    if (error.length <= capBytes) {
+        return error;
+    }
+    const head = Math.max(0, capBytes - TRUNCATION_SUFFIX.length);
+    return error.slice(0, head) + TRUNCATION_SUFFIX;
+}
+/**
+ * Thrown by any stage when an `AbortSignal` cancels execution
+ * mid-flight. The executor recognizes this class and marks the stage
+ * as `skipped` (not `failed`); no `ProcessingFailure` is recorded
+ * because a caller-driven cancellation is not a stage failure to
+ * report. Distinguishing abort from a genuine provider error matters
+ * for server-side cancellation observability (slice 2C's SSE bridge
+ * routes these differently).
+ */
+export class StageAbortedError extends Error {
+    stageId;
+    constructor(args) {
+        super(args.message ?? "aborted");
+        this.name = "StageAbortedError";
+        this.stageId = args.stageId;
+    }
+}
+/**
+ * Thrown by `subPipelineStage`'s wrapper when the nested pipeline
+ * returns `output: null` (any required dep of its finalize was
+ * skipped/failed, or its finalize itself returned null). The wrapper
+ * surfaces this as a stage failure on the outer pipeline so the
+ * caller sees a clean per-stage failure rather than an LLM-flavored
+ * misnomer. Kept separate from `LlmStageRetryExhaustedError` because
+ * no LLM call and no retry are involved.
+ */
+export class SubPipelineFailedError extends Error {
+    stageId;
+    code;
+    failureContext;
+    constructor(args) {
+        super(args.message);
+        this.name = "SubPipelineFailedError";
+        this.stageId = args.stageId;
+        this.code = args.code;
+        this.failureContext = args.context;
+    }
+}
+/**
+ * Thrown internally by `llmStage` after retry exhaustion. The
+ * executor catches it and converts it into a `ProcessingFailure`.
+ */
+export class LlmStageRetryExhaustedError extends Error {
+    reason;
+    code;
+    attempts;
+    stageId;
+    failureContext;
+    constructor(args) {
+        super(args.message);
+        this.name = "LlmStageRetryExhaustedError";
+        this.stageId = args.stageId;
+        this.reason = args.reason;
+        this.code = args.code;
+        this.attempts = args.attempts;
+        this.failureContext = args.context;
+    }
+}
+function classifyError(err) {
+    if (typeof err !== "object" || err === null) {
+        return "non_retryable";
+    }
+    const tag = err.retryReason;
+    if (tag === "transient" || tag === "rate_limit") {
+        return tag;
+    }
+    return "non_retryable";
+}
+async function sleep(ms, signal) {
+    if (ms <= 0)
+        return;
+    if (signal.aborted)
+        return;
+    await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function emitRetry(ctx, stageId, attempt, reason) {
+    const event = {
+        kind: "stage:retry",
+        stageId,
+        attempt,
+        reason,
+        at: now(),
+    };
+    ctx.emit(event);
+}
+function now() {
+    return typeof performance !== "undefined" && performance.now
+        ? performance.now()
+        : Date.now();
+}
+// -- LLM stage --
+export function llmStage(config) {
+    const policy = {
+        ...DEFAULT_RETRY_POLICY,
+        ...config.retry,
+        retryOn: config.retry?.retryOn ?? DEFAULT_RETRY_POLICY.retryOn,
+    };
+    const errorCap = policy.maxAppendedErrorBytes ??
+        DEFAULT_RETRY_POLICY.maxAppendedErrorBytes ??
+        2048;
+    return {
+        id: config.id,
+        dependsOn: config.dependsOn,
+        outputSchema: config.outputSchema,
+        run: async (ctx) => {
+            const prompt = config.buildPrompt(ctx);
+            let userMessage = prompt.user;
+            let attempt = 0;
+            let lastError = null;
+            while (attempt < policy.maxAttempts) {
+                attempt += 1;
+                if (ctx.signal.aborted) {
+                    // Loop-top abort: caller cancelled before (or
+                    // between) attempts. Surface as a `skipped` stage
+                    // rather than a failure.
+                    throw new StageAbortedError({ stageId: config.id });
+                }
+                const req = {
+                    model: config.model,
+                    reasoningEffort: config.reasoningEffort,
+                    systemPrompt: prompt.system,
+                    userMessage,
+                    outputSchema: config.outputSchema,
+                    tools: config.tools,
+                    maxOutputTokens: config.maxOutputTokens,
+                    signal: ctx.signal,
+                };
+                try {
+                    const response = await ctx.llm.respond(req);
+                    if (!Value.Check(config.outputSchema, response.output)) {
+                        const errors = [
+                            ...Value.Errors(config.outputSchema, response.output),
+                        ];
+                        const validationMessage = errors
+                            .map((e) => `${e.instancePath}: ${e.message}`)
+                            .join("; ");
+                        lastError = {
+                            reason: "schema_validation",
+                            code: "OUTPUT_SCHEMA_INVALID",
+                            message: validationMessage,
+                        };
+                        const retryable = policy.retryOn.includes("schema_validation");
+                        if (!retryable || attempt >= policy.maxAttempts) {
+                            break;
+                        }
+                        emitRetry(ctx, config.id, attempt, "schema_validation");
+                        const truncated = truncateValidationError(validationMessage, errorCap);
+                        userMessage =
+                            prompt.user +
+                                "\n\nYour previous response failed schema validation: " +
+                                truncated +
+                                ". Please retry conforming to the schema.";
+                        await sleep(policy.backoffMs, ctx.signal);
+                        continue;
+                    }
+                    // Token usage emission is handled by the executor at
+                    // stage:end time; we return the response output and
+                    // attach the usage onto a side channel via failure-free
+                    // path.
+                    // We stash token usage on a per-stage well-known key
+                    // recognized by the executor.
+                    stashTokenUsage(ctx, config.id, response.tokenUsage);
+                    return response.output;
+                }
+                catch (err) {
+                    if (err instanceof LlmStageRetryExhaustedError &&
+                        err.stageId === config.id) {
+                        // Re-throw our own marker; the catch below shouldn't
+                        // see it. Defensive.
+                        throw err;
+                    }
+                    if (err instanceof StageAbortedError) {
+                        throw err;
+                    }
+                    // Mid-flight abort surfaces here when the provider
+                    // honored the signal and threw. Recognize it before
+                    // classifying as a generic non-retryable failure so
+                    // the executor can mark this stage `skipped`, not
+                    // `failed` with `LLM_NON_RETRYABLE_ERROR`.
+                    if (ctx.signal.aborted) {
+                        throw new StageAbortedError({ stageId: config.id });
+                    }
+                    const reason = classifyError(err);
+                    const message = err instanceof Error ? err.message : String(err);
+                    if (reason === "non_retryable") {
+                        lastError = {
+                            reason: "transient",
+                            code: "LLM_NON_RETRYABLE_ERROR",
+                            message,
+                        };
+                        break;
+                    }
+                    lastError = {
+                        reason,
+                        code: reason === "rate_limit"
+                            ? "LLM_RATE_LIMITED"
+                            : "LLM_TRANSIENT_ERROR",
+                        message,
+                    };
+                    if (!policy.retryOn.includes(reason)) {
+                        break;
+                    }
+                    if (attempt >= policy.maxAttempts) {
+                        break;
+                    }
+                    emitRetry(ctx, config.id, attempt, reason);
+                    await sleep(policy.backoffMs, ctx.signal);
+                }
+            }
+            const failure = lastError ?? {
+                reason: "transient",
+                code: "LLM_UNKNOWN_ERROR",
+                message: "llmStage retry loop exited without error context",
+            };
+            throw new LlmStageRetryExhaustedError({
+                stageId: config.id,
+                reason: failure.reason,
+                code: failure.code,
+                attempts: attempt,
+                message: failure.message,
+                context: failure.context,
+            });
+        },
+    };
+}
+// -- Token-usage side channel ---------------------------------------------
+//
+// llmStage and the executor share a tiny side-channel so the executor
+// can attach token usage to the matching `stage:end` event without
+// changing the stage `run` return shape. The side channel is a per-
+// pipeline-run weak map keyed by the StageContext object.
+const TOKEN_USAGE_CHANNELS = new WeakMap();
+function stashTokenUsage(ctx, stageId, usage) {
+    let bucket = TOKEN_USAGE_CHANNELS.get(ctx);
+    if (!bucket) {
+        bucket = new Map();
+        TOKEN_USAGE_CHANNELS.set(ctx, bucket);
+    }
+    bucket.set(stageId, usage);
+}
+export function readStashedTokenUsage(ctx, stageId) {
+    return TOKEN_USAGE_CHANNELS.get(ctx)?.get(stageId);
+}
+// -- Sub-pipeline --
+export function subPipelineStage(config) {
+    return {
+        id: config.id,
+        dependsOn: config.dependsOn,
+        outputSchema: config.pipeline.outputSchema,
+        run: async (ctx) => {
+            const prefix = `${config.id}::`;
+            const forwarded = (event) => {
+                ctx.emit(prefixSubPipelineEvent(prefix, event));
+            };
+            const result = await executePipeline(config.pipeline, ctx.input, {
+                llm: ctx.llm,
+                generateId: ctx.generateId,
+                signal: ctx.signal,
+                onEvent: forwarded,
+            });
+            for (const failure of result.failures) {
+                ctx.addFailure({
+                    code: failure.code,
+                    message: failure.message,
+                    severity: failure.severity,
+                    context: {
+                        ...(failure.context ?? {}),
+                        subPipelineStageId: config.id,
+                        subPipelineStage: failure.stage,
+                    },
+                });
+            }
+            if (result.output === null) {
+                throw new SubPipelineFailedError({
+                    stageId: config.id,
+                    code: "SUB_PIPELINE_NULL_OUTPUT",
+                    message: "Nested pipeline returned null output; the outer stage cannot complete.",
+                    context: {
+                        subPipelineId: config.pipeline.id,
+                    },
+                });
+            }
+            return result.output;
+        },
+    };
+}
+function prefixSubPipelineEvent(prefix, event) {
+    switch (event.kind) {
+        case "pipeline:start":
+            return { ...event, pipelineId: prefix + event.pipelineId };
+        case "pipeline:end":
+            return event;
+        case "stage:start":
+            return { ...event, stageId: prefix + event.stageId };
+        case "stage:end":
+            return { ...event, stageId: prefix + event.stageId };
+        case "stage:retry":
+            return { ...event, stageId: prefix + event.stageId };
+    }
+}
+//# sourceMappingURL=stage-helpers.js.map

package/dist/lib/pipelines/stage-helpers.js.map

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

package/dist/lib/pipelines/types.d.ts

@@ -0,0 +1,88 @@
+import type { TSchema } from "typebox";
+import type { TLlmProvider, TLlmTokenUsage } from "../llm/types.js";
+export type TOptionalDep = {
+    readonly __optional: true;
+    readonly id: string;
+};
+export type TDepSpec = string | TOptionalDep;
+/**
+ * Wrap a stage id as an optional dependency. Optional upstream
+ * outcomes never propagate as skips: the depending stage runs even
+ * when the upstream skipped or failed, but `ctx.get` returns
+ * `undefined` for that id.
+ */
+export declare function optional(id: string): TOptionalDep;
+export declare function isOptionalDep(dep: TDepSpec): dep is TOptionalDep;
+export declare function depId(dep: TDepSpec): string;
+export type TStageStatus = "completed" | "skipped" | "failed";
+export type TStageContext = {
+    input: unknown;
+    get<T>(stageId: string): T | undefined;
+    stageStatus(stageId: string): TStageStatus;
+    llm: TLlmProvider;
+    generateId: () => string;
+    signal: AbortSignal;
+    emit: (event: TPipelineEvent) => void;
+    addFailure: (failure: Omit<TProcessingFailure, "stage">) => void;
+};
+export type TStage<TOutput> = {
+    id: string;
+    dependsOn: readonly TDepSpec[];
+    outputSchema: TSchema;
+    run: (ctx: TStageContext) => Promise<TOutput>;
+};
+export type TPipelineFinalize<TOutput> = {
+    dependsOn: readonly TDepSpec[];
+    run: (ctx: TStageContext) => TOutput;
+};
+export type TPipeline<TInput, TOutput> = {
+    id: string;
+    version: string;
+    inputSchema: TSchema;
+    outputSchema: TSchema;
+    stages: readonly TStage<unknown>[];
+    finalize: TPipelineFinalize<TOutput>;
+    /** Phantom field so `TInput` participates in inference. */
+    _inputTypeMarker?: TInput;
+};
+export type TProcessingFailure = {
+    stage: string;
+    code: string;
+    message: string;
+    severity: "warning" | "error";
+    context?: Record<string, unknown>;
+};
+export type TPipelineResult<TOutput> = {
+    output: TOutput | null;
+    failures: TProcessingFailure[];
+    stageOutcomes: Record<string, TStageStatus>;
+    tokenUsage?: TLlmTokenUsage;
+};
+export type TPipelineEvent = {
+    kind: "pipeline:start";
+    pipelineId: string;
+    pipelineVersion: string;
+    at: number;
+} | {
+    kind: "pipeline:end";
+    status: "completed" | "failed";
+    output: "present" | "null";
+    at: number;
+} | {
+    kind: "stage:start";
+    stageId: string;
+    at: number;
+} | {
+    kind: "stage:end";
+    stageId: string;
+    status: TStageStatus;
+    tokenUsage?: TLlmTokenUsage;
+    at: number;
+} | {
+    kind: "stage:retry";
+    stageId: string;
+    attempt: number;
+    reason: string;
+    at: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/pipelines/types.d.ts.map

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

package/dist/lib/pipelines/types.js

@@ -0,0 +1,36 @@
+// Pipeline framework primitives — shared types for the executor,
+// stage helpers, and consumers.
+//
+// Type aliases use the repo's T-prefixed PascalCase convention
+// (enforced by `@typescript-eslint/naming-convention`); the public
+// vocabulary maps to the spec's unprefixed names as follows:
+//
+//   spec name        ↔  repo type
+//   ---------------     -------------------
+//   Stage<TOutput>      TStage<TOutput>
+//   Pipeline<TIn,TOut>  TPipeline<TInput, TOutput>
+//   StageContext        TStageContext
+//   ProcessingFailure   TProcessingFailure
+//   PipelineResult<T>   TPipelineResult<TOutput>
+//   PipelineEvent       TPipelineEvent
+//   DepSpec             TDepSpec
+//   OptionalDep         TOptionalDep
+//
+// Helper functions (`optional`, `executePipeline`, …) keep their
+// spec-spelled camelCase names since they are values, not types.
+/**
+ * Wrap a stage id as an optional dependency. Optional upstream
+ * outcomes never propagate as skips: the depending stage runs even
+ * when the upstream skipped or failed, but `ctx.get` returns
+ * `undefined` for that id.
+ */
+export function optional(id) {
+    return { __optional: true, id };
+}
+export function isOptionalDep(dep) {
+    return typeof dep !== "string" && dep.__optional === true;
+}
+export function depId(dep) {
+    return typeof dep === "string" ? dep : dep.id;
+}
+//# sourceMappingURL=types.js.map

package/dist/lib/pipelines/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/pipelines/types.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,gCAAgC;AAChC,EAAE;AACF,+DAA+D;AAC/D,mEAAmE;AACnE,6DAA6D;AAC7D,EAAE;AACF,kCAAkC;AAClC,4CAA4C;AAC5C,wCAAwC;AACxC,mDAAmD;AACnD,sCAAsC;AACtC,2CAA2C;AAC3C,iDAAiD;AACjD,uCAAuC;AACvC,iCAAiC;AACjC,qCAAqC;AACrC,EAAE;AACF,iEAAiE;AACjE,iEAAiE;AAmBjE;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,EAAU;IAC/B,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,EAAE,CAAA;AACnC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAa;IACvC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,KAAK,IAAI,CAAA;AAC7D,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,GAAa;IAC/B,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAA;AACjD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proposit/proposit-core",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Core engine for building and manipulating propositional logic arguments.",
   "license": "MIT",
   "keywords": [
@@ -32,6 +32,11 @@
       "types": "./dist/extensions/basics/index.d.ts",
       "import": "./dist/extensions/basics/index.js",
       "default": "./dist/extensions/basics/index.js"
+    },
+    "./extensions/openai": {
+      "types": "./dist/extensions/openai/index.d.ts",
+      "import": "./dist/extensions/openai/index.js",
+      "default": "./dist/extensions/openai/index.js"
     }
   },
   "bin": {
@@ -66,6 +71,14 @@
     "typebox": "^1.1.14",
     "yaml": "^2.8.3"
   },
+  "peerDependencies": {
+    "openai": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    }
+  },
   "scripts": {
     "generate:parser": "peggy --format es -o src/lib/core/parser/formula-gen.js src/lib/core/parser/formula.peggy",
     "build": "rm -rf dist tsconfig.build.tsbuildinfo && pnpm run generate:parser && pnpm tsc -p tsconfig.build.json && cp src/lib/core/parser/formula-gen.js dist/lib/core/parser/formula-gen.js && pnpm run docs",

package/dist/cli/llm/openai.d.ts

@@ -1,4 +0,0 @@
-import type { TLlmProvider, TLlmProviderOptions } from "./types.js";
-export declare const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
-export declare function createOpenAiProvider(options: TLlmProviderOptions): TLlmProvider;
-//# sourceMappingURL=openai.d.ts.map

package/dist/cli/llm/openai.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../../src/cli/llm/openai.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAInE,eAAO,MAAM,kBAAkB,mBAAmB,CAAA;AAElD,wBAAgB,oBAAoB,CAChC,OAAO,EAAE,mBAAmB,GAC7B,YAAY,CAmDd"}