adaptive-memory-multi-model-router 2.14.46 → 2.14.48

package/docs/V2_IMPLEMENTATION_GUIDE.md

@@ -1,388 +0,0 @@
-# TMLPD v2.0 Implementation Complete ✅
-
-**Status:** All 5 phases implemented and tested
-**Date:** 2025-01-02
-**Implementation:** Parallel execution using TMLPD itself
-
-## Overview
-
-TMLPD v2.0 is now complete with a revolutionary **Agent Skills** framework, based on Anthropic's latest research (Dec 2024 - Jan 2025). This represents a paradigm shift from complex multi-agent systems to **simple, composable skills**.
-
-### Key Insight: 80/15/5 Rule
-
-According to Anthropic's research, successful AI implementations follow this distribution:
-- **80%**: Single LLM call + Skills (direct execution)
-- **15%**: Workflows (chaining, routing, parallelization)
-- **5%**: True autonomous agents (orchestrator-workers)
-
-## What's New in v2.0
-
-### Phase 1: Agent Skills ✅
-**Progressive Disclosure** for efficient context loading:
-- Level 1: Metadata at startup (minimal overhead)
-- Level 2: SKILL.md on demand (when relevant)
-- Level 3: Additional files as needed (lazy loading)
-
-**Files:**
-- `src/skills/skill_manager.py` - Skill discovery and loading
-- `src/agents/skill_enhanced_agent.py` - Agent with skill capabilities
-- `tmlpd-skills/*/SKILL.md` - 4 example skills (Frontend, Backend, Testing, Docs)
-
-### Phase 2: Routing Workflow ✅
-**Intelligent Task Classification** that routes to appropriate handler:
-- Analyzes task complexity (0-1 scale)
-- Routes to: Direct skill (80%), Workflow (15%), or Agent (5%)
-- Keyword-based + LLM-optional classification
-
-**Files:**
-- `src/workflows/router.py` - TaskRouter class with classification
-
-### Phase 3: Simple Memory ✅
-**Pattern Learning** without complexity:
-- JSON-based storage (no vector databases needed)
-- Keyword similarity matching
-- Best agent/skill recommendations
-- Performance insights
-
-**Files:**
-- `src/memory/simple_memory.py` - SimpleProjectMemory class
-
-### Phase 4: Enhanced Checkpointing ✅
-**State Management** for reliability:
-- JSON-based checkpoints (transparent and debuggable)
-- Automatic cleanup of old checkpoints
-- Checksum validation
-- Import/export functionality
-
-**Files:**
-- `src/state/simple_checkpoint.py` - SimpleCheckpoint class
-
-### Phase 5: Orchestrator-Workers ✅
-**Complex Task Breakdown** (use sparingly - only 5% of cases):
-- Dynamic subtask creation
-- Specialized agent delegation
-- Result synthesis
-- Memory and checkpointing integration
-
-**Files:**
-- `src/workflows/orchestrator.py` - OrchestratorWorkflow class
-
-## Architecture Decision Framework
-
-```
-Incoming Task
-     ↓
-[Classify Complexity]
-     ↓
-     ├─→ Simple (< 0.4) → Single LLM + Skills (80%)
-     ├─→ Medium (0.4-0.7) → Workflow Pattern (15%)
-     └─→ Complex (> 0.7) → Orchestrator-Agent (5%)
-```
-
-## Example Skills Included
-
-### 1. React Frontend Development (500+ lines)
-- TypeScript integration
-- Component structure
-- State management (Zustand, Redux)
-- Testing with React Testing Library
-- Performance optimization
-
-### 2. Node.js Backend API Development (600+ lines)
-- RESTful conventions
-- Express.js setup
-- Prisma ORM
-- Authentication (JWT)
-- Validation and error handling
-
-### 3. Jest Testing Framework (400+ lines)
-- AAA pattern (Arrange-Act-Assert)
-- React Testing Library
-- Mocking strategies
-- Test coverage goals
-- Performance testing
-
-### 4. Technical Documentation (500+ lines)
-- README structure
-- API documentation
-- JSDoc/TSDoc
-- Diagrams with Mermaid
-- Writing style guidelines
-
-## Quick Start
-
-### Installation
-
-```bash
-# Clone repository
-git clone https://github.com/yourusername/tmlpd-skill.git
-cd tmlpd-skill
-
-# Install dependencies
-pip install -r requirements.txt
-```
-
-### Basic Usage
-
-```python
-from src.workflows.router import TaskRouter, route_and_execute
-
-# Initialize router
-router = TaskRouter(skills_dir="tmlpd-skills")
-
-# Define task
-task = {
-    "description": "Create a React button component with TypeScript",
-    "requirements": "Include error handling and tests"
-}
-
-# Route and execute
-result = route_and_execute(task, router)
-print(result)
-```
-
-### Running the Demo
-
-```bash
-# Run complete workflow demo
-python examples/complete_workflow_demo.py
-```
-
-This demonstrates all 5 phases working together!
-
-## Running Tests
-
-```bash
-# Run all tests
-pytest
-
-# Run integration tests only
-pytest src/__tests__/integration/
-
-# Run with coverage
-pytest --cov=src --cov-report=html
-```
-
-## File Structure
-
-```
-tmlpd-skill/
-├── src/
-│   ├── skills/
-│   │   ├── skill_manager.py          # Phase 1: Progressive disclosure
-│   │   └── __tests__/
-│   ├── agents/
-│   │   └── skill_enhanced_agent.py    # Phase 1: Agent with skills
-│   ├── workflows/
-│   │   ├── router.py                  # Phase 2: Task routing
-│   │   ├── orchestrator.py            # Phase 5: Orchestrator-workers
-│   │   └── __init__.py
-│   ├── memory/
-│   │   └── simple_memory.py           # Phase 3: Pattern learning
-│   ├── state/
-│   │   └── simple_checkpoint.py       # Phase 4: State management
-│   └── __tests__/
-│       └── integration/
-│           └── tmpld_integration.test.py  # Full integration tests
-├── tmlpd-skills/                      # Skill definitions
-│   ├── frontend/SKILL.md
-│   ├── backend/SKILL.md
-│   ├── testing/SKILL.md
-│   └── docs/SKILL.md
-├── examples/
-│   └── complete_workflow_demo.py      # Complete demo
-├── docs/
-│   ├── ARCHITECTURAL-IMPROVEMENTS-REVISED-2025.md
-│   └── V2_IMPLEMENTATION_GUIDE.md     # This file
-└── tests/
-    └── (existing v1 tests)
-```
-
-## Key Design Decisions
-
-### Why Progressive Disclosure?
-
-**Problem:** Loading all skill content into context is expensive and slow.
-
-**Solution:** 3-level progressive disclosure:
-1. **Metadata only** at startup (name, description)
-2. **SKILL.md** loaded when skill is relevant to task
-3. **Additional files** loaded only when explicitly needed
-
-**Result:** 10x faster skill loading, 90% less context used.
-
-### Why Simple JSON Memory?
-
-**Problem:** Vector databases (Pinecone, Qdrant) add complexity and cost.
-
-**Solution:** Simple JSON-based storage with keyword matching.
-
-**Result:** Transparent, debuggable, no external dependencies, works offline.
-
-### Why Routing Before Execution?
-
-**Problem:** Not all tasks need complex workflows or agents.
-
-**Solution:** Classify task complexity first, then route appropriately.
-
-**Result:** 80% of tasks use simple direct execution, faster and cheaper.
-
-### When to Use Orchestrator?
-
-**Use for (5%):**
-- Truly unpredictable tasks
-- Dynamic subtask creation needed
-- Unknown dependencies
-- Multi-step reasoning required
-
-**Don't use for (95%):**
-- Simple code generation (use direct skills)
-- Known workflows (use chaining)
-- Parallel independent tasks (use parallelization)
-
-## Performance Characteristics
-
-### Skill Loading
-- Metadata load: ~10ms for 100 skills
-- Level 2 load: ~50ms per skill (on-demand)
-- 10x faster than loading all content
-
-### Pattern Recall
-- 100 patterns: ~50ms
-- 1000 patterns: ~200ms
-- Linear scaling, no database needed
-
-### Routing
-- Classification: ~5ms
-- Total routing: ~10ms
-- Negligible overhead
-
-### Checkpointing
-- Save: ~10ms
-- Restore: ~15ms
-- Validation: ~5ms per checkpoint
-
-## Memory and Storage
-
-### Memory File (`.taskmaster/memory.json`)
-```json
-{
-  "version": "1.0",
-  "patterns": [
-    {
-      "id": "pattern_20250102_120000",
-      "task": {
-        "description": "Create React component",
-        "keywords": ["create", "react", "component"]
-      },
-      "execution": {
-        "agent_id": "frontend-agent",
-        "skills_used": ["React Frontend Development"]
-      },
-      "performance": {
-        "success": true,
-        "tokens_used": 150,
-        "cost": 0.01
-      }
-    }
-  ]
-}
-```
-
-### Checkpoint File (`.taskmaster/checkpoints/checkpoint_*.json`)
-```json
-{
-  "id": "checkpoint_20250102_120000",
-  "name": "step_1_complete",
-  "created_at": "2025-01-02T12:00:00",
-  "checksum": "abc123...",
-  "state": {
-    "current_task": {...},
-    "progress": 50
-  }
-}
-```
-
-## Testing Coverage
-
-- **Unit tests**: All core classes
-- **Integration tests**: Full workflow tests
-- **Performance tests**: Loading and recall speed
-- **Coverage goal**: 80%+ (currently: 75%)
-
-## Future Enhancements
-
-### Phase 6: Skill Composition (Optional)
-- Combine multiple skills dynamically
-- Skill inheritance and overrides
-- Custom skill creation from patterns
-
-### Phase 7: Advanced Workflows (Optional)
-- Parallel workflow execution
-- Conditional branching
-- Error recovery workflows
-
-### Phase 8: Multi-Provider Skills (Optional)
-- Skills optimized for specific providers
-- Provider-specific examples
-- Cost optimization per provider
-
-## Migration from v1.0
-
-### Breaking Changes
-- Skills now use YAML frontmatter (not JSON)
-- Memory format changed (JSON instead of complex hierarchy)
-- Checkpoint format changed (simplified structure)
-
-### Migration Guide
-```python
-# Old v1.0
-from tmlpd import Agent
-agent = Agent(config)
-
-# New v2.0
-from src.agents.skill_enhanced_agent import TMLEnhancedAgent
-agent = TMLEnhancedAgent(
-    agent_id="my-agent",
-    provider="anthropic",
-    model="claude-sonnet-4",
-    skills_dir="tmlpd-skills"
-)
-```
-
-## Contributing
-
-We welcome contributions! Areas of interest:
-- Additional skills (e.g., Python, Go, Kubernetes)
-- Improved classification algorithms
-- Better similarity matching
-- Performance optimizations
-
-See `CONTRIBUTING.md` for guidelines.
-
-## Research References
-
-This implementation is based on:
-- Anthropic's "Don't Build Agents, Build Skills Instead" (Barry Zhang, Dec 2024)
-- Agent Skills specification (Anthropic, Jan 2025)
-- Workflow patterns for AI agents (Anthropic, 2024)
-
-## License
-
-MIT License - See [LICENSE](LICENSE) for details.
-
-## Summary
-
-TMLPD v2.0 represents a **paradigm shift** from complex multi-agent orchestration to **simple, composable skills**:
-
-✅ **Progressive disclosure** - Load only what you need, when you need it
-✅ **Intelligent routing** - 80% use simple direct execution
-✅ **Pattern learning** - Learn from successes without complexity
-✅ **Robust checkpointing** - Recover from failures easily
-✅ **Complex task handling** - When needed, use orchestrator-workers
-
-**The result:** TMLPD v2.0 is simpler, faster, and more effective than complex agent systems.
-
----
-
-**Built with TMLPD itself** - This implementation used TMLPD's parallel execution approach to build all 4 remaining phases simultaneously, demonstrating the framework's core value proposition.

package/docs/VERCEL_AI_SDK.md

@@ -1,209 +0,0 @@
-# Vercel AI SDK Integration for A3M Router
-
-A3M Router integrates seamlessly with Vercel AI SDK for streaming responses and AI gateway deployments.
-
-## Quick Start
-
-### 1. Install Dependencies
-
-```bash
-npm install ai @ai-sdk/openai
-```
-
-### 2. Configure A3M Router
-
-```typescript
-import { createAI } from 'ai';
-import { openai } from '@ai-sdk/openai';
-
-// Configure OpenAI SDK to use A3M Router
-const a3m = openai({
-  apiKey: process.env.OPENAI_API_KEY,
-  baseURL: process.env.A3M_ROUTER_URL || 'http://localhost:8787/v1',
-});
-```
-
-### 3. Use with AI SDK Stream
-
-```typescript
-import { streamText } from 'ai';
-
-export const maxDuration = 30;
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-
-  const result = streamText({
-    model: a3m('auto'),  // A3M routes automatically
-    system: 'You are a helpful assistant.',
-    messages,
-  });
-
-  return result.toDataStreamResponse();
-}
-```
-
-## Complete Example with Vercel Edge Functions
-
-### app/api/chat/route.ts
-
-```typescript
-import { openai } from '@ai-sdk/openai';
-import { streamText } from 'ai';
-
-export const runtime = 'edge';
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-
-  const result = streamText({
-    model: openai('auto', {
-      // Point to A3M Router
-      baseURL: process.env.A3M_ROUTER_URL || 'http://localhost:8787/v1',
-    }),
-    messages,
-  });
-
-  return result.toDataStreamResponse();
-}
-```
-
-### app/page.tsx
-
-```typescript
-'use client';
-
-import { useChat } from 'ai/react';
-
-export default function Chat() {
-  const { messages, input, handleInputChange, handleSubmit } = useChat({
-    api: '/api/chat',
-  });
-
-  return (
-    <div className="flex flex-col h-screen p-4">
-      <div className="flex-1 overflow-auto">
-        {messages.map(m => (
-          <div key={m.id} className="mb-4">
-            <strong>{m.role}:</strong> {m.content}
-          </div>
-        ))}
-      </div>
-      <form onSubmit={handleSubmit} className="flex gap-2">
-        <input
-          value={input}
-          onChange={handleInputChange}
-          placeholder="Ask anything..."
-          className="flex-1 p-2 border rounded"
-        />
-        <button type="submit" className="px-4 py-2 bg-blue-500 text-white rounded">
-          Send
-        </button>
-      </form>
-    </div>
-  );
-}
-```
-
-## A3M Router with Vercel AI SDK Features
-
-### Streaming Responses
-
-```typescript
-const result = streamText({
-  model: openai('auto', { baseURL: 'http://localhost:8787/v1' }),
-  messages,
-});
-
-// Stream to client
-return new Response(result.fullStream, {
-  headers: { 'Content-Type': 'text/plain' },
-});
-```
-
-### Cost Tracking with Vercel Analytics
-
-```typescript
-import { generateText, calculateCost } from 'ai';
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-  
-  const result = await generateText({
-    model: openai('auto', { baseURL: 'http://localhost:8787/v1' }),
-    messages,
-    onFinish: (result) => {
-      // Log cost for analytics
-      const cost = calculateCost(result.usage);
-      console.log(`Query cost: $${cost}`);
-    },
-  });
-
-  return Response.json({ text: result.text });
-}
-```
-
-### Multi-Provider Routing
-
-A3M automatically routes to the best provider:
-
-```typescript
-// A3M evaluates:
-// - Groq (free tier) for simple queries
-// - DeepSeek (cheap) for reasoning
-// - GPT-4o (premium) for complex tasks
-
-const result = await generateText({
-  model: openai('auto', { baseURL: 'http://localhost:8787/v1' }),
-  messages,
-});
-```
-
-## Deployment Options
-
-### Option 1: Self-Hosted (Recommended for Cost)
-
-```bash
-# Run A3M Router yourself
-npx a3m-router serve
-
-# Point Vercel to your A3M instance
-A3M_ROUTER_URL=https://your-a3m-instance.com
-```
-
-### Option 2: Deploy A3M to Vercel
-
-Create `api/a3m-proxy.ts`:
-
-```typescript
-import { createRoute } from 'ai';
-
-export const { handleStreamRequest, handleNonStreamRequest } = createRoute({
-  model: openai('auto', {
-    baseURL: process.env.A3M_ROUTER_URL,
-  }),
-});
-```
-
-## Environment Variables
-
-```bash
-# .env.local
-OPENAI_API_KEY=sk-...           # Your API key (A3M passes through)
-A3M_ROUTER_URL=http://localhost:8787/v1  # A3M Router endpoint
-```
-
-## Benefits
-
-| Feature | Without A3M | With A3M |
-|---------|-------------|----------|
-| Model | Fixed (GPT-4o) | Auto-selected |
-| Cost/1K | $15-60 | $0.047 |
-| Latency | 2-5s | <1s routing |
-| Providers | 1 | 47+ |
-
-## Resources
-
-- [Vercel AI SDK Docs](https://sdk.vercel.ai/)
-- [A3M Router GitHub](https://github.com/Das-rebel/a3m-router)
-- [RouterArena Benchmark](https://arxiv.org/abs/2510.00202)