An enterprise-ready Python library for solving Okey & Rummikub board states, arranging hands, and processing layouts with computer vision pipelines.
The codebase is split into fully decoupled, high-performance packages under the src/ directory:
okey_core: Holds shared domain types (Tile,Meld,Arrangement,OrchestratorResult) and exceptions. Completely independent.okey_solver: Stateless mathematical engines to calculate optimal run/group melds and identical pairs. Supports 8 solver strategies (Backtracking, Greedy, ILP, Hybrid, Beam Search, Genetic Algorithm, Simulated Annealing, and MCTS) and uses slot-based DTO mapping (LightTile,LightMeld) to bypass Pydantic model loop overhead.okey_vision: Translates frames (numpy, PIL, bytes, base64) into tile predictions. Queries the cloud Roboflow Workflow API (including the pretrained Okey-Rummikub Model on Roboflow Universe trained on the Okey-Data Kaggle Dataset) to detect layouts. Decoupled from solver logic via an injectableLabelParserStrategy.okey_orchestrator: Orchestrates pipelines by feeding vision outputs into the mathematical solver. Supports passing customSolverEngineinstances or any of the 8 strategy strings during setup.okey_server: A microservice framework delivering endpoints for vision processing and hand arrangement.
To install the core mathematical solver:
pip install okey-solver-pyTo install computer vision extras:
pip install okey-solver-py[vision]To install FastAPI server extras:
pip install okey-solver-py[server]To install everything for development:
pip install okey-solver-py[vision,server]The package exposes the following CLI commands:
okey-solve: Solves hand arrangements from lists of tile arguments.okey-vision: Runs object detection predictions on an image layout using Roboflow workflows.okey-serve: Launches the FastAPI REST microservice API.okey-demo: Launches the local terminal solver demo application.
from okey_solver import create_standard_okey_solver, Tile, TileColor
# Instantiates a stateless, independent engine
solver = create_standard_okey_solver(strategy="backtracking")
tiles = [
Tile(id="r5", color=TileColor.RED, value=5),
Tile(id="r6", color=TileColor.RED, value=6),
Tile(id="r7", color=TileColor.RED, value=7),
]
result = solver.find_best_arrangement(tiles)
print(f"Total Score: {result.totalScore}")from okey_vision import RoboflowWorkflowProvider
from okey_orchestrator import VisionSolverEngine
# 1. Initialize vision model provider
provider = RoboflowWorkflowProvider(api_key="YOUR_ROBOFLOW_API_KEY")
# 2. Bind pipeline inside the orchestrator with strategy selection
# Supports strategies: "backtracking", "greedy", "ilp", "hybrid", "beam", "genetic", "annealing", "mcts"
engine = VisionSolverEngine(pipeline=provider, strategy="greedy")
# 3. Analyze layout image and solve
result = engine.analyze_frame("board_layout.jpg")
print("Detected Tiles:", result.tiles)
print("Optimal Score:", result.arrangement.totalScore)Deploy this package directly to cloud infrastructure to process requests via HTTP:
# Set environment variables for Roboflow Workflow
export OKEY_RF_KEY="your_api_key"
# Start the uvicorn instance on port 8000
okey-serve --port 8000POST /solver/arrange: Accepts a JSON list of tile parameters and returns arranged melds.POST /vision/solve: Accepts an uploaded board image, detects the layout via Roboflow Workflows, and returns solved arrangements.POST /vision/extract: Accepts an uploaded board image, detects and returns the list of Okey tiles.- Interactive Swagger Docs: Visit http://localhost:8000/docs to test requests in the browser.
| Feature | Package | Mode | Capabilities |
|---|---|---|---|
| State Resolution | okey_solver |
Sync | Stateless backtracking, greedy, ILP, hybrid, beam search, genetic algorithm, simulated annealing, and MCTS hand-arranging meld solvers. Supports circular run checks and Joker resolutions. |
| Layout Detection | okey_vision |
Async / Sync | Multi-stage Roboflow Workflows querying, OCR labeling, confidence filters, and custom label mapping. |
| E2E Orchestration | okey_orchestrator |
Async / Sync | Feeds images directly into okey_vision and pipes outcomes into okey_solver dynamically. |
| FastAPI Microservice | okey_server |
Async | API exposing /vision/solve and /vision/extract with size (10MB) & MIME checks, instance registry caching, and safe error handling. |
graph TD
Client[Client / Caller] -->|1. HTTP Upload| Server[okey_server: API App]
Server -->|2. validate_image_file| SizeCheck{MIME & 10MB Check}
SizeCheck -->|Valid Image Bytes| DI[Depends: get_roboflow_workflow_provider]
DI -->|3. Registry Cached Provider| Router[solve_vision Router]
subgraph Vision Orchestration
Router -->|4. analyze_frame_async| Orch[okey_orchestrator: VisionSolverEngine]
Orch -->|5. detect_async| Providers[okey_vision: RoboflowWorkflowProvider]
Providers -->|6. run_workflow| CloudAPI((Roboflow Workflow API))
CloudAPI -->|7. Predictions JSON| Providers
Providers -->|8. parse_tile| Parser[FuzzyLabelParser]
end
subgraph Mathematical Solver
Parser -->|9. find_best_arrangement| Solver[okey_solver: SolverEngine]
Solver -->|10. Meld Arrangements| Orch
end
Orch -->|11. OrchestratorResult| Router
Router -->|12. JSON Response| Client
- 🧮 Solver Engines Guide - General mathematical formulations, performance comparison matrix, and links to detailed guides:
- 🏗 Architecture & Flow Reference - Visual flow pipelines, observers, and providers.
- 📜 Game Rules Reference - Explanations of run configurations, circular sequences, and Joker/False Okey rules.
- 💻 CLI Usage Guide - Terminal parameters for running predictions and solvers.
- 🤝 Contributing Guide - Guidelines for configuring local poetry environments and running Ruff/Mypy checks.