kuberlab/ambient-form repository overview

⁠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

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

uv sync --dev

Run the CLI:

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

Run the API server:

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

⁠Frontend setup

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:

docker compose up --build

⁠Run Dockerized project (step-by-step)

1. Build image:

docker compose build

1. Start in background:

docker compose up -d

1. Verify service is healthy:

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

1. Open app:

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

1. View logs:

docker compose logs -f ambientform

1. Stop and remove container:

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:

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 prompts

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.