QueryForge: Adaptive Retrieval
Optimization, Built Google-Native

§1 Problem Statement

Single-query retrieval is the number one production RAG failure mode. A single dense embedding is a reasonable default for a plain factual question, but it breaks down as soon as a query needs to synthesize across documents, compare entities, respect time, or match an exact identifier. Fixing this by hand — tuning chunk size, rewriting queries, adjusting top-k per use case — is slow and rarely converges on the right answer for every query shape a real corpus receives.

QueryForge exists because these four patterns recur across every enterprise corpus it has been pointed at, and each needs a structurally different retrieval strategy — not just a better prompt.

§2 Request Pipeline

Every call to POST /v1/optimize runs inside a single Cloud Run container, from request validation through to the fused, ranked, explained response. There is no separate vector database service, no separate reranker service, and no separate query-rewriting service — everything but the Gemini calls happens in-process.

§3 Pipeline Components

The query classifier, sub-query decomposer, and HyDE fallback are all Gemini 2.5 Flash-Lite calls against the Gemini Developer API — the free, API-key-based endpoint at aistudio.google.com, not the Vertex AI Gemini endpoint. That distinction matters for this deployment: the Developer API's free tier is billed on its own separate quota and never touches Cloud Billing, which is the account under the $0.01 cap. The classifier returns a query type, a confidence score, and the token-level signals that drove the decision — this classifier_explanation block is never omitted from a response.

Decomposition and HyDE are the two rewrite strategies QueryForge runs live in the build; step-back prompting and synonym-expansion rewrite are supported by the same classifier routing table but are not yet wired into the demo corpus evaluation — flagged honestly in §12 MVP Scope rather than presented as shipped.

Three retrieval strategies run concurrently via asyncio.gather() inside the same container, plus an optional reranker and the HyDE fallback above. Nothing here calls a paid API.

§4 Chunking Strategy

A content-type router selects chunking strategy per document class rather than applying uniform token splitting. Chunking config is versioned as YAML in Cloud Storage; the chunk version is stored as metadata on every Firestore document and returned in retrieval results.

§5 Pipeline Simulator

Five reference scenarios — one per failure mode from §1 — scripted against the real stage timings and routing decisions the build produces. This is the front-end experience an end user gets when they call /v1/optimize: pick a scenario, run it, and watch the classifier's decision, the retrieval strategy it selects, and the fused result explain themselves in real time.

// select a scenario and run simulation

§6 Design Validation

Three views on whether the routing actually helps: a before/after comparison on a real query, the grid search behind the adaptive-α defaults in §3.2, and where this pipeline sits in QueryForge's own MLOps lifecycle.

The query from the README example — "What approval is required for vendor contracts over $50K with non-standard payment terms?" — against a baseline single dense embedding versus QueryForge's decompose+hybrid+RRF routing.

Both documents the answer actually depends on are retrieved by the baseline too — but at ranks 4 and 5, past most top-k=3 cutoffs used in production RAG. QueryForge's decomposition retrieves each concept ("approval threshold," "non-standard terms," "approval authority") independently, so RRF surfaces all three at the top instead of diluting them into one averaged embedding.

The α defaults in §3.2 come from a grid search over strategy × α × reranker, evaluated on recall@10, MRR, and p50 latency against a HotpotQA-equivalent internal corpus. This is the shape of grid the config_recommendation block is drawn from.

The +31% recall figure quoted in the README is this bottom row against the dense-only baseline. The recommender only pays the reranker's ~600ms tax when the recall gain justifies it — which §3.2's routing table encodes as "multi-hop only."

§7 Google Cloud Architecture

Four layers, all Google-native. Nothing in this stack requires an account, API key, or credential outside Google Cloud and the Gemini Developer API.

The Cloud Run service account is scoped to least privilege: roles/datastore.user (Firestore), roles/storage.objectViewer (corpus bucket), roles/secretmanager.secretAccessor (Gemini API key), and roles/run.invoker for authenticated callers. No third-party vector database, SaaS annotation tool, or external hosting provider is in the request path — the only outbound call from the container is to the Gemini Developer API. On the free tier, Google may use API inputs/outputs to improve its models; enabling billing on the Gemini API opts out of that data use — a real trade-off for a $0.01-capped project, noted plainly in §13 Limitations rather than glossed over.

§8 Cost & Adoption Case

Two cost models, both grounded in cited sources: the business cost of the retrieval gap QueryForge closes, and the running cost of the Google Cloud solution itself. Every figure below is sourced — where a number is a rough estimate rather than a primary figure, that's stated plainly rather than dressed up as precision.

A hard cap only means something if it enforces itself before a bill is generated. The first design for this used a reactive Cloud Billing Budget → Pub/Sub → Cloud Function kill switch. Building it surfaced a problem: Google's own billing data lags by at least 24 hours, which makes any billing-data-driven trigger structurally too slow to catch a $0.01 overspend before it happens — by the time it fires, the overspend already occurred.

§9 Deployment

Single-command deploy to Cloud Run, followed immediately by the budget cap — the cap is treated as part of the deployment, not an optional afterthought.

# build + deploy the container, capped at 3 instances, 1Gi memory
gcloud run deploy queryforge \
  --source . \
  --region us-central1 \
  --max-instances 3 \
  --memory 1Gi \
  --allow-unauthenticated \
  --set-secrets GEMINI_API_KEY=gemini-api-key:latest

# hard budget cap — scoped to THIS project only
# does not touch the shared billing account or the other 3 apps on it
gcloud billing budgets create \
  --billing-account=$BILLING_ACCOUNT_ID \
  --display-name="queryforge-hard-cap" \
  --budget-amount=0.01USD \
  --threshold-rule=percent=1.0 \
  --filter-projects=projects/$QUERYFORGE_PROJECT_ID

§10 Architecture Decision Records

QueryForge's original design was open-source and local-first by default. Every ADR below records the point where that default was re-examined against two hard constraints — 100% Google Cloud, and a $0.01 ceiling on a shared billing account — and documents what was chosen instead and why.

§11 Data Schema

Firestore holds three collections: the vector-indexed corpus, the per-query log, and the config recommendations — all inside the Always-Free daily read/write allotment at demo volume.

// One document per chunk. `embedding` is indexed for Firestore Vector Search.
{
  "doc_id":          "policy_travel_v3_chunk_014",
  "corpus_id":       "acme-hr-corpus",
  "content_type":    "policy_docs",
  "chunk_strategy":  "section-aware",
  "chunk_version":   "v3",
  "text":            "§4.2 Non-standard payment terms require...",
  "embedding":       [0.0123, -0.0871, ...],   // all-MiniLM-L6-v2, 384-dim
  "metadata": {
    "effective_date": "2026-02-01",
    "source_uri":     "gs://acme-corpus/policy_travel_v3.pdf"
  }
}

// One document per /v1/optimize call.
{
  "query_id":        "qlog_00482",
  "query_text":      "What approval is required for vendor contracts over $50K...",
  "classifier_type": "multi-hop-entity",
  "confidence":      0.91,
  "sub_queries":     ["vendor contract approval threshold $50K", "..."],
  "alpha":           0.40,
  "reranked":        true,
  "latency_ms":      2340,
  "timestamp":       "2026-07-09T14:02:11Z"
}

§12 MVP Scope & Build Boundaries

Everything below runs inside the Always-Free tier and the $0.01 cap. Nothing here required a paid tier to demonstrate.

§13 Limitations & Known Issues

§14 Glossary