
AI Engineer Skill
- 115 installs
- 404kidwiz/claude-supercode-skills
Define and delegate engineering tasks to AI agents with structured execution flows.
About
AI Engineer skill enables delegating software engineering tasks to AI agents with structured execution and validation. Solo devs and teams use it to distribute coding work across multiple agents in parallel.
- AI task delegation
- Engineering workflows
- Agent orchestration
Ai Engineer by the numbers
- 115 all-time installs (skills.sh)
- Ranked #4,046 of 16,575 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Aug 11, 2026 (Skillselion catalog sync)
npx skills add https://github.com/404kidwiz/claude-supercode-skills --skill ai-engineerAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 115 |
|---|---|
| Repository | 404kidwiz/claude-supercode-skills ↗ |
What it does
Define and delegate engineering tasks to AI agents with structured execution flows.
Files
AI Engineer
Purpose
Provides expertise in end-to-end AI system development, from LLM integration to production deployment. Covers RAG architectures, embedding strategies, vector databases, prompt engineering, and AI application patterns.
When to Use
- Building LLM-powered applications or features
- Implementing RAG (Retrieval-Augmented Generation) systems
- Integrating AI APIs (OpenAI, Anthropic, etc.)
- Designing embedding and vector search pipelines
- Building chatbots or conversational AI
- Implementing AI agents with tool use
- Optimizing AI system latency and cost
Quick Start
Invoke this skill when:
- Building LLM-powered applications or features
- Implementing RAG systems with vector databases
- Integrating AI APIs into applications
- Designing embedding and retrieval pipelines
- Building conversational AI or agents
Do NOT invoke when:
- Training custom ML models from scratch (use ml-engineer)
- Deploying ML models to production infrastructure (use mlops-engineer)
- Managing multi-agent coordination (use agent-organizer)
- Optimizing LLM serving infrastructure (use llm-architect)
Decision Framework
AI Feature Type:
├── Simple Q&A → Direct LLM API call
├── Knowledge-based answers → RAG pipeline
├── Multi-step reasoning → Chain-of-thought or agents
├── External actions needed → Tool-use agents
├── Real-time data → Streaming + function calling
└── Complex workflows → Multi-agent orchestrationCore Workflows
1. RAG Pipeline Implementation
1. Chunk documents with appropriate strategy 2. Generate embeddings using suitable model 3. Store in vector database with metadata 4. Implement semantic search with reranking 5. Construct prompts with retrieved context 6. Add evaluation and monitoring
2. LLM Integration
1. Select appropriate model for use case 2. Design prompt templates with versioning 3. Implement structured output parsing 4. Add retry logic and fallbacks 5. Monitor token usage and costs 6. Cache responses where appropriate
3. AI Agent Development
1. Define agent capabilities and tools 2. Implement tool interfaces with validation 3. Design agent loop with termination conditions 4. Add guardrails and safety checks 5. Implement logging and tracing 6. Test edge cases and failure modes
Best Practices
- Version prompts alongside application code
- Use structured outputs (JSON mode) for reliability
- Implement semantic caching for common queries
- Add human-in-the-loop for critical decisions
- Monitor hallucination rates and retrieval quality
- Design for graceful degradation when AI fails
Anti-Patterns
| Anti-Pattern | Problem | Correct Approach |
|---|---|---|
| Prompt in code | Hard to iterate and test | Use prompt templates with versioning |
| No evaluation | Unknown quality in production | Implement eval pipelines |
| Synchronous LLM calls | Slow user experience | Use streaming responses |
| Unbounded context | Token limits and cost | Implement context windowing |
| No fallbacks | System fails on API errors | Add retry logic and alternatives |
AI Integration Guide
Quick Start
Installation
pip install openai anthropic chromadb sentence-transformersEnvironment Variables
export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"OpenAI Integration
Basic Usage
from integrate_openai import OpenAIIntegration, OpenAIConfig
config = OpenAIConfig(
api_key=os.getenv("OPENAI_API_KEY"),
model="gpt-4"
)
integration = OpenAIIntegration(config)
messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
response = integration.chat_completion(messages)
print(response['content'])Configuration Options
max_retries: Number of retry attempts (default: 3)retry_delay: Delay between retries in seconds (default: 1.0)timeout: Request timeout (default: 120)rate_limit_delay: Delay to avoid rate limiting (default: 0.5)
Anthropic Integration
Basic Usage
from integrate_anthropic import AnthropicIntegration, AnthropicConfig
config = AnthropicConfig(
api_key=os.getenv("ANTHROPIC_API_KEY"),
model="claude-3-5-sonnet-20241022"
)
integration = AnthropicIntegration(config)
messages = [{"role": "user", "content": "Explain AI"}]
response = integration.messages(messages)RAG Setup
Quick Start
from setup_rag import RAGSystem, RAGConfig
config = RAGConfig(
collection_name="my_docs",
embedding_model="all-MiniLM-L6-v2"
)
rag = RAGSystem(config)
# Add documents
documents = [
{
'id': 'doc1',
'text': 'Your document text here',
'metadata': {'source': 'doc.txt'}
}
]
rag.add_documents(documents)
# Query
results = rag.query("What is machine learning?")
for result in results:
print(result['text'])Prompt Management
from manage_prompts import PromptManager, PromptTemplate
manager = PromptManager()
template = PromptTemplate(
name="summary",
template="Summarize: {text}",
variables=["text"],
description="Text summarization"
)
manager.add_template(template)
# Render
rendered = template.render(text="Your text here")Monitoring
from monitor_ai_service import AIMonitor
monitor = AIMonitor(window_size=1000)
monitor.record_request(
success=True,
response_time=1.5,
token_usage=1000
)
status = monitor.get_health_status()
print(f"Healthy: {status.is_healthy}")Cost Optimization
from optimize_tokens import TokenTracker
tracker = TokenTracker()
tracker.record_usage(
model="gpt-4",
usage={'prompt_tokens': 100, 'completion_tokens': 50, 'total_tokens': 150}
)
cost = tracker.get_total_cost()
print(f"Total cost: ${cost:.4f}")Best Practices
1. Rate Limiting: Always implement rate limiting to avoid API limits 2. Error Handling: Use retry logic with exponential backoff 3. Token Tracking: Monitor usage to control costs 4. Fallback Systems: Implement fallback to alternative models 5. Monitoring: Track health metrics and response times 6. Security: Never commit API keys to version control
Pricing Reference
| Model | Input (per 1K) | Output (per 1K) |
|---|---|---|
| GPT-4 | $0.03 | $0.06 |
| GPT-4 Turbo | $0.01 | $0.03 |
| GPT-3.5 Turbo | $0.0005 | $0.0015 |
| Claude 3.5 Sonnet | $0.003 | $0.015 |
| Claude 3 Opus | $0.015 | $0.075 |
Cost Optimization Strategies
Understanding Token Costs
Token Pricing (per 1K tokens)
| Model | Input | Output | Context |
|---|---|---|---|
| GPT-4 | $0.03 | $0.06 | 8K |
| GPT-4 Turbo | $0.01 | $0.03 | 128K |
| GPT-3.5 Turbo | $0.0005 | $0.0015 | 16K |
| Claude 3.5 Sonnet | $0.003 | $0.015 | 200K |
| Claude 3 Opus | $0.015 | $0.075 | 200K |
Cost Estimation
Approximate tokens:
def estimate_tokens(text):
# Rough estimate: 1 token ≈ 0.75 words
return len(text.split()) * 1.3Full request cost:
def calculate_cost(model, input_tokens, output_tokens):
pricing = {
'gpt-4': {'input': 0.03, 'output': 0.06},
'gpt-4-turbo': {'input': 0.01, 'output': 0.03},
}
input_cost = (input_tokens / 1000) * pricing[model]['input']
output_cost = (output_tokens / 1000) * pricing[model]['output']
return input_cost + output_costOptimization Techniques
1. Model Selection
Use the right model for the task:
def select_model(task_complexity, budget):
if task_complexity == 'simple' and budget < 0.01:
return 'gpt-3.5-turbo'
elif task_complexity == 'medium' and budget < 0.10:
return 'gpt-4-turbo'
elif task_complexity == 'complex':
return 'gpt-4'
else:
return 'gpt-3.5-turbo' # Default cheapestTiered approach: 1. Start with smallest model 2. Escalate if quality insufficient 3. Cache results to avoid repeat calls
2. Prompt Optimization
Reduce prompt length:
def optimize_prompt(prompt, target_length=500):
while estimate_tokens(prompt) > target_length:
# Remove redundancies
prompt = remove_redundancies(prompt)
# Use abbreviations
prompt = abbreviate_common_terms(prompt)
# Simplify language
prompt = simplify_language(prompt)
return promptUse system prompts:
# Bad: Repeats context in every prompt
prompt = "You are a helpful assistant. Be concise. " + user_message
# Good: Set once, then use minimal prompts
client.chat.completions.create(
messages=[
{"role": "system", "content": "You are a helpful, concise assistant."},
{"role": "user", "content": user_message}
]
)3. Caching Strategies
Response caching:
from functools import lru_cache
import hashlib
@lru_cache(maxsize=1000)
def cached_llm_call(prompt_hash):
return client.generate(original_prompt)
def generate_with_cache(prompt):
prompt_hash = hashlib.md5(prompt.encode()).hexdigest()
return cached_llm_call(prompt_hash)Embedding caching:
embedding_cache = {}
def get_embeddings(texts):
uncached = [t for t in texts if t not in embedding_cache]
if uncached:
new_embeddings = client.embeddings.create(uncached)
for text, emb in zip(uncached, new_embeddings):
embedding_cache[text] = emb
return [embedding_cache[t] for t in texts]4. Batching
Batch requests:
def batch_generate(prompts, batch_size=10):
results = []
for i in range(0, len(prompts), batch_size):
batch = prompts[i:i+batch_size]
# Use batch API if available
batch_results = client.batch.generate(batch)
results.extend(batch_results)
return results5. Streaming for Long Outputs
def generate_streaming(prompt):
response = client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": prompt}],
stream=True
)
full_content = ""
for chunk in response:
if chunk.choices[0].delta.content:
content = chunk.choices[0].delta.content
full_content += content
# Process chunk as it arrives
process_chunk(content)
return full_content6. Token Limit Management
Smart truncation:
def smart_truncate(text, max_tokens, preserve_intro=True):
if estimate_tokens(text) <= max_tokens:
return text
if preserve_intro:
# Keep first and last parts
intro_tokens = max_tokens * 0.3
outro_tokens = max_tokens * 0.7
return truncate_ends(text, intro_tokens, outro_tokens)
else:
return truncate_from_start(text, max_tokens)Context window optimization:
def optimize_context_window(query, context, max_tokens):
query_tokens = estimate_tokens(query)
available_tokens = max_tokens - query_tokens - 100 # Buffer
# Select most relevant context
ranked_contexts = rank_relevance(query, context)
selected_contexts = []
for ctx in ranked_contexts:
ctx_tokens = estimate_tokens(ctx)
if sum(estimate_tokens(c) for c in selected_contexts) + ctx_tokens <= available_tokens:
selected_contexts.append(ctx)
else:
break
return "\n\n".join(selected_contexts)Monitoring and Alerts
Cost Tracking
class CostMonitor:
def __init__(self, budget_limit):
self.total_cost = 0
self.budget_limit = budget_limit
self.alerts = []
def track_usage(self, model, input_tokens, output_tokens):
cost = calculate_cost(model, input_tokens, output_tokens)
self.total_cost += cost
if self.total_cost > self.budget_limit * 0.8:
self.alerts.append(f"Budget warning: {self.total_cost:.2f}")
if self.total_cost > self.budget_limit:
self.alerts.append(f"Budget exceeded: {self.total_cost:.2f}")
def get_report(self):
return {
'total_cost': self.total_cost,
'budget_limit': self.budget_limit,
'utilization': self.total_cost / self.budget_limit,
'alerts': self.alerts
}Optimization Recommendations
def analyze_usage(usage_data):
recommendations = []
# High cost per request
avg_cost = usage_data['total_cost'] / usage_data['request_count']
if avg_cost > 0.10:
recommendations.append("Consider using smaller models")
# High error rate leads to retries
if usage_data['error_rate'] > 0.05:
recommendations.append("Improve error handling to reduce retries")
# Low cache hit rate
if usage_data['cache_hit_rate'] < 0.30:
recommendations.append("Implement response caching")
return recommendationsCost-Saving Patterns
1. Tiered LLM Strategy
Level 1: Small model for simple tasks (gpt-3.5-turbo)
Level 2: Medium model for complex tasks (gpt-4-turbo)
Level 3: Large model for critical tasks (gpt-4)2. Hybrid Approach
- Use local models for simple tasks
- Use API models for complex reasoning
- Cache everything possible
3. Fallback Patterns
def generate_with_fallbacks(prompt, models=['gpt-4', 'gpt-3.5-turbo']):
for model in models:
try:
return generate(model, prompt)
except RateLimitError:
continue
raise Exception("All models failed")Best Practices
1. Monitor continuously: Track costs in real-time 2. Set budgets: Enforce limits per user/project 3. Optimize prompts: Remove unnecessary context 4. Cache aggressively: Avoid repeat computations 5. Choose right model: Match model to task complexity 6. Use streaming: Reduce latency for long outputs 7. Batch requests: When API supports it 8. Test with small models: Before scaling to expensive ones
Prompt Templates
Template Library
Code Generation
Basic Code:
template = "Write {language} code that {description}"With Constraints:
template = """
Write {language} code that {description}.
Requirements:
- Use {framework}
- Handle errors appropriately
- Include type hints
- Add documentation
"""Code Explanation:
template = """
Explain the following {language} code:
{code}
Focus on:
- Functionality
- Best practices
- Potential improvements
"""Text Generation
Summarization:
template = """
Summarize the following text in {max_sentences} sentences:
{text}
"""Translation:
template = """
Translate the following text from {source_lang} to {target_lang}:
{text}
"""Rewriting:
template = """
Rewrite the following text in {tone} tone:
{text}
"""Question Answering
RAG QA:
template = """
Based on the following context:
{context}
Answer the question: {question}
If the answer is not in the context, say "I don't know".
"""Multi-step QA:
template = """
Step 1: {question1}
Step 2: Based on your answer, {question2}
Step 3: Finally, {question3}
"""Data Processing
Extraction:
template = """
Extract the following information from the text:
Text: {text}
Extract:
- Names: {names}
- Dates: {dates}
- Locations: {locations}
Format as JSON.
"""Classification:
template = """
Classify the following text into one of these categories:
Categories: {categories}
Text: {text}
Category:
"""Analysis
Sentiment Analysis:
template = """
Analyze the sentiment of the following text:
{text}
Provide:
- Overall sentiment (positive/negative/neutral)
- Confidence score (0-1)
- Key phrases influencing sentiment
"""Topic Modeling:
template = """
Identify the main topics in the following text:
{text}
List topics with brief descriptions.
"""Prompt Engineering Techniques
Chain-of-Thought
template = """
{question}
Think step by step:
1.
2.
3.
4.
Final answer:
"""Few-Shot Learning
template = """
Examples:
Input: "I love this!"
Output: positive
Input: "This is terrible"
Output: negative
Input: "It's okay"
Output: neutral
Input: {input_text}
Output:
"""Self-Consistency
template = """
Solve this problem: {problem}
Provide your reasoning and final answer.
"""
# Generate multiple responses, take majority voteTree-of-Thoughts
template = """
Problem: {problem}
Branch 1: {approach1}
Branch 2: {approach2}
Branch 3: {approach3}
Evaluate each branch and select the best solution.
"""System Prompts
Persona Definition
system_prompt = """
You are an expert {domain} with {years} years of experience.
Your responses should be {tone} and include {level} of detail.
Always cite sources when applicable.
"""Task Specification
system_prompt = """
Your task is to {task_description}.
Constraints:
- {constraint1}
- {constraint2}
- {constraint3}
Output format: {format_specification}
"""Prompt Optimization
A/B Testing
from prompt_engineer import PromptOptimizer
optimizer = PromptOptimizer()
template_a = "Summarize: {text}"
template_b = "Provide a concise summary of: {text}"
results = optimizer.compare_templates(
[template_a, template_b],
test_data=evaluation_set
)Iterative Improvement
def improve_prompt(current_prompt, feedback):
improved = llm.generate(f"""
Improve this prompt based on feedback:
Current prompt:
{current_prompt}
Feedback:
{feedback}
Improved prompt:
""")
return improvedBest Practices
1. Be specific: Clearly define what you want 2. Use examples: Show desired input/output pairs 3. Specify format: Define output structure explicitly 4. Add constraints: Limit response length or format 5. Test thoroughly: Validate on diverse inputs 6. Version control: Track prompt changes over time 7. Monitor performance: Track quality metrics
Common Pitfalls
1. Ambiguous instructions: Leads to inconsistent outputs 2. Too complex: Models may miss requirements 3. Missing context: Insufficient information for task 4. No examples: Models may misunderstand intent 5. Poor formatting: Hard to parse structured outputs
RAG Patterns
Core Components
1. Document Chunking
Fixed-size chunks:
chunk_size = 512
chunk_overlap = 50Semantic chunks:
- Use sentence boundaries
- Preserve paragraph structure
- Maintain context coherence
2. Embedding Models
Fast/Small:
all-MiniLM-L6-v2(384 dims, fast)all-mpnet-base-v2(768 dims, balanced)
Large/Accurate:
text-embedding-3-large(OpenAI)text-embedding-3-small(OpenAI)
3. Retrieval Strategies
Simple:
results = rag.query(query_text, n_results=5)Filtered:
results = rag.query(
query_text,
n_results=5,
where={'category': 'technical'}
)Hybrid Search:
- Combine semantic search with keyword search
- Re-rank results with cross-encoder
Advanced Patterns
Multi-hop RAG
Retrieve information across multiple steps:
def multi_hop_query(initial_query):
# First hop
results1 = rag.query(initial_query)
context1 = " ".join(r['text'] for r in results1)
# Second hop based on first results
followup = f"Based on: {context1}\nQuery: {followup_question}"
results2 = rag.query(followup)
return results1 + results2Agentic RAG
Let the agent decide what to retrieve:
def agentic_rag(query):
# Agent decides retrieval strategy
strategy = agent.analyze_query(query)
if strategy['needs_retrieval']:
results = rag.query(query, **strategy['params'])
else:
results = []
# Generate answer with retrieved context
return agent.generate_answer(query, results)Reranking
Improve retrieval quality:
def rerank(query, results, top_k=5):
from sentence_transformers import CrossEncoder
reranker = CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')
pairs = [[query, r['text']] for r in results]
scores = reranker.predict(pairs)
ranked = sorted(zip(results, scores), key=lambda x: x[1], reverse=True)
return [r for r, s in ranked[:top_k]]Citation Management
Track source information:
def generate_with_citations(query):
results = rag.query(query)
response = llm.generate(
f"Answer: {query}\n\nContext: {[r['text'] for r in results]}"
)
citations = [
{'source': r['metadata']['source'], 'chunk_id': r['metadata']['chunk_id']}
for r in results
]
return {'answer': response, 'citations': citations}Evaluation
RAGAS Framework
from ragas import evaluate
from ragas.metrics import faithfulness, answer_relevancy
metrics = [faithfulness, answer_relevancy]
results = evaluate(dataset, metrics)Custom Metrics
def retrieval_accuracy(expected_docs, retrieved_docs):
expected_ids = set(d['id'] for d in expected_docs)
retrieved_ids = set(d['id'] for d in retrieved_docs)
recall = len(expected_ids & retrieved_ids) / len(expected_ids)
precision = len(expected_ids & retrieved_ids) / len(retrieved_ids)
return {'recall': recall, 'precision': precision}Performance Optimization
Vector Index Tuning
# Use IVF for large collections
index_params = {
"index_type": "IVF_FLAT",
"nlist": 100,
"metric_type": "IP"
}Cache Frequently Asked Questions
from functools import lru_cache
@lru_cache(maxsize=1000)
def cached_query(query_hash):
return rag.query(query_hash)Best Practices
1. Chunk size: 500-1000 tokens usually works well 2. Overlap: 10-20% overlap maintains context 3. Embeddings: Choose based on speed vs accuracy needs 4. Reranking: Always rerank top 20-50 results 5. Evaluation: Regularly test retrieval quality 6. Update strategy: Implement incremental updates
"""
Anthropic Claude API Integration with retry logic and monitoring
Production-ready wrapper for Anthropic API calls
"""
import os
import time
import json
import logging
from typing import Dict, List, Optional, Any, Union
from dataclasses import dataclass
from pathlib import Path
import yaml
try:
import anthropic
from anthropic import Anthropic, APIError, RateLimitError, APITimeoutError
except ImportError:
raise ImportError("Anthropic package required: pip install anthropic")
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
@dataclass
class AnthropicConfig:
api_key: str
model: str = "claude-3-5-sonnet-20241022"
max_retries: int = 3
retry_delay: float = 1.0
timeout: int = 120
max_tokens: int = 4096
temperature: float = 0.7
rate_limit_delay: float = 0.5
@classmethod
def from_yaml(cls, path: Union[str, Path]) -> 'AnthropicConfig':
with open(path, 'r') as f:
config = yaml.safe_load(f)
return cls(**config)
class AnthropicIntegration:
def __init__(self, config: AnthropicConfig):
self.config = config
self.client = Anthropic(
api_key=config.api_key,
max_retries=config.max_retries,
timeout=config.timeout
)
self.usage_stats = {
'total_tokens': 0,
'input_tokens': 0,
'output_tokens': 0,
'total_requests': 0,
'successful_requests': 0,
'failed_requests': 0
}
def messages(
self,
messages: List[Dict[str, str]],
**kwargs
) -> Dict[str, Any]:
for attempt in range(self.config.max_retries):
try:
time.sleep(self.config.rate_limit_delay)
response = self.client.messages.create(
model=kwargs.get('model', self.config.model),
max_tokens=kwargs.get('max_tokens', self.config.max_tokens),
temperature=kwargs.get('temperature', self.config.temperature),
messages=messages,
**{k: v for k, v in kwargs.items()
if k not in ['model', 'max_tokens', 'temperature']}
)
content = response.content[0].text
self._update_usage(response.usage)
self.usage_stats['successful_requests'] += 1
self.usage_stats['total_requests'] += 1
return {
'content': content,
'usage': {
'input_tokens': response.usage.input_tokens,
'output_tokens': response.usage.output_tokens,
'total_tokens': response.usage.input_tokens + response.usage.output_tokens
},
'model': response.model,
'stop_reason': response.stop_reason
}
except RateLimitError as e:
logger.warning(f"Rate limit hit (attempt {attempt + 1}): {e}")
if attempt < self.config.max_retries - 1:
time.sleep(self.config.retry_delay * (2 ** attempt))
continue
raise
except APITimeoutError as e:
logger.warning(f"Timeout (attempt {attempt + 1}): {e}")
if attempt < self.config.max_retries - 1:
time.sleep(self.config.retry_delay * (2 ** attempt))
continue
raise
except APIError as e:
logger.error(f"API error: {e}")
self.usage_stats['failed_requests'] += 1
self.usage_stats['total_requests'] += 1
raise
def streaming_messages(
self,
messages: List[Dict[str, str]],
**kwargs
):
for attempt in range(self.config.max_retries):
try:
time.sleep(self.config.rate_limit_delay)
with self.client.messages.stream(
model=kwargs.get('model', self.config.model),
max_tokens=kwargs.get('max_tokens', self.config.max_tokens),
temperature=kwargs.get('temperature', self.config.temperature),
messages=messages,
**{k: v for k, v in kwargs.items()
if k not in ['model', 'max_tokens', 'temperature']}
) as stream:
for text in stream.text_stream:
yield text
return
except (RateLimitError, APITimeoutError) as e:
if attempt < self.config.max_retries - 1:
time.sleep(self.config.retry_delay * (2 ** attempt))
continue
raise
def _update_usage(self, usage: Any):
if usage:
self.usage_stats['input_tokens'] += usage.input_tokens
self.usage_stats['output_tokens'] += usage.output_tokens
self.usage_stats['total_tokens'] += usage.input_tokens + usage.output_tokens
def get_usage_stats(self) -> Dict[str, Any]:
return self.usage_stats.copy()
def estimate_cost(self, pricing: Dict[str, Dict[str, float]]) -> Dict[str, float]:
input_cost = (self.usage_stats['input_tokens'] / 1000000) * \
pricing.get(self.config.model, {}).get('input', 3.0)
output_cost = (self.usage_stats['output_tokens'] / 1000000) * \
pricing.get(self.config.model, {}).get('output', 15.0)
return {
'input_cost': input_cost,
'output_cost': output_cost,
'total_cost': input_cost + output_cost
}
def main():
config = AnthropicConfig(
api_key=os.getenv("ANTHROPIC_API_KEY", ""),
model="claude-3-5-sonnet-20241022"
)
integration = AnthropicIntegration(config)
messages = [
{"role": "user", "content": "Explain machine learning in one sentence."}
]
response = integration.messages(messages)
print("Response:", response['content'])
print("Usage:", response['usage'])
print("Stats:", integration.get_usage_stats())
if __name__ == "__main__":
main()
"""
OpenAI API Integration with retry logic, rate limiting, and monitoring
Production-ready wrapper for OpenAI API calls
"""
import os
import time
import json
import logging
from typing import Dict, List, Optional, Any, Union
from dataclasses import dataclass, asdict
from pathlib import Path
import yaml
try:
import openai
from openai import OpenAI, APIError, RateLimitError, APITimeoutError
except ImportError:
raise ImportError("OpenAI package required: pip install openai")
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
@dataclass
class OpenAIConfig:
api_key: str
model: str = "gpt-4"
max_retries: int = 3
retry_delay: float = 1.0
timeout: int = 120
organization: Optional[str] = None
base_url: Optional[str] = None
max_tokens: int = 4096
temperature: float = 0.7
rate_limit_delay: float = 0.5
@classmethod
def from_yaml(cls, path: Union[str, Path]) -> 'OpenAIConfig':
with open(path, 'r') as f:
config = yaml.safe_load(f)
return cls(**config)
class OpenAIIntegration:
def __init__(self, config: OpenAIConfig):
self.config = config
self.client = OpenAI(
api_key=config.api_key,
organization=config.organization,
base_url=config.base_url,
timeout=config.timeout,
max_retries=config.max_retries
)
self.usage_stats = {
'total_tokens': 0,
'prompt_tokens': 0,
'completion_tokens': 0,
'total_requests': 0,
'successful_requests': 0,
'failed_requests': 0
}
def chat_completion(
self,
messages: List[Dict[str, str]],
**kwargs
) -> Dict[str, Any]:
for attempt in range(self.config.max_retries):
try:
time.sleep(self.config.rate_limit_delay)
response = self.client.chat.completions.create(
model=kwargs.get('model', self.config.model),
messages=messages,
max_tokens=kwargs.get('max_tokens', self.config.max_tokens),
temperature=kwargs.get('temperature', self.config.temperature),
**{k: v for k, v in kwargs.items()
if k not in ['model', 'max_tokens', 'temperature']}
)
self._update_usage(response.usage)
self.usage_stats['successful_requests'] += 1
self.usage_stats['total_requests'] += 1
return {
'content': response.choices[0].message.content,
'usage': {
'prompt_tokens': response.usage.prompt_tokens,
'completion_tokens': response.usage.completion_tokens,
'total_tokens': response.usage.total_tokens
},
'model': response.model,
'finish_reason': response.choices[0].finish_reason
}
except RateLimitError as e:
logger.warning(f"Rate limit hit (attempt {attempt + 1}): {e}")
if attempt < self.config.max_retries - 1:
time.sleep(self.config.retry_delay * (2 ** attempt))
continue
raise
except APITimeoutError as e:
logger.warning(f"Timeout (attempt {attempt + 1}): {e}")
if attempt < self.config.max_retries - 1:
time.sleep(self.config.retry_delay * (2 ** attempt))
continue
raise
except APIError as e:
logger.error(f"API error: {e}")
self.usage_stats['failed_requests'] += 1
self.usage_stats['total_requests'] += 1
raise
def streaming_chat_completion(
self,
messages: List[Dict[str, str]],
**kwargs
):
for attempt in range(self.config.max_retries):
try:
time.sleep(self.config.rate_limit_delay)
stream = self.client.chat.completions.create(
model=kwargs.get('model', self.config.model),
messages=messages,
max_tokens=kwargs.get('max_tokens', self.config.max_tokens),
temperature=kwargs.get('temperature', self.config.temperature),
stream=True,
**{k: v for k, v in kwargs.items()
if k not in ['model', 'max_tokens', 'temperature', 'stream']}
)
for chunk in stream:
if chunk.choices[0].delta.content is not None:
yield chunk.choices[0].delta.content
return
except (RateLimitError, APITimeoutError) as e:
if attempt < self.config.max_retries - 1:
time.sleep(self.config.retry_delay * (2 ** attempt))
continue
raise
def embed_text(
self,
texts: List[str],
model: str = "text-embedding-3-small",
**kwargs
) -> List[List[float]]:
try:
response = self.client.embeddings.create(
model=model,
input=texts,
**kwargs
)
return [embedding.embedding for embedding in response.data]
except APIError as e:
logger.error(f"Embedding error: {e}")
raise
def _update_usage(self, usage: Any):
if usage:
self.usage_stats['total_tokens'] += usage.total_tokens
self.usage_stats['prompt_tokens'] += usage.prompt_tokens
self.usage_stats['completion_tokens'] += usage.completion_tokens
def get_usage_stats(self) -> Dict[str, Any]:
return self.usage_stats.copy()
def estimate_cost(self, pricing: Dict[str, Dict[str, float]]) -> Dict[str, float]:
input_cost = (self.usage_stats['prompt_tokens'] / 1000) * \
pricing.get(self.config.model, {}).get('input', 0.01)
output_cost = (self.usage_stats['completion_tokens'] / 1000) * \
pricing.get(self.config.model, {}).get('output', 0.03)
return {
'input_cost': input_cost,
'output_cost': output_cost,
'total_cost': input_cost + output_cost
}
def main():
config = OpenAIConfig(
api_key=os.getenv("OPENAI_API_KEY", ""),
model="gpt-4"
)
integration = OpenAIIntegration(config)
messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain machine learning in one sentence."}
]
response = integration.chat_completion(messages)
print("Response:", response['content'])
print("Usage:", response['usage'])
print("Stats:", integration.get_usage_stats())
if __name__ == "__main__":
main()
"""
Prompt Template Management System
Manages, versions, and retrieves prompt templates
"""
import os
import json
import yaml
import logging
from typing import Dict, List, Any, Optional, Union
from pathlib import Path
from dataclasses import dataclass, asdict
from datetime import datetime
import hashlib
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
@dataclass
class PromptTemplate:
name: str
template: str
version: str
variables: List[str]
description: Optional[str] = None
metadata: Optional[Dict[str, Any]] = None
created_at: Optional[str] = None
updated_at: Optional[str] = None
def __post_init__(self):
if self.created_at is None:
self.created_at = datetime.utcnow().isoformat()
if self.updated_at is None:
self.updated_at = self.created_at
def render(self, **kwargs) -> str:
missing_vars = set(self.variables) - set(kwargs.keys())
if missing_vars:
raise ValueError(f"Missing required variables: {missing_vars}")
try:
return self.template.format(**kwargs)
except KeyError as e:
raise ValueError(f"Template rendering error: {e}")
class PromptManager:
def __init__(self, templates_dir: Union[str, Path] = "./prompt_templates"):
self.templates_dir = Path(templates_dir)
self.templates_dir.mkdir(parents=True, exist_ok=True)
self.templates: Dict[str, List[PromptTemplate]] = {}
self._load_templates()
def _load_templates(self):
for file_path in self.templates_dir.rglob("*.yaml"):
try:
with open(file_path, 'r') as f:
data = yaml.safe_load(f)
for template_data in data.get('templates', []):
template = PromptTemplate(**template_data)
if template.name not in self.templates:
self.templates[template.name] = []
self.templates[template.name].append(template)
logger.info(f"Loaded templates from {file_path}")
except Exception as e:
logger.error(f"Error loading {file_path}: {e}")
def add_template(self, template: PromptTemplate, persist: bool = True):
if template.name not in self.templates:
self.templates[template.name] = []
existing_versions = [t.version for t in self.templates[template.name]]
if template.version in existing_versions:
logger.warning(f"Version {template.version} already exists for {template.name}")
template.version = self._get_next_version(template.name)
template.updated_at = datetime.utcnow().isoformat()
self.templates[template.name].append(template)
if persist:
self._save_template(template)
logger.info(f"Added template: {template.name} v{template.version}")
def _get_next_version(self, name: str) -> str:
versions = [t.version for t in self.templates.get(name, [])]
if not versions:
return "1.0.0"
try:
latest = max(versions, key=lambda v: [int(x) for x in v.split('.')])
major, minor, patch = latest.split('.')
return f"{major}.{minor}.{int(patch) + 1}"
except:
return "1.0.0"
def _save_template(self, template: PromptTemplate):
file_path = self.templates_dir / f"{template.name}.yaml"
data = {'templates': []}
if file_path.exists():
with open(file_path, 'r') as f:
data = yaml.safe_load(f) or {'templates': []}
template_dict = asdict(template)
data['templates'].append(template_dict)
with open(file_path, 'w') as f:
yaml.dump(data, f, default_flow_style=False)
def get_template(
self,
name: str,
version: Optional[str] = None
) -> Optional[PromptTemplate]:
if name not in self.templates:
return None
if version:
for template in self.templates[name]:
if template.version == version:
return template
else:
return self.templates[name][-1]
return None
def list_templates(self, name: Optional[str] = None) -> List[Dict[str, Any]]:
if name:
templates = self.templates.get(name, [])
else:
templates = []
for template_list in self.templates.values():
templates.extend(template_list)
return [
{
'name': t.name,
'version': t.version,
'description': t.description,
'created_at': t.created_at,
'updated_at': t.updated_at
}
for t in templates
]
def delete_template(self, name: str, version: Optional[str] = None):
if name not in self.templates:
return
if version:
self.templates[name] = [t for t in self.templates[name] if t.version != version]
else:
del self.templates[name]
logger.info(f"Deleted template: {name}")
def create_default_templates(manager: PromptManager):
templates = [
PromptTemplate(
name="code_explanation",
template="Explain the following code:\n\n```\n{code}\n```\n\nFocus on: {focus}",
variables=["code", "focus"],
description="Explains code with specific focus areas",
metadata={"category": "code"}
),
PromptTemplate(
name="summarization",
template="Summarize the following text in {max_sentences} sentences:\n\n{text}",
variables=["text", "max_sentences"],
description="Summarizes text to specified length",
metadata={"category": "nlp"}
),
PromptTemplate(
name="question_answering",
template="Based on the following context:\n\n{context}\n\nAnswer the question: {question}",
variables=["context", "question"],
description="Answers questions based on provided context",
metadata={"category": "qa"}
)
]
for template in templates:
manager.add_template(template)
def main():
manager = PromptManager()
create_default_templates(manager)
template = manager.get_template("code_explanation")
if template:
rendered = template.render(
code="print('Hello, World!')",
focus="functionality and best practices"
)
print("Rendered prompt:")
print(rendered)
print("\nAvailable templates:")
for t in manager.list_templates():
print(f" - {t['name']} v{t['version']}: {t['description']}")
if __name__ == "__main__":
main()
"""
Token Usage and Cost Optimization
Tracks token usage, estimates costs, and suggests optimizations
"""
import logging
from typing import Dict, List, Any, Optional, Callable
from dataclasses import dataclass, field
from collections import defaultdict
import json
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
@dataclass
class TokenPricing:
model: str
input_price_per_1k: float
output_price_per_1k: float
@dataclass
class TokenUsage:
prompt_tokens: int
completion_tokens: int
total_tokens: int
@dataclass
class UsageRecord:
model: str
usage: TokenUsage
timestamp: str
metadata: Optional[Dict[str, Any]] = None
class TokenTracker:
def __init__(self):
self.records: List[UsageRecord] = []
self.pricing: Dict[str, TokenPricing] = {
'gpt-4': TokenPricing('gpt-4', 0.03, 0.06),
'gpt-4-turbo': TokenPricing('gpt-4-turbo', 0.01, 0.03),
'gpt-3.5-turbo': TokenPricing('gpt-3.5-turbo', 0.0005, 0.0015),
'claude-3-5-sonnet-20241022': TokenPricing('claude-3-5-sonnet-20241022', 0.003, 0.015),
'claude-3-opus-20240229': TokenPricing('claude-3-opus-20240229', 0.015, 0.075)
}
def record_usage(
self,
model: str,
usage: Dict[str, int],
metadata: Optional[Dict[str, Any]] = None
):
record = UsageRecord(
model=model,
usage=TokenUsage(
prompt_tokens=usage.get('prompt_tokens', 0),
completion_tokens=usage.get('completion_tokens', 0),
total_tokens=usage.get('total_tokens', 0)
),
timestamp=__import__('datetime').datetime.utcnow().isoformat(),
metadata=metadata or {}
)
self.records.append(record)
logger.debug(f"Recorded usage: {model} - {usage.get('total_tokens', 0)} tokens")
def get_total_tokens(self, model: Optional[str] = None) -> int:
total = 0
for record in self.records:
if model is None or record.model == model:
total += record.usage.total_tokens
return total
def get_total_cost(self, model: Optional[str] = None) -> float:
total_cost = 0.0
for record in self.records:
if model is not None and record.model != model:
continue
pricing = self.pricing.get(record.model)
if pricing:
input_cost = (record.usage.prompt_tokens / 1000) * pricing.input_price_per_1k
output_cost = (record.usage.completion_tokens / 1000) * pricing.output_price_per_1k
total_cost += input_cost + output_cost
return total_cost
def get_cost_by_model(self) -> Dict[str, float]:
costs = defaultdict(float)
for record in self.records:
pricing = self.pricing.get(record.model)
if pricing:
input_cost = (record.usage.prompt_tokens / 1000) * pricing.input_price_per_1k
output_cost = (record.usage.completion_tokens / 1000) * pricing.output_price_per_1k
costs[record.model] += input_cost + output_cost
return dict(costs)
def get_average_tokens_per_request(self, model: Optional[str] = None) -> float:
records = [r for r in self.records if model is None or r.model == model]
if not records:
return 0.0
return sum(r.usage.total_tokens for r in records) / len(records)
def get_statistics(self) -> Dict[str, Any]:
total_tokens = self.get_total_tokens()
total_cost = self.get_total_cost()
total_requests = len(self.records)
avg_tokens = 0.0
if total_requests > 0:
avg_tokens = total_tokens / total_requests
return {
'total_requests': total_requests,
'total_tokens': total_tokens,
'total_cost': total_cost,
'average_tokens_per_request': avg_tokens,
'cost_by_model': self.get_cost_by_model(),
'requests_by_model': self._count_by_model()
}
def _count_by_model(self) -> Dict[str, int]:
counts = defaultdict(int)
for record in self.records:
counts[record.model] += 1
return dict(counts)
def export_report(self, filepath: str):
report = {
'statistics': self.get_statistics(),
'records': [
{
'model': r.model,
'usage': {
'prompt_tokens': r.usage.prompt_tokens,
'completion_tokens': r.usage.completion_tokens,
'total_tokens': r.usage.total_tokens
},
'timestamp': r.timestamp,
'metadata': r.metadata
}
for r in self.records
]
}
with open(filepath, 'w') as f:
json.dump(report, f, indent=2)
logger.info(f"Exported report to {filepath}")
class TokenOptimizer:
@staticmethod
def optimize_prompt(prompt: str, target_tokens: int) -> tuple[str, Dict[str, Any]]:
approx_tokens = len(prompt.split()) * 1.3
suggestions = []
if approx_tokens > target_tokens:
suggestions.append("Reduce prompt length")
suggestions.append("Use more concise language")
suggestions.append("Remove redundant information")
suggestions.append("Use system prompt for static context")
return prompt, {
'estimated_tokens': approx_tokens,
'target_tokens': target_tokens,
'optimizations': suggestions
}
@staticmethod
def suggest_model(
tokens_needed: int,
budget: float,
complexity: str = 'medium'
) -> Dict[str, Any]:
models = [
{'name': 'gpt-3.5-turbo', 'cost_per_1k': 0.002, 'context': 16384, 'quality': 'low'},
{'name': 'gpt-4-turbo', 'cost_per_1k': 0.04, 'context': 128000, 'quality': 'high'},
{'name': 'gpt-4', 'cost_per_1k': 0.09, 'context': 8192, 'quality': 'very-high'},
{'name': 'claude-3-5-sonnet-20241022', 'cost_per_1k': 0.018, 'context': 200000, 'quality': 'high'},
{'name': 'claude-3-opus-20240229', 'cost_per_1k': 0.09, 'context': 200000, 'quality': 'very-high'}
]
suitable = []
for model in models:
if tokens_needed <= model['context']:
suitable.append(model)
suitable.sort(key=lambda m: m['cost_per_1k'])
quality_ranking = {'low': 1, 'medium': 2, 'high': 3, 'very-high': 4}
min_quality = quality_ranking.get(complexity, 2)
for model in suitable:
if quality_ranking.get(model['quality'], 0) >= min_quality:
estimated_cost = (tokens_needed / 1000) * model['cost_per_1k']
if estimated_cost <= budget:
return {
'recommended': model['name'],
'estimated_cost': estimated_cost,
'reason': 'Best fit for complexity and budget'
}
return {
'recommended': suitable[0]['name'] if suitable else 'gpt-3.5-turbo',
'estimated_cost': (tokens_needed / 1000) * suitable[0]['cost_per_1k'] if suitable else 0,
'reason': 'Best available option'
}
def main():
tracker = TokenTracker()
sample_usages = [
{'model': 'gpt-4', 'usage': {'prompt_tokens': 100, 'completion_tokens': 50, 'total_tokens': 150}},
{'model': 'gpt-3.5-turbo', 'usage': {'prompt_tokens': 200, 'completion_tokens': 100, 'total_tokens': 300}},
{'model': 'gpt-4', 'usage': {'prompt_tokens': 150, 'completion_tokens': 75, 'total_tokens': 225}},
]
for usage in sample_usages:
tracker.record_usage(**usage)
print("=== Token Usage Statistics ===")
stats = tracker.get_statistics()
print(json.dumps(stats, indent=2))
print("\n=== Model Suggestion ===")
suggestion = TokenOptimizer.suggest_model(tokens_needed=5000, budget=0.50, complexity='high')
print(json.dumps(suggestion, indent=2))
if __name__ == "__main__":
main()
"""
RAG (Retrieval-Augmented Generation) Setup Script
Handles vector database, document chunking, and retrieval
"""
import os
import logging
from typing import List, Dict, Any, Optional, Union
from pathlib import Path
from dataclasses import dataclass
import json
import yaml
try:
import chromadb
from chromadb.config import Settings
except ImportError:
raise ImportError("chromadb required: pip install chromadb")
try:
from sentence_transformers import SentenceTransformer
except ImportError:
raise ImportError("sentence-transformers required: pip install sentence-transformers")
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
@dataclass
class RAGConfig:
collection_name: str = "documents"
embedding_model: str = "all-MiniLM-L6-v2"
chunk_size: int = 512
chunk_overlap: int = 50
persist_directory: str = "./chroma_db"
top_k: int = 5
@classmethod
def from_yaml(cls, path: Union[str, Path]) -> 'RAGConfig':
with open(path, 'r') as f:
config = yaml.safe_load(f)
return cls(**config)
class DocumentChunker:
def __init__(self, chunk_size: int = 512, overlap: int = 50):
self.chunk_size = chunk_size
self.overlap = overlap
def chunk_text(self, text: str) -> List[str]:
chunks = []
start = 0
while start < len(text):
end = start + self.chunk_size
chunk = text[start:end]
if start > 0:
chunk = text[max(0, start - self.overlap):end]
chunks.append(chunk.strip())
start = end
return [c for c in chunks if c]
def chunk_documents(self, documents: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
chunked_docs = []
for doc in documents:
text = doc.get('text', '')
chunks = self.chunk_text(text)
for i, chunk in enumerate(chunks):
chunked_docs.append({
'text': chunk,
'metadata': {
**doc.get('metadata', {}),
'chunk_id': i,
'source': doc.get('source', 'unknown')
},
'id': f"{doc.get('id', 'doc')}_{i}"
})
return chunked_docs
class RAGSystem:
def __init__(self, config: RAGConfig):
self.config = config
self.chunker = DocumentChunker(config.chunk_size, config.chunk_overlap)
Path(config.persist_directory).mkdir(parents=True, exist_ok=True)
self.client = chromadb.PersistentClient(
path=config.persist_directory,
settings=Settings(anonymized_telemetry=False)
)
self.collection = self.client.get_or_create_collection(
name=config.collection_name
)
logger.info(f"Loading embedding model: {config.embedding_model}")
self.embedding_model = SentenceTransformer(config.embedding_model)
def add_documents(self, documents: List[Dict[str, Any]]):
chunked_docs = self.chunker.chunk_documents(documents)
texts = [doc['text'] for doc in chunked_docs]
embeddings = self.embedding_model.encode(texts).tolist()
self.collection.add(
embeddings=embeddings,
documents=texts,
metadatas=[doc['metadata'] for doc in chunked_docs],
ids=[doc['id'] for doc in chunked_docs]
)
logger.info(f"Added {len(chunked_docs)} chunks to collection")
def query(
self,
query_text: str,
n_results: Optional[int] = None,
where: Optional[Dict[str, Any]] = None
) -> List[Dict[str, Any]]:
if n_results is None:
n_results = self.config.top_k
query_embedding = self.embedding_model.encode([query_text]).tolist()
results = self.collection.query(
query_embeddings=query_embedding,
n_results=n_results,
where=where
)
retrieved_docs = []
for i in range(len(results['ids'][0])):
retrieved_docs.append({
'id': results['ids'][0][i],
'text': results['documents'][0][i],
'metadata': results['metadatas'][0][i],
'distance': results['distances'][0][i]
})
return retrieved_docs
def delete_documents(self, ids: List[str]):
self.collection.delete(ids=ids)
logger.info(f"Deleted {len(ids)} documents")
def get_collection_stats(self) -> Dict[str, Any]:
return {
'count': self.collection.count(),
'name': self.config.collection_name,
'embedding_model': self.config.embedding_model
}
def clear_collection(self):
self.client.delete_collection(name=self.config.collection_name)
self.collection = self.client.create_collection(name=self.config.collection_name)
logger.info("Collection cleared")
def load_documents_from_directory(directory: Union[str, Path]) -> List[Dict[str, Any]]:
documents = []
directory = Path(directory)
for file_path in directory.rglob("*.txt"):
with open(file_path, 'r', encoding='utf-8') as f:
text = f.read()
documents.append({
'id': file_path.stem,
'text': text,
'metadata': {
'source': str(file_path),
'filename': file_path.name
}
})
return documents
def main():
config = RAGConfig()
rag = RAGSystem(config)
sample_docs = [
{
'id': 'doc1',
'text': 'Machine learning is a subset of artificial intelligence that focuses on building systems that can learn from data.',
'metadata': {'category': 'ML', 'source': 'intro'}
},
{
'id': 'doc2',
'text': 'Deep learning uses neural networks with multiple layers to model complex patterns in data.',
'metadata': {'category': 'DL', 'source': 'advanced'}
}
]
rag.add_documents(sample_docs)
query = "What is machine learning?"
results = rag.query(query)
print(f"Query: {query}")
for i, result in enumerate(results, 1):
print(f"\nResult {i}:")
print(f"Text: {result['text']}")
print(f"Distance: {result['distance']:.4f}")
print(f"\nStats: {rag.get_collection_stats()}")
if __name__ == "__main__":
main()