---
title: "Start Preparation"
method: POST
path: "/internal/evals/requirement-applicability/preparation"
tags: ["internal"]
---

# Start Preparation

`POST /internal/evals/requirement-applicability/preparation`

Decompose the guidelines this collateral needs and that nothing has decomposed yet.

Delegates to the customer route's own handler rather than restating it: that function owns a
savepoint per guideline, stale-run reaping, the "a newer version is still processing" refusal, the
per-request batch cap and the dispatch-failure rollback — none of which is worth a second
implementation, and all of which a second one would drift from. `backend/api/internal/runs.py`
reuses `backend/api/runs.py` the same way.

**A guideline with a standing library is never touched.** Keyed on the library a run would gather
from, not on the newest attempt: a decomposition supersedes every requirement it replaces, so
re-running one over a library a compliance reviewer has edited retires their work. A failed retry
above a good library is therefore left alone — the library is what the comparison reads, and the
retry's failure costs the run nothing.

`file_ids` narrows it further, because a company's standards are not all worth decomposing: a
70-page deposit account agreement filed as a marketing standard will yield contract clauses as
marketing requirements, and the operator can see the filenames before spending a pass on each.

## Request body

- PrepareCollateralRequest — Decompose whatever this collateral's product lines put on it and nothing has a library for.
  - `company_id` string, uuid, required
  - `file_id` string, uuid, required
  - `file_ids` string[], nullable

## Response `200`

Successful Response

- CollateralPreparation — What a comparison for this collateral would gather from, and what is missing. Answers the question the run itself cannot: a run against an undecomposed library succeeds and reports "0 of 0 survived", which is indistinguishable from a library that genuinely excludes everything. This says which guidelines have no library *before* anything is judged.
  - `company_id` string, uuid, required
  - `file_id` string, uuid, required
  - `collateral_filename` string, nullable, required
  - `preset_ids` string[], required
  - `unresolved_preset_ids` string[], required
  - `guidelines` GuidelineReadiness[], required
    - `file_id` string, uuid, required
    - `filename` string, nullable, required
    - `status` 'queued' | 'running' | 'succeeded' | 'failed', required — Lifecycle of one decomposition run.
    - `stage` 'queued' | 'downloading' | 'extracting' | 'grounding' | 'storing' | 'done', required — Where a running decomposition has got to. Only the stages a watching human can perceive. Resolving the model's channel names to `MarketingCollateralType` and writing the rows are both sub-second, so they are not stages — a step that never renders is a step that misleads. `EXTRACTING` is the one that takes the minute.
    - `requirements` integer, required
    - `has_library` boolean, required
    - `error` string, nullable, required
  - `ready` integer, required
  - `in_flight` integer, required
  - `failed` integer, required
  - `never_run` integer, required
  - `skipped` object[]

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/kobaltlabs/apis/fastapi.md) · [All operations](https://skmtc.dev/kobaltlabs/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kobaltlabs/fastapi/revisions/3ff4c0bd276b/schema)