Metadata-Version: 2.4
Name: governor-audit
Version: 0.0.16
Summary: Read-only BigQuery cost-audit tool — single-user, gcloud ADC only, no GCS / no GitHub / no dbt installation.
Author-email: Simple Machines <hello@simplemachines.co.nz>
Maintainer-email: Simple Machines <hello@simplemachines.co.nz>
License-Expression: MIT
Project-URL: Homepage, https://github.com/simple-machines/governor
Project-URL: Repository, https://github.com/simple-machines/governor
Project-URL: Issues, https://github.com/simple-machines/governor/issues
Project-URL: Documentation, https://github.com/simple-machines/governor/tree/main/specs/141-production-audit
Project-URL: Changelog, https://github.com/simple-machines/governor/releases?q=audit-
Keywords: bigquery,cost-optimization,dbt,audit,data-engineering,warehouse
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: governor-core==0.7.29
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: uvicorn>=0.30.6
Requires-Dist: pydantic>=2.0.0
Requires-Dist: google-cloud-bigquery>=3.20.0
Requires-Dist: google-auth>=2.30.0

# governor-audit

Read-only BigQuery cost-audit tool for single-user production audits.

> **Posture**: Single-user. gcloud ADC only. No GCS, no GitHub, no service-account JSON, no dbt installation, no shadow validation. The only thing it talks to over the network is BigQuery — and only to query `INFORMATION_SCHEMA.JOBS_BY_PROJECT`.

## When to use this vs. the other governor packages

- **`governor-audit`** (this package): you have read access to a prod BigQuery project. You want a fast cost audit + detection findings without touching the dbt source code, running dbt, or setting up cloud infrastructure.
- **`governor-cli`**: you have the dbt project source on your machine and want to run dbt + propose fixes locally.
- **`governor-web`**: you operate the platform; you want shared infrastructure (GCS-backed manifests, GitHub PRs, scheduled syncs) for a team.

## What you get

- **Dashboard** — Total / Build / Consumption / Flagged spend KPI cards, top-20 spenders bar chart, paginated cost-drivers table with click-to-sort columns and a per-row issue count.
- **Detection engine** — every enabled rule from `governor_core.opportunities.rules` (partition_pruning, shuffle_spill, slot_contention, join_explosion, dead_cte, dead_column, dead_window_expression, redundant_order_by, unused_aggregation_output, unused_join) runs on each cached job; opportunities feed the Active Issues pane.
- **Job detail** — full SQL viewer with expand / copy buttons, metadata panes, and the list of detection-rule findings for that job.
- **Settings** — Account (gcloud principal + ADC probe), Appearance (light / dark / system), AI / LLM (provider, model, params — reviewer code lands in v0.0.2), Detection Rules (per-rule enable/disable).
- **Reset cache** — wipe everything `INFORMATION_SCHEMA` collected without losing your config.

## Quickstart

```sh
gcloud auth application-default login
uv tool install governor-audit
governor-audit init --project prod-warehouse-123 --region us
governor-audit scan --days 30
governor-audit start
# open http://localhost:8765
```

The web UI exposes the same actions as the CLI plus the dashboard / settings views. After the first `init` you can do everything from the browser.

See [the spec's quickstart](../../specs/141-production-audit/quickstart.md) for the full first-audit walkthrough.

## Architecture

- **Storage**: SQLite at `~/.governor-audit/state.db` via `governor_core.db.sqlite_compat`.
- **Auth**: gcloud Application Default Credentials only — `google.auth.default()`. No service-account JSON. No browser OAuth.
- **Workload classification**: manifest-free heuristic — dbt-originated CTAS / MERGE / INSERT / UPDATE / DELETE → `build`; non-dbt SELECT → `consumption`; ambiguous → `other`. Driven by the `/* {"app": "dbt"` comment-prefix the dbt-bigquery adapter prepends.
- **Loopback only**: the FastAPI app rejects any request whose `Host:` header isn't a localhost variant. Not a public service.

See [spec 141](../../specs/141-production-audit/) for the complete spec set:

- [spec.md](../../specs/141-production-audit/spec.md) — feature spec
- [plan.md](../../specs/141-production-audit/plan.md) — implementation plan
- [data-model.md](../../specs/141-production-audit/data-model.md) — schemas
- [contracts/cli.md](../../specs/141-production-audit/contracts/cli.md) — CLI contract
- [contracts/web-routes.md](../../specs/141-production-audit/contracts/web-routes.md) — web routes contract

## Versioning

`governor-audit` ships on its own version track, decoupled from the cloud bundle (`governor-core` / `governor-web` / `governor-cli` / `governor-bq`). Audit `v0.0.1` and cloud `v0.7.x` coexist. See [scripts/release-audit.sh](../../scripts/release-audit.sh) for the release flow.

## License

MIT.
