Merge pull request #1 from code-rabi/docs/add-demo-and-events-api

docs: add demo section and real-time events API

Author: NitayRabi

AGENTS.md

@@ -13,8 +13,7 @@ The V8 isolate provides these bindings to LLM-generated code:
 | `context` | The loaded context data |
 | `llm_query(prompt, model?)` | Query sub-LLM |
 | `llm_query_batched(prompts, model?)` | Batch query sub-LLMs |
-| `FINAL(answer)` | Return final answer |
-| `FINAL_VAR(varName)` | Return variable as final answer |
+| `giveFinalAnswer({ message, data? })` | Return final answer |
 | `print(...)` | Console output |
 
 ## Architecture
@@ -30,7 +29,7 @@ The V8 isolate provides these bindings to LLM-generated code:
 │        │            │  • llm_query() ──┐               │   │
 │        │            │  • llm_query_batched()           │   │
 │        ▼            │  • print() / console             │   │
-│  ┌─────────────┐    │  • FINAL() / FINAL_VAR()         │   │
+│  ┌─────────────┐    │  • giveFinalAnswer()             │   │
 │  │  LLMClient  │◀───┼──────────────────┘               │   │
 │  │  (OpenAI)   │    │                                  │   │
 │  └─────────────┘    │  LLM-generated JS code runs here │   │

README.md

@@ -17,6 +17,14 @@ pnpm add rllm
 npm install rllm
 ```
 
+## Demo
+
+RLLM analyzing a `node_modules` directory — the LLM writes JavaScript to parse dependencies, query sub-LLMs in parallel, and synthesize a final answer:
+
+![RLLM Demo](./RLLM.gif)
+
+Built with Gemini Flash 3. See the full interactive example in [`examples/node-modules-viz/`](./examples/node-modules-viz/).
+
 ## Quick Start
 
 LLM writes JavaScript code that runs in a secure V8 isolate:
@@ -88,7 +96,7 @@ const findings = await llm_query_batched(
 
 const summary = await llm_query(`Combine findings:\n${findings.join('\n')}`);
 print(summary);
-FINAL(summary);
+giveFinalAnswer({ message: summary });
 ```
 
 ## API Reference
@@ -100,7 +108,7 @@ Create an RLLM instance with sensible defaults.
 ```typescript
 const rlm = createRLLM({
   model: 'gpt-4o-mini',      // Model name
-  provider: 'openai',         // 'openai' | 'anthropic' | 'openrouter' | 'custom'
+  provider: 'openai',         // 'openai' | 'anthropic' | 'gemini' | 'openrouter' | 'custom'
   apiKey: process.env.KEY,    // Optional, uses env vars by default
   baseUrl: undefined,         // Optional, required for 'custom' provider
   verbose: true,              // Enable logging
@@ -147,10 +155,44 @@ The V8 isolate provides these bindings to LLM-generated code:
 | `context` | The loaded context data |
 | `llm_query(prompt, model?)` | Query sub-LLM |
 | `llm_query_batched(prompts, model?)` | Batch query sub-LLMs |
-| `FINAL(answer)` | Return final answer |
-| `FINAL_VAR(varName)` | Return variable as final answer |
+| `giveFinalAnswer({ message, data? })` | Return final answer |
 | `print(...)` | Console output |
 
+### Real-time Events
+
+Subscribe to execution events for visualizations, debugging, or streaming UIs:
+
+```typescript
+const result = await rlm.completion("Analyze this data", {
+  context: myData,
+  onEvent: (event) => {
+    switch (event.type) {
+      case "iteration_start":
+        console.log(`Starting iteration ${event.iteration}`);
+        break;
+      case "llm_query_start":
+        console.log("LLM thinking...");
+        break;
+      case "code_execution_start":
+        console.log(`Executing:\n${event.code}`);
+        break;
+      case "final_answer":
+        console.log(`Answer: ${event.answer}`);
+        break;
+    }
+  }
+});
+```
+
+| Event Type | Description |
+|------------|-------------|
+| `iteration_start` | New iteration beginning |
+| `llm_query_start` | Main LLM query starting |
+| `llm_query_end` | Main LLM response received |
+| `code_execution_start` | V8 isolate executing code |
+| `code_execution_end` | Code execution finished |
+| `final_answer` | `giveFinalAnswer()` called with answer |
+
 ## Architecture
 
 ```
@@ -164,7 +206,7 @@ The V8 isolate provides these bindings to LLM-generated code:
 │        │            │  • llm_query() ──┐               │   │
 │        │            │  • llm_query_batched()           │   │
 │        ▼            │  • print() / console             │   │
-│  ┌─────────────┐    │  • FINAL() / FINAL_VAR()         │   │
+│  ┌─────────────┐    │  • giveFinalAnswer()             │   │
 │  │  LLMClient  │◀───┼──────────────────┘               │   │
 │  │  (OpenAI)   │    │                                  │   │
 │  └─────────────┘    │  LLM-generated JS code runs here │   │

RLM.gif

@@ -0,0 +1,264 @@
+# node_modules Graph Analyzer
+
+Interactive 3D visualization of your `node_modules` dependencies with RLLM-powered queries. Watch in real-time as the AI traverses your dependency graph to answer questions about duplicates, sizes, and relationships.
+
+## Features
+
+- 📦 **Parse any node_modules** - Analyzes package.json files, calculates sizes, detects duplicates
+- 🎯 **Real-time Visualization** - 3D force-directed graph with live highlighting as RLLM explores
+- 🤖 **AI-Powered Queries** - Ask natural language questions about your dependencies
+- 🔍 **Proxy Hooks** - Tracks every property access via JavaScript Proxies for visualization
+
+## Quick Start
+
+```bash
+cd examples/node-modules-viz
+pnpm install
+pnpm start
+```
+
+Then open http://localhost:3000 in your browser.
+
+This runs both the backend (WebSocket + RLLM) and frontend (Vite + React) concurrently.
+
+This will:
+1. Parse the parent directory's `node_modules` (this repo)
+2. Show the 3D visualization
+3. Let you click example queries or type your own
+
+## Usage
+
+### Analyze a specific project
+
+```bash
+pnpm server --target=/path/to/your/project
+```
+
+### Run a custom query from CLI
+
+```bash
+pnpm server --query="Find the largest packages"
+```
+
+Or just use the interactive UI in the browser!
+
+### Combine both
+
+```bash
+pnpm server --target=~/projects/my-app --query="What brings in lodash?"
+```
+
+## Example Queries
+
+### Find Duplicates
+```
+Which packages have multiple versions installed?
+```
+
+### Dependency Chains
+```
+What brings in lodash? Show the dependency chain.
+```
+
+### Disk Space Analysis
+```
+How much disk space could I save by deduping?
+```
+
+### Size Analysis
+```
+Find the 5 largest packages and their total size.
+```
+
+### Dependency Relationships
+```
+What's the path from react to scheduler?
+```
+
+### Popularity Analysis
+```
+Which packages have the most dependents?
+```
+
+### License Audit
+```
+Find all MIT licensed packages.
+```
+
+### Circular Dependencies
+```
+Find circular dependencies in the graph.
+```
+
+### Dev vs Prod
+```
+How many packages are dev dependencies vs production?
+```
+
+### Version Conflicts
+```
+Show all packages where different versions are required by different dependents.
+```
+
+## How It Works
+
+### 1. Graph Parsing
+
+The parser walks your `node_modules` directory recursively:
+- Reads each `package.json`
+- Calculates disk size
+- Detects hoisting and nesting
+- Identifies duplicate versions
+
+### 2. Proxy Tracking
+
+The graph context is wrapped in recursive JavaScript Proxies:
+
+```typescript
+const trackedContext = createTrackedGraph(context, (event) => {
+  // When RLLM code accesses context.packages["lodash@4.17.21"]
+  // This callback fires and sends the event to the browser
+  server.sendAccessEvent(event);
+});
+```
+
+### 3. RLLM Execution
+
+The AI writes JavaScript code that runs in a V8 isolate:
+
+```javascript
+// Example: Find duplicates
+const duplicates = [];
+for (const [name, ids] of Object.entries(context.packagesByName)) {
+  if (ids.length > 1) {
+    const sizes = ids.map(id => context.packages[id].diskSize);
+    duplicates.push({ name, versions: ids, totalSize: sizes.reduce((a,b) => a+b) });
+  }
+}
+giveFinalAnswer({ message: JSON.stringify(duplicates, null, 2) });
+```
+
+Every property access (like `context.packages[id]`) triggers the Proxy, which emits an event to highlight that node in the visualization.
+
+### 4. Real-time Visualization
+
+The browser receives WebSocket events and highlights nodes as they're accessed:
+- **Blue nodes** = regular packages
+- **Red nodes** = duplicate versions
+- **Green pulse** = currently accessed by RLLM
+
+## Architecture
+
+```
+┌─────────────────┐
+│  node_modules/  │
+└────────┬────────┘
+         │ parse
+         ▼
+┌─────────────────┐
+│ Dependency Graph│
+└────────┬────────┘
+         │ wrap in Proxy
+         ▼
+┌─────────────────┐      ┌──────────────┐
+│ Tracked Context │─────▶│ RLLM Engine  │
+└────────┬────────┘      └──────┬───────┘
+         │                      │
+         │ access events        │ query result
+         ▼                      ▼
+┌─────────────────────────────────────┐
+│     WebSocket Server                │
+└────────────┬────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────┐
+│  Browser (force-graph-3d)           │
+│  - 3D visualization                 │
+│  - Real-time highlighting           │
+│  - Stats panel                      │
+└─────────────────────────────────────┘
+```
+
+## Graph Data Structure
+
+### Nodes
+```typescript
+{
+  id: "lodash@4.17.21",
+  name: "lodash",
+  version: "4.17.21",
+  diskSize: 1234567,
+  isDuplicate: false,
+  isHoisted: true,
+  dependents: ["package-a@1.0.0", "package-b@2.0.0"]
+}
+```
+
+### Edges
+```typescript
+{
+  source: "react@18.2.0",
+  target: "scheduler@0.23.0",
+  type: "prod",
+  versionRange: "^0.23.0"
+}
+```
+
+## Environment Variables
+
+Create a `.env` file:
+
+```bash
+OPENAI_API_KEY=your_key_here
+MODEL=gpt-4o-mini  # or gpt-4o, gpt-4-turbo, etc.
+```
+
+## Tips
+
+- **Large projects**: Parsing may take a minute for huge `node_modules` (10k+ packages)
+- **Query complexity**: Start simple, let RLLM iterate to solve complex queries
+- **Visualization**: Click and drag nodes, scroll to zoom, the graph auto-rotates
+- **Results panel**: Shows at the bottom when query completes
+
+## Troubleshooting
+
+### No packages found
+Make sure the target directory has a `node_modules` folder:
+```bash
+ls /path/to/project/node_modules
+```
+
+### Browser doesn't open
+Manually navigate to: http://localhost:3000
+
+### WebSocket connection failed
+Check if port 3000 is available:
+```bash
+lsof -i :3000
+```
+
+### RLLM query fails
+Check your OpenAI API key is set:
+```bash
+echo $OPENAI_API_KEY
+```
+
+## Development
+
+```bash
+# Watch mode (auto-restart on changes)
+pnpm dev
+
+# Run with verbose logging
+pnpm start --query="Your query"
+```
+
+## Credits
+
+Built with:
+- [RLLM](https://github.com/code-rabi/rllm) - Recursive Language Models
+- [react-force-graph-3d](https://github.com/vasturiano/react-force-graph) - React 3D graph visualization
+- [Vite](https://vitejs.dev/) + [React](https://react.dev/) - Frontend framework
+- [ws](https://github.com/websockets/ws) - WebSocket server (port 4242)
+
+Inspired by the [Recursive Language Models paper](https://arxiv.org/abs/2512.24601).

examples/node-modules-viz/README.md

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>node_modules Graph Analyzer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>