@hotmeshio/long-tail 0.1.0

package/build/services/llm/translate.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Message format translation between OpenAI (canonical) and Anthropic.
+ *
+ * OpenAI's chat completion format is the canonical representation used
+ * throughout the codebase. This module translates to/from Anthropic's
+ * format when a Claude model is selected.
+ */
+import type { ChatMessage, ToolDefinition, LLMResponse } from './types';
+interface AnthropicMessage {
+    role: 'user' | 'assistant';
+    content: string | AnthropicContentBlock[];
+}
+type AnthropicContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+};
+interface AnthropicTool {
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+}
+/**
+ * Extract system messages and translate the rest for Anthropic's API.
+ */
+export declare function translateMessagesToAnthropic(messages: ChatMessage[]): {
+    system: string;
+    messages: AnthropicMessage[];
+};
+/**
+ * Translate OpenAI tool definitions to Anthropic format.
+ */
+export declare function translateToolsToAnthropic(tools: ToolDefinition[]): AnthropicTool[];
+/**
+ * Translate an Anthropic response to our canonical LLMResponse.
+ */
+export declare function translateAnthropicResponse(response: {
+    content: Array<{
+        type: string;
+        text?: string;
+        id?: string;
+        name?: string;
+        input?: unknown;
+    }>;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    stop_reason?: string;
+}): LLMResponse;
+export {};

package/build/services/llm/translate.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * Message format translation between OpenAI (canonical) and Anthropic.
+ *
+ * OpenAI's chat completion format is the canonical representation used
+ * throughout the codebase. This module translates to/from Anthropic's
+ * format when a Claude model is selected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translateMessagesToAnthropic = translateMessagesToAnthropic;
+exports.translateToolsToAnthropic = translateToolsToAnthropic;
+exports.translateAnthropicResponse = translateAnthropicResponse;
+/**
+ * Extract system messages and translate the rest for Anthropic's API.
+ */
+function translateMessagesToAnthropic(messages) {
+    // 1. Extract system messages into a single system string
+    const systemParts = [];
+    const nonSystem = [];
+    for (const msg of messages) {
+        if (msg.role === 'system') {
+            const text = typeof msg.content === 'string'
+                ? msg.content
+                : Array.isArray(msg.content)
+                    ? msg.content.filter(p => p.type === 'text').map(p => p.text).join('\n')
+                    : '';
+            if (text)
+                systemParts.push(text);
+        }
+        else {
+            nonSystem.push(msg);
+        }
+    }
+    // 2. Translate non-system messages
+    const translated = [];
+    for (const msg of nonSystem) {
+        if (msg.role === 'assistant') {
+            const blocks = [];
+            // Text content
+            if (typeof msg.content === 'string' && msg.content) {
+                blocks.push({ type: 'text', text: msg.content });
+            }
+            // Tool calls → tool_use blocks
+            if (msg.tool_calls?.length) {
+                for (const tc of msg.tool_calls) {
+                    let input = {};
+                    try {
+                        input = JSON.parse(tc.function.arguments || '{}');
+                    }
+                    catch { /* empty */ }
+                    blocks.push({
+                        type: 'tool_use',
+                        id: tc.id,
+                        name: tc.function.name,
+                        input,
+                    });
+                }
+            }
+            if (blocks.length > 0) {
+                translated.push({ role: 'assistant', content: blocks });
+            }
+            else {
+                // Empty assistant message — use empty text
+                translated.push({ role: 'assistant', content: [{ type: 'text', text: '' }] });
+            }
+        }
+        else if (msg.role === 'tool') {
+            // Tool result → merge into preceding or new user message
+            const toolResult = {
+                type: 'tool_result',
+                tool_use_id: msg.tool_call_id || '',
+                content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+            };
+            // Anthropic requires tool_result in a user message
+            const last = translated[translated.length - 1];
+            if (last?.role === 'user' && Array.isArray(last.content)) {
+                last.content.push(toolResult);
+            }
+            else {
+                translated.push({ role: 'user', content: [toolResult] });
+            }
+        }
+        else {
+            // User message
+            const content = translateContentToAnthropic(msg.content);
+            translated.push({ role: 'user', content });
+        }
+    }
+    // 3. Anthropic requires alternating user/assistant. Merge consecutive same-role.
+    const merged = mergeConsecutiveRoles(translated);
+    return { system: systemParts.join('\n\n'), messages: merged };
+}
+/**
+ * Translate content parts from OpenAI to Anthropic format.
+ */
+function translateContentToAnthropic(content) {
+    if (content === null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    const blocks = [];
+    for (const part of content) {
+        if (part.type === 'text') {
+            blocks.push({ type: 'text', text: part.text });
+        }
+        else if (part.type === 'image_url') {
+            const parsed = parseDataUrl(part.image_url.url);
+            if (parsed) {
+                blocks.push({
+                    type: 'image',
+                    source: { type: 'base64', media_type: parsed.mediaType, data: parsed.data },
+                });
+            }
+        }
+    }
+    return blocks.length > 0 ? blocks : '';
+}
+/**
+ * Parse a data: URL into media type and base64 data.
+ */
+function parseDataUrl(url) {
+    const match = url.match(/^data:([^;]+);base64,(.+)$/);
+    if (match)
+        return { mediaType: match[1], data: match[2] };
+    // For regular URLs, Anthropic can't handle them — would need to fetch
+    return null;
+}
+/**
+ * Merge consecutive messages with the same role (Anthropic requirement).
+ */
+function mergeConsecutiveRoles(messages) {
+    const merged = [];
+    for (const msg of messages) {
+        const last = merged[merged.length - 1];
+        if (last?.role === msg.role) {
+            // Merge content
+            const lastBlocks = Array.isArray(last.content)
+                ? last.content
+                : [{ type: 'text', text: last.content }];
+            const newBlocks = Array.isArray(msg.content)
+                ? msg.content
+                : [{ type: 'text', text: msg.content }];
+            last.content = [...lastBlocks, ...newBlocks];
+        }
+        else {
+            merged.push({ ...msg });
+        }
+    }
+    return merged;
+}
+/**
+ * Translate OpenAI tool definitions to Anthropic format.
+ */
+function translateToolsToAnthropic(tools) {
+    return tools.map(t => ({
+        name: t.function.name,
+        description: t.function.description,
+        input_schema: t.function.parameters || { type: 'object', properties: {} },
+    }));
+}
+// ── Anthropic → OpenAI (response translation) ────────────────────────────────
+/**
+ * Translate an Anthropic response to our canonical LLMResponse.
+ */
+function translateAnthropicResponse(response) {
+    let textContent = '';
+    const toolCalls = [];
+    for (const block of response.content) {
+        if (block.type === 'text' && block.text) {
+            textContent += block.text;
+        }
+        else if (block.type === 'tool_use') {
+            toolCalls.push({
+                id: block.id || `call_${Math.random().toString(36).slice(2, 10)}`,
+                type: 'function',
+                function: {
+                    name: block.name || '',
+                    arguments: JSON.stringify(block.input || {}),
+                },
+            });
+        }
+    }
+    return {
+        content: textContent || null,
+        tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
+        usage: response.usage ? {
+            prompt_tokens: response.usage.input_tokens,
+            completion_tokens: response.usage.output_tokens,
+            total_tokens: response.usage.input_tokens + response.usage.output_tokens,
+        } : undefined,
+    };
+}

package/build/services/llm/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Model-agnostic LLM types.
+ *
+ * Uses OpenAI's message format as the canonical representation.
+ * All providers translate to/from this format internally.
+ */
+export interface TextContent {
+    type: 'text';
+    text: string;
+}
+export interface ImageUrlContent {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+export type ContentPart = TextContent | ImageUrlContent;
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | ContentPart[] | null;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+    name?: string;
+}
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface LLMOptions {
+    model: string;
+    messages: ChatMessage[];
+    tools?: ToolDefinition[];
+    max_tokens?: number;
+    temperature?: number;
+    response_format?: {
+        type: 'json_object' | 'text';
+    };
+}
+export interface LLMResponse {
+    content: string | null;
+    tool_calls?: ToolCall[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+export interface LLMProvider {
+    call(options: LLMOptions): Promise<LLMResponse>;
+}
+export type ProviderName = 'openai' | 'anthropic' | 'openai-compatible';

package/build/services/llm/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Model-agnostic LLM types.
+ *
+ * Uses OpenAI's message format as the canonical representation.
+ * All providers translate to/from this format internally.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/services/logger/index.d.ts

@@ -0,0 +1,32 @@
+import type { LTLoggerAdapter } from '../../types/logger';
+/**
+ * Singleton registry for the logging adapter.
+ *
+ * Follows the same pattern as telemetryRegistry and eventRegistry:
+ * - register(adapter) — set the logging adapter
+ * - clear()           — reset (for tests)
+ *
+ * When no adapter is registered, all methods fall back to console.*.
+ */
+declare class LTLoggerRegistry implements LTLoggerAdapter {
+    private adapter;
+    /**
+     * Register a logging adapter. Replaces any previously registered adapter.
+     */
+    register(adapter: LTLoggerAdapter): void;
+    /**
+     * Remove the adapter and reset state. Used in tests.
+     */
+    clear(): void;
+    /**
+     * Check if an adapter is registered.
+     */
+    get hasAdapter(): boolean;
+    info(msg: string, context?: Record<string, any>): void;
+    warn(msg: string, context?: Record<string, any>): void;
+    error(msg: string, context?: Record<string, any>): void;
+    debug(msg: string, context?: Record<string, any>): void;
+}
+/** Singleton logger registry */
+export declare const loggerRegistry: LTLoggerRegistry;
+export {};

package/build/services/logger/index.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loggerRegistry = void 0;
+/**
+ * Singleton registry for the logging adapter.
+ *
+ * Follows the same pattern as telemetryRegistry and eventRegistry:
+ * - register(adapter) — set the logging adapter
+ * - clear()           — reset (for tests)
+ *
+ * When no adapter is registered, all methods fall back to console.*.
+ */
+class LTLoggerRegistry {
+    constructor() {
+        this.adapter = null;
+    }
+    /**
+     * Register a logging adapter. Replaces any previously registered adapter.
+     */
+    register(adapter) {
+        this.adapter = adapter;
+    }
+    /**
+     * Remove the adapter and reset state. Used in tests.
+     */
+    clear() {
+        this.adapter = null;
+    }
+    /**
+     * Check if an adapter is registered.
+     */
+    get hasAdapter() {
+        return this.adapter !== null;
+    }
+    info(msg, context) {
+        if (this.adapter) {
+            this.adapter.info(msg, context);
+        }
+        else {
+            console.log(msg);
+        }
+    }
+    warn(msg, context) {
+        if (this.adapter) {
+            this.adapter.warn(msg, context);
+        }
+        else {
+            console.warn(msg);
+        }
+    }
+    error(msg, context) {
+        if (this.adapter) {
+            this.adapter.error(msg, context);
+        }
+        else {
+            console.error(msg);
+        }
+    }
+    debug(msg, context) {
+        if (this.adapter) {
+            this.adapter.debug(msg, context);
+        }
+        else {
+            console.debug(msg);
+        }
+    }
+}
+/** Singleton logger registry */
+exports.loggerRegistry = new LTLoggerRegistry();

package/build/services/logger/pino.d.ts

@@ -0,0 +1,24 @@
+import type { LoggerOptions } from 'pino';
+import type { LTLoggerAdapter } from '../../types/logger';
+/**
+ * Pino-based logging adapter.
+ *
+ * JSON output by default, sub-millisecond serialization, first-class
+ * TypeScript types, and native OpenTelemetry integration via
+ * `@opentelemetry/instrumentation-pino`.
+ *
+ * Usage:
+ * ```typescript
+ * import { loggerRegistry, PinoLoggerAdapter } from '@hotmeshio/long-tail';
+ *
+ * loggerRegistry.register(new PinoLoggerAdapter({ level: 'debug' }));
+ * ```
+ */
+export declare class PinoLoggerAdapter implements LTLoggerAdapter {
+    private logger;
+    constructor(options?: LoggerOptions);
+    info(msg: string, context?: Record<string, any>): void;
+    warn(msg: string, context?: Record<string, any>): void;
+    error(msg: string, context?: Record<string, any>): void;
+    debug(msg: string, context?: Record<string, any>): void;
+}

package/build/services/logger/pino.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PinoLoggerAdapter = void 0;
+const pino_1 = __importDefault(require("pino"));
+/**
+ * Pino-based logging adapter.
+ *
+ * JSON output by default, sub-millisecond serialization, first-class
+ * TypeScript types, and native OpenTelemetry integration via
+ * `@opentelemetry/instrumentation-pino`.
+ *
+ * Usage:
+ * ```typescript
+ * import { loggerRegistry, PinoLoggerAdapter } from '@hotmeshio/long-tail';
+ *
+ * loggerRegistry.register(new PinoLoggerAdapter({ level: 'debug' }));
+ * ```
+ */
+class PinoLoggerAdapter {
+    constructor(options) {
+        this.logger = (0, pino_1.default)(options);
+    }
+    info(msg, context) {
+        if (context) {
+            this.logger.info(context, msg);
+        }
+        else {
+            this.logger.info(msg);
+        }
+    }
+    warn(msg, context) {
+        if (context) {
+            this.logger.warn(context, msg);
+        }
+        else {
+            this.logger.warn(msg);
+        }
+    }
+    error(msg, context) {
+        if (context) {
+            this.logger.error(context, msg);
+        }
+        else {
+            this.logger.error(msg);
+        }
+    }
+    debug(msg, context) {
+        if (context) {
+            this.logger.debug(context, msg);
+        }
+        else {
+            this.logger.debug(msg);
+        }
+    }
+}
+exports.PinoLoggerAdapter = PinoLoggerAdapter;

package/build/services/maintenance/index.d.ts

@@ -0,0 +1,43 @@
+import type { LTMaintenanceConfig } from '../../types/maintenance';
+/**
+ * Singleton registry for automatic database maintenance.
+ *
+ * Follows the same pattern as telemetryRegistry and eventRegistry:
+ * - register(config) — set the maintenance schedule and rules
+ * - connect()        — start the Virtual.cron
+ * - disconnect()     — interrupt the cron
+ * - clear()          — reset (for tests)
+ */
+declare class LTMaintenanceRegistry {
+    private _config;
+    private connected;
+    /**
+     * Register a maintenance configuration. Call before connect().
+     * Replaces any previously registered config.
+     */
+    register(config: LTMaintenanceConfig): void;
+    /**
+     * Start the maintenance cron using Virtual.cron().
+     * Idempotent — given the same CRON_ID, restarts won't duplicate.
+     */
+    connect(): Promise<void>;
+    /**
+     * Interrupt the running cron. Call during graceful shutdown.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Remove config and reset state. Used in tests.
+     */
+    clear(): void;
+    /**
+     * Check if a config is registered.
+     */
+    get hasConfig(): boolean;
+    /**
+     * Get the current config.
+     */
+    get config(): LTMaintenanceConfig | null;
+}
+/** Singleton maintenance registry */
+export declare const maintenanceRegistry: LTMaintenanceRegistry;
+export {};