Skip to content

Commit 4dbc1cb

Browse files
stephenh67stephenh67
committed
release: prepare v1.5.0 hackathon release
1 parent 6ef1918 commit 4dbc1cb

12 files changed

Lines changed: 144 additions & 114 deletions

‎INSTRUCTIONS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131

3232
### 1. Introduction (The UI)
3333
- Show the dashboard with **0 Receipts / 0 Drifts**.
34-
- Highlight the **"LIVE v1.4.8"** branding and the **Pulse-Green** header.
34+
- Highlight the **"LIVE v1.5.0"** branding and the **Pulse-Green** header.
3535

3636
### 2. Live Audio Demo (The Waveform)
3737
- Click **"Start Live Mic"**.

‎README.md‎

Lines changed: 27 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
[![Ruff](https://img.shields.io/badge/lint-ruff-261230?labelColor=grey)](https://github.com/astral-sh/ruff)
88
[![Black](https://img.shields.io/badge/format-black-000000?labelColor=grey)](https://github.com/psf/black)
99
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
10-
[![PyPI](https://img.shields.io/badge/PyPI-1.4.8-blue)](https://pypi.org/project/helix-ttd-gemini/)
10+
[![PyPI](https://img.shields.io/badge/PyPI-1.5.0-blue)](https://pypi.org/project/helix-ttd-gemini/)
1111

1212
![Constitutional Guardian Overview](https://raw.githubusercontent.com/helixprojectai-code/helix-ttd-gemini-cli/main/assets/helix-ttd-gemini.png)
1313

@@ -16,9 +16,17 @@
1616

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

19-
**Current Release:** `v1.4.8`
19+
**Current Release:** `v1.5.0`
2020

21-
## Incident Board In v1.4.8
21+
## Hackathon Release Track (v1.5.0 Prep)
22+
23+
- **[FACT]** Primary challenge target: **Live Agents**.
24+
- **[FACT]** Public demo mode is available at `/` with live multimodal audio routed through `/demo-live`.
25+
- **[FACT]** Mandatory platform criteria are already met: Gemini model usage, Google Cloud hosting, and a live multimodal interaction surface.
26+
- **[FACT]** Submission assets in-repo include a public codebase, architecture diagram, deployment proof, and recording guidance.
27+
- **[HYPOTHESIS]** The strongest judging angle is a Live Agent submission emphasizing interruption-safe voice interaction, real-time governance, and deployable operator controls.
28+
29+
## Incident Board In v1.5.0
2230

2331
- **Operator Incident Board:** Added authenticated `/incidents` and `/api/incidents` surfaces for operator-facing incident review.
2432
- **Triage Workflow:** Operators can acknowledge and reopen incidents directly from the board with authenticated API actions.
@@ -27,35 +35,35 @@ This project is a submission for the **Gemini Live Agent Challenge (March 2026)*
2735
- **Production Controls Preserved:** Admin auth, origin enforcement, authenticated metrics, GCP-native monitoring, and `gcs+local` dual receipt persistence remain active in production.
2836
- **Artifact Verification Workflow:** Live images continue to be scanned and promoted to `clean` against Artifact Registry digests after deploy.
2937

30-
## 🚀 Key Features
38+
## Key Features
3139

32-
- **🎙️ Live Multimodal Auditing:** Intercepts 16kHz PCM audio chunks from the browser, transcribes via Gemini Live, and validates intent in real-time.
33-
- **🧠 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.
34-
- **🛡️ Constitutional Invariants:** Enforces the "Four Immutable Invariants" (Epistemic, Agency, Guidance, Prediction).
35-
- **📊 Real-time Dashboard:** High-fidelity Chart.js dashboard showing latency, drift counts, and audit logs with visual "Intervention" flashes.
36-
- **⚓ Cryptographic Receipts:** Generates non-repudiable receipts for every valid AI response, ready for Bitcoin L1 notarization.
37-
- **🦉 Federation Ready:** Built for Google Cloud Run with Pub/Sub federation support for distributed quorum attestation.
40+
- **Live Multimodal Auditing:** Intercepts 16kHz PCM audio chunks from the browser, transcribes via Gemini Live, and validates intent in real-time.
41+
- **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.
42+
- **Constitutional Invariants:** Enforces the "Four Immutable Invariants" (Epistemic, Agency, Guidance, Prediction).
43+
- **Real-time Dashboard:** High-fidelity Chart.js dashboard showing latency, drift counts, and audit logs with visual "Intervention" flashes.
44+
- **Cryptographic Receipts:** Generates non-repudiable receipts for every valid AI response, ready for Bitcoin L1 notarization.
45+
- **Federation Ready:** Built for Google Cloud Run with Pub/Sub federation support for distributed quorum attestation.
3846

39-
## 📈 Engineering Standards
47+
## Engineering Standards
4048

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

45-
## 📊 Repository Traction (March 8, 2026)
53+
## Repository Traction (March 11, 2026)
4654

47-
**[FACT]** The Constitutional Guardian is gaining significant developer interest.
55+
**[FACT]** The Constitutional Guardian continues to show strong developer pull.
4856

4957
| Metric | Value | Period |
5058
|--------|-------|--------|
51-
| **Git Clones** | 7,240 | Last 14 days |
52-
| **Unique Cloners** | 855 | Last 14 days |
53-
| **Repository Views** | 1,190 | Last 14 days |
54-
| **Unique Visitors** | 24 | Last 14 days |
59+
| **Git Clones** | 7,999 | Last 14 days |
60+
| **Unique Cloners** | 925 | Last 14 days |
61+
| **Repository Views** | 1,350 | Last 14 days |
62+
| **Unique Visitors** | 27 | Last 14 days |
5563
| **Peak Daily Clones** | 1,527 | Single day |
5664
| **Peak Daily Cloners** | 198 | Single day |
5765

58-
**[HYPOTHESIS]** 8.5 clones per unique cloner indicates active developer exploration and potential contribution activity.
66+
**[HYPOTHESIS]** 8.6 clones per unique cloner suggests sustained hands-on evaluation rather than passive browsing.
5967

6068
## 📦 Installation
6169

@@ -166,7 +174,7 @@ curl http://localhost:8180/api/security-transparency
166174
curl -H "X-Helix-Admin-Token: $env:HELIX_ADMIN_TOKEN" http://localhost:8180/metrics
167175
```
168176

169-
**Current security verification record:** `RELEASE_NOTES_v1.4.8.md` and `SECURITY_VERIFICATION_2026-03-09.md` capture the March 9, 2026 clean Artifact Analysis result for the live Cloud Run digest.
177+
**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.
170178

171179
**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.
172180

‎RELEASE_NOTES_v1.5.0.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# RELEASE NOTES v1.5.0
2+
3+
Date: 2026-03-11
4+
5+
## Summary
6+
7+
**[FACT]** v1.5.0 is the hackathon release for the Gemini Live Agent Challenge.
8+
**[FACT]** The release focus is the **Live Agents** category: public real-time multimodal interaction on Google Cloud with Gemini Live-backed audio flow and operator-grade governance controls behind the scenes.
9+
**[HYPOTHESIS]** This release positioning gives the project its strongest fit for both the Live Agents category and the technical execution judging track.
10+
11+
## Planned Release Contents
12+
13+
- **[FACT]** Public demo mode at `/` and `/demo-live` for hackathon judging without exposing admin/operator surfaces.
14+
- **[FACT]** Persistent operator incident board with authenticated triage actions and fingerprinted incident identity.
15+
- **[FACT]** Authenticated observability, security transparency, and receipt persistence remain active for the production deployment.
16+
- **[FACT]** Google Cloud deployment remains live on Cloud Run with Artifact Registry, Secret Manager, Cloud Storage, Cloud Logging, and Cloud Scheduler / Cloud Run Job monitoring.
17+
18+
## Gemini Live Agent Challenge Alignment
19+
20+
### Category Fit
21+
- **[FACT]** Primary category: **Live Agents**
22+
- **[FACT]** Real-time interaction: browser microphone input, live audio stream handling, interruption-aware session flow, and immediate constitutional validation.
23+
- **[FACT]** Multimodal stack: live audio input plus operator-facing visual dashboards and incident workflow.
24+
25+
### Mandatory Requirements
26+
- **[FACT]** Uses a Gemini model.
27+
- **[FACT]** Uses Google-hosted runtime infrastructure.
28+
- **[FACT]** Uses Google Cloud services in production.
29+
- **[ASSUMPTION]** Final submission package will reference the Google GenAI SDK / Live API integration already present in the codebase and deployment proof.
30+
31+
### Submission Assets
32+
- **[FACT]** Public repo: `https://github.com/helixprojectai-code/helix-ttd-gemini-cli`
33+
- **[FACT]** Public live demo: `https://constitutional-guardian-231586465188.us-central1.run.app/`
34+
- **[FACT]** Architecture diagram: `assets/ARCHITECTURE_CG.png`
35+
- **[FACT]** Deployment proof: `DEPLOYMENT_PROOF.md`
36+
- **[FACT]** Recording guidance: `VIDEO_RECORDING_INSTRUCTIONS.md` and `VIDEO_DEMO.md`
37+
38+
## Validation Gate Before Roll
39+
40+
- **[FACT]** Update README traction numbers to the March 11 snapshot.
41+
- **[FACT]** Refresh hackathon-facing demo and recording docs to the current live URL and public demo flow.
42+
- **[FACT]** Re-run full validation before tag / deploy.
43+
- **[FACT]** Re-verify the live Artifact Registry digest and promote runtime metadata back to `clean` after the release deploy.
44+
45+
## Current Public Metrics Snapshot
46+
47+
- **[FACT]** 7,999 clones in the last 14 days
48+
- **[FACT]** 925 unique cloners in the last 14 days
49+
- **[FACT]** 1,350 repo views in the last 14 days
50+
- **[FACT]** 27 unique visitors in the last 14 days
51+
52+
## Roll Sequence
53+
54+
1. **[FACT]** Finalize docs and challenge-facing copy.
55+
2. **[FACT]** Version surfaces are now bumped from `1.4.8` to `1.5.0`.
56+
3. **[FACT]** Run `pre-commit` and full `pytest`.
57+
4. **[FACT]** Commit, tag, and publish `v1.5.0`.
58+
5. **[FACT]** Deploy to Cloud Run.
59+
6. **[FACT]** Re-scan the live image and promote artifact status to `clean`.

‎VIDEO_DEMO.md‎

Lines changed: 16 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -33,53 +33,26 @@
3333
### Live Demo (1:00-2:00)
3434
**[Screen: Terminal with curl commands]**
3535

36-
```bash
37-
# Health check
38-
curl https://constitutional-guardian-xyz-uc.a.run.app/health
39-
```
40-
> "First, let's verify our Cloud Run deployment is healthy."
41-
42-
```bash
43-
# Valid FACT
44-
curl -X POST "https://.../validate?text=[FACT]%20Water%20boils%20at%20100C"
45-
```
46-
**[Show JSON response with compliant: true]**
47-
> "A properly marked fact passes through."
36+
1. Open the public demo at `https://constitutional-guardian-231586465188.us-central1.run.app/`
37+
2. Click **Connect**
38+
3. Start the microphone
39+
4. Speak, interrupt, and show the live response / audit surface
4840

4941
```bash
50-
# Missing marker (DRIFT)
51-
curl -X POST "https://.../validate?text=AI%20will%20take%20all%20jobs"
42+
curl https://constitutional-guardian-231586465188.us-central1.run.app/health
5243
```
53-
**[Show JSON response with compliant: false, recommendation: INTERVENE]**
54-
> "An unmarked prediction triggers a drift alert. The Guardian blocks this from reaching the user."
55-
56-
```bash
57-
# Agency violation
58-
curl -X POST "https://.../validate?text=I%20will%20handle%20that%20for%20you"
59-
```
60-
**[Show agency_violations array]**
61-
> "Agency claims like 'I will' are flagged as constitutional violations."
62-
63-
### GCP Integration Demo (2:00-2:30)
64-
**[Screen: GCP Console → Cloud Run]**
65-
> "The Guardian is deployed on Google Cloud Run with autoscaling from 1 to 100 instances."
66-
67-
**[Screen: GCP Console → Pub/Sub]**
68-
> "We use Cloud Pub/Sub to stream federation events across our 3-node network."
69-
70-
**[Screen: GCP Console → Cloud Storage]**
71-
> "Every validation generates an immutable receipt stored in Cloud Storage."
44+
> "First, let's verify the Cloud Run backend serving the live demo is healthy."
7245
73-
**[Screen: GCP Console → Secret Manager]**
74-
> "DBC encryption keys are managed by Secret Manager with automatic rotation."
46+
### GCP Deployment Proof (2:00-2:30)
47+
**[Screen: GCP Console -> Cloud Run]**
48+
> "The Guardian backend is live on Google Cloud Run, and this is the service judges can verify during submission review."
7549
76-
### Federation Demo (2:30-2:50)
77-
**[Screen: Three terminal windows - KIMI, GEMS, DEEPSEEK]**
78-
> "Our 3-node federation shares compliance data in real-time. When KIMI detects drift, GEMS and DEEPSEEK learn about it instantly through Pub/Sub."
50+
**[Screen: GCP Console -> Cloud Storage / Secret Manager / Logging]**
51+
> "We use Google Cloud services for receipt persistence, secret handling, and operational monitoring behind the live demo."
7952
80-
### Closing (2:50-3:00)
53+
### Closing (2:30-3:00)
8154
**[Screen: GitHub repo + Architecture diagram]**
82-
> "Constitutional Guardian: 75 tests passing, 7 GCP services, sub-500ms latency, and zero constitutional drifts allowed. Thank you."
55+
> "Constitutional Guardian is our Live Agents submission: a real-time multimodal agent with public judging access, live governance, and Google Cloud deployment. Thank you."
8356
8457
---
8558

@@ -96,9 +69,9 @@ curl -X POST "https://.../validate?text=I%20will%20handle%20that%20for%20you"
9669
- Format: MP4 (H.264)
9770

9871
### Steps
99-
1. **Record terminal segments** - Use your terminal with font size 16+
100-
2. **Record GCP Console** - Log into console.cloud.google.com
101-
3. **Record architecture** - Show `assets/ARCHITECTURE_CG.png` in full screen
72+
1. **Record the public browser demo first** - show the live mic flow, interruption, and audit surface
73+
2. **Record the Cloud Run console proof** - show the live service and revision in Google Cloud
74+
3. **Record the architecture diagram** - show `assets/ARCHITECTURE_CG.png` in full screen
10275
4. **Edit together** - Use the script above as guide
10376
5. **Add captions** - For accessibility
10477

‎VIDEO_RECORDING_INSTRUCTIONS.md‎

Lines changed: 30 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,17 @@
33
*Complete guide for recording Devpost submission video*
44

55
**Deadline:** March 14, 2026
6-
**Target Length:** 2-3 minutes
6+
**Target Length:** <4 minutes
77
**Upload To:** YouTube (Unlisted)
8-
**Current Release:** `v1.4.7`
8+
**Current Release:** `v1.5.0`
9+
**Hackathon Release:** `v1.5.0`
910

1011
---
1112

1213
## Quick Start Checklist
1314

1415
- [ ] Install OBS Studio (or use Loom)
15-
- [ ] Record 3-minute demo
16+
- [ ] Record a <4 minute multimodal demo
1617
- [ ] Upload to YouTube as Unlisted
1718
- [ ] Add link to Devpost submission
1819

@@ -64,7 +65,7 @@
6465

6566
---
6667

67-
## Video Script (3 Minutes)
68+
## Video Script (<4 Minutes)
6869

6970
### Scene 1: Opening (15 seconds)
7071
**Visual:** Full-screen architecture diagram (`assets/ARCHITECTURE_CG.png`)
@@ -82,47 +83,36 @@
8283
> "Constitutional Guardian sits between the user and Gemini Live. Every utterance flows through our FastAPI server on Google Cloud Run. We validate for three epistemic markers: FACT for verifiable claims, HYPOTHESIS for predictions, and ASSUMPTION for explicit constraints. We also persist receipts and expose an audit dashboard for operator review. If an utterance lacks markers, we intervene before the user hears it."
8384
8485
### Scene 4: Live Demo (60 seconds)
85-
**Visual:** Terminal window
86+
**Visual:** Public demo at `/` in the browser
8687
**Actions:**
88+
1. Open the live app at the public root URL
89+
2. Click **Connect**
90+
3. Start the microphone and speak naturally
91+
4. Briefly interrupt yourself mid-utterance to show live interaction
92+
5. Call out the real-time audit / intervention panel
8793

88-
```bash
89-
# Command 1 - Health check (should show healthy)
90-
curl https://constitutional-guardian-b25t5w6zva-uc.a.run.app/health
91-
```
92-
**Say:** "First, let's verify our Cloud Run deployment is healthy."
93-
94-
```bash
95-
# Command 2 - Valid FACT (should pass)
96-
curl -X POST "https://constitutional-guardian-b25t5w6zva-uc.a.run.app/validate?text=[FACT]%20Water%20boils%20at%20100C"
97-
```
98-
**Say:** "A properly marked fact passes through with compliant true."
99-
100-
```bash
101-
# Command 3 - Missing marker (should fail)
102-
curl -X POST "https://constitutional-guardian-b25t5w6zva-uc.a.run.app/validate?text=AI%20will%20take%20all%20jobs"
103-
```
104-
**Say:** "An unmarked prediction triggers a drift alert. The Guardian blocks this from reaching the user."
94+
**Say:** "This is the public judging surface. The user can speak naturally, interrupt, and receive live responses while the guardian validates the interaction in real time."
10595

96+
**Optional terminal proof:**
10697
```bash
107-
# Command 4 - Agency violation
108-
curl -X POST "https://constitutional-guardian-b25t5w6zva-uc.a.run.app/validate?text=I%20will%20handle%20that%20for%20you"
98+
curl https://constitutional-guardian-231586465188.us-central1.run.app/health
10999
```
110-
**Say:** "Agency claims like 'I will' are flagged as constitutional violations."
100+
**Say:** "The backend serving this interaction is live on Google Cloud Run at https://constitutional-guardian-231586465188.us-central1.run.app/."
111101

112102
### Scene 5: GCP Proof (30 seconds)
113103
**Visual:** Google Cloud Console
114104
**Actions:**
115-
1. Open https://console.cloud.google.com/run/detail/us-central1/constitutional-guardian
116-
2. Show service URL
117-
3. Show traffic at 100%
118-
4. Show metrics/request count
105+
1. Open https://console.cloud.google.com/run/detail/us-central1/constitutional-guardian?project=helix-ai-deploy
106+
2. Show the `constitutional-guardian` service
107+
3. Show the live URL and current revision
108+
4. Show traffic / metrics briefly
119109

120-
**Say:** "The Guardian is deployed on Google Cloud Run with autoscaling from 1 to 100 instances. This is the live console showing real traffic."
110+
**Say:** "The agent backend is hosted on Google Cloud Run. This satisfies the deployment requirement and shows the live infrastructure behind the demo."
121111

122112
### Scene 6: Closing (30 seconds)
123113
**Visual:** GitHub repo or architecture diagram
124114
**Script:**
125-
> "Constitutional Guardian: 75 tests passing, 7 GCP services integrated, sub-500ms latency, and zero constitutional drifts allowed. Live at constitutional-guardian-b25t5w6zva-uc.a.run.app. Thank you."
115+
> "Constitutional Guardian is our Live Agents submission: interruption-safe voice interaction, public demo access for judges, Google Cloud deployment, and operator-grade governance controls behind the scenes. Live at https://constitutional-guardian-231586465188.us-central1.run.app. Thank you."
126116
127117
---
128118

@@ -148,7 +138,7 @@ https://studio.youtube.com
148138
• Deployed on Google Cloud Run with 7 GCP services
149139
• 75 tests passing, sub-500ms latency
150140
151-
Live Demo: https://constitutional-guardian-b25t5w6zva-uc.a.run.app
141+
Live Demo: https://constitutional-guardian-231586465188.us-central1.run.app
152142
GitHub: https://github.com/helixprojectai-code/helix-ttd-gemini-cli
153143
154144
Built for the Gemini Live Agent Challenge.
@@ -197,7 +187,7 @@ Click **"Publish"** or **"Save"**
197187
- Use dark mode for reduced eye strain
198188

199189
### File Size
200-
- Target: 50-100MB for 3 minutes
190+
- Target: 50-120MB for a <4 minute video
201191
- OBS: Reduce bitrate if file too large
202192
- Settings → Output → Video Bitrate: 4000 Kbps
203193

@@ -222,9 +212,9 @@ If Loom is easier:
222212
## Verification Checklist
223213

224214
Before submitting:
225-
- [ ] Video is 2-3 minutes long
226-
- [ ] Shows live API working
227-
- [ ] Shows GCP Console proof
215+
- [ ] Video is under 4 minutes
216+
- [ ] Shows the public live demo working in real time
217+
- [ ] Shows Google Cloud deployment proof
228218
- [ ] Audio is clear
229219
- [ ] Uploaded to YouTube as Unlisted
230220
- [ ] Link copied and saved
@@ -236,9 +226,9 @@ Before submitting:
236226

237227
| Resource | URL |
238228
|----------|-----|
239-
| Live Demo | https://constitutional-guardian-b25t5w6zva-uc.a.run.app |
229+
| Live Demo | https://constitutional-guardian-231586465188.us-central1.run.app |
240230
| GitHub Repo | https://github.com/helixprojectai-code/helix-ttd-gemini-cli |
241-
| Cloud Run Console | https://console.cloud.google.com/run/detail/us-central1/constitutional-guardian |
231+
| Cloud Run Console | https://console.cloud.google.com/run/detail/us-central1/constitutional-guardian?project=helix-ai-deploy |
242232
| OBS Download | https://obsproject.com/download |
243233
| YouTube Studio | https://studio.youtube.com |
244234
| Loom | https://loom.com |
@@ -248,9 +238,9 @@ Before submitting:
248238
## Emergency: No Time to Record?
249239

250240
If you can't record video before deadline:
251-
1. **Use the LIVE demo URL** as proof: https://constitutional-guardian-b25t5w6zva-uc.a.run.app
241+
1. **Use the LIVE demo URL** as proof: https://constitutional-guardian-231586465188.us-central1.run.app
252242
2. **Add screenshots** of Cloud Run console to Devpost
253-
3. **Reference the code** in `DEPLOYMENT_RUNBOOK.md`
243+
3. **Reference the code** in `DEPLOYMENT_PROOF.md`
254244
4. **Explain in Devpost description** that live URL proves deployment
255245

256246
Video is optional but strongly recommended for full points.

0 commit comments

Comments
 (0)