gemini-skill-install 0.1.1__tar.gz

gemini_skill_install-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 reshinto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gemini_skill_install-0.1.1/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE
+include VERSION
+include SKILL.md
+recursive-include core *.py
+recursive-include adapters *.py
+recursive-include reference *.md
+recursive-include registry *.json
+recursive-include scripts *.py *.sh
+include setup/install.py
+include setup/update.py
+include setup/requirements.txt

gemini_skill_install-0.1.1/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: gemini-skill-install
+Version: 0.1.1
+Summary: Bootstrap installer for the gemini Claude Code skill
+Home-page: https://github.com/reshinto/gemini-skill
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions>=4.0; python_version < "3.10"
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# gemini-skill
+
+A Claude Code skill for broad Gemini REST API access — text generation, multimodal input, image/video/music generation, embeddings, caching, batch processing, search grounding, code execution, file search, and more.
+
+## Quick Start
+
+1. **Install without cloning**
+   ```bash
+   uvx --from git+https://github.com/reshinto/gemini-skill gemini-skill-install
+   ```
+   Or with `pipx`:
+   ```bash
+   pipx run --spec git+https://github.com/reshinto/gemini-skill.git gemini-skill-install
+   ```
+   Tagged releases build and publish the same bootstrap installer to PyPI. After the
+   first PyPI release, these simplify to:
+   ```bash
+   uvx gemini-skill-install
+   pipx install gemini-skill-install
+   ```
+
+2. **Fallback: install from a clone or release tarball**
+   ```bash
+   git clone https://github.com/reshinto/gemini-skill.git
+   cd gemini-skill
+   python3 setup/install.py
+   ```
+   Both installer entry points call the same core installer. They:
+   - Copy operational files to `~/.claude/skills/gemini/`
+   - Includes the runtime payload: `SKILL.md`, `VERSION`, `core`, `adapters`, `reference`, `registry`, `scripts`, and `setup/{update.py,requirements.txt}`
+   - Creates `~/.claude/skills/gemini/.venv` with pinned `google-genai`
+   - Verifies install integrity via SHA-256 checksums
+   - Prompts for Gemini API key (hidden input)
+   - Merges env block into `~/.claude/settings.json` (with conflict resolution)
+   - Reuses an existing skill-local `.venv` on overwrite installs
+
+3. **Set your Gemini API key** (get one at [aistudio.google.com/apikey](https://aistudio.google.com/apikey))
+
+   The installer prompts you interactively. If you need to manually edit, add/update the `env` block in `~/.claude/settings.json`:
+   ```json
+   {
+     "env": {
+       "GEMINI_API_KEY": "AIzaSy...",
+       "GEMINI_IS_SDK_PRIORITY": "true",
+       "GEMINI_IS_RAWHTTP_PRIORITY": "false",
+       "GEMINI_LIVE_TESTS": "0"
+     }
+   }
+   ```
+   Claude Code injects these values into the process env at session start.
+
+   **Do NOT edit the repo-root `.env`** — that's only for local development from a clone. For the installed skill, use `~/.claude/settings.json` exclusively.
+
+4. **Fully restart Claude Code** (⌘Q on macOS, not "Reload Window"). Skill discovery and env injection happen at IDE launch.
+
+5. **Use it in Claude Code**
+   ```
+   /gemini text "Explain quantum computing"
+   ```
+
+## Architecture
+
+![Dual-backend transport architecture](docs/diagrams/architecture-dual-backend.svg)
+
+## Features
+
+- Text generation, multimodal input, structured output, function calling
+- Image generation (Nano Banana, Imagen 3), video generation (Veo), music generation (Lyria 3)
+- Embeddings, context caching, batch processing, token counting
+- Google Search grounding, Google Maps grounding, code execution
+- File API, File Search / hosted RAG
+- Deep Research (Interactions API), Computer Use (preview)
+- Live API realtime sessions (async dispatch)
+- Automatic model routing by task type and complexity
+- Two-phase cost tracking (pre-flight estimate + post-response)
+- Multi-turn conversation sessions with Gemini
+- Dual transport backend — google-genai SDK primary + urllib raw HTTP fallback, user never picks
+
+## Prerequisites
+
+- Python 3.9+
+- A Gemini API key
+- `google-genai==1.33.0` (installed automatically by the installer into `~/.claude/skills/gemini/.venv`)
+
+## Documentation
+
+**Start here:** [docs/README.md](docs/README.md) — the single index hub for every doc and reference page.
+
+### Most-read pages
+
+- **[Design patterns](docs/design-patterns.md)** — what / where / why / how for every architectural decision in the codebase (Adapter, Facade, Capability registry, Coordinator, Anti-corruption layer, Atomic write, SHA-256 integrity, etc.). Read this first if you're touching the code.
+- **[Security & secrets storage](docs/security.md)** — full threat model + the "How the skill stores secrets and why it's safe" section explaining where `GEMINI_API_KEY` lives, why the chosen storage location is safe, alternatives rejected, and rotation procedure.
+- **[Usage tour](docs/usage-tour.md)** — 16 end-to-end examples (text, multimodal, streaming, function calling, search grounding, image gen, batch, caching, sessions, dry-run vs `--execute`, error recovery).
+- **[Per-command reference](reference/index.md)** — detailed docs for all 22 commands. Every page covers what / which model(s) / why (vs alternatives) / how (concrete usage).
+
+### Reference catalogs (single-page lookups)
+
+- **[Flags reference](docs/flags-reference.md)** — every CLI flag the skill accepts, grouped by category (privacy, cost, execution, I/O), with rationale.
+- **[Models reference](docs/models-reference.md)** — every model in the registry with cost tier, capabilities, and "when to pick this over siblings".
+
+### Architecture & internals
+
+- [Architecture](docs/architecture.md) — System design, module layout, dual-backend transport diagram, "Why SKILL.md is terse" (token optimization rationale).
+- [How It Works](docs/how-it-works.md) — End-to-end execution trace.
+- [Model Routing](docs/model-routing.md) — Router decision tree.
+- [Capabilities](docs/capabilities.md) — Feature matrix with status and limitations.
+- [Commands](docs/commands.md) — Command index by capability family.
+
+### Operating the skill
+
+- [Installation](docs/install.md) — Setup, troubleshooting, API key configuration.
+- [Usage](docs/usage.md) — Getting started and common workflows.
+- [Update & Sync](docs/update-sync.md) — Install mechanism, release checking, rollback, and release publishing.
+
+### Contributors
+
+- [Contributing](docs/contributing.md) — Adding adapters, code style, PRs, strict typing rule.
+- [Testing](docs/testing.md) — Running tests, writing tests, coverage, live API smoke tests.
+- [Python Design](docs/python-guide.md) — Python 3.9+ floor, no `typing.Any`, idiomatic patterns.
+
+### Diagrams
+
+All diagrams are committed as both Mermaid source (`.mmd`) and rendered SVG with white background under [docs/diagrams/](docs/diagrams/):
+
+- `architecture-dual-backend.svg` — high-level dual-backend transport
+- `coordinator-decision-flow.svg` — fallback eligibility + capability gate
+- `backend-priority-matrix.svg` — env flag truth table
+- `auth-resolution.svg` — `GEMINI_API_KEY` precedence
+- `install-flow.svg` — installer pipeline
+- `secrets-flow.svg` — secret storage data flow + threat boundaries
+- `design-patterns-overview.svg` — class-diagram-style pattern map
+- `command-dispatch-flow.svg` — request lifecycle from `/gemini` to stdout
+- `token-optimization-flow.svg` — why SKILL.md stays small
+
+Regenerate any diagram with `bash scripts/render_diagrams.sh [name]`.
+
+## Releases
+
+Tagged releases (`v*`) run [.github/workflows/release.yml](.github/workflows/release.yml). The
+workflow verifies `VERSION`, builds the GitHub release tarball plus Python
+wheel/sdist artifacts, writes `checksums.txt`, creates the GitHub Release, and
+publishes `gemini-skill-install` to PyPI via Trusted Publishing.
+
+Maintainers can cut a release tag from the current [VERSION](VERSION) with:
+
+```bash
+bash scripts/tag_release.sh
+```
+
+See [docs/update-sync.md](docs/update-sync.md) for the full release flow.
+
+## Backends
+
+By default, the skill uses the **google-genai SDK as the primary backend**, with **urllib raw HTTP as the fallback**. Both backends return identical response shapes via the `normalize` layer — adapters never know which ran.
+
+To invert backend priority (raw HTTP primary, SDK fallback), edit `~/.claude/settings.json`:
+```json
+{
+  "env": {
+    "GEMINI_IS_SDK_PRIORITY": "false",
+    "GEMINI_IS_RAWHTTP_PRIORITY": "true"
+  }
+}
+```
+
+Restart Claude Code. Both flags cannot be false (ConfigError), and if both are true, SDK wins.
+
+## License
+
+MIT

gemini_skill_install-0.1.1/README.md

@@ -0,0 +1,170 @@
+# gemini-skill
+
+A Claude Code skill for broad Gemini REST API access — text generation, multimodal input, image/video/music generation, embeddings, caching, batch processing, search grounding, code execution, file search, and more.
+
+## Quick Start
+
+1. **Install without cloning**
+   ```bash
+   uvx --from git+https://github.com/reshinto/gemini-skill gemini-skill-install
+   ```
+   Or with `pipx`:
+   ```bash
+   pipx run --spec git+https://github.com/reshinto/gemini-skill.git gemini-skill-install
+   ```
+   Tagged releases build and publish the same bootstrap installer to PyPI. After the
+   first PyPI release, these simplify to:
+   ```bash
+   uvx gemini-skill-install
+   pipx install gemini-skill-install
+   ```
+
+2. **Fallback: install from a clone or release tarball**
+   ```bash
+   git clone https://github.com/reshinto/gemini-skill.git
+   cd gemini-skill
+   python3 setup/install.py
+   ```
+   Both installer entry points call the same core installer. They:
+   - Copy operational files to `~/.claude/skills/gemini/`
+   - Includes the runtime payload: `SKILL.md`, `VERSION`, `core`, `adapters`, `reference`, `registry`, `scripts`, and `setup/{update.py,requirements.txt}`
+   - Creates `~/.claude/skills/gemini/.venv` with pinned `google-genai`
+   - Verifies install integrity via SHA-256 checksums
+   - Prompts for Gemini API key (hidden input)
+   - Merges env block into `~/.claude/settings.json` (with conflict resolution)
+   - Reuses an existing skill-local `.venv` on overwrite installs
+
+3. **Set your Gemini API key** (get one at [aistudio.google.com/apikey](https://aistudio.google.com/apikey))
+
+   The installer prompts you interactively. If you need to manually edit, add/update the `env` block in `~/.claude/settings.json`:
+   ```json
+   {
+     "env": {
+       "GEMINI_API_KEY": "AIzaSy...",
+       "GEMINI_IS_SDK_PRIORITY": "true",
+       "GEMINI_IS_RAWHTTP_PRIORITY": "false",
+       "GEMINI_LIVE_TESTS": "0"
+     }
+   }
+   ```
+   Claude Code injects these values into the process env at session start.
+
+   **Do NOT edit the repo-root `.env`** — that's only for local development from a clone. For the installed skill, use `~/.claude/settings.json` exclusively.
+
+4. **Fully restart Claude Code** (⌘Q on macOS, not "Reload Window"). Skill discovery and env injection happen at IDE launch.
+
+5. **Use it in Claude Code**
+   ```
+   /gemini text "Explain quantum computing"
+   ```
+
+## Architecture
+
+![Dual-backend transport architecture](docs/diagrams/architecture-dual-backend.svg)
+
+## Features
+
+- Text generation, multimodal input, structured output, function calling
+- Image generation (Nano Banana, Imagen 3), video generation (Veo), music generation (Lyria 3)
+- Embeddings, context caching, batch processing, token counting
+- Google Search grounding, Google Maps grounding, code execution
+- File API, File Search / hosted RAG
+- Deep Research (Interactions API), Computer Use (preview)
+- Live API realtime sessions (async dispatch)
+- Automatic model routing by task type and complexity
+- Two-phase cost tracking (pre-flight estimate + post-response)
+- Multi-turn conversation sessions with Gemini
+- Dual transport backend — google-genai SDK primary + urllib raw HTTP fallback, user never picks
+
+## Prerequisites
+
+- Python 3.9+
+- A Gemini API key
+- `google-genai==1.33.0` (installed automatically by the installer into `~/.claude/skills/gemini/.venv`)
+
+## Documentation
+
+**Start here:** [docs/README.md](docs/README.md) — the single index hub for every doc and reference page.
+
+### Most-read pages
+
+- **[Design patterns](docs/design-patterns.md)** — what / where / why / how for every architectural decision in the codebase (Adapter, Facade, Capability registry, Coordinator, Anti-corruption layer, Atomic write, SHA-256 integrity, etc.). Read this first if you're touching the code.
+- **[Security & secrets storage](docs/security.md)** — full threat model + the "How the skill stores secrets and why it's safe" section explaining where `GEMINI_API_KEY` lives, why the chosen storage location is safe, alternatives rejected, and rotation procedure.
+- **[Usage tour](docs/usage-tour.md)** — 16 end-to-end examples (text, multimodal, streaming, function calling, search grounding, image gen, batch, caching, sessions, dry-run vs `--execute`, error recovery).
+- **[Per-command reference](reference/index.md)** — detailed docs for all 22 commands. Every page covers what / which model(s) / why (vs alternatives) / how (concrete usage).
+
+### Reference catalogs (single-page lookups)
+
+- **[Flags reference](docs/flags-reference.md)** — every CLI flag the skill accepts, grouped by category (privacy, cost, execution, I/O), with rationale.
+- **[Models reference](docs/models-reference.md)** — every model in the registry with cost tier, capabilities, and "when to pick this over siblings".
+
+### Architecture & internals
+
+- [Architecture](docs/architecture.md) — System design, module layout, dual-backend transport diagram, "Why SKILL.md is terse" (token optimization rationale).
+- [How It Works](docs/how-it-works.md) — End-to-end execution trace.
+- [Model Routing](docs/model-routing.md) — Router decision tree.
+- [Capabilities](docs/capabilities.md) — Feature matrix with status and limitations.
+- [Commands](docs/commands.md) — Command index by capability family.
+
+### Operating the skill
+
+- [Installation](docs/install.md) — Setup, troubleshooting, API key configuration.
+- [Usage](docs/usage.md) — Getting started and common workflows.
+- [Update & Sync](docs/update-sync.md) — Install mechanism, release checking, rollback, and release publishing.
+
+### Contributors
+
+- [Contributing](docs/contributing.md) — Adding adapters, code style, PRs, strict typing rule.
+- [Testing](docs/testing.md) — Running tests, writing tests, coverage, live API smoke tests.
+- [Python Design](docs/python-guide.md) — Python 3.9+ floor, no `typing.Any`, idiomatic patterns.
+
+### Diagrams
+
+All diagrams are committed as both Mermaid source (`.mmd`) and rendered SVG with white background under [docs/diagrams/](docs/diagrams/):
+
+- `architecture-dual-backend.svg` — high-level dual-backend transport
+- `coordinator-decision-flow.svg` — fallback eligibility + capability gate
+- `backend-priority-matrix.svg` — env flag truth table
+- `auth-resolution.svg` — `GEMINI_API_KEY` precedence
+- `install-flow.svg` — installer pipeline
+- `secrets-flow.svg` — secret storage data flow + threat boundaries
+- `design-patterns-overview.svg` — class-diagram-style pattern map
+- `command-dispatch-flow.svg` — request lifecycle from `/gemini` to stdout
+- `token-optimization-flow.svg` — why SKILL.md stays small
+
+Regenerate any diagram with `bash scripts/render_diagrams.sh [name]`.
+
+## Releases
+
+Tagged releases (`v*`) run [.github/workflows/release.yml](.github/workflows/release.yml). The
+workflow verifies `VERSION`, builds the GitHub release tarball plus Python
+wheel/sdist artifacts, writes `checksums.txt`, creates the GitHub Release, and
+publishes `gemini-skill-install` to PyPI via Trusted Publishing.
+
+Maintainers can cut a release tag from the current [VERSION](VERSION) with:
+
+```bash
+bash scripts/tag_release.sh
+```
+
+See [docs/update-sync.md](docs/update-sync.md) for the full release flow.
+
+## Backends
+
+By default, the skill uses the **google-genai SDK as the primary backend**, with **urllib raw HTTP as the fallback**. Both backends return identical response shapes via the `normalize` layer — adapters never know which ran.
+
+To invert backend priority (raw HTTP primary, SDK fallback), edit `~/.claude/settings.json`:
+```json
+{
+  "env": {
+    "GEMINI_IS_SDK_PRIORITY": "false",
+    "GEMINI_IS_RAWHTTP_PRIORITY": "true"
+  }
+}
+```
+
+Restart Claude Code. Both flags cannot be false (ConfigError), and if both are true, SDK wins.
+
+## License
+
+MIT

gemini_skill_install-0.1.1/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gemini
+description: Gemini API — text generation, image/video/music generation, embeddings, search grounding, maps grounding, context caching, batch processing, code execution, function calling, file search/RAG, computer use, deep research, and more.
+disable-model-invocation: true
+---
+
+## Usage
+
+Run: `python3 "${CLAUDE_SKILL_DIR}/scripts/gemini_run.py" <command> [args]`
+
+The launcher self-routes: if the skill-local virtual environment exists at `${CLAUDE_SKILL_DIR}/.venv`, it re-execs into `${CLAUDE_SKILL_DIR}/.venv/bin/python` so the dual-backend SDK is loaded; otherwise it runs under whichever Python invoked it (the raw HTTP backend works without google-genai installed).
+
+See `${CLAUDE_SKILL_DIR}/reference/index.md` for the full command map.
+For commands with flags or `--execute`, read `${CLAUDE_SKILL_DIR}/reference/<command>.md` first.
+
+## How transport works
+
+All commands route through `scripts/gemini_run.py` which dispatches to the right adapter. The adapter calls a single `api_call` / `stream_generate_content` / `upload_file` facade that picks the right backend automatically based on `GEMINI_IS_SDK_PRIORITY` / `GEMINI_IS_RAWHTTP_PRIORITY` environment variables. **You do not need to know which backend is active** — every command has identical CLI surface, identical output shape, and identical error format regardless of whether the SDK or raw HTTP path handled the call.
+
+## Rules
+
+- Mutating operations and mutating subcommands require `--execute`. Default is dry-run.
+- Privacy-sensitive commands (search grounding, maps grounding, computer use, deep research) are handled internally by dispatch; callers do not pass a separate privacy flag.
+- Pass user input as single opaque argv values (quoted).
+- Use stdin or temp files for complex/multiline content.
+- Never reconstruct shell commands by concatenating user text.
+- Multi-turn sessions: use `--session <id>` to start/continue, `--continue` for most recent.
+- Large responses (>50KB) and all media generation save to a file and return only the path + metadata.
+
+## Quick commands
+
+- `help` — list all commands
+- `models` — list available models from registry
+- `text "prompt"` — generate text
+- `multimodal "prompt" --file path.pdf` — analyze files
+- `embed "text"` — generate embeddings
+- `image_gen "prompt" --execute` — generate an image

gemini_skill_install-0.1.1/VERSION

@@ -0,0 +1 @@
+0.1.1

gemini_skill_install-0.1.1/adapters/data/batch.py

@@ -0,0 +1,112 @@
+"""Batch API adapter — submit, list, get, and cancel batch jobs.
+
+Submits multiple requests for async processing at reduced cost.
+Mutating operations (create, cancel) require --execute.
+
+Dependencies: core/infra/client.py, core/adapter/helpers.py
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from core.adapter.helpers import add_execute_flag, build_base_parser, check_dry_run, emit_json
+from core.infra.sanitize import safe_print
+from core.infra.client import api_call
+
+
+def get_parser() -> argparse.ArgumentParser:
+    """Return the argument parser for the batch adapter."""
+    parser = build_base_parser("Manage Gemini batch processing jobs")
+    sub = parser.add_subparsers(dest="action", help="Batch action")
+
+    create_p = sub.add_parser("create", help="Create a batch job")
+    add_execute_flag(create_p)
+    create_p.add_argument("--src", required=True, help="Source file URI (JSONL).")
+    create_p.add_argument("--dest", required=True, help="Destination file URI.")
+
+    sub.add_parser("list", help="List batch jobs")
+
+    get_p = sub.add_parser("get", help="Get batch job status")
+    get_p.add_argument("name", help="Batch job resource name.")
+
+    cancel_p = sub.add_parser("cancel", help="Cancel a running batch job")
+    add_execute_flag(cancel_p)
+    cancel_p.add_argument("name", help="Batch job resource name to cancel.")
+
+    return parser
+
+
+def run(
+    action: str | None = None,
+    name: str | None = None,
+    src: str | None = None,
+    dest: str | None = None,
+    model: str | None = None,
+    execute: bool = False,
+    **kwargs: object,
+) -> None:
+    """Execute batch management operations."""
+    if action == "create":
+        _create(src=src, dest=dest, model=model, execute=execute)
+    elif action == "list":
+        _list_batches()
+    elif action == "get":
+        _get_batch(name=name)
+    elif action == "cancel":
+        _cancel_batch(name=name, execute=execute)
+    else:
+        safe_print("[ERROR] No action specified. Use: create, list, get, cancel")
+
+
+def _create(
+    src: str | None,
+    dest: str | None,
+    model: str | None,
+    execute: bool,
+) -> None:
+    """Create a batch processing job."""
+    if not src or not dest:
+        safe_print("[ERROR] Both --src and --dest are required.")
+        return
+
+    if check_dry_run(execute, f"create batch job from {src}"):
+        return
+
+    body: dict[str, object] = {
+        "inputConfig": {"gcsSource": {"inputUri": src}},
+        "outputConfig": {"gcsDestination": {"outputUriPrefix": dest}},
+    }
+    if model:
+        body["model"] = f"models/{model}"
+
+    response = api_call("batchJobs", body=body)
+    emit_json(response)
+
+
+def _list_batches() -> None:
+    """List all batch jobs."""
+    response = api_call("batchJobs", method="GET")
+    jobs_value = response.get("batchJobs")
+    jobs = jobs_value if isinstance(jobs_value, list) else []
+    emit_json({"count": len(jobs), "jobs": jobs})
+
+
+def _get_batch(name: str | None) -> None:
+    """Get status of a batch job."""
+    if not name:
+        safe_print("[ERROR] No batch job name provided.")
+        return
+    response = api_call(name, method="GET")
+    emit_json(response)
+
+
+def _cancel_batch(name: str | None, execute: bool) -> None:
+    """Cancel a running batch job."""
+    if not name:
+        safe_print("[ERROR] No batch job name provided.")
+        return
+    if check_dry_run(execute, f"cancel batch {name}"):
+        return
+    api_call(f"{name}:cancel", body={})
+    safe_print(f"Cancelled batch {name}")

gemini_skill_install-0.1.1/adapters/data/cache.py

@@ -0,0 +1,122 @@
+"""Context caching adapter — create, list, get, and delete caches.
+
+Caches large content (system instructions, files) to reduce cost and
+latency on repeated requests. Mutating operations require --execute.
+
+Dependencies: core/infra/client.py, core/adapter/helpers.py
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from core.adapter.helpers import add_execute_flag, build_base_parser, check_dry_run, emit_json
+from core.infra.sanitize import safe_print
+from core.infra.client import api_call
+from core.infra.config import load_config
+
+
+def get_parser() -> argparse.ArgumentParser:
+    """Return the argument parser for the cache adapter."""
+    parser = build_base_parser("Manage Gemini context caches")
+    sub = parser.add_subparsers(dest="action", help="Cache action")
+
+    create_p = sub.add_parser("create", help="Create a cache")
+    add_execute_flag(create_p)
+    create_p.add_argument("content", help="Content to cache (text or file URI).")
+    create_p.add_argument("--ttl", default="3600s", help="Time-to-live (e.g., '3600s').")
+
+    sub.add_parser("list", help="List existing caches")
+
+    get_p = sub.add_parser("get", help="Get cache metadata")
+    get_p.add_argument("name", help="Cache resource name.")
+
+    delete_p = sub.add_parser("delete", help="Delete a cache")
+    add_execute_flag(delete_p)
+    delete_p.add_argument("name", help="Cache resource name to delete.")
+
+    return parser
+
+
+def run(
+    action: str | None = None,
+    content: str | None = None,
+    name: str | None = None,
+    ttl: str = "3600s",
+    model: str | None = None,
+    execute: bool = False,
+    **kwargs: object,
+) -> None:
+    """Execute cache management operations."""
+    if action == "create":
+        _create(content=content, ttl=ttl, model=model, execute=execute)
+    elif action == "list":
+        _list_caches()
+    elif action == "get":
+        _get_cache(name=name)
+    elif action == "delete":
+        _delete_cache(name=name, execute=execute)
+    else:
+        safe_print("[ERROR] No action specified. Use: create, list, get, delete")
+
+
+def _create(
+    content: str | None,
+    ttl: str,
+    model: str | None,
+    execute: bool,
+) -> None:
+    """Create a context cache."""
+    if not content:
+        safe_print("[ERROR] No content provided.")
+        return
+
+    if check_dry_run(execute, f"create cache with TTL {ttl}"):
+        return
+
+    from core.routing.router import Router
+
+    config = load_config()
+    router = Router(
+        root_dir=Path(__file__).parent.parent.parent,
+        prefer_preview=config.prefer_preview_models,
+    )
+    resolved_model = model or router.select_model("cache")
+
+    body: dict[str, object] = {
+        "model": f"models/{resolved_model}",
+        "contents": [{"role": "user", "parts": [{"text": content}]}],
+        "ttl": ttl,
+    }
+
+    response = api_call("cachedContents", body=body)
+    emit_json(response)
+
+
+def _list_caches() -> None:
+    """List all context caches."""
+    response = api_call("cachedContents", method="GET")
+    caches_value = response.get("cachedContents")
+    caches = caches_value if isinstance(caches_value, list) else []
+    emit_json({"count": len(caches), "caches": caches})
+
+
+def _get_cache(name: str | None) -> None:
+    """Get metadata for a single cache."""
+    if not name:
+        safe_print("[ERROR] No cache name provided.")
+        return
+    response = api_call(name, method="GET")
+    emit_json(response)
+
+
+def _delete_cache(name: str | None, execute: bool) -> None:
+    """Delete a context cache."""
+    if not name:
+        safe_print("[ERROR] No cache name provided.")
+        return
+    if check_dry_run(execute, f"delete cache {name}"):
+        return
+    api_call(name, method="DELETE")
+    safe_print(f"Deleted cache {name}")