# ── PRINCIPLE 1: Idempotent tools ────────────────────
# If the agent calls a tool twice with the same args, the result should be the same
# and no duplicate side effects should occur

# BAD: calling twice creates two records
def create_ticket(title: str, description: str) -> dict:
    return db.insert("tickets", {"title": title, "description": description})

# GOOD: upsert on a natural key — safe to call multiple times
def create_or_get_ticket(title: str, description: str) -> dict:
    existing = db.find_one("tickets", {"title": title})
    if existing:
        return existing
    return db.insert("tickets", {"title": title, "description": description})

# ── PRINCIPLE 2: Explicit error contracts ────────────
# Never raise exceptions — return structured errors the agent can understand

# BAD: agent receives an unhandled exception, gets confused
def get_user(user_id: str) -> dict:
    return db.get("users", user_id)   # raises KeyError if not found

# GOOD: structured error the agent can reason about
def get_user(user_id: str) -> dict:
    user = db.find_one("users", {"id": user_id})
    if not user:
        return {"error": "USER_NOT_FOUND",
                "message": f"No user with id '{user_id}'",
                "suggestion": "Try searching by email with search_users()"}
    return {"success": True, "user": user}

# ── PRINCIPLE 3: Atomic operations ───────────────────
# One tool should do ONE thing — not a chain of things

# BAD: one tool does too much — partial failures are unrecoverable
def process_order(order_id: str) -> dict:
    validate_stock()
    charge_payment()
    send_confirmation_email()
    update_inventory()

# GOOD: separate tools, agent orchestrates the sequence
def validate_stock(items: list) -> dict: ...
def charge_payment(amount: float, card_id: str) -> dict: ...
def send_confirmation_email(order_id: str, email: str) -> dict: ...
def update_inventory(items: list, delta: int) -> dict: ...

import asyncio, anthropic

async_client = anthropic.AsyncAnthropic()

async def call_llm_async(system: str, user: str) -> str:
    response = await async_client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        messages=[{"role": "user", "content": user}],
        system=system
    )
    return response.content[0].text

# ── Pattern 1: Same input, multiple perspectives ──────
async def multi_perspective_review(code: str) -> dict:
    security, performance, readability = await asyncio.gather(
        call_llm_async("Review this code for security vulnerabilities only.", code),
        call_llm_async("Review this code for performance issues only.", code),
        call_llm_async("Review this code for readability and maintainability only.", code),
    )
    # Synthesise all three perspectives
    synthesis = await call_llm_async(
        "Combine these three code reviews into a single prioritised action list.",
        f"Security:\n{security}\n\nPerformance:\n{performance}\n\nReadability:\n{readability}"
    )
    return {"security": security, "performance": performance,
            "readability": readability, "synthesis": synthesis}

# ── Pattern 2: Different inputs, same processing ──────
async def process_documents_parallel(documents: list[str]) -> list[str]:
    summaries = await asyncio.gather(
        *[call_llm_async("Summarise in 2 sentences.", doc) for doc in documents]
    )
    return list(summaries)

# ── Pattern 3: Voting — run N times, take majority ────
async def classify_with_voting(text: str, n: int = 3) -> str:
    from collections import Counter
    labels = await asyncio.gather(
        *[call_llm_async(
            "Classify as POSITIVE, NEGATIVE, or NEUTRAL. Reply with one word only.", text
          ) for _ in range(n)]
    )
    labels = [l.strip().upper() for l in labels]
    return Counter(labels).most_common(1)[0][0]

# ── Handling partial failures ──────────────────────────
async def gather_with_fallback(coroutines: list) -> list:
    results = await asyncio.gather(*coroutines, return_exceptions=True)
    processed = []
    for r in results:
        if isinstance(r, Exception):
            processed.append({"error": str(r)})
        else:
            processed.append(r)
    return processed

from pydantic import BaseModel
from typing import List, Literal
import instructor, anthropic, asyncio

instr_client = instructor.from_anthropic(anthropic.Anthropic())

class SubTask(BaseModel):
    agent:       Literal["researcher", "analyst", "writer"]
    task:        str
    depends_on:  List[int] = []   # indices of tasks that must complete first

class OrchestratorPlan(BaseModel):
    goal_summary: str
    subtasks:    List[SubTask]

def orchestrate(user_goal: str) -> str:
    # 1. Orchestrator plans the work
    plan = instr_client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        messages=[{"role": "user", "content":
            f"""Break this goal into subtasks for specialised agents:
Goal: {user_goal}

Available agents:
- researcher: searches web, finds facts, gathers data
- analyst: processes data, identifies patterns, creates structured analysis
- writer: synthesises research and analysis into coherent written output"""}],
        response_model=OrchestratorPlan
    )

    results = {}

    # 2. Execute subtasks in dependency order
    for i, subtask in enumerate(plan.subtasks):
        # Wait for dependencies
        context = "\n\n".join(
            f"Result from task {j}: {results[j]}"
            for j in subtask.depends_on if j in results
        )

        # Dispatch to specialised subagent
        AGENT_SYSTEMS = {
            "researcher": "You are a researcher. Find accurate information. Cite sources.",
            "analyst":   "You are an analyst. Process data systematically. Be precise.",
            "writer":    "You are a technical writer. Write clearly for the target audience.",
        }
        task_with_context = subtask.task
        if context:
            task_with_context = f"Prior results:\n{context}\n\nYour task: {subtask.task}"

        results[i] = run_agent(
            user_message=task_with_context,
            system=AGENT_SYSTEMS[subtask.agent]
        )

    # 3. Final synthesis
    all_results = "\n\n".join(f"Task {i}: {r}" for i, r in results.items())
    return run_agent(
        user_message=f"Goal: {user_goal}\n\nAll subtask results:\n{all_results}\n\nSynthesize into a complete answer.",
        system="You are a senior analyst. Synthesise all results into a coherent, complete response."
    )