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.4",

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)

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

SQL

Operator-run views: sql/analytics_views.sql

Development Status
- 4 - Beta
Intended Audience
- Developers
Programming Language

Release files for il-audit 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for il-audit 0.1.4
File	Size	Uploaded
il_audit-0.1.4.tar.gz	27.7 kB	Jul 4, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for il-audit 0.1.4
File	Interpreter	ABI	Platform	Reset
il_audit-0.1.4-py3-none-any.whl 30.0 kB Jul 4, 2026	Python 3	none	any	Details

Total release size: 57.7 kB

Release files / il_audit-0.1.4.tar.gz

Download URL	il_audit-0.1.4.tar.gz
Size	27.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`98d03726eacc4f21b55c756fe1f66aeb385d52ca57059f3c1237c04cc9664f70`
BLAKE2b-256 checksum How to use checksums	`a3699d5f58b14c3e0b5ec0d5fdd55b410ff9446fa9831cd76d33819c834bc38b`
Upload date	Jul 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.15`

Release files / il_audit-0.1.4-py3-none-any.whl

Download URL	il_audit-0.1.4-py3-none-any.whl
Size	30.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8507b3f922180ace3b12da61ba68b4e64afb13c8d9173c940fbcc60dd939cf0c`
BLAKE2b-256 checksum How to use checksums	`bb55030ff7baca2f1e2788928b846d24de39a0019e756e4a8a3b6f7d37bb7508`
Upload date	Jul 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.15`