Installation
============

Prerequisites
-------------

Before installing FLE, ensure you have:

- **Docker**: Required for running Factorio server instances
- **Python 3.10+**: The minimum Python version supported
- **Factorio** (version 1.1.110): Only needed for optional rendering with graphics

Installation Methods
--------------------

Core Installation
~~~~~~~~~~~~~~~~~

Install the core FLE SDK package:

.. code-block:: bash

   # Using pip
   pip install factorio-learning-environment

   # Using uv (recommended)
   uv add factorio-learning-environment

Installation with Optional Features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

FLE provides several optional feature sets:

.. code-block:: bash

   # For running experiments
   pip install factorio-learning-environment[eval]

   # For MCP protocol support
   pip install factorio-learning-environment[mcp]

   # For PostgreSQL support
   pip install factorio-learning-environment[psql]

   # Install all features
   pip install factorio-learning-environment[eval,mcp,psql]

   # Using uv (recommended)
   uv add factorio-learning-environment[eval]

Client-side Setup (Optional)
-----------------------------

For rendering Factorio with graphics, you need to set up a Factorio client:

1. **Purchase and Install Factorio**

   - Purchase from the `official website <https://www.factorio.com/>`_ (recommended) or on Steam
   - Download and install the game

2. **Downgrade to Version 1.1.110**

   - **Steam**: Right-click Factorio → Properties → Betas → Select ``1.1.110``
   - **Important**: Uncheck the Space Age DLC if you have it, as it forces the 2.x branch

3. **Activate Server License**

   - Open the Factorio client
   - Navigate to *Multiplayer*
   - Connect to ``localhost:34197`` (default) or your configured address in Docker
   - Once connected, you can safely disconnect. This step confirms your Factorio license with the server.

API Key Configuration
---------------------

FLE supports multiple LLM providers for agent evaluation.

Quick Setup (Recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~

Use the interactive setup script:

.. code-block:: bash

   python fle/eval/infra/setup_api_keys.py

This script helps you:

- Configure API keys for OpenAI, Anthropic, and other providers
- Set up API key rotation for high-volume experiments
- Generate provider-specific configuration files
- Validate your API key setup

Manual Setup
~~~~~~~~~~~~

Add your API keys to the ``.env`` file:

.. code-block:: bash

   # OpenAI
   OPENAI_API_KEY=sk-...

   # Anthropic
   ANTHROPIC_API_KEY=sk-ant-...

   # Additional providers as needed

Advanced Configuration
~~~~~~~~~~~~~~~~~~~~~~

For large-scale experiments, you can set up API key rotation and provider-specific settings using the configuration files generated by ``setup_api_keys.py``.

Initial Setup
-------------

When you run ``fle init`` or ``fle eval`` for the first time:

- An ``.env`` file is automatically created
- A ``configs/`` directory with example configurations is created

Verification
------------

Verify your installation by starting the Factorio cluster:

.. code-block:: bash

   # Start Factorio cluster
   fle cluster start

   # Run evaluation trajectories (requires [eval] dependencies)
   fle eval --config configs/gym_run_config.json

Next Steps
----------

- Continue to :doc:`quickstart` to learn how to use FLE
- See :doc:`troubleshooting` if you encounter issues
