fancy-fun-lab
Python twin of laravel-fun-lab: the same gamification engine and the same fun-lab/* tables, on an in-memory store or the standard library's sqlite3 in the Laravel table layout. Zero runtime dependencies.
pip install fancy-fun-labAPI surface
Headless package — drive it from code or an agent. No component grid.
fancy-fun-lab
A headless gamification engine for Python. XP awarded to gamed metrics, levels and weighted level groups, achievements, prizes with inventory, leaderboards (all-time, daily, weekly, monthly and per metric) and an event log with analytics, with zero runtime dependencies.
The Python twin of particle-academy/laravel-fun-lab
(PHP), with @particle-academy/fancy-fun-lab (Node) beside it.
All three run the same fun-lab/* conformance tables from
fancy-conformance in
their own CI, so the same awards give the same levels, boards and log in every
runtime, and @particle-academy/fancy-fun-lab-ui
renders the same JSON whichever backend produced it.
For agents. Every Fancy package, this one included, is listed on the Fancy MCP catalog server at
https://ui.particle.academy/mcp(streamable HTTP, no API key; MCP idfancy-ui), with install commands and docs. How an agent installs and uses this package is in AGENTS.md.
What it does
- XP to gamed metrics ("combat", "crafting", "coins"), with a per-action cap and validation hooks.
- Levels per metric, and level groups that weigh several metrics together. A level is claimed exactly once, even under concurrent awards.
- Achievements, granted by hand or automatically when a level is reached, and prizes with inventory and a claim / fulfil lifecycle.
- Leaderboards all-time, daily, weekly or monthly (on the XP earned in the period), per metric, by awardable type, paged.
- An event log of every award, grant and catalog change, with analytics: counts, totals, active users, completion rates, time series, breakdowns.
- Opt-out, honoured everywhere.
- Stores: in-memory, or SQLite on the standard library using laravel-fun-lab's own tables, so it can share a database with a Laravel app.
Example
from fancy_fun_lab import FunLab, Subject
lab = FunLab()
lab.setup("gamed-metric", {"slug": "combat"})
lab.setup("metric-level", {"metric": "combat", "level": 2, "xp": 100})
ada = Subject("user", 1)
lab.award("combat").to(ada).amount(150).save()
lab.level_info(ada, "combat")["current_level"] # 2
Status
pip install fancy-fun-lab
License
MIT

