DeepSearch

DeepSearch is an attractive, terminal-first deep research assistant built with Google ADK.
It converts a plain question into a structured, high-signal answer:

Quick Summary
Key Points
Deep Dive
Final Takeaway

When a Gemini model is selected, DeepSearch can use Google Search tool calls for live sources.
When a Gemma model is selected, it automatically disables search tools to avoid compatibility failures.

Highlights

Clean CLI UX with rich
Structured output format for better readability
Model-aware tool gating (Gemini: search on, Gemma: search off)
Easy .env configuration
Works well for quick research workflows and note-taking

Architecture

User Input (CLI)
    |
    v
cli.py
    |
    v
agent.py (ADK LlmAgent)
    |- instruction template
    |- model from RESEARCH_MODEL
    |- tools:
         - Gemini models -> [google_search]
         - Gemma models  -> []
    |
    v
Runner + Session Service
    |
    v
Structured Response

Project Structure

deep_research_agent/
├── agent.py          # Agent definition and model/tool logic
├── cli.py            # Interactive CLI loop and rendering
├── requirements.txt  # Python dependencies
├── .env.example      # Safe env template
└── README.md         # Documentation

Quick Start

1) Create and activate a virtual environment

python3 -m venv .venv
source .venv/bin/activate

2) Install dependencies

python3 -m pip install -r requirements.txt

3) Configure environment

cp .env.example .env

Set values in .env:

GOOGLE_API_KEY=YOUR_NEW_KEY
GOOGLE_GENAI_USE_VERTEXAI=FALSE
RESEARCH_MODEL=gemma-3-27b-it

4) Run

set -a; source .env; set +a; python3 cli.py

CLI Commands

Command	Description
`/help`	Show command help
`/clear`	Clear terminal screen
`/new`	Start a fresh session
`/model`	Show active model
`/exit`	Quit the app

Model Options

Pick a model by setting RESEARCH_MODEL in .env.

Model ID	Search Tool Support	Best For
`gemma-3-27b-it`	No	Stable structured responses with lower cost
`gemma-3-12b-it`	No	Faster responses
`gemini-2.0-flash`	Yes	Source-backed research with web tool calls

Compatibility note

Gemma models currently do not support the ADK Google Search tool in this project flow.
DeepSearch handles this automatically in code.

Example Session

🔬 DeepSearch > Explain quantum computing in simple words with examples

Expected shape:

Topic
Quick Summary
Key Points
Deep Dive
Final Takeaway

Troubleshooting

1) `API key not valid`

Verify .env has a real key (not placeholder)
Regenerate key at Google AI Studio API Key
Reload environment and run again

2) `429 RESOURCE_EXHAUSTED`

Your project/key quota is exhausted.

Rate limits: Gemini API rate limits
Usage dashboard: AI Dev rate-limit dashboard
Retry after the delay shown in the error message

3) `Google search tool is not supported for model ...`

Use a Gemini model if you need live web search (gemini-2.0-flash)
Or keep Gemma and run without search tool support

Security Best Practices

Never commit real API keys
Keep .env private
Rotate keys immediately if exposed
Use .env.example with placeholders only

Roadmap

Save results to markdown files
Add streaming output mode
Add model fallback strategy
Add persistent session history
Add prompt presets for common research tasks

Credits

Built by Gokulakrishnan.

🔬 DeepSearch — Deep Research Agent CLI

Point-by-point research answers with sources, powered by Google Gemma 4 via Google ADK

  ██████╗ ███████╗███████╗██████╗ ███████╗███████╗ █████╗ ██████╗  ██████╗██╗  ██╗
  ██╔══██╗██╔════╝██╔════╝██╔══██╗██╔════╝██╔════╝██╔══██╗██╔══██╗██╔════╝██║  ██║
  ██║  ██║█████╗  █████╗  ██████╔╝███████╗█████╗  ███████║██████╔╝██║     ███████║
  ██║  ██║██╔══╝  ██╔══╝  ██╔═══╝ ╚════██║██╔══╝  ██╔══██║██╔══██╗██║     ██╔══██║
  ██████╔╝███████╗███████╗██║     ███████║███████╗██║  ██║██║  ██║╚██████╗██║  ██║
  ╚═════╝ ╚══════╝╚══════╝╚═╝     ╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝

✨ What It Does

DeepSearch is a CLI-based deep research agent that:

📌 Breaks down answers point-by-point — clear, numbered key points
🔗 Provides source links — real URLs from web search, not hallucinated
📋 Gives a quick summary — 2-3 sentences you can understand instantly
🧠 Deep-dives the topic — explains like you're 16, no jargon
✅ Final takeaway — the single most important thing to know

📁 Project Structure

deep_research_agent/
├── agent.py          # Core agent logic (ADK + Gemma 4)
├── cli.py            # CLI interface with rich terminal UI
├── requirements.txt  # Python dependencies
├── .env.example      # Environment variable template
└── README.md         # This file

🚀 Quick Start

1. Clone / Set up

cd deep_research_agent
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

2. Install Dependencies

pip install -r requirements.txt

3. Get Your API Key

Go to https://aistudio.google.com/apikey
Create a free API key (no credit card needed)
Copy the key

4. Configure Environment

cp .env.example .env

Edit .env and paste your key:

GOOGLE_API_KEY=AIzaSy...your_actual_key_here
GOOGLE_GENAI_USE_VERTEXAI=FALSE
RESEARCH_MODEL=gemma-3-27b-it

5. Run DeepSearch

# Load env and run
export $(cat .env | xargs) && python cli.py

# Or set key directly
GOOGLE_API_KEY=your_key python cli.py

💬 Usage

Once running, just type your research question:

🔬 DeepSearch > What is quantum computing and how does it work?
🔬 DeepSearch > Latest AI breakthroughs in 2025
🔬 DeepSearch > Explain blockchain simply with real examples
🔬 DeepSearch > How does CRISPR gene editing work?

CLI Commands

Command	Description
`/help`	Show help and available commands
`/clear`	Clear the terminal screen
`/new`	Start a fresh session (new history)
`/model`	Show which model is active
`/exit`	Quit DeepSearch

🤖 Model Options

Edit RESEARCH_MODEL in your .env:

Model	Speed	Quality	Notes
`gemma-3-27b-it`	Medium	⭐⭐⭐⭐⭐	Best open model (default)
`gemma-3-12b-it`	Fast	⭐⭐⭐⭐	Lighter, still great
`gemini-2.0-flash`	Fast	⭐⭐⭐⭐⭐	Gemini — very capable
`gemini-2.5-flash-preview-04-17`	Fast	⭐⭐⭐⭐⭐	Latest Gemini Flash

📤 Example Output

### 🔍 TOPIC: What is quantum computing?

---

### 📋 QUICK SUMMARY
Quantum computing uses quantum mechanics to process information in ways 
classical computers can't. Instead of bits (0 or 1), it uses "qubits" 
that can be both at once, making it exponentially more powerful for 
certain problems.

---

### 📌 KEY POINTS

**Point 1: What is a Qubit?**
→ Unlike classical bits that are 0 OR 1, qubits can be 0, 1, or both 
  simultaneously (called superposition). This is the core difference.
🔗 Source: https://quantum.google/learn/

**Point 2: Why It Matters**
→ Quantum computers can solve certain problems millions of times faster 
  than any classical computer — like breaking encryption or drug discovery.
🔗 Source: https://www.ibm.com/quantum

...

### ✅ FINAL TAKEAWAY
Quantum computing isn't just a faster computer — it's a fundamentally 
different way of processing information that will transform cryptography, 
medicine, and AI.

🛠 How It Works

User Query
    │
    ▼
Google ADK Runner
    │
    ├── LlmAgent (Gemma 4 / Gemini)
    │       └── System Prompt: structured research format
    │
    └── google_search Tool
            └── Live web search for real sources
                    │
                    ▼
            Structured Response:
            Summary → Key Points → Deep Dive → Takeaway

📦 Dependencies

google-adk — Google Agent Development Kit
google-genai — Google AI Python SDK
rich — Beautiful terminal output
python-dotenv — Environment variable loading

🔑 Free Tier Info

Google AI Studio offers a free tier with Gemma models:

✅ No credit card required
✅ Generous rate limits for personal use
✅ Access to Gemma 3 (27B, 12B) and Gemini Flash
🔗 Get key: aistudio.google.com/apikey

🧑‍💻 Built With

Google ADK v1.30+ (with Gemma 4 support added in v1.30)
Google Gemma 3/4 models via Gemini API
Rich terminal UI
Python asyncio for async ADK runner

Built by Gokulakrishnan | gokulakrishnan.dev

Name		Name	Last commit message	Last commit date
bin		bin
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
agent.py		agent.py
cli.py		cli.py
package.json		package.json
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

DeepSearch

Highlights

Architecture

Project Structure

Quick Start

1) Create and activate a virtual environment

2) Install dependencies

3) Configure environment

4) Run

CLI Commands

Model Options

Compatibility note

Example Session

Troubleshooting

1) API key not valid

2) 429 RESOURCE_EXHAUSTED

3) Google search tool is not supported for model ...

Security Best Practices

Roadmap

Credits

🔬 DeepSearch — Deep Research Agent CLI

✨ What It Does

📁 Project Structure

🚀 Quick Start

1. Clone / Set up

2. Install Dependencies

3. Get Your API Key

4. Configure Environment

5. Run DeepSearch

💬 Usage

CLI Commands

🤖 Model Options

📤 Example Output

🛠 How It Works

📦 Dependencies

🔑 Free Tier Info

🧑‍💻 Built With

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

1) `API key not valid`

2) `429 RESOURCE_EXHAUSTED`

3) `Google search tool is not supported for model ...`