@pipedog/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2024–2026, Daily
+Copyright (c) 2026, pipedog contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/NOTICE

@@ -0,0 +1,9 @@
+pipedog is an unofficial TypeScript port of Pipecat (https://github.com/pipecat-ai/pipecat),
+a framework for voice and multimodal conversational AI created by Daily.
+
+It is not affiliated with or endorsed by Daily. Pipecat is distributed under
+the BSD 2-Clause License, Copyright (c) 2024–2026, Daily; that copyright notice
+and license are retained in LICENSE, and every ported source file carries a
+header naming the upstream file it was derived from.
+
+The upstream commit each file was ported from is recorded in porting/manifest.json.

package/dist/adapters/base_llm_adapter.d.ts

@@ -0,0 +1,266 @@
+import { type LLMContext, type LLMContextMessage, LLMSpecificMessage, type NotGiven } from "../processors/aggregators/llm_context.ts";
+import type { FileResolver } from "../utils/file_resolver.ts";
+import type { FunctionSchema } from "./schemas/function_schema.ts";
+import { ToolsSchema } from "./schemas/tools_schema.ts";
+type Dict = Record<string, any>;
+/** The scheme of a URL, lowercased (Python's `urlsplit(url).scheme`). */
+export declare function urlScheme(url: string): string;
+/**
+ * Raised when converting a universal `LLMContext` to a provider's message
+ * format fails.
+ *
+ * Adapters that transform context messages into a provider-specific format
+ * throw this from their conversion routine, wrapping the underlying error
+ * (preserved as `cause`). Its message identifies the failure as a
+ * context-mapping problem and carries the underlying cause. The corresponding
+ * LLM service catches this and surfaces it in the `ErrorFrame` it pushes
+ * upstream.
+ */
+export declare class LLMContextConversionError extends Error {
+    name: string;
+    /**
+     * @param cause The underlying error raised during message conversion.
+     */
+    constructor(cause: unknown);
+}
+/**
+ * Abstract base class for LLM provider adapters.
+ *
+ * Provides a standard interface for converting to provider-specific formats.
+ *
+ * Handles:
+ *
+ * - Extracting provider-specific parameters for LLM invocation from a
+ *   universal LLM context
+ * - Converting standardized tools schema to provider-specific tool formats.
+ * - Extracting messages from the LLM context for the purposes of logging
+ *   about the specific provider.
+ * - Resolving conflicts between `systemInstruction` and initial
+ *   system/developer messages in the conversation context.
+ *
+ * Subclasses must implement provider-specific conversion logic.
+ */
+export declare abstract class BaseLLMAdapter<TLLMInvocationParams = Record<string, unknown>> {
+    protected _warnedSystemInstruction: boolean;
+    protected _warnedContextSystemMessage: boolean;
+    protected _builtinTools: Record<string, FunctionSchema>;
+    protected _fileResolver: FileResolver | null;
+    prefersRawFileBytes: boolean;
+    /**
+     * Built-in tools automatically merged into every inference request.
+     *
+     * Keyed by tool name for O(1) lookup, insertion, and removal (`delete`). The service
+     * injects tools here so they are sent transparently on every inference
+     * request without the user having to add them to their `ToolsSchema`.
+     */
+    get builtinTools(): Record<string, FunctionSchema>;
+    /** The identifier used in LLMSpecificMessage instances for this LLM provider. */
+    abstract get idForLlmSpecificMessages(): string;
+    /**
+     * Get provider-specific LLM invocation parameters from a universal LLM
+     * context.
+     *
+     * An adapter whose provider takes files awaits `prepareFileContent()`
+     * first, so the files its conversion inlines are in the `fileResolver`'s
+     * caches.
+     *
+     * @param context The LLM context containing messages, tools, etc.
+     * @param options Additional provider-specific arguments that subclasses can use.
+     * @returns Provider-specific parameters for invoking the LLM.
+     */
+    abstract getLlmInvocationParams(context: LLMContext, options?: object): Promise<TLLMInvocationParams>;
+    /**
+     * Convert tools schema to the provider's specific format.
+     *
+     * @param toolsSchema The standardized tools schema to convert.
+     * @returns List of tools in the provider's expected format.
+     */
+    abstract toProviderToolsFormat(toolsSchema: ToolsSchema): unknown[];
+    /**
+     * Get messages from a universal LLM context in a format ready for logging
+     * about this provider.
+     *
+     * @param context The LLM context containing messages.
+     * @returns List of messages in a format ready for logging about this provider.
+     */
+    abstract getMessagesForLogging(context: LLMContext): Record<string, unknown>[];
+    /**
+     * The resolver that fetches and caches file content for this adapter.
+     *
+     * Set once by the owning LLM service. Every conversion this adapter
+     * performs — invocation params and logging alike — reads the same resolver
+     * caches. Without one, conversion still passes through URLs the provider
+     * consumes directly, but fails on any file that would need fetching.
+     */
+    get fileResolver(): FileResolver | null;
+    set fileResolver(resolver: FileResolver | null);
+    /**
+     * Whether the provider can be handed `url` to fetch itself.
+     *
+     * This covers both URLs the provider fetches over the public internet and
+     * cloud-storage URIs it resolves through its own IAM (e.g. Bedrock reading
+     * `s3://`). A URL the provider can't consume is instead fetched into the
+     * file resolver's cache and inlined at conversion — see
+     * `prepareFileContent()`.
+     *
+     * @param url The file URL from a `file_url` context content item.
+     * @param mimeType The file's MIME type.
+     * @returns True if conversion can pass `url` through to the provider.
+     */
+    supportsFileUrl(_url: string, _mimeType: string): boolean;
+    /**
+     * Fetch the file content this provider will need into the resolver's caches.
+     *
+     * A `file_url` item whose URL the provider consumes directly
+     * (`supportsFileUrl()`, and — for `http(s)` — publicly routable) needs
+     * nothing. Any other `file_url` item is fetched into the `fileResolver`'s
+     * cache, in the form this provider's conversion reads: raw bytes when
+     * `prefersRawFileBytes`, a base64 data URL otherwise. Inline `file_base64`
+     * items get their decoded bytes cached for raw-bytes providers. The
+     * resolver caches by URL, so each file is fetched once no matter how many
+     * turns — or how many adapters sharing the resolver — consume it; only the
+     * per-provider pass-through decision is re-evaluated here on every run.
+     *
+     * An adapter whose conversion inlines files (through `inlinedFileContent()`
+     * or `decodedFileBytes()`) awaits this at the start of
+     * `getLlmInvocationParams()`. An adapter for a provider that doesn't take
+     * files doesn't call it, so nothing is fetched for that provider.
+     *
+     * @param context The LLM context whose messages to resolve.
+     * @throws LLMContextConversionError If a file URL can't be resolved (refused
+     *   by the reachability policy, download failure, unresolvable scheme,
+     *   corrupt base64). The service handles it like any other conversion
+     *   failure, including invalid-file-message cleanup.
+     */
+    prepareFileContent(context: LLMContext): Promise<void>;
+    /** Whether `url` can be handed to the provider to fetch itself. */
+    protected _canPassFileUrl(url: string, mimeType: string, resolver: FileResolver): Promise<boolean>;
+    /**
+     * Return the content to inline for a `file_url` item, or null when the URL
+     * passes through.
+     *
+     * @param fileData The item's `file` object (`url`, `mime_type`, ...).
+     * @returns null when the URL passes through for the provider to fetch
+     *   itself; otherwise the resolved content from the `fileResolver`'s caches
+     *   — raw bytes when `prefersRawFileBytes`, a base64 data URL otherwise.
+     * @throws Error If the provider can't consume the URL and no resolved
+     *   content is cached (wrapped as `LLMContextConversionError` by the
+     *   conversion routine's caller).
+     */
+    inlinedFileContent(fileData: Readonly<Dict>): Uint8Array | string | null;
+    /**
+     * Return a `file_base64` item's decoded bytes, from the resolver's cache
+     * when prepared.
+     *
+     * Falls back to decoding inline for conversion-only calls where no
+     * resolution has run.
+     *
+     * @param fileData The item's `file` object (`file_data`, ...).
+     */
+    decodedFileBytes(fileData: Readonly<Dict>): Uint8Array;
+    /**
+     * Create an LLM-specific message (as opposed to a standard message) for use
+     * in an LLMContext.
+     *
+     * @param message The message content.
+     * @returns A LLMSpecificMessage instance.
+     */
+    createLlmSpecificMessage(message: unknown): LLMSpecificMessage;
+    /**
+     * Get messages from the LLM context, including standard and LLM-specific
+     * messages.
+     *
+     * @param context The LLM context containing messages.
+     * @param options.truncateLargeValues If true, return deep copies of messages
+     *   with large values replaced by short placeholders.
+     * @returns List of messages including standard and LLM-specific messages.
+     */
+    getMessages(context: LLMContext, options?: {
+        truncateLargeValues?: boolean;
+    }): LLMContextMessage[];
+    /**
+     * The tools a realtime session carries, in provider format.
+     *
+     * The context's own tools when it has any, else the init-provided ones.
+     * Built-in tools ride along with whichever set is in use, and are the set
+     * when there is neither.
+     *
+     * @param contextTools The context's tools (`NOT_GIVEN` or `null` when it has
+     *   none).
+     * @param serviceTools The service's init-provided tools, as
+     *   `_serviceTools()` returns them: a `ToolsSchema` or a provider-native
+     *   tool list, or `null`.
+     * @returns The tools, or `null` when there are none at all.
+     */
+    protected _realtimeSessionTools(contextTools: unknown, serviceTools: unknown): unknown[] | null;
+    /**
+     * Convert tools from standard format to provider format.
+     *
+     * Built-in tools are automatically merged into the schema before conversion
+     * so that every inference request receives them without the user having to
+     * declare them explicitly; when there are no other tools, they are the tool
+     * set.
+     *
+     * @param tools Tools in standard format or provider-specific format.
+     * @returns List of tools converted to provider format, or original tools
+     *   (possibly `null`) if not in standard format.
+     */
+    fromStandardTools(tools: unknown): unknown[] | NotGiven | null;
+    /**
+     * Warn once that the initial `"system"` context message is deprecated.
+     *
+     * The system prompt belongs on the LLM service, where it composes with the
+     * instructions the framework contributes — appended instructions,
+     * turn-completion guidance, async-tool guidance. A prompt carried in the
+     * context bypasses that composition, and providers that take the system
+     * instruction as a separate parameter drop it entirely when the service
+     * also has one.
+     */
+    protected _warnContextSystemMessage(): void;
+    /**
+     * Extract an initial `"system"` message for use as a system instruction.
+     *
+     * Only useful for services that expect the system instruction as a separate
+     * parameter, not inline in conversation history (today, all non-OpenAI
+     * services). Does not extract `"developer"` messages — those are converted
+     * to `"user"` by the adapter's subsequent message loop, like any other
+     * non-system role the provider doesn't support.
+     *
+     * Checks `messages[0]`. If the role is `"system"`, removes it and returns
+     * its content. If extracting would leave the messages list empty
+     * (`messages.length === 1`), the message is converted to `"user"` role
+     * instead of being extracted, to prevent sending an empty conversation
+     * history to providers that require at least one non-system message.
+     *
+     * @param messages Message list in standard format. The list is mutated
+     *   in-place; the message objects it holds are never mutated, since they are
+     *   shared with the source LLMContext.
+     * @param options.systemInstruction The system instruction from service
+     *   settings or `runInference`. Only used to decide whether to warn about a
+     *   conflict in the single-message case.
+     * @returns The extracted system message content, or `null` if nothing was
+     *   extracted.
+     */
+    protected _extractInitialSystem(messages: Dict[], options?: {
+        systemInstruction?: string | null;
+    }): string | null;
+    /**
+     * Resolve conflict between `systemInstruction` and an extracted context
+     * system message.
+     *
+     * @param systemFromContext Content extracted from an initial `"system"`
+     *   message by `_extractInitialSystem()`, or detected inline (OpenAI
+     *   adapters).
+     * @param systemInstruction From service settings or `runInference` param.
+     * @param options.discardContextSystem If true (non-OpenAI adapters), the
+     *   context system message is discarded when `systemInstruction` is also
+     *   present. If false (OpenAI adapters), both are kept.
+     * @returns The effective system instruction to use, or `null` if the system
+     *   instruction is already represented in the messages (OpenAI path).
+     */
+    protected _resolveSystemInstruction(systemFromContext: string | null, systemInstruction: string | null, options: {
+        discardContextSystem: boolean;
+    }): string | null;
+}
+export {};
+//# sourceMappingURL=base_llm_adapter.d.ts.map