rlm-analyzer 1.3.4 → 1.5.1

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-01-22
+
+### Added
+- **Claude Provider (Anthropic API)**: Direct integration with Claude API as third provider option
+  - New `--provider claude` CLI option
+  - Supports Claude 4.5 Sonnet, Opus, and Haiku models
+  - Model aliases: `sonnet`, `opus`, `haiku`, `claude-sonnet`, `claude-opus`, `claude-haiku`
+  - Authentication via `ANTHROPIC_API_KEY` or `CLAUDE_API_KEY` environment variable
+- **Claude Web Search**: Web grounding support for Claude provider
+  - Uses `web_search_20250305` tool for real-time web data
+  - Automatically enabled with `--grounding` flag when using Claude
+- **Token Usage Tracking**: Added `TokenUsage` interface for tracking API token consumption
+  - Includes `inputTokens`, `outputTokens`, `totalTokens`
+  - Cache token tracking for Claude (`cacheCreationTokens`, `cacheReadTokens`)
+
+### Changed
+- **Bedrock Web Grounding**: Now uses Nova 2 Lite (`us.amazon.nova-2-lite-v1:0`) instead of Nova Premier
+  - Nova 2 Lite has native web grounding support via `nova_grounding` system tool
+- Updated provider factory to support three providers: `gemini`, `bedrock`, `claude`
+- Enhanced MCP server with Claude provider support and status reporting
+
+### Removed
+- Removed `nova-2-pro` model alias (Nova 2 Pro is in preview only, not generally available)
+
+### Documentation
+- Updated `docs/models-and-commands.md` with Claude provider models and aliases
+- Updated README with Claude provider setup instructions
+
+---
+
 ## [1.3.4] - 2026-01-20
 
 ### Added

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://badge.fury.io/js/rlm-analyzer.svg)](https://www.npmjs.com/package/rlm-analyzer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Analyze any codebase with AI that can process **100x beyond context limits**. Powered by **Gemini 3** and based on MIT CSAIL research on [Recursive Language Models](https://arxiv.org/abs/2512.24601).
+Analyze any codebase with AI that can process **100x beyond context limits**. Powered by **Gemini 3**, **Amazon Bedrock (Nova/Claude/Llama)**, or **Claude (Anthropic API)** and based on MIT CSAIL research on [Recursive Language Models](https://arxiv.org/abs/2512.24601).
 
 ## Features
 
@@ -16,8 +16,10 @@ Analyze any codebase with AI that can process **100x beyond context limits**. Po
 - **Refactoring Suggestions** - Identifies code smells and improvements
 - **Symbol Search** - Find all usages of functions, classes, variables
 - **Custom Questions** - Ask anything about your codebase
+- **Multi-Provider Support** - Choose between Gemini (default), Amazon Bedrock (Nova/Claude/Llama), or Claude (Anthropic API)
+- **Web Grounding** - Verify package versions with real-time web search (Gemini & Nova Premier)
 - **MCP Integration** - Works with Claude Code, Cursor, and other MCP clients
-- **Cost Efficient** - Save 60-73% on API costs by offloading to Gemini
+- **Cost Efficient** - Save 60-73% on API costs by offloading to Gemini/Nova
 - **Token Optimization** - Context compression saves additional 50-70%
 
 ## Table of Contents
@@ -34,6 +36,11 @@ Analyze any codebase with AI that can process **100x beyond context limits**. Po
 - [Cost Savings](#cost-savings-with-mcp-integration)
 - [Troubleshooting](#troubleshooting)
 
+## Documentation
+
+- **[How It Works](docs/how-it-works.md)** - Deep dive into RLM architecture, recursive analysis, and token optimization
+- **[Models & Commands Reference](docs/models-and-commands.md)** - Complete list of CLI commands, model IDs, and aliases for Gemini, Bedrock, and Claude
+
 ---
 
 ## Installation
@@ -60,32 +67,73 @@ npx rlm-analyzer summary
 
 ## Quick Start
 
-### 1. Configure API Key
+### 1. Configure Provider Credentials
+
+#### Option A: Google Gemini (Default)
 
 Get a free API key from [Google AI Studio](https://makersuite.google.com/app/apikey), then:
 
 ```bash
-# Option 1: Use the config command
+# Use the config command
 rlm config YOUR_GEMINI_API_KEY
 
-# Option 2: Set environment variable
+# Or set environment variable
 export GEMINI_API_KEY=your_api_key
 
-# Option 3: Create .env file in your project
+# Or create .env file
 echo "GEMINI_API_KEY=your_api_key" > .env
 ```
 
+#### Option B: Amazon Bedrock
+
+First, install the AWS SDK (required for Bedrock):
+
+```bash
+npm install @aws-sdk/client-bedrock-runtime
+```
+
+Then configure authentication (choose one):
+
+```bash
+# Option 1: Bedrock API Key (Recommended - simplest setup)
+# Generate at: AWS Console → Bedrock → API keys
+export AWS_BEARER_TOKEN_BEDROCK=your_bedrock_api_key
+export AWS_REGION=us-east-1
+
+# Option 2: AWS Access Keys
+export AWS_ACCESS_KEY_ID=your_access_key
+export AWS_SECRET_ACCESS_KEY=your_secret_key
+export AWS_REGION=us-east-1
+
+# Option 3: AWS CLI profile
+aws configure
+```
+
+#### Option C: Claude (Anthropic API)
+
+Get your API key from [Anthropic Console](https://console.anthropic.com/), then:
+
+```bash
+export ANTHROPIC_API_KEY=your_api_key
+```
+
 ### 2. Analyze Your Code
 
 ```bash
-# Get a codebase summary
+# Get a codebase summary (uses Gemini by default)
 rlm summary
 
+# Use Amazon Bedrock instead
+rlm summary --provider bedrock
+
+# Use Claude (Anthropic API) instead
+rlm summary --provider claude
+
 # Analyze architecture
 rlm arch
 
-# Security analysis
-rlm security
+# Security analysis with web grounding
+rlm security --grounding
 
 # Ask a question
 rlm ask "How does authentication work?"
@@ -117,6 +165,8 @@ rlm ask "How does authentication work?"
 |--------|-------------|
 | `--dir, -d <path>` | Directory to analyze (default: current) |
 | `--model, -m <name>` | Model to use (see [Model Configuration](#model-configuration)) |
+| `--provider, -p <name>` | LLM provider: `gemini` (default), `bedrock`, or `claude` |
+| `--grounding` | Enable web grounding for security analysis |
 | `--output, -o <file>` | Save results to a markdown file |
 | `--verbose, -v` | Show detailed turn-by-turn output |
 | `--json` | Output results as JSON |
@@ -131,6 +181,15 @@ rlm arch --dir /path/to/project
 # Use a specific model
 rlm summary --model smart
 
+# Use Amazon Bedrock with Nova Pro
+rlm summary --provider bedrock --model smart
+
+# Use Bedrock with Claude (via AWS)
+rlm arch --provider bedrock --model claude-sonnet
+
+# Use Claude directly (Anthropic API)
+rlm arch --provider claude --model sonnet
+
 # Find all usages of a function
 rlm find "handleSubmit"
 
@@ -140,6 +199,9 @@ rlm explain src/auth/login.ts
 # Ask about the codebase
 rlm ask "What design patterns are used in this codebase?"
 
+# Security analysis with web grounding (verifies package versions)
+rlm security --grounding
+
 # Get JSON output for scripting
 rlm summary --json > analysis.json
 
@@ -160,6 +222,8 @@ RLM Analyzer includes an MCP (Model Context Protocol) server for integration wit
 
 Add to your Claude Code configuration (`~/.claude.json` or project `.mcp.json`):
 
+#### Using Gemini (Default)
+
 ```json
 {
   "mcpServers": {
@@ -174,6 +238,71 @@ Add to your Claude Code configuration (`~/.claude.json` or project `.mcp.json`):
 }
 ```
 
+#### Using Amazon Bedrock
+
+First, install the AWS SDK in your project or globally:
+
+```bash
+npm install @aws-sdk/client-bedrock-runtime
+```
+
+Then configure the MCP server (choose one authentication method):
+
+**Option 1: Bedrock API Key (Recommended)**
+
+```json
+{
+  "mcpServers": {
+    "rlm-analyzer": {
+      "command": "npx",
+      "args": ["-y", "rlm-analyzer-mcp"],
+      "env": {
+        "RLM_PROVIDER": "bedrock",
+        "AWS_BEARER_TOKEN_BEDROCK": "your_bedrock_api_key",
+        "AWS_REGION": "us-east-1"
+      }
+    }
+  }
+}
+```
+
+**Option 2: AWS Access Keys**
+
+```json
+{
+  "mcpServers": {
+    "rlm-analyzer": {
+      "command": "npx",
+      "args": ["-y", "rlm-analyzer-mcp"],
+      "env": {
+        "RLM_PROVIDER": "bedrock",
+        "AWS_ACCESS_KEY_ID": "your_access_key",
+        "AWS_SECRET_ACCESS_KEY": "your_secret_key",
+        "AWS_REGION": "us-east-1"
+      }
+    }
+  }
+}
+```
+
+**Option 3: AWS Profile**
+
+```json
+{
+  "mcpServers": {
+    "rlm-analyzer": {
+      "command": "npx",
+      "args": ["-y", "rlm-analyzer-mcp"],
+      "env": {
+        "RLM_PROVIDER": "bedrock",
+        "AWS_PROFILE": "your_profile_name",
+        "AWS_REGION": "us-east-1"
+      }
+    }
+  }
+}
+```
+
 ### Available MCP Tools
 
 | Tool | Description |
@@ -213,12 +342,12 @@ import {
   loadFiles,
 } from 'rlm-analyzer';
 
-// Analyze architecture
+// Analyze architecture (uses default provider - Gemini)
 const result = await analyzeArchitecture('/path/to/project');
 console.log(result.answer);
 
-// Security analysis
-const security = await analyzeSecurity('/path/to/project');
+// Security analysis with Bedrock
+const security = await analyzeSecurity('/path/to/project', { provider: 'bedrock' });
 console.log(security.answer);
 
 // Ask a custom question
@@ -233,7 +362,8 @@ const full = await analyzeCodebase({
   directory: '/path/to/project',
   query: 'Explain the data flow',
   analysisType: 'custom',
-  model: 'gemini-3-pro-preview',
+  model: 'smart', // Uses provider-specific alias
+  provider: 'bedrock', // Use Amazon Bedrock
   verbose: true,
 });
 ```
@@ -337,12 +467,26 @@ const relevantMemories = attention.filterByAttention(memories, 10);
 
 ### Available Models
 
-| Model ID | Alias | Description |
-|----------|-------|-------------|
-| `gemini-3-flash-preview` | `fast`, `flash`, `default` | Fast and efficient (recommended) |
-| `gemini-3-pro-preview` | `smart`, `pro` | Most capable |
-| `gemini-2.5-flash` | `flash-2.5` | Stable release |
-| `gemini-2.0-flash-exp` | `flash-2` | Fallback option |
+#### Gemini Models (Default Provider)
+
+| Alias | Model ID | Description |
+|-------|----------|-------------|
+| `fast`, `default` | `gemini-3-flash-preview` | Fast and efficient (recommended) |
+| `smart`, `pro` | `gemini-3-pro-preview` | Most capable |
+
+#### Amazon Bedrock Models
+
+| Alias | Model ID | Description |
+|-------|----------|-------------|
+| `fast`, `default` | `us.amazon.nova-2-lite-v1:0` | Nova 2 Lite (default) |
+| `smart` | `us.anthropic.claude-sonnet-4-5-*` | Claude 4.5 Sonnet |
+| `claude-sonnet` | `us.anthropic.claude-sonnet-4-5-*` | Claude 4.5 Sonnet |
+| `claude-opus` | `us.anthropic.claude-opus-4-5-*` | Claude 4.5 Opus |
+| `qwen3-coder` | `qwen.qwen3-coder-30b-*` | Qwen3 Coder - Best for coding |
+| `gpt-oss` | `openai.gpt-oss-120b-*` | OpenAI GPT OSS |
+| `llama-4` | `us.meta.llama4-maverick-*` | Llama 4 |
+
+> **[See all models and aliases →](docs/models-and-commands.md)**
 
 ### Configuration Priority
 
@@ -351,7 +495,7 @@ Model selection follows this priority order:
 1. **CLI `--model` flag** (highest priority)
 2. **Environment variables**: `RLM_DEFAULT_MODEL`, `RLM_FALLBACK_MODEL`
 3. **Config file**: `~/.rlm-analyzer/config.json`
-4. **Built-in defaults**: `gemini-3-flash-preview`
+4. **Built-in defaults**: `gemini-3-flash-preview` (Gemini) or `amazon.nova-lite-v1:0` (Bedrock)
 
 ### Using Model Aliases
 
@@ -361,16 +505,42 @@ rlm summary --model fast
 
 # Use smart model (gemini-3-pro-preview)
 rlm arch --model smart
+
+# Use Bedrock with Nova Pro
+rlm summary --provider bedrock --model smart
+
+# Use Bedrock with Claude Sonnet
+rlm arch --provider bedrock --model claude-sonnet
 ```
 
 ### Environment Variables
 
 ```bash
+# Set default provider (gemini or bedrock)
+export RLM_PROVIDER=gemini
+
 # Set default model
 export RLM_DEFAULT_MODEL=gemini-3-pro-preview
 
 # Set fallback model
 export RLM_FALLBACK_MODEL=gemini-2.0-flash-exp
+
+# Gemini API key
+export GEMINI_API_KEY=your_api_key
+
+# Bedrock authentication (choose one):
+# Option 1: Bedrock API Key (recommended)
+export AWS_BEARER_TOKEN_BEDROCK=your_bedrock_api_key
+export AWS_REGION=us-east-1
+
+# Option 2: AWS Access Keys
+export AWS_ACCESS_KEY_ID=your_access_key
+export AWS_SECRET_ACCESS_KEY=your_secret_key
+export AWS_REGION=us-east-1
+
+# Option 3: AWS Profile
+export AWS_PROFILE=your_profile_name
+export AWS_REGION=us-east-1
 ```
 
 ### Config File
@@ -379,7 +549,8 @@ Create `~/.rlm-analyzer/config.json`:
 
 ```json
 {
-  "apiKey": "your_api_key",
+  "apiKey": "your_gemini_api_key",
+  "provider": "gemini",
   "models": {
     "default": "gemini-3-flash-preview",
     "fallback": "gemini-2.0-flash-exp"
@@ -446,7 +617,9 @@ Multi-pass analysis for quality improvement on complex queries.
 
 ## Configuration
 
-### API Key Storage
+### Credentials Storage
+
+#### Gemini Credentials
 
 Your API key can be stored in multiple locations (checked in order):
 
@@ -457,6 +630,19 @@ Your API key can be stored in multiple locations (checked in order):
 5. `~/.rlm-analyzer/config.json`
 6. `~/.config/rlm-analyzer/config.json`
 
+#### Bedrock Credentials
+
+Authentication options (in priority order):
+
+1. **Bedrock API Key** (Recommended): `AWS_BEARER_TOKEN_BEDROCK` environment variable
+   - Generate at: AWS Console → Bedrock → API keys
+   - Simplest setup, no IAM configuration required
+2. **AWS Access Keys**: `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`
+3. **AWS Profile**: `AWS_PROFILE` or `~/.aws/credentials`
+4. **IAM Role**: Automatic when running on AWS infrastructure
+
+The region can be set via `AWS_REGION` environment variable (default: `us-east-1`).
+
 ### File Filtering
 
 Default file extensions analyzed:
@@ -491,32 +677,43 @@ target, .idea, .vscode, coverage, .nyc_output
 
 ## How It Works
 
-RLM Analyzer uses Recursive Language Models (RLMs) to analyze codebases that exceed traditional context limits:
+RLM Analyzer uses Recursive Language Models (RLMs) to analyze codebases that exceed traditional context limits.
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                      RLM Orchestrator                       │
-├─────────────────────────────────────────────────────────────┤
-│  1. File Loading      Load codebase into virtual env        │
-│  2. REPL Execution    AI writes code to explore files       │
-│  3. Sub-LLM Calls     Delegate analysis to specialized      │
-│                       sub-queries (llm_query)               │
-│  4. Context Mgmt      Compress, optimize, detect rot        │
-│  5. Synthesis         Combine findings into final answer    │
+│                      User Query                              │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Orchestrator (Main LLM)                   │
+│  • Sees file tree, decides which files to read              │
+│  • Spawns Sub-LLMs for deep analysis                        │
 └─────────────────────────────────────────────────────────────┘
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+        ┌──────────┐   ┌──────────┐   ┌──────────┐
+        │ Sub-LLM  │   │ Sub-LLM  │   │ Sub-LLM  │
+        └──────────┘   └──────────┘   └──────────┘
+              │               │               │
+              └───────────────┼───────────────┘
+                              ▼
+                        Final Answer
 ```
 
-### The RLM Approach
+### Key Concepts
 
-1. **File Loading** - Loads your codebase into a virtual file index
-2. **REPL Execution** - AI writes and executes Python-like code to explore files
-3. **Sub-LLM Calls** - Complex analysis delegated via `llm_query()` function
-4. **Context Management** - Compression, sliding window, memory bank
-5. **Iterative Refinement** - Multiple turns until `FINAL()` is called
-6. **Final Answer** - Synthesized analysis based on deep exploration
+1. **Recursive Analysis** - Main LLM spawns sub-LLMs to analyze files in parallel
+2. **Context Optimization** - Shows file tree first, LLM requests only needed files
+3. **Multi-turn Conversation** - Multiple turns to read, analyze, and refine
+4. **Memory Bank** - Tracks findings to prevent "context rot"
+5. **Adaptive Compression** - Compresses older context as usage increases
 
 This enables analysis of codebases **100x larger** than traditional context windows.
 
+> **[Read the full technical deep-dive →](docs/how-it-works.md)**
+
 ---
 
 ## Cost Savings with MCP Integration
@@ -579,7 +776,7 @@ When used as an MCP tool with Claude Code or Cursor, RLM Analyzer significantly
 
 ## Troubleshooting
 
-### "API key not configured"
+### "API key not configured" (Gemini)
 
 ```bash
 # Check if key is set
@@ -589,6 +786,29 @@ rlm config
 rlm config YOUR_API_KEY
 ```
 
+### "AWS credentials not configured" (Bedrock)
+
+```bash
+# Check credentials
+rlm config
+
+# Option 1: Set environment variables
+export AWS_ACCESS_KEY_ID=your_key
+export AWS_SECRET_ACCESS_KEY=your_secret
+export AWS_REGION=us-east-1
+
+# Option 2: Use AWS CLI to configure
+aws configure
+```
+
+### "Amazon Bedrock provider requires @aws-sdk/client-bedrock-runtime"
+
+The AWS SDK is an optional dependency. Install it to use Bedrock:
+
+```bash
+npm install @aws-sdk/client-bedrock-runtime
+```
+
 ### "No files found to analyze"
 
 Make sure you're in a directory with code files, or specify a directory:
@@ -602,6 +822,7 @@ rlm summary --dir /path/to/code
 - Large codebases take longer (100+ files = more sub-LLM calls)
 - Use `--verbose` to see progress and token savings
 - Consider analyzing specific subdirectories
+- Use `--model fast` for faster analysis
 
 ### Execution errors in verbose mode
 
@@ -610,9 +831,16 @@ Some codebases trigger security filters (e.g., files containing `process.env`).
 ### MCP server not connecting
 
 1. Verify the command works: `npx rlm-analyzer-mcp`
-2. Check API key is set in the MCP config
+2. Check credentials are set in the MCP config (Gemini API key or AWS credentials)
 3. Restart your MCP client (Claude Code, Cursor)
 
+### Bedrock throttling errors
+
+If you see throttling errors with Bedrock, try:
+- Using a smaller model (`--model fast`)
+- Reducing concurrent requests
+- Requesting higher limits from AWS
+
 ---
 
 ## TypeScript Types
@@ -628,6 +856,13 @@ import type {
   CodeAnalysisResult,
   AnalysisType,
 
+  // Provider types
+  ProviderName,       // 'gemini' | 'bedrock'
+  LLMProvider,        // Provider interface
+  Message,            // Conversation message
+  GenerateOptions,    // Generation options
+  GenerateResponse,   // Generation response
+
   // Context management
   MemoryEntry,
   CompressedTurn,

package/dist/cli.d.ts

@@ -2,6 +2,7 @@
 /**
  * RLM Analyzer CLI
  * Command-line interface for code analysis
+ * Supports multiple providers: Gemini (default), Amazon Bedrock, and Claude
  *
  * Usage:
  *   rlm <command> [options]
@@ -20,6 +21,7 @@
  *
  * Options:
  *   --dir, -d      Directory to analyze (default: current)
+ *   --provider, -p Provider to use (gemini|bedrock|claude)
  *   --verbose, -v  Show detailed output
  *   --json         Output as JSON
  *   --help, -h     Show help

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA2kBH,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAwE5C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAkoBH,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CA0I5C"}