[FEAT]: Missing Batch Endpoint for Multi-Form Filing

[Acuspeedster]

---

name: 🚀 Feature Request
about: Suggest an idea or a new capability for FireForm.
title: "[FEAT]: Add batch endpoint for multi-template form filing"
labels: enhancement
assignees: ''

📝 Description

There is currently no API endpoint that accepts:

• One transcript
• A list of template IDs

and returns filled PDFs for all requested agencies in a single request.

Callers must:

• Invoke POST /forms/fill N separate times
• Handle partial failures manually
• Aggregate responses client-side
• Reconcile inconsistencies across requests

This leaks orchestration complexity to the client and prevents treating multi-agency filing as a single logical operation.

---

💡 Rationale

Multi-agency filing is not an edge case — it is the primary operational use case.

The system should:

• Provide atomic orchestration
• Preserve partial successes
• Expose unified batch state
• Avoid redundant extraction (see Issue 1)

A naive batch endpoint that simply loops over the current fill implementation would multiply inefficiencies.

---

🛠️ Proposed Solution

Introduce:

• POST /forms/fill/batch

Request:

• input_text
• template_ids: list[str]

Response:

• Per-template output paths
• Per-template success/failure
• batch_id for status lookup

Add:

• GET /forms/batches/{id}

Requirements:

• Partial success allowed
• Batch never aborts fully due to one template failure
• Batch state persisted

---

✅ Acceptance Criteria

• Single transcript accepted
• Multiple templates processed
• Partial failures preserved
• Batch status persisted
• No redundant transcript extraction

[marcvergees]

That's definitely an idea we had in mind. We'll implement it soon!

[Acuspeedster]

That's definitely an idea we had in mind. We'll implement it soon!

@marcvergees

That’s great to hear it’s encouraging that this aligns with the intended direction.
I’ve opened PR #158 as a concrete implementation of the batch orchestration model described above, including canonical single-pass extraction and concurrent template mapping to avoid redundant LLM calls.
If you have the bandwidth, I would greatly appreciate your review particularly on the architectural separation between extraction, mapping, and audit persistence. I’m very open to iterating to better align with the project’s long-term design goals.

[utkarshqz]

Hi @marcvergees — PR #241 implements this using a template-agnostic single-pass approach.

Rather than extracting into a fixed canonical schema, PR #241 reads actual PDF annotation keys directly from the database, merges them into a dynamic superset, runs one LLM call for the entire batch, then maps results back to each template using deterministic Python key matching — no secondary LLM mapping pass, no hardcoded field categories.

This means it works natively with any PDF structure without configuration, including new agency forms with custom fields. Partial failures are preserved per template — one failed PDF never aborts the batch.

Happy to get your review and iterate!

[Acuspeedster]

@utkarshqz
Thanks for sharing your implementation.
For context, Issue #156 and PR #158 were opened earlier to address batch multi-form filling together with canonical extraction and audit traceability. Over the past few weeks there have been several overlapping PRs opened that re-implement the same ideas in parallel, which makes coordination and review more difficult.
If you’d like to contribute to this feature, it would probably be more productive to collaborate directly on the existing PR rather than opening separate implementations for the same issue. You’re very welcome to commit to the branch for PR #158 so we can iterate on the solution together.
It would also help if we refrain from opening redundant PRs for the same feature and instead converge on a single implementation, while letting the maintainers decide if the architectural direction needs to change.
@marcvergees happy to follow whatever workflow the maintainers prefer here my goal is simply to keep the effort collaborative and aligned with the project’s design direction.
Also this is not the first pr or issue he has been doing this to.

[utkarshqz]

Hi @Acuspeedster, @marcvergees, @vharkins1 —

Happy to clarify the architectural distinction since it matters for the maintainers' decision.

PR #158 extracts into a fixed canonical schema of 26 hardcoded field names, then runs a second LLM mapping call per template — so for T templates that is 1 + T total LLM calls. For a 3-agency batch: 4 calls. PR #241 reads annotation keys directly from whatever PDF is uploaded, merges them into a dynamic superset at runtime, runs exactly one LLM call for the entire batch, then maps results back using deterministic Python. For any batch size: 1 call total.

The more important distinction is scope. FireForm is a UN Digital Public Good explicitly intended for first responders globally — not just US agencies. A UK police form uses "warrant_card_number". An Indian fire department form uses "station_code" and "mandal". A Brazilian ambulance form uses "CRM_number" and "SUS_code". None of these appear in any fixed 26-field schema, and they will silently return null with no error. PR #241 works with all of them natively because it reads whatever annotation keys the uploaded PDF actually contains — zero configuration, zero maintenance, any country, any agency.

The screenshots below show the difference directly. Left: hardcoded canonical categories from PR #158. Right: our dynamic field merging from PR #241 — no field names anywhere in the code, just whatever the PDF contains.

A fixed canonical schema is a reasonable design for a known US form set. For a global UN deployment serving arbitrary agency PDFs across jurisdictions, dynamic field discovery is the more appropriate architectural direction — but this is exactly the kind of decision that should rest with @marcvergees and @vharkins1, not contributors.

I am fully open to consolidating implementations in whichever direction the maintainers prefer. That is their call entirely.

@marcvergees @vharkins1 — happy to follow whatever workflow you set here.

PR #158 — 26 hardcoded field names

PR #241 — reads fields dynamically from whatever PDF is uploaded: