# Migration guide — 0.14.0 (ubiquitous-language alignment)

`0.14.0` renames API fields and domain classes to align with the IFRC ubiquitous language (see [`docs/ubiquitous_language.md`](../ubiquitous_language.md)). All renames are breaking; there is no Pydantic-alias compatibility shim.

## Who needs to act

Anyone running a client (CRM scripts, integration tests, dashboards) that sends requests to or parses responses from these endpoints:

- `POST /v1/analyze`
- `POST /v1/summarize`
- `POST /v1/summarize-aggregate`
- `POST /v1/assign_codes`

Internal callers in this repo are already updated.

## Field renames

### Request bodies

| Endpoint | Before | After |
|---|---|---|
| `/v1/analyze` | `documents` (array) | `feedback_records` |
| `/v1/analyze` | `documents[].text` | `feedback_records[].content` |
| `/v1/summarize` | `feedback_items` | `feedback_records` |
| `/v1/summarize-aggregate` | `feedback_items` | `feedback_records` |
| `/v1/assign_codes` | `feedback_items` | `feedback_records` |

### Response bodies

| Endpoint | Before | After |
|---|---|---|
| `/v1/analyze` | `document_count` | `feedback_record_count` |
| `/v1/summarize` | `summaries[].feedback_item_id` | `summaries[].feedback_record_id` |
| `/v1/assign_codes` | `coded_items[].feedback_item_id` | `coded_records[].feedback_record_id` |

### Domain / error classes

These are visible to anyone consuming the Python package as a library (not over HTTP):

| Before | After |
|---|---|
| `FeedbackItemModel` | {py:class}`~qfa.domain.models.FeedbackRecordModel` |
| `FeedbackItemSummaryModel` | {py:class}`~qfa.domain.models.FeedbackRecordSummaryModel` |
| `CodedFeedbackItemModel` | {py:class}`~qfa.domain.models.CodedFeedbackRecordModel` |
| `DocumentsTooLargeError` | {py:exc}`~qfa.domain.errors.FeedbackTooLargeError` |
| `ApiFeedbackItemInput` | `ApiFeedbackRecordInput` |

## What did *not* change

- The XML tags used in the LLM prompt assembly (`<documents>` / `<document>`) — these remain unchanged in this release and are internal to prompt assembly, not visible to API consumers.
- HTTP status codes and the error envelope shape.
- Authentication (`Authorization: Bearer <key>`).
- Endpoint paths and methods.

## Behaviour if you do nothing

Old field names in the request body produce a Pydantic validation error (HTTP 422) naming only the **new** expected field. The response from an old client trying to read e.g. `document_count` will simply have that key missing.

## Migration checklist

1. Replace request-body field names per the tables above.
2. Replace response-parsing field names.
3. If you import the Python package, replace the renamed class names.
4. Redeploy the client.

There is no staged rollout; one deploy of the backend flips everyone over.