OSS/podman
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: fix mangled README title

Browse Source 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LuV8W8oNYRsDWKoqK8Mkqc
This commit is contained in:
Ramis
2026-06-28 06:41:34 -07:00
parent 12dbf69431
commit 0077e0d7c3
1 changed files with 92 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+46 -12
View File
@@ -1,9 +1,9 @@
# PodMan — A Pair Programmer for Engineering Teams # PodMan — A Pair Programmer for Engineering Teams
[![LiveKit](https://img.shields.io/badge/LiveKit-realtime-000000?logo=livekit&logoColor=white)](https://livekit.io/) [LiveKit](https://livekit.io/)
[![MongoDB](https://img.shields.io/badge/MongoDB-vector%20memory-47A248?logo=mongodb&logoColor=white)](https://www.mongodb.com/) [MongoDB](https://www.mongodb.com/)
[![Gemini](https://img.shields.io/badge/Gemini-3.x%20Live%20%2B%20Vision%20%2B%20Lyria-8E75B2?logo=googlegemini&logoColor=white)](https://ai.google.dev/) [Gemini](https://ai.google.dev/)
[![DigitalOcean](https://img.shields.io/badge/DigitalOcean-deploy-0080FF?logo=digitalocean&logoColor=white)](https://www.digitalocean.com/) [DigitalOcean](https://www.digitalocean.com/)
**2026 AI Engineer World's Fair Hackathon — Theme: Continual Learning** **2026 AI Engineer World's Fair Hackathon — Theme: Continual Learning**
@@ -47,6 +47,8 @@ time.
--- ---
## How it learns ## How it learns
The learning loop is the product, not a side feature. It runs with almost no The learning loop is the product, not a side feature. It runs with almost no
@@ -58,8 +60,9 @@ observe → detect → RECALL prior outcomes → policy gate → act → record
└──────────────────────────── feeds next recall ───────────────────────────┘ └──────────────────────────── feeds next recall ───────────────────────────┘
``` ```
| Stage | What happens | Code | | Stage | What happens | Code |
| --- | --- | --- | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| **Observe** | Gemini Vision turns each screen frame into structured work context (file, symbol, activity, unpushed hints) | `backend/src/vision/gemini.ts` | | **Observe** | Gemini Vision turns each screen frame into structured work context (file, symbol, activity, unpushed hints) | `backend/src/vision/gemini.ts` |
| **Detect** | Same file touched by 2+ engineers with unpushed work → a coordination event | `backend/src/collision/detector.ts` | | **Detect** | Same file touched by 2+ engineers with unpushed work → a coordination event | `backend/src/collision/detector.ts` |
| **Recall (memory)** | Embed the event, query MongoDB Atlas `$vectorSearch` for similar past events, attach their prior intervention + outcome | `backend/src/memory/vectors.ts` | | **Recall (memory)** | Embed the event, query MongoDB Atlas `$vectorSearch` for similar past events, attach their prior intervention + outcome | `backend/src/memory/vectors.ts` |
@@ -67,15 +70,16 @@ observe → detect → RECALL prior outcomes → policy gate → act → record
| **Act (least intrusive)** | Reuse the action kind that was accepted before; default to a card, escalate to a Hermes message, voice only when urgent | `backend/src/action/hermes.ts` | | **Act (least intrusive)** | Reuse the action kind that was accepted before; default to a card, escalate to a Hermes message, voice only when urgent | `backend/src/action/hermes.ts` |
| **Record (feedback)** | Accept/dismiss + "was it real?" is written back to memory, closing the loop for next time | `backend/src/memory/store.ts` | | **Record (feedback)** | Accept/dismiss + "was it real?" is written back to memory, closing the loop for next time | `backend/src/memory/store.ts` |
A few things make this real learning rather than a static prompt: A few things make this real learning rather than a static prompt:
- It adapts from real teammate behavior during a real session, not an offline - It adapts from real teammate behavior during a real session, not an offline
dataset. dataset.
- It gets more useful as the `outcomes` collection grows — better recall, fewer - It gets more useful as the `outcomes` collection grows — better recall, fewer
false alarms. false alarms.
- It needs one tap. No labeling, no config, no retraining. - It needs one tap. No labeling, no config, no retraining.
- The mechanism is memory: Atlas vector recall plus an outcome-conditioned - The mechanism is memory: Atlas vector recall plus an outcome-conditioned
policy, with an exact-signature fallback when vector search isn't available. policy, with an exact-signature fallback when vector search isn't available.
In practice: a false alarm gets dismissed once, and the same pattern stays quiet In practice: a false alarm gets dismissed once, and the same pattern stays quiet
next time. A real conflict gets accepted once, and when it recurs PodMan recalls next time. A real conflict gets accepted once, and when it recurs PodMan recalls
@@ -83,6 +87,8 @@ it and escalates straight to a spoken "seen before" cue.
--- ---
## Architecture ## Architecture
A browser PWA, an HTTP API service, LiveKit agent workers, and a A browser PWA, an HTTP API service, LiveKit agent workers, and a
@@ -138,10 +144,15 @@ flowchart LR
API --> Mongo API --> Mongo
``` ```
### Runtime shape ### Runtime shape
| Layer | Runtime | Responsibility | | Layer | Runtime | Responsibility |
| --- | --- | --- | | ----------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------- |
| Frontend PWA | React + Vite | Join pods, publish screen share, render interventions, play audio | | Frontend PWA | React + Vite | Join pods, publish screen share, render interventions, play audio |
| Backend API | Express | Mint LiveKit tokens, manage pods, record outcomes, expose memory stats, create sync PRs | | Backend API | Express | Mint LiveKit tokens, manage pods, record outcomes, expose memory stats, create sync PRs |
| Vision agent | `@livekit/rtc-node` | Subscribe to screen-share tracks, sample frames, publish intervention data | | Vision agent | `@livekit/rtc-node` | Subscribe to screen-share tracks, sample frames, publish intervention data |
@@ -152,6 +163,9 @@ flowchart LR
| Action layer | Hermes | Cards, teammate messages, Gemini TTS urgent voice, Lyria background score | | Action layer | Hermes | Cards, teammate messages, Gemini TTS urgent voice, Lyria background score |
| Deployment | DigitalOcean | Static frontend, API service, agent workers | | Deployment | DigitalOcean | Static frontend, API service, agent workers |
### Data flow ### Data flow
```mermaid ```mermaid
@@ -181,22 +195,28 @@ sequenceDiagram
API->>Mongo: Store learning signal API->>Mongo: Store learning signal
``` ```
--- ---
## Built with ## Built with
Everything below maps to code in this repo. Everything below maps to code in this repo.
**Gemini** does the perception, the voice, and the memory: **Gemini** does the perception, the voice, and the memory:
| Use | Model | Where | | Use | Model | Where |
| --- | --- | --- | | --------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------ |
| Real-time voice agent (talk to PodMan, answered with repo/git/memory tools) | `gemini-3.1-flash-live-preview` | `agents/podman-live-conversation/agent.py` | | Real-time voice agent (talk to PodMan, answered with repo/git/memory tools) | `gemini-3.1-flash-live-preview` | `agents/podman-live-conversation/agent.py` |
| Spoken urgent alerts over LiveKit | `gemini-3.1-flash-tts-preview` | `backend/src/voice/live.ts` | | Spoken urgent alerts over LiveKit | `gemini-3.1-flash-tts-preview` | `backend/src/voice/live.ts` |
| Screen understanding → structured work context | `gemini-2.0-flash` | `backend/src/vision/gemini.ts` | | Screen understanding → structured work context | `gemini-2.0-flash` | `backend/src/vision/gemini.ts` |
| Per-pod background music (Interactions API) | `lyria-3-clip-preview` | `backend/src/voice/music.ts` | | Per-pod background music (Interactions API) | `lyria-3-clip-preview` | `backend/src/voice/music.ts` |
| Embeddings for memory recall | `gemini-embedding-001` | `backend/src/memory/vectors.ts` | | Embeddings for memory recall | `gemini-embedding-001` | `backend/src/memory/vectors.ts` |
**LiveKit** is the real-time layer: screen-share tracks are the input, a typed **LiveKit** is the real-time layer: screen-share tracks are the input, a typed
data channel (`podman.intervention`) carries cards and messages, audio tracks data channel (`podman.intervention`) carries cards and messages, audio tracks
carry the spoken alerts and music, and a Python LiveKit Agents worker runs the carry the spoken alerts and music, and a Python LiveKit Agents worker runs the
@@ -212,6 +232,8 @@ fail loudly rather than degrade silently.
--- ---
## How it works ## How it works
1. Engineers open the PWA and join a pod room. 1. Engineers open the PWA and join a pod room.
@@ -236,10 +258,13 @@ in the repo — answered with real tool calls, not guesses.
--- ---
## Public interfaces ## Public interfaces
| Interface | Purpose | | Interface | Purpose |
| --- | --- | | ----------------------------------------------------------- | ------------------------------------------------- |
| `GET /health` | API health check | | `GET /health` | API health check |
| `POST /api/token` | Mint LiveKit room tokens | | `POST /api/token` | Mint LiveKit room tokens |
| `POST /api/sync-pr` | Create a visible sync PR artifact | | `POST /api/sync-pr` | Create a visible sync PR artifact |
@@ -250,12 +275,16 @@ in the repo — answered with real tool calls, not guesses.
| LiveKit topic `podman.intervention` | Intervention data channel | | LiveKit topic `podman.intervention` | Intervention data channel |
| Wire messages `COLLISION`, `ACK`, `GIT_REPORT`, `VOICE_CUE` | Agent/PWA contract | | Wire messages `COLLISION`, `ACK`, `GIT_REPORT`, `VOICE_CUE` | Agent/PWA contract |
--- ---
## Monorepo layout ## Monorepo layout
| Folder | What | | Folder | What |
| --- | --- | | ----------- | -------------------------------------------------------------------------- |
| `frontend/` | React + Vite PWA — pods, LiveKit room UI, screen share, intervention cards | | `frontend/` | React + Vite PWA — pods, LiveKit room UI, screen share, intervention cards |
| `backend/` | Express API plus the LiveKit vision agent worker | | `backend/` | Express API plus the LiveKit vision agent worker |
| `agents/` | Python LiveKit Agents worker for the Gemini Live conversation agent | | `agents/` | Python LiveKit Agents worker for the Gemini Live conversation agent |
@@ -265,8 +294,11 @@ in the repo — answered with real tool calls, not guesses.
| `scripts/` | Local git watcher + deploy/verify tooling | | `scripts/` | Local git watcher + deploy/verify tooling |
| `docs/` | Integration specs and the demo script | | `docs/` | Integration specs and the demo script |
--- ---
## Quick start ## Quick start
```bash ```bash
@@ -283,6 +315,8 @@ The live conversation agent (Gemini Live API) runs from `agents/podman-live-conv
--- ---
## Git watcher — run on every demo laptop ## Git watcher — run on every demo laptop
Each engineer runs this before the demo. It polls the local git working tree Each engineer runs this before the demo. It polls the local git working tree