Okey Solver

An enterprise-ready Python library for solving Okey & Rummikub board states, arranging hands, and processing layouts with computer vision pipelines.

🏗 Modular Package Architecture

The codebase is split into fully decoupled, high-performance packages under the src/ directory:

1. okey_core: Holds shared domain types (Tile, Meld, Arrangement, OrchestratorResult) and exceptions. Completely independent.
2. 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.
3. 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 injectable LabelParserStrategy.
4. okey_orchestrator: Orchestrates pipelines by feeding vision outputs into the mathematical solver. Supports passing custom SolverEngine instances or any of the 8 strategy strings during setup.
5. okey_server: A microservice framework delivering endpoints for vision processing and hand arrangement.

📦 Installation

To install the core mathematical solver:

pip install okey-solver-py

To 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]

💻 CLI Commands

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.

🚀 Quick Start

1. Basic Solver Arrangement

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}")

2. End-to-End Orchestration (Vision + Solver with Strategy Selection)

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)

🌐 FastAPI Microservice (API Server)

Deploy this package directly to cloud infrastructure to process requests via HTTP:

Start the Microservice

# Set environment variables for Roboflow Workflow
export OKEY_RF_KEY="your_api_key"

# Start the uvicorn instance on port 8000
okey-serve --port 8000

Endpoints

• POST /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.

📊 Capability Matrix

🗺 System Flow & Architecture

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

📖 Extended Documentation

• 🧮 Solver Engines Guide - General mathematical formulations, performance comparison matrix, and links to detailed guides:
  • Greedy Solver Guide
  • Backtracking Solver Guide
  • ILP Solver Guide
  • Hybrid Solver Guide
  • Beam Search Solver Guide
  • Genetic Algorithm Solver Guide
  • Simulated Annealing Solver Guide
  • MCTS Solver Guide
• 🏗 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.