feat: add Tavily search tool and research-agent support

[superresistant]

Summary

Adds a new search tool backed by the Tavily API for web search capabilities. This enables creating research-focused agents that can search the web and cite sources.

Changes

New Files

• code_puppy/tools/search_tool.py - Tavily API integration with:

  • Pydantic models for structured results (SearchResult, SearchOutput)
  • Search parameters: search_depth, topic, time_range, domain allow/deny lists
  • Response caching with configurable TTL (1 hour default)
  • Retry with exponential backoff on 429/5xx errors
  • Custom exceptions: MissingApiKey, RateLimited, UpstreamError

• tests/tools/test_search_tool.py - Unit tests covering:

  • HTTP request success/failure scenarios
  • Cache round-trip functionality
  • Parameter validation and clamping
  • Domain sanitization

Modified Files

• code_puppy/tools/__init__.py - Register search in tool registry
• README.md - Usage docs for Research Agent
• AGENTS.md - Added search to available tools list
• .env.example - Added SEARCH_API_KEY template

Usage

# Set API key
export SEARCH_API_KEY="tvly-..."

# Use with research-agent (JSON agent in ~/.code_puppy/agents/)
python -m code_puppy --agent research-agent "What is Tavily? Cite sources."

Example JSON Agent (~/.code_puppy/agents/research-agent.json):

{
  "name": "research-agent",
  "display_name": "Research Agent",
  "description": "Diligent researcher that searches the web and summarizes with citations",
  "tools": ["search", "list_files", "read_file", "agent_share_your_reasoning"],
  "system_prompt": [
    "You are an expert Technical Research Assistant.",
    "Objective: gather factual, publicly available information to answer user queries accurately.",
    "Protocol:",
    "1) Analyze the question and craft precise search queries.",
    "2) Use the search tool; do not guess URLs.",
    "3) Evaluate snippets; refine the query if evidence is weak.",
    "4) Use search parameters when needed: search_depth=advanced for deep research, topic=news + time_range for recency, include_domains/exclude_domains for source quality.",
    "5) Summarize findings clearly.",
    "6) Cite sources as [Title](URL) inline with claims."
  ]
}

Testing

uv run pytest tests/tools/test_search_tool.py -v
# 9 passed ✅

Checklist

• Code follows project style (ruff check/format passed)
• Tests added and passing
• Documentation updated (README, AGENTS.md, .env.example)
• No breaking changes