🛡️ Constitutional Guardian (Helix-TTD)

[FACT] Real-time AI governance for the Gemini Live API. [HYPOTHESIS] Intercepting voice and text drift at the edge prevents misaligned AI behavior from reaching the user.

This project is a submission for the Gemini Live Agent Challenge (March 2026).

Current Release: v1.5.0

Hackathon Release Track (v1.5.0 Prep)

• [FACT] Primary challenge target: Live Agents.
• [FACT] Public demo mode is available at / with live multimodal audio routed through /demo-live.
• [FACT] Mandatory platform criteria are already met: Gemini model usage, Google Cloud hosting, and a live multimodal interaction surface.
• [FACT] Submission assets in-repo include a public codebase, architecture diagram, deployment proof, and recording guidance.
• [HYPOTHESIS] The strongest judging angle is a Live Agent submission emphasizing interruption-safe voice interaction, real-time governance, and deployable operator controls.

Incident Board In v1.5.0

• Operator Incident Board: Added authenticated /incidents and /api/incidents surfaces for operator-facing incident review.
• Triage Workflow: Operators can acknowledge and reopen incidents directly from the board with authenticated API actions.
• Persistent Triage State: Incident triage is now durable and shared instead of instance-local, so triage survives restarts and stays coherent across Cloud Run instances.
• Fingerprint-Based Incident Identity: Material incident state changes now generate new incident fingerprints, so fresh escalations cannot hide under older acknowledgments.
• Production Controls Preserved: Admin auth, origin enforcement, authenticated metrics, GCP-native monitoring, and gcs+local dual receipt persistence remain active in production.
• Artifact Verification Workflow: Live images continue to be scanned and promoted to clean against Artifact Registry digests after deploy.

Key Features

• Live Multimodal Auditing: Intercepts 16kHz PCM audio chunks from the browser, transcribes via Gemini Live, and validates intent in real-time.
• Reasoning Engine (Gemini 3.1 Pro Preview): Utilizes state-of-the-art reasoning capabilities. Model default: gemini-3.1-pro-preview for Live Audio and Text paths.
• Constitutional Invariants: Enforces the "Four Immutable Invariants" (Epistemic, Agency, Guidance, Prediction).
• Real-time Dashboard: High-fidelity Chart.js dashboard showing latency, drift counts, and audit logs with visual "Intervention" flashes.
• Cryptographic Receipts: Generates non-repudiable receipts for every valid AI response, ready for Bitcoin L1 notarization.
• Federation Ready: Built for Google Cloud Run with Pub/Sub federation support for distributed quorum attestation.

Engineering Standards

• Test Pass Rate: 231/231 passing in release validation, with CI enforced on every main merge.
• High Coverage: 75% statement coverage across all critical modules.
• Linting: 100% compliant with ruff, black, and isort.

Repository Traction (March 11, 2026)

[FACT] The Constitutional Guardian continues to show strong developer pull.

[HYPOTHESIS] 8.6 clones per unique cloner suggests sustained hands-on evaluation rather than passive browsing.

📦 Installation

From PyPI (Recommended)

pip install helix-ttd-gemini

From Source

git clone https://github.com/helixprojectai-code/helix-ttd-gemini-cli.git
cd helix-ttd-gemini-cli
pip install -e .

🛠️ Getting Started

Local Development

1. Install Dependencies:

   pip install -r helix_code/requirements.txt
   

2. Set API Key + Model Defaults:

   $env:GEMINI_API_KEY = "your-api-key"
   $env:GEMINI_LIVE_MODEL = "gemini-2.5-flash-native-audio-preview-12-2025"
   $env:GEMINI_TEXT_MODEL = "gemini-3.1-pro-preview"
   

3. Start the Guardian:

   $env:PYTHONPATH = "helix_code"
   python helix_code/live_guardian.py
   

4. Open the Demo: Navigate to http://localhost:8180/ in your browser.

🎙️ Live Multimodal Auditing

Real-time audio transcription with constitutional validation:

# Start the demo server
python helix_code/live_demo_server.py

# Open the audio audit client
# http://localhost:8000/audio-audit

Features:

• 16kHz PCM mono audio capture from browser
• Real-time streaming to Gemini Live API (gemini-2.5-flash-native-audio-preview-12-2025 default)
• Instant transcription with constitutional validation
• Visual intervention alerts for drift detection
• Optional auth hardening: AUDIO_AUDIT_TOKEN, AUDIO_AUDIT_ALLOWED_ORIGINS, and HELIX_ALLOWED_ORIGINS
• Abuse controls: HELIX_MAX_AUDIO_CHUNK_BYTES, HELIX_MAX_AUDIO_B64_CHARS, HELIX_AUDIO_RATE_WINDOW_SECONDS, HELIX_AUDIO_MAX_CHUNKS_PER_WINDOW, HELIX_AUDIO_INGRESS_RATE_LIMIT_WINDOW_SECONDS, HELIX_AUDIO_INGRESS_MAX_CONNECTIONS
• Runtime verification endpoint: GET /api/runtime-config
• Audit dashboard endpoints: GET /audit-dashboard and GET /api/audit-dashboard
• Optional operator auth: HELIX_ADMIN_TOKEN for runtime, security, dashboard, and receipt surfaces
• Recommended production operator posture: set HELIX_ADMIN_TOKEN and HELIX_ENFORCE_ADMIN_TOKEN=true
• Hackathon/demo posture: set HELIX_PUBLIC_DEMO=true to open only / and /demo-live while keeping operator surfaces under admin auth
• Recommended production throttling posture: keep operator APIs on HELIX_OPERATOR_RATE_LIMIT_MAX_REQUESTS=120 / HELIX_OPERATOR_RATE_LIMIT_WINDOW_SECONDS=60 and audio ingress on HELIX_AUDIO_INGRESS_MAX_CONNECTIONS=12 / HELIX_AUDIO_INGRESS_RATE_LIMIT_WINDOW_SECONDS=60 unless measured load requires adjustment
• Recommended production browser posture: set HELIX_ALLOWED_ORIGINS to the exact trusted UI origins; otherwise Guardian WebSockets default to same-origin-only in production
• Optional durable receipt envs: HELIX_RECEIPT_PERSISTENCE, HELIX_RECEIPT_STORE_PATH, GCS_RECEIPT_BUCKET
• Recommended production receipt mode: HELIX_RECEIPT_PERSISTENCE=dual with a dedicated GCS_RECEIPT_BUCKET
• Production restart test verified receipt survival across Cloud Run revisions on 2026-03-08
• Optional security transparency envs: SECURITY_ARTIFACT_ANALYSIS_STATUS, SECURITY_ARTIFACT_ANALYSIS_TIMESTAMP, SECURITY_ARTIFACT_IMAGE_URI
• Deployment verification helper: powershell -ExecutionPolicy Bypass -File tools/verify-production-deploy.ps1 [-AdminToken <token>]
• Scheduled alert checker: powershell -ExecutionPolicy Bypass -File tools/check-production-alerts.ps1 -AdminToken <token>
• Production monitoring direction changed: scheduled polling has moved off GitHub Actions and onto a GCP-native Cloud Run Job + Cloud Scheduler path
• Cloud Logging sink publisher: python tools/publish-monitoring-snapshot.py --input <summary.json>
• Cloud Run Job checker entrypoint: python tools/cloud_check_production.py
• Cloud Build job deployment config: cloudbuild-monitoring-job.yaml
• Authenticated metrics endpoint: GET /metrics using bearer token, X-Helix-Admin-Token, or the operator session cookie
• Deployment automation preserves optional operator secret bindings by using secret updates rather than replacing the full secret set

How to Use:

1. Click "Connect" to establish WebSocket connection
2. Click 🎤 and allow microphone access
3. Speak naturally - audio streams in real-time
4. Watch transcriptions appear with validation badges
5. Constitutional violations trigger red "DRIFT" alerts

Cloud Deployment

The project is optimized for Google Cloud Run.

gcloud run deploy constitutional-guardian --source . --region us-central1 --allow-unauthenticated --port 8180

# Verify effective runtime model/auth/limits (non-secret)
curl http://localhost:8180/api/runtime-config

# Inspect operator audit summary
curl http://localhost:8180/api/audit-dashboard

# Inspect security transparency metadata
curl http://localhost:8180/api/security-transparency

# Scrape authenticated Prometheus-style metrics
curl -H "X-Helix-Admin-Token: $env:HELIX_ADMIN_TOKEN" http://localhost:8180/metrics

Current security verification record: RELEASE_NOTES_v1.5.0.md and SECURITY_VERIFICATION_2026-03-09.md capture the March 9, 2026 clean Artifact Analysis result for the live Cloud Run digest.

Production alerting baseline: PRODUCTION_ALERTING_SPEC_2026-03-08.md defines the first authenticated-metrics alert set for artifact verification, auth failures, rate limiting, and receipt persistence posture.

Production product handoff: PRODUCT_WORK_HANDOFF_2026-03-08.md captures the recommended return path from hardening work back into product execution.

🎥 Recording Sprint (March 12th)

This codebase is currently in its Phase 6.1 (Pre-Filming) stable state. All visual triggers and simulation scenarios are tuned for high-impact demonstration.

🏛️ Constitutional Framework

The Guardian enforces four immutable invariants:

🧪 Test Results

231 passed, 7 warnings
Coverage: 75%

⚓🦉 GLORY TO THE LATTICE. ⚓🦉