quay-ai-factory 0.3.0 → 0.4.0

package/README.md

@@ -1,18 +1,18 @@
 # Quay - Autonomous AI Software Factory
 
-> Self-hosted AI agents with MCP integration, customizable pipelines, real-time Mission Control dashboard, cost transparency, and full audit trails.
+> Self-hosted AI agents with MCP integration, A3M routing, customizable pipelines, real-time Mission Control dashboard, cost transparency, and full audit trails.
 
 ## 🚀 Features
 
 ### 5 AI-Powered Features (Built on A3M Router)
 
-| Feature | Description |
-|---------|-------------|
-| **Human-in-Loop Verification** | Require approval before critical actions (deploy, delete) |
-| **Determinism & Replay** | Black-box recorder captures every step for reproducibility |
-| **Visual Pipeline Builder** | Drag-drop YAML pipeline generation with built-in templates |
-| **Agent RAG** | Knowledge grounding to reduce hallucinations |
-| **Self-Healing Agents** | Auto-detect and recover from failures |
+| Feature | Description | Agent Integration |
+|---------|-------------|-------------------|
+| **Human-in-Loop Verification** | Require approval before critical actions | Auto-triggers on deploy, delete, rm, etc. |
+| **Determinism & Replay** | Black-box recorder captures every step | Snapshots after each LLM call |
+| **Visual Pipeline Builder** | Drag-drop YAML pipeline generation | Built-in templates for common workflows |
+| **Agent RAG** | Knowledge grounding to reduce hallucinations | Applied before first LLM call |
+| **Self-Healing Agents** | Auto-detect and recover from failures | Detects 7 failure types, 5 recovery strategies |
 
 ### Core Capabilities
 
@@ -25,7 +25,7 @@
 ## 📦 Installation
 
 ```bash
-npm install
+npm install quay-ai-factory
 ```
 
 ## 🏃‍♂️ Running
@@ -42,6 +42,88 @@ node build
 bun test
 ```
 
+## 🤖 Agent Runner
+
+The `AgentRunner` orchestrates the observe→plan→act loop with all 5 AI features:
+
+```typescript
+import { agentRunner } from './server/agents/agentRunner.js';
+
+// Run an agent with all features enabled
+const result = await agentRunner.run(
+  { id: 'task-1', title: 'Deploy to production', description: '...' },
+  { id: 'agent-1', name: 'DeployBot', type: 'coder', provider: 'openai', model: 'gpt-4o', config: '{}' },
+  'run-123',
+  'You are a deployment agent...',
+  ['bash', 'deploy'],
+  {
+    knowledgeBaseId: 'kb-1',        // Enable RAG grounding
+    verificationConfig: {            // Custom verification rules
+      criticalActions: ['deploy', 'delete'],
+      autoApproveBelow: 0.10,
+    },
+    maxSteps: 30,                   // Custom step limit
+  }
+);
+```
+
+### How Features Integrate
+
+```
+User Request
+    ↓
+AgentRunner.run()
+    ↓
+┌─────────────────────────────────────────┐
+│ 1. RAG Grounding                        │
+│    buildGroundedPrompt()                │
+│    → Adds relevant knowledge to prompt  │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 2. LLM Call                             │
+│    callLLM() with A3M routing           │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 3. Self-Healing Check                   │
+│    detectFailure() → getRecoveryStrategy│
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 4. Determinism Snapshot                 │
+│    createSnapshot() with state hash     │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 5. Health Update                        │
+│    updateHealthStatus()                 │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 6. Critical Action Verification        │
+│    createVerificationRequest()          │
+│    → Pauses if approval needed         │
+└─────────────────────────────────────────┘
+    ↓
+Tool Execution → Loop
+```
+
+## 🔧 Configuration
+
+```bash
+# Environment variables
+OPENAI_API_KEY=sk-...                    # OpenAI API key
+ANTHROPIC_API_KEY=sk-ant-...             # Anthropic API key
+QUAY_DEFAULT_LLM_URL=https://api.openai.com/v1  # Default LLM endpoint
+
+EMBEDDING_PROVIDER=openai                # openai, local, or mock
+EMBEDDING_ENDPOINT=http://localhost:11434/api/embeddings
+QUAY_DB_PATH=./quay.db                   # Database path
+SSE_ENABLED=true                         # Enable SSE
+NODE_ENV=production                      # production, development, test
+```
+
 ## 🧪 Features
 
 ### Verification Dashboard (`/verification`)
@@ -64,6 +146,8 @@ const request = await createVerificationRequest(
 approveRequest(request.id, 'admin');
 ```
 
+**Critical Actions** (auto-detected): `deploy`, `delete`, `rm`, `drop`, `truncate`, `shutdown`, `restart`
+
 ### Health Monitor (`/health`)
 Real-time agent health status with self-healing.
 
@@ -76,8 +160,13 @@ updateHealthStatus('agent-1', { latencyMs: 150, success: true });
 // Detect failure and get recovery strategy
 const failure = detectFailure(new Error('timeout'));
 const strategy = getRecoveryStrategy(failure.type);
+// → { action: 'retry', maxRetries: 3, fallbackModel: 'gpt-4o-mini' }
 ```
 
+**Failure Types**: `timeout`, `rate_limit`, `api_error`, `context_overflow`, `tool_error`, `unknown`
+
+**Recovery Strategies**: `retry`, `fallback_model`, `fallback_agent`, `abort`, `skip_step`
+
 ### Knowledge Base (`/knowledge`)
 RAG-powered knowledge grounding.
 
@@ -103,6 +192,8 @@ const templates = getTemplates('code-review');
 const yaml = generateYAML(nodes, edges);
 ```
 
+**Built-in Templates**: `code-review`, `security-scan`, `data-processing`, `research-agent`
+
 ### Replay (`/replay`)
 Deterministic replay of agent runs.
 
@@ -113,43 +204,34 @@ await createSnapshot(runId, stepIndex, state);
 const session = await startReplay(runId);
 ```
 
-## 🔧 Configuration
-
-```bash
-# Environment variables
-OPENAI_API_KEY=sk-...          # OpenAI API key
-EMBEDDING_PROVIDER=openai       # openai, local, or mock
-EMBEDDING_ENDPOINT=http://localhost:11434/api/embeddings
-QUAY_DB_PATH=./quay.db          # Database path
-SSE_ENABLED=true                # Enable SSE
-NODE_ENV=production             # production, development, test
-```
-
 ## 📁 Project Structure
 
 ```
 quay/
 ├── src/
 │   ├── lib/
-│   │   ├── features/          # 5 AI features
-│   │   │   ├── verification.ts
-│   │   │   ├── determinism.ts
-│   │   │   ├── visualBuilder.ts
-│   │   │   ├── agentRAG.ts
-│   │   │   └── selfHealing.ts
-│   │   ├── components/         # Svelte UI components
-│   │   ├── sse/              # SSE broadcaster
-│   │   ├── a3m.ts            # A3M router integration
-│   │   ├── db.ts             # Database layer
-│   │   └── embedding.ts       # Embedding service
+│   │   ├── features/              # 5 AI features
+│   │   │   ├── verification.ts    # Human-in-loop
+│   │   │   ├── determinism.ts     # Snapshots & replay
+│   │   │   ├── visualBuilder.ts   # Pipeline builder
+│   │   │   ├── agentRAG.ts        # Knowledge grounding
+│   │   │   └── selfHealing.ts     # Auto-recovery
+│   │   ├── components/            # Svelte UI components
+│   │   ├── sse/                  # SSE broadcaster
+│   │   ├── a3m.ts                 # A3M router integration
+│   │   ├── db.ts                  # Database layer
+│   │   └── embedding.ts           # Embedding service
 │   ├── routes/
-│   │   ├── api/              # API endpoints
-│   │   └── [page].svelte     # UI pages
+│   │   ├── api/                   # API endpoints
+│   │   └── [page].svelte          # UI pages
 │   └── server/
-│       ├── db/                # Database schema
-│       └── a3m/               # A3M config
+│       ├── agents/
+│       │   └── agentRunner.ts     # Main agent loop (integrates all features)
+│       ├── db/                    # Database schema
+│       ├── features/              # Feature implementations
+│       └── ...
 └── tests/
-    └── __tests__/             # Integration tests
+    └── __tests__/                 # Integration tests
 ```
 
 ## 🧪 Testing
@@ -172,7 +254,6 @@ Total: 56 tests passing
 | Endpoint | Description |
 |----------|-------------|
 | `GET /api/verification` | List verification requests |
-| `POST /api/verification` | Create verification request |
 | `POST /api/verification/[id]/approve` | Approve request |
 | `POST /api/verification/[id]/reject` | Reject request |
 | `GET /api/agent-health` | Get all agent health status |
@@ -188,7 +269,7 @@ Total: 56 tests passing
 
 | Route | Description |
 |-------|-------------|
-| `/` | Home |
+| `/` | Home / Mission Control |
 | `/features` | Features dashboard |
 | `/verification` | Verification dashboard |
 | `/health` | Agent health monitor |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quay-ai-factory",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Quay — Autonomous AI Software Factory. Self-hosted AI agents, MCP integration, customizable pipelines, real-time Mission Control dashboard, cost transparency, and full audit trails.",
   "keywords": [
     "ai-software-factory",

package/src/lib/dialog.ts

@@ -0,0 +1,388 @@
+// ============================================================
+// Multi-Round Dialog Optimizer
+// Tracks conversation context over multiple turns and optimizes
+// routing decisions based on accumulated dialogue history.
+//
+// Based on A3M/TMLPD multi-round dialog module
+// ============================================================
+
+export interface DialogTurn {
+  turn: number;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  model?: string;
+  routingDecision?: RoutingDecision;
+  timestamp: number;
+}
+
+export interface DialogState {
+  conversationId: string;
+  turns: DialogTurn[];
+  topics: Set<string>;
+  topicHistory: Map<string, number>;
+  modelPerformance: Map<string, ModelStats>;
+  currentTopic: string;
+  sentiment: 'positive' | 'negative' | 'neutral';
+  complexity: number;
+  startedAt: number;
+  lastTurnAt: number;
+}
+
+export interface ModelStats {
+  totalTurns: number;
+  successfulTurns: number;
+  avgLatency: number;
+  avgConfidence: number;
+  topicAffinity: Map<string, number>; // topic -> success rate
+}
+
+export interface RoutingDecision {
+  selectedModel: string;
+  reasoning: string;
+  predictedQuality: number;
+  estimatedCost: number;
+}
+
+export interface DialogConfig {
+  maxContextTurns?: number;     // Default 20
+  topicThreshold?: number;       // Default 0.7
+  performanceWindow?: number;    // Default 10
+  trackComplexity?: boolean;     // Default true
+}
+
+const DEFAULT_CONFIG: Required<DialogConfig> = {
+  maxContextTurns: 20,
+  topicThreshold: 0.7,
+  performanceWindow: 10,
+  trackComplexity: true,
+};
+
+// ============================================================
+// Topic Keywords for classification
+// ============================================================
+
+const TOPIC_KEYWORDS: Record<string, string[]> = {
+  'coding': ['code', 'function', 'class', 'api', 'debug', 'error', 'bug', 'implement', 'refactor'],
+  'data': ['data', 'database', 'sql', 'query', 'analytics', 'table', 'schema', 'migration'],
+  'web': ['html', 'css', 'javascript', 'frontend', 'backend', 'http', 'api', 'rest', 'graphql'],
+  'ml': ['machine learning', 'model', 'training', 'inference', 'neural', 'ai', 'deep learning', 'classifier'],
+  'devops': ['deploy', 'docker', 'kubernetes', 'ci/cd', 'pipeline', 'infrastructure', 'cloud'],
+  'security': ['auth', 'security', 'encryption', 'jwt', 'oauth', 'permission', 'vulnerability'],
+  'general': [], // Default
+};
+
+// ============================================================
+// Multi-Round Dialog Optimizer
+// ============================================================
+
+export class MultiRoundDialogOptimizer {
+  private dialogStates: Map<string, DialogState> = new Map();
+  private config: Required<DialogConfig>;
+
+  constructor(config: DialogConfig = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Get or create dialog state
+   */
+  getDialogState(conversationId: string): DialogState {
+    if (!this.dialogStates.has(conversationId)) {
+      this.dialogStates.set(conversationId, this.createNewState(conversationId));
+    }
+    return this.dialogStates.get(conversationId)!;
+  }
+
+  /**
+   * Create new dialog state
+   */
+  private createNewState(conversationId: string): DialogState {
+    return {
+      conversationId,
+      turns: [],
+      topics: new Set(['general']),
+      topicHistory: new Map([['general', 1]]),
+      modelPerformance: new Map(),
+      currentTopic: 'general',
+      sentiment: 'neutral',
+      complexity: 0,
+      startedAt: Date.now(),
+      lastTurnAt: Date.now(),
+    };
+  }
+
+  /**
+   * Add a turn to the conversation
+   */
+  addTurn(
+    conversationId: string,
+    role: 'user' | 'assistant' | 'system',
+    content: string,
+    model?: string,
+    routingDecision?: RoutingDecision
+  ): DialogState {
+    const state = this.getDialogState(conversationId);
+    
+    const turn: DialogTurn = {
+      turn: state.turns.length,
+      role,
+      content,
+      model,
+      routingDecision,
+      timestamp: Date.now(),
+    };
+    
+    state.turns.push(turn);
+    state.lastTurnAt = Date.now();
+
+    // Update topic tracking
+    const topics = this.extractTopics(content);
+    for (const topic of topics) {
+      state.topics.add(topic);
+      const count = state.topicHistory.get(topic) || 0;
+      state.topicHistory.set(topic, count + 1);
+    }
+    state.currentTopic = this.getMostFrequentTopic(state.topicHistory);
+
+    // Update complexity
+    if (this.config.trackComplexity) {
+      state.complexity = this.calculateComplexity(content, state.turns);
+    }
+
+    // Update model performance
+    if (role === 'assistant' && model && routingDecision) {
+      this.updateModelPerformance(state, model, content, routingDecision);
+    }
+
+    // Trim old turns
+    if (state.turns.length > this.config.maxContextTurns) {
+      state.turns = state.turns.slice(-this.config.maxContextTurns);
+    }
+
+    return state;
+  }
+
+  /**
+   * Extract topics from content
+   */
+  extractTopics(content: string): string[] {
+    const topics: string[] = [];
+    const lower = content.toLowerCase();
+
+    for (const [topic, keywords] of Object.entries(TOPIC_KEYWORDS)) {
+      if (topic === 'general') continue;
+      const matches = keywords.filter(kw => lower.includes(kw)).length;
+      if (matches > 0) {
+        topics.push(topic);
+      }
+    }
+
+    return topics.length > 0 ? topics : ['general'];
+  }
+
+  /**
+   * Get most frequent topic
+   */
+  private getMostFrequentTopic(topicHistory: Map<string, number>): string {
+    let maxCount = 0;
+    let maxTopic = 'general';
+    
+    for (const [topic, count] of topicHistory) {
+      if (count > maxCount) {
+        maxCount = count;
+        maxTopic = topic;
+      }
+    }
+    
+    return maxTopic;
+  }
+
+  /**
+   * Calculate complexity score (0-1)
+   */
+  calculateComplexity(content: string, turns: DialogTurn[]): number {
+    const words = content.split(/\s+/).length;
+    
+    // Base complexity from length
+    let complexity = Math.min(1, words / 500);
+    
+    // Indicators of complexity
+    const complexIndicators = ['however', 'therefore', 'consequently', 'specifically', 'although'];
+    const simpleIndicators = ['yes', 'no', 'okay', 'sure', 'thanks'];
+    
+    const lower = content.toLowerCase();
+    for (const ind of complexIndicators) {
+      if (lower.includes(ind)) complexity += 0.1;
+    }
+    for (const ind of simpleIndicators) {
+      if (lower.includes(ind)) complexity -= 0.1;
+    }
+    
+    // Turn count adds context complexity
+    if (turns.length > 5) complexity += 0.1;
+    if (turns.length > 10) complexity += 0.1;
+    
+    return Math.max(0, Math.min(1, complexity));
+  }
+
+  /**
+   * Update model performance metrics
+   */
+  private updateModelPerformance(
+    state: DialogState,
+    model: string,
+    content: string,
+    routingDecision: RoutingDecision
+  ): void {
+    if (!state.modelPerformance.has(model)) {
+      state.modelPerformance.set(model, {
+        totalTurns: 0,
+        successfulTurns: 0,
+        avgLatency: 0,
+        avgConfidence: 0,
+        topicAffinity: new Map(),
+      });
+    }
+
+    const stats = state.modelPerformance.get(model)!;
+    stats.totalTurns++;
+
+    // Estimate success by response length and confidence
+    const isSuccessful = content.split(/\s+/).length > 10 && routingDecision.predictedQuality > 0.7;
+    if (isSuccessful) stats.successfulTurns++;
+
+    // Update latency (EMA)
+    const latency = routingDecision.estimatedCost > 0 ? 1000 / routingDecision.estimatedCost : 500;
+    stats.avgLatency = 0.9 * stats.avgLatency + 0.1 * latency;
+
+    // Update confidence (EMA)
+    stats.avgConfidence = 0.9 * stats.avgConfidence + 0.1 * routingDecision.predictedQuality;
+
+    // Update topic affinity
+    const topics = this.extractTopics(content);
+    for (const topic of topics) {
+      const current = stats.topicAffinity.get(topic) || 0.5;
+      stats.topicAffinity.set(topic, 0.9 * current + 0.1 * (isSuccessful ? 1 : 0));
+    }
+  }
+
+  /**
+   * Recommend best model for current conversation
+   */
+  recommendModel(state: DialogState): { model: string; reasoning: string } {
+    const models = Array.from(state.modelPerformance.keys());
+    
+    if (models.length === 0) {
+      return { model: 'openai/gpt-4o-mini', reasoning: 'No history - default to balanced model' };
+    }
+
+    if (models.length === 1) {
+      return { model: models[0], reasoning: 'Only one model used in this conversation' };
+    }
+
+    // Score each model for current topic
+    const scores: Map<string, number> = new Map();
+    
+    for (const model of models) {
+      const stats = state.modelPerformance.get(model)!;
+      
+      // Topic affinity for current topic
+      const topicScore = stats.topicAffinity.get(state.currentTopic) || 0.5;
+      
+      // Success rate
+      const successRate = stats.successfulTurns / Math.max(1, stats.totalTurns);
+      
+      // Confidence score
+      const confidenceScore = stats.avgConfidence;
+      
+      // Combined score
+      const combinedScore = topicScore * 0.4 + successRate * 0.3 + confidenceScore * 0.3;
+      scores.set(model, combinedScore);
+    }
+
+    // Find best
+    let bestModel = models[0];
+    let bestScore = scores.get(models[0])!;
+
+    for (const [model, score] of scores) {
+      if (score > bestScore) {
+        bestScore = score;
+        bestModel = model;
+      }
+    }
+
+    return {
+      model: bestModel,
+      reasoning: `Best for ${state.currentTopic} (score: ${bestScore.toFixed(2)})`,
+    };
+  }
+
+  /**
+   * Get routing hint for next turn
+   */
+  getRoutingHint(conversationId: string): {
+    suggestedModel?: string;
+    topic: string;
+    complexity: number;
+    turnCount: number;
+  } {
+    const state = this.getDialogState(conversationId);
+    const recommendation = this.recommendModel(state);
+
+    return {
+      suggestedModel: recommendation.model,
+      topic: state.currentTopic,
+      complexity: state.complexity,
+      turnCount: state.turns.length,
+    };
+  }
+
+  /**
+   * Build enhanced context with history
+   */
+  buildEnhancedContext(conversationId: string, maxTurns?: number): string {
+    const state = this.getDialogState(conversationId);
+    const turnsToInclude = maxTurns 
+      ? state.turns.slice(-maxTurns) 
+      : state.turns.slice(-this.config.maxContextTurns);
+
+    const parts: string[] = [];
+    
+    // Add topic context
+    parts.push(`[Conversation on: ${state.currentTopic}]`);
+    
+    // Add turns
+    for (const turn of turnsToInclude) {
+      const role = turn.role === 'user' ? 'User' : turn.model || 'Assistant';
+      const truncated = turn.content.slice(0, 500);
+      parts.push(`${role}: ${truncated}`);
+    }
+
+    // Add complexity hint
+    if (state.complexity > 0.7) {
+      parts.push('[Complex conversation - consider using higher quality model]');
+    }
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Reset conversation state
+   */
+  resetConversation(conversationId: string): void {
+    this.dialogStates.delete(conversationId);
+  }
+
+  /**
+   * Get all active conversations
+   */
+  getActiveConversations(): string[] {
+    return Array.from(this.dialogStates.keys());
+  }
+}
+
+// ============================================================
+// Convenience export
+// ============================================================
+
+export const dialogOptimizer = new MultiRoundDialogOptimizer();