START supports Python 3.11 and 3.12 (requires-python = ">=3.11"). Use the locked uv environment
for local commands, CI, and documentation builds so dependency resolution does
not vary between surfaces. The repo pins the interpreter with
.python-version (3.12) because key dependencies (e.g.
spacy) publish no wheel for newer CPythons; without the pin a cold uv run
on a 3.14-default machine fails at install time.
uv sync --all-extras --dev
uv run start-curriculum --help
uv run start-gate docs
Steps
uv sync --all-extras --dev.envLinks
curl -LsSf https://astral.sh/uv/install.sh | sh
# or on macOS: brew install uv
# Install all dependencies including development tools
uv sync --all-extras --dev
# spaCy model for natural language processing
uv run python -m spacy download en_core_web_sm
# Additional language models for multilingual support (optional)
uv run python -m spacy download fr_core_news_sm # French
uv run python -m spacy download es_core_news_sm # Spanish
# Copy the example environment file
cp .env.example .env
# Edit with your API keys and configuration
$EDITOR .env
# Required API Keys
PERPLEXITY_API_KEY=your_perplexity_api_key_here
OPENROUTER_API_KEY=your_openrouter_api_key_here
# Optional API Keys
OPENAI_API_KEY=your_openai_api_key_here
# Default Model Configuration (built-in defaults if unset)
PERPLEXITY_MODEL=llama-3.1-sonar-small-128k-online
OPENROUTER_MODEL=anthropic/claude-3.5-sonnet
The system uses YAML configuration files in data/config/:
entities.yaml - Target learner profiles and research subjectsdomains.yaml - Professional domains for curriculum developmentlanguages.yaml - Translation targets and language mappingsuv run start-gate <arm> is the single gate; each arm is the command CI runs.
uv run start-gate fast # tests not marked slow/network/integration
uv run start-gate full # full suite + branch-aware coverage floor
uv run start-gate lint # ruff, black, shell syntax
uv run start-gate types # mypy over src, scripts, learning
uv run start-gate audit # dependency vulnerability audit
uv run start-gate --list # every arm with its exact command
# Auto-formatting is a local convenience command, not a gate arm
uv run black .
# Use the canonical installed orchestrator in the locked environment
uv run start-curriculum --help
uv run start-validate-outputs --check
# Test Perplexity API connection
uv run python -c "
from src.perplexity.clients import build_perplexity_client
client = build_perplexity_client()
print('Perplexity API connection successful')
"
# Test OpenRouter API connection
uv run python -c "
from src.perplexity.clients import build_openrouter_client
client = build_openrouter_client()
print('OpenRouter API connection successful')
"
src/
├── common/ # Shared utilities and infrastructure
│ ├── config.py # Configuration management
│ ├── io.py # File I/O operations
│ ├── logging_utils.py # Structured logging
│ ├── paths.py # Path management
│ └── prompts.py # Prompt template system
├── perplexity/ # Perplexity API integration
│ ├── clients.py # API client management
│ ├── domain.py # Domain research
│ ├── entity.py # Entity/audience research
│ ├── curriculum.py # Curriculum generation
│ └── translation.py # Multilingual content
├── config/ # Configuration utilities
└── visualization/ # Chart and diagram generation
data/
├── config/ # YAML configuration files
├── prompts/ # LLM prompt templates
├── audience_research/ # Generated entity research
├── domain_research/ # Generated domain analysis
├── written_curriculums/ # Generated curriculum content
├── translated_curriculums/ # Multilingual versions
└── visualizations/ # Charts and diagrams
learning/curriculum_creation/ # Main curriculum creation scripts
docs/ # Comprehensive documentation
tests/ # Test suite and fixtures
These tools are not required by the locked environment and are not declared
in pyproject.toml. Install them only if you want them for your own workflow:
# Notebook editing (not a project dependency)
uv run --with jupyter jupyter lab
# Faster JSON parsing (optional; the project uses the standard library)
uv run --with orjson python -c "import orjson; print(orjson.__version__)"
Avoid installing extra packages into the locked environment with bare pip;
use uv run --with ... so dependency resolution stays reproducible.
uv run --with jupyter jupyter lab for notebook development# Verify API keys are loaded
uv run python -c "import os; print('PERPLEXITY_API_KEY:', bool(os.getenv('PERPLEXITY_API_KEY')))"
# Verify the installed package
uv run python -c "import src.common.paths; print('Import successful')"
# Force reinstall dependencies
uv sync --reinstall
# Check for conflicts
uv tree
docs/ directory for detailed guidestests/ for usage examples.github/workflows/ci.yml calls the same start-gate arms a developer runs, so
emulating CI locally is running the affected arms:
uv sync --all-extras --dev --locked
uv run start-gate lint
uv run start-gate full
uv run start-gate docs
sequenceDiagram
participant Dev as Developer
participant Gate as start-gate
participant CI as CI Runner
Dev->>Gate: uv run start-gate <arm>
CI->>Gate: uv run start-gate <arm>
Gate-->>Dev: arm output
Gate-->>CI: arm output
Job-to-arm mapping is in Gate entry point; markers in
TESTING.md.