akin

The Akinator experience, simplified. No ads, no busy UI.

Prerequisites

Tool	Required for
uv	all targets
Docker	make docker, make start
curl	make start

Quick start

make setup    # install deps + initialize both services (re-run after pulling dep changes)

make start                    # full stack: engine (Docker) + TUI
make start ARGS="es"          # same, Spanish
make start ARGS="en --debug"  # same, with debug info

Or run services separately:

# Dockerless (two terminals)
make engine     # Terminal 1 - engine on :8000
make tui        # Terminal 2 - TUI

# Docker engine + native TUI (two terminals)
make docker     # Terminal 1 - engine via Docker Compose
make tui        # Terminal 2 - TUI

Run make (no target) to see all available targets.

Once the engine is running, the interactive API docs are at http://localhost:8000.

Architecture

The project is built in phases, each adding a layer while keeping the previous one intact as a reference.

Phase 0: Proof of concept

Single main.py file - all UI and game logic in one file. Uses akinator.py.

graph LR
    poc["main.py<br/>(UI + game logic)"] --> lib["akinator.py"]

Loading

Phase 1: TUI

phase1 - the PoC is split into two separate Python packages: engine/ and tui/; TUI imports the engine directly and serves a cleaner CLI experience.

graph LR
    tui["tui/"] --import--> engine["engine/"]

Loading

Phase 2: HTTP ← current

phase2 - Engine and TUI are independent services (separate uv projects). They communicate over HTTP. Engine ships as a Docker image.

Cloudflare note: akinator.com is behind Cloudflare. The engine uses curl-cffi to impersonate Chrome's TLS fingerprint, which passes bot detection reliably in any environment including Docker. Without this, the akinator library (using cloudscraper) only solves JS challenges but leaves Python's TLS fingerprint exposed, causing 403 errors in containers.

graph LR
    tui["tui/"] --HTTP--> engine["engine/ :8000"]

Loading

Phase 3: Homebrew

TUI is packaged as a proper Python package and distributed via Homebrew. Requires converting tui/ from a flat-module layout to a real package (akin_tui/) so that non-Python assets (e.g. app.tcss) are included in the wheel.

Phase 4: Hypermedia

A web/ server is added for browser clients. The engine has no awareness of who is calling it.

graph LR
    tui["tui/"] --HTTP--> engine["engine/ :8000"]
    browser["browser"] --HTTP--> web["web/"] --HTTP--> engine

Loading

Repository layout

Path	Description
engine/	Game logic + FastAPI HTTP server (README)
tui/	Textual TUI client (README)
web/	Spring Boot hypermedia server (Phase 4, not yet implemented)
docker-compose.yml	Starts the engine service

Acknowledgements

• fiorix for the akinator.py gist that inspired this project
• Ombucha for the akinator.py library that powers the engine