Gemini Smart Search

Use this skill when Gemini should be the search backend, but gateway-level web_search config is too static or too disruptive to change.

Purpose

This skill is a script-backed search workflow, not a gateway tool override.

It exists to provide:

• - dynamic Gemini model selection
• quota-aware fallback
• a separate Gemini API key path if desired
• structured JSON output
• no gateway restart requirement for model changes

Modes

Model routing is split into two layers:

• - display chain: human-facing preferred model family labels
• candidate API ids: the actual model ids to probe, especially for 3.x preview-era models

Current display chains:

• - cheap

• - balanced

• - deep

For 3.x models, do not assume the UI label is the raw API id. Probe candidate ids such as preview-suffixed names when needed.

Invocation

Run the Python script or the shell wrapper via exec and request JSON output.

Python is now the canonical entrypoint because it also loads repo-local .env.local when present. The shell wrapper remains a convenience layer.

Primary example (preferred):

CODEBLOCK0

Wrapper example (convenience only):

CODEBLOCK1

INLINECODE12 may work when run from the scripts/ directory, but it is not a supported interface for agents right now. Do not depend on it.

Output contract

Expect JSON with at least:

• - INLINECODE14
• INLINECODE15
• INLINECODE16
• INLINECODE17
• INLINECODE18
• INLINECODE19
• INLINECODE20
• INLINECODE21
• INLINECODE22
• INLINECODE23

Notes:

• - model_used is the actual probed API model id (for example gemini-3-flash-preview), not the human-facing display label.
• Citation URLs may initially be Google/Vertex grounding redirect URLs instead of canonical source URLs; treat that as a known current limitation.
• With --json, supported runtime paths should return structured JSON on both success and error. Invalid CLI arguments now also return JSON when --json is present.

API key policy

The script should prefer a dedicated key path for this skill, then fall back to the standard Gemini key.

Required key resolution order:

1. 1. SMART_SEARCH_GEMINI_API_KEY (primary declared env)
2. INLINECODE29 (compatibility fallback)

If neither key is present, the agent must explicitly ask the human for a Gemini API key before claiming setup is complete.

Do not store the key in tracked repository files. Prefer a repo-local, gitignored file such as .env.local.

See references/config.md.

When to use this skill instead of built-in web_search

Use this skill when:

• - you want Gemini-only search
• you want to test or isolate quota pools
• you want model routing without touching gateway config
• you want predictable JSON output for downstream orchestration

Do not use this skill when:

• - a normal built-in web_search is sufficient
• you need non-Gemini providers
• you only need to fetch and read a known URL (web_fetch)
• you need logged-in or JS-heavy page interaction (browser)

Fallback policy

Fallback only for errors like:

• - quota exceeded / 429
• model unavailable
• transient upstream failure

Do not silently fallback on obvious local/script bugs or invalid arguments.

References

• - references/config.md — environment variables and design notes
• INLINECODE37 — focused QA scope for v1 behavior and release gates
• INLINECODE38 — CLI-oriented QA outcomes from the current release cycle
• INLINECODE39 — adversarial agent-style misuse review
• INLINECODE40 — verified callable Gemini model IDs and mapping notes
• INLINECODE41 — when to return a GitHub issue URL for human escalation
• INLINECODE42 — artifact release checklist with current completion status
• INLINECODE43 — next small version scope and artifact policy
• INLINECODE44 — release notes for the current artifact
• INLINECODE45 — expected response shape
• INLINECODE46 — non-destructive local smoke checks for the scaffold
• INLINECODE47 — deterministic clean artifact export helper

Status

Python implementation is now wired for a first real version:

• - direct Gemini API call path
• Google Search grounding enabled
• mode-based model routing
• Python-side repo-local .env.local loading
• fallback across Gemini Flash-Lite / Flash variants for retryable upstream errors
• structured JSON output for orchestration

This is still intentionally minimal: it does not yet expose advanced tuning flags, caching, or richer citation post-processing.

Before publishing an artifact, consult references/release-checklist.md, review references/development-goals-v0.1.1.md, run scripts/prepare_artifact.sh, and publish the release note in references/release-notes-v0.1.1.md alongside the artifact.