AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• extractor.py contains PDF rendering, template selection, and OpenAI calls.
• templates/ holds JSON extraction templates referenced by TEMPLATE_REGISTRY.
• src/streamlit_app.py is the Hugging Face Space UI entrypoint.
• Dockerfile builds the Space image (Streamlit on port 8501).
• .streamlit/config.toml contains Space-friendly Streamlit server settings.
• README.md includes Space metadata front matter and usage notes.
• The UI relies on filename keywords to select templates (see TEMPLATE_REGISTRY).
• Sample PDFs are fetched from the HF dataset set by SAMPLE_DATASET_REPO.

Build, Test, and Development Commands

• Install dependencies with python -m pip install -r requirements.txt.
• Local CLI extraction prompts for a PDF path and prints JSON:
  • python extractor.py
• Run the Space UI locally:
  • streamlit run src/streamlit_app.py
• Quick import sanity check:
  • python -c "import extractor; print(extractor.DEFAULT_MODEL)"

Coding Style & Naming Conventions

• Keep 2-space indentation in extractor.py.
• Use snake_case for functions/variables, UPPER_SNAKE for constants, and add type hints for new functions.
• Template JSON filenames should be snake_case and registered via lowercase filename keywords in TEMPLATE_REGISTRY.

Testing Guidelines

• No automated test suite exists yet. If adding tests, use pytest under tests/.
• Validate that model output matches the exact template schema and that filename keywords map to the right template.

Commit & Pull Request Guidelines

• No established commit convention; use short, imperative subjects.
• PRs should include the document type, template files touched, example filename keyword, and any config/env changes.

Security & Configuration Tips

• Set OPENAI_API_KEY for local runs and the Space; optionally override EXTRACTOR_MODEL_ALIAS.
• Avoid committing sensitive PDFs or output data; use redacted samples for demos.

Automation

• .github/workflows/sync-hf.yml pushes main to the HF Space on each commit using HF_TOKEN.
• Treat GitHub as the source of truth; direct edits on HF may be overwritten.
• The workflow force-pushes a fresh snapshot to avoid blocked legacy binaries in history.