ana - AI-powered CLI

Answers, comparisons, and interactive study sessions powered by Gemini and LangGraph.

Table of Contents

• Features
• 30-second Quick Start (Windows)
• Full Setup (Windows)
• Usage
• Output Examples
• CLI Options
• Environment Variables
• Demo Media (Screenshots and Video)
• Project Structure
• Data and Checkpoints
• Running Tests
• Troubleshooting
• Security Notes
• LangGraph Workflow
• Contributing
• License
• Acknowledgements

Features

Command	What it does
ana "QUESTION"	Plan -> generate -> reflect loop that answers any question
ana compare "A" "B"	Structured comparison table + narrative + when-to-use guidance
ana study "TOPIC" --quiz N	Lesson + key takeaways + N-question interactive quiz with grading

All modes share:

• configurable revision loops via --revisions
• optional Tavily web research via --research
• SQLite checkpointing
• output formats: text, markdown, JSON

30-second Quick Start (Windows)

PowerShell:

cd ana_agent
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
$env:GOOGLE_API_KEY = "AIza...your-key..."
ana "What is the difference between TCP and UDP?"

Full Setup (Windows)

1) Prerequisites

• Python 3.10-3.12 (recommended and tested)
• A Google AI Studio API key (free tier available): https://aistudio.google.com/app/apikey
• Optional OpenRouter API key if using --provider openrouter: https://openrouter.ai/developers

2) Install

# Clone / enter repo
cd ana_agent

# Create and activate virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install package in editable mode
pip install -e .

3) Set API keys

CMD:

set GOOGLE_API_KEY=AIza...your-key...
set TAVILY_API_KEY=tvly-...
set OPENROUTER_API_KEY=or-...

PowerShell:

$env:GOOGLE_API_KEY = "AIza...your-key..."
$env:TAVILY_API_KEY = "tvly-..."
$env:OPENROUTER_API_KEY = "or-..."

Persistent .env file in project root:

GOOGLE_API_KEY=AIza...your-key...
# Optional
TAVILY_API_KEY=tvly-...
OPENROUTER_API_KEY=or-...
OPENROUTER_SITE_URL=https://github.com/OWNER/REPO
OPENROUTER_APP_NAME=ana

Usage

Answer a question

ana "What is the difference between TCP and UDP?"
ana "Explain gradient descent" --revisions 2 --show-plan --show-critique

Compare two things

ana compare "React" "Vue"
ana compare "PostgreSQL" "MongoDB" --revisions 2 --format md --save

Study a topic interactively

ana study "async/await in Python" --quiz 5
ana study "Docker containers" --quiz 3 --revisions 2

Enable web research (requires Tavily key)

CMD:

set TAVILY_API_KEY=tvly-...
ana "Latest LLM benchmarks 2025" --research --show-sources

PowerShell:

$env:TAVILY_API_KEY = "tvly-..."
ana compare "Claude" "GPT-4" --research --format md --save

Use OpenRouter instead of Gemini

PowerShell:

$env:OPENROUTER_API_KEY = "or-..."
ana "Summarize latest Llama news" --provider openrouter --model openrouter/auto

Optional OpenRouter headers:

• OPENROUTER_SITE_URL -> HTTP-Referer
• OPENROUTER_APP_NAME -> X-Title

Output Examples

Text mode (default)

ana "Explain event loops"

Example:

Event loops are the mechanism that lets a program handle many tasks without
starting one OS thread per task...

Markdown mode

ana compare "Redis" "Memcached" --format md --save

JSON mode

ana "What is overfitting?" --format json

Example shape:

{
  "mode": "answer",
  "question": "What is overfitting?",
  "output": "...",
  "sources": [
    {
      "title": "...",
      "url": "...",
      "snippet": "..."
    }
  ]
}

CLI Options

All commands:

Option	Default	Description
--revisions N	1	Number of generate->reflect loops
--thread-id ID	auto	Checkpoint group ID
--research	off	Enable Tavily web search
--show-plan	off	Print planner steps
--show-critique	off	Print reflector critique
--show-sources	off	Print source table after output
--format text|md|json	text	Output format
--provider gemini|ollama|openai|openrouter	gemini	LLM provider
--model NAME	provider default	Override model name
--save	off	Save output to ~/.ana/outputs/<thread>.md

Study-only option:

Option	Default	Description
--quiz N	3	Number of quiz questions (0 means skip quiz)

Environment Variables

Variable	Required	Purpose
GOOGLE_API_KEY	Yes for default provider	Gemini API key
TAVILY_API_KEY	Only with --research	Tavily search API key
OPENAI_API_KEY	Only with --provider openai	OpenAI API key
OPENROUTER_API_KEY	Only with --provider openrouter	OpenRouter API key
OPENROUTER_SITE_URL	Optional	Sets HTTP-Referer header
OPENROUTER_APP_NAME	Optional	Sets X-Title header

Demo Media (Screenshots and Video)

Project Structure

ana_agent/
|- pyproject.toml
|- README.md
|- src/
|  \- ana/
|     |- __init__.py
|     |- cli.py
|     |- graph.py
|     |- state.py
|     |- nodes.py
|     |- prompts.py
|     |- render.py
|     |- study.py
|     \- llm.py
\- tests/
   \- test_render.py

Data and Checkpoints

Path	Contents
%USERPROFILE%/.ana/ana.sqlite	LangGraph checkpoint database
%USERPROFILE%/.ana/outputs/.md	Saved outputs

Running Tests

pip install -e ".[dev]"
pytest

Troubleshooting

1) Python version issues

Symptoms:

• dependency installation failures
• runtime import/type errors with newer Python versions

Fix:

• use Python 3.10-3.12 for this project
• recreate the virtual environment if needed

2) Missing API key errors

Symptoms:

• provider authentication errors
• research mode exits with key warning

Fix:

• set required key in your current shell or .env
• verify variable names exactly match docs

3) Provider/model mismatch

Symptoms:

• model not found or provider-specific errors

Fix:

• use a model valid for your selected provider
• for OpenRouter, openrouter/auto is a safe default

4) Network/DNS install failures

Symptoms:

• pip cannot download packages

Fix:

• retry after network stabilizes
• verify proxy/firewall settings if in a corporate environment

LangGraph Workflow

START
  |
  v
planner ---------------------------------------------+
  |                                                   | (--research)
  |-( no research )--> generator                      |
  |                     |                             v
  +-( --research  )--> research_plan --> generator  (same)
                                         |
                                         v
                                      reflector
                                         |
                             revision_count < max_revisions?
                               |- YES -------------------------------+
                               |  |-( no research )--> generator ----+
                               |  +-( --research )--> research_critique --> generator
                               +- NO --> END

Contributing

Contributions are welcome.

1. Fork the repo.
2. Create a feature branch.
3. Run tests locally.
4. Open a pull request with a clear description.

License

No license file is included yet. Add a LICENSE file before publishing if you want explicit reuse terms.

Acknowledgements

This project is inspired by planning, reflection, and revision-loop patterns taught in the AI Agents in LangGraph course by DeepLearning.AI.