A high-performance REST API for Wakfu items data and equipment set optimization using Constraint Programming (OR-Tools CP-SAT).
- RESTful API with FastAPI
- Item search and filtering (pagination, multilingual support)
- Equipment set optimization endpoint
- Type and reference metadata endpoints
- Constraint Programming Solver (OR-Tools CP-SAT)
- Optimizes equipment builds in ~2 seconds across 7,651 items
- Handles complex game constraints (equipment slots, weapon compatibility)
- Flexible stat resolution (element priority: fire, water, earth, air)
- Required items support (lock specific equipment slots)
- Beam Search for generating diverse alternative builds (5-20 alternatives)
- ETL Pipeline
- Automated data ingestion from official Wakfu API
- PostgreSQL storage (8,097 items, 53k+ effects, 8 models)
- Parquet export for fast optimization (44 columns, 12 equipment categories)
- Production Ready
- Type-safe with Pydantic V2 & mypy strict mode
- Comprehensive test suite (175+ tests)
- Docker support (PostgreSQL)
- Database migrations with Alembic
- Backend: Python 3.11+, FastAPI, SQLAlchemy 2.0
- Database: PostgreSQL 15+
- Optimization: OR-Tools CP-SAT, pandas
- Data Validation: Pydantic V2, Pandera
- Dev Tools: Poetry, Ruff, mypy, pytest
- Python 3.11 or higher
- Docker & Docker Compose
- Poetry (Python dependency manager)
- Clone the repository:
git clone https://github.com/yourusername/wakfu-items-api.git
cd wakfu-items-api- Install dependencies:
poetry install- Set up environment variables:
cp .env.example .env
# Edit .env with your configuration- Start PostgreSQL:
docker-compose up -d- Run database migrations:
poetry run alembic upgrade head- Load data via ETL:
# Download latest game data
poetry run python -m wakfu_items_api.scripts.download_gamedata
# Run ETL pipeline (JSON → PostgreSQL)
poetry run wakfu-etl load
# Export to Parquet for optimization
poetry run python -m wakfu_items_api.scripts.generate_dataset- Start the API:
poetry run uvicorn wakfu_items_api.api.main:app --reloadThe API will be available at http://localhost:8000. Visit http://localhost:8000/docs for interactive API documentation.
# Get all items (paginated)
curl http://localhost:8000/api/v1/items?skip=0&limit=10
# Search items by name (multilingual)
curl "http://localhost:8000/api/v1/items/search?query=épée&language=fr"
# Get item details
curl http://localhost:8000/api/v1/items/1234Create a JSON request file (e.g., examples/fire_build.json):
{
"objectives": [
{
"stat": "MAITRISE_FEU",
"weight": 10,
"priority": 1
},
{
"stat": "PV",
"weight": 5,
"priority": 2
}
],
"element_priority": {
"mastery": ["feu", "eau", "terre", "air"],
"resistance": ["terre", "air", "feu", "eau"]
},
"constraints": [
{
"stat": "CRITIQUE_PCT",
"op": ">=",
"value": 50
}
],
"filters": {
"level_min": 200,
"level_max": 230,
"rarities": [5, 6, 7]
},
"timeout_seconds": 30
}Submit the optimization request:
curl -X POST http://localhost:8000/api/v1/optimize \
-H "Content-Type: application/json" \
-d @examples/fire_build.jsonResponse includes:
best_build: Optimal equipment set with 12 slotspareto_front: List of alternative builds (5-20 diverse options via Beam Search)stats: Performance metrics (time, items evaluated)
You can request multiple diverse alternative builds using num_alternatives and min_diversity:
{
"objectives": [...],
"element_priority": {...},
"num_alternatives": 10,
"min_diversity": 4,
"filters": {...}
}num_alternatives(default: 5, max: 20): Number of alternative builds to generatemin_diversity(default: 3, max: 12): Minimum number of different items between builds
The API uses Beam Search to iteratively find diverse high-quality builds. Each alternative differs from others by at least min_diversity equipment pieces.
You can force specific items in certain slots using required_items:
{
"objectives": [...],
"required_items": {
"Chapeau": 1234,
"Anneau_1": 5678,
"Main": 0
},
"filters": {...}
}Slot names: Chapeau, Cape, Ceinture, Bottes, Amulette, Anneau_1, Anneau_2, Bouclier, Familier, Main, Seconde main
| Method | Endpoint | Description |
|---|---|---|
GET |
/ |
Root welcome message |
GET |
/health |
Health check |
GET |
/api/v1/items |
List items (paginated) |
GET |
/api/v1/items/search |
Search items by name |
GET |
/api/v1/items/{id} |
Get item details |
POST |
/api/v1/optimize |
Optimize equipment build |
GET |
/api/v1/types |
List item types |
GET |
/api/v1/references |
Get reference metadata |
Full interactive documentation available at /docs (Swagger UI) and /redoc (ReDoc).
┌─────────────────┐
│ Wakfu API │ Official game data (JSON)
└────────┬────────┘
│
▼
┌─────────────────┐
│ ETL Pipeline │ scripts/download_gamedata.py
│ │ etl/pipeline.py
└────────┬────────┘
│
▼
┌─────────────────┐
│ PostgreSQL │ 8,097 items, 53k+ effects
│ (SQLAlchemy) │ 8 models (Item, Effect, Action, State, ...)
└────────┬────────┘
│
▼
┌─────────────────┐
│ Parquet Export │ 7,651 equippable items
│ (pandas) │ 44 columns (6 metadata + 38 combat stats)
└────────┬────────┘
│
▼
┌─────────────────┐
│ CP-SAT Solver │ Constraint Programming (OR-Tools)
│ (optimization) │ 2s solve time, 97.6% variable reduction
└────────┬────────┘
│
▼
┌─────────────────┐
│ FastAPI │ RESTful endpoints
│ (api) │ /items, /optimize, /types
└─────────────────┘
src/wakfu_items_api/
├── api/ # FastAPI application
│ ├── main.py # App entrypoint, CORS config
│ ├── routes/ # API endpoints (items, optimization, types)
│ └── dependencies.py # Dependency injection (DB, DataFrame cache)
├── models/ # SQLAlchemy ORM models (8 models)
├── schemas/ # Pydantic validation schemas
├── optimization/ # CP-SAT solver & preprocessing
│ ├── core/ # cp_solver.py (OR-Tools CP-SAT)
│ ├── preprocessing/ # Flexible stats, constraint filtering
│ ├── constraints/ # Equipment slot constraints
│ └── schemas/ # Optimization request/response
├── etl/ # ETL pipeline (JSON → PostgreSQL)
│ ├── pipeline.py # Main ETL orchestrator
│ ├── loaders/ # Data loaders per entity
│ └── cli.py # CLI commands (wakfu-etl)
├── export/ # Parquet exporters
├── scripts/ # Utility scripts (download, versioning)
├── services/ # External API clients (wakfu_api.py)
├── config/ # settings.py (environment config)
└── database/ # engine.py (SQLAlchemy setup)
# Format & lint with Ruff
poetry run ruff format src tests
poetry run ruff check src tests
# Type checking with mypy (strict mode)
poetry run mypy src tests# Run all tests with coverage
poetry run pytest
# Run specific test categories
poetry run pytest -m unit
poetry run pytest -m integration
poetry run pytest -k test_cp_solver
# Exclude slow tests
poetry run pytest -m "not slow"Test Coverage: 175+ tests across 7 categories (CP solver, preprocessing, API, ETL, models, schemas, exports)
# Create migration
poetry run alembic revision --autogenerate -m "Description"
# Apply migrations
poetry run alembic upgrade head
# Rollback migration
poetry run alembic downgrade -1
# View migration history
poetry run alembic history# Load all data
poetry run wakfu-etl load
# Load specific categories
poetry run wakfu-etl load --categories items effects
# Clean old data versions
poetry run python -m wakfu_items_api.scripts.clean_old_versions --keep 3- Official Wakfu API: Versioned in
data/{version}/raw/ - Volume: 8,263 items, 53k+ effects
- Languages: French, English, Spanish, Portuguese
- 8 SQLAlchemy models: Item, Effect, Action, State, ItemType, EquipmentItemType, ItemProperty
- Relations: Items → Types, Effects → Actions/States
- 7,651 equippable items (502 excluded: enchantments, sublimations, tools, costumes)
- 12 equipment categories: Chapeau, Cape, Bottes, Ceinture, Amulette, Anneau, Bouclier, Familier, Une main, Deux mains, Seconde main
- 44 columns: 6 metadata (id, name, level, rarity, category) + 38 combat stats (UPPERCASE_NO_ACCENTS)
- 166 items skipped during ETL: Types 219, 480, 582 (pets), 611 (mounts) exist only in EquipmentItemTypes
- 502 items excluded from Parquet: Non-combat items (enchantments, sublimations, tools, costumes)
Environment variables (.env):
# Environment
ENVIRONMENT=development
# PostgreSQL
POSTGRES_DB=wakfu_items
POSTGRES_USER=wakfu
POSTGRES_PASSWORD=your_password
POSTGRES_PORT=5432
# Database connection
DATABASE_URL=postgresql://wakfu:your_password@localhost:5432/wakfu_items
DATABASE_ECHO=false
DATABASE_POOL_SIZE=5
# API
API_DEBUG=false
PARQUET_PATH=data/processed/items_optimization.parquet- CP-SAT Solver with constraint support
- RESTful API (GET items, POST optimize)
- ETL Pipeline & Parquet export
- Beam Search (generate alternative builds) ✨ NEW
- Comprehensive documentation (this README + docs/)
- Dockerfile for API
- Authentication & authorization (JWT, API keys)
- Rate limiting & CORS configuration
- CI/CD pipeline (GitHub Actions)
- Structured logging & metrics (Prometheus)
- Health checks (DB connectivity)
- CRUD endpoints for items (POST, PUT, DELETE)
- Item synchronization with Parquet after modifications
- WebSocket support (real-time progress updates)
- Batch optimization (multiple builds simultaneously)
- Build comparison & sharing
- Export builds (JSON, CSV, image)
- Frontend UI (React/Vue)
See CLAUDE.tasks.md for detailed task breakdown.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Run tests and linting (
poetry run pytest && poetry run ruff check) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Code Standards:
- Python 3.11+ with type hints
- Ruff for formatting & linting
- mypy strict mode
- pytest for testing (minimum 80% coverage)
- Pydantic V2 for validation
This project is not affiliated with Ankama Games. Wakfu is a trademark of Ankama Games.
- OR-Tools (Google) for the CP-SAT solver
- Ankama Games for the Wakfu API
- FastAPI for the excellent web framework
Version: 0.1.0 | Last Updated: 2025-10-17