poe2-agent 0.2.0

AI agent for Path of Exile 2 build analysis
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

# poe2-agent

Rust library for AI-driven Path of Exile 2 build analysis. Published on crates.io as `poe2-agent`. Provides a ReAct-style tool-calling agent that answers questions about PoB builds via headless Lua integration.

## For Agents: Start Here

1. **Load `/project`** — Understand the project structure
2. **Load `/tickets`** — Understand how to find and complete work
3. **Check `.project/backlog/`** — Find your next task

## Project Structure

```
poe2-agent/
├── CLAUDE.md              # You are here
├── .project/              # Tickets, systems, research
├── src/                   # Library crate (core modules)
├── build-agent/           # Multi-step build generator (future)
│   ├── src/               # Agent reasoning logic
│   └── docs/              # Design docs, prompts, domain knowledge
├── vendor/                # PathOfBuilding-PoE2 (gitignored)
└── .claude/skills/        # Slash command definitions
```

This is one of three sibling repos:

| Repo                | Purpose                                                 |
| ------------------- | ------------------------------------------------------- |
| `poe2-agent`        | AI agents for build analysis (this repo)                |
| `poe2-build-helper` | Web application (uses this crate as a dependency)       |
| `poe2-pob`          | Path of Building web fork (future)                      |

## Module Structure

| Module         | Purpose                                                              |
| -------------- | -------------------------------------------------------------------- |
| `agent`        | ReAct tool-calling agent loop (streams `AgentEvent` tokens/actions)  |
| `llm`          | OpenAI chat completion client (blocking and streaming)               |
| `pob_parser`   | Thread-safe PoB parser (runs `pob` on a dedicated OS thread)         |
| `pob`          | Path of Building 2 headless Lua VM integration                      |
| `query_agent`  | Single-turn build Q&A agent (legacy, superseded by `agent`)         |
| `knowledge`    | Pre-summarized game mechanics for LLM prompt context                |
| `wiki`         | PoE2 wiki data fetcher with filesystem caching                      |

## Coding Standards

- Rust 2021 edition, one concern per module
- `thiserror` for library errors, `anyhow` for application glue
- `tracing` for logging (never `println!`)
- Document public APIs
- BDD-style tests where applicable (Given/When/Then, fakes over mocks)
- `cargo test` before every commit
- **Prefer finished, production-quality solutions over intermediate "get it working" code.** Agent labour is cheap; confusion from half-done implementations is not. Write robust, scalable code as if it's the final version — proper error handling, clean interfaces, real implementations instead of stubs or TODOs.

## Key Architecture Patterns

**ReAct agent loop** (`agent.rs`): User question → LLM (with tool definitions) → tool calls or text response → execute tools via PobParser → append results → loop until final answer.

**Thread-safe PoB** (`pob_parser.rs`): mlua's Lua VM is `!Send`, so `PobParser` runs it on a dedicated OS thread and communicates via channels. Consumers get a thread-safe async interface.

**Streaming**: Agent yields `AgentEvent::Token(string)` for streamed text and `AgentEvent::ToolCall { name }` for progress indication.

## Environment

```bash
# Required
export OPENAI_API_KEY="sk-..."

# PoB2 (if not already cloned)
git clone https://github.com/PathOfBuildingCommunity/PathOfBuilding-PoE2.git vendor/PathOfBuilding-PoE2
```

## Skills Available

| Skill              | When to load                                                                    |
| ------------------ | ------------------------------------------------------------------------------- |
| `/project`         | At the start of a session, before doing any work                                |
| `/tickets`         | Before picking up, creating, or modifying tickets                               |
| `/finalize-ticket` | After completing any ticket — before moving on to the next task                 |

## Quick Reference

| Resource                | Purpose                             |
| ----------------------- | ----------------------------------- |
| `.project/backlog/`     | Pending tickets (work to do)        |
| `.project/done/`        | Completed tickets                   |
| `.project/systems/`     | Component state + improvement ideas |
| `.project/research/`    | Investigation notes                 |
| `build-agent/docs/`     | Agent design + domain knowledge     |