DSPy Factorio — Master building agents through…

Pitch

Description

Comments

About this project

Dive into the world of agentic engineering by engaging with the Factorio Learning Environment. This project provides a structured approach to learning DSPy framework concepts by applying them in a real game setting. Develop your Python skills while optimizing factory operations and enhancing your understanding of AI agents in a fun and interactive way.

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:

Step	What you practice	Entry
1	Connect + one FLE program	HELLO_WORLD.md · `examples/01_…`
2	Scripted multi-step play	`examples/03_scripted_miner.py`
3	DSPy `Predict` agent loop	`examples/04_dspy_agent_loop.py`
4	Optimize instructions (GEPA)	GEPA_STARTER.md · `07`/`08`
5	REPL agent (`dspy.RLM`)	RLM_STARTER.md · `11`
6	Structure search (`dspy.Flex`)	FLEX_STARTER.md · `12`/`13a`/`13b`

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:

Doc	What it covers
docs/SETUP.md	Install instructions and environment variables
docs/HELP.md	Guide for the first working program
docs/VISUALIZATION.md	Techniques for visualizing map dumps and live gameplay
docs/SCENARIOS.md	Building scripted scenarios and using LLM
docs/AI_OPTIMIZATION.md	Insights into DSPy runtime performance
docs/GEPA_STARTER.md	Initial guidance on GEPA optimizations
docs/RLM_STARTER.md	Details on using `dspy.RLM` for REPL agents
docs/FLEX_STARTER.md	Introduction to `dspy.Flex` for structuring training

Example Scripts

A rich collection of example scripts illustrates various functionalities:

Script	Purpose
`examples/01_hello_world.py`	Establish a connection and identify the nearest iron ore resource
`examples/02_list_environments.py`	List task IDs within the FLE
`examples/03_scripted_miner.py`	Execute a deterministic multi-step scenario
`examples/04_dspy_agent_loop.py`	Demonstrate the DSPy agent loop
`examples/11_dspy_rlm_miner.py`	Utilize `dspy.RLM` to automate mining tasks

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.