Let Gemini's Free Tier Do
Claude Code's Bulk Reading

export GEMINI_API_KEY="paste-your-key-here"   # better: read it from your password manager

#!/usr/bin/env python3
"""bulk_read.py - send long PUBLIC reading to Gemini's free tier; keep only answers it can quote.

Usage:  python3 bulk_read.py "your question" page1.html report.txt ...
Needs:  GEMINI_API_KEY in your environment (never written into this file).
"""
import html
import json
import os
import re
import sys
import urllib.error
import urllib.request

# "-latest" names follow Google's current model, so the script does not go stale.
# The lighter model is the fallback when the main one is busy (503) or out of free quota (429).
MODELS = [os.environ.get("GEMINI_MODEL", "gemini-flash-latest"), "gemini-flash-lite-latest"]
API = "https://generativelanguage.googleapis.com/v1beta/models/{}:generateContent"
# The free tier may use what you send to improve Google's products. Refuse obvious private files.
PRIVATE = re.compile(r"\.env|secret|password|credential|private|id_rsa|\.pem$|\.key$", re.I)


def text_of(path):
    raw = open(path, encoding="utf-8", errors="replace").read()
    if path.lower().endswith((".html", ".htm")):
        raw = re.sub(r"(?is)<(script|style)\b.*?</\1>", " ", raw)
        raw = html.unescape(re.sub(r"<[^>]+>", " ", raw))
    return re.sub(r"\s+", " ", raw).strip()


def norm(s):
    return re.sub(r"\s+", " ", s).strip().lower()


def main():
    if len(sys.argv) < 3:
        sys.exit(__doc__)
    key = os.environ.get("GEMINI_API_KEY")
    if not key:
        sys.exit("GEMINI_API_KEY is not set. See step 2 of the guide.")
    question, paths = sys.argv[1], sys.argv[2:]
    blocked = [p for p in paths if PRIVATE.search(p)]
    if blocked:
        sys.exit(f"Refusing to send files that look private: {blocked}")
    docs = {p: text_of(p) for p in paths}
    corpus = "\n\n".join(f"===== FILE: {p} =====\n{t}" for p, t in docs.items())
    prompt = (
        "Answer the question using ONLY the files below. Reply as JSON: "
        '{"findings":[{"claim":"...","quote":"...","file":"..."}]}. '
        "Each quote must be copied word for word from one file. "
        "If the files do not answer the question, reply with an empty findings list.\n\n"
        f"QUESTION: {question}\n\n{corpus}"
    )
    body = {"contents": [{"parts": [{"text": prompt}]}],
            "generationConfig": {"responseMimeType": "application/json", "temperature": 0}}
    data = None
    for model in MODELS:
        req = urllib.request.Request(API.format(model), data=json.dumps(body).encode(),
                                     headers={"Content-Type": "application/json", "x-goog-api-key": key})
        try:
            with urllib.request.urlopen(req, timeout=180) as r:
                data = json.load(r)
            break
        except urllib.error.HTTPError as e:
            # 503 = model busy. 429 = this model's free quota is used up (each model has its own).
            if e.code in (503, 429):
                print(f"{model}: HTTP {e.code}, trying the next model...", file=sys.stderr)
                continue
            sys.exit(f"Gemini returned HTTP {e.code}: {e.read()[:600].decode(errors='replace')}")
    if data is None:
        sys.exit("Every model was busy or out of free quota. Daily quotas reset at midnight Pacific.")
    reply = data["candidates"][0]["content"]["parts"][0]["text"]
    findings = json.loads(reply).get("findings", [])
    sources = [norm(t) for t in docs.values()]
    kept = dropped = 0
    for f in findings:
        quote = norm(str(f.get("quote", "")))
        if quote and any(quote in s for s in sources):
            kept += 1
            print(f"- {f.get('claim')}\n    \"{f.get('quote')}\"  [{f.get('file')}]")
        else:
            dropped += 1
    print(f"\n{kept} answer(s) verified against your files, {dropped} dropped (quote not found).")
    sys.exit(0 if kept else 2)


if __name__ == "__main__":
    main()

curl -sL -o rate-limits.html https://ai.google.dev/gemini-api/docs/rate-limits

python3 scripts/bulk_read.py "When do daily request quotas reset, and are limits per key or per project?" rate-limits.html
python3 scripts/bulk_read.py "What is the capital of Mongolia?" rate-limits.html

gemini-flash-latest: HTTP 429, trying the next model...
- Daily request quotas reset at midnight Pacific time.
    "Requests per day ( RPD ) quotas reset at midnight Pacific time."  [rate-limits.html]
- Rate limits are applied per project, not per API key.
    "Rate limits are applied per project, not per API key."  [rate-limits.html]

2 answer(s) verified against your files, 0 dropped (quote not found).

gemini-flash-latest: HTTP 429, trying the next model...

0 answer(s) verified against your files, 0 dropped (quote not found).

## Bulk reading
- For long PUBLIC reading (more than ~5 pages, a long report, a docs site), save the pages to
  research/ and run: python3 scripts/bulk_read.py "<one narrow question>" research/*
- Use only answers the script marks as verified. If it returns 0, the files do not say; do not guess.
- Never send private files (client documents, contracts, email, anything with keys or personal data).

{
  "permissions": {
    "allow": ["Bash(python3 scripts/bulk_read.py *)"]
  }
}