Metadata-Version: 2.5
Name: gemini-radar
Version: 0.1.0
Summary: Gemini API infrastructure FinOps SDK — part of the Hyperscaler Radar suite.
Project-URL: Homepage, https://github.com/mormichaeli/gemini-radar
Project-URL: Repository, https://github.com/mormichaeli/gemini-radar
Project-URL: Bug Tracker, https://github.com/mormichaeli/gemini-radar/issues
Author: Sarimor Michaeli
License: MIT
Keywords: cloud-cost,finops,gemini,google-ai,hyperscaler,llm,radar
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.31
Provides-Extra: all
Provides-Extra: csv
Provides-Extra: drawio
Description-Content-Type: text/markdown

# gemini-radar

**Gemini API infrastructure FinOps SDK** — part of the Hyperscaler Radar suite.

Scan a Gemini Developer API key's project for its model catalog, tuned models, cached
content, uploaded files, File Search Stores, and batch jobs. Detect external service
relationships from cached-content system instructions (the closest thing this API has to
an OpenAI assistant's stored instructions), flag cost/hygiene anomalies via a findings
engine, and export inventory to CSV or a draw.io architecture diagram.

---

## Install

```
pip install gemini-radar
```

Requires Python 3.10+. CSV and draw.io export ship in the base install.

---

## A different shape than `openai-radar` / `anthropic-radar` — on purpose

The Gemini Developer API (`generativelanguage.googleapis.com`) has **no org-wide
usage/cost report and no API-key-listing endpoint** — a single key just scopes calls to
whichever Google Cloud project issued it in AI Studio. So `gemini-radar` doesn't do
token/dollar findings the way its siblings do; instead it watches the resources that
carry their own standing cost regardless of billing visibility:

* **cachedContents** — billed hourly for storage until they expire, whether or not
  they're being hit
* **fileSearchStores** — persistent RAG storage
* **batches** — async job failures that silently waste quota
* **files** — 48h auto-delete TTL, useful for pipeline hygiene

For actual token spend and Cloud Billing data on the backing project, pair this with
`gcp-radar` rather than duplicating that surface here.

```python
from gemini_radar import RadarClient, Runner

# Reads GEMINI_API_KEY (or GOOGLE_API_KEY) from environment
client = RadarClient()
result = Runner.run_sync(client)

print(result.summary())
result.export_csv("./out/")
result.export_drawio("./out/gemini_arch.drawio")
```

---

## CLI

```
# Full scan — findings table to stdout
gemini-radar run

# CSVs + draw.io diagram
gemini-radar run --csv-dir ./out --drawio-file arch.drawio

# JSON instead of a table
gemini-radar run --output json --out-file scan.json

# Skip batch jobs or File Search Stores
gemini-radar run --no-batches --no-file-search

# Findings only
gemini-radar findings

# Print the version
gemini-radar version
```

Flags follow the Radar suite convention: `--output/-o` selects `table` or `json`,
`--out-file` writes the JSON payload, `--csv-dir` writes per-resource CSVs.

---

## Findings engine

| Rule ID   | Severity | Condition                                                    |
| --------- | -------- | -------------------------------------------------------------- |
| CACHE_001 | HIGH     | Cached content expiring within 24h while still holding tokens  |
| CACHE_002 | MEDIUM   | Cached content is idle (zero tokens) but still billed hourly   |
| TUNED_001 | MEDIUM   | Tuned model stuck in `FAILED` state                            |
| BATCH_001 | HIGH     | Batch job failure rate > 10% across recent jobs                |
| FSS_001   | MEDIUM   | File Search Store larger than 5 GB (storage cost driver)       |
| FILE_001  | LOW      | Uploaded file expiring within 6h (auto-deleted at the 48h TTL) |

---

## Service relationship detection

`cachedContents` is the one Gemini resource that stores a real `systemInstruction`, so
`detect_relationships()` mines that text (plus tuned-model and file-search-store display
names) for the same external-service signal set as the rest of the Radar suite, and
emits `ServiceRelationship` edges (dashed lines in the draw.io diagram):

| Kind     | Signals                                              |
| -------- | ------------------------------------------------------ |
| AWS      | `aws`, `s3`, `ec2`, `lambda`, `dynamodb`, `sqs`         |
| GCP      | `gcp`, `bigquery`, `gcs`, `google cloud`, `cloud storage` |
| AZURE    | `azure`, `blob.core.windows`, `cosmosdb`                |
| DATABASE | `postgres`, `mysql`, `mongo`, `redis`, `neon`, `supabase` |
| SLACK    | `slack`                                                 |
| EMAIL    | `sendgrid`, `mailgun`, `smtp`                           |
| WEBHOOK  | `webhook`, `http://`                                    |

---

## SDK structure

```
src/gemini_radar/
├── client.py               # RadarClient (single-key auth)
├── runner.py                 # Runner, RunConfig, RunResult
├── findings.py                # FindingEngine, Finding, Severity
├── relationships.py           # systemInstruction-based service relationship detection
├── models/base.py             # Pydantic v2 models for all resource types
├── scanners/                  # models.py, cached_contents.py, files.py, batches.py
├── exporters/                 # csv_exporter.py, drawio_exporter.py
└── cli.py                     # gemini-radar CLI
```

---

## Part of the Hyperscaler Radar suite

`aws-radar` · `gcp-radar` · `azure-radar` · `oci-radar` · `openai-radar` · `anthropic-radar` · `gemini-radar` · `datadog-radar` · `coreweave-radar`

## License

MIT
