From 73f638388de0d868ced53c901d35c27751cf4d57 Mon Sep 17 00:00:00 2001 From: Caspar Addyman Date: Fri, 16 Oct 2026 14:30:45 +0000 Subject: [PATCH 01/48] specs: 025 results out (spec, plan, tasks) Roadmap v1.6.0 Phase 3: one table of every pipeline's results for R or Python, ELAN files, and a methods paragraph with BibTeX, plus worked notebooks. Done before 023 (viewer overhaul): it is the release's main goal, an outside lab getting from install to results without help. Co-Authored-By: Claude Opus 5.5 --- .specify/feature.json | 2 +- CLAUDE.md | 13 +- .../checklists/requirements.md | 38 ++ specs/025-results-out/contracts/api.md | 55 +++ specs/025-results-out/contracts/cli.md | 29 ++ .../contracts/elan-and-methods.md | 50 +++ specs/025-results-out/contracts/table.md | 76 ++++ specs/025-results-out/data-model.md | 110 +++++ specs/025-results-out/plan.md | 125 ++++++ specs/025-results-out/quickstart.md | 72 ++++ specs/025-results-out/research.md | 233 +++++++++++ specs/025-results-out/spec.md | 396 ++++++++++++++++++ specs/025-results-out/tasks.md | 143 +++++++ 13 files changed, 1335 insertions(+), 7 deletions(-) create mode 100644 specs/025-results-out/checklists/requirements.md create mode 100644 specs/025-results-out/contracts/api.md create mode 100644 specs/025-results-out/contracts/cli.md create mode 100644 specs/025-results-out/contracts/elan-and-methods.md create mode 100644 specs/025-results-out/contracts/table.md create mode 100644 specs/025-results-out/data-model.md create mode 100644 specs/025-results-out/plan.md create mode 100644 specs/025-results-out/quickstart.md create mode 100644 specs/025-results-out/research.md create mode 100644 specs/025-results-out/spec.md create mode 100644 specs/025-results-out/tasks.md diff --git a/.specify/feature.json b/.specify/feature.json index a01f9d18..61c358a4 100644 --- a/.specify/feature.json +++ b/.specify/feature.json @@ -1,3 +1,3 @@ { - "feature_directory": "specs/024-container-feels-local" + "feature_directory": "specs/025-results-out" } diff --git a/CLAUDE.md b/CLAUDE.md index 6c92beb4..3c9a98dc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -55,12 +55,13 @@ against it. ## Current Plan -`specs/024-container-feels-local/plan.md`: researchers start VideoAnnotator with `launcher/ -videoannotator-start` (sh, plus a PowerShell twin), which finds Docker or Podman, shares chosen -folders read-only at their real paths (remembered in a host `start.conf`), runs the slim GHCR -image on 127.0.0.1 and opens the viewer connected. App, installed pipelines (restored after -updates and restarts), model weights, activity and the researcher's files each persist on their -own. Inside a container the server never lists its own filesystem. After 024: +`specs/025-results-out/plan.md` (roadmap v1.6.0 Phase 3): results out of VideoAnnotator for +analysis. One long-format table (CSV; Parquet with the `parquet` extra), one ELAN `.eaf` per video, +and a methods paragraph with BibTeX, all built from the output files and their spec 017 provenance +by `src/videoannotator/exporters/`, so `videoannotator export table|elan|methods ` (no +server), the API (`/export/...`, `/methods` on jobs, batches, datasets) and the viewer's Export menu +agree. Plus R and Python notebooks in `examples/notebooks/`. Native outputs don't change. Before +025: spec 024 (container launcher; T082 walkthrough open). After 025: `specs/023-viewer-overhaul` (needs research first). diff --git a/specs/025-results-out/checklists/requirements.md b/specs/025-results-out/checklists/requirements.md new file mode 100644 index 00000000..992fe20a --- /dev/null +++ b/specs/025-results-out/checklists/requirements.md @@ -0,0 +1,38 @@ +# Specification Quality Checklist: Results Out + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-10-16 +**Feature**: [spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- The feature is about file formats researchers consume, so the formats themselves (CSV, Parquet, + ELAN `.eaf`, BibTeX) and the analysis languages (R, Python) are named: they are the user-facing + outcome, not implementation choices. The column list (FR-001) is likewise the user-facing contract. +- No clarifications asked: defaults chosen and recorded in Assumptions (long layout, Parquet as an + optional component, on-request exports, ELAN gap tolerance). diff --git a/specs/025-results-out/contracts/api.md b/specs/025-results-out/contracts/api.md new file mode 100644 index 00000000..42ffa9d8 --- /dev/null +++ b/specs/025-results-out/contracts/api.md @@ -0,0 +1,55 @@ +# Contract: Export API + +All routes need the same API key as the job/batch/dataset routes they sit beside +(`validate_api_key`); no admin requirement. Work runs in a worker thread. + +## Table + +``` +GET /api/v1/jobs/{job_id}/export/table?format=csv|parquet +GET /api/v1/batches/{batch_id}/export/table?format=csv|parquet +GET /api/v1/datasets/{dataset_id}/export/table?format=csv|parquet +``` + +- `format` defaults to `csv`. +- 200: the file. `Content-Type: text/csv; charset=utf-8` or `application/vnd.apache.parquet`. + `Content-Disposition: attachment` with filename `.csv|.parquet` (dataset: + `.csv`), RFC 5987 `filename*` for non-ASCII. +- Header `X-VideoAnnotator-Export-Summary`: the export summary (data-model.md), ASCII JSON, at most + 8 KB (lists cut and `"truncated": true` past that). Listed in `Access-Control-Expose-Headers`. +- 404 `JOB_NOT_FOUND` / `BATCH_NOT_FOUND` / `DATASET_NOT_FOUND`. +- 409 `NOTHING_TO_EXPORT`: no result files at all; `message` says why (still running, failed with + ``, no runs of this dataset). +- 422 `PARQUET_NOT_INSTALLED`: `hint` = `pip install videoannotator[parquet]`, `details.extra` = + `parquet` (the viewer offers spec 005's install with it). +- 422 for an unknown `format`. + +## ELAN + +``` +GET /api/v1/jobs/{job_id}/export/elan → one .eaf (application/xml), filename