Domain Library

The BOTCOIN challenge system supports multiple knowledge domains through an interchangeable domain library architecture. Each domain is a self-contained bundle that defines everything needed to generate challenges in that domain.

How Domains Work

• The coordinator loads approved domain bundles at startup
• Each challenge is generated from a specific domain, indicated by challengeDomain in the response
• The challenge structure (document, questions, constraints, verification) remains consistent across domains
• What changes: entity types, attribute names, prose language, question semantics, and domain-specific context
• All domain libraries are deterministic: the same seed and library version always produce byte-identical challenges, enabling replay verification via golden hash sets

Domain Bundle Structure

Each domain bundle contains a domain_library.json that defines:

Supported Attribute Types

Domain entities can have attributes of various types:

• name — Entity names drawn from pools
• person_name — Person names (e.g., for leadership roles)
• pick — Categorical selection from a defined set
• int_range / float_range — Numeric values within bounds
• quarterly_int / quarterly_float — Periodic numeric data (e.g., quarterly revenue, seasonal measurements) — 4-element arrays

Current Domains

Adding New Domains

New domains are created through an automated offline pipeline that converts source documents into validated domain bundles. The process is orchestrated by an LLM agent (Claude Opus 4.6) with full context of the system architecture, guided by strict format specifications and self-verification checklists.

Pipeline stages:

1. Ingest — Source documents (PDF, TXT, DOCX, or other formats) are extracted and chunked into processable segments
2. Schema extraction — An LLM agent analyzes the source material and designs the entity schema: what the entities are, what attributes they have, how names are constructed, and which attributes serve as constraint anchors
3. Human review gate — The schema is reviewed and approved before proceeding. This is the only manual step.
4. Library generation — The LLM agent builds the complete domain library: 25-30 question definitions with declarative answer logic, 5+ prose document formats, trap language, relational patterns, and a neutral domain-context solve prompt
5. Deterministic validation — 40+ automated checks verify the bundle without any LLM involvement: - Structural correctness and completeness - Entity name uniqueness across hundreds of generated worlds - Question coherence (all answers resolve to entity names, no ambiguity) - Constraint anchor diversity (sufficient distinct values for primes and equations) - Solvability proof (every generated challenge is mathematically satisfiable — no constraint contradictions, and every required value appears in the served document) - Source contamination check (n-gram overlap analysis to flag exploitable training data overlap) - Golden hash generation for determinism replay verification
6. Calibration — Challenges are solved by an isolated LLM (Sonnet 4.6 with extended thinking, no system context) to measure difficulty. Target: ~50% of challenges fully passed. Per-constraint diagnostics identify which dimensions need adjustment.
7. Targeted adjustment — If the pass rate is outside the target band, the LLM agent makes surgical changes to the specific failing dimension (e.g., simplify chain questions if question accuracy is low, adjust prose density if document reading is the bottleneck) rather than broad untargeted changes

Validation requirements before activation:

• Minimum 10 calibration solves with production-parity configuration (128-bit random seeds, 20 entities, 10 questions, 8 constraints)
• Pass rate within the 40–60% band across the calibration sample
• Zero challenges where a required constraint value is absent from the served document
• Zero self-contradictory constraint sets (forbidden letter conflicts, infeasible word counts)
• Clean contamination report (no 15+ gram overlap with source material)

Deployment:

Once validated, activation requires only syncing the domain_library.json to the coordinator, adding it to the served-domains manifest, and restarting. No per-domain coordinator code changes are needed.

The domain bundle specification and creation pipeline are open for contribution. New domains can be proposed by providing source documents — the pipeline handles the rest.

Complexity Tuning

After a domain is deployed, challenge difficulty can be adjusted at two levels:

Coordinator-side (immediate, no library change): - Constraint difficulty tier (easy/medium/hard) — affects word count ranges and acrostic length - Trap count (0, 1, or 2 simultaneous traps) - Multipass retry policy (1–3 solve attempts per challenge)

Library-side (requires bundle update): - Entity count (fewer entities = shorter, easier documents) - Question complexity mix (ratio of single-hop vs. multi-hop chain questions) - Document density (prose template verbosity, red herring frequency, relational embedding depth)