tech-hub-skills 1.2.0 → 1.5.1

package/.claude/roles/ai-engineer/skills/01-prompt-engineering/token_cost_estimator.py

@@ -0,0 +1,324 @@
+"""
+Token Cost Estimator for Multiple LLM Providers
+Calculate and compare costs across OpenAI, Anthropic, Google, and more.
+"""
+
+import tiktoken
+from typing import Dict, Optional, Tuple
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Provider(Enum):
+    """Supported LLM providers."""
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    GOOGLE = "google"
+    META = "meta"
+    MISTRAL = "mistral"
+
+
+@dataclass
+class ModelPricing:
+    """Pricing information for a model."""
+    input_cost_per_1k: float  # Cost per 1K input tokens
+    output_cost_per_1k: float  # Cost per 1K output tokens
+    context_window: int  # Maximum context window in tokens
+
+
+# Pricing as of December 2025 (prices in USD)
+PRICING_TABLE: Dict[str, ModelPricing] = {
+    # OpenAI
+    "gpt-4-turbo": ModelPricing(0.01, 0.03, 128000),
+    "gpt-4": ModelPricing(0.03, 0.06, 8192),
+    "gpt-3.5-turbo": ModelPricing(0.0005, 0.0015, 16385),
+    "gpt-4o": ModelPricing(0.005, 0.015, 128000),
+    "gpt-4o-mini": ModelPricing(0.00015, 0.0006, 128000),
+
+    # Anthropic
+    "claude-opus-4": ModelPricing(0.015, 0.075, 200000),
+    "claude-sonnet-4": ModelPricing(0.003, 0.015, 200000),
+    "claude-haiku-4": ModelPricing(0.00025, 0.00125, 200000),
+    "claude-3-opus": ModelPricing(0.015, 0.075, 200000),
+    "claude-3-sonnet": ModelPricing(0.003, 0.015, 200000),
+    "claude-3-haiku": ModelPricing(0.00025, 0.00125, 200000),
+
+    # Google
+    "gemini-pro": ModelPricing(0.000125, 0.000375, 32760),
+    "gemini-pro-vision": ModelPricing(0.000125, 0.000375, 16384),
+    "gemini-ultra": ModelPricing(0.001, 0.002, 32760),
+    "gemini-1.5-pro": ModelPricing(0.00125, 0.005, 1000000),
+    "gemini-1.5-flash": ModelPricing(0.000125, 0.0005, 1000000),
+
+    # Meta (via hosting providers - example pricing)
+    "llama-3-70b": ModelPricing(0.0007, 0.0009, 8192),
+    "llama-3-8b": ModelPricing(0.0002, 0.0002, 8192),
+
+    # Mistral
+    "mistral-large": ModelPricing(0.004, 0.012, 32000),
+    "mistral-medium": ModelPricing(0.0027, 0.0081, 32000),
+    "mistral-small": ModelPricing(0.001, 0.003, 32000),
+}
+
+
+class TokenCounter:
+    """Count tokens for different providers."""
+
+    def __init__(self):
+        self.encoders = {
+            Provider.OPENAI: tiktoken.get_encoding("cl100k_base"),
+            # For other providers, we approximate with cl100k_base
+            # In production, use provider-specific tokenizers
+        }
+
+    def count_tokens(self, text: str, provider: Provider = Provider.OPENAI) -> int:
+        """Count tokens in text."""
+        encoder = self.encoders.get(provider, self.encoders[Provider.OPENAI])
+        return len(encoder.encode(text))
+
+    def count_tokens_for_messages(
+        self,
+        messages: list,
+        model: str = "gpt-4"
+    ) -> int:
+        """Count tokens for chat completion messages."""
+        encoding = tiktoken.encoding_for_model(model)
+
+        # Token counting varies by model
+        if "gpt-4" in model or "gpt-3.5" in model:
+            tokens_per_message = 3
+            tokens_per_name = 1
+        else:
+            tokens_per_message = 3
+            tokens_per_name = 1
+
+        num_tokens = 0
+        for message in messages:
+            num_tokens += tokens_per_message
+            for key, value in message.items():
+                num_tokens += len(encoding.encode(str(value)))
+                if key == "name":
+                    num_tokens += tokens_per_name
+
+        num_tokens += 3  # every reply is primed with assistant
+        return num_tokens
+
+
+class CostEstimator:
+    """Estimate costs for LLM API calls."""
+
+    def __init__(self):
+        self.token_counter = TokenCounter()
+
+    def estimate_cost(
+        self,
+        input_text: str,
+        model: str,
+        estimated_output_tokens: int = 0,
+        provider: Optional[Provider] = None
+    ) -> Dict[str, float]:
+        """
+        Estimate the cost of an LLM API call.
+
+        Args:
+            input_text: The input prompt
+            model: Model name (e.g., 'gpt-4', 'claude-3-opus')
+            estimated_output_tokens: Expected output length
+            provider: LLM provider (auto-detected if None)
+
+        Returns:
+            Dictionary with cost breakdown
+        """
+        # Auto-detect provider if not specified
+        if provider is None:
+            provider = self._detect_provider(model)
+
+        # Get pricing info
+        pricing = PRICING_TABLE.get(model)
+        if not pricing:
+            raise ValueError(f"Unknown model: {model}")
+
+        # Count input tokens
+        input_tokens = self.token_counter.count_tokens(input_text, provider)
+
+        # Calculate costs
+        input_cost = (input_tokens / 1000) * pricing.input_cost_per_1k
+        output_cost = (estimated_output_tokens / 1000) * pricing.output_cost_per_1k
+        total_cost = input_cost + output_cost
+
+        return {
+            "input_tokens": input_tokens,
+            "output_tokens": estimated_output_tokens,
+            "total_tokens": input_tokens + estimated_output_tokens,
+            "input_cost": input_cost,
+            "output_cost": output_cost,
+            "total_cost": total_cost,
+            "currency": "USD",
+            "model": model,
+            "context_window": pricing.context_window,
+            "context_utilization": (input_tokens + estimated_output_tokens) / pricing.context_window
+        }
+
+    def compare_models(
+        self,
+        input_text: str,
+        models: list,
+        estimated_output_tokens: int = 500
+    ) -> Dict[str, Dict[str, float]]:
+        """Compare costs across multiple models."""
+        comparisons = {}
+
+        for model in models:
+            try:
+                cost = self.estimate_cost(input_text, model, estimated_output_tokens)
+                comparisons[model] = cost
+            except ValueError as e:
+                comparisons[model] = {"error": str(e)}
+
+        return comparisons
+
+    def _detect_provider(self, model: str) -> Provider:
+        """Auto-detect provider from model name."""
+        if "gpt" in model.lower():
+            return Provider.OPENAI
+        elif "claude" in model.lower():
+            return Provider.ANTHROPIC
+        elif "gemini" in model.lower():
+            return Provider.GOOGLE
+        elif "llama" in model.lower():
+            return Provider.META
+        elif "mistral" in model.lower():
+            return Provider.MISTRAL
+        else:
+            return Provider.OPENAI  # Default
+
+    def estimate_monthly_cost(
+        self,
+        queries_per_day: int,
+        avg_input_tokens: int,
+        avg_output_tokens: int,
+        model: str
+    ) -> Dict[str, float]:
+        """Estimate monthly costs based on usage patterns."""
+        pricing = PRICING_TABLE.get(model)
+        if not pricing:
+            raise ValueError(f"Unknown model: {model}")
+
+        # Daily costs
+        daily_input_cost = (queries_per_day * avg_input_tokens / 1000) * pricing.input_cost_per_1k
+        daily_output_cost = (queries_per_day * avg_output_tokens / 1000) * pricing.output_cost_per_1k
+        daily_cost = daily_input_cost + daily_output_cost
+
+        # Monthly projection (30 days)
+        monthly_cost = daily_cost * 30
+
+        return {
+            "queries_per_day": queries_per_day,
+            "daily_cost": daily_cost,
+            "monthly_cost": monthly_cost,
+            "yearly_cost": monthly_cost * 12,
+            "cost_per_query": daily_cost / queries_per_day,
+            "model": model
+        }
+
+
+def format_cost_comparison(comparisons: Dict[str, Dict[str, float]]) -> str:
+    """Format cost comparison for display."""
+    lines = ["🔍 Cost Comparison", "=" * 70]
+
+    # Sort by total cost
+    sorted_models = sorted(
+        [(k, v) for k, v in comparisons.items() if "error" not in v],
+        key=lambda x: x[1]["total_cost"]
+    )
+
+    for model, cost in sorted_models:
+        lines.append(f"\n📊 {model}")
+        lines.append(f"  Input:  {cost['input_tokens']:,} tokens → ${cost['input_cost']:.6f}")
+        lines.append(f"  Output: {cost['output_tokens']:,} tokens → ${cost['output_cost']:.6f}")
+        lines.append(f"  Total:  ${cost['total_cost']:.6f}")
+        lines.append(f"  Context: {cost['context_utilization']:.1%} utilized")
+
+    return "\n".join(lines)
+
+
+# Example usage
+if __name__ == "__main__":
+    estimator = CostEstimator()
+
+    # Example prompt
+    prompt = """Analyze this marketing campaign and provide detailed recommendations:
+
+    Campaign: Summer Sale 2025
+    Budget: $50,000
+    Duration: 30 days
+    Channels: Email, Social Media, Search Ads
+
+    Current Metrics (Week 1):
+    - Impressions: 1,200,000
+    - Clicks: 24,000 (CTR: 2%)
+    - Conversions: 480 (Conv Rate: 2%)
+    - Revenue: $48,000
+    - ROAS: 0.96
+
+    Please provide:
+    1. Performance analysis
+    2. Optimization recommendations
+    3. Budget reallocation strategy
+    4. Projected outcomes
+    """
+
+    # Single model estimate
+    print("=" * 70)
+    print("💰 Single Model Estimation")
+    print("=" * 70)
+
+    cost = estimator.estimate_cost(
+        input_text=prompt,
+        model="gpt-4o",
+        estimated_output_tokens=1000
+    )
+
+    print(f"\nModel: {cost['model']}")
+    print(f"Input tokens: {cost['input_tokens']:,}")
+    print(f"Estimated output tokens: {cost['output_tokens']:,}")
+    print(f"Total cost: ${cost['total_cost']:.4f}")
+    print(f"Context utilization: {cost['context_utilization']:.1%}")
+
+    # Compare multiple models
+    print("\n" + "=" * 70)
+    models_to_compare = [
+        "gpt-4o",
+        "gpt-4o-mini",
+        "claude-sonnet-4",
+        "claude-haiku-4",
+        "gemini-1.5-pro",
+        "gemini-1.5-flash"
+    ]
+
+    comparisons = estimator.compare_models(
+        input_text=prompt,
+        models=models_to_compare,
+        estimated_output_tokens=1000
+    )
+
+    print(format_cost_comparison(comparisons))
+
+    # Monthly cost projection
+    print("\n" + "=" * 70)
+    print("📅 Monthly Cost Projection")
+    print("=" * 70)
+
+    monthly = estimator.estimate_monthly_cost(
+        queries_per_day=1000,
+        avg_input_tokens=500,
+        avg_output_tokens=800,
+        model="gpt-4o"
+    )
+
+    print(f"\nModel: {monthly['model']}")
+    print(f"Queries per day: {monthly['queries_per_day']:,}")
+    print(f"Daily cost: ${monthly['daily_cost']:.2f}")
+    print(f"Monthly cost: ${monthly['monthly_cost']:.2f}")
+    print(f"Yearly cost: ${monthly['yearly_cost']:,.2f}")
+    print(f"Cost per query: ${monthly['cost_per_query']:.4f}")

package/.claude/roles/ai-engineer/skills/02-rag-pipeline/document_chunker.py

@@ -0,0 +1,336 @@
+"""
+Advanced Document Chunking for RAG Systems
+Supports semantic, recursive, and fixed-size chunking strategies.
+"""
+
+from typing import List, Dict, Any, Optional
+from dataclasses import dataclass
+from enum import Enum
+import re
+from langchain.text_splitter import (
+    RecursiveCharacterTextSplitter,
+    CharacterTextSplitter,
+    TokenTextSplitter
+)
+
+
+class ChunkStrategy(Enum):
+    """Available chunking strategies."""
+    FIXED = "fixed"  # Fixed character/token size
+    SEMANTIC = "semantic"  # Semantic boundaries (paragraphs, sentences)
+    RECURSIVE = "recursive"  # Recursive splitting with multiple separators
+    SLIDING_WINDOW = "sliding_window"  # Overlapping windows
+
+
+@dataclass
+class Chunk:
+    """A document chunk with metadata."""
+    content: str
+    chunk_id: str
+    document_id: str
+    chunk_index: int
+    metadata: Dict[str, Any]
+    char_count: int
+    token_count: Optional[int] = None
+
+    def __post_init__(self):
+        if self.char_count == 0:
+            self.char_count = len(self.content)
+
+
+class DocumentChunker:
+    """Advanced document chunker with multiple strategies."""
+
+    def __init__(
+        self,
+        strategy: ChunkStrategy = ChunkStrategy.RECURSIVE,
+        chunk_size: int = 1000,
+        chunk_overlap: int = 200,
+        separators: Optional[List[str]] = None
+    ):
+        """
+        Initialize document chunker.
+
+        Args:
+            strategy: Chunking strategy to use
+            chunk_size: Target chunk size (characters or tokens)
+            chunk_overlap: Overlap between chunks
+            separators: Custom separators for recursive splitting
+        """
+        self.strategy = strategy
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self.separators = separators or ["\n\n", "\n", ". ", " ", ""]
+
+        self._init_splitter()
+
+    def _init_splitter(self):
+        """Initialize the appropriate text splitter."""
+        if self.strategy == ChunkStrategy.RECURSIVE:
+            self.splitter = RecursiveCharacterTextSplitter(
+                chunk_size=self.chunk_size,
+                chunk_overlap=self.chunk_overlap,
+                separators=self.separators,
+                length_function=len
+            )
+        elif self.strategy == ChunkStrategy.FIXED:
+            self.splitter = CharacterTextSplitter(
+                chunk_size=self.chunk_size,
+                chunk_overlap=self.chunk_overlap,
+                separator="\n"
+            )
+        elif self.strategy == ChunkStrategy.SEMANTIC:
+            # For semantic chunking, we'll use custom logic
+            self.splitter = None
+        else:
+            self.splitter = RecursiveCharacterTextSplitter(
+                chunk_size=self.chunk_size,
+                chunk_overlap=self.chunk_overlap
+            )
+
+    def chunk_document(
+        self,
+        text: str,
+        document_id: str,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> List[Chunk]:
+        """
+        Chunk a document into smaller pieces.
+
+        Args:
+            text: Document text
+            document_id: Unique document identifier
+            metadata: Additional metadata
+
+        Returns:
+            List of Chunk objects
+        """
+        metadata = metadata or {}
+
+        if self.strategy == ChunkStrategy.SEMANTIC:
+            text_chunks = self._semantic_chunking(text)
+        elif self.strategy == ChunkStrategy.SLIDING_WINDOW:
+            text_chunks = self._sliding_window_chunking(text)
+        else:
+            text_chunks = self.splitter.split_text(text)
+
+        chunks = []
+        for idx, chunk_text in enumerate(text_chunks):
+            chunk = Chunk(
+                content=chunk_text,
+                chunk_id=f"{document_id}_chunk_{idx}",
+                document_id=document_id,
+                chunk_index=idx,
+                metadata={**metadata, "strategy": self.strategy.value},
+                char_count=len(chunk_text)
+            )
+            chunks.append(chunk)
+
+        return chunks
+
+    def _semantic_chunking(self, text: str) -> List[str]:
+        """
+        Chunk by semantic boundaries (paragraphs with context).
+
+        This strategy:
+        1. Splits on paragraph boundaries
+        2. Combines small paragraphs
+        3. Ensures chunks don't exceed max size
+        """
+        # Split into paragraphs
+        paragraphs = re.split(r'\n\s*\n', text)
+
+        chunks = []
+        current_chunk = []
+        current_length = 0
+
+        for para in paragraphs:
+            para = para.strip()
+            if not para:
+                continue
+
+            para_length = len(para)
+
+            # If paragraph alone exceeds chunk size, split it
+            if para_length > self.chunk_size:
+                # Save current chunk if exists
+                if current_chunk:
+                    chunks.append("\n\n".join(current_chunk))
+                    current_chunk = []
+                    current_length = 0
+
+                # Split large paragraph
+                sentences = re.split(r'(?<=[.!?])\s+', para)
+                temp_chunk = []
+                temp_length = 0
+
+                for sentence in sentences:
+                    sent_length = len(sentence)
+                    if temp_length + sent_length > self.chunk_size:
+                        if temp_chunk:
+                            chunks.append(" ".join(temp_chunk))
+                        temp_chunk = [sentence]
+                        temp_length = sent_length
+                    else:
+                        temp_chunk.append(sentence)
+                        temp_length += sent_length + 1
+
+                if temp_chunk:
+                    chunks.append(" ".join(temp_chunk))
+
+            # If adding paragraph exceeds chunk size, save current chunk
+            elif current_length + para_length > self.chunk_size:
+                if current_chunk:
+                    chunks.append("\n\n".join(current_chunk))
+                current_chunk = [para]
+                current_length = para_length
+
+            # Otherwise, add to current chunk
+            else:
+                current_chunk.append(para)
+                current_length += para_length + 2  # +2 for \n\n
+
+        # Add remaining chunk
+        if current_chunk:
+            chunks.append("\n\n".join(current_chunk))
+
+        return chunks
+
+    def _sliding_window_chunking(self, text: str) -> List[str]:
+        """
+        Create overlapping chunks with sliding window.
+
+        Useful for ensuring important content at chunk boundaries isn't lost.
+        """
+        chunks = []
+        start = 0
+
+        while start < len(text):
+            end = start + self.chunk_size
+            chunk = text[start:end]
+
+            # Try to end at sentence boundary
+            if end < len(text):
+                last_period = chunk.rfind('. ')
+                if last_period > self.chunk_size // 2:
+                    chunk = chunk[:last_period + 1]
+                    end = start + last_period + 1
+
+            chunks.append(chunk.strip())
+
+            # Move start forward (with overlap)
+            start = end - self.chunk_overlap
+
+        return chunks
+
+    def chunk_multiple_documents(
+        self,
+        documents: List[Dict[str, Any]]
+    ) -> List[Chunk]:
+        """
+        Chunk multiple documents.
+
+        Args:
+            documents: List of dicts with 'id', 'text', and optional 'metadata'
+
+        Returns:
+            List of all chunks
+        """
+        all_chunks = []
+
+        for doc in documents:
+            chunks = self.chunk_document(
+                text=doc['text'],
+                document_id=doc['id'],
+                metadata=doc.get('metadata', {})
+            )
+            all_chunks.extend(chunks)
+
+        return all_chunks
+
+    def get_chunk_statistics(self, chunks: List[Chunk]) -> Dict[str, Any]:
+        """Get statistics about chunks."""
+        if not chunks:
+            return {}
+
+        char_counts = [c.char_count for c in chunks]
+
+        return {
+            "total_chunks": len(chunks),
+            "total_characters": sum(char_counts),
+            "avg_chunk_size": sum(char_counts) / len(chunks),
+            "min_chunk_size": min(char_counts),
+            "max_chunk_size": max(char_counts),
+            "unique_documents": len(set(c.document_id for c in chunks)),
+            "strategy": self.strategy.value
+        }
+
+
+# Example usage
+if __name__ == "__main__":
+    # Sample document
+    sample_doc = """
+    Marketing Campaign Analysis Best Practices
+
+    Effective marketing campaign analysis requires a systematic approach to data collection and interpretation.
+
+    Data Collection
+    First, ensure you're tracking the right metrics. Common KPIs include impression count, click-through rates (CTR), conversion rates, and return on ad spend (ROAS). Use tracking pixels and UTM parameters to accurately attribute conversions.
+
+    Campaign Segmentation
+    Break down your analysis by campaign type, channel, audience segment, and time period. This granular view helps identify what's working and what isn't. For example, email campaigns might perform better with certain demographics, while social media ads resonate with others.
+
+    Performance Benchmarking
+    Compare your results against industry benchmarks and historical data. A 2% CTR might seem low in isolation, but could be excellent for your industry. Track performance over time to identify trends and seasonality.
+
+    Attribution Modeling
+    Understand the customer journey. Did they convert after the first touchpoint or after multiple interactions? Multi-touch attribution helps allocate credit appropriately across channels.
+
+    A/B Testing
+    Never stop testing. Test subject lines, ad copy, images, calls-to-action, and landing pages. Use statistical significance testing to ensure your results are valid.
+
+    Reporting and Insights
+    Create actionable reports that tell a story. Don't just show numbers—explain what they mean and what actions should be taken. Use visualizations to make data accessible.
+
+    Continuous Optimization
+    Marketing is iterative. Use insights from each campaign to improve the next one. Build a knowledge base of what works for your audience.
+    """
+
+    print("=" * 80)
+    print("Document Chunking Demonstrations")
+    print("=" * 80)
+
+    # Test different chunking strategies
+    strategies = [
+        (ChunkStrategy.RECURSIVE, "Recursive (smart boundaries)"),
+        (ChunkStrategy.SEMANTIC, "Semantic (paragraph-based)"),
+        (ChunkStrategy.SLIDING_WINDOW, "Sliding Window (overlapping)"),
+        (ChunkStrategy.FIXED, "Fixed Size")
+    ]
+
+    for strategy, description in strategies:
+        print(f"\n📄 Strategy: {description}")
+        print("-" * 80)
+
+        chunker = DocumentChunker(
+            strategy=strategy,
+            chunk_size=300,
+            chunk_overlap=50
+        )
+
+        chunks = chunker.chunk_document(
+            text=sample_doc,
+            document_id="campaign_analysis_guide",
+            metadata={"category": "marketing", "author": "Tech Hub"}
+        )
+
+        stats = chunker.get_chunk_statistics(chunks)
+
+        print(f"Total chunks: {stats['total_chunks']}")
+        print(f"Avg chunk size: {stats['avg_chunk_size']:.0f} chars")
+        print(f"Size range: {stats['min_chunk_size']}-{stats['max_chunk_size']} chars")
+
+        print(f"\nFirst chunk preview:")
+        print(f"{chunks[0].content[:200]}...")
+
+        print(f"\nChunk IDs: {[c.chunk_id for c in chunks]}")