Overview

DSPy Factorio provides an engaging platform for mastering DSPy by utilizing the Factorio Learning Environment (FLE). Through gradual, hands-on practice, users can learn to create and optimize small Python programs that interact with the game, making the learning process both immersive and effective.

Key Features

• Interactive Learning: Engage with Factorio as a training ground. The environment encourages writing Python scripts that control and observe factory operations through various DSPy modules, including Predict, GEPA, RLM, and Flex.

FLE / Factorio  ←── programs / tools ──  DSPy modules
     obs text  ──────────────────────►  (Predict → GEPA → RLM → Flex)

• Structured Learning Path: Progress systematically through six levels of complexity, starting with basic connections and culminating in advanced agent optimization. Each step is designed to build upon the knowledge acquired in the previous stage:

• Quick Start Guide: Get up and running promptly with a clear setup process:

# 1) Install dependencies
uv sync

# 2) API keys configuration
cp .env.example .env
# Add OPENAI_API_KEY=... in .env

# 3) Start Factorio cluster (Docker required)
uv run fle cluster start -n 1
# Wait ~30–90s on Apple Silicon for RCON to come up

# 4) Run Hello World example
uv run python examples/01_hello_world.py

Documentation

Comprehensive documentation is available detailing setup, tutorials, and troubleshooting to enhance user experience and facilitate learning. Key documents include:

Example Scripts

A rich collection of example scripts illustrates various functionalities:

Project Structure

Organized for clarity, the project layout comprises:

dspy_factorio/          # Environment, agent, offline training dataset
examples/              # Numbered DSPy / FLE practice scripts
docs/                  # Setup and step-by-step tutorials
docs/.env              # Secrets (gitignored)

For additional details and resources, visit the repository: github.com/ukituki/dspy-factorio.