lynkr 9.2.0 → 9.2.1

package/README.md

@@ -27,48 +27,102 @@
 npm install -g lynkr
 ```
 
-### 2. Choose Your Setup
+### 2. Configure Lynkr
+
+First run creates a `.env` file. Edit it with your provider settings.
+
+**Option A: Free & Local (Ollama) - Recommended for Testing**
 
-**Option A: Free & Local (Ollama)**
 ```bash
 # Install Ollama first: https://ollama.com
 ollama pull qwen2.5-coder:latest
-
-# Start Lynkr
-lynkr start
 ```
 
-Your `.env` file (auto-created on first run):
+Create/edit `.env` in your project directory:
 ```bash
+# Provider
 MODEL_PROVIDER=ollama
 FALLBACK_ENABLED=false
+
+# Ollama Configuration
+OLLAMA_ENDPOINT=http://localhost:11434
 OLLAMA_MODEL=qwen2.5-coder:latest
+
+# Server
+PORT=8081
+
+# Increase limits for Claude Code/Cursor
+POLICY_MAX_STEPS=50
+POLICY_MAX_TOOL_CALLS=100
+
+# Disable overly strict command filtering
+POLICY_SAFE_COMMANDS_ENABLED=false
 ```
 
-**Option B: Cloud Provider (OpenRouter)**
+**Option B: Cloud (OpenRouter) - Recommended for Production**
+
 ```bash
 # Get API key from https://openrouter.ai
-lynkr start
 ```
 
-Your `.env` file:
+Create/edit `.env`:
 ```bash
+# Provider
 MODEL_PROVIDER=openrouter
 OPENROUTER_API_KEY=sk-or-v1-your-key-here
 FALLBACK_ENABLED=false
+
+# Server
+PORT=8081
+
+# Increase limits
+POLICY_MAX_STEPS=50
+POLICY_MAX_TOOL_CALLS=100
+
+# Optional: Enable caching
+PROMPT_CACHE_ENABLED=true
+SEMANTIC_CACHE_ENABLED=true
 ```
 
 **Option C: Enterprise (AWS Bedrock)**
-```bash
-lynkr start
-```
 
-Your `.env` file:
+Create/edit `.env`:
 ```bash
+# Provider
 MODEL_PROVIDER=bedrock
 AWS_BEDROCK_API_KEY=your-aws-key
 AWS_BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0
 FALLBACK_ENABLED=false
+
+# Server
+PORT=8081
+
+# Increase limits
+POLICY_MAX_STEPS=50
+POLICY_MAX_TOOL_CALLS=100
+```
+
+**Option D: Enterprise (Databricks)**
+
+Create/edit `.env`:
+```bash
+# Provider
+MODEL_PROVIDER=databricks
+DATABRICKS_API_BASE=https://your-workspace.cloud.databricks.com
+DATABRICKS_API_KEY=your-token
+FALLBACK_ENABLED=false
+
+# Server
+PORT=8081
+
+# Increase limits
+POLICY_MAX_STEPS=50
+POLICY_MAX_TOOL_CALLS=100
+```
+
+Then start Lynkr:
+```bash
+lynkr start
 ```
 
 ### 3. Connect Your Tool
@@ -169,52 +223,222 @@ Lynkr analyzes each request and routes it to the appropriate tier. Simple questi
 
 ---
 
-## Configuration Examples
+## Complete .env Examples
+
+### MVP: Minimal Working Setup (Ollama)
+
+Copy-paste ready configuration for immediate use:
 
-### Minimal Ollama Setup
 ```bash
-# .env
+# .env - Minimal Ollama Setup
+
+# ============================================
+# REQUIRED: Provider Configuration
+# ============================================
 MODEL_PROVIDER=ollama
 FALLBACK_ENABLED=false
+
+# ============================================
+# REQUIRED: Ollama Settings
+# ============================================
+OLLAMA_ENDPOINT=http://localhost:11434
 OLLAMA_MODEL=qwen2.5-coder:latest
+
+# ============================================
+# REQUIRED: Server Configuration
+# ============================================
+PORT=8081
+HOST=0.0.0.0
+
+# ============================================
+# REQUIRED: Claude Code/Cursor Compatibility
+# ============================================
 POLICY_MAX_STEPS=50
 POLICY_MAX_TOOL_CALLS=100
+POLICY_SAFE_COMMANDS_ENABLED=false
+
+# ============================================
+# OPTIONAL: Performance (Recommended)
+# ============================================
+LOG_LEVEL=warn
+LOAD_SHEDDING_ENABLED=true
+LOAD_SHEDDING_HEAP_THRESHOLD=0.85
 ```
 
-### Production Cloud Setup
+**Steps:**
+1. Install Ollama: `curl -fsSL https://ollama.com/install.sh | sh`
+2. Pull model: `ollama pull qwen2.5-coder:latest`
+3. Copy above to `.env` in your project directory
+4. Run: `lynkr start`
+
+---
+
+### Production: Cloud with Tier Routing (OpenRouter)
+
+Optimized for cost savings with smart routing:
+
 ```bash
-# .env
+# .env - Production OpenRouter Setup
+
+# ============================================
+# REQUIRED: Provider Configuration
+# ============================================
 MODEL_PROVIDER=openrouter
-OPENROUTER_API_KEY=sk-or-v1-your-key
+OPENROUTER_API_KEY=sk-or-v1-your-key-here
 FALLBACK_ENABLED=false
 
-# Tier routing for cost optimization
+# ============================================
+# REQUIRED: Server Configuration
+# ============================================
+PORT=8081
+HOST=0.0.0.0
+
+# ============================================
+# TIER ROUTING: Smart Cost Optimization
+# ============================================
+# Simple queries → Cheap/fast model
 TIER_SIMPLE=openrouter:google/gemini-flash-1.5
+
+# Normal coding → Balanced model
 TIER_MEDIUM=openrouter:anthropic/claude-3.5-sonnet
+
+# Complex refactoring → Powerful model
 TIER_COMPLEX=openrouter:anthropic/claude-opus-4
+
+# Deep reasoning → Most capable model
 TIER_REASONING=openrouter:anthropic/claude-opus-4
 
-# Increase limits
+# ============================================
+# REQUIRED: Claude Code/Cursor Compatibility
+# ============================================
 POLICY_MAX_STEPS=50
 POLICY_MAX_TOOL_CALLS=100
+POLICY_SAFE_COMMANDS_ENABLED=false
 
-# Optional: Enable caching for repeated prompts
+# ============================================
+# OPTIONAL: Token Optimization (60-80% savings)
+# ============================================
 PROMPT_CACHE_ENABLED=true
 SEMANTIC_CACHE_ENABLED=true
+SEMANTIC_CACHE_THRESHOLD=0.95
+TOOL_INJECTION_ENABLED=false
+
+# ============================================
+# OPTIONAL: Performance Tuning
+# ============================================
+LOG_LEVEL=warn
+LOAD_SHEDDING_ENABLED=true
+LOAD_SHEDDING_HEAP_THRESHOLD=0.85
 ```
 
-### Enterprise Databricks Setup
+**Expected savings:** 70-90% of requests use Gemini Flash ($). Only 10-30% use Claude Opus ($$$).
+
+---
+
+### Enterprise: Databricks Foundation Models
+
+For teams using Databricks Model Serving:
+
 ```bash
-# .env
+# .env - Enterprise Databricks Setup
+
+# ============================================
+# REQUIRED: Provider Configuration
+# ============================================
 MODEL_PROVIDER=databricks
 DATABRICKS_API_BASE=https://your-workspace.cloud.databricks.com
-DATABRICKS_API_KEY=your-token
+DATABRICKS_API_KEY=dapi1234567890abcdef
 FALLBACK_ENABLED=false
 
+# ============================================
+# REQUIRED: Model Configuration
+# ============================================
+# Option 1: Single model (no tier routing)
+DATABRICKS_MODEL=databricks-meta-llama-3-1-405b-instruct
+
+# Option 2: Tier routing (comment out above, uncomment below)
+# TIER_SIMPLE=databricks:databricks-meta-llama-3-1-70b-instruct
+# TIER_MEDIUM=databricks:databricks-claude-sonnet-4-5
+# TIER_COMPLEX=databricks:databricks-claude-opus-4-6
+# TIER_REASONING=databricks:databricks-claude-opus-4-6
+
+# ============================================
+# REQUIRED: Server Configuration
+# ============================================
+PORT=8081
+HOST=0.0.0.0
+
+# ============================================
+# REQUIRED: Claude Code/Cursor Compatibility
+# ============================================
+POLICY_MAX_STEPS=50
+POLICY_MAX_TOOL_CALLS=100
+POLICY_SAFE_COMMANDS_ENABLED=false
+
+# ============================================
+# OPTIONAL: Enterprise Features
+# ============================================
+LOG_LEVEL=info
+LOAD_SHEDDING_ENABLED=true
+LOAD_SHEDDING_HEAP_THRESHOLD=0.85
+
+# Optional: Metrics for monitoring
+# PROMETHEUS_METRICS_ENABLED=true
+```
+
+---
+
+### Hybrid: Local + Cloud Fallback
+
+Use free Ollama, fallback to cloud when needed:
+
+```bash
+# .env - Hybrid Setup (Advanced)
+
+# ============================================
+# PRIMARY: Local Ollama
+# ============================================
+MODEL_PROVIDER=ollama
+OLLAMA_ENDPOINT=http://localhost:11434
+OLLAMA_MODEL=qwen2.5-coder:latest
+
+# ============================================
+# FALLBACK: Cloud Provider
+# ============================================
+FALLBACK_ENABLED=true
+FALLBACK_PROVIDER=openrouter
+OPENROUTER_API_KEY=sk-or-v1-your-key-here
+
+# ============================================
+# TIER ROUTING: Mix Local + Cloud
+# ============================================
+TIER_SIMPLE=ollama:qwen2.5:3b
+TIER_MEDIUM=ollama:qwen2.5:7b
+TIER_COMPLEX=openrouter:anthropic/claude-3.5-sonnet
+TIER_REASONING=openrouter:anthropic/claude-opus-4
+
+# ============================================
+# REQUIRED: Server Configuration
+# ============================================
+PORT=8081
+HOST=0.0.0.0
+
+# ============================================
+# REQUIRED: Claude Code/Cursor Compatibility
+# ============================================
 POLICY_MAX_STEPS=50
 POLICY_MAX_TOOL_CALLS=100
+POLICY_SAFE_COMMANDS_ENABLED=false
+
+# ============================================
+# OPTIONAL: Performance
+# ============================================
+LOG_LEVEL=warn
+LOAD_SHEDDING_ENABLED=true
 ```
 
+**Best of both worlds:** 80% of requests stay local (free). Complex tasks use cloud (paid).
+
 ---
 
 ## Common Issues & Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkr",
-  "version": "9.2.0",
+  "version": "9.2.1",
   "description": "Self-hosted Claude Code & Cursor proxy with Databricks,AWS BedRock,Azure  adapters, openrouter, Ollama,llamacpp,LM Studio, workspace tooling, and MCP integration.",
   "main": "index.js",
   "bin": {