docs/features/word-problems.md

# Word Problem Handling Strategy

## Overview

meeTARA Agent handles word problems differently based on their complexity and type:

## Three Types of Word Problems

### 1. **Simple Math Word Problems** → **Calculator** ✅
**Examples:**
- "What's 15% of 340?" → Extracted as `0.15 * 340` → Calculator calculates
- "Find 25 * 48" → Calculator handles directly
- "Calculate tan(45)" → Scientific function → Calculator

**Why Calculator:**
- Clear mathematical expression can be extracted via pattern matching
- Calculator ensures 100% accuracy
- Fast and efficient

### 2. **Complex Word Problems** → **Model Directly** ✅
**Examples:**
- "If John has 5 apples and gives 2 away, how many does he have left?"
- "A train travels 60 miles in 2 hours. What's its speed?"
- "Sarah buys 3 books at $10 each and 2 pens at $5 each. How much did she spend?"
- "If a rectangle has length 6 cm and width 4 cm, what's its area?" (geometry - has keywords)

**Why Model Directly:**
- Requires understanding relationships between entities (John, apples, gives away)
- Need to extract formula from context (speed = distance/time)
- Need to combine multiple operations (3 books × $10 + 2 pens × $5)
- Model can understand natural language relationships and extract math
- Calculator would need perfect extraction, which is hard for complex relationships

**Detection:**
- Uses `word_problem_keywords` from config: "if", "has", "gives", "travels", "buys", "costs", etc.
- Strategy: `model_direct` (configurable in `agent_config.json`)
- Skips calculator if complex word problem detected → Sends directly to model

### 3. **Word Problems About Current Events/Data** → **Web Search + Model** ✅
**Examples:**
- "What's the current unemployment rate in the US?"
- "What's the current price of Bitcoin?"
- "What's today's stock market performance?"

**Why Web Search:**
- Requires up-to-date information beyond training data
- Real-time data that changes frequently
- Web search provides current data → Model structures response

## Configuration

All word problem handling is configurable in `config/agent_config.json`:

```json
{
  "calculator": {
    "word_problem_keywords": [
      "if", "when", "has", "gives", "receives", "buys", "sells",
      "travels", "drives", "costs", "price", "total", "spends",
      "left", "remaining", "more than", "less than", "times"
    ],
    "word_problem_strategy": "model_direct",
    "word_problem_explanation": "Simple word problems handled by calculator. Complex word problems go to model. Current events go to web search."
  }
}
```

## Decision Flow

```
User Query: Word Problem
    ↓
Check if contains word_problem_keywords (if, has, gives, etc.)
    ↓
┌─────────────────────────────────────────────────┐
│ Is it about current events/data?                │
│ → Contains "current", "today", "latest", etc.   │
└─────────────────────────────────────────────────┘
    YES → Web Search → Model
    NO  ↓
┌─────────────────────────────────────────────────┐
│ Can math be extracted via patterns?             │
│ → "15% of 340" → 0.15 * 340 ✓                  │
│ → "tan(45)" → tan(45) ✓                        │
│ → "25 * 48" → 25 * 48 ✓                        │
└─────────────────────────────────────────────────┘
    YES → Calculator → Model
    NO  ↓
┌─────────────────────────────────────────────────┐
│ Is it a complex word problem?                   │
│ → Contains relationship keywords                │
│ → No clear math expression extractable          │
└─────────────────────────────────────────────────┘
    YES → Model Directly (skip calculator)
    NO  → Model Directly (fallback)
```

## Examples

### Example 1: Simple → Calculator
**Query:** "What's 15% of 340?"
- Detection: Percentage pattern matched
- Extraction: `0.15 * 340`
- Calculator: `51`
- Model: Structures response with steps

### Example 2: Complex → Model Directly
**Query:** "If John has 5 apples and gives 2 away, how many does he have left?"
- Detection: Contains word_problem_keywords ("if", "has", "gives", "left")
- Complex word problem: Yes (requires understanding relationships)
- Calculator: Skipped (no clear expression to extract)
- Model: Understands relationship → Extracts: 5 - 2 = 3 → Responds

### Example 3: Current Events → Web Search
**Query:** "What's the current unemployment rate?"
- Detection: Contains "current" → Web search keyword
- Web Search: Fetches current data
- Model: Structures response with current data

### Example 4: Geometry → Full Query to Model
**Query:** "Find the surface area of a rectangular prism with dimensions: length = 6 cm, width = 4 cm, height = 5 cm"
- Detection: Geometry keywords ("surface area", "rectangular prism")
- Calculator: Receives full query (not just numbers)
- Calculator: Detects geometry → Returns context message
- Model: Calculates using formula 2(lw + lh + wh) = 148 cm²

## Recommendations

1. **Simple Math** → Calculator (100% accurate, fast)
2. **Complex Word Problems** → Model (understands relationships, extracts math)
3. **Current Events** → Web Search (up-to-date data)
4. **Geometry** → Full query to calculator/model (needs formula context)

## Why This Strategy Works

- **Calculator** = Perfect for clear math expressions (ensures accuracy)
- **Model** = Perfect for understanding relationships and extracting formulas
- **Web Search** = Perfect for current/realtime data
- **Combination** = Best of all worlds (tool precision + model understanding + current data)