app.services.seed_synthetic_gen

Pure generator for the synthetic benchmark ADR corpus.

No I/O, no storage port, no FastAPI: everything here is a plain function over random, so a fixed seed reproduces the exact same documents (generate_published(), generate_candidates(), generate_decisions()). app.services.seed_synthetic ingests the result through the normal poll/push path. Title and body text come from app.services.seed_synthetic_text.

Each generator draws from its own random.Random, seeded from f"{seed}:<phase>", so the phases are independent of call order and of each other’s internal consumption of randomness.

Realism, kept deliberately small:

  • titles are built from verb/subject/qualifier word lists;

  • bodies are “Context” / “Decision” / “Consequences” sections built from sentence templates, stretched or trimmed to 300-3000 characters;

  • a share of records link updates/obsoletes to an earlier record (by UUID, catalog-wide, matching how app.services.record_relationships resolves links); a smaller share are errata (erratum-for), small RFC-style reports against an earlier decision – not a full ADR body (see app.services.seed_synthetic_errata, which owns their generation);

  • a share use the legacy deprecates alias or a legacy signed-off-by list;

  • a share carry one deliberate validation issue (missing uuid, a malformed decision-date, or an unknown field), so the seeded catalog exercises the same error/warning paths as real content.

Public API: GeneratedPublished, GeneratedCandidate, GeneratedDecision, generate_published(), generate_candidates(), generate_decisions().

class app.services.seed_synthetic_gen.GeneratedCandidate(*, project, path, ref, content, adr_uuid)

Bases: object

One synthetic competing candidate of a published identity.

Parameters:

  • project (str) – Owning project path (matches the published row).

  • path (str) – File path inside the project (matches the published row; candidates are keyed by (source, project, key, ref)).

  • ref (str) – Branch/ref, distinct from the published ref.

  • content (bytes) – Raw Markdown bytes, a small variant of the published content.

  • adr_uuid (UUID) – The identity’s UUID.

project: str
path: str
ref: str
content: bytes
adr_uuid: UUID
class app.services.seed_synthetic_gen.GeneratedDecision(*, project, adr_uuid, digest, action)

Bases: object

One synthetic accept/reject decision.

Parameters:

  • project (str) – Owning project path.

  • adr_uuid (UUID) – The decided identity’s UUID.

  • digest (str) – Digest of the decided (published) content.

  • action (DecisionAction) – Accepted or rejected.

project: str
adr_uuid: UUID
digest: str
action: DecisionAction
class app.services.seed_synthetic_gen.GeneratedPublished(*, project, path, content, adr_uuid)

Bases: object

One synthetic published ADR document.

Parameters:

  • project (str) – Owning project path.

  • path (str) – File path inside the project.

  • content (bytes) – Raw Markdown bytes (frontmatter and body).

  • adr_uuid (UUID | None) – The record’s UUID, or None for a deliberately broken record with no stable identity (never a link target).

project: str
path: str
content: bytes
adr_uuid: UUID | None
app.services.seed_synthetic_gen.generate_candidates(published, *, ratio, seed)

Generate a competing candidate for a share of published identities.

Parameters:
Return type:

list[GeneratedCandidate]

Returns:

The generated candidates.

app.services.seed_synthetic_gen.generate_decisions(published, *, ratio, seed)

Generate an accept/reject decision for a share of published identities.

The digest matches the published content’s digest exactly, so the decision binds to the row the seeding ingest writes.

Parameters:
Return type:

list[GeneratedDecision]

Returns:

The generated decisions.

app.services.seed_synthetic_gen.generate_published(*, records, projects, seed, path_prefix='doc/decisions', today=None)

Generate a deterministic synthetic corpus of published documents.

Records are spread round-robin over projects projects. A record may link to any earlier record in the sequence (catalog-wide, not only within its own project), matching how relationships resolve at read time.

Parameters:

  • records (int) – Number of documents to generate.

  • projects (int) – Number of projects to spread them across.

  • seed (int) – Random seed; same inputs always yield the same documents.

  • path_prefix (str) – ADR directory inside each project.

  • today (date | None) – Anchor date for decision dates (default: today).

Return type:

list[GeneratedPublished]

Returns:

The generated documents, in generation order.