Domain Packs

A domain pack is the per-domain data bundle that everything downstream depends on: the base dataset that seeds the training mix, the base system prompt that becomes the avatar's runtime prompt, and the held-out questions that grade the finished adapter. This page covers the shape of an active pack and the separate, gated pipeline used to build new ones.

Active packs

An active pack is two files, both named after the domain_id.

Base dataset — `state/config/domain_datasets/{domain_id}_base.json`

{
  "domain_id": "math",
  "version": "1.0.0",
  "description": "Базовий датасет для аватара-вчителя математики…",
  "spoken_formula_note": "Всі математичні вирази записані у вигляді природного мовлення…",
  "standalone": [ { "instruction": "…", "input": "", "output": "…" } ],
  "rag_aware": [ { "instruction": "…", "context": "…", "output": "…" } ],
  "sample_count": 41,
  "base_system_prompt": "Use retrieved context as internal grounding only. …"
}

Field	Role
`standalone`	Examples answered from the model's own knowledge.
`rag_aware`	Examples that must ground an answer in a supplied `context` block.
`sample_count`	`len(standalone) + len(rag_aware)`. Validated against the actual counts by `domain.integrity`.
`base_system_prompt`	The domain's behavioural contract. Fed to Kimi as the summary anchor during generation, rewritten into the avatar's runtime prompt, and used as the system prompt for both sides of the LoRA evaluation.
`description`, `version`, and any extra keys	Documentation only; not read by the pipeline.

Content is per domain and may be non-English — the shipped math pack is Ukrainian and normalizes every formula into spoken form so it survives text-to-speech.

base_system_prompt is required in practice: LoRA evaluation refuses to run without it, and prompt rewriting falls back to it whenever the rewrite call fails.

Evaluation questions — `state/config/lora_eval_questions/{domain_id}.json`

{
  "domain_id": "math",
  "domain_name": "Math",
  "generated_by": "…",
  "question_count": 20,
  "questions": [
    { "id": "q1", "question_type": "factual", "question": "…" }
  ]
}

The loader is strict: exactly 20 questions, each with non-empty text and a question_type from factual, procedural, reasoning, edge_case. A missing id is defaulted to q{index}. Anything else raises and fails the run's quality evaluation. See Training Pipeline.

note

Both lookups are case- and separator-insensitive: the resolver normalizes names by stripping everything outside [a-z0-9], so Math, math, and MATH all resolve to math_base.json and math.json.

Candidate packs

New domains are built in state/config/domain_candidates/{domain_id}/ and are never activated automatically. Nothing in the candidate tree is visible to onboarding or production; activation is a deliberate review-and-release step that adds the catalog entry, base dataset, evaluation file, and checksum manifest entry together.

Fourteen candidates ship in the tree: accounting_bookkeeping, agriculture_gardening, automotive_maintenance, career_employability, copywriting_content_creation, first_aid_emergency_preparedness, history_civics, literature_creative_writing, music_theory_production, personal_finance, project_management, sales_customer_development, startup_business_planning, study_skills.

The complete candidate set contains 840 canonical RAG chunks and 11,200 generated examples. Each domain covers eight topics; every topic has at least three source chunks, five behaviour seeds, 80 standalone examples, and 20 RAG-aware examples.

Pack contract

File	Contents
`domain.json`	Scope, audiences, topic map, risk boundaries, base prompt.
`source_manifest.json`	Source URLs, publisher details, licenses, checksums, extraction metadata, corpus version.
`rag_corpus.jsonl`	Canonical source chunks assigned to domain topics.
`training_seeds.json`	Forty behaviour scenarios — five per topic.
`evaluation.json`	Twenty held-out questions, split equally across the four question types.
`generated_dataset.json`	640 standalone and 160 RAG-aware examples, marked `generated_review_required`.
`_catalog.json`	Shared candidate index at the root of `domain_candidates/`.

Two rules protect the evaluation signal:

evaluation questions are never used as generation seeds;
RAG-aware examples reference a canonical source_chunk_id, and the generator inserts the exact source text after generation — the model can select a chunk but cannot rewrite or fabricate retrieval context.

Source policy

Candidate corpora use attributable government publications, explicitly licensed resources, or works identified as public domain. Every downloaded source is checksummed. Sources with unclear reuse terms, incompatible restrictions (NC, ND), embedded all-rights-reserved material, or third-party content that cannot be separated are excluded.

The source builder downloads and extracts material reproducibly, strips page and site boilerplate, creates bounded chunks, and assigns unique chunks to topics using the catalog keywords. It fails when a topic cannot reach the minimum source coverage.

Generation flow

Build source-grounded domain files from the reviewed catalog.
Generate exactly five behaviour seeds for every topic.
Generate a balanced held-out evaluation set.
Expand every seed into sixteen standalone and four RAG-aware examples.
Reject malformed, short, duplicated, leaking, or ungrounded examples.
Selectively regenerate only failed or globally duplicated batches.
Validate the complete pack before review.

Generation is resumable through ignored checkpoint files. A failed request does not produce a partial dataset and does not invalidate completed batches.

Validation gates

validate_domain_candidate checks:

the complete file and schema contract;
source identifiers, licenses, URLs, and SHA-256 checksums;
unique canonical chunks and minimum topic coverage;
exact seed and evaluation balance;
no evaluation leakage into training data;
the exact 640/160 generated-data balance and per-topic coverage;
globally unique instructions;
valid seed and source-chunk provenance;
exact canonical context in every RAG-aware example.

warning

Schema validation does not replace human content review. Before activation, reviewers must inspect source suitability, generated answer quality, safety behaviour, regional assumptions, and held-out evaluation performance. High-risk domains require subject-matter review and explicit approval.

Commands

Build or refresh source-grounded files:

python -m training.scripts.build_candidate_domain_packs --domain automotive_maintenance --force

Generate seeds and the held-out evaluation set:

python -m training.scripts.generate_candidate_scaffold state/config/domain_candidates/automotive_maintenance

Generate the resumable training dataset:

python -m training.scripts.generate_candidate_dataset state/config/domain_candidates/automotive_maintenance

Validate a candidate pack:

python -m training.scripts.validate_domain_candidate state/config/domain_candidates/automotive_maintenance

The generation commands accept either the authenticated core LLM or an explicitly configured OpenRouter model. Credentials are read from the environment and are never stored in candidate files.

# OpenRouter
export OPENROUTER_API_KEY=...
export DOMAIN_GENERATION_MODEL=your-reviewed-model

# or the team's core LLM
export DOMAIN_GENERATION_LLM_URL=https://example.internal/api/generate
export DOMAIN_GENERATION_LLM_TOKEN=...

Worked example: `study_skills`

The study_skills candidate documents what a well-formed pack looks like.

Scope. The avatar helps learners plan and evaluate study, practise retrieval, space review, alternate examples with independent work, connect representations, and build explanations through deeper questions. It does not replace a teacher, diagnose learning disabilities, provide mental-health treatment, complete graded work, or claim that one study method works equally well for every person and subject.

Topic map.

Topic	Expected capability
Study planning	Turn a learning goal into realistic sessions and review points.
Spaced review	Revisit important material after delays instead of relying on one long session.
Retrieval practice	Use low-stakes recall with feedback to strengthen memory and expose gaps.
Worked examples	Alternate examples and independent problems, reducing support as skill improves.
Representations	Connect verbal, visual, concrete, and abstract forms without irrelevant decoration.
Self-assessment	Judge learning after a delay and without answers in view.
Deep questions	Use why, how, comparison, cause, and what-if questions to build explanations.
Adaptation	Adjust the plan to the learner's goal, available time, current evidence, and subject.

Sources. The corpus uses Organizing Instruction and Study to Improve Student Learning, an Institute of Education Sciences practice guide that states it is in the public domain; the manifest records its URL, checksum, publisher, date, selected pages, and extraction policy. OpenStax College Success is deliberately excluded because its terms prohibit using the content to train or ingest into large language models without permission.

Review gates. The domain moves from candidate to active only after all of: a reviewer checks every seed and evaluation item; a valid team model credential expands the reviewed seeds; generated examples pass schema, duplicate, leakage, grounding, and safety checks; the pack hits the agreed standalone/RAG-aware balance; retrieval evaluation confirms the corpus answers the held-out grounded questions; and the catalog entry, base dataset, evaluation file, and checksum manifest are added together.

Active packs​

Base dataset — state/config/domain_datasets/{domain_id}_base.json​

Evaluation questions — state/config/lora_eval_questions/{domain_id}.json​

Candidate packs​

Pack contract​

Source policy​

Generation flow​

Validation gates​

Commands​

Worked example: study_skills​