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). 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

FeedbackRecordModel

FeedbackItemSummaryModel

FeedbackRecordSummaryModel

CodedFeedbackItemModel

CodedFeedbackRecordModel

DocumentsTooLargeError

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.