GitHub - ukituki/dspy-factorio: Learn DSPy step by step by teaching agents how to play Factorio (FLE) · GitHub
/" data-turbo-transient="true" />
Skip to content
Type / to search
Sign in<br>Sign upAppearance settings
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
ukituki
dspy-factorio
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
master
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>14 Commits<br>14 Commits
docs
docs
dspy_factorio
dspy_factorio
examples
examples
.env.example
.env.example
.gitignore
.gitignore
.python-version
.python-version
README.md
README.md
main.py
main.py
pyproject.toml
pyproject.toml
uv.lock
uv.lock
View all files
Repository files navigation
DSPy Factorio
Step-by-step practice for learning DSPy by playing Factorio through the Factorio Learning Environment (FLE).
You write (or optimize) small Python programs that act in the game — Predict, GEPA, RLM, Flex — and see the factory respond. The game is the gym; DSPy is what you’re learning.
FLE / Factorio ←── programs / tools ── DSPy modules<br>obs text ──────────────────────► (Predict → GEPA → RLM → Flex)
Learning path
Step<br>What you practice<br>Entry
Connect + one FLE program<br>HELLO_WORLD.md · examples/01_…
Scripted multi-step play<br>examples/03_scripted_miner.py
DSPy Predict agent loop<br>examples/04_dspy_agent_loop.py
Optimize instructions (GEPA)<br>GEPA_STARTER.md · 07/08
REPL agent (dspy.RLM)<br>RLM_STARTER.md · 11
Structure search (dspy.Flex)<br>FLEX_STARTER.md · 12/13a/13b
Same early milestone across advanced paths: place and fuel one burner mining drill .
Quick start
# 1) deps<br>uv sync
# 2) API keys<br>cp .env.example .env<br># put OPENAI_API_KEY=... in .env
# 3) Factorio cluster (Docker required)<br>uv run fle cluster start -n 1<br># wait ~30–90s on Apple Silicon for RCON to come up
# 4) Hello World<br>uv run python examples/01_hello_world.py
Documentation
Doc<br>What it covers
docs/SETUP.md<br>Install, cluster, env vars, Apple Silicon notes
docs/HELLO_WORLD.md<br>First working program end-to-end
docs/VISUALIZATION.md<br>PNG map dumps (no client) + optional live Factorio client
docs/SCENARIOS.md<br>Building scripted + LLM scenarios
docs/AI_OPTIMIZATION.md<br>DSPy runtime vs optimization tracks
docs/GEPA_STARTER.md<br>Minimal GEPA optimize → load flow
docs/RLM_STARTER.md<br>dspy.RLM REPL agent → place a fueled drill
docs/FLEX_STARTER.md<br>dspy.Flex intro → train from play → run
docs/TROUBLESHOOTING.md<br>Docker / RCON / eval pitfalls we hit
FLE reference (0.3.x docs — partly outdated vs installed 0.4.x):
Overview
Sphinx / API
Quickstart
Examples
Script<br>Purpose
examples/01_hello_world.py<br>Connect + nearest(Resource.IronOre)
examples/02_list_environments.py<br>List FLE task IDs
examples/03_scripted_miner.py<br>Deterministic multi-step scenario
examples/09_visualize_renders.py<br>Save map PNGs after each action
examples/10_live_client_watch.py<br>Join Factorio client + slow watchable scenario
examples/04_dspy_agent_loop.py<br>Intro DSPy agent loop (--renders for map PNGs)
examples/05_optimize_agent.py<br>Offline BootstrapFewShot train
examples/06_run_inspect_eval.py<br>Thin wrapper for fle inspect-eval
examples/07_gepa_train.py<br>Offline GEPA train → save module
examples/08_gepa_run.py<br>Run a GEPA-compiled module in Factorio
examples/11_dspy_rlm_miner.py<br>dspy.RLM + run_factorio tool (RLM_STARTER.md)
examples/12_dspy_flex_miner.py<br>Flex intro (baseline), same drill goal (FLEX_STARTER.md)
examples/13a_dspy_flex_train.py<br>Online play → demos → Flex+GEPA compile
examples/13b_dspy_flex_run.py<br>Load learned Flex → Factorio rollout
Important 0.4.x differences from upstream quickstart
fle eval is removed → use fle inspect-eval
Always pass --model ... (omitting it can crash)
With one Factorio container use --epochs 1 (default Pass@8 needs 8 instances)
gym.make(env_id) needs run_idx=0 — prefer dspy_factorio.env.make_env
Pin a2a-sdk>=0.3.26, (1.x breaks imports)
FLE still uses OpenAI gym (helpers silence deprecation noise; do not blindly switch to Gymnasium)
LLM agents must emit Resource.* / Prototype.* enums and move_to before distant placements
uv run fle inspect-eval \<br>--env-id iron_ore_throughput \<br>--model openai/gpt-4o-mini \<br>--limit 1 --epochs 1 \<br>--trajectory-length 64 \<br>--max-connections 1
Project layout
dspy_factorio/ # env + agent + offline trainset<br>examples/ # numbered DSPy / FLE practice scripts<br>docs/ # setup + step-by-step tutorials<br>.env # secrets (gitignored)
Repo: github.com/ukituki/dspy-factorio
About<br>Learn DSPy step by step by teaching agents how to play Factorio (FLE)<br>Topics<br>agentsdspydspy-aidspy-rlmfactorio<br>Resources<br>Readme<br>Activity<br>Stars<br>2 stars<br>Watchers<br>0 watching<br>Forks<br>0 forks<br>Report...