POE2 Build AI

A Rails + Python application for analyzing Path of Exile 2 league changes and helping with build planning.

The long-term goal is to build an assistant that can:

ingest new league announcements and patch notes
detect what got buffed, nerfed, reworked, added, or removed
map those changes to known build archetypes
help diagnose a struggling character
recommend better passive pathing, uniques, and rare item priorities

This project is not intended to automate gameplay or act as a bot. It is a planning and analysis tool.

Overview
Goals of the App
Tech Stack
Project Layout
Current MVP Scope
Quick Start
Detailed Setup
Database and Core Models
Example API Endpoints
Development Workflow
Debugging / Issues We Ran Into
Recommended Next Steps
Long-Term Vision
Notes

Overview

POE2 Build AI is meant to become a build analysis assistant for Path of Exile 2.

Instead of trying to train a giant game-specific model from scratch, the app is structured around:

official patch-note ingestion
structured build archetype data
character snapshot diagnosis
rule-based and model-assisted recommendations

The first versions focus on building a reliable foundation:

store patch documents
store balance changes
store build archetypes
diagnose characters
expose simple recommendation APIs

Goals of the App

This app is meant to answer questions like:

What builds got buffed or nerfed this league?
Which league starters look stronger after the latest patch notes?
Why does my build feel weak right now?
What should I upgrade next?
Should I replace this unique with a rare?
What stats should I prioritize on my next gear upgrade?

The app is built around a few core ideas:

1. Patch ingestion

store official patch notes and announcements
extract meaningful balance changes from raw text

2. Build knowledge

maintain a structured database of build archetypes
track offense/defense tags, scaling methods, and common failure modes

3. Character diagnosis

accept a snapshot of a build
identify likely issues
suggest next upgrades and fixes

4. Recommendation engine

combine structured data, rules, and later ML/LLM support
explain why a build is improving or getting worse

Tech Stack

Main app

Ruby on Rails 8
PostgreSQL
Redis
Sidekiq

Supporting services

Python / FastAPI
scikit-learn / XGBoost for future scoring models

Infra / dev environment

Docker Compose

Project Layout

poe2_build_ai/
├── app/                  # Rails application
│   ├── app/
│   │   ├── controllers/
│   │   ├── models/
│   │   ├── services/
│   │   └── jobs/
│   ├── config/
│   ├── db/
│   └── Dockerfile
├── python_service/       # FastAPI scoring service
│   ├── main.py
│   ├── requirements.txt
│   └── Dockerfile
├── docker-compose.yml
├── .env
└── README.md

Key parts

Rails app

Responsible for:

API endpoints
database models
background jobs
patch ingestion
archetype storage
character snapshots
recommendation history

Python service

Responsible for:

lightweight scoring endpoints
future ranking or model-based recommendations

Postgres

Stores:

patch documents
patch changes
build archetypes
archetype impact mappings
character snapshots
recommendation runs

Redis / Sidekiq

Used for:

background jobs
patch fetching and parsing
future async processing

Current MVP Scope

The current app skeleton is designed to support:

storing patch documents
storing patch changes
storing build archetypes
diagnosing a build snapshot
exposing basic JSON API endpoints

Planned next steps include:

patch note ingestion jobs
patch parsing
change classification
mapping changes to archetypes
league starter summaries
upgrade recommendation logic
passive-tree-aware recommendations

Quick Start

If you already have Docker Desktop running and just want the short version:

mkdir poe2_build_ai
cd poe2_build_ai
git init
mkdir -p python_service

Create the Rails app:

docker run --rm \
  -v "$PWD:/app" \
  -w /app \
  ruby:3.3.1 \
  bash -lc 'gem install rails bundler && ruby -S rails new app -d postgresql'

Then create the project files described below, and run:

docker compose build
docker compose run --rm web bundle install
docker compose run --rm web bin/rails db:create
docker compose run --rm web bin/rails db:migrate
docker compose up

Health checks:

curl http://localhost:3000/up
curl http://localhost:8001/health

Detailed Setup

Prerequisites

You should have these installed on your Mac:

Docker Desktop
Git

Optional but useful:

Homebrew
Python 3
curl

Verify Docker is running:

docker --version
docker compose version

Initial Project Setup

From your terminal:

mkdir poe2_build_ai
cd poe2_build_ai
git init

Create the Rails App

We initially scaffolded Rails inside Docker rather than installing Ruby/Rails directly on macOS.

docker run --rm \
  -v "$PWD:/app" \
  -w /app \
  ruby:3.3.1 \
  bash -lc 'gem install rails bundler && ruby -S rails new app -d postgresql'

If ruby -S rails is needed, it is because the rails executable may not be on PATH inside the temporary container.

Create the Python Service

mkdir -p python_service

Create python_service/requirements.txt:

fastapi
uvicorn
pydantic
scikit-learn
pandas
numpy
xgboost

Create python_service/main.py:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class BuildScoreRequest(BaseModel):
    archetype: dict
    patch_impacts: list
    character_snapshot: dict | None = None

@app.get("/health")
def health():
    return {"ok": True}

@app.post("/score_archetype")
def score_archetype(req: BuildScoreRequest):
    score = sum(item.get("impact_score", 0) for item in req.patch_impacts)
    return {
        "league_start_score": score,
        "confidence": 0.65
    }

Create python_service/Dockerfile:

FROM python:3.11-slim

WORKDIR /service

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8001

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8001"]

Rails Dockerfile

Replace app/Dockerfile with:

FROM ruby:3.3.1

RUN apt-get update -qq && apt-get install -y \
  build-essential \
  libpq-dev \
  nodejs \
  && rm -rf /var/lib/apt/lists/*

WORKDIR /rails

COPY Gemfile Gemfile.lock ./
RUN bundle install

COPY . .

EXPOSE 3000

CMD ["bash", "-lc", "bundle exec rails server -b 0.0.0.0 -p 3000"]

Rails Gemfile

Replace app/Gemfile with:

source "https://rubygems.org"

gem "rails", "~> 8.1.3"
gem "pg", "~> 1.1"
gem "puma", ">= 5.0"
gem "bootsnap", require: false
gem "propshaft"

gem "sidekiq"
gem "redis"
gem "httparty"
gem "oj"
gem "dotenv-rails"
gem "pgvector"
gem "ruby-openai"

propshaft is included because Rails 8 generated config may still assume asset-related configuration exists.

docker-compose.yml

Create this in the project root:

services:
  db:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: poe2_ai_development
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7
    ports:
      - "6379:6379"

  python_service:
    build:
      context: ./python_service
    volumes:
      - ./python_service:/service
    ports:
      - "8001:8001"

  web:
    build:
      context: ./app
    command: bash -lc "rm -f tmp/pids/server.pid && bundle exec rails server -b 0.0.0.0 -p 3000"
    volumes:
      - ./app:/rails
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://postgres:password@db:5432/poe2_ai_development
      REDIS_URL: redis://redis:6379/0
      PYTHON_SERVICE_URL: http://python_service:8001
      RAILS_ENV: development
    depends_on:
      - db
      - redis
      - python_service

  worker:
    build:
      context: ./app
    command: bash -lc "bundle exec sidekiq"
    volumes:
      - ./app:/rails
    environment:
      DATABASE_URL: postgres://postgres:password@db:5432/poe2_ai_development
      REDIS_URL: redis://redis:6379/0
      PYTHON_SERVICE_URL: http://python_service:8001
      RAILS_ENV: development
    depends_on:
      - db
      - redis

volumes:
  postgres_data:

Database config

Replace app/config/database.yml with:

default: &default
  adapter: postgresql
  encoding: unicode
  pool: <%= ENV.fetch("RAILS_MAX_THREADS", 5) %>
  url: <%= ENV["DATABASE_URL"] %>

development:
  <<: *default

test:
  <<: *default
  url: postgres://postgres:password@db:5432/poe2_ai_test

Sidekiq config

Create app/config/initializers/sidekiq.rb:

Sidekiq.configure_server do |config|
  config.redis = { url: ENV.fetch("REDIS_URL", "redis://redis:6379/0") }
end

Sidekiq.configure_client do |config|
  config.redis = { url: ENV.fetch("REDIS_URL", "redis://redis:6379/0") }
end

Environment variables

Create .env:

OPENAI_API_KEY=replace_me

Build and boot

Build the containers:

docker compose build

Install gems inside the web container:

docker compose run --rm web bundle install

Create the database:

docker compose run --rm web bin/rails db:create

Run migrations:

docker compose run --rm web bin/rails db:migrate

Start the app:

docker compose up

Database and Core Models

Planned core models include:

PatchDocument
PatchChange
Archetype
ArchetypeImpact
CharacterSnapshot
RecommendationRun

These are intended to support:

patch note storage
parsed balance changes
build archetypes
build impact analysis
build diagnosis
recommendation tracking

Example model generation commands

docker compose run --rm web bin/rails generate model PatchDocument \
  title:string source_url:string version:string document_type:string \
  published_at:datetime raw_text:text metadata:jsonb

docker compose run --rm web bin/rails generate model PatchChange \
  patch_document:references entity_name:string entity_type:string \
  change_type:string before_text:text after_text:text summary:text \
  tags:jsonb numeric_data:jsonb confidence:float

docker compose run --rm web bin/rails generate model Archetype \
  name:string class_name:string ascendancy_name:string primary_skill:string \
  offense_tags:jsonb defense_tags:jsonb core_mechanics:jsonb \
  leveling_notes:text failure_modes:text

docker compose run --rm web bin/rails generate model ArchetypeImpact \
  archetype:references patch_change:references impact_score:float \
  impact_kind:string reasoning:text

docker compose run --rm web bin/rails generate model CharacterSnapshot \
  name:string class_name:string ascendancy_name:string level:integer \
  skills:jsonb stats:jsonb defenses:jsonb gear:jsonb passives:jsonb \
  constraints:jsonb

docker compose run --rm web bin/rails generate model RecommendationRun \
  character_snapshot:references mode:string input_payload:jsonb output_payload:jsonb

pgvector migration

Generate the migration:

docker compose run --rm web bin/rails generate migration EnablePgvector

Then edit the migration file to:

class EnablePgvector < ActiveRecord::Migration[8.1]
  def change
    enable_extension "vector"
  end
end

JSONB defaults

When editing generated migrations, use defaults like:

t.jsonb :metadata, default: {}
t.jsonb :tags, default: []
t.jsonb :numeric_data, default: {}
t.jsonb :offense_tags, default: []
t.jsonb :defense_tags, default: []
t.jsonb :core_mechanics, default: []
t.jsonb :skills, default: {}
t.jsonb :stats, default: {}
t.jsonb :defenses, default: {}
t.jsonb :gear, default: {}
t.jsonb :passives, default: {}
t.jsonb :constraints, default: {}
t.jsonb :input_payload, default: {}
t.jsonb :output_payload, default: {}

Example API Endpoints

Health check

GET /up

League starters

GET /api/league_starters

Diagnose build

POST /api/diagnose_build

Example request:

{
  "name": "My Ranger",
  "class_name": "Ranger",
  "ascendancy_name": "Deadeye",
  "level": 35,
  "defenses": {
    "life": 420,
    "fire_res": 48,
    "cold_res": 31,
    "lightning_res": 75
  },
  "gear": {
    "weapon": {
      "type": "Bow",
      "dps_score": 70
    }
  }
}

Example curl:

curl -X POST http://localhost:3000/api/diagnose_build \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Ranger",
    "class_name": "Ranger",
    "ascendancy_name": "Deadeye",
    "level": 35,
    "defenses": {
      "life": 420,
      "fire_res": 48,
      "cold_res": 31,
      "lightning_res": 75
    },
    "gear": {
      "weapon": {
        "type": "Bow",
        "dps_score": 70
      }
    }
  }'

Development Workflow

Common commands:

docker compose up
docker compose down
docker compose logs -f web
docker compose logs -f worker
docker compose run --rm web bin/rails console
docker compose run --rm web bin/rails db:migrate
docker compose run --rm web bin/rails db:seed
docker compose restart web

Useful checks:

curl http://localhost:3000/up
curl http://localhost:8001/health
curl http://localhost:3000/api/league_starters

Debugging / Issues We Ran Into

This section documents the actual problems hit during setup so future setup is faster.

1. `rails: command not found` during initial scaffold

Command:

docker run --rm \
  -v "$PWD:/app" \
  -w /app \
  ruby:3.3.1 \
  bash -lc 'gem install rails bundler && rails new app -d postgresql'

Problem:

Rails gem installed successfully
but the rails executable was not on PATH inside the shell

Fix:

use ruby -S rails instead

docker run --rm \
  -v "$PWD:/app" \
  -w /app \
  ruby:3.3.1 \
  bash -lc 'gem install rails bundler && ruby -S rails new app -d postgresql'

2. `cannot load such file -- bootsnap/setup`

Problem:

the Rails app scaffold was mostly created
but some post-generation installer steps failed while loading bootsnap/setup

Cause:

dependency/setup mismatch during scaffold completion

Fix:

keep the generated app
continue with Docker-first setup
ensure bootsnap is present in the Gemfile
run bundle install inside the container

3. `undefined method 'assets' for Rails::Application::Configuration`

Error looked like:

NoMethodError: undefined method `assets' for an instance of Rails::Application::Configuration

Cause:

Rails generated config still referenced asset configuration
but the simplified Gemfile no longer had the matching asset pipeline support

Fix:

add propshaft back to the Gemfile

gem "propshaft"

4. `stale_when_importmap_changes` undefined in `ApplicationController`

Problematic controller:

class ApplicationController < ActionController::Base
  allow_browser versions: :modern
  stale_when_importmap_changes
end

Cause:

default scaffold code expected importmap-related helpers
but the app was no longer using that setup

Fix:

simplify the controller

class ApplicationController < ActionController::Base
  allow_browser versions: :modern
end

If allow_browser ever becomes a problem too, the fallback is:

class ApplicationController < ActionController::Base
end

Recommended Next Steps

Once the app boots cleanly:

add the core models and migrations
seed a small set of build archetypes
add a CharacterDoctor service
add recommendation endpoints
add patch-note ingestion jobs
parse raw patch notes into structured changes
map those changes to build archetypes
generate league-start summaries

A good first milestone is getting these endpoints working:

GET /up
GET /api/league_starters
POST /api/diagnose_build

Long-Term Vision

The final version of this app should be able to:

ingest official POE2 patch notes quickly
classify changes automatically
explain build meta shifts
rank likely league starters
help diagnose weak builds
recommend item and passive path changes
provide grounded reasoning instead of generic chatbot answers

The system should stay focused on being a build planning and analysis assistant, not an automation tool.

Notes

This project currently favors a Docker-first workflow
The app is still in early scaffolding / MVP stage
The current priority is getting a clean vertical slice working before adding more advanced AI or ML features
If setup gets weird, favor keeping the generated app and fixing config incrementally instead of repeatedly recreating the project from scratch

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

POE2 Build AI

Table of Contents

Overview

Goals of the App

1. Patch ingestion

2. Build knowledge

3. Character diagnosis

4. Recommendation engine

Tech Stack

Main app

Supporting services

Infra / dev environment

Project Layout

Key parts

Rails app

Python service

Postgres

Redis / Sidekiq

Current MVP Scope

Quick Start

Detailed Setup

Prerequisites

Initial Project Setup

Create the Rails App

Create the Python Service

Rails Dockerfile

Rails Gemfile

docker-compose.yml

Database config

Sidekiq config

Environment variables

Build and boot

Database and Core Models

Example model generation commands

pgvector migration

JSONB defaults

Example API Endpoints

Health check

League starters

Diagnose build

Development Workflow

Debugging / Issues We Ran Into

1. rails: command not found during initial scaffold

2. cannot load such file -- bootsnap/setup

3. undefined method 'assets' for Rails::Application::Configuration

4. stale_when_importmap_changes undefined in ApplicationController

Recommended Next Steps

Long-Term Vision

Notes

1. `rails: command not found` during initial scaffold

2. `cannot load such file -- bootsnap/setup`

3. `undefined method 'assets' for Rails::Application::Configuration`

4. `stale_when_importmap_changes` undefined in `ApplicationController`