Files · Field Punch-List Agent for GC Superintendents

# Field Punch-List Agent for GC Superintendents
 
> Capture photo + voice memo punch items that sync directly to PM tools.
 
## Problem
 
GC superintendents need a fast, mobile-friendly way to capture punch-list defects during site walks. Voice memos and photos must be automatically transcribed, categorized, and synced to project management tools without manual data entry.
 
## Architecture Pipeline
 
```
Voice/Photo → STT (Deepgram Nova-2) → LLM Extraction (GPT-5.2) → Guardrail Chain → Agent Memory → Webhook Sync → PM Tool
```
 
## Setup
 
```bash
pnpm install
cp .env.example .env
pnpm dev
```
 
## API Usage
 
### Voice Upload
 
```bash
curl -X POST http://localhost:3000/voice/upload \
  -F "audio=@recording.wav" \
  -H "Authorization: Bearer dev-key"
```
 
### Photo Upload
 
```bash
curl -X POST http://localhost:3000/photo/upload \
  -F "image=@defect.jpg" \
  -H "Authorization: Bearer dev-key"
```
 
### Punch Items CRUD
 
```bash
# List
curl http://localhost:3000/api/punch-items?projectId=p1
 
# Create
curl -X POST http://localhost:3000/api/punch-items \
  -H "Content-Type: application/json" \
  -d '{"projectId":"p1","title":"Cracked drywall","description":"Visible crack at corner"}'
 
# Get by ID
curl http://localhost:3000/api/punch-items/<id>
 
# Update status
curl -X PATCH http://localhost:3000/api/punch-items/<id> \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved"}'
```
 
## Environment Variables
 
| Variable | Description | Default |
|----------|-------------|---------|
| `DEEPGRAM_API_KEY` | Deepgram API key for STT | required |
| `PUNCH_LIST_PM_WEBHOOK_URL` | PM tool webhook URL | "" |
| `PUNCH_LIST_AUTH_API_KEY` | API key for authentication | "dev-key" |
| `PUNCH_LIST_LLM_MODEL` | LLM model for extraction | "openai/gpt-5.2" |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key | "" |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key | "" |
| `LANGFUSE_HOST` | Langfuse host | "https://cloud.langfuse.com" |
| `OPENAI_API_KEY` | OpenAI API key for embeddings | "" |
| `AGENT_MEMORY_STORAGE` | Memory storage backend | "memory" |
 
## License
 
MIT — see [LICENSE](./LICENSE).