@pipedog/core 0.0.0 → 0.1.0

package/dist/classifiers/openai/decisions/classifier.js

@@ -0,0 +1,241 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/classifiers/openai/decisions/classifier.py
+/**
+ * Classifier backed by OpenAI's Decisions API.
+ *
+ * `OpenAIDecisionsClassifier` turns each question into a request and each
+ * reply into a result, through an `OpenAIDecisionsClient`.
+ */
+import { rethrowIfCancelled } from "@pipedog/asyncio";
+import { LLMTokenUsage } from "../../../metrics/metrics.js";
+import { logger } from "../../../utils/logger.js";
+import { BaseClassifier, ChoiceQuestion, ChoiceResult, ClassifierError, ScoreLevel, ScoreResult, YesNoQuestion, YesNoResult, } from "../../base_classifier.js";
+import { bytesToBase64, isDict, toFloat } from "../../http_client.js";
+import { DEFAULT_BASE_URL, DEFAULT_MODEL, DEFAULT_TIMEOUT, OpenAIDecisionsClient, } from "./client.js";
+/** The most options the Decisions API takes in one choice question. */
+export const OPENAI_DECISIONS_MAX_CHOICE_OPTIONS = 255;
+/** The most images the Decisions API takes in one request. */
+export const OPENAI_DECISIONS_MAX_IMAGES = 128;
+/**
+ * Answers questions by asking OpenAI's Decisions API.
+ *
+ * Structured state, instructions and descriptions are sent as JSON. Build
+ * one with an API key to get a client of its own, or pass an
+ * `OpenAIDecisionsClient` to share one between several classifiers. A client
+ * the classifier created is closed in `cleanup()`; a shared one is left to
+ * whoever made it.
+ *
+ * The Decisions API can see images: up to `OPENAI_DECISIONS_MAX_IMAGES` per
+ * call.
+ *
+ * @example
+ * const classifier = new OpenAIDecisionsClassifier({ apiKey: process.env.OPENAI_API_KEY });
+ */
+export class OpenAIDecisionsClassifier extends BaseClassifier {
+    _ownsClient;
+    _client;
+    constructor(options = {}) {
+        super(options);
+        this._ownsClient = options.client == null;
+        let client = options.client ?? null;
+        if (!client) {
+            if (!options.apiKey) {
+                throw new Error("OpenAIDecisionsClassifier needs an API key or an OpenAIDecisionsClient");
+            }
+            client = new OpenAIDecisionsClient({
+                apiKey: options.apiKey,
+                model: options.model ?? DEFAULT_MODEL,
+                baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+                timeout: options.timeout ?? DEFAULT_TIMEOUT,
+            });
+        }
+        this._client = client;
+    }
+    /** The client this classifier asks through. */
+    get client() {
+        return this._client;
+    }
+    /**
+     * Open the connection to OpenAI ahead of the first question.
+     *
+     * A connection that cannot be opened now is only a warning: the first
+     * question opens it itself.
+     *
+     * @param taskManager The task manager of the owner.
+     */
+    async setup(taskManager) {
+        await super.setup(taskManager);
+        try {
+            await this._client.connect();
+        }
+        catch (e) {
+            if (!(e instanceof ClassifierError)) {
+                throw e;
+            }
+            logger.warning(`${this}: ${e.message}`);
+        }
+    }
+    /** Close the client if this classifier created it. */
+    async cleanup() {
+        await super.cleanup();
+        if (this._ownsClient) {
+            await this._client.close();
+        }
+    }
+    /** The decision model the questions go to. */
+    get model() {
+        return this._client.model;
+    }
+    /** The Decisions API can see images. */
+    get supportsImages() {
+        return true;
+    }
+    /** Answer the questions in one request. */
+    async _ask(state, questions, images = []) {
+        if (images.length > OPENAI_DECISIONS_MAX_IMAGES) {
+            throw new ClassifierError(`OpenAI Decisions takes at most ${OPENAI_DECISIONS_MAX_IMAGES} images, got ${images.length}`);
+        }
+        const openaiQuestions = {};
+        for (const [name, q] of Object.entries(questions)) {
+            openaiQuestions[name] = this._toOpenai(q);
+        }
+        const [answers, usage] = await this._client.ask(this._input(state, images), openaiQuestions);
+        const results = {};
+        for (const [name, question] of Object.entries(questions)) {
+            results[name] = this._fromOpenai(name, question, answers[name]);
+        }
+        return [
+            results,
+            new LLMTokenUsage({
+                promptTokens: usage.inputTokens,
+                completionTokens: usage.outputTokens,
+                totalTokens: usage.inputTokens + usage.outputTokens,
+            }),
+        ];
+    }
+    /** The request's input: the state as text, or a user message with any images first. */
+    _input(state, images) {
+        const text = this._text(state);
+        if (images.length === 0) {
+            return text;
+        }
+        const content = images.map((image) => ({
+            type: "input_image",
+            image_url: `data:${image.contentType};base64,${bytesToBase64(image.data)}`,
+        }));
+        content.push({ type: "input_text", text });
+        return [{ role: "user", content }];
+    }
+    /** A question in the Decisions API's own format. */
+    _toOpenai(question) {
+        if (question instanceof YesNoQuestion) {
+            // A predicate has no field for what counts as each answer, so it goes
+            // in the instructions.
+            const lines = [this._text(question.instructions)];
+            if (question.yes !== null) {
+                lines.push(`Yes means: ${this._text(question.yes)}`);
+            }
+            if (question.no !== null) {
+                lines.push(`No means: ${this._text(question.no)}`);
+            }
+            return { type: "predicate", instructions: lines.join("\n") };
+        }
+        if (question instanceof ChoiceQuestion) {
+            const count = Object.keys(question.options).length;
+            if (count > OPENAI_DECISIONS_MAX_CHOICE_OPTIONS) {
+                throw new ClassifierError(`OpenAI Decisions takes at most ${OPENAI_DECISIONS_MAX_CHOICE_OPTIONS} options, got ${count}`);
+            }
+            return {
+                type: "choice",
+                instructions: this._text(question.instructions),
+                choices: Object.entries(question.options).map(([option, description]) => description === null
+                    ? { value: option }
+                    : { value: option, description: this._text(description) }),
+            };
+        }
+        return {
+            type: "score",
+            instructions: this._text(question.instructions),
+            levels: question.levels.map((level) => ({ label: this._text(level) })),
+        };
+    }
+    /** A result built from the Decisions API's answer to the question. */
+    _fromOpenai(name, question, answer) {
+        if (answer.type === "refusal") {
+            throw new ClassifierError(`OpenAI Decisions refused to answer '${name}'`);
+        }
+        if (question instanceof YesNoQuestion) {
+            return new YesNoResult({ probability: this._number(answer, "probability") });
+        }
+        if (question instanceof ChoiceQuestion) {
+            const choice = String(answer.choice ?? "");
+            if (!Object.hasOwn(question.options, choice)) {
+                throw new ClassifierError(`OpenAI Decisions chose '${choice}', which is not an option`);
+            }
+            const probabilities = this._probabilities(answer, Object.keys(question.options));
+            return new ChoiceResult({
+                choice,
+                probabilities,
+                confidence: this._number(answer, "confidence"),
+            });
+        }
+        // The Decisions API keys level probabilities by position.
+        const positions = question.levels.map((_level, index) => String(index));
+        const probabilities = this._probabilities(answer, positions);
+        return new ScoreResult({
+            score: this._number(answer, "score"),
+            levels: question.levels.map((level, index) => new ScoreLevel({ level, probability: probabilities[positions[index]] ?? 0 })),
+            confidence: this._number(answer, "confidence"),
+        });
+    }
+    /** Text for the Decisions API: a string as is, structured data as JSON. */
+    _text(value) {
+        return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+    }
+    /** The number the API wrote under `key`, or a ClassifierError if it did not. */
+    _number(answer, key) {
+        try {
+            if (!Object.hasOwn(answer, key)) {
+                throw new RangeError(key);
+            }
+            return toFloat(answer[key]);
+        }
+        catch (e) {
+            rethrowIfCancelled(e);
+            throw new ClassifierError(`OpenAI Decisions reply has no usable '${key}'`, { cause: e });
+        }
+    }
+    /**
+     * The probability the API gave for each key, 0 for the ones it left out.
+     *
+     * The API lists probabilities as `{"value", "probability"}` items, where
+     * the value is a choice's option or a level's position.
+     */
+    _probabilities(answer, keys) {
+        const given = answer.probabilities;
+        const byValue = new Map();
+        for (const item of Array.isArray(given) ? given : []) {
+            if (isDict(item)) {
+                byValue.set(pyStr(item.value), item.probability ?? null);
+            }
+        }
+        try {
+            return Object.fromEntries(keys.map((key) => [key, toFloat(byValue.has(key) ? byValue.get(key) : 0.0)]));
+        }
+        catch (e) {
+            rethrowIfCancelled(e);
+            throw new ClassifierError(`OpenAI Decisions reply has an unusable probability: ${e.message}`, { cause: e });
+        }
+    }
+}
+/** Python's `str()` for a JSON value, so a missing value reads `None` as upstream's does. */
+function pyStr(value) {
+    if (value === undefined || value === null) {
+        return "None";
+    }
+    return String(value);
+}
+//# sourceMappingURL=classifier.js.map

package/dist/classifiers/openai/decisions/client.d.ts

@@ -0,0 +1,108 @@
+/**
+ * HTTP client for OpenAI's Decisions API.
+ *
+ * One `OpenAIDecisionsClient` holds one connection pool, adds the auth
+ * header, retries when OpenAI is busy, and counts the tokens every request
+ * used. Several `OpenAIDecisionsClassifier` instances can share one.
+ *
+ * PORTING NOTE: upstream uses `httpx` with HTTP/2 and a 240 s keep-alive;
+ * here requests go through `fetch` (see `../../http_client.ts`), and
+ * connection reuse is left to the runtime.
+ */
+import { Lock } from "@pipedog/asyncio";
+import { HttpClient, type HttpResponse } from "../../http_client.ts";
+/** Where the API is served. */
+export declare const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+/** The decision model to ask. */
+export declare const DEFAULT_MODEL = "gpt-6-luna";
+/** Seconds to wait for a reply before giving up. */
+export declare const DEFAULT_TIMEOUT = 10;
+export interface OpenAIDecisionsUsageOptions {
+    /** Tokens sent. */
+    inputTokens?: number;
+    /** Tokens received. */
+    outputTokens?: number;
+}
+/**
+ * Tokens the Decisions API used: for one request, or over every request.
+ *
+ * `OpenAIDecisionsClient.usage` holds the total over every request.
+ */
+export declare class OpenAIDecisionsUsage {
+    inputTokens: number;
+    outputTokens: number;
+    constructor(options?: OpenAIDecisionsUsageOptions);
+    /** Build a usage from the API's wire format (`input_tokens`, `output_tokens`). */
+    static fromDict(data: Record<string, unknown>): OpenAIDecisionsUsage;
+}
+export interface OpenAIDecisionsClientOptions {
+    /** OpenAI API key. */
+    apiKey: string;
+    /**
+     * Where the API is served, such as `https://eu.api.openai.com/v1` for data
+     * residency in Europe.
+     */
+    baseUrl?: string;
+    /** The decision model to ask. */
+    model?: string;
+    /** Seconds to wait for a reply before giving up. */
+    timeout?: number;
+    /** How many times to retry a request OpenAI refused because it was busy. */
+    maxRetries?: number;
+    /** The transport requests go through; the global `fetch` by default. */
+    fetch?: typeof fetch;
+}
+/**
+ * HTTP client for OpenAI's `decisions` endpoint.
+ *
+ * Many small requests can be in flight at the same time. Retries with
+ * backoff when OpenAI answers 429 or 503. Counts the tokens every request
+ * used in `usage`. Errors carry the reason OpenAI gave.
+ *
+ * `connect()` opens the connection ahead of the first question, and
+ * `close()` releases it.
+ */
+export declare class OpenAIDecisionsClient {
+    protected _model: string;
+    protected _maxRetries: number;
+    protected _usage: OpenAIDecisionsUsage;
+    protected _connected: boolean;
+    protected _connectLock: Lock;
+    protected _http: HttpClient;
+    constructor(options: OpenAIDecisionsClientOptions);
+    /** The decision model the questions go to. */
+    get model(): string;
+    /** Tokens used so far, over every request. */
+    get usage(): OpenAIDecisionsUsage;
+    /**
+     * Open the connection to OpenAI.
+     *
+     * Looks up the model, a cheap request that also checks the key and whether
+     * it has access to the model. Connects once: a client shared by several
+     * classifiers is asked by each of them, and only the first call sends
+     * anything.
+     *
+     * @throws ClassifierError If OpenAI could not be reached or refused the request.
+     */
+    connect(): Promise<void>;
+    /** Close the connection pool. */
+    close(): Promise<void>;
+    /**
+     * Send questions about one state and return OpenAI's answers.
+     *
+     * @param state What the questions are about, as the request's `input`:
+     *   text, or user messages.
+     * @param questions The questions by name, each in OpenAI's own format: a
+     *   `type` of `predicate`, `choice` or `score`, `instructions`, and
+     *   `choices` or `levels`.
+     * @returns The answers by the same names, in OpenAI's own format, and the
+     *   tokens the request used.
+     * @throws ClassifierError If OpenAI rejected the request, kept refusing it
+     *   because it was busy, could not be reached, or left a question
+     *   unanswered.
+     */
+    ask(state: string | Record<string, unknown>[], questions: Readonly<Record<string, Record<string, unknown>>>): Promise<[Record<string, Record<string, unknown>>, OpenAIDecisionsUsage]>;
+    /** A failed response's HTTP status and the reason OpenAI gave. */
+    protected _failure(response: HttpResponse): string;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/classifiers/openai/decisions/client.js

@@ -0,0 +1,234 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/classifiers/openai/decisions/client.py
+/**
+ * HTTP client for OpenAI's Decisions API.
+ *
+ * One `OpenAIDecisionsClient` holds one connection pool, adds the auth
+ * header, retries when OpenAI is busy, and counts the tokens every request
+ * used. Several `OpenAIDecisionsClassifier` instances can share one.
+ *
+ * PORTING NOTE: upstream uses `httpx` with HTTP/2 and a 240 s keep-alive;
+ * here requests go through `fetch` (see `../../http_client.ts`), and
+ * connection reuse is left to the runtime.
+ */
+import { Lock, rethrowIfCancelled, sleep } from "@pipedog/asyncio";
+import { logger } from "../../../utils/logger.js";
+import { exponentialBackoffTime } from "../../../utils/network.js";
+import { ClassifierError } from "../../base_classifier.js";
+import { errorRepr, HttpClient, HttpError, isDict } from "../../http_client.js";
+/** OpenAI answers a request with this status when the caller is rate limited. */
+const TOO_MANY_REQUESTS = 429;
+/** OpenAI answers a request with this status when it is temporarily overloaded. */
+const OVERLOADED = 503;
+/** Where the API is served. */
+export const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+/** The decision model to ask. */
+export const DEFAULT_MODEL = "gpt-6-luna";
+/** Seconds to wait for a reply before giving up. */
+export const DEFAULT_TIMEOUT = 10.0;
+/**
+ * Tokens the Decisions API used: for one request, or over every request.
+ *
+ * `OpenAIDecisionsClient.usage` holds the total over every request.
+ */
+export class OpenAIDecisionsUsage {
+    inputTokens;
+    outputTokens;
+    constructor(options = {}) {
+        this.inputTokens = options.inputTokens ?? 0;
+        this.outputTokens = options.outputTokens ?? 0;
+    }
+    /** Build a usage from the API's wire format (`input_tokens`, `output_tokens`). */
+    static fromDict(data) {
+        return new OpenAIDecisionsUsage({
+            inputTokens: data.input_tokens ?? 0,
+            outputTokens: data.output_tokens ?? 0,
+        });
+    }
+}
+/**
+ * HTTP client for OpenAI's `decisions` endpoint.
+ *
+ * Many small requests can be in flight at the same time. Retries with
+ * backoff when OpenAI answers 429 or 503. Counts the tokens every request
+ * used in `usage`. Errors carry the reason OpenAI gave.
+ *
+ * `connect()` opens the connection ahead of the first question, and
+ * `close()` releases it.
+ */
+export class OpenAIDecisionsClient {
+    _model;
+    _maxRetries;
+    _usage = new OpenAIDecisionsUsage();
+    _connected = false;
+    _connectLock = new Lock();
+    _http;
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new Error("OpenAIDecisionsClient needs an API key");
+        }
+        this._model = options.model ?? DEFAULT_MODEL;
+        this._maxRetries = options.maxRetries ?? 3;
+        this._http = new HttpClient({
+            baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+            headers: { Authorization: `Bearer ${options.apiKey}` },
+            timeout: options.timeout ?? DEFAULT_TIMEOUT,
+            fetch: options.fetch,
+        });
+    }
+    /** The decision model the questions go to. */
+    get model() {
+        return this._model;
+    }
+    /** Tokens used so far, over every request. */
+    get usage() {
+        return this._usage;
+    }
+    /**
+     * Open the connection to OpenAI.
+     *
+     * Looks up the model, a cheap request that also checks the key and whether
+     * it has access to the model. Connects once: a client shared by several
+     * classifiers is asked by each of them, and only the first call sends
+     * anything.
+     *
+     * @throws ClassifierError If OpenAI could not be reached or refused the request.
+     */
+    async connect() {
+        await this._connectLock.run(async () => {
+            if (this._connected) {
+                return;
+            }
+            let response;
+            try {
+                response = await this._http.get(`/models/${this._model}`);
+            }
+            catch (e) {
+                if (e instanceof HttpError) {
+                    throw new ClassifierError(`could not connect to OpenAI Decisions: ${e.message}`, {
+                        cause: e,
+                    });
+                }
+                throw e;
+            }
+            if (response.statusCode !== 200) {
+                throw new ClassifierError(`OpenAI Decisions refused the connection: ${this._failure(response)}`);
+            }
+            this._connected = true;
+        });
+    }
+    /** Close the connection pool. */
+    async close() {
+        this._connected = false;
+        await this._http.aclose();
+    }
+    /**
+     * Send questions about one state and return OpenAI's answers.
+     *
+     * @param state What the questions are about, as the request's `input`:
+     *   text, or user messages.
+     * @param questions The questions by name, each in OpenAI's own format: a
+     *   `type` of `predicate`, `choice` or `score`, `instructions`, and
+     *   `choices` or `levels`.
+     * @returns The answers by the same names, in OpenAI's own format, and the
+     *   tokens the request used.
+     * @throws ClassifierError If OpenAI rejected the request, kept refusing it
+     *   because it was busy, could not be reached, or left a question
+     *   unanswered.
+     */
+    async ask(state, questions) {
+        const body = {
+            model: this._model,
+            input: state,
+            questions: Object.entries(questions).map(([name, question]) => ({ name, ...question })),
+        };
+        let attempt = 0;
+        while (true) {
+            attempt += 1;
+            let response;
+            try {
+                response = await this._http.post("/decisions", { json: body });
+            }
+            catch (e) {
+                if (e instanceof HttpError) {
+                    // Some errors, such as a timeout, carry no useful message.
+                    throw new ClassifierError(`OpenAI Decisions request failed: ${errorRepr(e)}`, {
+                        cause: e,
+                    });
+                }
+                throw e;
+            }
+            if (response.statusCode === TOO_MANY_REQUESTS || response.statusCode === OVERLOADED) {
+                if (attempt > this._maxRetries) {
+                    throw new ClassifierError(`OpenAI Decisions is busy (${this._failure(response)}) after ${attempt} attempts`);
+                }
+                const wait = exponentialBackoffTime(attempt, 0.25, 2.0, 0.25);
+                logger.debug(`OpenAI Decisions answered ${response.statusCode}, retrying in ${wait}s`);
+                await sleep(wait);
+                continue;
+            }
+            if (response.statusCode !== 200) {
+                throw new ClassifierError(`OpenAI Decisions rejected the request: ${this._failure(response)}`);
+            }
+            let data;
+            try {
+                data = response.json();
+            }
+            catch (e) {
+                rethrowIfCancelled(e);
+                throw new ClassifierError(`OpenAI Decisions reply is not valid JSON: ${e.message}`, { cause: e });
+            }
+            if (!isDict(data)) {
+                throw new ClassifierError("OpenAI Decisions reply is not a JSON object");
+            }
+            const usage = data.usage;
+            const requestUsage = isDict(usage)
+                ? OpenAIDecisionsUsage.fromDict(usage)
+                : new OpenAIDecisionsUsage();
+            this._usage.inputTokens += requestUsage.inputTokens;
+            this._usage.outputTokens += requestUsage.outputTokens;
+            const answers = data.answers;
+            if (!Array.isArray(answers)) {
+                throw new ClassifierError("OpenAI Decisions reply has no answers");
+            }
+            // Answers come back as a list, each carrying its question's name.
+            const byName = new Map();
+            for (const answer of answers) {
+                if (isDict(answer) && typeof answer.name === "string") {
+                    byName.set(answer.name, answer);
+                }
+            }
+            const missing = Object.keys(questions).filter((name) => !byName.has(name));
+            if (missing.length > 0) {
+                throw new ClassifierError(`OpenAI Decisions reply has no answer for ${missing.join(", ")}`);
+            }
+            const result = {};
+            for (const name of Object.keys(questions)) {
+                result[name] = byName.get(name);
+            }
+            return [result, requestUsage];
+        }
+    }
+    /** A failed response's HTTP status and the reason OpenAI gave. */
+    _failure(response) {
+        const status = `HTTP ${response.statusCode}`;
+        let message;
+        try {
+            const data = response.json();
+            const error = isDict(data) ? data.error : undefined;
+            if (!isDict(error) || !("message" in error)) {
+                return status;
+            }
+            message = error.message;
+        }
+        catch (e) {
+            rethrowIfCancelled(e);
+            return status;
+        }
+        return message ? `${status}: ${message}` : status;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/classifiers/openai/decisions/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/classifiers/openai/decisions/index.js

@@ -0,0 +1,8 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/classifiers/openai/decisions/__init__.py
+// Upstream's `__init__.py` is empty: import the package's modules directly.
+export {};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/classifiers/openai/index.js

@@ -0,0 +1,8 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/classifiers/openai/__init__.py
+// Upstream's `__init__.py` is empty: import the package's modules directly.
+export {};
+//# sourceMappingURL=index.js.map

package/dist/classifiers/typesafe/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/classifiers/typesafe/index.js

@@ -0,0 +1,8 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/classifiers/typesafe/__init__.py
+// Upstream's `__init__.py` is empty: import the package's modules directly.
+export {};
+//# sourceMappingURL=index.js.map