Start

Environment Setup & Development Guide

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

Prerequisites

System Requirements

API Access Requirements

Quick Installation

Steps

Links

1. Install uv Package Manager

curl -LsSf https://astral.sh/uv/install.sh | sh
# or on macOS: brew install uv

2. Install Project Dependencies

# Install all dependencies including development tools
uv sync --all-extras --dev

3. Download Required Models

# 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

Configuration

1. Environment Variables Setup

# Copy the example environment file
cp .env.example .env

# Edit with your API keys and configuration
$EDITOR .env

2. Required Environment Variables

# 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

3. Configuration Files

The system uses YAML configuration files in data/config/:

Development Workflow

Code Quality & Testing

uv 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 .

Curriculum Pipeline Development

# Use the canonical installed orchestrator in the locked environment
uv run start-curriculum --help
uv run start-validate-outputs --check

Testing API Integration

# 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')
"

Project Structure

Core Development Directories

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 and Configuration

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 and Documentation

learning/curriculum_creation/ # Main curriculum creation scripts
docs/                        # Comprehensive documentation
tests/                       # Test suite and fixtures

Advanced Setup

Optional Tooling

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.

IDE Integration

Troubleshooting

Common Issues

API Key Issues

# Verify API keys are loaded
uv run python -c "import os; print('PERPLEXITY_API_KEY:', bool(os.getenv('PERPLEXITY_API_KEY')))"

Import Errors

# Verify the installed package
uv run python -c "import src.common.paths; print('Import successful')"

Dependency Issues

# Force reinstall dependencies
uv sync --reinstall

# Check for conflicts
uv tree

Performance Considerations

Getting Help

Continuous Integration (CI)

.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.