wicked-garden 12.27.0

package/skills/agentic/context-engineering/refs/caching-and-optimization.md

@@ -0,0 +1,251 @@
+---
+phase_relevance: ["design", "review"]
+archetype_relevance: ["*"]
+---
+# Caching, Batching & Cost Optimization
+
+Advanced strategies for reducing API costs through caching, batching, and intelligent model selection.
+
+## Caching Strategies
+
+### 10. Prompt Prefix Caching
+
+Cache common prompt prefixes.
+
+```python
+class PrefixCache:
+    """
+    Some LLM providers (like Anthropic) cache prompt prefixes automatically.
+    Structure prompts to maximize cache hits.
+    """
+
+    def build_cacheable_prompt(self, static_instructions, dynamic_task):
+        # Put static content first (will be cached)
+        prompt = [
+            {
+                "role": "system",
+                "content": static_instructions,  # This gets cached
+                "cache_control": {"type": "ephemeral"}
+            },
+            {
+                "role": "user",
+                "content": dynamic_task  # This changes each time
+            }
+        ]
+        return prompt
+
+# Usage: Reuse same system prompt across requests
+cache = PrefixCache()
+for task in tasks:
+    prompt = cache.build_cacheable_prompt(
+        static_instructions="You are a helpful assistant...",  # Cached
+        dynamic_task=task  # Not cached
+    )
+```
+
+### 11. Semantic Caching
+
+Cache responses for semantically similar queries.
+
+```python
+class SemanticCache:
+    def __init__(self, similarity_threshold=0.95):
+        self.cache = []  # [(query_embedding, response)]
+        self.threshold = similarity_threshold
+
+    async def get(self, query):
+        query_embedding = await self.embed(query)
+
+        # Check for similar cached query
+        for cached_embedding, cached_response in self.cache:
+            similarity = cosine_similarity([query_embedding], [cached_embedding])[0][0]
+            if similarity >= self.threshold:
+                return cached_response
+
+        return None
+
+    async def set(self, query, response):
+        query_embedding = await self.embed(query)
+        self.cache.append((query_embedding, response))
+
+# Usage
+cache = SemanticCache()
+
+# Try cache first
+cached = await cache.get(user_query)
+if cached:
+    return cached
+
+# If not cached, generate and cache
+response = await llm.generate(user_query)
+await cache.set(user_query, response)
+```
+
+## Batching and Parallelization
+
+### 12. Batch Processing
+
+Process multiple items in single LLM call.
+
+```python
+class BatchProcessor:
+    async def process_batch(self, items, max_batch_size=10):
+        results = []
+
+        for i in range(0, len(items), max_batch_size):
+            batch = items[i:i+max_batch_size]
+
+            # Process entire batch in one call
+            batch_prompt = "Process each item:\n\n"
+            for idx, item in enumerate(batch):
+                batch_prompt += f"Item {idx+1}: {item}\n"
+
+            batch_results = await self.llm.generate(batch_prompt)
+            results.extend(self.parse_batch_results(batch_results))
+
+        return results
+```
+
+### 13. Parallel Context Loading
+
+Load multiple context sources in parallel.
+
+```python
+class ParallelContextLoader:
+    async def load_context(self, query):
+        # Load multiple sources in parallel
+        results = await asyncio.gather(
+            self.load_vector_search(query),
+            self.load_user_preferences(query.user_id),
+            self.load_recent_history(query.session_id),
+            self.load_domain_knowledge(query.domain)
+        )
+
+        vector_results, preferences, history, knowledge = results
+
+        # Combine and trim to budget
+        combined = self.combine_context(
+            vector_results,
+            preferences,
+            history,
+            knowledge,
+            token_budget=8000
+        )
+
+        return combined
+```
+
+## Cost-Aware Optimization
+
+### 14. Model Selection by Budget
+
+Choose model based on available budget.
+
+```python
+class BudgetAwareModelSelector:
+    def select_model(self, task_complexity, token_budget, cost_budget):
+        # For complex tasks with high budget, use best model
+        if task_complexity == 'high' and cost_budget > 1.0:
+            return 'claude-opus-4'
+
+        # For medium complexity, use balanced model
+        elif task_complexity == 'medium':
+            return 'claude-sonnet-4'
+
+        # For simple tasks or tight budget, use efficient model
+        else:
+            return 'claude-haiku-4'
+
+# Usage
+selector = BudgetAwareModelSelector()
+model = selector.select_model(
+    task_complexity='medium',
+    token_budget=10000,
+    cost_budget=0.5
+)
+```
+
+### 15. Progressive Detail Loading
+
+Start with minimal context, add detail if needed.
+
+```python
+class ProgressiveLoader:
+    async def solve(self, task):
+        # Start with minimal context
+        context = await self.load_minimal_context(task)
+        response = await self.llm.generate(task, context=context)
+
+        # If agent says it needs more info...
+        if "need more information" in response.lower():
+            # Load medium context
+            context = await self.load_medium_context(task)
+            response = await self.llm.generate(task, context=context)
+
+            # If still needs more...
+            if "need more information" in response.lower():
+                # Load full context
+                context = await self.load_full_context(task)
+                response = await self.llm.generate(task, context=context)
+
+        return response
+```
+
+## Monitoring and Analytics
+
+### 16. Token Usage Analytics
+
+Track where tokens are being spent.
+
+```python
+class TokenAnalytics:
+    def __init__(self):
+        self.usage = defaultdict(lambda: {'input': 0, 'output': 0})
+
+    def record(self, component, input_tokens, output_tokens):
+        self.usage[component]['input'] += input_tokens
+        self.usage[component]['output'] += output_tokens
+
+    def get_report(self):
+        total_input = sum(u['input'] for u in self.usage.values())
+        total_output = sum(u['output'] for u in self.usage.values())
+
+        report = {
+            'total_tokens': total_input + total_output,
+            'total_input': total_input,
+            'total_output': total_output,
+            'by_component': {}
+        }
+
+        for component, usage in self.usage.items():
+            total = usage['input'] + usage['output']
+            report['by_component'][component] = {
+                'tokens': total,
+                'percentage': (total / report['total_tokens']) * 100
+            }
+
+        return report
+
+# Find optimization opportunities
+analytics = TokenAnalytics()
+report = analytics.get_report()
+top_spenders = sorted(
+    report['by_component'].items(),
+    key=lambda x: x[1]['tokens'],
+    reverse=True
+)[:5]
+print(f"Top 5 token consumers: {top_spenders}")
+```
+
+## Best Practices Summary
+
+1. **Compress old context**: Summarize conversations > 20 messages
+2. **Load selectively**: Retrieve only relevant context for current task
+3. **Use structured formats**: JSON/YAML more efficient than prose
+4. **Cache intelligently**: Cache common prompts and similar queries
+5. **Batch when possible**: Process multiple items per LLM call
+6. **Monitor usage**: Track token usage by component
+7. **Progressive loading**: Start minimal, add detail if needed
+8. **Deduplicate**: Remove semantically similar context
+9. **Time decay**: Weight recent information more heavily
+10. **Budget enforcement**: Hard limits on tokens per agent/session

package/skills/agentic/context-engineering/refs/compression-techniques.md

@@ -0,0 +1,171 @@
+---
+phase_relevance: ["design", "review"]
+archetype_relevance: ["*"]
+---
+# Context Optimization Techniques
+
+Advanced strategies for minimizing token usage while maximizing context quality.
+
+## Compression Techniques
+
+### 1. Conversation Summarization
+
+Progressive summarization of conversation history.
+
+```python
+class ConversationCompressor:
+    def __init__(self, llm, max_full_messages=10, summary_length=500):
+        self.llm = llm
+        self.max_full_messages = max_full_messages
+        self.summary_length = summary_length
+
+    async def compress(self, messages):
+        if len(messages) <= self.max_full_messages:
+            return messages
+
+        # Split into old (to summarize) and recent (keep full)
+        old_messages = messages[:-self.max_full_messages]
+        recent_messages = messages[-self.max_full_messages:]
+
+        # Create summary of old messages
+        summary_prompt = f"""Summarize this conversation in {self.summary_length} words or less.
+        Focus on:
+        - Key decisions made
+        - Important facts established
+        - Current task state
+
+        Conversation:
+        {self.format_messages(old_messages)}
+        """
+
+        summary = await self.llm.generate(summary_prompt, max_tokens=self.summary_length * 2)
+
+        # Return summary + recent messages
+        return [
+            {"role": "system", "content": f"Previous conversation summary:\n{summary}"}
+        ] + recent_messages
+
+    def format_messages(self, messages):
+        return "\n".join(f"{m['role']}: {m['content']}" for m in messages)
+```
+
+### 2. Semantic Deduplication
+
+Remove redundant information.
+
+```python
+from sentence_transformers import SentenceTransformer
+from sklearn.metrics.pairwise import cosine_similarity
+
+class SemanticDeduplicator:
+    def __init__(self, similarity_threshold=0.9):
+        self.encoder = SentenceTransformer('all-MiniLM-L6-v2')
+        self.threshold = similarity_threshold
+
+    def deduplicate(self, texts):
+        if not texts:
+            return texts
+
+        # Encode all texts
+        embeddings = self.encoder.encode(texts)
+
+        # Keep track of which to keep
+        keep_indices = [0]  # Always keep first
+
+        for i in range(1, len(texts)):
+            # Compare to all kept texts
+            similarities = cosine_similarity(
+                [embeddings[i]],
+                embeddings[keep_indices]
+            )[0]
+
+            # Only keep if not too similar to existing
+            if max(similarities) < self.threshold:
+                keep_indices.append(i)
+
+        return [texts[i] for i in keep_indices]
+
+# Usage
+deduper = SemanticDeduplicator()
+unique_contexts = deduper.deduplicate([
+    "The user prefers Python",
+    "User likes Python programming",  # Very similar - would be removed
+    "The user works at Acme Corp"      # Different - would be kept
+])
+```
+
+### 3. Hierarchical Summarization
+
+Summarize at multiple levels of detail.
+
+```python
+class HierarchicalSummarizer:
+    async def summarize(self, text, levels=3):
+        summaries = {}
+
+        # Level 0: Full text
+        summaries['full'] = text
+
+        # Level 1: Detailed summary (50% reduction)
+        summaries['detailed'] = await self.llm.generate(
+            f"Summarize in half the length:\n{text}"
+        )
+
+        # Level 2: Brief summary (80% reduction)
+        summaries['brief'] = await self.llm.generate(
+            f"Summarize in 1-2 paragraphs:\n{summaries['detailed']}"
+        )
+
+        # Level 3: Ultra-brief (95% reduction)
+        summaries['headline'] = await self.llm.generate(
+            f"Summarize in one sentence:\n{summaries['brief']}"
+        )
+
+        return summaries
+
+# Usage: Choose appropriate level based on available tokens
+summaries = await summarizer.summarize(long_document)
+if tokens_available > 5000:
+    context = summaries['detailed']
+elif tokens_available > 1000:
+    context = summaries['brief']
+else:
+    context = summaries['headline']
+```
+
+### 4. Entity-Based Compression
+
+Extract and store only key entities and relationships.
+
+```python
+class EntityCompressor:
+    async def compress(self, text):
+        # Extract entities
+        entities_prompt = f"""Extract key entities and relationships from this text.
+        Format as JSON: {{"entities": [...], "relationships": [...]}}
+
+        Text: {text}
+        """
+
+        entities = await self.llm.generate(entities_prompt)
+
+        # Store compressed representation
+        return {
+            'entities': entities['entities'],
+            'relationships': entities['relationships'],
+            'original_length': len(text),
+            'compressed_length': len(str(entities))
+        }
+
+    def reconstruct_context(self, compressed):
+        # Build minimal context from entities
+        context = "Key facts:\n"
+        for entity in compressed['entities']:
+            context += f"- {entity}\n"
+
+        context += "\nRelationships:\n"
+        for rel in compressed['relationships']:
+            context += f"- {rel}\n"
+
+        return context
+```

package/skills/agentic/context-engineering/refs/cost-calculation-budget.md

@@ -0,0 +1,250 @@
+---
+phase_relevance: ["design", "review"]
+archetype_relevance: ["*"]
+---
+# Token Cost Models and Budgeting
+
+Comprehensive guide to calculating, tracking, and optimizing token costs in agentic systems.
+
+## Pricing Overview (2026 Estimates)
+
+```python
+PRICING = {
+    # Anthropic Claude
+    'claude-opus-4-6': {
+        'input': 0.015,   # $ per 1K tokens
+        'output': 0.075,
+        'context_window': 200000,
+        'output_limit': 16000
+    },
+    'claude-sonnet-4-5': {
+        'input': 0.003,
+        'output': 0.015,
+        'context_window': 200000,
+        'output_limit': 16000
+    },
+    'claude-haiku-4': {
+        'input': 0.0008,
+        'output': 0.004,
+        'context_window': 200000,
+        'output_limit': 8000
+    },
+
+    # OpenAI GPT
+    'gpt-4-turbo': {
+        'input': 0.01,
+        'output': 0.03,
+        'context_window': 128000,
+        'output_limit': 4096
+    },
+    'gpt-4': {
+        'input': 0.03,
+        'output': 0.06,
+        'context_window': 8192,
+        'output_limit': 4096
+    },
+    'gpt-3.5-turbo': {
+        'input': 0.001,
+        'output': 0.002,
+        'context_window': 16384,
+        'output_limit': 4096
+    },
+}
+```
+
+Note: These are approximate rates. Always check current pricing from providers.
+
+## Cost Calculation
+
+### Basic Cost Calculator
+
+```python
+class CostCalculator:
+    def __init__(self, pricing=PRICING):
+        self.pricing = pricing
+
+    def calculate(self, model, input_tokens, output_tokens):
+        """Calculate cost for a single LLM call."""
+        if model not in self.pricing:
+            raise ValueError(f"Unknown model: {model}")
+
+        rates = self.pricing[model]
+
+        input_cost = (input_tokens / 1000) * rates['input']
+        output_cost = (output_tokens / 1000) * rates['output']
+
+        return {
+            'input_cost': input_cost,
+            'output_cost': output_cost,
+            'total_cost': input_cost + output_cost,
+            'input_tokens': input_tokens,
+            'output_tokens': output_tokens
+        }
+
+# Example
+calc = CostCalculator()
+cost = calc.calculate('claude-opus-4-6', input_tokens=10000, output_tokens=2000)
+print(f"Total cost: ${cost['total_cost']:.4f}")  # $0.30
+```
+
+### Multi-Agent Cost Tracking
+
+```python
+class MultiAgentCostTracker:
+    def __init__(self):
+        self.calls = []  # All LLM calls
+        self.costs_by_agent = defaultdict(float)
+        self.costs_by_model = defaultdict(float)
+
+    def record_call(self, agent_id, model, input_tokens, output_tokens):
+        """Record a single LLM call."""
+        calc = CostCalculator()
+        cost_info = calc.calculate(model, input_tokens, output_tokens)
+
+        # Store call details
+        self.calls.append({
+            'timestamp': datetime.now(),
+            'agent_id': agent_id,
+            'model': model,
+            **cost_info
+        })
+
+        # Update aggregates
+        self.costs_by_agent[agent_id] += cost_info['total_cost']
+        self.costs_by_model[model] += cost_info['total_cost']
+
+    def get_total_cost(self):
+        """Get total cost across all calls."""
+        return sum(call['total_cost'] for call in self.calls)
+
+    def get_agent_costs(self):
+        """Get cost breakdown by agent."""
+        return dict(sorted(
+            self.costs_by_agent.items(),
+            key=lambda x: x[1],
+            reverse=True
+        ))
+
+    def get_model_costs(self):
+        """Get cost breakdown by model."""
+        return dict(sorted(
+            self.costs_by_model.items(),
+            key=lambda x: x[1],
+            reverse=True
+        ))
+
+    def get_stats(self):
+        """Get comprehensive statistics."""
+        total_tokens = sum(
+            call['input_tokens'] + call['output_tokens']
+            for call in self.calls
+        )
+
+        return {
+            'total_cost': self.get_total_cost(),
+            'total_calls': len(self.calls),
+            'total_tokens': total_tokens,
+            'avg_cost_per_call': self.get_total_cost() / len(self.calls) if self.calls else 0,
+            'avg_tokens_per_call': total_tokens / len(self.calls) if self.calls else 0,
+            'by_agent': self.get_agent_costs(),
+            'by_model': self.get_model_costs()
+        }
+```
+
+## Budget Management
+
+### Session Budget
+
+```python
+class SessionBudget:
+    def __init__(self, max_cost=5.0):
+        self.max_cost = max_cost
+        self.spent = 0.0
+        self.calls = []
+
+    def check_and_reserve(self, estimated_cost):
+        """Check if we can afford this call."""
+        if self.spent + estimated_cost > self.max_cost:
+            raise BudgetExceededError(
+                f"Would exceed budget: ${self.spent + estimated_cost:.4f} > ${self.max_cost:.4f}"
+            )
+
+    def record_actual(self, actual_cost):
+        """Record actual cost after call."""
+        self.spent += actual_cost
+        self.calls.append({
+            'timestamp': datetime.now(),
+            'cost': actual_cost
+        })
+
+    def get_remaining(self):
+        """Get remaining budget."""
+        return self.max_cost - self.spent
+
+    def get_utilization(self):
+        """Get budget utilization percentage."""
+        return (self.spent / self.max_cost) * 100
+
+# Usage
+budget = SessionBudget(max_cost=1.0)
+
+# Before each call
+estimated_cost = estimate_cost(model, estimated_input, estimated_output)
+budget.check_and_reserve(estimated_cost)
+
+# After call
+actual_cost = calculate_actual_cost(model, actual_input, actual_output)
+budget.record_actual(actual_cost)
+```
+
+### Tiered Budget System
+
+```python
+class TieredBudget:
+    """Different budget limits for different user tiers."""
+
+    TIERS = {
+        'free': {'daily': 0.10, 'monthly': 2.0},
+        'pro': {'daily': 1.0, 'monthly': 25.0},
+        'enterprise': {'daily': 10.0, 'monthly': 500.0}
+    }
+
+    def __init__(self, user_tier):
+        self.tier = user_tier
+        self.limits = self.TIERS[user_tier]
+        self.daily_spent = 0.0
+        self.monthly_spent = 0.0
+        self.last_reset = datetime.now()
+
+    def check_budget(self, estimated_cost):
+        """Check both daily and monthly budgets."""
+        self._reset_if_needed()
+
+        if self.daily_spent + estimated_cost > self.limits['daily']:
+            raise DailyBudgetExceeded(
+                f"Daily limit: ${self.limits['daily']}"
+            )
+
+        if self.monthly_spent + estimated_cost > self.limits['monthly']:
+            raise MonthlyBudgetExceeded(
+                f"Monthly limit: ${self.limits['monthly']}"
+            )
+
+    def record_usage(self, cost):
+        self._reset_if_needed()
+        self.daily_spent += cost
+        self.monthly_spent += cost
+
+    def _reset_if_needed(self):
+        now = datetime.now()
+
+        # Reset daily budget
+        if now.date() > self.last_reset.date():
+            self.daily_spent = 0.0
+
+        # Reset monthly budget
+        if now.month != self.last_reset.month:
+            self.monthly_spent = 0.0
+
+        self.last_reset = now
+```