aidevops 2.52.1

package/.agent/tools/context/dspyground.md

@@ -0,0 +1,374 @@
+---
+description: DSPyGround visual prompt optimization playground
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+  task: true
+---
+
+# DSPyGround Integration Guide
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- DSPyGround: Visual prompt optimization playground with GEPA optimizer
+- Requires: Node.js 18+, AI Gateway API key
+- Helper: `./.agent/scripts/dspyground-helper.sh install|init|dev [project]`
+- Config: `configs/dspyground-config.json`, project: `dspyground.config.ts`
+- Projects: `data/dspyground/[project-name]/`
+- Web UI: `http://localhost:3000` (run with `dspyground dev`)
+- Features: Real-time optimization, voice feedback, structured output with Zod
+- Metrics: accuracy, tone, efficiency, tool_accuracy, guardrails (customizable)
+- Workflow: Chat + Sample -> Organize -> Optimize -> Export prompt
+- API keys: `AI_GATEWAY_API_KEY` required, `OPENAI_API_KEY` optional for voice
+<!-- AI-CONTEXT-END -->
+
+## Overview
+
+DSPyGround is a visual prompt optimization playground powered by the GEPA (Genetic-Pareto Evolutionary Algorithm) optimizer. It provides an intuitive web interface for iterative prompt optimization with real-time feedback and multi-dimensional metrics.
+
+## 🚀 **Quick Start**
+
+### **Prerequisites**
+
+- Node.js 18+ installed
+- npm package manager
+- AI Gateway API key
+- OpenAI API key (optional, for voice feedback)
+
+### **Installation**
+
+```bash
+# Install DSPyGround globally
+./.agent/scripts/dspyground-helper.sh install
+
+# Verify installation
+dspyground --version
+```
+
+### **Configuration**
+
+1. **Copy configuration template:**
+
+   ```bash
+   cp configs/dspyground-config.json.txt configs/dspyground-config.json
+   ```
+
+2. **Edit configuration:**
+
+   ```bash
+   # Customize settings for your use case
+   nano configs/dspyground-config.json
+   ```
+
+## 📁 **Project Structure**
+
+```text
+aidevops/
+├── .agent/scripts/dspyground-helper.sh    # DSPyGround management script
+├── configs/dspyground-config.json    # DSPyGround configuration
+├── data/dspyground/                  # DSPyGround projects
+│   └── my-agent/
+│       ├── dspyground.config.ts      # Project configuration
+│       ├── .env                      # Environment variables
+│       └── .dspyground/              # Local data storage
+└── package.json                      # Node.js dependencies
+```
+
+## 🛠️ **Usage**
+
+### **Initialize New Project**
+
+```bash
+# Create a new DSPyGround project
+./.agent/scripts/dspyground-helper.sh init my-agent
+
+# Navigate to project directory
+cd data/dspyground/my-agent
+```
+
+### **Start Development Server**
+
+```bash
+# Start the development server
+./.agent/scripts/dspyground-helper.sh dev my-agent
+
+# Or from project directory
+dspyground dev
+```
+
+The playground will open at `http://localhost:3000`
+
+### **Basic Configuration**
+
+Create `dspyground.config.ts`:
+
+```typescript
+import { tool } from 'ai'
+import { z } from 'zod'
+
+export default {
+  // System prompt for your agent
+  systemPrompt: `You are a helpful DevOps assistant specialized in infrastructure management.
+
+  You help users with:
+  - Server configuration and deployment
+  - CI/CD pipeline optimization
+  - Infrastructure monitoring
+  - Security best practices
+
+  Always provide practical, actionable advice.`,
+
+  // AI SDK tools (optional)
+  tools: {
+    checkServerStatus: tool({
+      description: 'Check the status of a server',
+      parameters: z.object({
+        serverId: z.string().describe('The server ID to check'),
+      }),
+      execute: async ({ serverId }) => {
+        // Implementation would connect to actual server
+        return `Server ${serverId} is running normally`;
+      },
+    }),
+  },
+
+  // Optional: Structured output schema
+  schema: z.object({
+    response: z.string(),
+    confidence: z.number().min(0).max(1),
+    category: z.enum(['deployment', 'monitoring', 'security', 'general'])
+  }),
+
+  // Optimization preferences
+  preferences: {
+    selectedModel: 'openai/gpt-4o-mini',
+    optimizationModel: 'openai/gpt-4o-mini',
+    reflectionModel: 'openai/gpt-4o',
+    batchSize: 3,
+    numRollouts: 10,
+    selectedMetrics: ['accuracy', 'tone'],
+    useStructuredOutput: false,
+  },
+
+  // Metrics configuration
+  metricsPrompt: {
+    evaluation_instructions: 'You are an expert DevOps evaluator...',
+    dimensions: {
+      accuracy: {
+        name: 'Technical Accuracy',
+        description: 'Is the DevOps advice technically correct?',
+        weight: 1.0
+      },
+      tone: {
+        name: 'Professional Tone',
+        description: 'Is the communication professional and clear?',
+        weight: 0.8
+      },
+      efficiency: {
+        name: 'Solution Efficiency',
+        description: 'Does the solution optimize for efficiency?',
+        weight: 0.9
+      }
+    }
+  }
+}
+```
+
+### **Environment Setup**
+
+Create `.env` file:
+
+```bash
+# Required: AI Gateway API key
+AI_GATEWAY_API_KEY=your_ai_gateway_api_key_here
+
+# Optional: For voice feedback feature
+# DSPyGround automatically uses your terminal session's OPENAI_API_KEY
+OPENAI_API_KEY=${OPENAI_API_KEY}  # Uses your existing environment variable
+OPENAI_BASE_URL=https://api.openai.com/v1
+```
+
+**Note**: DSPyGround will automatically use API keys from your terminal session environment. You only need to add `AI_GATEWAY_API_KEY` if you're using AI Gateway instead of direct OpenAI API calls.
+
+## 🎯 **Optimization Workflow**
+
+### **1. Chat and Sample**
+
+- Start conversations with your agent
+- Test different scenarios and use cases
+- Save good responses as positive samples
+- Mark problematic responses as negative samples
+
+### **2. Organize Samples**
+
+- Create sample groups (e.g., "Deployment Tasks", "Security Questions")
+- Categorize samples by use case or complexity
+- Build a comprehensive test suite
+
+### **3. Run Optimization**
+
+- Click "Optimize" to start GEPA optimization
+- Watch real-time progress and metrics
+- Review generated candidate prompts
+- Select the best performing prompt
+
+### **4. Export Results**
+
+- Copy optimized prompt from history
+- Update your `dspyground.config.ts`
+- Deploy to production systems
+
+## 📊 **Metrics and Evaluation**
+
+### **Built-in Metrics**
+
+- **Accuracy**: Factual correctness and relevance
+- **Tone**: Communication style and professionalism
+- **Efficiency**: Resource usage and optimization
+- **Tool Accuracy**: Correct tool selection and usage
+- **Guardrails**: Safety and ethical compliance
+
+### **Custom Metrics**
+
+```typescript
+metricsPrompt: {
+  dimensions: {
+    devops_expertise: {
+      name: 'DevOps Expertise',
+      description: 'Does the response demonstrate deep DevOps knowledge?',
+      weight: 1.0
+    },
+    actionability: {
+      name: 'Actionability',
+      description: 'Can the user immediately act on this advice?',
+      weight: 0.9
+    }
+  }
+}
+```
+
+## 🔧 **Advanced Features**
+
+### **Voice Feedback**
+
+- Press and hold spacebar in feedback dialogs
+- Record voice feedback for samples
+- Automatic transcription and analysis
+
+### **Structured Output**
+
+```typescript
+schema: z.object({
+  task_type: z.enum(['deployment', 'monitoring', 'troubleshooting']),
+  priority: z.enum(['low', 'medium', 'high', 'critical']),
+  steps: z.array(z.string()),
+  estimated_time: z.string(),
+  risks: z.array(z.string())
+})
+```
+
+### **Tool Integration**
+
+```typescript
+tools: {
+  deployApp: tool({
+    description: 'Deploy application to server',
+    parameters: z.object({
+      appName: z.string(),
+      environment: z.enum(['dev', 'staging', 'prod']),
+    }),
+    execute: async ({ appName, environment }) => {
+      // Integration with actual deployment systems
+      return `Deployed ${appName} to ${environment}`;
+    },
+  }),
+}
+```
+
+## 🎨 **UI Features**
+
+### **Chat Interface**
+
+- Real-time streaming responses
+- Structured output visualization
+- Tool call execution display
+- Sample saving with feedback
+
+### **Optimization Dashboard**
+
+- Progress tracking with real-time updates
+- Pareto frontier visualization
+- Metric score evolution
+- Candidate prompt comparison
+
+### **History Management**
+
+- Complete optimization run history
+- Prompt evolution tracking
+- Performance metrics over time
+- Export capabilities
+
+## 🔍 **Troubleshooting**
+
+### **Common Issues**
+
+1. **Server Won't Start**
+
+   ```bash
+   # Check Node.js version
+   node --version  # Should be 18+
+
+   # Check port availability
+   lsof -i :3000
+   ```
+
+2. **API Key Issues**
+
+   ```bash
+   # Verify environment variables
+   cat .env
+
+   # Test API connectivity
+   curl -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
+        https://api.aigateway.com/v1/models
+   ```
+
+3. **Optimization Failures**
+
+   ```typescript
+   // Reduce batch size for stability
+   preferences: {
+     batchSize: 1,
+     numRollouts: 5,
+   }
+   ```
+
+## 📚 **Additional Resources**
+
+- [DSPyGround GitHub Repository](https://github.com/Scale3-Labs/dspyground)
+- [AI Gateway Documentation](https://docs.aigateway.com/)
+- [AI SDK Documentation](https://sdk.vercel.ai/)
+- [GEPA Algorithm Paper](https://arxiv.org/abs/2310.03714)
+
+## 🤝 **Integration with AI DevOps**
+
+DSPyGround complements other AI DevOps Framework components:
+
+- **Server Management**: Optimize prompts for infrastructure tasks
+- **Code Quality**: Create better prompts for code analysis
+- **Documentation**: Generate optimized technical writing prompts
+- **Monitoring**: Develop prompts for alert analysis and response
+
+## 🔗 **Related Documentation**
+
+- [DSPy Integration Guide](./DSPY-INTEGRATION.md) - Core DSPy framework integration
+- [AI DevOps Framework Overview](../README.md) - Main framework documentation
+- [MCP Integrations](./MCP-INTEGRATIONS.md) - Model Context Protocol integrations

package/.agent/tools/context/llm-tldr.md

@@ -0,0 +1,219 @@
+---
+description: TLDR semantic code analysis with 95% token savings
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: false
+  task: true
+---
+
+# llm-tldr - Semantic Code Analysis
+
+TLDR extracts code structure and semantics, saving ~95% tokens compared to raw code.
+
+**Source**: [parcadei/llm-tldr](https://github.com/parcadei/llm-tldr)
+
+## Installation
+
+```bash
+pip install llm-tldr
+```
+
+## MCP Server (OpenCode)
+
+Add to your MCP config:
+
+```json
+{
+  "llm-tldr": {
+    "command": "tldr-mcp",
+    "args": ["--project", "${workspaceFolder}"]
+  }
+}
+```
+
+Or use the template: `configs/mcp-templates/llm-tldr.json`
+
+## CLI Commands
+
+### Tree - File Structure
+
+```bash
+tldr tree /path/to/project
+```
+
+Shows file tree with line counts.
+
+### Structure - Code Skeleton
+
+```bash
+tldr structure /path/to/file.py
+```
+
+Extracts classes, functions, imports without implementation details.
+
+### Context - Full Analysis
+
+```bash
+tldr context /path/to/file.py
+```
+
+Comprehensive analysis including:
+- Imports and dependencies
+- Class/function signatures
+- Docstrings
+- Type hints
+- Call relationships
+
+### CFG - Control Flow Graph
+
+```bash
+tldr cfg /path/to/file.py function_name
+```
+
+Shows control flow for a specific function.
+
+### DFG - Data Flow Graph
+
+```bash
+tldr dfg /path/to/file.py function_name
+```
+
+Shows data dependencies and variable flow.
+
+### Semantic Search
+
+```bash
+tldr search "authentication logic" /path/to/project
+```
+
+Uses bge-large-en-v1.5 embeddings (1024-dim) for semantic code search.
+
+### Impact Analysis
+
+```bash
+tldr impact /path/to/file.py function_name
+```
+
+Shows what would be affected by changing a function.
+
+### Dead Code Detection
+
+```bash
+tldr dead /path/to/project
+```
+
+Finds unused functions and classes.
+
+### Slice - Code Slice
+
+```bash
+tldr slice /path/to/file.py variable_name
+```
+
+Extracts code slice affecting a variable.
+
+## MCP Tools (via tldr-mcp)
+
+When running as MCP server, provides these tools:
+
+| Tool | Purpose |
+|------|---------|
+| `tldr_tree` | Get project file structure |
+| `tldr_structure` | Extract code skeleton |
+| `tldr_context` | Full semantic analysis |
+| `tldr_cfg` | Control flow graph |
+| `tldr_dfg` | Data flow graph |
+| `tldr_search` | Semantic code search |
+| `tldr_impact` | Impact analysis |
+| `tldr_dead` | Dead code detection |
+| `tldr_slice` | Code slicing |
+
+## Token Savings
+
+| Content Type | Raw Tokens | TLDR Tokens | Savings |
+|--------------|------------|-------------|---------|
+| 1000-line file | ~15,000 | ~750 | 95% |
+| Class definition | ~500 | ~50 | 90% |
+| Function body | ~200 | ~20 | 90% |
+
+## Use Cases
+
+### Before Editing Code
+
+```bash
+# Get structure before making changes
+tldr context src/auth/handler.py
+
+# Check what would be affected
+tldr impact src/auth/handler.py validate_token
+```
+
+### Understanding Codebase
+
+```bash
+# Find authentication logic
+tldr search "where do we validate JWT tokens" ./src
+
+# Get project overview
+tldr tree ./src
+```
+
+### Code Review
+
+```bash
+# Check for dead code
+tldr dead ./src
+
+# Understand data flow
+tldr dfg src/payment/processor.py process_payment
+```
+
+## Comparison with Other Tools
+
+| Tool | Purpose | Token Efficiency |
+|------|---------|------------------|
+| llm-tldr | Semantic extraction | 95% savings |
+| osgrep | Semantic search | Good for finding |
+| Augment | Codebase retrieval | Good for context |
+| repomix | Full packing | No savings |
+
+**Recommendation**: Use llm-tldr for understanding code structure, osgrep/Augment for finding code, repomix for full context when needed.
+
+## Integration with Memory System
+
+After using TLDR to understand code:
+
+```bash
+# Remember the pattern you discovered
+~/.aidevops/agents/scripts/memory-helper.sh store "CODEBASE_PATTERN" \
+  "Auth flow: validate_token -> check_permissions -> authorize" \
+  "auth,flow,pattern" "myproject"
+```
+
+## Troubleshooting
+
+### Embedding Model Download
+
+First run downloads bge-large-en-v1.5 (~1.3GB). Be patient.
+
+### Unsupported Language
+
+TLDR supports: Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, Ruby, PHP, C#, Kotlin, Scala, Lua, Elixir.
+
+For other languages, use `tldr tree` and `tldr context` (basic parsing).
+
+### MCP Connection Issues
+
+```bash
+# Test MCP server directly
+tldr-mcp --project /path/to/project
+
+# Check if running
+ps aux | grep tldr-mcp
+```