This directory contains a comprehensive suite of Python scripts for creating personalized Active Inference curricula. The scripts follow a modular, test-driven development approach and implement the full curriculum generation pipeline from research to translation.
The canonical public interface is the installed start-curriculum command. The
numbered files below remain staged entrypoints for imports and local workflows;
they delegate execution to the same acquire → prepare → process → parse →
render runner and return its exit status.
uv run start-curriculum --non-interactive --stages domain-research entity-research \
--domains biochemistry --entities karl_friston --json
uv run start-curriculum --non-interactive --stages curriculum visualizations translations \
--languages Spanish French --run-id example-001 --json
The curriculum creation process follows these stages:
Purpose: Analyzes domain characteristics to create domain-specific Active Inference curricula.
Key Features:
data/domain_research/Usage:
uv run start-curriculum --non-interactive --stages domain-research
Input: Domain targets from data/config/domains.yaml
Output: Research reports in data/domain_research/
Functions:
get_domain_files(domain_dir): Finds domain files to processmain(): Orchestrates the complete domain analysis workflowPurpose: Researches target audience characteristics for personalized curriculum creation.
Key Features:
data/audience_research/Usage:
uv run start-curriculum --non-interactive --stages entity-research
Input: Entity targets from data/config/entities.yaml
Output: Audience research reports in data/audience_research/
Functions:
get_entity_files(entity_dir): Finds entity files to processmain(): Orchestrates the complete audience analysis workflowPurpose: Converts research reports into comprehensive Active Inference curricula.
Key Features:
data/written_curriculums/Usage:
uv run start-curriculum --non-interactive --stages curriculum
Input: Research files from data/domain_research/ and data/audience_research/
Output: Complete curricula in data/written_curriculums/
Functions:
get_research_files(research_dir): Lists research files for staged processingmain(): Orchestrates the complete curriculum generation workflowPurpose: Generates PNG charts and Mermaid diagrams for curriculum visualization.
Key Features:
data/visualizations/Usage:
uv run start-curriculum --non-interactive --stages visualizations \
[--curriculum-dir INPUT_DIR] [--visualizations-dir OUTPUT_DIR]
Options:
--curriculum-dir: Custom input directory (default: data/written_curriculums)--visualizations-dir: Custom output directory (default: data/visualizations)Outputs:
charts/curriculum_metrics.png: Deterministic metrics dashboarddiagrams/curriculum_structure.mmd: Overall curriculum structure diagramdiagrams/{stable-item-id}_flow.mmd: Stable-ID learning flow diagramsmetrics/curriculum_metrics.json: Detailed metrics datavisualization_manifest.json: Input/output hashes and evidence boundaryFunctions:
extract_curriculum_metadata(): Analyzes curriculum content for metricscreate_curriculum_metrics_chart(): Chart helper; canonical bundle generation is in src/visualization/runner.pycreate_curriculum_flow_mermaid(): Creates learning progression diagramscreate_curriculum_structure_mermaid(): Creates overview structure diagramsPurpose: Translates curricula into multiple configured languages.
Key Features:
data/translated_curriculums/Usage:
uv run start-curriculum --non-interactive --stages translations \
[--curriculum-dir INPUT_DIR] [--translation-dir OUTPUT_DIR] [--languages LANG1 LANG2 ...]
Options:
--curriculum-dir: Custom input directory (default: data/written_curriculums)--translation-dir: Custom output directory (default: data/translated_curriculums)--languages: Specific languages to translate (default: all configured languages)Functions:
validate_languages(): Validates requested languages against configurationmain(): Orchestrates the complete translation workflowAll scripts follow a consistent data organization pattern:
data/
├── audience_research/ # Entity/audience research reports
│ └── {entity}_research_{timestamp}.json
├── domain_research/ # Domain analysis reports
│ ├── {domain}_research_{timestamp}.json
│ └── {domain}_research_{timestamp}.md
├── written_curriculums/ # Generated curricula
│ └── {entity}/
│ ├── {section}_{timestamp}.md
│ └── complete_curriculum_{timestamp}.md
├── translated_curriculums/ # Translated curricula
│ └── {language}/
│ └── {entity}_curriculum_{language}_{timestamp}.md
└── visualizations/ # Canonical derived bundle
├── charts/curriculum_metrics.png
├── diagrams/curriculum_structure.mmd
└── visualization_manifest.json
Configure target languages in data/config/languages.yaml:
target_languages:
- Chinese
- Spanish
- Arabic
- Hindi
- French
# ... more languages
script_mappings:
Arabic: "Modern Standard Arabic"
Chinese: "Simplified Chinese"
# ... more mappings
Customize prompts in data/prompts/:
research_domain_analysis.md: Domain analysis promptsresearch_domain_curriculum.md: Domain curriculum generationresearch_entity.md: Entity research promptscurriculum_section.md: Section generation promptstranslation.md: Translation promptsDependencies are declared in the root pyproject.toml and installed with
uv sync --all-extras --dev. Notable groups:
openai: API client for Perplexity and OpenRouterpyyaml: Configuration loadingpython-dotenv: .env loadingrequests: HTTP utilitiesGitPython: Repository cloning supportnumpy, pandas, scipy: Numerical data handlingmatplotlib, seaborn: Chart generationscikit-learn, nltk, spacy, wordcloud, networkx, adjustText: Text
and structure analysispytest: Testing frameworkblack: Code formattingruff: Lintingmypy: Type checkingmkdocs / mkdocs-material: Documentation site builduv sync --all-extras --dev
export PERPLEXITY_API_KEY="your-perplexity-key"
export OPENROUTER_API_KEY="your-openrouter-key"
export PERPLEXITY_MODEL="llama-3.1-sonar-small-128k-online"
export OPENROUTER_MODEL="anthropic/claude-3.5-sonnet"
Run all scripts in sequence:
# 1. Research domains and entities
uv run start-curriculum --non-interactive --stages domain-research
uv run start-curriculum --non-interactive --stages entity-research
# 2. Generate curricula
uv run start-curriculum --non-interactive --stages curriculum
# 3. Create visualizations
uv run start-curriculum --non-interactive --stages visualizations
# 4. Translate to target languages
uv run start-curriculum --non-interactive --stages translations
Generate visualizations for specific input:
uv run start-curriculum --non-interactive --stages visualizations \
--curriculum-dir /path/to/curricula --visualizations-dir /path/to/viz
Translate only to specific languages:
uv run start-curriculum --non-interactive --stages translations --languages Spanish French German
All scripts implement comprehensive error handling and quality assurance:
The scripts include comprehensive tests:
Run tests:
uv run pytest tests/test_curriculum_scripts_integration.py
All scripts use structured logging:
logger = common_setup_logging()
logger.info("Starting process")
logger.error("Process failed", extra={"error": str(e)})
Logs include:
API Key Errors:
File Not Found Errors:
Memory Issues:
Network Errors:
Enable verbose logging by setting log level:
import logging
logging.getLogger().setLevel(logging.DEBUG)
Configuration Errors:
API Connection Issues:
Content Quality Issues:
Processing Failures:
black for code formattingruff for lintingThis project follows the repository’s LICENSE terms.