docs generate¶

Generate an EU AI Act Annex IV technical documentation dossier (REQ-DOC-001).

Synopsis¶

opencomplai docs generate --system-id <id> [OPTIONS]

opencomplai docs generate --system-id <id> [OPTIONS]

Options¶

Modes¶

Service-backed mode (when OPENCOMPLAI_API_URL is set): sends POST /v1/docs/generate to the doc-generator service. The dossier is stored server-side and its metadata is returned.

Local mode (when OPENCOMPLAI_API_URL is unset): generates the dossier in-process with the Annex IV generator shipped in opencomplai-core (installed with opencomplai-cli, so this works from a plain pip install) and writes dossier_<id>.json to --output-dir.

Examples¶

# Service-backed (Docker Compose stack running)
OPENCOMPLAI_API_URL=http://localhost:8080 opencomplai docs generate \
  --system-id "loan-decision-model" \
  --commit-ref "$(git rev-parse HEAD)" \
  --intended-purpose "automated credit scoring for retail lending" \
  --provider-name "ACME Financial AI"

# Local generation
opencomplai docs generate \
  --system-id "loan-decision-model" \
  --intended-purpose "automated credit scoring for retail lending" \
  --provider-name "ACME Financial AI" \
  --output-dir ./compliance-docs/

# Service-backed (Docker Compose stack running)
$env:OPENCOMPLAI_API_URL = "http://localhost:8080"; opencomplai docs generate --system-id "loan-decision-model" --commit-ref (git rev-parse HEAD) --intended-purpose "automated credit scoring for retail lending" --provider-name "ACME Financial AI"

# Local generation
opencomplai docs generate --system-id "loan-decision-model" --intended-purpose "automated credit scoring for retail lending" --provider-name "ACME Financial AI" --output-dir ./compliance-docs/

Output (human)¶

Annex IV Dossier Generated
  dossier_id:      d4f9c2a1-...
  bundle_checksum: sha256:3e2f1a...
  schema:          valid
  duration_ms:     142

Output (JSON)¶

{
  "dossier_id": "d4f9c2a1-...",
  "bundle_checksum": "sha256:3e2f1a...",
  "schema_valid": true,
  "duration_ms": 142
}

Sidecar reports (D10)¶

--scan-report and --eval-report default to scan-report.json and eval-report.json in the current directory — the same files opencomplai check/opencomplai gaps write automatically when a scan or eval actually ran. If either file exists, generate loads it and populates the corresponding wired-evidence fields on the dossier (Section 5 scanner fields, eval-merged metrics). If neither exists, those fields stay exactly as empty as they are without them — nothing is fabricated to fill the gap. See the Annex IV coverage ledger for which dossier fields are automated, wired evidence, or provider attestation.

Fail-closed dossier gate¶

An invalid Annex IV dossier (schema_valid: false — see validate_dossier_schema) is refused by default: the dossier is still written to --output-dir (or persisted server-side in service-backed mode) so an auditor can see exactly what failed, but the process exits 2 (VALIDATION_FAIL) instead of 0. This also applies to the doc-generator service, which returns HTTP 422 instead of 200 for the same case.

Existing CI pipelines that relied on docs generate always exiting 0 must add --allow-incomplete (CLI) or allow_incomplete: true (service request body) to restore the old behaviour — the dossier is generated and written identically either way; only the exit code / HTTP status changes.

Rendered output¶

--render md writes dossier_<id>.md and --render pdf writes dossier_<id>.pdf next to the JSON (--render md --render pdf writes both). Without --render only the JSON is written. The files show what the dossier contains and nothing more: a provider placeholder, a "not specified" stub or an empty field is printed as NOT PROVIDED, and a dossier that fails validation, has a stub Section 2 or has annex_iv_complete false starts with an INCOMPLETE banner listing why. The exit code is unchanged: an incomplete HIGH-risk dossier still exits 2 (without --allow-incomplete) after its renders are written. Rendering is not signed and verify checks the JSON file only. PDF output needs the reports extra (fpdf2); if it is missing the command exits 1 after writing the JSON and Markdown.

Halt / resume¶

If the system is currently HALTED_PENDING_REVIEW (see check), generate refuses outright and exits 4 — no dossier is written, and there is no --force bypass. Resume with opencomplai approve then opencomplai resume before retrying.

Exit codes¶