Start

Active Inference Curriculum Creation Scripts

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

Overview

The curriculum creation process follows these stages:

  1. Research (Scripts 1_*): Analyze domains and target audiences
  2. Content Generation (Script 2_*): Create tailored curriculum content
  3. Visualization (Script 3_*): Generate charts and diagrams
  4. Translation (Script 4_*): Translate to multiple languages

Scripts

1_Research_Domain.py

Purpose: Analyzes domain characteristics to create domain-specific Active Inference curricula.

Key Features:

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:

1_Research_Entity.py

Purpose: Researches target audience characteristics for personalized curriculum creation.

Key Features:

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:

2_Write_Introduction.py

Purpose: Converts research reports into comprehensive Active Inference curricula.

Key Features:

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:

3_Introduction_Visualizations.py

Purpose: Generates PNG charts and Mermaid diagrams for curriculum visualization.

Key Features:

Usage:

uv run start-curriculum --non-interactive --stages visualizations \
  [--curriculum-dir INPUT_DIR] [--visualizations-dir OUTPUT_DIR]

Options:

Outputs:

Functions:

4_Translate_Introductions.py

Purpose: Translates curricula into multiple configured languages.

Key Features:

Usage:

uv run start-curriculum --non-interactive --stages translations \
  [--curriculum-dir INPUT_DIR] [--translation-dir OUTPUT_DIR] [--languages LANG1 LANG2 ...]

Options:

Functions:

Data Structure

All 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

Configuration

Language Configuration

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

Prompt Templates

Customize prompts in data/prompts/:

Dependencies

Dependencies are declared in the root pyproject.toml and installed with uv sync --all-extras --dev. Notable groups:

Core Dependencies

Data & Visualization Dependencies

Development Dependencies

Environment Setup

  1. Install dependencies:
    uv sync --all-extras --dev
    
  2. Set up environment variables:
    export PERPLEXITY_API_KEY="your-perplexity-key"
    export OPENROUTER_API_KEY="your-openrouter-key"
    
  3. Configure models (optional):
    export PERPLEXITY_MODEL="llama-3.1-sonar-small-128k-online"
    export OPENROUTER_MODEL="anthropic/claude-3.5-sonnet"
    

Usage Examples

Complete Pipeline

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

Custom Visualization

Generate visualizations for specific input:

uv run start-curriculum --non-interactive --stages visualizations \
  --curriculum-dir /path/to/curricula --visualizations-dir /path/to/viz

Selective Translation

Translate only to specific languages:

uv run start-curriculum --non-interactive --stages translations --languages Spanish French German

Error Handling & Quality Assurance

All scripts implement comprehensive error handling and quality assurance:

Robust Error Handling

Content Validation

Enhanced User Experience

Testing

The scripts include comprehensive tests:

Run tests:

uv run pytest tests/test_curriculum_scripts_integration.py

Logging

All scripts use structured logging:

logger = common_setup_logging()
logger.info("Starting process")
logger.error("Process failed", extra={"error": str(e)})

Logs include:

Best Practices

Code Quality

Data Management

Performance

Troubleshooting

Common Issues

API Key Errors:

File Not Found Errors:

Memory Issues:

Network Errors:

Debug Mode

Enable verbose logging by setting log level:

import logging
logging.getLogger().setLevel(logging.DEBUG)

Enhanced Troubleshooting

Configuration Errors:

API Connection Issues:

Content Quality Issues:

Processing Failures:

Contributing

Code Style

Testing

Documentation

License

This project follows the repository’s LICENSE terms.