@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/agent-patterns.md

@@ -0,0 +1,387 @@
+---
+name: agent-patterns
+description: AI agent patterns for tool use, multi-step reasoning, memory management, planning, guardrails, and evaluation.
+---
+
+# AI Agent Patterns
+
+## When to Use
+Build AI agents when tasks require multi-step reasoning, tool use, and dynamic decision-making that cannot be achieved with a single prompt. Agents are appropriate for research tasks, code generation with verification, data analysis pipelines, and customer support automation. Use these patterns to structure tool definitions, implement planning loops, manage conversation memory, and apply safety guardrails. Start simple and add complexity only when needed.
+
+## How It Works
+
+### Tool Definition Pattern
+
+```typescript
+// src/agent/tools.ts
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    description: string;
+    required?: boolean;
+    enum?: string[];
+  }>;
+  execute: (params: Record<string, unknown>) => Promise<ToolResult>;
+}
+
+export interface ToolResult {
+  output: string;
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+const tools: ToolDefinition[] = [
+  {
+    name: 'search_web',
+    description: 'Search the web for current information. Use when the user asks about recent events or needs data not in your training.',
+    parameters: {
+      query: { type: 'string', description: 'Search query', required: true },
+      maxResults: { type: 'number', description: 'Maximum results (1-10)', required: false },
+    },
+    execute: async ({ query, maxResults }) => {
+      const results = await searchAPI(query as string, (maxResults as number) ?? 5);
+      return { output: results.map((r: any) => `[${r.title}](${r.url}): ${r.snippet}`).join('\n') };
+    },
+  },
+  {
+    name: 'run_code',
+    description: 'Execute Python code in a sandboxed environment. Returns stdout and stderr.',
+    parameters: {
+      code: { type: 'string', description: 'Python code to execute', required: true },
+      timeout: { type: 'number', description: 'Timeout in seconds (max 30)', required: false },
+    },
+    execute: async ({ code, timeout }) => {
+      const result = await sandbox.execute(code as string, { timeout: Math.min((timeout as number) ?? 10, 30) });
+      return {
+        output: result.stdout || '(no output)',
+        error: result.stderr || undefined,
+        metadata: { exitCode: result.exitCode, executionTime: result.durationMs },
+      };
+    },
+  },
+  {
+    name: 'read_file',
+    description: 'Read the contents of a file. Use to examine code, configuration, or data files.',
+    parameters: {
+      path: { type: 'string', description: 'File path relative to workspace root', required: true },
+    },
+    execute: async ({ path: filePath }) => {
+      const content = await fs.readFile(filePath as string, 'utf-8');
+      return { output: content, metadata: { lines: content.split('\n').length } };
+    },
+  },
+];
+```
+
+### ReAct Loop (Reason + Act)
+
+```typescript
+// src/agent/react-loop.ts
+import Anthropic from '@anthropic-ai/sdk';
+
+interface AgentState {
+  messages: Anthropic.MessageParam[];
+  toolResults: Map<string, ToolResult>;
+  stepCount: number;
+  maxSteps: number;
+}
+
+export async function runAgent(
+  client: Anthropic,
+  userMessage: string,
+  tools: ToolDefinition[],
+  maxSteps: number = 10
+): Promise<string> {
+  const state: AgentState = {
+    messages: [{ role: 'user', content: userMessage }],
+    toolResults: new Map(),
+    stepCount: 0,
+    maxSteps,
+  };
+
+  const anthropicTools: Anthropic.Tool[] = tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    input_schema: {
+      type: 'object' as const,
+      properties: Object.fromEntries(
+        Object.entries(t.parameters).map(([k, v]) => [k, { type: v.type, description: v.description }])
+      ),
+      required: Object.entries(t.parameters).filter(([, v]) => v.required).map(([k]) => k),
+    },
+  }));
+
+  while (state.stepCount < state.maxSteps) {
+    state.stepCount++;
+
+    const response = await client.messages.create({
+      model: 'claude-sonnet-4-20250514',
+      max_tokens: 4096,
+      system: AGENT_SYSTEM_PROMPT,
+      tools: anthropicTools,
+      messages: state.messages,
+    });
+
+    // Check if the model wants to use tools
+    if (response.stop_reason === 'tool_use') {
+      state.messages.push({ role: 'assistant', content: response.content });
+
+      const toolUseBlocks = response.content.filter(
+        (block): block is Anthropic.ToolUseBlock => block.type === 'tool_use'
+      );
+
+      const toolResults: Anthropic.ToolResultBlockParam[] = [];
+
+      for (const toolUse of toolUseBlocks) {
+        const tool = tools.find((t) => t.name === toolUse.name);
+        if (!tool) {
+          toolResults.push({
+            type: 'tool_result',
+            tool_use_id: toolUse.id,
+            content: `Error: Unknown tool "${toolUse.name}"`,
+            is_error: true,
+          });
+          continue;
+        }
+
+        try {
+          const result = await tool.execute(toolUse.input as Record<string, unknown>);
+          toolResults.push({
+            type: 'tool_result',
+            tool_use_id: toolUse.id,
+            content: result.error ? `Error: ${result.error}\n\nOutput: ${result.output}` : result.output,
+            is_error: !!result.error,
+          });
+        } catch (err) {
+          toolResults.push({
+            type: 'tool_result',
+            tool_use_id: toolUse.id,
+            content: `Execution error: ${(err as Error).message}`,
+            is_error: true,
+          });
+        }
+      }
+
+      state.messages.push({ role: 'user', content: toolResults });
+      continue;
+    }
+
+    // Model is done — extract final text response
+    const textBlocks = response.content.filter(
+      (block): block is Anthropic.TextBlock => block.type === 'text'
+    );
+    return textBlocks.map((b) => b.text).join('\n');
+  }
+
+  return 'Agent reached maximum step limit without completing the task.';
+}
+```
+
+### Memory Management
+
+```typescript
+// src/agent/memory.ts
+interface MemoryEntry {
+  id: string;
+  content: string;
+  timestamp: Date;
+  importance: number;  // 0-1
+  type: 'fact' | 'preference' | 'task_result' | 'error';
+}
+
+export class AgentMemory {
+  private shortTerm: Anthropic.MessageParam[] = [];
+  private longTerm: MemoryEntry[] = [];
+  private maxShortTermMessages = 20;
+  private maxLongTermEntries = 100;
+
+  addMessage(message: Anthropic.MessageParam) {
+    this.shortTerm.push(message);
+
+    // Trim old messages when exceeding limit
+    if (this.shortTerm.length > this.maxShortTermMessages) {
+      const removed = this.shortTerm.splice(1, 2); // keep system, remove oldest
+      this.summarizeToLongTerm(removed);
+    }
+  }
+
+  addFact(content: string, importance: number = 0.5) {
+    this.longTerm.push({
+      id: crypto.randomUUID(),
+      content,
+      timestamp: new Date(),
+      importance,
+      type: 'fact',
+    });
+
+    // Evict low-importance entries when full
+    if (this.longTerm.length > this.maxLongTermEntries) {
+      this.longTerm.sort((a, b) => b.importance - a.importance);
+      this.longTerm = this.longTerm.slice(0, this.maxLongTermEntries);
+    }
+  }
+
+  getContext(): string {
+    if (this.longTerm.length === 0) return '';
+
+    const relevant = this.longTerm
+      .sort((a, b) => b.importance - a.importance)
+      .slice(0, 10);
+
+    return `## Relevant Memory\n${relevant.map((e) => `- [${e.type}] ${e.content}`).join('\n')}`;
+  }
+
+  getMessages(): Anthropic.MessageParam[] {
+    return [...this.shortTerm];
+  }
+
+  private summarizeToLongTerm(messages: Anthropic.MessageParam[]) {
+    // Extract key facts from removed messages
+    for (const msg of messages) {
+      const content = typeof msg.content === 'string' ? msg.content : '';
+      if (content.length > 50) {
+        this.addFact(content.slice(0, 200), 0.3);
+      }
+    }
+  }
+}
+```
+
+### Planning Pattern
+
+```typescript
+// src/agent/planner.ts
+interface Plan {
+  goal: string;
+  steps: PlanStep[];
+  currentStep: number;
+  status: 'planning' | 'executing' | 'completed' | 'failed';
+}
+
+interface PlanStep {
+  description: string;
+  tool?: string;
+  params?: Record<string, unknown>;
+  status: 'pending' | 'running' | 'done' | 'failed';
+  result?: string;
+}
+
+export async function createPlan(client: Anthropic, goal: string, availableTools: string[]): Promise<Plan> {
+  const response = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 2048,
+    messages: [{
+      role: 'user',
+      content: `Create a step-by-step plan to accomplish this goal. Available tools: ${availableTools.join(', ')}
+
+Goal: ${goal}
+
+Respond with a JSON array of steps: [{"description": "...", "tool": "tool_name_or_null"}]`,
+    }],
+  });
+
+  const text = (response.content[0] as Anthropic.TextBlock).text;
+  const stepsJson = JSON.parse(text.match(/\[[\s\S]*\]/)?.[0] ?? '[]');
+
+  return {
+    goal,
+    steps: stepsJson.map((s: any) => ({ ...s, status: 'pending' as const })),
+    currentStep: 0,
+    status: 'executing',
+  };
+}
+
+export async function executePlan(plan: Plan, agent: typeof runAgent): Promise<Plan> {
+  for (let i = plan.currentStep; i < plan.steps.length; i++) {
+    const step = plan.steps[i];
+    step.status = 'running';
+    plan.currentStep = i;
+
+    try {
+      const result = await agent(
+        `Execute this step: ${step.description}\n\nContext from previous steps:\n${
+          plan.steps.slice(0, i).filter((s) => s.result).map((s) => `- ${s.description}: ${s.result}`).join('\n')
+        }`
+      );
+      step.result = result;
+      step.status = 'done';
+    } catch (err) {
+      step.status = 'failed';
+      step.result = (err as Error).message;
+      plan.status = 'failed';
+      return plan;
+    }
+  }
+
+  plan.status = 'completed';
+  return plan;
+}
+```
+
+### Guardrails
+
+```typescript
+// src/agent/guardrails.ts
+interface GuardrailCheck {
+  name: string;
+  check: (input: string) => { safe: boolean; reason?: string };
+}
+
+const guardrails: GuardrailCheck[] = [
+  {
+    name: 'no-secrets',
+    check: (input) => {
+      const patterns = [/password\s*[:=]\s*\S+/i, /api[_-]?key\s*[:=]\s*\S+/i, /-----BEGIN.*KEY-----/];
+      const match = patterns.find((p) => p.test(input));
+      return match ? { safe: false, reason: 'Output contains potential secrets' } : { safe: true };
+    },
+  },
+  {
+    name: 'no-dangerous-commands',
+    check: (input) => {
+      const dangerous = ['rm -rf /', 'DROP TABLE', 'FORMAT C:', 'sudo rm', ':(){:|:&};:'];
+      const found = dangerous.find((cmd) => input.includes(cmd));
+      return found ? { safe: false, reason: `Dangerous command detected: ${found}` } : { safe: true };
+    },
+  },
+  {
+    name: 'output-length',
+    check: (input) => {
+      return input.length > 50_000
+        ? { safe: false, reason: 'Output exceeds maximum length' }
+        : { safe: true };
+    },
+  },
+];
+
+export function applyGuardrails(output: string): { safe: boolean; violations: string[] } {
+  const violations: string[] = [];
+  for (const guardrail of guardrails) {
+    const result = guardrail.check(output);
+    if (!result.safe) violations.push(`${guardrail.name}: ${result.reason}`);
+  }
+  return { safe: violations.length === 0, violations };
+}
+```
+
+## Examples
+
+| Pattern | When to Use | Complexity |
+|---------|-------------|------------|
+| Single tool call | FAQ lookup, calculations | Low |
+| ReAct loop | Research, multi-step tasks | Medium |
+| Plan-then-execute | Complex workflows with dependencies | High |
+| Memory + planning | Long-running sessions, personalization | High |
+| Multi-agent | Specialized subtasks (research + code + review) | Very high |
+
+## Checklist
+- [ ] Tools have clear descriptions explaining when and why to use them
+- [ ] ReAct loop has a maximum step limit to prevent infinite loops
+- [ ] Tool execution errors caught and returned as structured results
+- [ ] Memory manager trims conversation history to stay within context window
+- [ ] Long-term memory stores key facts with importance scoring
+- [ ] Guardrails check for secrets, dangerous commands, and output length
+- [ ] Agent evaluation suite measures task completion rate and quality
+- [ ] Planning step validates feasibility before execution begins

package/assets/skills/ai-integration.md

@@ -0,0 +1,263 @@
+---
+name: ai-integration
+description: AI/LLM integration patterns for streaming, function calling, token management, fallbacks, and prompt caching.
+---
+
+# AI Integration
+
+## When to Use
+Apply these patterns when integrating LLM APIs into production applications. Use streaming for real-time UX, function calling for structured outputs, token management to control costs, fallbacks for reliability, and prompt caching to reduce latency and spend on repeated context.
+
+## How It Works
+
+### Streaming Responses
+
+Stream tokens as they arrive to improve perceived latency:
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic();
+
+async function streamChat(userMessage: string): Promise<string> {
+  const chunks: string[] = [];
+
+  const stream = client.messages.stream({
+    model: "claude-sonnet-4-20250514",
+    max_tokens: 1024,
+    messages: [{ role: "user", content: userMessage }],
+  });
+
+  for await (const event of stream) {
+    if (
+      event.type === "content_block_delta" &&
+      event.delta.type === "text_delta"
+    ) {
+      chunks.push(event.delta.text);
+      process.stdout.write(event.delta.text);
+    }
+  }
+  return chunks.join("");
+}
+```
+
+Server-Sent Events endpoint for web clients:
+
+```typescript
+app.post("/api/chat", async (req, res) => {
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+
+  const stream = client.messages.stream({
+    model: "claude-sonnet-4-20250514",
+    max_tokens: 1024,
+    messages: req.body.messages,
+  });
+
+  for await (const event of stream) {
+    if (
+      event.type === "content_block_delta" &&
+      event.delta.type === "text_delta"
+    ) {
+      res.write(`data: ${JSON.stringify({ text: event.delta.text })}\n\n`);
+    }
+  }
+  res.write("data: [DONE]\n\n");
+  res.end();
+});
+```
+
+### Function Calling with Structured Output
+
+Define tools so the model returns structured JSON you can dispatch:
+
+```typescript
+import OpenAI from "openai";
+
+const openai = new OpenAI();
+
+const tools: OpenAI.ChatCompletionTool[] = [
+  {
+    type: "function",
+    function: {
+      name: "get_weather",
+      description: "Get current weather for a location",
+      parameters: {
+        type: "object",
+        properties: {
+          location: { type: "string", description: "City name" },
+          units: { type: "string", enum: ["celsius", "fahrenheit"] },
+        },
+        required: ["location"],
+      },
+    },
+  },
+];
+
+const response = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Weather in Paris?" }],
+  tools,
+  tool_choice: "auto",
+});
+
+const toolCall = response.choices[0].message.tool_calls?.[0];
+if (toolCall) {
+  const args = JSON.parse(toolCall.function.arguments);
+  const result = await getWeather(args.location, args.units);
+  // Send tool result back for the model to summarize
+}
+```
+
+### Token Management
+
+Count tokens before sending to avoid exceeding limits:
+
+```typescript
+import { encoding_for_model } from "tiktoken";
+
+function countTokens(text: string, model = "gpt-4o"): number {
+  const enc = encoding_for_model(model as Parameters<typeof encoding_for_model>[0]);
+  const tokens = enc.encode(text);
+  enc.free();
+  return tokens.length;
+}
+
+interface Message {
+  role: string;
+  content: string;
+}
+
+function truncateToFit(messages: Message[], maxTokens: number): Message[] {
+  let total = 0;
+  const kept: Message[] = [];
+  const system = messages.find((m) => m.role === "system");
+  if (system) {
+    total += countTokens(system.content);
+    kept.push(system);
+  }
+  for (const msg of [...messages].reverse()) {
+    if (msg.role === "system") continue;
+    const cost = countTokens(msg.content);
+    if (total + cost > maxTokens) break;
+    total += cost;
+    kept.unshift(msg);
+  }
+  return kept;
+}
+```
+
+### Provider Fallback Chain
+
+Retry across providers when one fails:
+
+```typescript
+interface LLMProvider {
+  name: string;
+  call: (messages: Message[]) => Promise<string>;
+}
+
+async function callWithFallback(
+  providers: LLMProvider[],
+  messages: Message[],
+  maxRetries = 2
+): Promise<string> {
+  for (const provider of providers) {
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        return await provider.call(messages);
+      } catch (err: any) {
+        const isRateLimit = err.status === 429;
+        if (isRateLimit && attempt < maxRetries - 1) {
+          await new Promise((r) => setTimeout(r, Math.pow(2, attempt) * 1000));
+          continue;
+        }
+        console.warn(`${provider.name} attempt ${attempt + 1} failed:`, err.message);
+        break;
+      }
+    }
+  }
+  throw new Error("All LLM providers exhausted");
+}
+```
+
+### Prompt Caching with Anthropic
+
+Use cache_control to avoid re-processing large system prompts:
+
+```typescript
+const anthropic = new Anthropic();
+
+const response = await anthropic.messages.create({
+  model: "claude-sonnet-4-20250514",
+  max_tokens: 1024,
+  system: [
+    {
+      type: "text",
+      text: largeSystemPrompt, // 10k+ tokens of instructions
+      cache_control: { type: "ephemeral" },
+    },
+  ],
+  messages: [{ role: "user", content: "Summarize the key points." }],
+});
+// cache_read_input_tokens shows tokens served from cache on subsequent calls
+console.log("Cache hit tokens:", response.usage.cache_read_input_tokens);
+```
+
+### Cost Tracking and Rate Limiting
+
+```typescript
+interface UsageRecord {
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  costUsd: number;
+  userId: string;
+  timestamp: Date;
+}
+
+const COST_PER_1K: Record<string, { input: number; output: number }> = {
+  "claude-sonnet-4-20250514": { input: 0.003, output: 0.015 },
+  "gpt-4o": { input: 0.0025, output: 0.01 },
+  "gpt-4o-mini": { input: 0.00015, output: 0.0006 },
+};
+
+function trackUsage(
+  model: string,
+  inputTokens: number,
+  outputTokens: number,
+  userId: string
+): UsageRecord {
+  const rates = COST_PER_1K[model] ?? { input: 0, output: 0 };
+  return {
+    model,
+    inputTokens,
+    outputTokens,
+    costUsd: (inputTokens * rates.input + outputTokens * rates.output) / 1000,
+    userId,
+    timestamp: new Date(),
+  };
+}
+```
+
+## Examples
+
+| Pattern | When | Result |
+|---------|------|--------|
+| Streaming SSE | Chat UI, CLI output | First token in < 300ms, progressive display |
+| Function calling | Data extraction, tool use | Structured JSON, no regex parsing needed |
+| Token truncation | Long conversations | Stays within context window, drops oldest first |
+| Provider fallback | Production reliability | 99.9% uptime across Anthropic + OpenAI |
+| Prompt caching | Repeated system prompts | 90% cost reduction on cached prefix tokens |
+| Cost tracking | Budget control | Per-user cost visibility, alerts at thresholds |
+
+## Checklist
+- [ ] Streaming enabled for all user-facing chat responses
+- [ ] Function calling schemas validated with Zod or JSON Schema
+- [ ] Token counting runs before every API call to prevent context overflow
+- [ ] Fallback chain configured with at least two providers
+- [ ] Prompt caching enabled for system prompts over 1024 tokens
+- [ ] Rate limiter in place for all LLM API calls
+- [ ] Error handling covers 429, 500, 503, and timeout scenarios
+- [ ] Usage metrics logged per request (tokens in, tokens out, latency, cost)