Diviner

A fast CLI tool written in Rust that generates minimal regex patterns for Path of Exile items. Given a list of target items (e.g., specific divination cards), diviner generates a PoE regex filter that matches exactly those items and no others.

Features

• Smart Pattern Generation: Automatically finds the shortest unique substring patterns
• Description Text Search: Searches both item names and flavor text for unique patterns
• Fast Performance: Built in Rust for speed
• Caching: API responses cached locally (24h default) to avoid hammering poe.ninja
• Multiple Item Types: Support for divination cards, scarabs, essences, and more
• Error Handling: Graceful handling of typos and network errors

Installation

Build from Source

cargo build --release

The binary will be at target/release/diviner.

Usage

Basic Usage

# Generate regex for specific divination cards
diviner -t div -i "The Doctor,The Nurse,The Apothecary"

# Using full flag names
diviner --item-type div --items "House of Mirrors,Seven Years Bad Luck"

List Available Item Types

diviner --list-types

Output:

Supported item types:
  div → DivinationCard
  scarab → Scarab
  essence → Essence
  fossil → Fossil
  (and more...)

Read Items from File

Create a file with one item per line:

# items.txt
The Doctor
The Nurse
House of Mirrors

Then run:

diviner -t div -f items.txt

Force Cache Refresh

diviner -t div -i "The Doctor" --refresh

Specify League

diviner -t div -i "The Doctor" --league Settlers

Command-Line Options

Flag	Long Form	Description	Default
-t	--item-type	Item type (div, scarab, etc.)	required
-i	--items	Comma-separated list of items	-
-f	--file	Read items from file	-
-l	--league	PoE league name	Standard
-r	--refresh	Force cache refresh	false
	--list-types	List all item types	-
	--cache-dir	Custom cache directory	~/.cache/diviner
	--cache-duration	Cache expiry in hours	24
-h	--help	Show help	-
-V	--version	Show version	-

Fuzzy Matching

Diviner supports intelligent fuzzy matching for item names:

• Case-insensitive: Automatically handles uppercase/lowercase
• Partial names: "doctor" matches "The Doctor", "apoth" matches "The Apothecary"
• Typo correction: "doctorr" matches "The Doctor" using Levenshtein distance
• Word matching: Matches items by individual words
• Ambiguity detection: Warns when multiple items match with similar confidence

When fuzzy matching is used, the tool will show you what was matched and the confidence score.

Examples

Example 1: High-Value Divination Cards

$ diviner -t div -i "The Doctor,The Apothecary,House of Mirrors" -l Standard

✓ Loaded 453 items from cache

Found 3 of 3 items:
  ✓ The Doctor
  ✓ The Apothecary
  ✓ House of Mirrors

Generated regex:
doc " ap" hou

Copy this into your Path of Exile item filter.

Example 2: Fuzzy Matching (Partial Names)

$ diviner -t div -i "doctor,nurse,apoth" -l Standard

✓ Loaded 453 items from cache

📝 Fuzzy matched 3 item(s):
  'doctor' → 'The Doctor' (score: 92, substring match)
  'nurse' → 'The Nurse' (score: 91, substring match)
  'apoth' → 'The Apothecary' (score: 87, substring match)

✓ Found 3 of 3 items:
  The Doctor
  The Nurse
  The Apothecary

Generated regex:
"(doc|nur| apo)"

Copy this into your Path of Exile item filter.

Example 3: Typo Correction

$ diviner -t div -i "doctorr" -l Standard

✓ Loaded 453 items from cache

📝 Fuzzy matched 1 item(s):
  'doctorr' → 'The Doctor' (score: 80, word match)

✓ Found 1 of 1 items:
  The Doctor

Generated regex:
xam

Copy this into your Path of Exile item filter.

Example 4: Ambiguous Matches

$ diviner -t div -i "the" -l Standard

✓ Loaded 453 items from cache

⚠ Ambiguous match for 'the'. Did you mean one of these?
  1. The Fox (score: 88, substring match)
  2. The Sun (score: 88, substring match)
  3. The Web (score: 88, substring match)
  4. The Body (score: 87, substring match)
  5. The Deal (score: 87, substring match)

✗ 1 item(s) not found:
  the

Error: None of the requested items were found

How It Works

1. Fetch Item Data: Downloads item list from poe.ninja API (or uses cache), including:
   • Item name
   • Flavor text (description)
   • Explicit modifiers (e.g., divination card rewards)
   • Implicit modifiers
2. Find Unique Patterns: For each target item, finds the shortest substring that:
   • Appears in the target item's searchable text (name + description + modifiers)
   • Does NOT appear in any non-target items' searchable text
3. Format Output: Combines patterns using PoE regex syntax:
   • Single item: Returns pattern as-is (e.g., xam)
   • Multiple items: Returns "(pattern1|pattern2|pattern3)" format
   • Deduplicates identical patterns
   • Escapes special characters

Path of Exile Regex Format

The generated regex uses PoE's built-in search syntax:

• Single pattern: pattern (e.g., xam)
• Multiple patterns: "(pattern1|pattern2|pattern3)" for OR logic
• Case-insensitive matching by default in PoE
• The tool searches across item name, description, and modifiers (like div card rewards)

Example: "(doc| apo)" matches items containing "doc" OR " apo"

Cache Location

By default, cache files are stored in:

• Linux/macOS: ~/.cache/diviner/
• Windows: %LOCALAPPDATA%\diviner\

Cache files are named: {league}_{itemtype}.json

Phase 1 (MVP) - Current Implementation

✅ Basic CLI with flags ✅ poe.ninja API fetching ✅ Simple caching with expiry ✅ Regex generation (brute force substring search) ✅ Support for divination cards and all item types ✅ Error handling and validation

Future Enhancements

• Fuzzy matching for typos
• Pattern optimization (merge similar patterns)
• Interactive mode with fuzzy search
• Validate regex against known items
• Export to filter file format

Dependencies

• reqwest - HTTP client for API calls
• clap - CLI argument parsing
• serde / serde_json - JSON serialization
• chrono - Date/time handling
• dirs - Cross-platform directory paths
• anyhow / thiserror - Error handling
• shellexpand - Path expansion

License

MIT

Contributing

Contributions welcome! Please ensure:

• Code passes cargo test
• Code passes cargo clippy
• Follow existing code style