@deepagents/context 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,286 @@
+import type { ContextFragment } from './lib/context.ts';
+import { type EstimateResult } from './lib/estimate.ts';
+import type { Models } from './lib/models.generated.ts';
+import { type ContextRenderer } from './lib/renderers/abstract.renderer.ts';
+import { type BranchInfo, type CheckpointInfo, ContextStore } from './lib/store/store.ts';
+export type { ContextFragment, FragmentType } from './lib/context.ts';
+export { isMessageFragment } from './lib/context.ts';
+export { ContextStore, type ChatData, type ChatInfo, type MessageData, type MessageInfo, type BranchData, type BranchInfo, type CheckpointData, type CheckpointInfo, type GraphNode, type GraphBranch, type GraphCheckpoint, type GraphData, type SearchOptions, type SearchResult, } from './lib/store/store.ts';
+export { SqliteContextStore } from './lib/store/sqlite.store.ts';
+export { InMemoryContextStore } from './lib/store/memory.store.ts';
+export { visualizeGraph } from './lib/visualize.ts';
+/**
+ * Message format compatible with AI SDK's CoreMessage.
+ */
+export interface Message {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+/**
+ * Result of resolving context - ready for AI SDK consumption.
+ */
+export interface ResolveResult {
+    /** Rendered non-message fragments for system prompt */
+    systemPrompt: string;
+    /** Message fragments decoded to AI SDK format */
+    messages: Message[];
+}
+/**
+ * Options for resolve().
+ */
+export interface ResolveOptions {
+    /** Renderer to use for system prompt (defaults to XmlRenderer) */
+    renderer?: ContextRenderer;
+}
+/**
+ * Options for creating a ContextEngine.
+ */
+export interface ContextEngineOptions {
+    /** Store for persisting fragments (required) */
+    store: ContextStore;
+    /** Unique identifier for this chat (required) */
+    chatId: string;
+    /** Branch name (defaults to 'main') */
+    branch?: string;
+}
+/**
+ * Options for creating message fragments.
+ */
+export interface MessageOptions {
+    /** Custom ID for the fragment. If not provided, auto-generates UUID. */
+    id?: string;
+}
+/**
+ * Metadata about a chat.
+ */
+export interface ChatMeta {
+    /** Unique chat identifier */
+    id: string;
+    /** When the chat was created */
+    createdAt: number;
+    /** When the chat was last updated */
+    updatedAt: number;
+    /** Optional user-provided title */
+    title?: string;
+    /** Optional custom metadata */
+    metadata?: Record<string, unknown>;
+}
+export { type ContextRenderer, type RendererOptions, XmlRenderer, MarkdownRenderer, TomlRenderer, ToonRenderer, } from './lib/renderers/abstract.renderer.ts';
+export { type ModelCost, type ModelInfo, type EstimateResult, type Tokenizer, defaultTokenizer, ModelsRegistry, getModelsRegistry, } from './lib/estimate.ts';
+export type { Models, KnownModels } from './lib/models.generated.ts';
+/**
+ * Context engine for managing AI conversation context with graph-based storage.
+ *
+ * The engine uses a DAG (Directed Acyclic Graph) model for messages:
+ * - Messages are immutable nodes with parentId forming the graph
+ * - Branches are pointers to head (tip) messages
+ * - Checkpoints are pointers to specific messages
+ * - History is preserved through branching (rewind creates new branch)
+ */
+export declare class ContextEngine {
+    #private;
+    constructor(options: ContextEngineOptions);
+    /**
+     * Get the current chat ID.
+     */
+    get chatId(): string;
+    /**
+     * Get the current branch name.
+     */
+    get branch(): string;
+    /**
+     * Get metadata for the current chat.
+     * Returns null if the chat hasn't been initialized yet.
+     */
+    get chat(): ChatMeta | null;
+    /**
+     * Add fragments to the context.
+     *
+     * - Message fragments (user/assistant) are queued for persistence
+     * - Non-message fragments (role/hint) are kept in memory for system prompt
+     */
+    set(...fragments: ContextFragment[]): this;
+    /**
+     * Render all fragments using the provided renderer.
+     * @internal Use resolve() instead for public API.
+     */
+    render(renderer: ContextRenderer): string;
+    /**
+     * Resolve context into AI SDK-ready format.
+     *
+     * - Initializes chat and branch if needed
+     * - Loads message history from the graph (walking parent chain)
+     * - Separates context fragments for system prompt
+     * - Combines with pending messages
+     *
+     * @example
+     * ```ts
+     * const context = new ContextEngine({ store, chatId: 'chat-1' })
+     *   .set(role('You are helpful'), user('Hello'));
+     *
+     * const { systemPrompt, messages } = await context.resolve();
+     * await generateText({ system: systemPrompt, messages });
+     * ```
+     */
+    resolve(options?: ResolveOptions): Promise<ResolveResult>;
+    /**
+     * Save pending messages to the graph.
+     *
+     * Each message is added as a node with parentId pointing to the previous message.
+     * The branch head is updated to point to the last message.
+     *
+     * @example
+     * ```ts
+     * context.set(user('Hello'));
+     * // AI responds...
+     * context.set(assistant('Hi there!'));
+     * await context.save(); // Persist to graph
+     * ```
+     */
+    save(): Promise<void>;
+    /**
+     * Estimate token count and cost for the current context.
+     *
+     * @param modelId - Model ID (e.g., "openai:gpt-4o", "anthropic:claude-3-5-sonnet")
+     * @param options - Optional settings
+     * @returns Estimate result with token counts and costs
+     */
+    estimate(modelId: Models, options?: {
+        renderer?: ContextRenderer;
+    }): Promise<EstimateResult>;
+    /**
+     * Rewind to a specific message by ID.
+     *
+     * Creates a new branch from that message, preserving the original branch.
+     * The new branch becomes active.
+     *
+     * @param messageId - The message ID to rewind to
+     * @returns The new branch info
+     *
+     * @example
+     * ```ts
+     * context.set(user('What is 2 + 2?', { id: 'q1' }));
+     * context.set(assistant('The answer is 5.', { id: 'wrong' })); // Oops!
+     * await context.save();
+     *
+     * // Rewind to the question, creates new branch
+     * const newBranch = await context.rewind('q1');
+     *
+     * // Now add correct answer on new branch
+     * context.set(assistant('The answer is 4.'));
+     * await context.save();
+     * ```
+     */
+    rewind(messageId: string): Promise<BranchInfo>;
+    /**
+     * Create a checkpoint at the current position.
+     *
+     * A checkpoint is a named pointer to the current branch head.
+     * Use restore() to return to this point later.
+     *
+     * @param name - Name for the checkpoint
+     * @returns The checkpoint info
+     *
+     * @example
+     * ```ts
+     * context.set(user('I want to learn a new skill.'));
+     * context.set(assistant('Would you like coding or cooking?'));
+     * await context.save();
+     *
+     * // Save checkpoint before user's choice
+     * const cp = await context.checkpoint('before-choice');
+     * ```
+     */
+    checkpoint(name: string): Promise<CheckpointInfo>;
+    /**
+     * Restore to a checkpoint by creating a new branch from that point.
+     *
+     * @param name - Name of the checkpoint to restore
+     * @returns The new branch info
+     *
+     * @example
+     * ```ts
+     * // User chose cooking, but wants to try coding path
+     * await context.restore('before-choice');
+     *
+     * context.set(user('I want to learn coding.'));
+     * context.set(assistant('Python is a great starting language!'));
+     * await context.save();
+     * ```
+     */
+    restore(name: string): Promise<BranchInfo>;
+    /**
+     * Switch to a different branch by name.
+     *
+     * @param name - Branch name to switch to
+     *
+     * @example
+     * ```ts
+     * // List branches (via store)
+     * const branches = await store.listBranches(context.chatId);
+     * console.log(branches); // [{name: 'main', ...}, {name: 'main-v2', ...}]
+     *
+     * // Switch to original branch
+     * await context.switchBranch('main');
+     * ```
+     */
+    switchBranch(name: string): Promise<void>;
+    /**
+     * Update metadata for the current chat.
+     *
+     * @param updates - Partial metadata to merge (title, metadata)
+     *
+     * @example
+     * ```ts
+     * await context.updateChat({
+     *   title: 'Coding Help Session',
+     *   metadata: { tags: ['python', 'debugging'] }
+     * });
+     * ```
+     */
+    updateChat(updates: Partial<Pick<ChatMeta, 'title' | 'metadata'>>): Promise<void>;
+    /**
+     * Consolidate context fragments (no-op for now).
+     *
+     * This is a placeholder for future functionality that merges context fragments
+     * using specific rules. Currently, it does nothing.
+     *
+     * @experimental
+     */
+    consolidate(): void;
+}
+export declare function hint(text: string): ContextFragment;
+export declare function fragment(name: string, ...children: ContextFragment[]): ContextFragment;
+/**
+ * Create a role fragment for system prompt instructions.
+ */
+export declare function role(content: string): ContextFragment;
+/**
+ * Create a user message fragment.
+ * Message fragments are separated from regular fragments during resolve().
+ *
+ * @param content - The message content
+ * @param options - Optional settings (id)
+ *
+ * @example
+ * ```ts
+ * context.set(user('Hello'));                     // Auto-generated ID
+ * context.set(user('Hello', { id: 'msg-1' }));   // Custom ID
+ * ```
+ */
+export declare function user(content: string, options?: MessageOptions): ContextFragment;
+/**
+ * Create an assistant message fragment.
+ * Message fragments are separated from regular fragments during resolve().
+ *
+ * @param content - The message content
+ * @param options - Optional settings (id)
+ *
+ * @example
+ * ```ts
+ * context.set(assistant('Hi there!'));                    // Auto-generated ID
+ * context.set(assistant('Hi there!', { id: 'resp-1' })); // Custom ID
+ * ```
+ */
+export declare function assistant(content: string, options?: MessageOptions): ContextFragment;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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