Metadata-Version: 2.4
Name: il-audit
Version: 0.1.3
Summary: Cross-app audit and analytics logging for Locaria Intelligence Layer
Author: Locaria Intelligence Layer Team
License: Proprietary
Keywords: audit,logging,bigquery,analytics,locaria
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: google-api-core>=2.19.0
Requires-Dist: google-cloud-bigquery>=3.27.0
Requires-Dist: pydantic>=2.0
Requires-Dist: fastapi>=0.115.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# il-audit — Intelligence Layer audit & analytics

Cross-app BigQuery audit logging for **intelligence-layer-ingest** and **intelligence-layer-chat**.

## Install

Local dev (sibling repo):

```bash
pip install -e ../intelligence-layer-audit
```

Production pin (PyPI, after release):

```toml
"il-audit>=0.1.3",
```

Or from Git:

```toml
"il-audit @ git+https://github.com/Locaria/intelligence-layer-audit@v0.1.0",
```

See [PUBLISHING.md](PUBLISHING.md) for release → PyPI workflow (same as `locaria-integrated-testing`).

## Package layout

```
il_audit/
  config/
    audit_settings.py       # runtime settings (env + fallbacks)
    cost_catalog.py         # service/operation/resource constants
    cost_rates_loader.py    # seed JSON / BQ cost_rates loader
    fallbacks/              # bundled JSON defaults
    stores/
      audit_schema_store.py # BQ table ids + schema builders
  builders/
    envelope_builder.py     # shared row builder
  taxonomy.py               # event type constants
  emit.py, writer.py, ...   # runtime modules
  __init__.py               # public API re-exports
```

Import the stable API from the package root:

```python
from il_audit import emit, AuditContext, flush_audit_writer
```

## Configuration

All defaults live in bundled JSON — **never hardcode prices or dataset names in application code**.

| File | Purpose |
|------|---------|
| `il_audit/config/fallbacks/audit_defaults.json` | Dataset, flush tuning, default `cost_rates_source` |
| `il_audit/config/fallbacks/cost_rates_seed.json` | Interim pricing catalog (until BQ `cost_rates` is scraped) |
| `il_audit/config/cost_catalog.py` | Stable service/operation/resource identifier constants |
| `il_audit/config/audit_settings.py` | Runtime settings (`get_audit_settings`) |
| `il_audit/config/stores/audit_schema_store.py` | BigQuery table ids and schema builders |

| Variable | Default (from JSON) | Purpose |
|----------|---------------------|---------|
| `IL_ENABLE_AUDIT_LOGS` | `true` | Master switch (also respects `IL_ENABLE_BQ_LOGS`) |
| `IL_BQ_AUDIT_DATASET` | `intelligence_layer_logs` | BQ dataset |
| `IL_BQ_LOGS_PROJECT` | — | GCP project (`GOOGLE_CLOUD_PROJECT` / `GCP_PROJECT` fallback) |
| `IL_COST_RATES_SOURCE` | `seed` | `seed` or `bigquery` (authoritative catalog from `cost_rates` table) |
| `IL_COST_RATES_CACHE_SECONDS` | `3600` | In-memory rate cache TTL |
| `IL_AUDIT_WRITE_QUEUE_MAX_SIZE` | `10000` | Max pending rows before drop |
| `IL_AUDIT_STORE_QUERY_TEXT` | `true` | Store full chat questions in BQ (phase 2) |

When `IL_COST_RATES_SOURCE=bigquery`, rates load from `{project}.{dataset}.cost_rates`. A scheduled-tasks job will scrape GCP pricing docs and maintain that table. Until then, seed JSON is used and rows are tagged `pricing_source=seed_catalog`.

## Usage

```python
from il_audit import AuditContext, emit
from il_audit import taxonomy as T

emit(
    T.AUTH_LOGIN_SUCCEEDED,
    context=AuditContext(app="ingest", actor_uid=uid, actor_email=email),
    status="succeeded",
    action="login",
)
```

## Browser beacons

Mount the FastAPI router with host auth (ingest example):

```python
from il_audit.beacon_router import create_beacon_router

app.include_router(
    create_beacon_router(
        app_name="ingest",
        get_context=audit_context_from_request,
        require_auth=require_beacon_auth,
    ),
)
```

Only `UI_*` event types from `taxonomy.BEACON_EVENT_TYPES` are accepted.

**HTML convention:** mark elements with `data-il-audit-*` attributes — see [documentation/ui-beacon-convention.md](documentation/ui-beacon-convention.md). Host apps ship `il_audit/static/audit_beacon.js` (or a copy) with `auditFieldsFromElement()` and `auditTrack()`.

## Chat adoption (phase 2)

1. Add same `il-audit` dep to chat
2. Mount `create_beacon_router(app_name="chat", get_context=...)`
3. Emit `chat_turns` on `POST /query` with client `conversation_session_id`
4. See `documentation/chat-phase2.md`

## SQL

Operator-run views: `sql/analytics_views.sql`
