app.services.seed_synthetic

Synthetic dataset seeding for benchmarking (adriano seed-synthetic).

A twelve-factor “admin process”: a one-off command that shares the app’s code and config, run against a throwaway dev/bench database. It generates a deterministic synthetic ADR corpus (app.services.seed_synthetic_gen) and ingests it through the same shared path poll and push use (app.services.ingest.prepare_document(), app.services.ingest.ingest_document()), under lock_registration(), in batches – never raw SQL. Decision events are appended directly through the store port (append_decision()) for a share of identities, using a synthetic reviewer identity and the configured (or a documented fallback) policy id/version.

The target registration must already be configured in catalog.yaml (see bench/catalog.bench.yaml: a filesystem registration whose root never needs to exist, because seeding never calls the adapter – it writes rows directly through the store port, the same way the push intake path never calls an adapter either). seed_catalog() syncs registrations itself, exactly like adriano poll.

Safety: refuses to run against a database whose name does not look like a dev/test/bench database unless the caller passes force=True (see looks_like_dev_database()); the CLI wires this to --force.

Public API: SeedConfig, SeedSummary, DEFAULT_BATCH_SIZE, SYNTHETIC_REVIEWER_ISSUER, SYNTHETIC_REVIEWER_SUBJECT, looks_like_dev_database(), resolve_source(), seed_catalog().

app.services.seed_synthetic.DEFAULT_BATCH_SIZE = 500

Documents (or decisions) ingested per unit of work.

app.services.seed_synthetic.SYNTHETIC_REVIEWER_ISSUER = 'adriano-synthetic'

Identity asserted for seeded decision events. Never a real token’s issuer/subject, so it can never collide with an actual reviewer.

class app.services.seed_synthetic.SeedConfig(*, records, projects, source_id, seed=42, candidates_ratio=0.1, decisions_ratio=0.3, batch_size=500)

Bases: object

Parameters of one seeding run.

Parameters:

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

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

  • source_id (str) – Target registration id (must be configured and enabled in the loaded catalog.yaml).

  • seed (int) – Random seed; a run is fully determined by (records, projects, source_id, seed, candidates_ratio, decisions_ratio).

  • candidates_ratio (float) – Share of identities that also get a competing candidate row.

  • decisions_ratio (float) – Share of identities that get an accept/reject decision event.

  • batch_size (int) – Documents/decisions per database transaction.

records: int
projects: int
source_id: str
seed: int
candidates_ratio: float
decisions_ratio: float
batch_size: int
class app.services.seed_synthetic.SeedSummary(*, published, candidates, decisions)

Bases: object

Outcome of one seeding run.

Parameters:

  • published (int) – Published rows ingested.

  • candidates (int) – Candidate rows ingested.

  • decisions (int) – Decision events appended.

published: int
candidates: int
decisions: int
app.services.seed_synthetic.looks_like_dev_database(database_url)

Heuristically tell whether a database looks safe to seed.

Parameters:

database_url (str) – The plain DSN. Only the path (database name) is inspected; the password is never read.

Return type:

bool

Returns:

True if the database name is the ephemeral dev database (adriano) or contains a dev/test/bench/synthetic hint, case-insensitively.

app.services.seed_synthetic.resolve_source(config, source_id)

Find the enabled registration seeding will write to.

Parameters:

  • config (CatalogConfig) – Loaded catalog configuration.

  • source_id (str) – Requested registration id.

Return type:

SourceRegistration

Returns:

The registration.

Raises:

ValueError – If it is not configured or disabled.

app.services.seed_synthetic.seed_catalog(provider, config, seed_config, *, progress=None)

Generate and ingest a deterministic synthetic ADR corpus.

Parameters:

  • provider (CatalogStoreProvider) – Storage provider for the target database.

  • config (CatalogConfig) – Loaded catalog configuration; the source_id of seed_config must be one of its enabled registrations.

  • seed_config (SeedConfig) – Generation and batching parameters.

  • progress (Callable[[str], None] | None) – Called with a short status line after each batch and generation step; defaults to a no-op.

Return type:

SeedSummary

Returns:

Counts of what was written.

Raises:

ValueError – If the source is not configured or disabled.