lemura 1.0.0

package/dist/adapters-BSkhv5ac.d.ts

@@ -0,0 +1,208 @@
+import { I as IToolDefinition } from './storage-BGu4Loao.js';
+
+interface ContentBlock {
+    type: string;
+    text?: string;
+    imageUrl?: string;
+    [key: string]: unknown;
+}
+interface ToolResult {
+    toolCallId: string;
+    content: string;
+}
+interface Turn {
+    role: 'user' | 'assistant' | 'tool' | 'system';
+    content: string | ContentBlock[];
+    tokenCount: number;
+    turnIndex: number;
+    compressed: boolean;
+    toolCalls?: ToolCall[];
+    toolResults?: ToolResult[];
+}
+interface ContextWindow {
+    systemPrompt: string;
+    scratchpad: string;
+    turns: Turn[];
+    tokenCount: number;
+    maxTokens: number;
+    compressionSummary?: string;
+    metadata: Record<string, unknown>;
+}
+interface IContextStrategy {
+    name: string;
+    priority: number;
+    shouldApply(ctx: ContextWindow): boolean;
+    apply(ctx: ContextWindow): Promise<ContextWindow>;
+}
+
+/** Represents a single message in the provider format */
+interface NormalizedMessage {
+    /** The role of the message sender */
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /** The text or multimodal content of the message */
+    content: string | ContentBlock[];
+    /** Name of the tool, required if role is 'tool' */
+    name?: string;
+    /** Tool calls made by the assistant, present if role is 'assistant' */
+    toolCalls?: ToolCall[];
+}
+/** A request strictly normalized for the provider */
+interface CompletionRequest {
+    /** Model ID to use */
+    model: string;
+    /** The array of messages to send to the provider */
+    messages: NormalizedMessage[];
+    /** Optional array of tool definitions */
+    tools?: IToolDefinition[];
+    /** Maximum number of tokens to generate */
+    maxTokens?: number;
+    /** Generation temperature */
+    temperature?: number;
+    /** Optional array of sequences that will stop generation */
+    stopSequences?: string[];
+    /** Whether to stream the response back */
+    stream?: boolean;
+}
+/** Tracking of model token usage */
+interface TokenUsage {
+    /** Tokens in the prompt */
+    promptTokens: number;
+    /** Tokens in the completion */
+    completionTokens: number;
+    /** Total tokens used */
+    totalTokens: number;
+}
+/** Structure of a tool call requested by the model */
+interface ToolCall {
+    /** Unique ID for the tool call */
+    id: string;
+    /** Name of the tool to be invoked */
+    name: string;
+    /** JSON string of arguments to pass to the tool */
+    arguments: string;
+}
+/** Standard response from a non-streaming completion */
+interface CompletionResponse {
+    /** The text content generated */
+    content: string;
+    /** Optional tool calls requested */
+    toolCalls?: ToolCall[];
+    /** The reason generation stopped */
+    finishReason: 'stop' | 'tool_call' | 'max_tokens' | 'error';
+    /** Token usage statistics */
+    usage: TokenUsage;
+    /** The unparsed provider response for debugging */
+    rawResponse?: unknown;
+}
+/** Structure of a yielded chunk during a streaming completion */
+interface CompletionChunk {
+    /** The newly generated text delta */
+    delta: string;
+    /** Partial tool call delta if generating a tool call */
+    toolCallDelta?: Partial<ToolCall>;
+    /** True if this is the final chunk */
+    finished: boolean;
+    /** The reason generation stopped, typically present only on the final chunk */
+    finishReason?: CompletionResponse['finishReason'];
+}
+interface TranscriptionRequest {
+    audioBase64: string;
+    mimeType: string;
+    language?: string;
+}
+interface TranscriptionResponse {
+    transcript: string;
+    confidence: number;
+    language: string;
+}
+interface SynthesisRequest {
+    text: string;
+    voiceId: string;
+    format: 'mp3' | 'wav' | 'pcm';
+}
+interface AudioChunk {
+    audioBase64: string;
+}
+interface VisionRequest {
+    imageBase64: string;
+    prompt?: string;
+}
+interface VisionResponse {
+    description: string;
+    objects: string[];
+}
+interface ImageGenRequest {
+    prompt: string;
+    dimensions: string;
+}
+interface ImageGenResponse {
+    imageUrl: string;
+    revisedPrompt?: string;
+}
+/** Basic info about the model's capabilities */
+interface ModelInfo {
+    /** Does it support vision? */
+    supportsVision: boolean;
+    /** Does it support tools? */
+    supportsTools: boolean;
+    /** Maximum context window size */
+    contextWindow: number;
+}
+/**
+ * Interface that all provider adapters must implement.
+ *
+ * @example
+ * class MyAdapter implements IProviderAdapter {
+ *   readonly name = 'custom';
+ *   readonly version = '1.0.0';
+ *   async complete(request) { ... }
+ *   ...
+ * }
+ */
+interface IProviderAdapter {
+    /** The name of the adapter implementation */
+    readonly name: string;
+    /** The version of the adapter implementation */
+    readonly version: string;
+    /**
+     * Generates a single completion response.
+     *
+     * @param request - Normalized completion request parameters
+     * @returns A promise resolving to the normalized completion response
+     * @throws {LemuraAdapterError} When the API fails or capabilities are missing
+     */
+    complete(request: CompletionRequest): Promise<CompletionResponse>;
+    /**
+     * Streams a completion response back in chunks.
+     *
+     * @param request - Normalized completion request parameters
+     * @returns An async iterable yielding completion chunks
+     * @throws {LemuraAdapterError} When the API fails
+     */
+    stream(request: CompletionRequest): AsyncIterable<CompletionChunk>;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResponse>;
+    synthesize(request: SynthesisRequest): AsyncIterable<AudioChunk>;
+    describeImage(request: VisionRequest): Promise<VisionResponse>;
+    generateImage(request: ImageGenRequest): Promise<ImageGenResponse>;
+    /**
+     * Estimates token count for standard text.
+     *
+     * @param text - The string to measure
+     * @returns The estimated number of tokens
+     */
+    estimateTokens(text: string): number;
+    /**
+     * Gets details about the underlying model's capabilities.
+     *
+     * @returns An object describing model features
+     */
+    getModelInfo(): ModelInfo;
+    /**
+     * Verify whether the adapter is healthy and reachable.
+     *
+     * @returns A promise resolving to true if healthy, false otherwise
+     */
+    healthCheck(): Promise<boolean>;
+}
+
+export type { AudioChunk as A, ContextWindow as C, IContextStrategy as I, ModelInfo as M, NormalizedMessage as N, SynthesisRequest as S, Turn as T, VisionRequest as V, ContentBlock as a, CompletionChunk as b, CompletionRequest as c, CompletionResponse as d, IProviderAdapter as e, ImageGenRequest as f, ImageGenResponse as g, TokenUsage as h, ToolCall as i, ToolResult as j, TranscriptionRequest as k, TranscriptionResponse as l, VisionResponse as m };

package/dist/adapters-BnG0LEYD.d.mts

@@ -0,0 +1,208 @@
+import { I as IToolDefinition } from './storage-DMcliVVj.mjs';
+
+interface ContentBlock {
+    type: string;
+    text?: string;
+    imageUrl?: string;
+    [key: string]: unknown;
+}
+interface ToolResult {
+    toolCallId: string;
+    content: string;
+}
+interface Turn {
+    role: 'user' | 'assistant' | 'tool' | 'system';
+    content: string | ContentBlock[];
+    tokenCount: number;
+    turnIndex: number;
+    compressed: boolean;
+    toolCalls?: ToolCall[];
+    toolResults?: ToolResult[];
+}
+interface ContextWindow {
+    systemPrompt: string;
+    scratchpad: string;
+    turns: Turn[];
+    tokenCount: number;
+    maxTokens: number;
+    compressionSummary?: string;
+    metadata: Record<string, unknown>;
+}
+interface IContextStrategy {
+    name: string;
+    priority: number;
+    shouldApply(ctx: ContextWindow): boolean;
+    apply(ctx: ContextWindow): Promise<ContextWindow>;
+}
+
+/** Represents a single message in the provider format */
+interface NormalizedMessage {
+    /** The role of the message sender */
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /** The text or multimodal content of the message */
+    content: string | ContentBlock[];
+    /** Name of the tool, required if role is 'tool' */
+    name?: string;
+    /** Tool calls made by the assistant, present if role is 'assistant' */
+    toolCalls?: ToolCall[];
+}
+/** A request strictly normalized for the provider */
+interface CompletionRequest {
+    /** Model ID to use */
+    model: string;
+    /** The array of messages to send to the provider */
+    messages: NormalizedMessage[];
+    /** Optional array of tool definitions */
+    tools?: IToolDefinition[];
+    /** Maximum number of tokens to generate */
+    maxTokens?: number;
+    /** Generation temperature */
+    temperature?: number;
+    /** Optional array of sequences that will stop generation */
+    stopSequences?: string[];
+    /** Whether to stream the response back */
+    stream?: boolean;
+}
+/** Tracking of model token usage */
+interface TokenUsage {
+    /** Tokens in the prompt */
+    promptTokens: number;
+    /** Tokens in the completion */
+    completionTokens: number;
+    /** Total tokens used */
+    totalTokens: number;
+}
+/** Structure of a tool call requested by the model */
+interface ToolCall {
+    /** Unique ID for the tool call */
+    id: string;
+    /** Name of the tool to be invoked */
+    name: string;
+    /** JSON string of arguments to pass to the tool */
+    arguments: string;
+}
+/** Standard response from a non-streaming completion */
+interface CompletionResponse {
+    /** The text content generated */
+    content: string;
+    /** Optional tool calls requested */
+    toolCalls?: ToolCall[];
+    /** The reason generation stopped */
+    finishReason: 'stop' | 'tool_call' | 'max_tokens' | 'error';
+    /** Token usage statistics */
+    usage: TokenUsage;
+    /** The unparsed provider response for debugging */
+    rawResponse?: unknown;
+}
+/** Structure of a yielded chunk during a streaming completion */
+interface CompletionChunk {
+    /** The newly generated text delta */
+    delta: string;
+    /** Partial tool call delta if generating a tool call */
+    toolCallDelta?: Partial<ToolCall>;
+    /** True if this is the final chunk */
+    finished: boolean;
+    /** The reason generation stopped, typically present only on the final chunk */
+    finishReason?: CompletionResponse['finishReason'];
+}
+interface TranscriptionRequest {
+    audioBase64: string;
+    mimeType: string;
+    language?: string;
+}
+interface TranscriptionResponse {
+    transcript: string;
+    confidence: number;
+    language: string;
+}
+interface SynthesisRequest {
+    text: string;
+    voiceId: string;
+    format: 'mp3' | 'wav' | 'pcm';
+}
+interface AudioChunk {
+    audioBase64: string;
+}
+interface VisionRequest {
+    imageBase64: string;
+    prompt?: string;
+}
+interface VisionResponse {
+    description: string;
+    objects: string[];
+}
+interface ImageGenRequest {
+    prompt: string;
+    dimensions: string;
+}
+interface ImageGenResponse {
+    imageUrl: string;
+    revisedPrompt?: string;
+}
+/** Basic info about the model's capabilities */
+interface ModelInfo {
+    /** Does it support vision? */
+    supportsVision: boolean;
+    /** Does it support tools? */
+    supportsTools: boolean;
+    /** Maximum context window size */
+    contextWindow: number;
+}
+/**
+ * Interface that all provider adapters must implement.
+ *
+ * @example
+ * class MyAdapter implements IProviderAdapter {
+ *   readonly name = 'custom';
+ *   readonly version = '1.0.0';
+ *   async complete(request) { ... }
+ *   ...
+ * }
+ */
+interface IProviderAdapter {
+    /** The name of the adapter implementation */
+    readonly name: string;
+    /** The version of the adapter implementation */
+    readonly version: string;
+    /**
+     * Generates a single completion response.
+     *
+     * @param request - Normalized completion request parameters
+     * @returns A promise resolving to the normalized completion response
+     * @throws {LemuraAdapterError} When the API fails or capabilities are missing
+     */
+    complete(request: CompletionRequest): Promise<CompletionResponse>;
+    /**
+     * Streams a completion response back in chunks.
+     *
+     * @param request - Normalized completion request parameters
+     * @returns An async iterable yielding completion chunks
+     * @throws {LemuraAdapterError} When the API fails
+     */
+    stream(request: CompletionRequest): AsyncIterable<CompletionChunk>;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResponse>;
+    synthesize(request: SynthesisRequest): AsyncIterable<AudioChunk>;
+    describeImage(request: VisionRequest): Promise<VisionResponse>;
+    generateImage(request: ImageGenRequest): Promise<ImageGenResponse>;
+    /**
+     * Estimates token count for standard text.
+     *
+     * @param text - The string to measure
+     * @returns The estimated number of tokens
+     */
+    estimateTokens(text: string): number;
+    /**
+     * Gets details about the underlying model's capabilities.
+     *
+     * @returns An object describing model features
+     */
+    getModelInfo(): ModelInfo;
+    /**
+     * Verify whether the adapter is healthy and reachable.
+     *
+     * @returns A promise resolving to true if healthy, false otherwise
+     */
+    healthCheck(): Promise<boolean>;
+}
+
+export type { AudioChunk as A, ContextWindow as C, IContextStrategy as I, ModelInfo as M, NormalizedMessage as N, SynthesisRequest as S, Turn as T, VisionRequest as V, ContentBlock as a, CompletionChunk as b, CompletionRequest as c, CompletionResponse as d, IProviderAdapter as e, ImageGenRequest as f, ImageGenResponse as g, TokenUsage as h, ToolCall as i, ToolResult as j, TranscriptionRequest as k, TranscriptionResponse as l, VisionResponse as m };

package/dist/context/index.d.mts

@@ -0,0 +1,143 @@
+import { I as IContextStrategy, C as ContextWindow, e as IProviderAdapter } from '../adapters-BnG0LEYD.mjs';
+import { a as IStorageAdapter } from '../storage-DMcliVVj.mjs';
+export { b as STMRegistryConfig, c as ShortTermMemoryRegistry } from '../storage-DMcliVVj.mjs';
+import '../rag-La_Bo-J8.mjs';
+import '../logger-DxvKliuk.mjs';
+
+/**
+ * Orchestrates a stack of IContextStrategy implementations to keep the
+ * token count within the maxTokens limit.
+ */
+declare class ContextManager {
+    private strategies;
+    /**
+     * Registers a new compression or pre-turn strategy and sorts the stack by priority.
+     *
+     * @param strategy - The strategy implementation to register
+     */
+    registerStrategy(strategy: IContextStrategy): void;
+    /**
+     * Applies all registered strategies that return true for `shouldApply()`
+     * until the context token count is safely below the maximum budget.
+     *
+     * @param context - The context window to prepare
+     * @param safetyMargin - Modifier applied to maxTokens (default: 0.95 -> 95%)
+     * @returns A new ContextWindow object potentially compressed
+     * @throws {LemuraContextOverflowError} If the context is still over maxTokens after all strategies
+     */
+    prepare(context: ContextWindow, safetyMargin?: number): Promise<ContextWindow>;
+}
+
+interface SandwichCompressionConfig {
+    preserveFirst: number;
+    preserveLast: number;
+    triggerThreshold: number;
+}
+/**
+ * Sandwich compression preserves the beginning and end of the conversation,
+ * replacing the middle with a generated summary.
+ */
+declare class SandwichCompressionStrategy implements IContextStrategy {
+    private adapter;
+    private config;
+    readonly name = "sandwich_compression";
+    readonly priority = 20;
+    constructor(adapter: IProviderAdapter, config: SandwichCompressionConfig);
+    shouldApply(ctx: ContextWindow): boolean;
+    apply(ctx: ContextWindow): Promise<ContextWindow>;
+    /**
+     * Applies sandwich compression specifically to a Short Term Memory item's content.
+     * Implements a 3-layer pipeline: Pre-Layer (encoding), Core Layer (dense summary), Post-Layer (refinement cues).
+     *
+     * @param content - The heavy text content to compress
+     * @param instructions - Guiding instructions for the core layer summary
+     * @returns The three-layer sandwich result
+     */
+    compressMemoryItem(content: string, instructions?: string): Promise<{
+        preLayer: string;
+        coreLayer: string;
+        postLayer: string;
+    }>;
+}
+
+/**
+ * ScratchpadStrategy manages the thinking process separate from the turn history.
+ * It is primarily a marker/pre-turn strategy that ensures scratchpad gets tokenized properly
+ * but is not compressed.
+ */
+declare class ScratchpadStrategy implements IContextStrategy {
+    readonly name = "scratchpad_strategy";
+    readonly priority = 10;
+    shouldApply(ctx: ContextWindow): boolean;
+    apply(ctx: ContextWindow): Promise<ContextWindow>;
+}
+interface HistoryCompressionConfig {
+    windowSize: number;
+    triggerAtPercent: number;
+}
+/**
+ * Operates on a rolling window of the oldest N turns and summarizes them.
+ */
+declare class HistoryCompressionStrategy implements IContextStrategy {
+    private adapter;
+    private config;
+    readonly name = "history_compression";
+    readonly priority = 30;
+    constructor(adapter: IProviderAdapter, config: HistoryCompressionConfig);
+    shouldApply(ctx: ContextWindow): boolean;
+    apply(ctx: ContextWindow): Promise<ContextWindow>;
+}
+
+/**
+ * An in-memory implementation of IStorageAdapter for holding Short Term Memory.
+ * Ideal for testing or single-process lightweight usage.
+ *
+ * @example
+ * const storage = new InMemoryStorageAdapter();
+ * const id = await storage.set(undefined, 'my content', { type: 'text' });
+ * const retrieved = await storage.get(id);
+ */
+declare class InMemoryStorageAdapter implements IStorageAdapter {
+    private store;
+    /**
+     * Retrieves stored content by ID.
+     *
+     * @param id - The identifier of the stored item
+     * @returns The stored content or undefined if not found
+     */
+    get(id: string): Promise<any | undefined>;
+    /**
+     * Returns the full item including metadata.
+     *
+     * @param id - The identifier of the stored item
+     * @returns The complete item with content and metadata
+     * @internal
+     */
+    getFull(id: string): Promise<{
+        content: any;
+        metadata?: Record<string, unknown>;
+    } | undefined>;
+    /**
+     * Stores content, generating an ID if none is provided.
+     *
+     * @param id - Optional provided ID. If omitted, a UUID is generated.
+     * @param content - The content to store
+     * @param metadata - Optional metadata
+     * @returns The ID under which the content is stored
+     */
+    set(id: string | undefined, content: any, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Deletes the content for the given ID.
+     *
+     * @param id - The identifier of the item to delete
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Synchronous health check, always true for in-memory.
+     *
+     * @returns true
+     */
+    healthCheck(): Promise<boolean>;
+}
+
+export { ContextManager, type HistoryCompressionConfig, HistoryCompressionStrategy, InMemoryStorageAdapter, type SandwichCompressionConfig, SandwichCompressionStrategy, ScratchpadStrategy };

package/dist/context/index.d.ts

@@ -0,0 +1,143 @@
+import { I as IContextStrategy, C as ContextWindow, e as IProviderAdapter } from '../adapters-BSkhv5ac.js';
+import { a as IStorageAdapter } from '../storage-BGu4Loao.js';
+export { b as STMRegistryConfig, c as ShortTermMemoryRegistry } from '../storage-BGu4Loao.js';
+import '../rag-La_Bo-J8.js';
+import '../logger-DxvKliuk.js';
+
+/**
+ * Orchestrates a stack of IContextStrategy implementations to keep the
+ * token count within the maxTokens limit.
+ */
+declare class ContextManager {
+    private strategies;
+    /**
+     * Registers a new compression or pre-turn strategy and sorts the stack by priority.
+     *
+     * @param strategy - The strategy implementation to register
+     */
+    registerStrategy(strategy: IContextStrategy): void;
+    /**
+     * Applies all registered strategies that return true for `shouldApply()`
+     * until the context token count is safely below the maximum budget.
+     *
+     * @param context - The context window to prepare
+     * @param safetyMargin - Modifier applied to maxTokens (default: 0.95 -> 95%)
+     * @returns A new ContextWindow object potentially compressed
+     * @throws {LemuraContextOverflowError} If the context is still over maxTokens after all strategies
+     */
+    prepare(context: ContextWindow, safetyMargin?: number): Promise<ContextWindow>;
+}
+
+interface SandwichCompressionConfig {
+    preserveFirst: number;
+    preserveLast: number;
+    triggerThreshold: number;
+}
+/**
+ * Sandwich compression preserves the beginning and end of the conversation,
+ * replacing the middle with a generated summary.
+ */
+declare class SandwichCompressionStrategy implements IContextStrategy {
+    private adapter;
+    private config;
+    readonly name = "sandwich_compression";
+    readonly priority = 20;
+    constructor(adapter: IProviderAdapter, config: SandwichCompressionConfig);
+    shouldApply(ctx: ContextWindow): boolean;
+    apply(ctx: ContextWindow): Promise<ContextWindow>;
+    /**
+     * Applies sandwich compression specifically to a Short Term Memory item's content.
+     * Implements a 3-layer pipeline: Pre-Layer (encoding), Core Layer (dense summary), Post-Layer (refinement cues).
+     *
+     * @param content - The heavy text content to compress
+     * @param instructions - Guiding instructions for the core layer summary
+     * @returns The three-layer sandwich result
+     */
+    compressMemoryItem(content: string, instructions?: string): Promise<{
+        preLayer: string;
+        coreLayer: string;
+        postLayer: string;
+    }>;
+}
+
+/**
+ * ScratchpadStrategy manages the thinking process separate from the turn history.
+ * It is primarily a marker/pre-turn strategy that ensures scratchpad gets tokenized properly
+ * but is not compressed.
+ */
+declare class ScratchpadStrategy implements IContextStrategy {
+    readonly name = "scratchpad_strategy";
+    readonly priority = 10;
+    shouldApply(ctx: ContextWindow): boolean;
+    apply(ctx: ContextWindow): Promise<ContextWindow>;
+}
+interface HistoryCompressionConfig {
+    windowSize: number;
+    triggerAtPercent: number;
+}
+/**
+ * Operates on a rolling window of the oldest N turns and summarizes them.
+ */
+declare class HistoryCompressionStrategy implements IContextStrategy {
+    private adapter;
+    private config;
+    readonly name = "history_compression";
+    readonly priority = 30;
+    constructor(adapter: IProviderAdapter, config: HistoryCompressionConfig);
+    shouldApply(ctx: ContextWindow): boolean;
+    apply(ctx: ContextWindow): Promise<ContextWindow>;
+}
+
+/**
+ * An in-memory implementation of IStorageAdapter for holding Short Term Memory.
+ * Ideal for testing or single-process lightweight usage.
+ *
+ * @example
+ * const storage = new InMemoryStorageAdapter();
+ * const id = await storage.set(undefined, 'my content', { type: 'text' });
+ * const retrieved = await storage.get(id);
+ */
+declare class InMemoryStorageAdapter implements IStorageAdapter {
+    private store;
+    /**
+     * Retrieves stored content by ID.
+     *
+     * @param id - The identifier of the stored item
+     * @returns The stored content or undefined if not found
+     */
+    get(id: string): Promise<any | undefined>;
+    /**
+     * Returns the full item including metadata.
+     *
+     * @param id - The identifier of the stored item
+     * @returns The complete item with content and metadata
+     * @internal
+     */
+    getFull(id: string): Promise<{
+        content: any;
+        metadata?: Record<string, unknown>;
+    } | undefined>;
+    /**
+     * Stores content, generating an ID if none is provided.
+     *
+     * @param id - Optional provided ID. If omitted, a UUID is generated.
+     * @param content - The content to store
+     * @param metadata - Optional metadata
+     * @returns The ID under which the content is stored
+     */
+    set(id: string | undefined, content: any, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Deletes the content for the given ID.
+     *
+     * @param id - The identifier of the item to delete
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Synchronous health check, always true for in-memory.
+     *
+     * @returns true
+     */
+    healthCheck(): Promise<boolean>;
+}
+
+export { ContextManager, type HistoryCompressionConfig, HistoryCompressionStrategy, InMemoryStorageAdapter, type SandwichCompressionConfig, SandwichCompressionStrategy, ScratchpadStrategy };