` block. Successful PNGs are cached by content, language, theme,
pipeline, and Carbon version, then embedded directly in the self-contained
HTML. They therefore appear in the HTML-derived PDF and PPTX, while
`slides.tex` and the Beamer PDF remain unchanged. Use `--code-images off` to
persistently return the course to `` rendering.
### Method 3: Direct API Calls
**API Server**: `api_server.py` β RESTful API service
```bash
# Start API server first (if not using Docker)
python api_server.py
# Generate a course
curl -X POST http://localhost:8000/api/course/generate \
-H "Content-Type: application/json" \
-H "X-OpenAI-API-Key: your_api_key_here" \
-d '{
"course_name": "Introduction to Machine Learning",
"model_name": "gpt-4o-mini",
"exp_name": "ml_intro_v1"
}'
# Check task status
curl http://localhost:8000/api/course/status/{task_id}
# Get result files
curl http://localhost:8000/api/course/results/{task_id}/files
# Download a file
curl http://localhost:8000/api/course/results/{task_id}/download/chapter_1/slides.pdf \
--output slides.pdf
```
For complete API documentation, see [API Documentation](https://github.com/DaRL-GenAI/instructional_agents/blob/HEAD/docs/API_DOCUMENTATION.md).
---
## π§ Core Modules
| Module | Description | Usage |
|--------|-------------|-------|
| **Course Generation** | Generate complete course materials based on ADDIE model | Web interface, CLI (`run.py`), or RESTful API |
| **Catalog Mode** | Use structured catalog files for guided generation | `--catalog` flag or upload in web interface |
| **Copilot Mode** | Interactive feedback during generation | `--copilot` flag in CLI or enable in web interface |
| **Evaluation** | Automatic assessment of generated materials | `python evaluate.py --exp ` |
| **Web Interface** | Visual interface for course generation | Open `frontend/index.html` in browser |
| **API Server** | RESTful API for programmatic access | `python api_server.py` or Docker |
---
## π Advanced Usage
### Catalog Mode
Catalog files provide structured input data to guide the course generation process. They include:
- Student profiles and backgrounds
- Instructor preferences and teaching style
- Optional presentation style preferences, including visual direction, colors,
typography, layout density, accessibility needs, and styles to avoid
- Course structure requirements
- Assessment design preferences
- Teaching constraints
- Institutional requirements
**Using Catalogs**:
```bash
# Use default catalog
python run.py "Software Engineering" --catalog
# Use a specific catalog file (without .json extension)
python run.py "AI Fundamentals" --catalog ai_catalog
# System looks for: catalog/ai_catalog.json
# Upload catalog via web interface
# In the web interface, select "δΈδΌ Catalog ζδ»Ά" and upload your JSON file
```
See [API Documentation](https://github.com/DaRL-GenAI/instructional_agents/blob/HEAD/docs/API_DOCUMENTATION.md#catalog-format) for catalog format details.
`presentation_style_preferences` is advisory. The presentation-design agents
consider every non-empty preference when comparing packaged styles, while
accessibility, readability, course suitability, and rendering feasibility take
priority when a preference conflicts with the available designs. The selected
style remains frozen on resume; use a new experiment or
`--reselect-presentation-design` with `run.py` to apply changed
preferences.
### Copilot Mode
Interactive mode that prompts for feedback after each phase of the ADDIE workflow:
- **Analysis** phase: Review and provide feedback on learning goals, resource assessment, target audience
- **Design** phase: Review and refine syllabus design, assessment planning, final project
- **Development** phase: Review and adjust chapter materials as they're generated
```bash
python run.py "Advanced Algorithms" --copilot --exp algo_course_v2
```
### Automatic Evaluation
**Entry Point**: `evaluate.py` β Automatic assessment and scoring
```bash
# Evaluate a specific experiment
python evaluate.py --exp web_dev_v1
```
Evaluation results are saved in `eval/{experiment_name}/` directory.
### LaTeX-to-PPTX Conversion
Convert generated LaTeX Beamer slides to editable PowerPoint presentations with professional design:
```bash
# Convert a single chapter
python -c "
from src.latex_to_pptx import LaTeXToPPTXConverter
converter = LaTeXToPPTXConverter()
converter.convert('exp/my_course/chapter_1/slides.tex', 'exp/my_course/chapter_1/slides.pptx')
"
# Convert all chapters in a course
python -c "
from src.latex_to_pptx import LaTeXToPPTXConverter
converter = LaTeXToPPTXConverter()
converter.convert_directory('exp/my_course/')
"
```
**PPTX Design Features:**
- π¨ **Midnight Executive palette** β navy/ice-blue/orange color scheme with Georgia/Calibri fonts
- π **Slide Masters** β consistent layouts via `CONTENT_MASTER`, `CONTENT_CODE`, and `DARK_MASTER`
- π **Dark/light sandwich** β dark slides for title/conclusion, light for content
- π€ **Smart icons** β topic-aware icons from react-icons (robot, brain, code, etc.) in colored circles
- π **Varied layouts** β auto-detected: single-text, list-only, blocks, code, columns, mixed
- π« **Visual polish** β shadows on blocks/code, sidebar accent motif, decorative circles
- π **Typography** β 36pt+ titles, 14-16pt body, auto-scaling for long titles
**Architecture**: `LaTeX .tex β [Python LaTeXParser] β JSON β [Node.js pptxgenjs] β .pptx`
### Background Execution with Logging
For long-running tasks, run in the background:
```bash
# Run in background with log file
nohup python run.py "Advanced Machine Learning" --exp ml_advanced > logs/ml_course.log 2>&1 &
# Monitor progress
tail -f logs/ml_course.log
# Check process status
ps aux | grep "python run.py"
```
---
## π Example Workflows
### Complete Course Design
```bash
# Step 1: Generate course using catalog
python run.py "Python Fundamentals" \
--catalog python_catalog \
--model gpt-4o \
--exp py_course_v1
# Step 2: Evaluate results
python evaluate.py --exp py_course_v1
# Step 3: Review generated materials
open exp/py_course_v1/result_syllabus_design.md
open exp/py_course_v1/chapter_1/slides.pdf
```
### Interactive Development (Copilot)
```bash
python run.py "Advanced Algorithms" --copilot --exp algo_course_v2
# You'll be prompted for feedback after each phase:
# - Analysis β feedback on goals, resources, audience
# - Design β feedback on syllabus, assessments
# - Development β feedback on chapter materials
```
---
## π Documentation
| [API Documentation](https://github.com/DaRL-GenAI/instructional_agents/blob/HEAD/docs/API_DOCUMENTATION.md) | [Docker Deployment](https://github.com/DaRL-GenAI/instructional_agents/blob/HEAD/docs/README_DOCKER.md) | [Generated Files Guide](https://github.com/DaRL-GenAI/instructional_agents/blob/HEAD/docs/FILES_GENERATED.md) |
|------------------------------------------------|---------------------------------------------|---------------------------------------------------|
| Complete API reference and endpoints | Docker setup and deployment guide | Detailed description of generated files |
| [Workflow Documentation](https://github.com/DaRL-GenAI/instructional_agents/blob/HEAD/docs/WORKFLOW_DOCUMENTATION.md) | [Development Guide](https://github.com/DaRL-GenAI/instructional_agents/blob/HEAD/docs/README.md) | |
|----------------------------------------------------------|--------------------------------------|--|
| System workflow and agent collaboration details | Development and debugging documentation | |
---
## β FAQ
How to configure API key?
**Checklist**
- Get OpenAI API key from https://platform.openai.com/api-keys
- Configure in `.env` file or web interface
**Solutions**
- **Option 1**: Set in `.env` file: `OPENAI_API_KEY=your_key_here`
- **Option 2**: Configure in web interface (stored in browser local storage only)
Port 8000 already in use?
**Problem**
Starting the service shows "port already in use" error.
**Solution**
```bash
# macOS/Linux: Find and kill the process
lsof -i :8000
kill -9
# Or change port in .env file
API_PORT=8001
```
How to use catalog files?
**Checklist**
- Catalog files should be in JSON format
- Place catalog files in `catalog/` directory
**Solutions**
- **Default catalog**: Use `--catalog` without value to use `catalog/default_catalog.json`
- **Custom catalog**: Use `--catalog my_catalog` to use `catalog/my_catalog.json`
- **Web interface**: Upload catalog file directly in the web interface
Where are generated files saved?
**Answer**
Generated files are saved in `exp/{experiment_name}/` directory:
- Foundation files (syllabus, goals, etc.) in the root
- Chapter materials in `chapter_1/`, `chapter_2/`, etc.
- Files are generated incrementally and can be downloaded as soon as they appear
Web interface cannot connect to backend?
**Checklist**
- Confirm backend is running (visit http://localhost:8000/docs or http://localhost:8000/health)
- Check browser console for error messages
- Verify API address configuration
**Solution**
- **Docker**: Ensure Docker container is running: `docker-compose ps`
- **Local**: Ensure API server is running: `python api_server.py`
- Check that the port matches (default: 8000)
What models are supported?
**Answer**
Currently supports OpenAI models:
- GPT-4o Mini (recommended, cost-effective)
- GPT-4o
- GPT-4 Turbo
Configure via model selection in web interface or `--model` flag in CLI.
---
## π License
Instructional Agents is released under the [MIT License](https://github.com/DaRL-GenAI/instructional_agents/blob/HEAD/LICENSE).
### Third-party attribution
The HTML slide style-selection assets in [`assets/slide_gen/skill`](assets/slide_gen/skill)
are adapted from [Frontend Slides](https://github.com/zarazhangrui/frontend-slides)
by Zara Zhang. Frontend Slides is used under the MIT License; its original
copyright notice and license terms are preserved in
[`assets/slide_gen/skill/LICENSE`](assets/slide_gen/skill/LICENSE).