recursive-llm-ts 4.4.1 → 4.6.0

package/dist/streaming.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Streaming support for recursive-llm-ts.
+ *
+ * Provides `AsyncIterable`-based streaming for both text completions
+ * and structured output, with AbortController support.
+ */
+export type StreamChunkType = 'text' | 'partial_object' | 'usage' | 'error' | 'done';
+export interface StreamChunkBase {
+    type: StreamChunkType;
+    timestamp: number;
+}
+export interface TextStreamChunk extends StreamChunkBase {
+    type: 'text';
+    text: string;
+}
+export interface PartialObjectStreamChunk<T = unknown> extends StreamChunkBase {
+    type: 'partial_object';
+    object: Partial<T>;
+    /** JSON path of the field being populated */
+    path?: string;
+}
+export interface UsageStreamChunk extends StreamChunkBase {
+    type: 'usage';
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+export interface ErrorStreamChunk extends StreamChunkBase {
+    type: 'error';
+    error: Error;
+}
+export interface DoneStreamChunk extends StreamChunkBase {
+    type: 'done';
+    stats: {
+        llm_calls: number;
+        iterations: number;
+        depth: number;
+    };
+}
+export type StreamChunk<T = unknown> = TextStreamChunk | PartialObjectStreamChunk<T> | UsageStreamChunk | ErrorStreamChunk | DoneStreamChunk;
+export interface StreamOptions {
+    /** AbortController signal to cancel the stream */
+    signal?: AbortSignal;
+    /** Called on each chunk (alternative to async iteration) */
+    onChunk?: (chunk: StreamChunk) => void;
+}
+/**
+ * An async iterable stream of completion chunks.
+ *
+ * Can be consumed with `for await...of` or by attaching an `onChunk` callback.
+ *
+ * @example
+ * ```typescript
+ * const stream = rlm.streamCompletion(query, context);
+ * let fullText = '';
+ * for await (const chunk of stream) {
+ *   if (chunk.type === 'text') fullText += chunk.text;
+ * }
+ * ```
+ */
+export declare class RLMStream<T = unknown> implements AsyncIterable<StreamChunk<T>> {
+    private chunks;
+    private resolvers;
+    private done;
+    private error;
+    private signal?;
+    private abortHandler?;
+    constructor(signal?: AbortSignal);
+    /** Push a chunk into the stream (called by the producer) */
+    push(chunk: StreamChunk<T>): void;
+    /** Signal an error on the stream */
+    pushError(err: Error): void;
+    /** Mark the stream as complete */
+    complete(stats: {
+        llm_calls: number;
+        iterations: number;
+        depth: number;
+    }): void;
+    private cleanup;
+    /** Collect all text chunks into a single string */
+    toText(): Promise<string>;
+    /** Collect the final structured object (for structured streaming) */
+    toObject(): Promise<T | undefined>;
+    [Symbol.asyncIterator](): AsyncIterator<StreamChunk<T>>;
+}
+/**
+ * Creates a simulated stream from a non-streaming completion result.
+ * Useful as a compatibility bridge until full streaming is implemented in the Go binary.
+ */
+export declare function createSimulatedStream(text: string, stats: {
+    llm_calls: number;
+    iterations: number;
+    depth: number;
+}, signal?: AbortSignal, chunkSize?: number): RLMStream;

package/dist/streaming.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Streaming support for recursive-llm-ts.
+ *
+ * Provides `AsyncIterable`-based streaming for both text completions
+ * and structured output, with AbortController support.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RLMStream = void 0;
+exports.createSimulatedStream = createSimulatedStream;
+const errors_1 = require("./errors");
+// ─── RLM Stream ──────────────────────────────────────────────────────────────
+/**
+ * An async iterable stream of completion chunks.
+ *
+ * Can be consumed with `for await...of` or by attaching an `onChunk` callback.
+ *
+ * @example
+ * ```typescript
+ * const stream = rlm.streamCompletion(query, context);
+ * let fullText = '';
+ * for await (const chunk of stream) {
+ *   if (chunk.type === 'text') fullText += chunk.text;
+ * }
+ * ```
+ */
+class RLMStream {
+    constructor(signal) {
+        this.chunks = [];
+        this.resolvers = [];
+        this.done = false;
+        this.error = null;
+        this.signal = signal;
+        if (signal) {
+            this.abortHandler = () => {
+                this.pushError(new errors_1.RLMAbortError());
+            };
+            signal.addEventListener('abort', this.abortHandler, { once: true });
+        }
+    }
+    /** Push a chunk into the stream (called by the producer) */
+    push(chunk) {
+        if (this.done)
+            return;
+        if (chunk.type === 'done') {
+            this.done = true;
+        }
+        if (this.resolvers.length > 0) {
+            const resolve = this.resolvers.shift();
+            resolve({ value: chunk, done: false });
+            if (chunk.type === 'done') {
+                // Resolve any remaining waiters
+                for (const r of this.resolvers) {
+                    r({ value: undefined, done: true });
+                }
+                this.resolvers = [];
+            }
+        }
+        else {
+            this.chunks.push(chunk);
+        }
+    }
+    /** Signal an error on the stream */
+    pushError(err) {
+        if (this.done)
+            return;
+        this.error = err;
+        this.done = true;
+        // Reject any waiting resolvers
+        for (const resolve of this.resolvers) {
+            resolve({ value: { type: 'error', error: err, timestamp: Date.now() }, done: false });
+        }
+        this.resolvers = [];
+        this.cleanup();
+    }
+    /** Mark the stream as complete */
+    complete(stats) {
+        this.push({ type: 'done', stats, timestamp: Date.now() });
+        this.cleanup();
+    }
+    cleanup() {
+        if (this.signal && this.abortHandler) {
+            this.signal.removeEventListener('abort', this.abortHandler);
+        }
+    }
+    /** Collect all text chunks into a single string */
+    toText() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, e_1, _b, _c;
+            let text = '';
+            try {
+                for (var _d = true, _e = __asyncValues(this), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                    _c = _f.value;
+                    _d = false;
+                    const chunk = _c;
+                    if (chunk.type === 'text') {
+                        text += chunk.text;
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+            return text;
+        });
+    }
+    /** Collect the final structured object (for structured streaming) */
+    toObject() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, e_2, _b, _c;
+            let latest;
+            try {
+                for (var _d = true, _e = __asyncValues(this), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                    _c = _f.value;
+                    _d = false;
+                    const chunk = _c;
+                    if (chunk.type === 'partial_object') {
+                        latest = chunk.object;
+                    }
+                }
+            }
+            catch (e_2_1) { e_2 = { error: e_2_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+                }
+                finally { if (e_2) throw e_2.error; }
+            }
+            return latest;
+        });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                var _a;
+                // Check for abort
+                if (((_a = this.signal) === null || _a === void 0 ? void 0 : _a.aborted) && !this.error) {
+                    this.pushError(new errors_1.RLMAbortError());
+                }
+                // Return buffered chunks first
+                if (this.chunks.length > 0) {
+                    const chunk = this.chunks.shift();
+                    if (chunk.type === 'done' || chunk.type === 'error') {
+                        return Promise.resolve({ value: chunk, done: false }).then(r => {
+                            return { value: undefined, done: true };
+                        });
+                    }
+                    return Promise.resolve({ value: chunk, done: false });
+                }
+                // Stream is done
+                if (this.done) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                // Wait for next chunk
+                return new Promise((resolve) => {
+                    this.resolvers.push(resolve);
+                });
+            },
+        };
+    }
+}
+exports.RLMStream = RLMStream;
+// ─── Stream Builder (for simulating streaming from non-streaming sources) ────
+/**
+ * Creates a simulated stream from a non-streaming completion result.
+ * Useful as a compatibility bridge until full streaming is implemented in the Go binary.
+ */
+function createSimulatedStream(text, stats, signal, chunkSize = 20) {
+    const stream = new RLMStream(signal);
+    // Simulate streaming by splitting text into chunks
+    (() => __awaiter(this, void 0, void 0, function* () {
+        try {
+            for (let i = 0; i < text.length; i += chunkSize) {
+                if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+                    stream.pushError(new errors_1.RLMAbortError());
+                    return;
+                }
+                const chunk = text.slice(i, i + chunkSize);
+                stream.push({ type: 'text', text: chunk, timestamp: Date.now() });
+                // Small yield to allow consumer to process
+                yield new Promise(resolve => setImmediate(resolve));
+            }
+            stream.complete(stats);
+        }
+        catch (err) {
+            stream.pushError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }))();
+    return stream;
+}

package/go/README.md

@@ -159,6 +159,11 @@ All fields in `config` are optional and have defaults:
 | `max_iterations` | int | 30 | Maximum REPL iterations per call |
 | `temperature` | float | 0.7 | LLM temperature (0-2) |
 | `timeout` | int | 60 | HTTP timeout in seconds |
+| `context_overflow.enabled` | bool | true | Enable context overflow recovery |
+| `context_overflow.strategy` | string | `mapreduce` | Reduction strategy: mapreduce, truncate, chunked, tfidf, textrank, refine |
+| `context_overflow.max_model_tokens` | int | 0 (auto) | Override detected model token limit |
+| `context_overflow.safety_margin` | float | 0.15 | Fraction reserved for prompt overhead |
+| `context_overflow.max_reduction_attempts` | int | 3 | Max retry attempts |
 
 Any other fields in `config` are passed as extra parameters to the LLM API.
 
@@ -258,7 +263,10 @@ rlm/                         # Public package (importable)
 ├── prompt.go                # System prompt builder
 ├── repl.go                  # JavaScript REPL (goja)
 ├── openai.go                # OpenAI API client
-└── errors.go                # Error types
+├── errors.go                # Error types
+├── context_overflow.go      # Context overflow detection + 6 reduction strategies
+├── tfidf.go                 # TF-IDF extractive compression (pure Go)
+└── textrank.go              # TextRank graph-based ranking with PageRank
 ```
 
 ## Error Handling