Active Inference Curriculum Creation Pipeline

Overview

The START project provides a pipeline for creating personalized Active Inference and Free Energy Principle curricula. Live provider calls are optional; offline fixtures and synthetic foundation material are explicitly labeled and never treated as live evidence.

Pipeline Stages

Stages - Inputs: data/config/entities.yaml, data/config/domains.yaml, data/config/languages.yaml - acquire → prepare → process → parse → render

Each run has a stable run ID, a filesystem checkpoint directory, and an atomic manifest.json. Required-stage failures make PipelineResult.ok false; optional-stage failures remain visible in structured stage results.

Links - Configuration Reference - Visualizations - Translations

1. Acquire 🔍

  • Domain Research: Analyze professional domains (biochemistry, AI, neuroscience, etc.)
  • Entity Research: Create personalized profiles for target learners
  • Configuration-Driven: Uses YAML configs for scalable, organized research

2. Prepare and Process ✍️

  • Comprehensive Content: Prompt-defined professional development programs with manifest-backed quality status
  • Personalized: Tailored to specific domains and individual learning profiles
  • Structured Modules: Multi-section educational frameworks with assessments

3. Parse and Render 📊

  • Data Visualizations: PNG charts showing curriculum metrics and analysis
  • Process Diagrams: Mermaid diagrams for curriculum structure and flow
  • Visualization manifest: Input/output hashes and the derived-evidence boundary for every canonical render bundle
  • Interactive Elements: Visual learning aids and conceptual frameworks

4. Multilingual Translation 🌍

  • Cultural Adaptation: Full localization beyond literal translation
  • Review Required: Translation structure and script checks are automated; fluency and technical accuracy require human review
  • Multiple Languages: Support for the configured target languages with script mapping

Script Entrypoints

Staged Entrypoints

# Numbered files remain importable staged entrypoints; use the canonical runner.
learning/curriculum_creation/1_Research_Domain.py    # Domain analysis
learning/curriculum_creation/1_Research_Entity.py    # Audience profiling  
learning/curriculum_creation/2_Write_Introduction.py # Curriculum generation
learning/curriculum_creation/3_Introduction_Visualizations.py # Charts & diagrams
learning/curriculum_creation/4_Translate_Introductions.py     # Multilingual output

Supporting Infrastructure

src/perplexity/           # Perplexity API integration
src/common/               # Shared utilities (paths, config, prompts)
src/config/               # Configuration management
src/visualization/        # Visualization generation

Data Architecture

Input Configuration

data/config/
├── entities.yaml         # Target learner profiles
├── domains.yaml          # Professional domains
└── languages.yaml        # Translation targets and scripts

Research Outputs

data/
├── audience_research/     # Personalized learner analysis
├── domain_research/       # Professional domain analysis
├── written_curriculums/   # Generated curriculum content
├── translated_curriculums/ # Multilingual versions
└── visualizations/        # Charts and diagrams

Template System

data/prompts/
├── research_domain_analysis.md     # 6-section domain framework
├── research_domain_curriculum.md   # Prompt-defined curriculum generation
├── research_entity.md              # 6-section personalization
├── curriculum_section.md           # Comprehensive module creation
└── translation.md                  # 7-section multilingual framework

Enhanced Features

Configuration-Driven Research

  • YAML-Based Control: All research targets defined in configuration files
  • Priority Filtering: Process high/medium/low priority items
  • Category Filtering: Focus on specific domain categories
  • Overwrite Control: Skip existing by default, force overwrite with flags
  • Release controls: The canonical runner supports --dry-run, --estimate-cost, --run-id, --resume, --offline, --budget-usd, and machine-readable --json summaries.
  • Evidence boundaries: Synthetic foundational material is labeled as synthetic; provider, model, prompt, source hashes, usage, and quality status accompany generated outputs.

Advanced Command-Line Interface

# Filter by priority and category
uv run start-curriculum --non-interactive --stages domain-research \
  --domain-priority high --domain-category life_sciences --json

# Process specific targets
uv run start-curriculum --non-interactive --stages entity-research \
  --entities karl_friston --overwrite --json

# Multilingual output with specific languages
uv run start-curriculum --non-interactive --stages translations \
  --languages Spanish French German --json

Comprehensive Content Generation

  • Domain Analysis: Prompt-targeted professional landscape analysis, checked for structure and provenance
  • Curriculum Content: Structured learning programs whose actual output is recorded and validated
  • Personalization: Prompt-targeted tailored learning strategies, checked before publication
  • Section Modules: Prompt-defined learning units; duration is an estimate requiring review

API Integration

Perplexity API (Research)

  • Live Research: Current online information and analysis when a live provider run is explicitly enabled
  • Professional Insights: Industry trends, challenges, opportunities
  • Comprehensive Analysis: Multi-perspective domain understanding

OpenRouter API (Content Generation)

  • Advanced LLMs: High-quality curriculum and translation generation
  • Structured Output: Consistent, professional educational content
  • Multilingual Capability: Configured translation workflows with structural, parity, and script checks; cultural and technical review remains required

Quality Assurance

Content Standards

  • Reviewable structure: Required sections, lengths, citations, and provenance are checked before publication
  • Evidence-labeled: Live research, source material, synthetic foundations, offline fixtures, and derived visuals are never silently conflated
  • Human validation: Technical accuracy, pedagogical suitability, language fluency, and learning outcomes remain review responsibilities
  • Explicit limits: Generated content is not independently fact-checked or evidence of learning outcomes by the pipeline alone

Technical Standards

  • Modular Architecture: Clean, maintainable, testable code
  • Error Handling: Robust failure recovery and logging
  • Performance Optimized: Efficient API usage and data processing
  • Standards Compliant: Following Python best practices and project conventions

Operational commands

# Plan without contacting providers
uv run start-curriculum --non-interactive --dry-run --run-id plan-001 --json

# Validate generated text and JSON contracts without modifying data
uv run start-validate-outputs --check

# Regenerate a deterministic, explicitly synthetic fixture
uv run start-regenerate-offline --output-dir /tmp/start-fixtures --run-id fixture-001 --json

# Inspect or conservatively prune filesystem-backed run history
uv run start-run-history --root data/written_curriculums/.runs --json
uv run start-run-history --root data/written_curriculums/.runs --keep 10 --prune --json

Cross-References

  • Environment setup and CI workflow: environment.md
  • Testing policy and markers: TESTING.md
  • Clone management for optional resources: clones.md