kuberlab/ambient-form

Ambient Form Codex Project

This repository packages the Ambient Form workflow as:

• a Python CLI
• a FastAPI server
• a React frontend
• Codex-friendly repository instructions and skills

Project layout

text
backend/                     Python CLI + FastAPI service
frontend/                    Vite + React UI
examples/                    Example PDF and transcript
.agents/skills/              Repo-scoped Codex skill
AGENTS.md                    Repo instructions for Codex
pyproject.toml               Python project definition for uv

Requirements

• Python 3.11+
• Node 20+
• uv for Python environment management
• optional: OPENAI_API_KEY for model-based extraction

Runtime environment variables

Python setup with uv

bash
uv sync --dev

Run the CLI:

bash
uv run python backend/pdf_schema_extract_fill.py \
  --pdf examples/Bilan_Prevention_45.pdf \
  --text "examples/michael interview.txt"

Run the API server:

bash
uv run python backend/pdf_schema_extract_fill.py serve --host 0.0.0.0 --port 8000

Frontend setup

bash
cd frontend
npm install
npm run dev

The Vite dev server proxies all /api requests to the backend at http://localhost:8000, so no environment variables are needed. Start the backend first, then the frontend.

Docker (single container, no nginx)

The repository includes a multi-stage Docker setup where:

• frontend is built with Vite during image build — no build-time environment variables required
• FastAPI serves both API routes and frontend static assets from frontend/dist
• one container exposes the app at http://localhost:8000
• all frontend API calls use relative paths (/api/…), so the image is host-agnostic

CORS is open (*) by default. To restrict to specific origins, set CORS_ALLOW_ORIGINS at runtime (see docker-compose.yml for the commented example).

Build and run:

bash
docker compose up --build

Run Dockerized project (step-by-step)

1. Build image:

bash
docker compose build

2. Start in background:

bash
docker compose up -d

3. Verify service is healthy:

bash
curl http://localhost:8000/api/health

4. Open app:

• UI: http://localhost:8000
• API docs: http://localhost:8000/docs

5. View logs:

bash
docker compose logs -f ambientform

6. Stop and remove container:

bash
docker compose down

Then open:

• UI: http://localhost:8000
• API health: http://localhost:8000/api/health

Persistent data:

• ./data on host is mounted to /app/data in container
• cache/upload artifacts (used by upload_id) are stored under /app/data/cache

Run backend CLI inside the container:

bash
docker compose run --rm ambientform \
  /app/.venv/bin/python backend/pdf_schema_extract_fill.py \
  --pdf examples/Bilan_Prevention_45.pdf \
  --text "examples/michael interview.txt"

PDF rendering

The frontend uses react-pdf backed by PDF.js. The PDF.js worker is bundled from pdfjs-dist at build time and served as a local asset — no external CDN requests are made at runtime.

The form preview supports:

• Table/Card review mode
• Form view rendered with PDF.js for:
  • the original uploaded PDF
  • the filled PDF returned by /api/forms/fill

Codex migration notes

This repository is prepared for Codex-driven production work:

• AGENTS.md contains repository instructions for Codex
• .agents/skills/bilan-prevention/SKILL.md gives Codex workflow-specific guidance
• backend and frontend contracts are documented and should be changed together
• the project keeps local fallback extraction so Codex can iterate without requiring model access for every task

Recommended Codex work sequence:

1. verify the backend API with the example files
2. run the frontend locally
3. improve extraction quality and field mapping
4. add backend tests and frontend integration tests
5. harden PDF preview and export UX
6. add authentication, persistence, and audit history if needed

Suggested Codex pro***s

bash
codex "Review backend request and response contracts and suggest cleanup before production"
codex "Add frontend integration tests for schema upload, extraction, preview, and export"
codex "Improve local extraction rules for real-world French interviews"
codex "Refactor App.jsx into components while keeping pdf.js preview working"

Notes

• The backend keeps local fallback extraction so the prototype still works when no model endpoint is available.
• The frontend exports a filled PDF through the backend /api/forms/fill route using upload_id returned by /api/forms/schema.
• The PDF form preview uses PDF.js (react-pdf) with a self-hosted worker — no iframe embedding, no external CDN dependency.