Stage 2: Implement tool development with retry logic and error handling

Implemented 4 core tools with comprehensive test coverage:

**Tools Added:**
- web_search.py: Tavily/Exa search with fallback (10 tests)
- file_parser.py: PDF/Excel/Word/Text parsing (19 tests)
- calculator.py: Safe math eval with security (41 tests)
- vision.py: Multimodal image analysis (15 tests)

**Features:**
- Retry logic with tenacity (exponential backoff, 3 max retries)
- Comprehensive error handling and logging
- Tool registry in __init__.py with metadata
- 85 passing tests total

**Integration:**
- Updated graph.py execute_node to load tool registry
- Added TOOLS dict for Stage 3 dynamic tool selection
- Maintained Stage 1 compatibility

**Testing:**
- Created test fixtures for all file types
- Mock API testing for web search and vision
- Security testing for calculator (prevents code injection)
- All 91 tests passing (6 agent + 85 tool tests)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

PLAN.md

@@ -1,8 +1,300 @@
-# Implementation Plan
+# Implementation Plan - Stage 2: Tool Development
 
-**Status:** Ready for next stage
-**Last Updated:** 2026-01-02
+**Date:** 2026-01-02
+**Dev Record:** TBD (will create dev_260102_##_stage2_tool_development.md)
+**Status:** In Progress
 
----
+## Objective
 
-Stage 1 completed. Planning for next stage will be documented here.
+Implement 4 core tools (web search, file parsing, calculator, multimodal vision) with retry logic and error handling, following Level 5 (Component Selection) and Level 6 (Implementation Framework) architectural decisions. Each tool must be independently testable and integrate seamlessly with the LangGraph StateGraph.
+
+## Steps
+
+### Step 1: Web Search Tool Implementation
+
+**1.1 Create src/tools/web_search.py**
+
+- Implement `tavily_search(query: str, max_results: int = 5) -> dict` function
+- Implement `exa_search(query: str, max_results: int = 5) -> dict` function (fallback)
+- Use Settings.get_search_api_key() for API key retrieval
+- Return structured results: {results: [{title, url, snippet}], source: "tavily"|"exa"}
+
+**1.2 Add retry logic with exponential backoff**
+
+- Use `tenacity` library for retry decorator
+- Retry on connection errors, timeouts, rate limits
+- Max 3 retries with 2^n second delays
+- Fallback from Tavily to Exa if Tavily fails after retries
+
+**1.3 Error handling**
+
+- Catch API errors and return meaningful error messages
+- Handle empty results gracefully
+- Log all errors for debugging
+
+**1.4 Create tests/test_web_search.py**
+
+- Test Tavily search with mock API
+- Test Exa search with mock API
+- Test retry logic (simulate failures)
+- Test fallback mechanism
+- Test error handling
+
+### Step 2: File Parsing Tool Implementation
+
+**2.1 Create src/tools/file_parser.py**
+
+- Implement `parse_pdf(file_path: str) -> str` using PyPDF2
+- Implement `parse_excel(file_path: str) -> dict` using openpyxl
+- Implement `parse_docx(file_path: str) -> str` using python-docx
+- Implement `parse_image_text(image_path: str) -> str` using Pillow + OCR (optional)
+- Generic `parse_file(file_path: str) -> dict` dispatcher based on extension
+
+**2.2 Add retry logic for file operations**
+
+- Retry on file read errors (network issues, temporary locks)
+- Max 3 retries with exponential backoff
+
+**2.3 Error handling**
+
+- Handle file not found errors
+- Handle corrupted file errors
+- Handle unsupported format errors
+- Return structured error responses
+
+**2.4 Create tests/test_file_parser.py**
+
+- Create test fixtures (sample PDF, Excel, Word files in tests/fixtures/)
+- Test each parser function independently
+- Test error handling for missing files
+- Test error handling for corrupted files
+
+### Step 3: Calculator Tool Implementation
+
+**3.1 Create src/tools/calculator.py**
+
+- Implement `safe_eval(expression: str) -> dict` using ast.literal_eval
+- Support basic arithmetic operations (+, -, *, /, **, %)
+- Support mathematical functions (sin, cos, sqrt, etc.) via math module
+- Return structured result: {result: float|int, expression: str}
+
+**3.2 Add safety checks**
+
+- Whitelist allowed operations (no exec, eval, import)
+- Validate expression before evaluation
+- Set execution timeout (prevent infinite loops)
+- Limit expression complexity (prevent DoS)
+
+**3.3 Error handling**
+
+- Handle syntax errors
+- Handle division by zero
+- Handle invalid operations
+- Return meaningful error messages
+
+**3.4 Create tests/test_calculator.py**
+
+- Test basic arithmetic (2+2, 10*5, etc.)
+- Test mathematical functions (sqrt(16), sin(0), etc.)
+- Test error handling (division by zero, invalid syntax)
+- Test safety checks (block dangerous operations)
+
+### Step 4: Multimodal Vision Tool Implementation
+
+**4.1 Create src/tools/vision.py**
+
+- Implement `analyze_image(image_path: str, question: str) -> str`
+- Use LLM's native vision capabilities (Gemini/Claude)
+- Load image, encode to base64
+- Send to vision-capable LLM with question
+- Return description/answer
+
+**4.2 Add retry logic**
+
+- Retry on API errors
+- Max 3 retries with exponential backoff
+
+**4.3 Error handling**
+
+- Handle image loading errors
+- Handle unsupported image formats
+- Handle API errors
+- Return structured responses
+
+**4.4 Create tests/test_vision.py**
+
+- Create test image fixtures
+- Test image analysis with mock LLM
+- Test error handling
+- Test retry logic
+
+### Step 5: Tool Integration with StateGraph
+
+**5.1 Update src/tools/__init__.py**
+
+- Export all tool functions
+- Create unified tool registry: `TOOLS = {name: function}`
+- Add tool metadata (description, parameters, return type)
+
+**5.2 Update src/agent/graph.py execute_node**
+
+- Replace placeholder with actual tool execution
+- Parse tool calls from plan
+- Execute tools with error handling
+- Collect results
+- Return updated state with tool results
+
+**5.3 Add tool execution wrapper**
+
+- Implement `execute_tool(tool_name: str, **kwargs) -> dict`
+- Add logging for tool calls
+- Add timeout enforcement
+- Add result validation
+
+### Step 6: Configuration and Settings Updates
+
+**6.1 Update src/config/settings.py**
+
+- Add tool-specific settings (timeouts, max retries, etc.)
+- Add tool feature flags (enable/disable specific tools)
+- Add result size limits
+
+**6.2 Update .env.example**
+
+- Document any new environment variables
+- Add tool-specific configuration examples
+
+### Step 7: Integration Testing
+
+**7.1 Create tests/test_tools_integration.py**
+
+- Test all tools working together
+- Test tool execution from StateGraph
+- Test error propagation
+- Test retry mechanisms across all tools
+
+**7.2 Create test_stage2.py**
+
+- End-to-end test with real tool calls
+- Verify StateGraph executes tools correctly
+- Verify results are returned to state
+- Verify errors are handled gracefully
+
+### Step 8: Documentation and Deployment
+
+**8.1 Update requirements.txt**
+
+- Ensure all tool dependencies are included
+- Add tenacity for retry logic
+
+**8.2 Local testing**
+
+- Run all test suites
+- Test with Gradio UI
+- Verify no regressions from Stage 1
+
+**8.3 Deploy to HF Spaces**
+
+- Push changes
+- Verify build succeeds
+- Test tools in deployed environment
+
+## Files to Modify
+
+**New files to create:**
+
+- `src/tools/web_search.py` - Tavily/Exa search implementation
+- `src/tools/file_parser.py` - PDF/Excel/Word/Image parsing
+- `src/tools/calculator.py` - Safe expression evaluation
+- `src/tools/vision.py` - Multimodal image analysis
+- `tests/test_web_search.py` - Web search tests
+- `tests/test_file_parser.py` - File parser tests
+- `tests/test_calculator.py` - Calculator tests
+- `tests/test_vision.py` - Vision tests
+- `tests/test_tools_integration.py` - Integration tests
+- `tests/test_stage2.py` - Stage 2 end-to-end tests
+- `tests/fixtures/` - Test files directory
+
+**Existing files to modify:**
+
+- `src/tools/__init__.py` - Export all tools, create tool registry
+- `src/agent/graph.py` - Update execute_node to use real tools
+- `src/config/settings.py` - Add tool-specific settings
+- `.env.example` - Document new configuration (if any)
+- `requirements.txt` - Add tenacity for retry logic
+
+**Files NOT to modify:**
+
+- `src/agent/graph.py` plan_node - Defer to Stage 3
+- `src/agent/graph.py` answer_node - Defer to Stage 3
+- Planning/reasoning logic - Defer to Stage 3
+
+## Success Criteria
+
+### Functional Requirements
+
+- [ ] Web search tool returns valid results from Tavily
+- [ ] Web search falls back to Exa when Tavily fails
+- [ ] File parser handles PDF, Excel, Word files correctly
+- [ ] Calculator evaluates mathematical expressions safely
+- [ ] Vision tool analyzes images using LLM vision capabilities
+- [ ] All tools have retry logic with exponential backoff
+- [ ] All tools handle errors gracefully
+- [ ] Tools integrate with StateGraph execute_node
+
+### Technical Requirements
+
+- [ ] All tool functions return structured dict responses
+- [ ] Retry logic uses tenacity with max 3 retries
+- [ ] Error messages are clear and actionable
+- [ ] All tools have comprehensive test coverage (>80%)
+- [ ] No unsafe code execution in calculator
+- [ ] Tool timeouts enforced to prevent hangs
+
+### Validation Checkpoints
+
+- [ ] **Checkpoint 1:** Web search tool working with tests passing
+- [ ] **Checkpoint 2:** File parser working with tests passing
+- [ ] **Checkpoint 3:** Calculator working with tests passing
+- [ ] **Checkpoint 4:** Vision tool working with tests passing
+- [ ] **Checkpoint 5:** All tools integrated with StateGraph
+- [ ] **Checkpoint 6:** Integration tests passing
+- [ ] **Checkpoint 7:** Deployed to HF Spaces successfully
+
+### Non-Goals for Stage 2
+
+- ❌ Implementing planning logic (Stage 3)
+- ❌ Implementing answer synthesis (Stage 3)
+- ❌ Optimizing tool selection strategy (Stage 3)
+- ❌ Advanced error recovery beyond retries (Stage 4)
+- ❌ Performance optimization (Stage 5)
+
+## Dependencies & Risks
+
+**Dependencies:**
+
+- Tavily API key (free tier: 1000 req/month)
+- Exa API key (paid tier, fallback)
+- LLM vision API access (Gemini/Claude)
+- Test fixtures (sample files for parsing)
+
+**Risks:**
+
+- **Risk:** API rate limits during testing
+  - **Mitigation:** Use mocks for unit tests, real APIs only for integration tests
+- **Risk:** File parsing fails on edge cases
+  - **Mitigation:** Comprehensive test fixtures covering various formats
+- **Risk:** Calculator security vulnerabilities
+  - **Mitigation:** Strict whitelisting, no eval/exec, use AST parsing only
+- **Risk:** Tool timeout issues on slow networks
+  - **Mitigation:** Configurable timeouts, retry logic
+
+## Next Steps After Stage 2
+
+Once Stage 2 Success Criteria met:
+
+1. Create Stage 3 plan (Core Agent Logic - Planning & Reasoning)
+2. Implement plan_node with tool selection strategy
+3. Implement answer_node with result synthesis
+4. Test end-to-end agent behavior
+5. Proceed to Stage 4 (Integration & Robustness)

TODO.md

@@ -1,14 +1,71 @@
-# TODO List
+# TODO - Stage 2: Tool Development
 
-**Session Date:** [YYYY-MM-DD]
-**Dev Record:** [link to dev/dev_YYMMDD_##_concise_title.md]
+**Created:** 2026-01-02
+**Plan:** PLAN.md (Stage 2: Tool Development)
+**Status:** Ready for execution
 
-## Active Tasks
+## Task List
 
-- [ ] [Task 1]
-- [ ] [Task 2]
-- [ ] [Task 3]
+### Step 1: Web Search Tool
+- [ ] Create `src/tools/web_search.py` with Tavily and Exa search functions
+- [ ] Add retry logic with tenacity decorator (max 3 retries, exponential backoff)
+- [ ] Implement fallback mechanism (Tavily → Exa)
+- [ ] Add error handling and logging
+- [ ] Create `tests/test_web_search.py` with mock API tests
+- [ ] Test retry logic and fallback mechanism
 
-## Completed Tasks
+### Step 2: File Parsing Tool
+- [ ] Create `src/tools/file_parser.py` with PDF/Excel/Word parsers
+- [ ] Implement generic `parse_file()` dispatcher
+- [ ] Add retry logic for file operations
+- [ ] Add error handling for missing/corrupted files
+- [ ] Create test fixtures in `tests/fixtures/`
+- [ ] Create `tests/test_file_parser.py` with parser tests
 
-- [x] [Completed task 1]
+### Step 3: Calculator Tool
+- [ ] Create `src/tools/calculator.py` with safe_eval function
+- [ ] Implement safety checks (whitelist operations, timeout, complexity limits)
+- [ ] Add error handling for syntax/division errors
+- [ ] Create `tests/test_calculator.py` with arithmetic and safety tests
+
+### Step 4: Vision Tool
+- [ ] Create `src/tools/vision.py` with image analysis function
+- [ ] Implement image loading and base64 encoding
+- [ ] Integrate with LLM vision API (Gemini/Claude)
+- [ ] Add retry logic for API errors
+- [ ] Create test image fixtures
+- [ ] Create `tests/test_vision.py` with mock LLM tests
+
+### Step 5: StateGraph Integration
+- [ ] Update `src/tools/__init__.py` to export all tools
+- [ ] Create unified tool registry with metadata
+- [ ] Update `src/agent/graph.py` execute_node to use real tools
+- [ ] Implement `execute_tool()` wrapper with logging and timeout
+- [ ] Test tool execution from StateGraph
+
+### Step 6: Configuration Updates
+- [ ] Update `src/config/settings.py` with tool-specific settings
+- [ ] Add tool feature flags and timeouts
+- [ ] Update `.env.example` with new configuration (if needed)
+
+### Step 7: Integration Testing
+- [ ] Create `tests/test_tools_integration.py` for cross-tool tests
+- [ ] Create `tests/test_stage2.py` for end-to-end validation
+- [ ] Test error propagation and retry mechanisms
+- [ ] Verify StateGraph executes all tools correctly
+
+### Step 8: Deployment
+- [ ] Add `tenacity` to requirements.txt
+- [ ] Run all test suites locally
+- [ ] Test with Gradio UI
+- [ ] Verify no regressions from Stage 1
+- [ ] Push changes to HF Spaces
+- [ ] Verify deployment build succeeds
+- [ ] Test tools in deployed environment
+
+## Notes
+
+- All tools use direct API approach (not MCP servers)
+- HF Spaces deployment compatibility is priority
+- Mock APIs for unit tests, real APIs for integration tests only
+- Each checkpoint should pass before moving to next step

pyproject.toml

@@ -13,28 +13,24 @@ dependencies = [
     "langgraph>=0.2.0",
     "langchain>=0.3.0",
     "langchain-core>=0.3.0",
-
     # LLM APIs
     "anthropic>=0.39.0",
     "google-genai>=0.2.0",
-
     # Search & retrieval tools
     "exa-py>=1.0.0",
     "tavily-python>=0.5.0",
-
     # File readers (multi-format support)
     "PyPDF2>=3.0.0",
     "openpyxl>=3.1.0",
     "python-docx>=1.1.0",
     "pillow>=10.4.0",
-
     # Web & API utilities
     "requests>=2.32.0",
     "python-dotenv>=1.0.0",
-
     # Gradio UI
     "gradio[oauth]>=5.0.0",
     "pandas>=2.2.0",
+    "tenacity>=9.1.2",
 ]
 
 [tool.uv]

requirements.txt

@@ -57,3 +57,4 @@ python-dotenv>=1.0.0       # Environment variable management
 # ============================================================================
 pydantic>=2.0.0            # Data validation (for StateGraph)
 typing-extensions>=4.12.0  # Type hints support
+tenacity>=8.2.0            # Retry logic with exponential backoff

src/agent/graph.py

@@ -4,7 +4,7 @@ Author: @mangobee
 Date: 2026-01-01
 
 Stage 1: Skeleton with placeholder nodes
-Stage 2: Tool integration
+Stage 2: Tool integration (CURRENT)
 Stage 3: Planning and reasoning logic implementation
 
 Based on:
@@ -13,9 +13,16 @@ Based on:
 - Level 6: LangGraph framework
 """
 
+import logging
 from typing import TypedDict, List, Optional
 from langgraph.graph import StateGraph, END
 from src.config import Settings
+from src.tools import TOOLS
+
+# ============================================================================
+# Logging Setup
+# ============================================================================
+logger = logging.getLogger(__name__)
 
 # ============================================================================
 # Agent State Definition
@@ -42,8 +49,8 @@ def plan_node(state: AgentState) -> AgentState:
     """
     Planning node: Analyze question and generate execution plan.
 
-    Stage 1: Returns placeholder plan
-    Stage 3: Implement dynamic planning logic
+    Stage 2: Basic tool listing
+    Stage 3: Dynamic planning with LLM
 
     Args:
         state: Current agent state with question
@@ -51,10 +58,13 @@ def plan_node(state: AgentState) -> AgentState:
     Returns:
         Updated state with execution plan
     """
-    print(f"[plan_node] Question received: {state['question'][:100]}...")
+    logger.info(f"[plan_node] Question received: {state['question'][:100]}...")
+
+    # Stage 2: List available tools (dynamic planning in Stage 3)
+    tool_summary = ", ".join(TOOLS.keys())
+    state["plan"] = f"Stage 2: {len(TOOLS)} tools available ({tool_summary}). Dynamic planning in Stage 3."
 
-    # Stage 1 placeholder: Skip planning
-    state["plan"] = "Stage 1 placeholder: No planning implemented yet"
+    logger.info(f"[plan_node] Plan created: {state['plan']}")
 
     return state
 
@@ -63,9 +73,8 @@ def execute_node(state: AgentState) -> AgentState:
     """
     Execution node: Execute tools based on plan.
 
-    Stage 1: Returns placeholder tool calls
-    Stage 2: Implement tool orchestration
-    Stage 3: Implement tool selection based on plan
+    Stage 2: Tool execution with error handling
+    Stage 3: Dynamic tool selection based on plan
 
     Args:
         state: Current agent state with plan
@@ -73,12 +82,25 @@ def execute_node(state: AgentState) -> AgentState:
     Returns:
         Updated state with tool execution results
     """
-    print(f"[execute_node] Plan: {state['plan']}")
+    logger.info(f"[execute_node] Executing tools - Plan: {state['plan'][:100]}...")
 
-    # Stage 1 placeholder: No tool execution
-    state["tool_calls"] = [
-        {"tool": "placeholder", "status": "Stage 1: No tools implemented yet"}
-    ]
+    # Stage 2: Tools are available but no dynamic planning yet
+    # For now, just demonstrate tool registry is loaded
+    tool_calls = []
+
+    # Log available tools
+    for tool_name, tool_info in TOOLS.items():
+        logger.info(f"  Available tool: {tool_name} - {tool_info['description']}")
+        tool_calls.append({
+            "tool": tool_name,
+            "status": "ready",
+            "description": tool_info["description"],
+            "category": tool_info["category"]
+        })
+
+    state["tool_calls"] = tool_calls
+
+    logger.info(f"[execute_node] {len(tool_calls)} tools ready for Stage 3 dynamic execution")
 
     return state
 
@@ -87,8 +109,8 @@ def answer_node(state: AgentState) -> AgentState:
     """
     Answer synthesis node: Generate final factoid answer.
 
-    Stage 1: Returns fixed placeholder answer
-    Stage 3: Implement answer synthesis from tool results
+    Stage 2: Summarize tool availability
+    Stage 3: Synthesize answer from tool execution results
 
     Args:
         state: Current agent state with tool results
@@ -96,10 +118,13 @@ def answer_node(state: AgentState) -> AgentState:
     Returns:
         Updated state with final answer
     """
-    print(f"[answer_node] Tool calls: {len(state['tool_calls'])}")
+    logger.info(f"[answer_node] Processing {len(state['tool_calls'])} tool results")
+
+    # Stage 2: Report tool readiness
+    ready_tools = [t["tool"] for t in state["tool_calls"] if t["status"] == "ready"]
+    state["answer"] = f"Stage 2 complete: {len(ready_tools)} tools ready for execution in Stage 3"
 
-    # Stage 1 placeholder: Fixed answer
-    state["answer"] = "Stage 1 placeholder answer"
+    logger.info(f"[answer_node] Answer generated: {state['answer']}")
 
     return state
 

src/tools/__init__.py

@@ -1,15 +1,64 @@
 """
-MCP tool implementations package
+Tool implementations package
 Author: @mangobee
 
-This package will contain:
-- web_search.py: Web search tool (Exa/Tavily)
-- code_interpreter.py: Python code execution
-- file_reader.py: Multi-format file reading
-- multimodal.py: Vision/image processing
+This package contains all agent tools:
+- web_search: Web search using Tavily/Exa
+- file_parser: Multi-format file parsing (PDF/Excel/Word/Text)
+- calculator: Safe mathematical expression evaluation
+- vision: Multimodal image analysis using LLMs
 
-Stage 1: Placeholder only
-Stage 2: Full implementation
+Stage 2: All tools implemented with retry logic and error handling
 """
 
-__all__ = []
+from src.tools.web_search import search, tavily_search, exa_search
+from src.tools.file_parser import parse_file, parse_pdf, parse_excel, parse_word, parse_text
+from src.tools.calculator import safe_eval
+from src.tools.vision import analyze_image, analyze_image_gemini, analyze_image_claude
+
+# Tool registry with metadata
+TOOLS = {
+    "web_search": {
+        "function": search,
+        "description": "Search the web using Tavily or Exa APIs with fallback",
+        "parameters": ["query", "max_results"],
+        "category": "information_retrieval",
+    },
+    "parse_file": {
+        "function": parse_file,
+        "description": "Parse files (PDF, Excel, Word, Text, CSV) and extract content",
+        "parameters": ["file_path"],
+        "category": "file_processing",
+    },
+    "calculator": {
+        "function": safe_eval,
+        "description": "Safely evaluate mathematical expressions",
+        "parameters": ["expression"],
+        "category": "computation",
+    },
+    "vision": {
+        "function": analyze_image,
+        "description": "Analyze images using multimodal LLMs (Gemini/Claude)",
+        "parameters": ["image_path", "question"],
+        "category": "multimodal",
+    },
+}
+
+__all__ = [
+    # Main unified tool functions
+    "search",
+    "parse_file",
+    "safe_eval",
+    "analyze_image",
+    # Specific implementations (for advanced use)
+    "tavily_search",
+    "exa_search",
+    "parse_pdf",
+    "parse_excel",
+    "parse_word",
+    "parse_text",
+    "analyze_image_gemini",
+    "analyze_image_claude",
+    # Tool registry
+    "TOOLS",
+]

src/tools/calculator.py

@@ -0,0 +1,303 @@
+"""
+Calculator Tool - Safe mathematical expression evaluation
+Author: @mangobee
+Date: 2026-01-02
+
+Provides safe evaluation of mathematical expressions with:
+- Whitelisted operations and functions
+- Timeout protection
+- Complexity limits
+- No access to dangerous built-ins
+
+Security is prioritized over functionality.
+"""
+
+import ast
+import math
+import operator
+import logging
+from typing import Any, Dict
+import signal
+from contextlib import contextmanager
+
+# ============================================================================
+# CONFIG
+# ============================================================================
+MAX_EXPRESSION_LENGTH = 500
+MAX_EVAL_TIME_SECONDS = 2
+MAX_NUMBER_SIZE = 10**100  # Prevent huge number calculations
+
+# Whitelist of safe operations
+SAFE_OPERATORS = {
+    ast.Add: operator.add,
+    ast.Sub: operator.sub,
+    ast.Mult: operator.mul,
+    ast.Div: operator.truediv,
+    ast.FloorDiv: operator.floordiv,
+    ast.Mod: operator.mod,
+    ast.Pow: operator.pow,
+    ast.USub: operator.neg,
+    ast.UAdd: operator.pos,
+}
+
+# Whitelist of safe mathematical functions
+SAFE_FUNCTIONS = {
+    'abs': abs,
+    'round': round,
+    'min': min,
+    'max': max,
+    'sum': sum,
+    # Math module functions
+    'sqrt': math.sqrt,
+    'ceil': math.ceil,
+    'floor': math.floor,
+    'log': math.log,
+    'log10': math.log10,
+    'exp': math.exp,
+    'sin': math.sin,
+    'cos': math.cos,
+    'tan': math.tan,
+    'asin': math.asin,
+    'acos': math.acos,
+    'atan': math.atan,
+    'degrees': math.degrees,
+    'radians': math.radians,
+    'factorial': math.factorial,
+    # Constants
+    'pi': math.pi,
+    'e': math.e,
+}
+
+# ============================================================================
+# Logging Setup
+# ============================================================================
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Timeout Context Manager
+# ============================================================================
+
+class TimeoutError(Exception):
+    """Raised when evaluation exceeds timeout"""
+    pass
+
+
+@contextmanager
+def timeout(seconds: int):
+    """
+    Context manager for timeout protection.
+
+    Args:
+        seconds: Maximum execution time
+
+    Raises:
+        TimeoutError: If execution exceeds timeout
+    """
+    def timeout_handler(signum, frame):
+        raise TimeoutError(f"Evaluation exceeded {seconds} second timeout")
+
+    # Set signal handler
+    old_handler = signal.signal(signal.SIGALRM, timeout_handler)
+    signal.alarm(seconds)
+
+    try:
+        yield
+    finally:
+        # Restore old handler and cancel alarm
+        signal.alarm(0)
+        signal.signal(signal.SIGALRM, old_handler)
+
+
+# ============================================================================
+# Safe AST Evaluator
+# ============================================================================
+
+class SafeEvaluator(ast.NodeVisitor):
+    """
+    AST visitor that evaluates mathematical expressions safely.
+
+    Only allows whitelisted operations and functions.
+    Prevents code execution, attribute access, and other dangerous operations.
+    """
+
+    def visit_Expression(self, node):
+        """Visit Expression node (root of parse tree)"""
+        return self.visit(node.body)
+
+    def visit_Constant(self, node):
+        """Visit Constant node (numbers, strings)"""
+        value = node.value
+
+        # Only allow numbers
+        if not isinstance(value, (int, float, complex)):
+            raise ValueError(f"Unsupported constant type: {type(value).__name__}")
+
+        # Prevent huge numbers
+        if isinstance(value, (int, float)) and abs(value) > MAX_NUMBER_SIZE:
+            raise ValueError(f"Number too large: {value}")
+
+        return value
+
+    def visit_BinOp(self, node):
+        """Visit binary operation node (+, -, *, /, etc.)"""
+        op_type = type(node.op)
+
+        if op_type not in SAFE_OPERATORS:
+            raise ValueError(f"Unsupported operation: {op_type.__name__}")
+
+        left = self.visit(node.left)
+        right = self.visit(node.right)
+
+        op_func = SAFE_OPERATORS[op_type]
+
+        # Check for division by zero
+        if op_type in (ast.Div, ast.FloorDiv, ast.Mod) and right == 0:
+            raise ZeroDivisionError("Division by zero")
+
+        # Prevent huge exponentiations
+        if op_type == ast.Pow and abs(right) > 1000:
+            raise ValueError(f"Exponent too large: {right}")
+
+        return op_func(left, right)
+
+    def visit_UnaryOp(self, node):
+        """Visit unary operation node (-, +)"""
+        op_type = type(node.op)
+
+        if op_type not in SAFE_OPERATORS:
+            raise ValueError(f"Unsupported unary operation: {op_type.__name__}")
+
+        operand = self.visit(node.operand)
+        op_func = SAFE_OPERATORS[op_type]
+
+        return op_func(operand)
+
+    def visit_Call(self, node):
+        """Visit function call node"""
+        # Only allow simple function names, not attribute access
+        if not isinstance(node.func, ast.Name):
+            raise ValueError("Only direct function calls are allowed")
+
+        func_name = node.func.id
+
+        if func_name not in SAFE_FUNCTIONS:
+            raise ValueError(f"Unsupported function: {func_name}")
+
+        # Evaluate arguments
+        args = [self.visit(arg) for arg in node.args]
+
+        # No keyword arguments allowed
+        if node.keywords:
+            raise ValueError("Keyword arguments not allowed")
+
+        func = SAFE_FUNCTIONS[func_name]
+
+        try:
+            return func(*args)
+        except Exception as e:
+            raise ValueError(f"Error calling {func_name}: {str(e)}")
+
+    def visit_Name(self, node):
+        """Visit name node (variable/constant reference)"""
+        # Only allow whitelisted constants
+        if node.id in SAFE_FUNCTIONS:
+            value = SAFE_FUNCTIONS[node.id]
+            # If it's a constant (not a function), return it
+            if not callable(value):
+                return value
+
+        raise ValueError(f"Undefined name: {node.id}")
+
+    def visit_List(self, node):
+        """Visit list node"""
+        return [self.visit(element) for element in node.elts]
+
+    def visit_Tuple(self, node):
+        """Visit tuple node"""
+        return tuple(self.visit(element) for element in node.elts)
+
+    def generic_visit(self, node):
+        """Catch-all for unsupported node types"""
+        raise ValueError(f"Unsupported expression type: {type(node).__name__}")
+
+
+# ============================================================================
+# Public API
+# ============================================================================
+
+def safe_eval(expression: str) -> Dict[str, Any]:
+    """
+    Safely evaluate a mathematical expression.
+
+    Args:
+        expression: Mathematical expression string
+
+    Returns:
+        Dict with structure: {
+            "result": float or int,  # Evaluation result
+            "expression": str,       # Original expression
+            "success": bool          # True if evaluation succeeded
+        }
+
+    Raises:
+        ValueError: For invalid or unsafe expressions
+        ZeroDivisionError: For division by zero
+        TimeoutError: If evaluation exceeds timeout
+        SyntaxError: For malformed expressions
+
+    Examples:
+        >>> safe_eval("2 + 2")
+        {"result": 4, "expression": "2 + 2", "success": True}
+
+        >>> safe_eval("sqrt(16) + 3")
+        {"result": 7.0, "expression": "sqrt(16) + 3", "success": True}
+
+        >>> safe_eval("import os")  # Raises ValueError
+    """
+    # Input validation
+    if not expression or not isinstance(expression, str):
+        raise ValueError("Expression must be a non-empty string")
+
+    expression = expression.strip()
+
+    if len(expression) > MAX_EXPRESSION_LENGTH:
+        raise ValueError(
+            f"Expression too long ({len(expression)} chars). "
+            f"Maximum: {MAX_EXPRESSION_LENGTH} chars"
+        )
+
+    logger.info(f"Evaluating expression: {expression}")
+
+    try:
+        # Parse expression into AST
+        tree = ast.parse(expression, mode='eval')
+
+        # Evaluate with timeout protection
+        with timeout(MAX_EVAL_TIME_SECONDS):
+            evaluator = SafeEvaluator()
+            result = evaluator.visit(tree)
+
+        logger.info(f"Evaluation successful: {result}")
+
+        return {
+            "result": result,
+            "expression": expression,
+            "success": True,
+        }
+
+    except SyntaxError as e:
+        logger.error(f"Syntax error in expression: {e}")
+        raise SyntaxError(f"Invalid expression syntax: {str(e)}")
+    except ZeroDivisionError as e:
+        logger.error(f"Division by zero: {expression}")
+        raise
+    except TimeoutError as e:
+        logger.error(f"Evaluation timeout: {expression}")
+        raise
+    except ValueError as e:
+        logger.error(f"Invalid expression: {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error evaluating expression: {e}")
+        raise ValueError(f"Evaluation error: {str(e)}")

src/tools/file_parser.py

@@ -0,0 +1,367 @@
+"""
+File Parser Tool - Multi-format file reading
+Author: @mangobee
+Date: 2026-01-02
+
+Provides file parsing for:
+- PDF files (.pdf) using PyPDF2
+- Excel files (.xlsx, .xls) using openpyxl
+- Word documents (.docx) using python-docx
+- Text files (.txt, .csv) using built-in open()
+
+All parsers include retry logic and error handling.
+"""
+
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional
+from tenacity import (
+    retry,
+    stop_after_attempt,
+    wait_exponential,
+    retry_if_exception_type,
+)
+
+# ============================================================================
+# CONFIG
+# ============================================================================
+MAX_RETRIES = 3
+RETRY_MIN_WAIT = 1  # seconds
+RETRY_MAX_WAIT = 5  # seconds
+
+SUPPORTED_EXTENSIONS = {
+    '.pdf': 'PDF',
+    '.xlsx': 'Excel',
+    '.xls': 'Excel',
+    '.docx': 'Word',
+    '.txt': 'Text',
+    '.csv': 'CSV',
+}
+
+# ============================================================================
+# Logging Setup
+# ============================================================================
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# PDF Parser
+# ============================================================================
+
+@retry(
+    stop=stop_after_attempt(MAX_RETRIES),
+    wait=wait_exponential(multiplier=1, min=RETRY_MIN_WAIT, max=RETRY_MAX_WAIT),
+    retry=retry_if_exception_type((IOError, OSError)),
+    reraise=True,
+)
+def parse_pdf(file_path: str) -> Dict:
+    """
+    Parse PDF file and extract text content.
+
+    Args:
+        file_path: Path to PDF file
+
+    Returns:
+        Dict with structure: {
+            "content": str,  # Extracted text
+            "pages": int,    # Number of pages
+            "file_type": "PDF",
+            "file_path": str
+        }
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        ValueError: If file is corrupted or invalid
+        IOError: For file reading errors (triggers retry)
+    """
+    try:
+        from PyPDF2 import PdfReader
+
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"PDF file not found: {file_path}")
+
+        logger.info(f"Parsing PDF: {file_path}")
+
+        reader = PdfReader(str(path))
+        num_pages = len(reader.pages)
+
+        # Extract text from all pages
+        content = []
+        for page_num, page in enumerate(reader.pages, 1):
+            text = page.extract_text()
+            if text.strip():
+                content.append(f"--- Page {page_num} ---\n{text}")
+
+        full_content = "\n\n".join(content)
+
+        logger.info(f"PDF parsed successfully: {num_pages} pages, {len(full_content)} chars")
+
+        return {
+            "content": full_content,
+            "pages": num_pages,
+            "file_type": "PDF",
+            "file_path": file_path,
+        }
+
+    except FileNotFoundError as e:
+        logger.error(f"PDF file not found: {e}")
+        raise
+    except (IOError, OSError) as e:
+        logger.warning(f"PDF IO error (will retry): {e}")
+        raise
+    except Exception as e:
+        logger.error(f"PDF parsing error: {e}")
+        raise ValueError(f"Failed to parse PDF: {str(e)}")
+
+
+# ============================================================================
+# Excel Parser
+# ============================================================================
+
+@retry(
+    stop=stop_after_attempt(MAX_RETRIES),
+    wait=wait_exponential(multiplier=1, min=RETRY_MIN_WAIT, max=RETRY_MAX_WAIT),
+    retry=retry_if_exception_type((IOError, OSError)),
+    reraise=True,
+)
+def parse_excel(file_path: str) -> Dict:
+    """
+    Parse Excel file and extract data from all sheets.
+
+    Args:
+        file_path: Path to Excel file (.xlsx or .xls)
+
+    Returns:
+        Dict with structure: {
+            "content": str,      # Formatted table data
+            "sheets": List[str], # Sheet names
+            "file_type": "Excel",
+            "file_path": str
+        }
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        ValueError: If file is corrupted or invalid
+        IOError: For file reading errors (triggers retry)
+    """
+    try:
+        from openpyxl import load_workbook
+
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Excel file not found: {file_path}")
+
+        logger.info(f"Parsing Excel: {file_path}")
+
+        workbook = load_workbook(str(path), data_only=True)
+        sheet_names = workbook.sheetnames
+
+        # Extract data from all sheets
+        content_parts = []
+        for sheet_name in sheet_names:
+            sheet = workbook[sheet_name]
+
+            # Get all values
+            rows = []
+            for row in sheet.iter_rows(values_only=True):
+                # Filter out completely empty rows
+                if any(cell is not None for cell in row):
+                    row_str = "\t".join(str(cell) if cell is not None else "" for cell in row)
+                    rows.append(row_str)
+
+            if rows:
+                sheet_content = f"=== Sheet: {sheet_name} ===\n" + "\n".join(rows)
+                content_parts.append(sheet_content)
+
+        full_content = "\n\n".join(content_parts)
+
+        logger.info(f"Excel parsed successfully: {len(sheet_names)} sheets")
+
+        return {
+            "content": full_content,
+            "sheets": sheet_names,
+            "file_type": "Excel",
+            "file_path": file_path,
+        }
+
+    except FileNotFoundError as e:
+        logger.error(f"Excel file not found: {e}")
+        raise
+    except (IOError, OSError) as e:
+        logger.warning(f"Excel IO error (will retry): {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Excel parsing error: {e}")
+        raise ValueError(f"Failed to parse Excel: {str(e)}")
+
+
+# ============================================================================
+# Word Document Parser
+# ============================================================================
+
+@retry(
+    stop=stop_after_attempt(MAX_RETRIES),
+    wait=wait_exponential(multiplier=1, min=RETRY_MIN_WAIT, max=RETRY_MAX_WAIT),
+    retry=retry_if_exception_type((IOError, OSError)),
+    reraise=True,
+)
+def parse_word(file_path: str) -> Dict:
+    """
+    Parse Word document and extract text content.
+
+    Args:
+        file_path: Path to Word file (.docx)
+
+    Returns:
+        Dict with structure: {
+            "content": str,        # Extracted text
+            "paragraphs": int,     # Number of paragraphs
+            "file_type": "Word",
+            "file_path": str
+        }
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        ValueError: If file is corrupted or invalid
+        IOError: For file reading errors (triggers retry)
+    """
+    try:
+        from docx import Document
+
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Word file not found: {file_path}")
+
+        logger.info(f"Parsing Word document: {file_path}")
+
+        doc = Document(str(path))
+
+        # Extract text from all paragraphs
+        paragraphs = [para.text for para in doc.paragraphs if para.text.strip()]
+        full_content = "\n\n".join(paragraphs)
+
+        logger.info(f"Word parsed successfully: {len(paragraphs)} paragraphs")
+
+        return {
+            "content": full_content,
+            "paragraphs": len(paragraphs),
+            "file_type": "Word",
+            "file_path": file_path,
+        }
+
+    except FileNotFoundError as e:
+        logger.error(f"Word file not found: {e}")
+        raise
+    except (IOError, OSError) as e:
+        logger.warning(f"Word IO error (will retry): {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Word parsing error: {e}")
+        raise ValueError(f"Failed to parse Word document: {str(e)}")
+
+
+# ============================================================================
+# Text/CSV Parser
+# ============================================================================
+
+@retry(
+    stop=stop_after_attempt(MAX_RETRIES),
+    wait=wait_exponential(multiplier=1, min=RETRY_MIN_WAIT, max=RETRY_MAX_WAIT),
+    retry=retry_if_exception_type((IOError, OSError)),
+    reraise=True,
+)
+def parse_text(file_path: str) -> Dict:
+    """
+    Parse plain text or CSV file.
+
+    Args:
+        file_path: Path to text file (.txt or .csv)
+
+    Returns:
+        Dict with structure: {
+            "content": str,
+            "lines": int,
+            "file_type": "Text" or "CSV",
+            "file_path": str
+        }
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        IOError: For file reading errors (triggers retry)
+    """
+    try:
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Text file not found: {file_path}")
+
+        logger.info(f"Parsing text file: {file_path}")
+
+        with open(path, 'r', encoding='utf-8') as f:
+            content = f.read()
+
+        lines = content.count('\n') + 1
+        file_type = "CSV" if path.suffix == '.csv' else "Text"
+
+        logger.info(f"{file_type} file parsed successfully: {lines} lines")
+
+        return {
+            "content": content,
+            "lines": lines,
+            "file_type": file_type,
+            "file_path": file_path,
+        }
+
+    except FileNotFoundError as e:
+        logger.error(f"Text file not found: {e}")
+        raise
+    except (IOError, OSError) as e:
+        logger.warning(f"Text file IO error (will retry): {e}")
+        raise
+    except UnicodeDecodeError as e:
+        logger.error(f"Text file encoding error: {e}")
+        raise ValueError(f"Failed to decode text file (try UTF-8): {str(e)}")
+
+
+# ============================================================================
+# Unified File Parser
+# ============================================================================
+
+def parse_file(file_path: str) -> Dict:
+    """
+    Parse file based on extension, automatically selecting the right parser.
+
+    Args:
+        file_path: Path to file
+
+    Returns:
+        Dict with parsed content and metadata
+
+    Raises:
+        ValueError: If file type is not supported
+        FileNotFoundError: If file doesn't exist
+        Exception: For parsing errors
+    """
+    path = Path(file_path)
+    extension = path.suffix.lower()
+
+    if extension not in SUPPORTED_EXTENSIONS:
+        raise ValueError(
+            f"Unsupported file type: {extension}. "
+            f"Supported: {', '.join(SUPPORTED_EXTENSIONS.keys())}"
+        )
+
+    logger.info(f"Dispatching parser for {SUPPORTED_EXTENSIONS[extension]} file: {file_path}")
+
+    # Dispatch to appropriate parser
+    if extension == '.pdf':
+        return parse_pdf(file_path)
+    elif extension in ['.xlsx', '.xls']:
+        return parse_excel(file_path)
+    elif extension == '.docx':
+        return parse_word(file_path)
+    elif extension in ['.txt', '.csv']:
+        return parse_text(file_path)
+    else:
+        # Should never reach here due to check above
+        raise ValueError(f"No parser for extension: {extension}")

src/tools/vision.py

@@ -0,0 +1,339 @@
+"""
+Vision Tool - Image analysis using multimodal LLMs
+Author: @mangobee
+Date: 2026-01-02
+
+Provides image analysis functionality using:
+- Gemini 2.0 Flash (default, free tier)
+- Claude Sonnet 4.5 (fallback, if configured)
+
+Supports:
+- Image file loading and encoding
+- Question answering about images
+- Object detection/description
+- Text extraction (OCR)
+- Visual reasoning
+"""
+
+import base64
+import logging
+from pathlib import Path
+from typing import Dict, Optional
+from tenacity import (
+    retry,
+    stop_after_attempt,
+    wait_exponential,
+    retry_if_exception_type,
+)
+
+from src.config.settings import Settings
+
+# ============================================================================
+# CONFIG
+# ============================================================================
+MAX_RETRIES = 3
+RETRY_MIN_WAIT = 1  # seconds
+RETRY_MAX_WAIT = 10  # seconds
+MAX_IMAGE_SIZE_MB = 10  # Maximum image size in MB
+SUPPORTED_IMAGE_FORMATS = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'}
+
+# ============================================================================
+# Logging Setup
+# ============================================================================
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Image Loading and Encoding
+# ============================================================================
+
+def load_and_encode_image(image_path: str) -> Dict[str, str]:
+    """
+    Load image file and encode as base64.
+
+    Args:
+        image_path: Path to image file
+
+    Returns:
+        Dict with structure: {
+            "data": str,          # Base64 encoded image
+            "mime_type": str,     # MIME type (e.g., "image/jpeg")
+            "size_mb": float,     # File size in MB
+        }
+
+    Raises:
+        FileNotFoundError: If image doesn't exist
+        ValueError: If file is not a supported image format or too large
+    """
+    path = Path(image_path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Image file not found: {image_path}")
+
+    # Check file extension
+    extension = path.suffix.lower()
+    if extension not in SUPPORTED_IMAGE_FORMATS:
+        raise ValueError(
+            f"Unsupported image format: {extension}. "
+            f"Supported: {', '.join(SUPPORTED_IMAGE_FORMATS)}"
+        )
+
+    # Check file size
+    size_bytes = path.stat().st_size
+    size_mb = size_bytes / (1024 * 1024)
+
+    if size_mb > MAX_IMAGE_SIZE_MB:
+        raise ValueError(
+            f"Image too large: {size_mb:.2f}MB. Maximum: {MAX_IMAGE_SIZE_MB}MB"
+        )
+
+    # Read and encode image
+    with open(path, 'rb') as f:
+        image_data = f.read()
+
+    encoded = base64.b64encode(image_data).decode('utf-8')
+
+    # Determine MIME type
+    mime_types = {
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.png': 'image/png',
+        '.gif': 'image/gif',
+        '.webp': 'image/webp',
+        '.bmp': 'image/bmp',
+    }
+    mime_type = mime_types.get(extension, 'image/jpeg')
+
+    logger.info(f"Image loaded: {path.name} ({size_mb:.2f}MB, {mime_type})")
+
+    return {
+        "data": encoded,
+        "mime_type": mime_type,
+        "size_mb": size_mb,
+    }
+
+
+# ============================================================================
+# Gemini Vision
+# ============================================================================
+
+@retry(
+    stop=stop_after_attempt(MAX_RETRIES),
+    wait=wait_exponential(multiplier=1, min=RETRY_MIN_WAIT, max=RETRY_MAX_WAIT),
+    retry=retry_if_exception_type((ConnectionError, TimeoutError)),
+    reraise=True,
+)
+def analyze_image_gemini(image_path: str, question: Optional[str] = None) -> Dict:
+    """
+    Analyze image using Gemini 2.0 Flash.
+
+    Args:
+        image_path: Path to image file
+        question: Optional question about the image (default: "Describe this image")
+
+    Returns:
+        Dict with structure: {
+            "answer": str,       # LLM's analysis/answer
+            "model": "gemini-2.0-flash",
+            "image_path": str,
+            "question": str
+        }
+
+    Raises:
+        ValueError: If API key not configured or image invalid
+        ConnectionError: If API connection fails (triggers retry)
+    """
+    try:
+        import google.genai as genai
+
+        settings = Settings()
+        api_key = settings.google_api_key
+
+        if not api_key:
+            raise ValueError("GOOGLE_API_KEY not configured in settings")
+
+        # Load and encode image
+        image_data = load_and_encode_image(image_path)
+
+        # Default question
+        if not question:
+            question = "Describe this image in detail."
+
+        logger.info(f"Gemini vision analysis: {Path(image_path).name} - '{question}'")
+
+        # Configure Gemini client
+        client = genai.Client(api_key=api_key)
+
+        # Create content with image and text
+        response = client.models.generate_content(
+            model='gemini-2.0-flash-exp',
+            contents=[
+                question,
+                {
+                    "mime_type": image_data["mime_type"],
+                    "data": image_data["data"]
+                }
+            ]
+        )
+
+        answer = response.text.strip()
+
+        logger.info(f"Gemini vision successful: {len(answer)} chars")
+
+        return {
+            "answer": answer,
+            "model": "gemini-2.0-flash",
+            "image_path": image_path,
+            "question": question,
+        }
+
+    except ValueError as e:
+        logger.error(f"Gemini configuration/input error: {e}")
+        raise
+    except (ConnectionError, TimeoutError) as e:
+        logger.warning(f"Gemini connection error (will retry): {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Gemini vision error: {e}")
+        raise Exception(f"Gemini vision failed: {str(e)}")
+
+
+# ============================================================================
+# Claude Vision (Fallback)
+# ============================================================================
+
+@retry(
+    stop=stop_after_attempt(MAX_RETRIES),
+    wait=wait_exponential(multiplier=1, min=RETRY_MIN_WAIT, max=RETRY_MAX_WAIT),
+    retry=retry_if_exception_type((ConnectionError, TimeoutError)),
+    reraise=True,
+)
+def analyze_image_claude(image_path: str, question: Optional[str] = None) -> Dict:
+    """
+    Analyze image using Claude Sonnet 4.5.
+
+    Args:
+        image_path: Path to image file
+        question: Optional question about the image (default: "Describe this image")
+
+    Returns:
+        Dict with structure: {
+            "answer": str,       # LLM's analysis/answer
+            "model": "claude-sonnet-4.5",
+            "image_path": str,
+            "question": str
+        }
+
+    Raises:
+        ValueError: If API key not configured or image invalid
+        ConnectionError: If API connection fails (triggers retry)
+    """
+    try:
+        from anthropic import Anthropic
+
+        settings = Settings()
+        api_key = settings.anthropic_api_key
+
+        if not api_key:
+            raise ValueError("ANTHROPIC_API_KEY not configured in settings")
+
+        # Load and encode image
+        image_data = load_and_encode_image(image_path)
+
+        # Default question
+        if not question:
+            question = "Describe this image in detail."
+
+        logger.info(f"Claude vision analysis: {Path(image_path).name} - '{question}'")
+
+        # Configure Claude client
+        client = Anthropic(api_key=api_key)
+
+        # Create message with image
+        response = client.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=1024,
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "image",
+                            "source": {
+                                "type": "base64",
+                                "media_type": image_data["mime_type"],
+                                "data": image_data["data"],
+                            },
+                        },
+                        {
+                            "type": "text",
+                            "text": question
+                        }
+                    ],
+                }
+            ],
+        )
+
+        answer = response.content[0].text.strip()
+
+        logger.info(f"Claude vision successful: {len(answer)} chars")
+
+        return {
+            "answer": answer,
+            "model": "claude-sonnet-4.5",
+            "image_path": image_path,
+            "question": question,
+        }
+
+    except ValueError as e:
+        logger.error(f"Claude configuration/input error: {e}")
+        raise
+    except (ConnectionError, TimeoutError) as e:
+        logger.warning(f"Claude connection error (will retry): {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Claude vision error: {e}")
+        raise Exception(f"Claude vision failed: {str(e)}")
+
+
+# ============================================================================
+# Unified Vision Analysis
+# ============================================================================
+
+def analyze_image(image_path: str, question: Optional[str] = None) -> Dict:
+    """
+    Analyze image using available multimodal LLM.
+
+    Tries Gemini first (free tier), falls back to Claude if configured.
+
+    Args:
+        image_path: Path to image file
+        question: Optional question about the image
+
+    Returns:
+        Dict with analysis results from either Gemini or Claude
+
+    Raises:
+        Exception: If both Gemini and Claude fail or are not configured
+    """
+    settings = Settings()
+
+    # Try Gemini first (default, free tier)
+    if settings.google_api_key:
+        try:
+            return analyze_image_gemini(image_path, question)
+        except Exception as e:
+            logger.warning(f"Gemini failed, trying Claude: {e}")
+
+    # Fallback to Claude
+    if settings.anthropic_api_key:
+        try:
+            return analyze_image_claude(image_path, question)
+        except Exception as e:
+            logger.error(f"Claude also failed: {e}")
+            raise Exception(f"Vision analysis failed - Gemini and Claude both failed")
+
+    # No API keys configured
+    raise ValueError(
+        "No vision API configured. Please set GOOGLE_API_KEY or ANTHROPIC_API_KEY"
+    )

src/tools/web_search.py

@@ -0,0 +1,230 @@
+"""
+Web Search Tool - Tavily and Exa implementations
+Author: @mangobee
+Date: 2026-01-02
+
+Provides web search functionality with:
+- Tavily as primary search (free tier: 1000 req/month)
+- Exa as fallback (paid tier)
+- Retry logic with exponential backoff
+- Structured error handling
+"""
+
+import logging
+from typing import Dict, List, Optional
+from tenacity import (
+    retry,
+    stop_after_attempt,
+    wait_exponential,
+    retry_if_exception_type,
+)
+
+from src.config.settings import Settings
+
+# ============================================================================
+# CONFIG
+# ============================================================================
+MAX_RETRIES = 3
+RETRY_MIN_WAIT = 1  # seconds
+RETRY_MAX_WAIT = 10  # seconds
+DEFAULT_MAX_RESULTS = 5
+
+# ============================================================================
+# Logging Setup
+# ============================================================================
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Tavily Search Implementation
+# ============================================================================
+
+@retry(
+    stop=stop_after_attempt(MAX_RETRIES),
+    wait=wait_exponential(multiplier=1, min=RETRY_MIN_WAIT, max=RETRY_MAX_WAIT),
+    retry=retry_if_exception_type((ConnectionError, TimeoutError)),
+    reraise=True,
+)
+def tavily_search(query: str, max_results: int = DEFAULT_MAX_RESULTS) -> Dict:
+    """
+    Search using Tavily API with retry logic.
+
+    Args:
+        query: Search query string
+        max_results: Maximum number of results to return (default: 5)
+
+    Returns:
+        Dict with structure: {
+            "results": [{"title": str, "url": str, "snippet": str}, ...],
+            "source": "tavily",
+            "query": str,
+            "count": int
+        }
+
+    Raises:
+        ValueError: If API key not configured
+        ConnectionError: If API connection fails after retries
+        Exception: For other API errors
+    """
+    try:
+        from tavily import TavilyClient
+
+        settings = Settings()
+        api_key = settings.tavily_api_key
+
+        if not api_key:
+            raise ValueError("TAVILY_API_KEY not configured in settings")
+
+        logger.info(f"Tavily search: query='{query}', max_results={max_results}")
+
+        client = TavilyClient(api_key=api_key)
+        response = client.search(query=query, max_results=max_results)
+
+        # Extract and structure results
+        results = []
+        for item in response.get("results", []):
+            results.append({
+                "title": item.get("title", ""),
+                "url": item.get("url", ""),
+                "snippet": item.get("content", ""),
+            })
+
+        logger.info(f"Tavily search successful: {len(results)} results")
+
+        return {
+            "results": results,
+            "source": "tavily",
+            "query": query,
+            "count": len(results),
+        }
+
+    except ValueError as e:
+        logger.error(f"Tavily configuration error: {e}")
+        raise
+    except (ConnectionError, TimeoutError) as e:
+        logger.warning(f"Tavily connection error (will retry): {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Tavily search error: {e}")
+        raise Exception(f"Tavily search failed: {str(e)}")
+
+
+# ============================================================================
+# Exa Search Implementation
+# ============================================================================
+
+@retry(
+    stop=stop_after_attempt(MAX_RETRIES),
+    wait=wait_exponential(multiplier=1, min=RETRY_MIN_WAIT, max=RETRY_MAX_WAIT),
+    retry=retry_if_exception_type((ConnectionError, TimeoutError)),
+    reraise=True,
+)
+def exa_search(query: str, max_results: int = DEFAULT_MAX_RESULTS) -> Dict:
+    """
+    Search using Exa API with retry logic.
+
+    Args:
+        query: Search query string
+        max_results: Maximum number of results to return (default: 5)
+
+    Returns:
+        Dict with structure: {
+            "results": [{"title": str, "url": str, "snippet": str}, ...],
+            "source": "exa",
+            "query": str,
+            "count": int
+        }
+
+    Raises:
+        ValueError: If API key not configured
+        ConnectionError: If API connection fails after retries
+        Exception: For other API errors
+    """
+    try:
+        from exa_py import Exa
+
+        settings = Settings()
+        api_key = settings.exa_api_key
+
+        if not api_key:
+            raise ValueError("EXA_API_KEY not configured in settings")
+
+        logger.info(f"Exa search: query='{query}', max_results={max_results}")
+
+        client = Exa(api_key=api_key)
+        response = client.search(query=query, num_results=max_results, use_autoprompt=True)
+
+        # Extract and structure results
+        results = []
+        for item in response.results:
+            results.append({
+                "title": item.title if hasattr(item, 'title') else "",
+                "url": item.url if hasattr(item, 'url') else "",
+                "snippet": item.text if hasattr(item, 'text') else "",
+            })
+
+        logger.info(f"Exa search successful: {len(results)} results")
+
+        return {
+            "results": results,
+            "source": "exa",
+            "query": query,
+            "count": len(results),
+        }
+
+    except ValueError as e:
+        logger.error(f"Exa configuration error: {e}")
+        raise
+    except (ConnectionError, TimeoutError) as e:
+        logger.warning(f"Exa connection error (will retry): {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Exa search error: {e}")
+        raise Exception(f"Exa search failed: {str(e)}")
+
+
+# ============================================================================
+# Unified Search with Fallback
+# ============================================================================
+
+def search(query: str, max_results: int = DEFAULT_MAX_RESULTS) -> Dict:
+    """
+    Unified search function with automatic fallback.
+
+    Tries Tavily first (free tier), falls back to Exa if Tavily fails.
+
+    Args:
+        query: Search query string
+        max_results: Maximum number of results to return (default: 5)
+
+    Returns:
+        Dict with search results from either Tavily or Exa
+
+    Raises:
+        Exception: If both Tavily and Exa searches fail
+    """
+    settings = Settings()
+    default_tool = settings.default_search_tool
+
+    # Try default tool first
+    if default_tool == "tavily":
+        try:
+            return tavily_search(query, max_results)
+        except Exception as e:
+            logger.warning(f"Tavily failed, falling back to Exa: {e}")
+            try:
+                return exa_search(query, max_results)
+            except Exception as exa_error:
+                logger.error(f"Both Tavily and Exa failed")
+                raise Exception(f"Search failed - Tavily: {e}, Exa: {exa_error}")
+    else:
+        # Default is Exa
+        try:
+            return exa_search(query, max_results)
+        except Exception as e:
+            logger.warning(f"Exa failed, falling back to Tavily: {e}")
+            try:
+                return tavily_search(query, max_results)
+            except Exception as tavily_error:
+                logger.error(f"Both Exa and Tavily failed")
+                raise Exception(f"Search failed - Exa: {e}, Tavily: {tavily_error}")

tests/fixtures/generate_fixtures.py

@@ -0,0 +1,95 @@
+"""
+Generate test fixtures for file parser tests
+Author: @mangobee
+"""
+
+from pathlib import Path
+
+# ============================================================================
+# CONFIG
+# ============================================================================
+FIXTURES_DIR = Path(__file__).parent
+
+# ============================================================================
+# Generate PDF
+# ============================================================================
+def generate_pdf():
+    """Generate sample PDF file using fpdf"""
+    try:
+        from fpdf import FPDF
+    except ImportError:
+        print("Skipping PDF generation (fpdf not installed)")
+        return
+
+    pdf = FPDF()
+    pdf.add_page()
+    pdf.set_font("Arial", size=12)
+    pdf.cell(200, 10, txt="Test PDF Document", ln=True)
+    pdf.cell(200, 10, txt="This is page 1 content.", ln=True)
+    pdf.add_page()
+    pdf.cell(200, 10, txt="Page 2", ln=True)
+    pdf.cell(200, 10, txt="This is page 2 content.", ln=True)
+
+    pdf_path = FIXTURES_DIR / "sample.pdf"
+    pdf.output(str(pdf_path))
+
+    print(f"Created: {pdf_path}")
+
+
+# ============================================================================
+# Generate Excel
+# ============================================================================
+def generate_excel():
+    """Generate sample Excel file"""
+    from openpyxl import Workbook
+
+    wb = Workbook()
+
+    # Sheet 1
+    ws1 = wb.active
+    ws1.title = "Data"
+    ws1.append(["Product", "Price", "Quantity"])
+    ws1.append(["Apple", 1.50, 100])
+    ws1.append(["Banana", 0.75, 150])
+    ws1.append(["Orange", 2.00, 80])
+
+    # Sheet 2
+    ws2 = wb.create_sheet("Summary")
+    ws2.append(["Total Products", 3])
+    ws2.append(["Total Quantity", 330])
+
+    excel_path = FIXTURES_DIR / "sample.xlsx"
+    wb.save(excel_path)
+
+    print(f"Created: {excel_path}")
+
+
+# ============================================================================
+# Generate Word
+# ============================================================================
+def generate_word():
+    """Generate sample Word document"""
+    from docx import Document
+
+    doc = Document()
+    doc.add_heading("Test Word Document", 0)
+    doc.add_paragraph("This is the first paragraph.")
+    doc.add_paragraph("This is the second paragraph with some content.")
+    doc.add_heading("Section 2", level=1)
+    doc.add_paragraph("Content in section 2.")
+
+    word_path = FIXTURES_DIR / "sample.docx"
+    doc.save(word_path)
+
+    print(f"Created: {word_path}")
+
+
+# ============================================================================
+# Main
+# ============================================================================
+if __name__ == "__main__":
+    print("Generating test fixtures...")
+    generate_pdf()
+    generate_excel()
+    generate_word()
+    print("All fixtures generated successfully!")

tests/fixtures/sample.csv

@@ -0,0 +1,4 @@
+Name,Age,City
+Alice,30,New York
+Bob,25,San Francisco
+Charlie,35,Boston

tests/fixtures/sample.txt

@@ -0,0 +1,4 @@
+This is a test text file.
+It has multiple lines.
+Line 3 with some content.
+Final line.

tests/test_calculator.py

@@ -0,0 +1,293 @@
+"""
+Tests for calculator tool (safe mathematical evaluation)
+Author: @mangobee
+Date: 2026-01-02
+
+Tests cover:
+- Basic arithmetic operations
+- Mathematical functions
+- Safety checks (no code execution, no imports, etc.)
+- Timeout protection
+- Complexity limits
+- Error handling
+"""
+
+import pytest
+from src.tools.calculator import safe_eval
+
+
+# ============================================================================
+# Basic Arithmetic Tests
+# ============================================================================
+
+def test_addition():
+    """Test basic addition"""
+    result = safe_eval("2 + 3")
+    assert result["result"] == 5
+    assert result["success"] is True
+
+
+def test_subtraction():
+    """Test basic subtraction"""
+    result = safe_eval("10 - 4")
+    assert result["result"] == 6
+
+
+def test_multiplication():
+    """Test basic multiplication"""
+    result = safe_eval("6 * 7")
+    assert result["result"] == 42
+
+
+def test_division():
+    """Test basic division"""
+    result = safe_eval("15 / 3")
+    assert result["result"] == 5.0
+
+
+def test_floor_division():
+    """Test floor division"""
+    result = safe_eval("17 // 5")
+    assert result["result"] == 3
+
+
+def test_modulo():
+    """Test modulo operation"""
+    result = safe_eval("17 % 5")
+    assert result["result"] == 2
+
+
+def test_exponentiation():
+    """Test exponentiation"""
+    result = safe_eval("2 ** 8")
+    assert result["result"] == 256
+
+
+def test_negative_numbers():
+    """Test negative numbers"""
+    result = safe_eval("-5 + 3")
+    assert result["result"] == -2
+
+
+def test_complex_expression():
+    """Test complex arithmetic expression"""
+    result = safe_eval("(2 + 3) * 4 - 10 / 2")
+    assert result["result"] == 15.0
+
+
+# ============================================================================
+# Mathematical Function Tests
+# ============================================================================
+
+def test_sqrt():
+    """Test square root function"""
+    result = safe_eval("sqrt(16)")
+    assert result["result"] == 4.0
+
+
+def test_abs():
+    """Test absolute value"""
+    result = safe_eval("abs(-42)")
+    assert result["result"] == 42
+
+
+def test_round():
+    """Test rounding"""
+    result = safe_eval("round(3.7)")
+    assert result["result"] == 4
+
+
+def test_min():
+    """Test min function"""
+    result = safe_eval("min(5, 2, 8, 1)")
+    assert result["result"] == 1
+
+
+def test_max():
+    """Test max function"""
+    result = safe_eval("max(5, 2, 8, 1)")
+    assert result["result"] == 8
+
+
+def test_trigonometric():
+    """Test trigonometric functions"""
+    result = safe_eval("sin(0)")
+    assert result["result"] == 0.0
+
+    result = safe_eval("cos(0)")
+    assert result["result"] == 1.0
+
+
+def test_logarithm():
+    """Test logarithmic functions"""
+    result = safe_eval("log10(100)")
+    assert result["result"] == 2.0
+
+
+def test_constants():
+    """Test mathematical constants"""
+    result = safe_eval("pi")
+    assert abs(result["result"] - 3.14159) < 0.001
+
+    result = safe_eval("e")
+    assert abs(result["result"] - 2.71828) < 0.001
+
+
+def test_factorial():
+    """Test factorial function"""
+    result = safe_eval("factorial(5)")
+    assert result["result"] == 120
+
+
+def test_nested_functions():
+    """Test nested function calls"""
+    result = safe_eval("sqrt(abs(-16))")
+    assert result["result"] == 4.0
+
+
+# ============================================================================
+# Security Tests
+# ============================================================================
+
+def test_no_import():
+    """Test that imports are blocked"""
+    with pytest.raises(SyntaxError):
+        safe_eval("import os")
+
+
+def test_no_exec():
+    """Test that exec is blocked"""
+    with pytest.raises((ValueError, SyntaxError)):
+        safe_eval("exec('print(1)')")
+
+
+def test_no_eval():
+    """Test that eval is blocked"""
+    with pytest.raises((ValueError, SyntaxError)):
+        safe_eval("eval('1+1')")
+
+
+def test_no_lambda():
+    """Test that lambda is blocked"""
+    with pytest.raises((ValueError, SyntaxError)):
+        safe_eval("lambda x: x + 1")
+
+
+def test_no_attribute_access():
+    """Test that attribute access is blocked"""
+    with pytest.raises(ValueError):
+        safe_eval("(1).__class__")
+
+
+def test_no_list_comprehension():
+    """Test that list comprehensions are blocked"""
+    with pytest.raises(ValueError):
+        safe_eval("[x for x in range(10)]")
+
+
+def test_no_dict_access():
+    """Test that dict operations are blocked"""
+    with pytest.raises((ValueError, SyntaxError)):
+        safe_eval("{'a': 1}")
+
+
+def test_no_undefined_names():
+    """Test that undefined variable names are blocked"""
+    with pytest.raises(ValueError, match="Undefined name"):
+        safe_eval("undefined_variable + 1")
+
+
+def test_no_dangerous_functions():
+    """Test that dangerous functions are blocked"""
+    with pytest.raises(ValueError, match="Unsupported function"):
+        safe_eval("open('file.txt')")
+
+
+# ============================================================================
+# Error Handling Tests
+# ============================================================================
+
+def test_division_by_zero():
+    """Test division by zero raises error"""
+    with pytest.raises(ZeroDivisionError):
+        safe_eval("10 / 0")
+
+
+def test_invalid_syntax():
+    """Test invalid syntax raises error"""
+    with pytest.raises(SyntaxError):
+        safe_eval("2 +* 3")
+
+
+def test_empty_expression():
+    """Test empty expression raises error"""
+    with pytest.raises(ValueError, match="non-empty string"):
+        safe_eval("")
+
+
+def test_too_long_expression():
+    """Test expression length limit"""
+    long_expr = "1 + " * 300 + "1"
+    with pytest.raises(ValueError, match="too long"):
+        safe_eval(long_expr)
+
+
+def test_huge_exponent():
+    """Test that huge exponents are blocked"""
+    with pytest.raises(ValueError, match="Exponent too large"):
+        safe_eval("2 ** 10000")
+
+
+def test_sqrt_negative():
+    """Test sqrt of negative number raises error"""
+    with pytest.raises(ValueError):
+        safe_eval("sqrt(-1)")
+
+
+def test_factorial_negative():
+    """Test factorial of negative number raises error"""
+    with pytest.raises(ValueError):
+        safe_eval("factorial(-5)")
+
+
+# ============================================================================
+# Edge Case Tests
+# ============================================================================
+
+def test_whitespace_handling():
+    """Test that whitespace is handled correctly"""
+    result = safe_eval("  2 + 3  ")
+    assert result["result"] == 5
+
+
+def test_floating_point():
+    """Test floating point arithmetic"""
+    result = safe_eval("3.14 * 2")
+    assert abs(result["result"] - 6.28) < 0.01
+
+
+def test_very_small_numbers():
+    """Test very small numbers"""
+    result = safe_eval("0.0001 + 0.0002")
+    assert abs(result["result"] - 0.0003) < 0.00001
+
+
+def test_scientific_notation():
+    """Test scientific notation"""
+    result = safe_eval("1e3 + 2e2")
+    assert result["result"] == 1200.0
+
+
+def test_parentheses_precedence():
+    """Test that parentheses affect precedence correctly"""
+    result1 = safe_eval("2 + 3 * 4")
+    assert result1["result"] == 14
+
+    result2 = safe_eval("(2 + 3) * 4")
+    assert result2["result"] == 20
+
+
+def test_multiple_operations():
+    """Test chaining multiple operations"""
+    result = safe_eval("10 + 20 - 5 * 2 / 2 + 3")
+    assert result["result"] == 28.0

tests/test_file_parser.py

@@ -0,0 +1,317 @@
+"""
+Tests for file parser tool
+Author: @mangobee
+Date: 2026-01-02
+
+Tests cover:
+- PDF parsing
+- Excel parsing
+- Word document parsing
+- Text/CSV parsing
+- Retry logic
+- Error handling
+"""
+
+import pytest
+from pathlib import Path
+from unittest.mock import Mock, patch, MagicMock
+from src.tools.file_parser import (
+    parse_pdf,
+    parse_excel,
+    parse_word,
+    parse_text,
+    parse_file,
+)
+
+# ============================================================================
+# Test Fixtures
+# ============================================================================
+
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+
+
+@pytest.fixture
+def sample_text_file():
+    """Path to sample text file"""
+    return str(FIXTURES_DIR / "sample.txt")
+
+
+@pytest.fixture
+def sample_csv_file():
+    """Path to sample CSV file"""
+    return str(FIXTURES_DIR / "sample.csv")
+
+
+@pytest.fixture
+def sample_excel_file():
+    """Path to sample Excel file"""
+    return str(FIXTURES_DIR / "sample.xlsx")
+
+
+@pytest.fixture
+def sample_word_file():
+    """Path to sample Word file"""
+    return str(FIXTURES_DIR / "sample.docx")
+
+
+@pytest.fixture
+def mock_pdf_reader():
+    """Mock PyPDF2 PdfReader"""
+    mock_page_1 = Mock()
+    mock_page_1.extract_text.return_value = "Test PDF page 1 content"
+
+    mock_page_2 = Mock()
+    mock_page_2.extract_text.return_value = "Test PDF page 2 content"
+
+    mock_reader = Mock()
+    mock_reader.pages = [mock_page_1, mock_page_2]
+
+    return mock_reader
+
+
+# ============================================================================
+# PDF Parser Tests
+# ============================================================================
+
+def test_parse_pdf_success(mock_pdf_reader):
+    """Test successful PDF parsing"""
+    with patch('PyPDF2.PdfReader') as mock_reader_class:
+        with patch('src.tools.file_parser.Path') as mock_path_class:
+            # Mock file exists
+            mock_path = Mock()
+            mock_path.exists.return_value = True
+            mock_path_class.return_value = mock_path
+
+            # Mock PdfReader
+            mock_reader_class.return_value = mock_pdf_reader
+
+            result = parse_pdf("test.pdf")
+
+            assert result["file_type"] == "PDF"
+            assert result["pages"] == 2
+            assert "page 1 content" in result["content"].lower()
+            assert "page 2 content" in result["content"].lower()
+
+
+def test_parse_pdf_file_not_found():
+    """Test PDF parsing with missing file"""
+    with patch('src.tools.file_parser.Path') as mock_path_class:
+        mock_path = Mock()
+        mock_path.exists.return_value = False
+        mock_path_class.return_value = mock_path
+
+        with pytest.raises(FileNotFoundError):
+            parse_pdf("nonexistent.pdf")
+
+
+def test_parse_pdf_io_error_retry():
+    """Test PDF parsing with IO error triggers retry"""
+    with patch('PyPDF2.PdfReader') as mock_reader_class:
+        with patch('src.tools.file_parser.Path') as mock_path_class:
+            # Mock file exists
+            mock_path = Mock()
+            mock_path.exists.return_value = True
+            mock_path_class.return_value = mock_path
+
+            # Mock IO error
+            mock_reader_class.side_effect = IOError("Disk error")
+
+            with pytest.raises(IOError):
+                parse_pdf("test.pdf")
+
+            # Verify retry happened (should be called MAX_RETRIES times)
+            assert mock_reader_class.call_count == 3
+
+
+# ============================================================================
+# Excel Parser Tests
+# ============================================================================
+
+def test_parse_excel_success(sample_excel_file):
+    """Test successful Excel parsing with real file"""
+    result = parse_excel(sample_excel_file)
+
+    assert result["file_type"] == "Excel"
+    assert len(result["sheets"]) == 2
+    assert "Data" in result["sheets"]
+    assert "Summary" in result["sheets"]
+    assert "Apple" in result["content"]
+    assert "Banana" in result["content"]
+
+
+def test_parse_excel_file_not_found():
+    """Test Excel parsing with missing file"""
+    with pytest.raises(FileNotFoundError):
+        parse_excel("nonexistent.xlsx")
+
+
+def test_parse_excel_io_error_retry():
+    """Test Excel parsing with IO error triggers retry"""
+    with patch('openpyxl.load_workbook') as mock_load:
+        with patch('src.tools.file_parser.Path') as mock_path_class:
+            # Mock file exists
+            mock_path = Mock()
+            mock_path.exists.return_value = True
+            mock_path_class.return_value = mock_path
+
+            # Mock IO error
+            mock_load.side_effect = IOError("Disk error")
+
+            with pytest.raises(IOError):
+                parse_excel("test.xlsx")
+
+            # Verify retry happened
+            assert mock_load.call_count == 3
+
+
+# ============================================================================
+# Word Document Parser Tests
+# ============================================================================
+
+def test_parse_word_success(sample_word_file):
+    """Test successful Word document parsing with real file"""
+    result = parse_word(sample_word_file)
+
+    assert result["file_type"] == "Word"
+    assert result["paragraphs"] > 0
+    assert "Test Word Document" in result["content"]
+    assert "first paragraph" in result["content"]
+
+
+def test_parse_word_file_not_found():
+    """Test Word parsing with missing file"""
+    with pytest.raises(FileNotFoundError):
+        parse_word("nonexistent.docx")
+
+
+def test_parse_word_io_error_retry():
+    """Test Word parsing with IO error triggers retry"""
+    with patch('docx.Document') as mock_doc_class:
+        with patch('src.tools.file_parser.Path') as mock_path_class:
+            # Mock file exists
+            mock_path = Mock()
+            mock_path.exists.return_value = True
+            mock_path_class.return_value = mock_path
+
+            # Mock IO error
+            mock_doc_class.side_effect = IOError("Disk error")
+
+            with pytest.raises(IOError):
+                parse_word("test.docx")
+
+            # Verify retry happened
+            assert mock_doc_class.call_count == 3
+
+
+# ============================================================================
+# Text/CSV Parser Tests
+# ============================================================================
+
+def test_parse_text_success(sample_text_file):
+    """Test successful text file parsing with real file"""
+    result = parse_text(sample_text_file)
+
+    assert result["file_type"] == "Text"
+    assert result["lines"] > 0
+    assert "test text file" in result["content"].lower()
+
+
+def test_parse_csv_success(sample_csv_file):
+    """Test successful CSV file parsing with real file"""
+    result = parse_text(sample_csv_file)
+
+    assert result["file_type"] == "CSV"
+    assert result["lines"] > 0
+    assert "Name,Age,City" in result["content"]
+    assert "Alice" in result["content"]
+
+
+def test_parse_text_file_not_found():
+    """Test text parsing with missing file"""
+    with pytest.raises(FileNotFoundError):
+        parse_text("nonexistent.txt")
+
+
+def test_parse_text_io_error_retry():
+    """Test text parsing with IO error triggers retry"""
+    with patch('builtins.open') as mock_open:
+        with patch('src.tools.file_parser.Path') as mock_path_class:
+            # Mock file exists
+            mock_path = Mock()
+            mock_path.exists.return_value = True
+            mock_path.suffix = '.txt'
+            mock_path_class.return_value = mock_path
+
+            # Mock IO error
+            mock_open.side_effect = IOError("Disk error")
+
+            with pytest.raises(IOError):
+                parse_text("test.txt")
+
+            # Verify retry happened
+            assert mock_open.call_count == 3
+
+
+# ============================================================================
+# Unified Parser Tests
+# ============================================================================
+
+def test_parse_file_pdf():
+    """Test unified parser dispatches to PDF parser"""
+    with patch('src.tools.file_parser.parse_pdf') as mock_parse_pdf:
+        mock_parse_pdf.return_value = {"file_type": "PDF"}
+
+        result = parse_file("test.pdf")
+
+        assert result["file_type"] == "PDF"
+        mock_parse_pdf.assert_called_once()
+
+
+def test_parse_file_excel():
+    """Test unified parser dispatches to Excel parser"""
+    with patch('src.tools.file_parser.parse_excel') as mock_parse_excel:
+        mock_parse_excel.return_value = {"file_type": "Excel"}
+
+        result = parse_file("test.xlsx")
+
+        assert result["file_type"] == "Excel"
+        mock_parse_excel.assert_called_once()
+
+
+def test_parse_file_word():
+    """Test unified parser dispatches to Word parser"""
+    with patch('src.tools.file_parser.parse_word') as mock_parse_word:
+        mock_parse_word.return_value = {"file_type": "Word"}
+
+        result = parse_file("test.docx")
+
+        assert result["file_type"] == "Word"
+        mock_parse_word.assert_called_once()
+
+
+def test_parse_file_text():
+    """Test unified parser dispatches to text parser"""
+    with patch('src.tools.file_parser.parse_text') as mock_parse_text:
+        mock_parse_text.return_value = {"file_type": "Text"}
+
+        result = parse_file("test.txt")
+
+        assert result["file_type"] == "Text"
+        mock_parse_text.assert_called_once()
+
+
+def test_parse_file_unsupported_extension():
+    """Test unified parser rejects unsupported file type"""
+    with pytest.raises(ValueError, match="Unsupported file type"):
+        parse_file("test.mp4")
+
+
+def test_parse_file_xls_extension():
+    """Test unified parser handles .xls extension"""
+    with patch('src.tools.file_parser.parse_excel') as mock_parse_excel:
+        mock_parse_excel.return_value = {"file_type": "Excel"}
+
+        result = parse_file("test.xls")
+
+        assert result["file_type"] == "Excel"
+        mock_parse_excel.assert_called_once()

tests/test_vision.py

@@ -0,0 +1,299 @@
+"""
+Tests for vision tool (multimodal image analysis)
+Author: @mangobee
+Date: 2026-01-02
+
+Tests cover:
+- Image loading and encoding
+- Gemini vision analysis
+- Claude vision analysis
+- Fallback mechanism
+- Retry logic
+- Error handling
+"""
+
+import pytest
+from pathlib import Path
+from unittest.mock import Mock, patch, MagicMock
+from src.tools.vision import (
+    load_and_encode_image,
+    analyze_image_gemini,
+    analyze_image_claude,
+    analyze_image,
+)
+
+
+# ============================================================================
+# Test Fixtures
+# ============================================================================
+
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+
+
+@pytest.fixture
+def test_image_path():
+    """Path to test image"""
+    return str(FIXTURES_DIR / "test_image.jpg")
+
+
+@pytest.fixture
+def mock_gemini_response():
+    """Mock Gemini API response"""
+    mock_response = Mock()
+    mock_response.text = "This image shows a red square."
+    return mock_response
+
+
+@pytest.fixture
+def mock_claude_response():
+    """Mock Claude API response"""
+    mock_content = Mock()
+    mock_content.text = "The image contains a red colored square."
+
+    mock_response = Mock()
+    mock_response.content = [mock_content]
+    return mock_response
+
+
+@pytest.fixture
+def mock_settings_gemini():
+    """Mock Settings with Gemini API key"""
+    with patch('src.tools.vision.Settings') as mock:
+        settings_instance = Mock()
+        settings_instance.google_api_key = "test_google_key"
+        settings_instance.anthropic_api_key = None
+        mock.return_value = settings_instance
+        yield mock
+
+
+@pytest.fixture
+def mock_settings_claude():
+    """Mock Settings with Claude API key"""
+    with patch('src.tools.vision.Settings') as mock:
+        settings_instance = Mock()
+        settings_instance.google_api_key = None
+        settings_instance.anthropic_api_key = "test_anthropic_key"
+        mock.return_value = settings_instance
+        yield mock
+
+
+@pytest.fixture
+def mock_settings_both():
+    """Mock Settings with both API keys"""
+    with patch('src.tools.vision.Settings') as mock:
+        settings_instance = Mock()
+        settings_instance.google_api_key = "test_google_key"
+        settings_instance.anthropic_api_key = "test_anthropic_key"
+        mock.return_value = settings_instance
+        yield mock
+
+
+# ============================================================================
+# Image Loading Tests
+# ============================================================================
+
+def test_load_and_encode_image_success(test_image_path):
+    """Test successful image loading and encoding"""
+    result = load_and_encode_image(test_image_path)
+
+    assert "data" in result
+    assert "mime_type" in result
+    assert result["mime_type"] == "image/jpeg"
+    assert result["size_mb"] > 0
+    assert len(result["data"]) > 0  # Base64 encoded data
+
+
+def test_load_image_file_not_found():
+    """Test image loading with missing file"""
+    with pytest.raises(FileNotFoundError):
+        load_and_encode_image("nonexistent_image.jpg")
+
+
+def test_load_image_unsupported_format(tmp_path):
+    """Test image loading with unsupported format"""
+    # Create a text file with .mp4 extension
+    fake_video = tmp_path / "video.mp4"
+    fake_video.write_text("not a real video")
+
+    with pytest.raises(ValueError, match="Unsupported image format"):
+        load_and_encode_image(str(fake_video))
+
+
+# ============================================================================
+# Gemini Vision Tests
+# ============================================================================
+
+def test_analyze_image_gemini_success(mock_settings_gemini, test_image_path, mock_gemini_response):
+    """Test successful Gemini vision analysis"""
+    with patch('google.genai.Client') as mock_client_class:
+        # Mock Gemini client
+        mock_client = Mock()
+        mock_client.models.generate_content.return_value = mock_gemini_response
+        mock_client_class.return_value = mock_client
+
+        result = analyze_image_gemini(test_image_path, "What is in this image?")
+
+        assert result["model"] == "gemini-2.0-flash"
+        assert result["answer"] == "This image shows a red square."
+        assert result["question"] == "What is in this image?"
+        assert result["image_path"] == test_image_path
+
+
+def test_analyze_image_gemini_default_question(mock_settings_gemini, test_image_path, mock_gemini_response):
+    """Test Gemini with default question"""
+    with patch('google.genai.Client') as mock_client_class:
+        mock_client = Mock()
+        mock_client.models.generate_content.return_value = mock_gemini_response
+        mock_client_class.return_value = mock_client
+
+        result = analyze_image_gemini(test_image_path)
+
+        assert result["question"] == "Describe this image in detail."
+
+
+def test_analyze_image_gemini_missing_api_key():
+    """Test Gemini with missing API key"""
+    with patch('src.tools.vision.Settings') as mock_settings:
+        settings_instance = Mock()
+        settings_instance.google_api_key = None
+        mock_settings.return_value = settings_instance
+
+        with pytest.raises(ValueError, match="GOOGLE_API_KEY not configured"):
+            analyze_image_gemini("test.jpg")
+
+
+def test_analyze_image_gemini_connection_error(mock_settings_gemini, test_image_path):
+    """Test Gemini with connection error (triggers retry)"""
+    with patch('google.genai.Client') as mock_client_class:
+        mock_client = Mock()
+        mock_client.models.generate_content.side_effect = ConnectionError("Network error")
+        mock_client_class.return_value = mock_client
+
+        with pytest.raises(ConnectionError):
+            analyze_image_gemini(test_image_path)
+
+        # Verify retry happened
+        assert mock_client.models.generate_content.call_count == 3
+
+
+# ============================================================================
+# Claude Vision Tests
+# ============================================================================
+
+def test_analyze_image_claude_success(mock_settings_claude, test_image_path, mock_claude_response):
+    """Test successful Claude vision analysis"""
+    with patch('anthropic.Anthropic') as mock_anthropic_class:
+        # Mock Claude client
+        mock_client = Mock()
+        mock_client.messages.create.return_value = mock_claude_response
+        mock_anthropic_class.return_value = mock_client
+
+        result = analyze_image_claude(test_image_path, "What is in this image?")
+
+        assert result["model"] == "claude-sonnet-4.5"
+        assert result["answer"] == "The image contains a red colored square."
+        assert result["question"] == "What is in this image?"
+        assert result["image_path"] == test_image_path
+
+
+def test_analyze_image_claude_default_question(mock_settings_claude, test_image_path, mock_claude_response):
+    """Test Claude with default question"""
+    with patch('anthropic.Anthropic') as mock_anthropic_class:
+        mock_client = Mock()
+        mock_client.messages.create.return_value = mock_claude_response
+        mock_anthropic_class.return_value = mock_client
+
+        result = analyze_image_claude(test_image_path)
+
+        assert result["question"] == "Describe this image in detail."
+
+
+def test_analyze_image_claude_missing_api_key():
+    """Test Claude with missing API key"""
+    with patch('src.tools.vision.Settings') as mock_settings:
+        settings_instance = Mock()
+        settings_instance.anthropic_api_key = None
+        mock_settings.return_value = settings_instance
+
+        with pytest.raises(ValueError, match="ANTHROPIC_API_KEY not configured"):
+            analyze_image_claude("test.jpg")
+
+
+def test_analyze_image_claude_connection_error(mock_settings_claude, test_image_path):
+    """Test Claude with connection error (triggers retry)"""
+    with patch('anthropic.Anthropic') as mock_anthropic_class:
+        mock_client = Mock()
+        mock_client.messages.create.side_effect = ConnectionError("Network error")
+        mock_anthropic_class.return_value = mock_client
+
+        with pytest.raises(ConnectionError):
+            analyze_image_claude(test_image_path)
+
+        # Verify retry happened
+        assert mock_client.messages.create.call_count == 3
+
+
+# ============================================================================
+# Unified Vision Analysis Tests
+# ============================================================================
+
+def test_analyze_image_uses_gemini(mock_settings_both, test_image_path, mock_gemini_response):
+    """Test unified analysis prefers Gemini when both APIs available"""
+    with patch('google.genai.Client') as mock_gemini_class:
+        mock_client = Mock()
+        mock_client.models.generate_content.return_value = mock_gemini_response
+        mock_gemini_class.return_value = mock_client
+
+        result = analyze_image(test_image_path, "What is this?")
+
+        assert result["model"] == "gemini-2.0-flash"
+        assert "red square" in result["answer"].lower()
+
+
+def test_analyze_image_fallback_to_claude(mock_settings_both, test_image_path, mock_claude_response):
+    """Test unified analysis falls back to Claude when Gemini fails"""
+    with patch('google.genai.Client') as mock_gemini_class:
+        with patch('anthropic.Anthropic') as mock_claude_class:
+            # Gemini fails
+            mock_gemini_client = Mock()
+            mock_gemini_client.models.generate_content.side_effect = Exception("Gemini error")
+            mock_gemini_class.return_value = mock_gemini_client
+
+            # Claude succeeds
+            mock_claude_client = Mock()
+            mock_claude_client.messages.create.return_value = mock_claude_response
+            mock_claude_class.return_value = mock_claude_client
+
+            result = analyze_image(test_image_path, "What is this?")
+
+            assert result["model"] == "claude-sonnet-4.5"
+            assert "red" in result["answer"].lower()
+
+
+def test_analyze_image_no_api_keys():
+    """Test unified analysis with no API keys configured"""
+    with patch('src.tools.vision.Settings') as mock_settings:
+        settings_instance = Mock()
+        settings_instance.google_api_key = None
+        settings_instance.anthropic_api_key = None
+        mock_settings.return_value = settings_instance
+
+        with pytest.raises(ValueError, match="No vision API configured"):
+            analyze_image("test.jpg")
+
+
+def test_analyze_image_both_fail(mock_settings_both, test_image_path):
+    """Test unified analysis when both APIs fail"""
+    with patch('google.genai.Client') as mock_gemini_class:
+        with patch('anthropic.Anthropic') as mock_claude_class:
+            # Both fail
+            mock_gemini_client = Mock()
+            mock_gemini_client.models.generate_content.side_effect = Exception("Gemini error")
+            mock_gemini_class.return_value = mock_gemini_client
+
+            mock_claude_client = Mock()
+            mock_claude_client.messages.create.side_effect = Exception("Claude error")
+            mock_claude_class.return_value = mock_claude_client
+
+            with pytest.raises(Exception, match="both failed"):
+                analyze_image(test_image_path)

tests/test_web_search.py

@@ -0,0 +1,242 @@
+"""
+Tests for web search tool (Tavily and Exa)
+Author: @mangobee
+Date: 2026-01-02
+
+Tests cover:
+- Tavily search with mocked API
+- Exa search with mocked API
+- Retry logic simulation
+- Fallback mechanism
+- Error handling
+"""
+
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+from src.tools.web_search import tavily_search, exa_search, search
+
+
+# ============================================================================
+# Test Fixtures
+# ============================================================================
+
+@pytest.fixture
+def mock_tavily_response():
+    """Mock Tavily API response"""
+    return {
+        "results": [
+            {
+                "title": "Test Result 1",
+                "url": "https://example.com/1",
+                "content": "This is test content 1"
+            },
+            {
+                "title": "Test Result 2",
+                "url": "https://example.com/2",
+                "content": "This is test content 2"
+            }
+        ]
+    }
+
+
+@pytest.fixture
+def mock_exa_response():
+    """Mock Exa API response"""
+    mock_result_1 = Mock()
+    mock_result_1.title = "Exa Result 1"
+    mock_result_1.url = "https://exa.com/1"
+    mock_result_1.text = "This is exa content 1"
+
+    mock_result_2 = Mock()
+    mock_result_2.title = "Exa Result 2"
+    mock_result_2.url = "https://exa.com/2"
+    mock_result_2.text = "This is exa content 2"
+
+    mock_response = Mock()
+    mock_response.results = [mock_result_1, mock_result_2]
+    return mock_response
+
+
+@pytest.fixture
+def mock_settings_tavily():
+    """Mock Settings with Tavily API key"""
+    with patch('src.tools.web_search.Settings') as mock:
+        settings_instance = Mock()
+        settings_instance.tavily_api_key = "test_tavily_key"
+        settings_instance.exa_api_key = "test_exa_key"
+        settings_instance.default_search_tool = "tavily"
+        mock.return_value = settings_instance
+        yield mock
+
+
+@pytest.fixture
+def mock_settings_exa():
+    """Mock Settings with Exa as default"""
+    with patch('src.tools.web_search.Settings') as mock:
+        settings_instance = Mock()
+        settings_instance.tavily_api_key = "test_tavily_key"
+        settings_instance.exa_api_key = "test_exa_key"
+        settings_instance.default_search_tool = "exa"
+        mock.return_value = settings_instance
+        yield mock
+
+
+# ============================================================================
+# Tavily Search Tests
+# ============================================================================
+
+def test_tavily_search_success(mock_settings_tavily, mock_tavily_response):
+    """Test successful Tavily search"""
+    with patch('tavily.TavilyClient') as mock_client_class:
+        mock_client = Mock()
+        mock_client.search.return_value = mock_tavily_response
+        mock_client_class.return_value = mock_client
+
+        result = tavily_search("test query", max_results=2)
+
+        assert result["source"] == "tavily"
+        assert result["query"] == "test query"
+        assert result["count"] == 2
+        assert len(result["results"]) == 2
+        assert result["results"][0]["title"] == "Test Result 1"
+        assert result["results"][0]["url"] == "https://example.com/1"
+        assert result["results"][0]["snippet"] == "This is test content 1"
+
+
+def test_tavily_search_missing_api_key():
+    """Test Tavily search with missing API key"""
+    with patch('src.tools.web_search.Settings') as mock_settings:
+        settings_instance = Mock()
+        settings_instance.tavily_api_key = None
+        mock_settings.return_value = settings_instance
+
+        with pytest.raises(ValueError, match="TAVILY_API_KEY not configured"):
+            tavily_search("test query")
+
+
+def test_tavily_search_connection_error(mock_settings_tavily):
+    """Test Tavily search with connection error (triggers retry)"""
+    with patch('tavily.TavilyClient') as mock_client_class:
+        mock_client = Mock()
+        mock_client.search.side_effect = ConnectionError("Network error")
+        mock_client_class.return_value = mock_client
+
+        with pytest.raises(ConnectionError):
+            tavily_search("test query")
+
+        # Verify retry happened (should be called MAX_RETRIES times)
+        assert mock_client.search.call_count == 3
+
+
+def test_tavily_search_empty_results(mock_settings_tavily):
+    """Test Tavily search with empty results"""
+    with patch('tavily.TavilyClient') as mock_client_class:
+        mock_client = Mock()
+        mock_client.search.return_value = {"results": []}
+        mock_client_class.return_value = mock_client
+
+        result = tavily_search("test query")
+
+        assert result["count"] == 0
+        assert result["results"] == []
+
+
+# ============================================================================
+# Exa Search Tests
+# ============================================================================
+
+def test_exa_search_success(mock_settings_exa, mock_exa_response):
+    """Test successful Exa search"""
+    with patch('exa_py.Exa') as mock_client_class:
+        mock_client = Mock()
+        mock_client.search.return_value = mock_exa_response
+        mock_client_class.return_value = mock_client
+
+        result = exa_search("test query", max_results=2)
+
+        assert result["source"] == "exa"
+        assert result["query"] == "test query"
+        assert result["count"] == 2
+        assert len(result["results"]) == 2
+        assert result["results"][0]["title"] == "Exa Result 1"
+        assert result["results"][0]["url"] == "https://exa.com/1"
+        assert result["results"][0]["snippet"] == "This is exa content 1"
+
+
+def test_exa_search_missing_api_key():
+    """Test Exa search with missing API key"""
+    with patch('src.tools.web_search.Settings') as mock_settings:
+        settings_instance = Mock()
+        settings_instance.exa_api_key = None
+        mock_settings.return_value = settings_instance
+
+        with pytest.raises(ValueError, match="EXA_API_KEY not configured"):
+            exa_search("test query")
+
+
+def test_exa_search_connection_error(mock_settings_exa):
+    """Test Exa search with connection error (triggers retry)"""
+    with patch('exa_py.Exa') as mock_client_class:
+        mock_client = Mock()
+        mock_client.search.side_effect = ConnectionError("Network error")
+        mock_client_class.return_value = mock_client
+
+        with pytest.raises(ConnectionError):
+            exa_search("test query")
+
+        # Verify retry happened
+        assert mock_client.search.call_count == 3
+
+
+# ============================================================================
+# Unified Search with Fallback Tests
+# ============================================================================
+
+def test_search_tavily_success(mock_settings_tavily, mock_tavily_response):
+    """Test unified search using Tavily successfully"""
+    with patch('tavily.TavilyClient') as mock_client_class:
+        mock_client = Mock()
+        mock_client.search.return_value = mock_tavily_response
+        mock_client_class.return_value = mock_client
+
+        result = search("test query")
+
+        assert result["source"] == "tavily"
+        assert result["count"] == 2
+
+
+def test_search_fallback_to_exa(mock_settings_tavily, mock_exa_response):
+    """Test unified search falls back to Exa when Tavily fails"""
+    with patch('tavily.TavilyClient') as mock_tavily_class:
+        with patch('exa_py.Exa') as mock_exa_class:
+            # Tavily fails
+            mock_tavily_client = Mock()
+            mock_tavily_client.search.side_effect = Exception("Tavily error")
+            mock_tavily_class.return_value = mock_tavily_client
+
+            # Exa succeeds
+            mock_exa_client = Mock()
+            mock_exa_client.search.return_value = mock_exa_response
+            mock_exa_class.return_value = mock_exa_client
+
+            result = search("test query")
+
+            assert result["source"] == "exa"
+            assert result["count"] == 2
+
+
+def test_search_both_fail(mock_settings_tavily):
+    """Test unified search when both Tavily and Exa fail"""
+    with patch('tavily.TavilyClient') as mock_tavily_class:
+        with patch('exa_py.Exa') as mock_exa_class:
+            # Both fail
+            mock_tavily_client = Mock()
+            mock_tavily_client.search.side_effect = Exception("Tavily error")
+            mock_tavily_class.return_value = mock_tavily_client
+
+            mock_exa_client = Mock()
+            mock_exa_client.search.side_effect = Exception("Exa error")
+            mock_exa_class.return_value = mock_exa_client
+
+            with pytest.raises(Exception, match="Search failed"):
+                search("test query")