deep-research

Deep Research

Web-grounded deep research via Gemini Interactions API.

IRON LAW: Always Use the Script

NEVER call the Gemini Interactions API manually. ALWAYS use bun deep-research.ts. This is non-negotiable.

cd "${CLAUDE_SKILL_DIR}" && bun deep-research.ts "research query"

The script handles model selection, interaction submission, polling with retries, timeout enforcement, and report formatting. Calling the Interactions API by hand means you skip retry logic, miss the 65-minute timeout guard, and lose the saved report file.

When to Use

Deep Research is the LAST RESORT in the librarian's source hierarchy. It costs $1-7 per query, takes minutes not seconds, and produces a broad web-grounded report rather than precise academic citations.

User needs information on a topic
    |
    v
Check curated sources FIRST (all must be exhausted):
  1. Paperpile bib (local library)
  2. Google Scholar (scholar search/lookup)
  3. Consensus (consensus search)
  4. NLM notebooks (existing sources)
  5. Readwise (highlights/full-text)
    |
    v
Are there still significant gaps?
    |
    +-- NO --> Stop. Curated sources are sufficient.
    |
    +-- YES
          |
          v
        Has the user explicitly asked for broader/deeper research?
          |
          +-- NO --> Report gaps, suggest deep research, WAIT for approval.
          |
          +-- YES --> Run deep-research.ts

Trigger signals (use this skill):

• User says "deep research", "thorough investigation", "comprehensive report"
• User explicitly asks for web-grounded synthesis beyond academic databases
• Curated sources have been exhausted and user wants more

NOT-triggers (do NOT use this skill):

• User wants a specific known paper -- use Scholar or Consensus
• User wants papers from their own library -- use Paperpile bib or Readwise
• User wants citation metadata -- use Scholar with --bibtex
• User has not exhausted curated sources yet
• User has not explicitly approved the cost

Commands

Basic (thorough report)

cd "${CLAUDE_SKILL_DIR}" && bun deep-research.ts "What is the current state of mandatory climate disclosure regulation worldwide?"

Fast (quick scan)

cd "${CLAUDE_SKILL_DIR}" && bun deep-research.ts --fast "ESG disclosure enforcement mechanisms"

Resume polling an existing interaction

cd "${CLAUDE_SKILL_DIR}" && bun deep-research.ts --status <interaction-id>

JSON output (raw interaction object)

cd "${CLAUDE_SKILL_DIR}" && bun deep-research.ts --json "corporate governance reform trends"

Models

Model	Flag	Queries	Time	Cost	Use when
deep-research-max	(default)	~160 web queries	5-20 min	~$3-7	Thorough reports, literature reviews, multi-faceted questions
deep-research	--fast	~80 web queries	2-10 min	~$1-3	Quick scans, narrow questions, time-sensitive requests

Cost Warning

$1-7 per query. NEVER auto-invoke. Always ask the user first.

This is the most expensive tool in the librarian's toolkit. Before every invocation:

1. Confirm the user explicitly requested deep research
2. Report which curated sources were already checked and what gaps remain
3. State the estimated cost range ($1-3 for fast, $3-7 for thorough)
4. Wait for the user's go-ahead

Cost Facts

• Even --fast costs $1-3 and takes 2-10 minutes; Scholar, Consensus, Paperpile, NLM, and Readwise are free and return in seconds. Reaching for deep research because it seems "faster than searching multiple sources" is counterproductive on its own terms.
• "The curated sources didn't have enough" is only a fact after ALL five (Paperpile, Scholar, Consensus, NLM, Readwise) have been tried. Before that it is an assumption — and $3-7 spent on an assumption without the user's go-ahead is unauthorized spending.

Integration with Librarian Workflow

Paperpile bib  -->  Scholar  -->  Consensus  -->  NLM / Readwise
       (local)       (free)        (free)          (free)
                                                      |
                                                      v
                                          [GAPS IDENTIFIED + USER ASKS]
                                                      |
                                                      v
                                          Deep Research (THIS SKILL)
                                            $1-7, 2-20 min
                                                      |
                                                      v
                                          Curate results to NLM
                                          (save report, extract key sources)

After deep research completes:

1. Present the report to the user
2. Extract key sources cited in the report
3. If the user wants to keep specific sources, add them to NLM notebooks
4. The report is also saved to /tmp/deep-research-<id>.md for reference

Red Flags

#	Action	Why Wrong	Do Instead
1	Using before checking curated sources	Scholar, Consensus, Paperpile, NLM, Readwise are free and fast	Exhaust all five curated sources first
2	Using for known paper lookup	Deep Research returns web-grounded reports, not citation metadata	Use scholar lookup --bibtex or scholar cite
3	Launching without user's explicit request	$1-7 per query; unauthorized spending violates trust	Report gaps, state cost, wait for go-ahead
4	Calling Interactions API directly (without the script)	Skips retry logic, timeout guard, report file save	Always use bun deep-research.ts
5	Ignoring the report and re-searching the same topic	Wastes another $1-7 for information you already have	Read the saved report at /tmp/deep-research-<id>.md

Environment

Variable	Required	Description
GOOGLE_API_KEY	Yes	Gemini API key with Deep Research access

Timeout: 65 minutes maximum polling duration (covers the API's 60-min hard limit plus buffer).

Polling interval: 10 seconds between status checks.

Retries: Up to 3 retries on transient errors (503, 429, service_unavailable, rate_limit).

Output

The script prints the research report to stdout as Markdown. It also saves the report to /tmp/deep-research-<interaction-id>.md for later reference.

With --json, it prints the full interaction object as JSON (useful for debugging or extracting structured metadata).

On failure, it prints the error to stderr and exits non-zero.

Limitations

• Beta API -- the Gemini Interactions API is in preview; behavior may change
• No structured output -- reports are free-form Markdown, not JSON-structured citations
• Max 60 minutes -- the API enforces a hard time limit on research sessions
• Cost per query -- $1-7 depending on model; no free tier
• Web-grounded, not academic-specific -- results include news, blogs, and general web sources alongside academic content; always cross-reference claims against Scholar/Consensus for academic rigor
• No incremental results -- the report arrives all at once when polling completes; no streaming