attocode 0.1.0 → 0.1.3

package/dist/src/tricks/recursive-context.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Trick U: Recursive Language Model Context (RLM)
+ *
+ * Instead of cramming everything into context or summarizing, let the model
+ * "browse" the context as an external environment through recursive self-calls.
+ *
+ * Inspired by arXiv:2512.24601 - Recursive Language Models.
+ *
+ * Problem: Traditional approaches either:
+ * - Stuff everything in context → hits limits, loses attention
+ * - Summarize → loses critical details
+ *
+ * Solution: Let the model decide what parts of context to examine, then
+ * recursively call itself with focused snippets, synthesizing across calls.
+ *
+ * @example
+ * ```typescript
+ * const rlm = createRecursiveContext({
+ *   maxDepth: 3,
+ *   snippetTokens: 2000,
+ *   synthesisTokens: 1000,
+ * });
+ *
+ * // Register context sources
+ * rlm.registerSource('files', {
+ *   describe: () => 'Project source files',
+ *   list: async () => ['src/main.ts', 'src/agent.ts', ...],
+ *   fetch: async (key) => readFile(key),
+ * });
+ *
+ * // Process a query with recursive context access
+ * const result = await rlm.process(query, llmCall, {
+ *   depth: 0,
+ *   budget: 10000,
+ * });
+ * ```
+ */
+/**
+ * A context source that can be browsed.
+ */
+export interface ContextSource {
+    /** Brief description of this source */
+    describe: () => string;
+    /** List available items in this source */
+    list: (filter?: string) => Promise<string[]>;
+    /** Fetch a specific item */
+    fetch: (key: string) => Promise<string>;
+    /** Optional: search within this source */
+    search?: (query: string) => Promise<Array<{
+        key: string;
+        snippet: string;
+        score: number;
+    }>>;
+}
+/**
+ * A navigation command from the model.
+ */
+export interface NavigationCommand {
+    /** Type of navigation */
+    type: 'list' | 'fetch' | 'search' | 'synthesize' | 'done';
+    /** Source to navigate (for list/fetch/search) */
+    source?: string;
+    /** Key to fetch or query to search */
+    key?: string;
+    /** Reason for this navigation */
+    reason?: string;
+}
+/**
+ * Result of a recursive call.
+ */
+export interface RecursiveResult {
+    /** Final synthesized answer */
+    answer: string;
+    /** Breadcrumb trail of navigation */
+    path: NavigationStep[];
+    /** Statistics */
+    stats: RecursiveStats;
+}
+/**
+ * A step in the navigation path.
+ */
+export interface NavigationStep {
+    /** Depth in the recursion tree */
+    depth: number;
+    /** Command executed */
+    command: NavigationCommand;
+    /** Result (truncated if large) */
+    result: string;
+    /** Tokens used */
+    tokens: number;
+}
+/**
+ * Statistics about recursive processing.
+ */
+export interface RecursiveStats {
+    /** Total LLM calls made */
+    totalCalls: number;
+    /** Maximum depth reached */
+    maxDepthReached: number;
+    /** Total tokens used */
+    totalTokens: number;
+    /** Context sources accessed */
+    sourcesAccessed: string[];
+    /** Items fetched */
+    itemsFetched: number;
+    /** Processing time in ms */
+    duration: number;
+}
+/**
+ * Configuration for recursive context.
+ */
+export interface RecursiveContextConfig {
+    /** Maximum recursion depth */
+    maxDepth?: number;
+    /** Maximum tokens per snippet */
+    snippetTokens?: number;
+    /** Maximum tokens for synthesis */
+    synthesisTokens?: number;
+    /** Token budget for entire process */
+    totalBudget?: number;
+    /** Whether to cache fetched items */
+    cacheResults?: boolean;
+    /** Timeout per LLM call in ms */
+    callTimeout?: number;
+}
+/**
+ * Options for a recursive process call.
+ */
+export interface ProcessOptions {
+    /** Current depth (for recursive calls) */
+    depth?: number;
+    /** Remaining token budget */
+    budget?: number;
+    /** Previous navigation context (for recursive calls) */
+    navigationContext?: string;
+    /** Cancel token */
+    cancelToken?: {
+        isCancelled: boolean;
+    };
+}
+/**
+ * LLM call function signature.
+ */
+export type LLMCallFunction = (systemPrompt: string, userMessage: string, options?: {
+    maxTokens?: number;
+}) => Promise<{
+    content: string;
+    tokens: number;
+}>;
+/**
+ * Events emitted during recursive processing.
+ */
+export type RecursiveContextEvent = {
+    type: 'process.started';
+    query: string;
+    depth: number;
+} | {
+    type: 'navigation.command';
+    command: NavigationCommand;
+    depth: number;
+} | {
+    type: 'source.accessed';
+    source: string;
+    command: string;
+} | {
+    type: 'synthesis.started';
+    depth: number;
+    itemCount: number;
+} | {
+    type: 'process.completed';
+    stats: RecursiveStats;
+} | {
+    type: 'budget.warning';
+    remaining: number;
+    total: number;
+} | {
+    type: 'depth.warning';
+    current: number;
+    max: number;
+};
+export type RecursiveContextEventListener = (event: RecursiveContextEvent) => void;
+/**
+ * Manages recursive context navigation.
+ */
+export declare class RecursiveContextManager {
+    private config;
+    private sources;
+    private cache;
+    private listeners;
+    constructor(config?: RecursiveContextConfig);
+    /**
+     * Register a context source.
+     */
+    registerSource(name: string, source: ContextSource): void;
+    /**
+     * Unregister a context source.
+     */
+    unregisterSource(name: string): void;
+    /**
+     * Get registered source names.
+     */
+    getSourceNames(): string[];
+    /**
+     * Process a query with recursive context navigation.
+     */
+    process(query: string, llmCall: LLMCallFunction, options?: ProcessOptions): Promise<RecursiveResult>;
+    /**
+     * Clear the results cache.
+     */
+    clearCache(): void;
+    /**
+     * Subscribe to events.
+     */
+    on(listener: RecursiveContextEventListener): () => void;
+    private buildSourceDescriptions;
+    private buildContextSummary;
+    private parseNavigationCommand;
+    private executeCommand;
+    private synthesize;
+    private formatGatheredItem;
+    private truncate;
+    private estimateTokens;
+    private emit;
+}
+/**
+ * Create a recursive context manager.
+ *
+ * @example
+ * ```typescript
+ * const rlm = createRecursiveContext({
+ *   maxDepth: 3,
+ *   snippetTokens: 2000,
+ *   totalBudget: 50000,
+ * });
+ *
+ * // Register file system source
+ * rlm.registerSource('files', {
+ *   describe: () => 'Project source files',
+ *   list: async () => glob('src/*.ts'),
+ *   fetch: async (path) => fs.readFile(path, 'utf-8'),
+ *   search: async (query) => grep(query),
+ * });
+ *
+ * // Process a complex query
+ * const result = await rlm.process(
+ *   'How does authentication work in this codebase?',
+ *   async (system, user, opts) => {
+ *     const response = await provider.chat([
+ *       { role: 'system', content: system },
+ *       { role: 'user', content: user },
+ *     ], opts);
+ *     return { content: response.content, tokens: response.usage.totalTokens };
+ *   }
+ * );
+ *
+ * console.log(result.answer);
+ * console.log(`Used ${result.stats.totalTokens} tokens across ${result.stats.totalCalls} calls`);
+ * ```
+ */
+export declare function createRecursiveContext(config?: RecursiveContextConfig): RecursiveContextManager;
+/**
+ * Create a minimal recursive context manager for testing.
+ */
+export declare function createMinimalRecursiveContext(): RecursiveContextManager;
+/**
+ * Create a file system context source.
+ */
+export declare function createFileSystemSource(options: {
+    basePath: string;
+    glob: (pattern: string) => Promise<string[]>;
+    readFile: (path: string) => Promise<string>;
+    grep?: (query: string, path?: string) => Promise<Array<{
+        file: string;
+        line: number;
+        content: string;
+    }>>;
+}): ContextSource;
+/**
+ * Create a conversation history context source.
+ */
+export declare function createConversationSource(options: {
+    getMessages: () => Array<{
+        role: string;
+        content: string;
+        timestamp?: string;
+    }>;
+}): ContextSource;
+/**
+ * Format recursive result for display.
+ */
+export declare function formatRecursiveResult(result: RecursiveResult): string;
+/**
+ * Format statistics for display.
+ */
+export declare function formatRecursiveStats(stats: RecursiveStats): string;
+//# sourceMappingURL=recursive-context.d.ts.map

package/dist/src/tricks/recursive-context.d.ts.map

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