tavily

# Tavily (Web Search / Extract / Research)

## Prereqs

- Ensure `TAVILY_API_KEY` is set in the Hermes environment (commonly `~/.hermes/.env`).
- Do not hardcode or paste API keys into chat logs. See `references/bp-api-key-management.md`.

## Security Notes

- The bundled CLI (`scripts/tavily.py`) reads only `TAVILY_API_KEY` from the environment and only sends requests to `https://api.tavily.com`.
- Prefer `search` then `extract` over `include_raw_content` on `search` to keep outputs small and reduce accidental data exposure.

## Quick Reference

Use the terminal tool to run the bundled CLI script (prints JSON).
`SKILL_DIR` is the directory containing this `SKILL.md` file.

```bash
# Search (general)
python3 SKILL_DIR/scripts/tavily.py search --query "latest OpenAI API changes" --max-results 5

# Search (news) with recency filter
python3 SKILL_DIR/scripts/tavily.py search --query "latest OpenAI API changes" --topic news --time-range week --max-results 5

# High-precision search (more cost/latency)
python3 SKILL_DIR/scripts/tavily.py search --query "OpenAI API rate limits March 2026" --search-depth advanced --chunks-per-source 3 --max-results 5

# Search + answer (still cite URLs from results)
python3 SKILL_DIR/scripts/tavily.py search --query "What is X?" --include-answer basic --max-results 5

# Extract (targeted chunks; prefer this over include_raw_content on search)
python3 SKILL_DIR/scripts/tavily.py extract --url "https://example.com" --query "pricing" --chunks-per-source 3 --format markdown

# Research (creates task + polls until complete)
python3 SKILL_DIR/scripts/tavily.py research --input "Summarize the EU AI Act enforcement timeline. Provide numbered citations." --model auto --citation-format numbered --max-wait-seconds 180
```

Use returned `results[].url` fields as citations/sources in your final answer.

## No-Script Option (curl)

Use Tavily directly via curl (same endpoints, no bundled script):

```bash
curl -s "https://api.tavily.com/search" \
  -H "...