Six Components, Six Jobs

POE Crafter has six main components. When you paste an item, all six spring into action — like a stage crew that has rehearsed their moves so many times it looks effortless.

Stateless vs Stateful

Not all components are created equal. Some remember things between calls; others forget everything the moment they finish. This distinction shapes how the whole system is tested, scaled, and debugged.

The DataCache Singleton

Think of a hotel concierge who memorizes every guest preference once — ask twice and you get the same instant answer. The DataCache loads all 10,000+ game items once at startup, then answers lookups in microseconds. Below is the exact class definition from loader.py, translated line by line.

class DataCache:
    """
    In-memory cache for POE game data.

    Each instance holds independent state — no shared
    class-level mutable dicts.
    Use the module-level singleton `cache` for normal
    application code.
    Instantiate a fresh DataCache() in tests that need
    isolation.
    """

    def __init__(self) -> None:
        self.bases: Dict[str, Dict[str, Any]] = {}
        self.mods: Dict[str, Dict[str, Any]] = {}
        self._eligible_mods: Dict[str, Dict[int, List[...]]] = {}
        self._mod_weights: Dict[str, Dict[int, Dict[str, int]]] = {}
        self._initialized: bool = False
        self._engine: Optional[Engine] = None

Who Calls Whom

When you POST an item to /api/parse-pob, here is the conversation that plays out between the components. Click Next Message to step through it one exchange at a time.

The Full Picture

Every component has a home in the file system and a role in the request lifecycle. Click any component below to see exactly what it does and where it lives.

Check Your Understanding

Two Formats, One Result

POE Crafter accepts item text in two formats. Both are auto-detected — you just paste and go.

Item Class: Gloves
Rarity: Rare
Havoc Claw
Runic Gauntlets
--------
Item Level: 84
--------
+110 to maximum Life
+35% to Cold Resistance

Rarity: RARE
Eldritch Gloves
Runic Gauntlets
ItemLvl: 85
Prefix: {range:0.525}IncreasedLife8
Suffix: {range:0.803}FireResist6

The format detection logic is just a few lines. Here is exactly how Path of Building (PoB) exports are told apart from in-game pastes.

def parse_item(text: str, cache) -> ParseResult:
    lines = text.splitlines()
    is_pob = any(
        l.startswith("Prefix: ") or l.startswith("Suffix: ") for l in lines
    )
    if is_pob:
        log.debug("Detected PoB format")
        return _parse_pob(text, cache)
    log.debug("Detected in-game format")
    return _parse_ingame(text, cache)

How a Stat Line Becomes a Mod ID

The game shows +110 to maximum Life, but the code needs IncreasedLife8. These two things mean the same thing in different languages. The parser builds a bridge.

The function below converts one line from the mod database into a compiled pre-compiled regex pattern. It is called once per mod during server startup.

def _text_line_to_pattern(line: str) -> Tuple[re.Pattern, List[Tuple[float, float]]]:
    ranges: List[Tuple[float, float]] = []
    parts: List[str] = []
    last_end = 0

    for m in _RANGE_RE.finditer(line):
        parts.append(re.escape(line[last_end:m.start()]))
        lo = float(m.group(1))
        hi = float(m.group(2))
        ranges.append((lo, hi))
        is_float = ("." in m.group(1)) or ("." in m.group(2))
        parts.append(r"([\d.]+)" if is_float else r"(\d+)")
        last_end = m.end()

    parts.append(re.escape(line[last_end:]))
    pattern_str = "".join(parts)
    return re.compile(r"^" + pattern_str + r"$"), ranges

The Four Validation Rules

Once the parser produces an ItemState, the ValidationEngine runs it through four rules. Any rule can return errors. If all return None, the item is valid.

Inside AffixLimitRule

Every rule follows the same contract: receive a dictionary describing the item, return None on success or an error dictionary on failure. Here is AffixLimitRule in full.

class AffixLimitRule(ValidationRule):
    MAX_AFFIXES = 3

    def validate(self, item_state: Dict) -> Optional[Dict]:
        prefixes: List[str] = []
        suffixes: List[str] = []

        for mod_entry in item_state.get("target_mods", []):
            mod_id = mod_entry.get("mod_id") if isinstance(mod_entry, dict) else mod_entry
            mod_def = self.cache.mods.get(mod_id)
            if mod_def is None:
                continue
            if mod_def["mod_type"] == "prefix":
                prefixes.append(mod_id)
            else:
                suffixes.append(mod_id)

        errors: List[Dict] = []
        suggestions: List[str] = []

        if len(prefixes) > self.MAX_AFFIXES:
            excess = len(prefixes) - self.MAX_AFFIXES
            errors.append({
                "rule": "affix_limit",
                "type": "too_many_prefixes",
                "message": f"Too many prefixes: {len(prefixes)} (max {self.MAX_AFFIXES})",
            })

The Full Parse-Validate Flow

Every item paste travels the same seven-step path from raw text to a structured response. Each step has a single job and hands its output to the next.

Check Your Understanding

The Currency Operations

Every Path of Exile crafting method boils down to one of five operations. POE Crafter simulates all five. Each currency orb targets a specific rarity and performs exactly one kind of change to the mod pool.

The Weighted Lottery

Not all mods are equally likely to roll. Each mod is assigned a spawn weight — common mods have weight 1000, rare mods might have 100 or even 10. When an orb rolls, the engine draws from this weighted pool. Higher weight = higher probability.

Reading the Weighted Selection

Here is the inner loop of generate_mods() in crafting_engine.py. Each iteration fills one mod slot using the weighted random approach described above.

        for _ in range(num_mods):
            can_prefix = prefix_count < 3 and mod_type in ("all", "prefix")
            can_suffix = suffix_count < 3 and mod_type in ("all", "suffix")

            ids: List[str] = []
            weights: List[int] = []

            if can_prefix:
                p_ids, p_weights = self._select_eligible_mods(base_id, ilvl, "prefix", excluded_groups)
                ids.extend(p_ids)
                weights.extend(p_weights)
            if can_suffix:
                s_ids, s_weights = self._select_eligible_mods(base_id, ilvl, "suffix", excluded_groups)
                ids.extend(s_ids)
                weights.extend(s_weights)

            if not ids:
                break

            total_weight = sum(weights)
            probs = [w / total_weight for w in weights]
            chosen_id = str(self.rng.choice(ids, p=probs))

            mod_def = self.cache.mods[chosen_id]
            chosen_type = mod_def["mod_type"]
            result.append({"mod_id": chosen_id, "mod_type": chosen_type})
            excluded_groups.add(mod_def["mod_group"])

The Engine and the Arena

CraftingEngine and CraftingEnvironment look similar — both deal with items and crafting. But they play very different roles. The Engine is a stateless physics layer; the Environment is a stateful episode wrapper.

apply_chaos_orb: a pure function in practice

    def apply_chaos_orb(self, item_state: ItemState) -> ItemState:
        if item_state.rarity != "rare":
            raise ValueError(f"Chaos Orb requires a rare item, got '{item_state.rarity}'")

        count = self._roll_mod_count()
        new_mods = self.generate_mods(item_state.base_id, item_state.ilvl, count)
        return self._build_item(item_state, new_mods, rarity="rare")

66% Fours, 25% Fives, 8% Sixes

Before rolling which mods appear, the engine first decides how many mods to roll. This is a discrete distribution with three possible outcomes. The weights come directly from the observed Path of Exile game data.

    def _roll_mod_count(self) -> int:
        """Roll number of mods for a rare item: 4 (8/12), 5 (3/12), 6 (1/12)."""
        return int(self.rng.choice([4, 5, 6], p=[8 / 12, 3 / 12, 1 / 12]))

This matches the actual Path of Exile probability distribution, reverse-engineered by the community from game observations.

Pattern 1 — The Singleton

One Instance to Rule Them All

Imagine a city library with one central card catalog. Every librarian — no matter which desk they sit at — consults the same catalog. Nobody gets their own private copy. The DataCache is that catalog.

A singleton is a class where only ONE instance is ever created and shared by the entire application. The module-level cache = DataCache() at the bottom of loader.py is the textbook example. When the application starts, Python imports the module, runs that one line, and that single object is reused everywhere for as long as the server runs.

class DataCache:
    """
    In-memory cache for POE game data.

    Each instance holds independent state — no shared class-level mutable dicts.
    Use the module-level singleton `cache` for normal application code.
    Instantiate a fresh DataCache() in tests that need isolation.
    """

    def __init__(self) -> None:
        self.bases: Dict[str, Dict[str, Any]] = {}
        self.mods: Dict[str, Dict[str, Any]] = {}
        self._eligible_mods: Dict[str, Dict[int, List[Dict[str, Any]]]] = {}
        self._mod_weights: Dict[str, Dict[int, Dict[str, int]]] = {}
        self._initialized: bool = False
        self._engine: Optional[Engine] = None

Pattern 2 — The Strategy Pattern

Plug-In Behaviors with the Strategy Pattern

Think of a power drill with interchangeable bits. The drill (CraftingEnvironment) is the same every time. The bit (the strategy) is swappable. You can design a new bit without touching the drill at all. Python's ABC module lets you define a contract — any class that wants to be a strategy MUST implement select_action. The environment calls that method without caring which strategy it holds.

Watch how the environment and a strategy talk to each other during an episode:

Pattern 3 — The Gym Contract

Reset, Step, Done — The Universal Game Loop

CraftingEnvironment mimics the OpenAI Gym interface — a standard contract used in machine learning for training AI agents. reset() starts an episode, step() applies one action, and done is True when the target is met or time runs out. Any RL library can plug into this loop without knowing anything about Path of Exile.

    def step(self, action: CraftingAction) -> Tuple[ItemState, int, bool]:
        if self._state is None:
            raise RuntimeError("Call reset() before step()")

        self._state = self._apply(action, self._state)
        self._step_count += 1
        done = self.is_target_met() or self._step_count >= self.max_steps
        return self._state, 1, done

What Is Built and What Comes Next

The Roadmap

POE Crafter is production-ready for parsing and validation. The simulation layer has the architecture in place but needs the strategy logic filled in.

✅ Working Today

🔲 Coming Next

The Patterns You Now Know

A Language for Talking to AI

You have now seen four patterns that appear in production software everywhere. Knowing their names means you can describe exactly what you want to an AI coding assistant — instead of hoping it guesses the right structure.

These are not advanced concepts — they are the vocabulary of working software. Every codebase you encounter will use variations of these four patterns. Now you can name them.