@blockrun/clawrouter 0.12.61 → 0.12.63

package/docs/features.md

@@ -0,0 +1,257 @@
+# Advanced Features
+
+ClawRouter v0.5+ includes intelligent routing features that work automatically.
+
+## Table of Contents
+
+- [Response Cache](#response-cache)
+- [Agentic Auto-Detection](#agentic-auto-detection)
+- [Tool Detection](#tool-detection)
+- [Context-Length-Aware Routing](#context-length-aware-routing)
+- [Model Aliases](#model-aliases)
+- [Free Tier Fallback](#free-tier-fallback)
+- [Session Persistence](#session-persistence)
+- [Cost Tracking with /stats](#cost-tracking-with-stats)
+
+---
+
+## Response Cache
+
+ClawRouter includes LLM response caching inspired by LiteLLM's caching system. Identical requests return cached responses, saving both cost and latency.
+
+**How it works:**
+
+```
+Request: "What is 2+2?"
+  First call:  → API ($0.001) → Cache response
+  Second call: → Cache HIT → Return instantly ($0)
+```
+
+**Features:**
+
+| Feature      | Default     | Description                |
+| ------------ | ----------- | -------------------------- |
+| TTL          | 10 minutes  | Responses expire after TTL |
+| Max size     | 200 entries | LRU eviction when full     |
+| Item limit   | 1MB         | Large responses skipped    |
+| Auto-enabled | Yes         | No config needed           |
+
+**Cache key generation:**
+
+The cache key is a SHA-256 hash of the request body (model + messages + params), with normalization:
+
+- Message timestamps stripped (OpenClaw injects `[Mon 2024-01-15 10:30 UTC]`)
+- Keys sorted for consistent hashing
+- Stream mode, user, and request_id fields excluded
+
+**Bypass cache:**
+
+```typescript
+// Via header
+fetch("/v1/chat/completions", {
+  headers: { "Cache-Control": "no-cache" }
+})
+
+// Via body
+{
+  "model": "blockrun/auto",
+  "cache": false,  // or "no_cache": true
+  "messages": [...]
+}
+```
+
+**Check cache stats:**
+
+```bash
+curl http://localhost:8402/cache
+```
+
+Response:
+
+```json
+{
+  "size": 42,
+  "maxSize": 200,
+  "hits": 156,
+  "misses": 89,
+  "evictions": 3,
+  "hitRate": "63.7%"
+}
+```
+
+**Configuration:**
+
+Response caching is enabled by default with sensible defaults. For advanced tuning, the cache can be configured programmatically:
+
+```typescript
+import { ResponseCache } from "@blockrun/clawrouter";
+
+const cache = new ResponseCache({
+  maxSize: 500, // Max cached responses
+  defaultTTL: 300, // 5 minutes
+  maxItemSize: 2_097_152, // 2MB max per item
+  enabled: true,
+});
+```
+
+---
+
+## Agentic Auto-Detection
+
+ClawRouter automatically detects multi-step agentic tasks and routes to models optimized for autonomous execution:
+
+```
+"what is 2+2"                    → gemini-flash (standard)
+"build the project then run tests" → kimi-k2.5 (auto-agentic)
+"fix the bug and make sure it works" → kimi-k2.5 (auto-agentic)
+```
+
+**How it works:**
+
+- Detects agentic keywords: file ops ("read", "edit"), execution ("run", "test", "deploy"), iteration ("fix", "debug", "verify")
+- Threshold: 2+ signals triggers auto-switch to agentic tiers
+- No config needed — works automatically
+
+**Agentic tier models** (optimized for multi-step autonomy):
+
+| Tier      | Agentic Model     | Why                            |
+| --------- | ----------------- | ------------------------------ |
+| SIMPLE    | claude-haiku-4.5  | Fast + reliable tool use       |
+| MEDIUM    | kimi-k2.5         | 200+ tool chains, 76% cheaper  |
+| COMPLEX   | claude-sonnet-4.6 | Best balance for complex tasks |
+| REASONING | kimi-k2.5         | Extended reasoning + execution |
+
+### Force Agentic Mode
+
+You can also force agentic mode via config:
+
+```yaml
+# openclaw.yaml
+plugins:
+  - id: "@blockrun/clawrouter"
+    config:
+      routing:
+        overrides:
+          agenticMode: true # Always use agentic tiers
+```
+
+---
+
+## Tool Detection
+
+When your request includes a `tools` array (function calling), ClawRouter automatically switches to agentic tiers:
+
+```typescript
+// Request with tools → auto-agentic mode
+{
+  model: "blockrun/auto",
+  messages: [{ role: "user", content: "Check the weather" }],
+  tools: [{ type: "function", function: { name: "get_weather", ... } }]
+}
+// → Routes to claude-haiku-4.5 (excellent tool use)
+// → Instead of gemini-flash (may produce malformed tool calls)
+```
+
+**Why this matters:** Some models (like `deepseek-reasoner`) are optimized for chain-of-thought reasoning but can generate malformed tool calls. Tool detection ensures requests with functions go to models proven to handle tool use correctly.
+
+---
+
+## Context-Length-Aware Routing
+
+ClawRouter automatically filters out models that can't handle your context size:
+
+```
+150K token request:
+  Full chain: [grok-4-fast (131K), deepseek (128K), kimi (262K), gemini (1M)]
+  Filtered:   [kimi (262K), gemini (1M)]
+  → Skips models that would fail with "context too long" errors
+```
+
+This prevents wasted API calls and faster fallback to capable models.
+
+---
+
+## Model Aliases
+
+Use short aliases instead of full model paths:
+
+```bash
+/model free      # gpt-oss-120b (FREE!)
+/model br-sonnet # anthropic/claude-sonnet-4.6
+/model br-opus   # anthropic/claude-opus-4
+/model br-haiku  # anthropic/claude-haiku-4.5
+/model gpt       # openai/gpt-4o
+/model gpt5      # openai/gpt-5.2
+/model deepseek  # deepseek/deepseek-chat
+/model reasoner  # deepseek/deepseek-reasoner
+/model kimi      # moonshot/kimi-k2.5
+/model gemini    # google/gemini-2.5-pro
+/model flash     # google/gemini-2.5-flash
+/model grok      # xai/grok-3
+/model grok-fast # xai/grok-4-fast-reasoning
+```
+
+All aliases work with `/model blockrun/xxx` or just `/model xxx`.
+
+---
+
+## Free Tier Fallback
+
+When your wallet balance hits $0, ClawRouter automatically falls back to the free model (`gpt-oss-120b`):
+
+```
+Wallet: $0.00
+Request: "Help me write a function"
+→ Routes to gpt-oss-120b (FREE)
+→ No "insufficient funds" error
+→ Keep building while you top up
+```
+
+You'll never get blocked by an empty wallet — the free tier keeps you running.
+
+---
+
+## Session Persistence
+
+For multi-turn conversations, ClawRouter pins the model to prevent mid-task switching:
+
+```
+Turn 1: "Build a React component" → claude-sonnet-4.6
+Turn 2: "Add dark mode support"   → claude-sonnet-4.6 (pinned)
+Turn 3: "Now add tests"           → claude-sonnet-4.6 (pinned)
+```
+
+Sessions are identified by conversation ID and persist for 1 hour of inactivity.
+
+---
+
+## Cost Tracking with /stats
+
+Track your savings in real-time:
+
+```bash
+# In any OpenClaw conversation
+/stats
+```
+
+Output:
+
+```
++============================================================+
+|              ClawRouter Usage Statistics                   |
++============================================================+
+|  Period: last 7 days                                      |
+|  Total Requests: 442                                      |
+|  Total Cost: $1.73                                       |
+|  Baseline Cost (Opus): $20.13                            |
+|  Total Saved: $18.40 (91.4%)                             |
++------------------------------------------------------------+
+|  Routing by Tier:                                          |
+|    SIMPLE     ===========           55.0% (243)            |
+|    MEDIUM     ======                30.8% (136)            |
+|    COMPLEX    =                      7.2% (32)             |
+|    REASONING  =                      7.0% (31)             |
++============================================================+
+```
+
+Stats are stored locally at `~/.openclaw/blockrun/logs/` and aggregated on demand.

package/docs/image-generation.md

@@ -0,0 +1,380 @@
+# Image Generation & Editing
+
+Generate and edit images via BlockRun's image API with x402 micropayments — no API keys, pay per image.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Models & Pricing](#models--pricing)
+- [API Reference](#api-reference)
+  - [POST /v1/images/generations](#post-v1imagesgenerations)
+  - [POST /v1/images/image2image](#post-v1imagesimage2image)
+- [Code Examples](#code-examples)
+  - [Image Generation](#image-generation-examples)
+  - [Image Editing (img2img)](#image-editing-examples)
+- [In-Chat Commands](#in-chat-commands)
+- [Notes](#notes)
+
+---
+
+## Quick Start
+
+ClawRouter runs a local proxy on port `8402` that handles x402 payments automatically. Point any OpenAI-compatible client at it:
+
+```bash
+curl -X POST http://localhost:8402/v1/images/generations \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "google/nano-banana",
+    "prompt": "a golden retriever surfing on a wave",
+    "size": "1024x1024",
+    "n": 1
+  }'
+```
+
+Response:
+
+```json
+{
+  "created": 1741460000,
+  "data": [
+    {
+      "url": "https://files.catbox.moe/abc123.png"
+    }
+  ]
+}
+```
+
+The returned URL is a publicly hosted image, ready to use in Telegram, Discord, or any client.
+
+---
+
+## Models & Pricing
+
+| Model ID                   | Shorthand       | Price       | Max Size   | Provider          |
+| -------------------------- | --------------- | ----------- | ---------- | ----------------- |
+| `google/nano-banana`       | `nano-banana`   | $0.05/image | 1024×1024  | Google Gemini Flash |
+| `google/nano-banana-pro`   | `banana-pro`    | $0.10/image | 4096×4096  | Google Gemini Pro |
+| `openai/dall-e-3`          | `dall-e-3`      | $0.04/image | 1792×1024  | OpenAI DALL-E 3   |
+| `openai/gpt-image-1`       | `gpt-image`     | $0.02/image | 1536×1024  | OpenAI GPT Image  |
+| `black-forest/flux-1.1-pro`| `flux`          | $0.04/image | 1024×1024  | Black Forest Labs |
+
+Default model: `google/nano-banana`.
+
+---
+
+## API Reference
+
+### `POST /v1/images/generations`
+
+OpenAI-compatible endpoint. Route via ClawRouter proxy (`http://localhost:8402`) for automatic x402 payment handling.
+
+**Request body:**
+
+| Field    | Type     | Required | Description                                      |
+| -------- | -------- | -------- | ------------------------------------------------ |
+| `model`  | `string` | Yes      | Model ID (see table above)                       |
+| `prompt` | `string` | Yes      | Text description of the image to generate        |
+| `size`   | `string` | No       | Image dimensions, e.g. `"1024x1024"` (default)  |
+| `n`      | `number` | No       | Number of images (default: `1`)                  |
+
+**Response:**
+
+```typescript
+{
+  created: number;          // Unix timestamp
+  data: Array<{
+    url: string;            // Publicly hosted image URL
+    revised_prompt?: string; // Model's rewritten prompt (dall-e-3 only)
+  }>;
+}
+```
+
+### `POST /v1/images/image2image`
+
+Edit an existing image using AI. Route via ClawRouter proxy (`http://localhost:8402`) for automatic x402 payment handling.
+
+**Request body:**
+
+| Field    | Type     | Required | Description                                                    |
+| -------- | -------- | -------- | -------------------------------------------------------------- |
+| `model`  | `string` | No       | Model ID (default: `openai/gpt-image-1`)                       |
+| `prompt` | `string` | Yes      | Text description of the edit to apply                          |
+| `image`  | `string` | Yes      | Source image — see **Image input formats** below               |
+| `mask`   | `string` | No       | Mask image (white = area to edit) — same formats as `image`    |
+| `size`   | `string` | No       | Output dimensions, e.g. `"1024x1024"` (default)               |
+
+**Image input formats** — the `image` and `mask` fields accept any of:
+
+| Format              | Example                              | Description                                    |
+| ------------------- | ------------------------------------ | ---------------------------------------------- |
+| Local file path     | `"/Users/me/photo.png"`              | Absolute path — ClawRouter reads the file      |
+| Home-relative path  | `"~/photo.png"`                      | Expands `~` to home directory                  |
+| HTTP/HTTPS URL      | `"https://example.com/photo.png"`    | ClawRouter downloads the image automatically   |
+| Base64 data URI     | `"data:image/png;base64,iVBOR..."`   | Passed through directly (no conversion needed) |
+
+Supported image formats: **PNG**, **JPG/JPEG**, **WebP**.
+
+**Response:**
+
+```typescript
+{
+  created: number;          // Unix timestamp
+  data: Array<{
+    url: string;            // Locally cached image URL (http://localhost:8402/images/...)
+    revised_prompt?: string; // Model's rewritten prompt
+  }>;
+}
+```
+
+---
+
+## Code Examples
+
+### Image Generation Examples {#image-generation-examples}
+
+### curl
+
+```bash
+# Default model (nano-banana, $0.05)
+curl -X POST http://localhost:8402/v1/images/generations \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "google/nano-banana",
+    "prompt": "a futuristic city at sunset, cyberpunk style",
+    "size": "1024x1024",
+    "n": 1
+  }'
+
+# DALL-E 3 with landscape size ($0.04)
+curl -X POST http://localhost:8402/v1/images/generations \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "openai/dall-e-3",
+    "prompt": "a serene Japanese garden in autumn",
+    "size": "1792x1024",
+    "n": 1
+  }'
+```
+
+### TypeScript / Node.js
+
+```typescript
+const response = await fetch("http://localhost:8402/v1/images/generations", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    model: "google/nano-banana",
+    prompt: "a golden retriever surfing on a wave",
+    size: "1024x1024",
+    n: 1,
+  }),
+});
+
+const result = await response.json() as {
+  created: number;
+  data: Array<{ url: string; revised_prompt?: string }>;
+};
+
+const imageUrl = result.data[0].url;
+console.log(imageUrl); // https://files.catbox.moe/xxx.png
+```
+
+### Python
+
+```python
+import requests
+
+response = requests.post(
+    "http://localhost:8402/v1/images/generations",
+    json={
+        "model": "google/nano-banana",
+        "prompt": "a golden retriever surfing on a wave",
+        "size": "1024x1024",
+        "n": 1,
+    }
+)
+
+result = response.json()
+image_url = result["data"][0]["url"]
+print(image_url)
+```
+
+### OpenAI SDK (drop-in)
+
+```typescript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "blockrun",               // any non-empty string
+  baseURL: "http://localhost:8402/v1",
+});
+
+const response = await client.images.generate({
+  model: "google/nano-banana",
+  prompt: "a golden retriever surfing on a wave",
+  size: "1024x1024",
+  n: 1,
+});
+
+console.log(response.data[0].url);
+```
+
+### startProxy (programmatic)
+
+If you're using ClawRouter as a library:
+
+```typescript
+import { startProxy } from "@blockrun/clawrouter";
+
+const proxy = await startProxy({ walletKey: process.env.BLOCKRUN_WALLET_KEY! });
+
+const response = await fetch(`${proxy.baseUrl}/v1/images/generations`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    model: "openai/dall-e-3",
+    prompt: "a serene Japanese garden in autumn",
+    size: "1792x1024",
+    n: 1,
+  }),
+});
+
+const { data } = await response.json();
+console.log(data[0].url);
+
+await proxy.close();
+```
+
+### Image Editing Examples {#image-editing-examples}
+
+### curl
+
+```bash
+# Using a local file path (simplest)
+curl -X POST http://localhost:8402/v1/images/image2image \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "add sunglasses to the person",
+    "image": "~/photo.png"
+  }'
+
+# Using an image URL
+curl -X POST http://localhost:8402/v1/images/image2image \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "change the background to a sunset beach",
+    "image": "https://example.com/photo.png"
+  }'
+
+# With a mask (inpainting — white = area to edit)
+curl -X POST http://localhost:8402/v1/images/image2image \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "replace the background with a starry sky",
+    "image": "~/photo.png",
+    "mask": "~/mask.png"
+  }'
+
+# With explicit model, size, and base64 data URI
+curl -X POST http://localhost:8402/v1/images/image2image \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "openai/gpt-image-1",
+    "prompt": "add a crown",
+    "image": "data:image/png;base64,iVBOR...",
+    "size": "1536x1024"
+  }'
+```
+
+### TypeScript / Node.js
+
+```typescript
+// ClawRouter reads the file for you — no base64 encoding needed
+const response = await fetch("http://localhost:8402/v1/images/image2image", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    prompt: "change the background to a starry sky",
+    image: "/Users/me/photo.png", // or "~/photo.png" or an HTTPS URL
+  }),
+});
+
+const result = (await response.json()) as {
+  created: number;
+  data: Array<{ url: string; revised_prompt?: string }>;
+};
+
+console.log(result.data[0].url); // http://localhost:8402/images/xxx.png
+```
+
+### Python
+
+```python
+import requests
+
+response = requests.post(
+    "http://localhost:8402/v1/images/image2image",
+    json={
+        "prompt": "add a hat to the person",
+        "image": "~/photo.png",  # or an absolute path or HTTPS URL
+    },
+)
+
+result = response.json()
+print(result["data"][0]["url"])
+```
+
+---
+
+## In-Chat Commands
+
+When using ClawRouter with OpenClaw, generate and edit images directly from any conversation:
+
+### `/imagegen` — Generate images
+
+```
+/imagegen a dog dancing on the beach
+/imagegen --model dall-e-3 a futuristic city at sunset
+/imagegen --model banana-pro --size 2048x2048 mountain landscape
+```
+
+| Flag      | Default       | Description           |
+| --------- | ------------- | --------------------- |
+| `--model` | `nano-banana` | Model shorthand or ID |
+| `--size`  | `1024x1024`   | Image dimensions      |
+
+### `/img2img` — Edit images
+
+```
+/img2img --image ~/photo.png change the background to a starry sky
+/img2img --image ./cat.jpg --mask ./mask.png remove the background
+/img2img --image /tmp/portrait.png --size 1536x1024 add a hat
+```
+
+| Flag      | Default        | Description                           |
+| --------- | -------------- | ------------------------------------- |
+| `--image` | _(required)_   | Local image file path (supports `~/`) |
+| `--mask`  | _(none)_       | Mask image (white = area to edit)     |
+| `--model` | `gpt-image-1`  | Model to use                          |
+| `--size`  | `1024x1024`    | Output size                           |
+
+### Model shorthands
+
+| Shorthand     | Full ID                     |
+| ------------- | --------------------------- |
+| `nano-banana` | `google/nano-banana`        |
+| `banana-pro`  | `google/nano-banana-pro`    |
+| `dall-e-3`    | `openai/dall-e-3`           |
+| `gpt-image`   | `openai/gpt-image-1`       |
+| `flux`        | `black-forest/flux-1.1-pro` |
+
+---
+
+## Notes
+
+- **Local image caching** — All images (generated and edited) are cached locally at `~/.openclaw/blockrun/images/` and served via `http://localhost:8402/images/`. Both base64 data URIs and HTTP URLs from upstream are downloaded and replaced with localhost URLs.
+- **Payment** — Each image costs the listed price in USDC, deducted from your wallet via x402. Make sure your wallet is funded before generating or editing.
+- **No DALL-E content policy bypass** — DALL-E 3 and GPT Image 1 still apply OpenAI's content policy. Use `flux` or `nano-banana` for more flexibility with generation.
+- **Size limits** — Requesting a size larger than the model's max will return an error. Check the table above before setting `--size`.
+- **Image editing** — The `/v1/images/image2image` endpoint currently supports `openai/gpt-image-1` (default). The `image` and `mask` fields accept local file paths (`~/photo.png`, `/abs/path.png`), HTTP/HTTPS URLs, or base64 data URIs. ClawRouter handles file reading and URL downloading automatically. Supported formats: PNG, JPG/JPEG, WebP.