USAGE.md

# Usage Guide

## Quick Start (5 minutes)

### Step 1: Install Dependencies

```bash
pip install -r requirements.txt
```

### Step 2: Configure API Keys

Copy `.env.example` to `.env` and fill in your API keys:

```bash
cp .env.example .env
# Edit .env file with your keys
```

Minimum required:
- `HUGGINGFACEHUB_API_TOKEN` (for LLM)
- `TAVILY_API_KEY` (for web search)

### Step 3: Setup Vector Database

```bash
python setup_chromadb.py
```

This will:
- Download embedding model (~90MB)
- Load metadata.jsonl
- Create local ChromaDB database

### Step 4: Run the Agent

#### Option A: Gradio UI (Recommended)

```bash
python app.py
```

Then:
1. Log in with your HuggingFace account
2. Click "Run Evaluation & Submit All Answers"
3. Wait for results

#### Option B: Command Line

```bash
python agent.py
```

Edit the question in `agent.py` line 208.

## Understanding the Output

### Agent Messages

The agent produces several message types:

1. **SystemMessage**: Instructions and guidelines
2. **HumanMessage**: Your question + similar example (from RAG)
3. **AIMessage**: Agent's reasoning and tool calls
4. **ToolMessage**: Tool execution results
5. **Final AIMessage**: The answer

Example:
```
SystemMessage: You are Alfred, an intelligent research assistant...
HumanMessage: What is quantum computing?
HumanMessage: Here is a similar question... (from vector DB)
AIMessage: I will use deep_research tool
   tool_calls: [{"name": "deep_research", "args": {"query": "..."}}]
ToolMessage: DEEP RESEARCH REPORT: ...
AIMessage: FINAL ANSWER: Quantum computing is...
```

### Deep Research Report Structure

```
DEEP RESEARCH REPORT: [Query]
=====================================

📊 OVERVIEW
- Total sources: X
- Wikipedia: Y articles
- Web: Z pages
- Academic: W papers

📚 WIKIPEDIA FINDINGS
[Source 1] ...
[Source 2] ...

🌐 WEB FINDINGS
[Source 1] ...
[Source 2] ...

🎓 ACADEMIC FINDINGS
[Source 1] ...
[Source 2] ...

📋 ALL SOURCES
[1] https://...
[2] https://...
```

## Customization

### Changing LLM Provider

Edit `agent.py` line 217:

```python
# Option 1: HuggingFace (Free, slower)
graph = build_graph(provider="huggingface")

# Option 2: Groq (Fast, free tier available)
graph = build_graph(provider="groq")

# Option 3: Google Gemini (Balanced, requires payment)
graph = build_graph(provider="google")
```

### Adjusting Deep Research Behavior

Edit `deep_research_tool.py`:

```python
# Line 54: Wikipedia results
WikipediaLoader(query=query, load_max_docs=2)  # Change to 1-5

# Line 68: Web results
TavilySearchResults(max_results=10)  # Change to 3-15

# Line 85: Academic results
ArxivLoader(query=query, load_max_docs=5)  # Change to 1-10

# Line 58, 75, 89: Content truncation
"content": doc.page_content[:2000]  # Change to 500-3000
```

### Modifying System Prompt

Edit `system_prompt.txt` to:
- Change tool selection strategy
- Adjust reasoning guidelines
- Modify output format

## Testing Different Question Types

### Mathematical Questions
```python
question = "What is 15 multiplied by 23?"
# Expected: Uses multiply tool → Direct answer
```

### Simple Factual Questions
```python
question = "Who invented the telephone?"
# Expected: Uses wiki_search → Quick answer
```

### Complex Conceptual Questions
```python
question = "Explain quantum entanglement and its applications"
# Expected: Uses deep_research → Comprehensive answer
```

### Recent Events
```python
question = "What are the latest AI developments in 2025?"
# Expected: Uses web_search or deep_research
```

## Troubleshooting

### Issue: "No module named 'sentence_transformers'"

```bash
pip install sentence-transformers
```

### Issue: "TAVILY_API_KEY not found"

Make sure `.env` file exists and contains:
```
TAVILY_API_KEY=tvly-xxxxx
```

### Issue: ChromaDB not working

Delete and recreate:
```bash
rm -rf chroma_db/
python setup_chromadb.py
```

### Issue: Agent not using deep_research

Check `system_prompt.txt` - make sure it mentions when to use deep_research.

Or be explicit in your question:
```python
question = "Use deep research to analyze quantum computing"
```

## Performance Optimization

### Speed vs Quality Trade-offs

**Faster** (for testing):
```python
# deep_research_tool.py
WikipediaLoader(load_max_docs=1)
TavilySearchResults(max_results=3)
ArxivLoader(load_max_docs=1)
"content": doc.page_content[:500]
```

**Balanced** (recommended):
```python
WikipediaLoader(load_max_docs=2)
TavilySearchResults(max_results=10)
ArxivLoader(load_max_docs=5)
"content": doc.page_content[:2000]
```

**Comprehensive** (slower but thorough):
```python
WikipediaLoader(load_max_docs=5)
TavilySearchResults(max_results=15)
ArxivLoader(load_max_docs=10)
"content": doc.page_content[:5000]
```

## Advanced Usage

### Adding Custom Tools

1. Define tool in `agent.py`:

```python
@tool
def my_custom_tool(query: str) -> str:
    """Description of what this tool does."""
    # Your implementation
    return result
```

2. Add to tools list:

```python
tools = [
    multiply, add, subtract,
    wiki_search, web_search,
    deep_research,
    my_custom_tool,  # Add here
]
```

3. Update `system_prompt.txt` to mention when to use it.

### Batch Processing

```python
from agent import build_graph
from langchain_core.messages import HumanMessage

graph = build_graph(provider="huggingface")

questions = [
    "Question 1",
    "Question 2",
    "Question 3",
]

for q in questions:
    result = graph.invoke({"messages": [HumanMessage(content=q)]})
    answer = result["messages"][-1].content
    print(f"Q: {q}\nA: {answer}\n")
```

### Logging and Debugging

Add logging to track agent behavior:

```python
# In agent.py, modify assistant function:
def assistant(state: MessagesState):
    """Assistant node"""
    print(f"\n{'='*60}")
    print("Assistant Input:")
    for msg in state["messages"]:
        print(f"  - {type(msg).__name__}: {msg.content[:100]}...")

    result = llm_with_tools.invoke(state["messages"])

    print("\nAssistant Output:")
    if hasattr(result, "tool_calls") and result.tool_calls:
        print(f"  Tool calls: {[tc['name'] for tc in result.tool_calls]}")
    print(f"{'='*60}\n")

    return {"messages": [result]}
```

## FAQ

**Q: How do I know which tool was used?**

A: Check the AIMessage for `tool_calls` field, or add logging as shown above.

**Q: Can I use without Tavily API?**

A: Yes, but web_search and deep_research will partially fail. Consider removing them from the tools list.

**Q: How long does setup take?**

A: ~5 minutes (mostly downloading the embedding model).

**Q: Can I run this offline?**

A: No, it requires API calls to LLM and search services.

**Q: How much does it cost?**

A: Using HuggingFace Inference API is free (with rate limits). Tavily has a free tier (1000 queries/month).

## Next Steps

1. Test with different question types
2. Optimize performance for your use case
3. Customize system prompt
4. Add domain-specific tools
5. Integrate with your application

For more details, see the full documentation in the main repository.