# ReAct agent loop
def react_agent(question, tools, llm, max_steps=10):
    """Simple ReAct loop."""
    history = [{"role": "user", "content": question}]
    
    for step in range(max_steps):
        # Think
        thought = llm.chat(history + [{
            "role": "system",
            "content": f"Available tools: {[t.name for t in tools]}\n"
                      f"Think step by step. What should you do next?"
        }])
        
        # Check if done
        if "FINAL ANSWER:" in thought:
            return thought.replace("FINAL ANSWER:", "").strip()
        
        # Act
        action = parse_action(thought)  # e.g., {"tool": "search", "query": "..."}
        tool = next(t for t in tools if t.name == action["tool"])
        observation = tool.run(action["query"])
        
        history.append({"role": "assistant", "content": thought})
        history.append({"role": "user", "content": f"Observation: {observation}"})
    
    return "Maximum steps reached without final answer"

# Plan-and-execute agent
def plan_and_execute_agent(question, tools, llm):
    """Agent that plans first, then executes."""
    
    # Step 1: Create plan
    plan = llm.chat(f"""Create a step-by-step plan to answer: {question}
    
Available tools: {[t.name for t in tools]}
    
Return JSON: {{"steps": ["step 1 description", "step 2 description", ...]}}""")
    
    steps = parse_plan(plan)
    results = []
    
    # Step 2: Execute each step
    for i, step in enumerate(steps):
        # Find appropriate tool for this step
        tool = select_tool(step, tools)
        
        # Execute with context from previous steps
        result = tool.run(step, context=results)
        results.append({"step": step, "result": result})
        
        # Optional: Replan if needed
        if needs_replan(results, question):
            steps = replan(question, results, llm)
    
    # Step 3: Synthesize final answer
    return synthesize(question, results, llm)

# Multi-agent coordinator
class MultiAgentSystem:
    def __init__(self):
        self.agents = {
            "researcher": ResearchAgent(),
            "analyst": AnalysisAgent(),
            "writer": WritingAgent(),
        }
        self.coordinator = CoordinatorAgent()
    
    def process(self, task):
        # Coordinator breaks task into sub-tasks
        sub_tasks = self.coordinator.decompose(task)
        
        results = {}
        for sub_task in sub_tasks:
            # Route to appropriate agent
            agent_name = self.coordinator.route(sub_task)
            agent = self.agents[agent_name]
            
            # Execute with context from previous results
            result = agent.execute(sub_task, context=results)
            results[agent_name] = result
        
        # Coordinator synthesizes final answer
        return self.coordinator.synthesize(task, results)

# Good tool design
class Tool:
    """Base tool class with clear interface."""
    
    name: str           # Human-readable name
    description: str    # What it does (used by LLM for tool selection)
    parameters: dict    # JSON schema for inputs
    returns: str        # Description of output
    
    def run(self, **kwargs) -> ToolResult:
        """Execute the tool. Returns structured result."""
        pass
    
    def validate(self, **kwargs) -> bool:
        """Validate inputs before execution."""
        pass


# Example: Well-designed tool
class StockPriceTool(Tool):
    name = "get_stock_price"
    description = "Get current stock price and daily change for a ticker symbol"
    parameters = {
        "ticker": {"type": "string", "description": "Stock ticker symbol (e.g., AAPL)"},
        "include_history": {"type": "boolean", "description": "Include 30-day history", "default": False},
    }
    returns = "JSON with current price, change, and optional history"
    
    def run(self, ticker: str, include_history: bool = False) -> ToolResult:
        # Validate
        if not ticker.isalnum():
            return ToolResult(success=False, content="Invalid ticker symbol")
        
        # Execute
        price = fetch_price(ticker)
        history = fetch_history(ticker, days=30) if include_history else None
        
        return ToolResult(
            success=True,
            content=json.dumps({"price": price, "history": history}),
            metadata={"ticker": ticker, "timestamp": datetime.now().isoformat()}
        )

# 1. Data Retrieval Tools
tools = [
    VectorSearchTool(),      # Search knowledge base
    SQLQueryTool(),          # Query database
    APICallTool(),           # Call external API
    WebSearchTool(),         # Search the web
]

# 2. Computation Tools
tools = [
    CalculatorTool(),        # Math operations
    CodeExecutionTool(),     # Run Python code
    DataAnalysisTool(),      # Pandas operations
]

# 3. Action Tools
tools = [
    EmailTool(),             # Send emails
    FileWriteTool(),         # Create/modify files
    WebhookTool(),           # Trigger webhooks
]

# 4. Communication Tools
tools = [
    HumanEscalationTool(),   # Ask human for help
    NotificationTool(),      # Send notifications
    TranslationTool(),       # Translate text
]

# 1. Working Memory (current conversation)
class WorkingMemory:
    def __init__(self, max_tokens=4000):
        self.messages = []
        self.max_tokens = max_tokens
    
    def add(self, message):
        self.messages.append(message)
        self._trim()
    
    def _trim(self):
        """Remove old messages when exceeding token limit."""
        while self.token_count() > self.max_tokens:
            self.messages.pop(0)  # Remove oldest
    
    def get_context(self):
        return self.messages


# 2. Long-term Memory (across conversations)
class LongTermMemory:
    def __init__(self, vector_store, embedding_model):
        self.vector_store = vector_store
        self.embedding_model = embedding_model
    
    def store(self, key_info, metadata=None):
        """Store important information for later retrieval."""
        embedding = self.embedding_model.embed(key_info)
        self.vector_store.add(
            embedding=embedding,
            text=key_info,
            metadata=metadata or {}
        )
    
    def recall(self, query, k=5):
        """Retrieve relevant memories."""
        embedding = self.embedding_model.embed(query)
        return self.vector_store.search(embedding, k=k)


# 3. Episodic Memory (past experiences)
class EpisodicMemory:
    def __init__(self, db):
        self.db = db
    
    def store_episode(self, task, action, result, outcome):
        """Store a complete task episode for learning."""
        self.db.insert({
            "task": task,
            "action": action,
            "result": result,
            "outcome": outcome,
            "timestamp": datetime.now()
        })
    
    def find_similar_episodes(self, task, k=3):
        """Find past episodes similar to current task."""
        # Use embeddings to find similar tasks
        pass
    
    def extract_lessons(self, episodes):
        """Extract patterns and lessons from past episodes."""
        pass

def chain_of_thought(question, llm):
    """Simple CoT planning."""
    prompt = f"""Think step by step to answer: {question}

1. First, I need to understand...
2. Then, I should check...
3. Next, I need to compute...
4. Finally, I can conclude...

Step-by-step plan:"""
    
    return llm.generate(prompt)

def tree_of_thought(question, llm, num_branches=3):
    """Explore multiple reasoning paths."""
    
    # Generate multiple initial thoughts
    thoughts = []
    for i in range(num_branches):
        thought = llm.generate(f"""
        Generate a unique approach to answer: {question}
        Approach {i+1}:""")
        thoughts.append(thought)
    
    # Evaluate each thought
    scores = []
    for thought in thoughts:
        score = llm.generate(f"""
        Rate this reasoning approach (1-10):
        {thought}
        
        Score:""")
        scores.append(float(score))
    
    # Expand the best thought
    best_thought = thoughts[scores.index(max(scores))]
    
    # Continue reasoning from best path
    return continue_reasoning(best_thought, question, llm)

def rewoo_planner(question, tools, llm):
    """Plan all steps before executing any."""
    
    plan_prompt = f"""Create a complete plan to answer: {question}

Available tools: {[(t.name, t.description) for t in tools]}

Plan format:
- Step 1: [Tool] Input → Variable #1
- Step 2: [Tool] Input (using #1) → Variable #2
- ...

Plan:"""
    
    plan = llm.generate(plan_prompt)
    steps = parse_plan(plan)
    
    # Execute all steps
    variables = {}
    for step in steps:
        # Substitute variables
        input_text = substitute_variables(step.input, variables)
        
        # Execute tool
        tool = get_tool(step.tool_name)
        result = tool.run(input_text)
        
        # Store result
        variables[step.variable] = result
    
    # Generate final answer
    return llm.generate(f"""
    Question: {question}
    
    Evidence:
    {format_variables(variables)}
    
    Answer:""")

EVALUATION_DIMENSIONS = {
    "Task Completion": {
        "success_rate": "Percentage of tasks completed successfully",
        "accuracy": "Correctness of outputs",
        "completeness": "All requirements met",
    },
    "Efficiency": {
        "steps_taken": "Number of steps to complete task",
        "tool_calls": "Number of API/tool calls made",
        "latency": "Time to completion",
        "cost": "API costs per task",
    },
    "Safety": {
        "hallucination_rate": "Fabricated information rate",
        "safety_violations": "Unsafe actions attempted",
        "data_leakage": "Sensitive data exposed",
    },
    "User Experience": {
        "response_quality": "Human rating of output quality",
        "clarity": "How clear is the response",
        "helpfulness": "Does it actually help the user",
    },
}

class AgentEvaluator:
    def __init__(self, agent, test_cases):
        self.agent = agent
        self.test_cases = test_cases
    
    def evaluate(self):
        results = []
        
        for test in self.test_cases:
            # Run agent
            start_time = time.time()
            output = self.agent.query(test["question"])
            latency = time.time() - start_time
            
            # Measure metrics
            metrics = {
                "task_id": test["id"],
                "question": test["question"],
                "expected": test["expected_answer"],
                "actual": output["answer"],
                "latency": latency,
                "steps": output.get("iterations", 1),
                "tool_calls": output.get("tool_calls", 0),
            }
            
            # Automated scoring
            metrics["accuracy"] = self.score_accuracy(
                output["answer"], test["expected_answer"]
            )
            metrics["relevance"] = self.score_relevance(
                output["answer"], test["question"]
            )
            
            results.append(metrics)
        
        return self.summarize(results)
    
    def score_accuracy(self, actual, expected):
        """Score how accurate the answer is."""
        prompt = f"""Rate the accuracy of this answer (0-1):
        
        Expected: {expected}
        Actual: {actual}
        
        Score (0-1):"""
        
        return float(self.llm.generate(prompt))

HUMAN_EVAL_TEMPLATE = {
    "question": "The user asked: {question}",
    "agent_response": "The agent responded: {response}",
    "criteria": [
        {"name": "Accuracy", "scale": "1-5", "description": "Is the information correct?"},
        {"name": "Completeness", "scale": "1-5", "description": "Does it fully answer the question?"},
        {"name": "Clarity", "scale": "1-5", "description": "Is it easy to understand?"},
        {"name": "Helpfulness", "scale": "1-5", "description": "Does it actually help the user?"},
    ]
}

PRODUCTION_INFRASTRUCTURE = {
    "API Layer": {
        "FastAPI": "REST API with auto-docs",
        "Authentication": "API key or OAuth2",
        "Rate Limiting": "Per-user, per-endpoint",
        "CORS": "Configure for your frontend",
    },
    "Agent Runtime": {
        "Container": "Docker with health checks",
        "Scaling": "Horizontal via Kubernetes",
        "Queue": "Celery or Redis for async tasks",
        "Timeout": "Per-request timeout limits",
    },
    "Data Layer": {
        "Vector DB": "Pinecone/Weaviate with backups",
        "Cache": "Redis for repeated queries",
        "Database": "PostgreSQL for metadata",
        "Storage": "S3 for documents",
    },
    "Monitoring": {
        "Metrics": "Prometheus + Grafana",
        "Logging": "Structured JSON logs",
        "Tracing": "LangSmith or OpenTelemetry",
        "Alerting": "PagerDuty integration",
    },
    "Security": {
        "Input Validation": "Sanitize all user inputs",
        "Output Filtering": "Check for PII, harmful content",
        "Sandboxing": "Isolate code execution",
        "Audit Logging": "Track all agent actions",
    },
}

# Cost optimization strategies
COST_OPTIMIZATION = {
    "Model Routing": {
        "simple_queries": "Use GPT-4o-mini ($0.15/1M tokens)",
        "complex_queries": "Use GPT-4o ($5/1M tokens)",
        "routing_logic": "Use embeddings to classify complexity",
    },
    "Caching": {
        "semantic_cache": "Cache similar queries (Redis + embeddings)",
        "exact_cache": "Cache identical queries",
        "tool_cache": "Cache API responses with TTL",
    },
    "Token Optimization": {
        "prompt_compression": "Remove redundant text from prompts",
        "context_limiting": "Only include relevant context",
        "chunk_summarization": "Summarize long retrieved chunks",
    },
    "Batch Processing": {
        "batch_embeddings": "Batch API calls for embeddings",
        "background_jobs": "Process non-urgent tasks in background",
    },
}

class CustomerSupportAgent:
    """Template for customer support automation."""
    
    def __init__(self):
        self.tools = [
            TicketSearchTool(),      # Search past tickets
            KnowledgeBaseTool(),     # Search docs/FAQ
            OrderLookupTool(),       # Look up customer orders
            EscalationTool(),        # Escalate to human
        ]
        
        self.system_prompt = """You are a customer support agent.
        
Guidelines:
1. First, search the knowledge base for answers
2. If not found, search past tickets for similar issues
3. If still not found, escalate to human support
4. Always be empathetic and professional
5. Never make up answers — say "I need to escalate this"

Escalate when:
- Customer is angry or frustrated
- Issue involves billing disputes
- Technical issue you can't resolve
- Any request you're unsure about
"""

class ResearchAgent:
    """Template for research and analysis."""
    
    def __init__(self):
        self.tools = [
            WebSearchTool(),
            ArxivSearchTool(),
            SemanticScholarTool(),
            PDFReaderTool(),
            NoteTakingTool(),
        ]
        
        self.system_prompt = """You are a research assistant.
        
Research process:
1. Understand the research question
2. Search for relevant papers and articles
3. Read and extract key findings
4. Synthesize information from multiple sources
5. Cite all sources properly

Quality standards:
- Always verify claims with multiple sources
- Distinguish between facts and opinions
- Note any conflicting information
- Provide balanced perspectives
"""

class CodeAssistantAgent:
    """Template for code generation and debugging."""
    
    def __init__(self):
        self.tools = [
            CodeExecutionTool(sandbox=True),  # Sandboxed execution
            FileReadTool(),
            FileWriteTool(),
            GitTool(),
            LinterTool(),
            TestRunnerTool(),
        ]
        
        self.system_prompt = """You are a coding assistant.
        
Coding process:
1. Understand the requirement
2. Plan the approach
3. Write code
4. Test the code
5. Fix any issues

Standards:
- Always write tests
- Handle edge cases
- Follow language conventions
- Add comments for complex logic
- Never execute untrusted code without sandboxing
"""

PITFALLS = {
    "Too many tools": {
        "problem": "LLM gets confused about which tool to use",
        "solution": "Limit to 5-10 well-defined tools, use tool descriptions",
    },
    "Infinite loops": {
        "problem": "Agent keeps retrying without progress",
        "solution": "Set max iterations, track progress, detect stagnation",
    },
    "Hallucination": {
        "problem": "Agent makes up information",
        "solution": "Force citation, use Self-RAG, validate against knowledge base",
    },
    "Cost explosion": {
        "problem": "Agent makes too many API calls",
        "solution": "Set token budgets, use model routing, implement caching",
    },
    "Safety violations": {
        "problem": "Agent takes unsafe actions",
        "solution": "Sandbox execution, input validation, output filtering",
    },
    "Context overflow": {
        "problem": "Context window exceeded",
        "solution": "Implement context compression, sliding window, summarization",
    },
}