---
name: pssrag-batch-questions
description: Submit CSV or JSON question sets to the PSSRAG PoC batch API, monitor processing, and return grounded answers with citations. Use when a user asks to run many questions against uploaded RAG documents, submit PotentialQuestions-style test cases, check a batch, or export batch results.
---

# PSSRAG Batch Questions

Submit and monitor question batches through the user-facing `/api/v1` contract. Do not call internal evaluation routes unless the user explicitly asks for an evaluation run.

## Workflow

1. Read [references/api.md](references/api.md) before constructing a request.
2. Resolve the base URL from `PSSRAG_BASE_URL`; default to `https://pssrag.hydsoft.site`.
3. Normalize each input row to `id`, `question`, and optional `source_name` or `document_ids`.
4. Preserve duplicate questions as separate rows with distinct IDs.
5. Submit with `scripts/submit_batch.py` or the equivalent API call.
6. Poll until `completed`, `partial`, or `failed` when the user asks for final results.
7. Report failed row IDs separately. For completed answers, preserve answer text and citation locators exactly as returned.

## Input Rules

- Accept JSON containing either a top-level array or `{ "questions": [...] }`.
- Accept CSV with `id,question` and optional `source_name` columns.
- For `PotentialQuestions.xlsx`, read the workbook with the spreadsheet workflow and convert rows to JSON without changing question text.
- If IDs are missing, assign deterministic row IDs such as `q_0001`.
- Do not collapse repeated questions; they may intentionally test repeatability.

## Run

```bash
python scripts/submit_batch.py questions.json --wait --output results.json
```

Use `--name` for a recognizable batch name and `--poll-seconds` to adjust polling. Never print API keys or place them in a request body.

## Output Rules

- Treat `partial` as a terminal state and show both completed and failed counts.
- Do not invent answers for failed rows.
- Do not rewrite citation IDs, source names, page numbers, cell ranges, email locators, or image bounding boxes.
- Report any `flags` returned with an answer; `calculation_unverified` means a numeric claim was not deterministically checked and should be called out, not silently passed through.
- Do not recompute values in `calculations[]`; they are already evaluated and substituted.
- Do not expose hidden-judge prompts or provisional fact baselines through this user-facing skill.