il-audit 0.1.3

Cross-app audit and analytics logging for Locaria Intelligence Layer

il-audit — Intelligence Layer audit & analytics

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

Install

Local dev (sibling repo):

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

Production pin (PyPI, after release):

"il-audit>=0.1.3",

Or from Git:

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

See 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:

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

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):

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. 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