Contract Design — Questions

Fill in each [Answer]: tag. Options A-E plus X (Other). The file is the authoritative record of your contract decisions.

Q1: Contract representation

How should the inter-unit contracts (Generator ↔ AiDraft, Generator ↔ Funnies, and the DraftBundle handoff) be specified?

A) Shared-schema contracts in Python (data classes / pydantic-style models) that live with the producer unit and are referenced by consumers — ideal for a local library-backed tool (recommended) B) A standalone JSON-schema file per contract, imported by all units C) Formal OpenAPI/AsyncAPI specs — heavier than a local tool needs X) Other (please specify)

Q2: Integration mechanism

How do the units call each other at the library boundary?

A) Direct module/function calls (the newspaper CLI imports the ai-draft and funnies libraries and calls their entry functions in-process) (recommended) B) Each unit is a separate process, communicating via JSON over a pipe/CLI C) A message/event bus between units X) Other (please specify)

Q3: Contract ownership

Who owns each contract spec?

A) Each producer unit owns the contract for data it emits — AiDraft owns the DraftBundle shape, Funnies owns the puzzle/cartoon output shape, Generator owns content/config input shapes (recommended) B) A shared "contracts" home owned jointly C) The CLI (Generator) owns all contracts centrally X) Other (please specify)

Q4: Error / timeout / fallback behaviour

How should the boundaries handle failure (e.g. Ollama unavailable, Funnies finds no cartoon, missing content)?

A) Fail gracefully: each unit returns a clear error/fallback (Ollama down → skip drafting with a message; no cartoon → tasteful placeholder; missing content → guided empty state), never a crash or blank page (recommended) B) Hard-fail loudly with a clear message and non-zero exit C) Best-effort only — ignore failures silently X) Other (please specify)

Q5: Versioning policy

How should internal contract changes be handled (this is a one-shot local tool)?

A) No formal versioning — additive, backward-compatible changes only within/after a build; breaking changes are re-generated in one go (recommended) B) Semantic versioning of the library API, since content/consumers could persist between runs C) Locked/immutable — contracts cannot change after review X) Other (please specify)

Consolidated Summary Confirmation

Summary of your five contract answers before the contract summary is generated:

Contract representation: shared-schema contracts in Python (data classes / pydantic-style), referenced by consumers (Q1=A)

Integration mechanism: in-process module/function calls — the newspaper CLI imports the ai-draft and funnies libraries (Q2=A)

Contract ownership: each producer owns its contract — AiDraft owns the DraftBundle shape, Funnies the puzzle/cartoon output, Generator the content/config input shapes (Q3=A)

Error/fallback: fail gracefully — Ollama down → skip draft with a message, no cartoon → tasteful placeholder, missing content → guided empty state; never crash or blank (Q4=A)

Versioning: no formal versioning — additive backward-compatible changes; breaking changes regenerated in one go (Q5=A)

Human pre-approved this summary (answers recorded via the file, self-guided mode).

Does this all look correct before I generate the contract summary?

Looks correct
Request changes

Answer: Looks correct

3.5 KiB Raw Blame History