Metadata-Version: 2.4
Name: okey-solver-py
Version: 0.3.0
Summary: Python port of okey-solver-ts and okey-vision-ts
License-File: LICENSE
Author: Ata Can Yaymacı
Author-email: atacanymc@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: vision
Requires-Dist: numpy (>=1.20,<3.0) ; extra == "vision"
Requires-Dist: opencv-python (>=4.0,<5.0) ; extra == "vision"
Requires-Dist: pillow (>=10,<13) ; extra == "vision"
Requires-Dist: pydantic (>=2.0,<3.0)
Requires-Dist: requests (>=2.31,<3.0) ; extra == "vision"
Requires-Dist: ultralytics (>=8.0,<9.0) ; extra == "vision"
Description-Content-Type: text/markdown

<div align="center">
  <img src=".github/screenshots/okey-solver-logo.png" alt="Okey Solver Py Logo" width="200" />
  <h1>okey-solver-py</h1>
  <p>Python library for solving Okey & Rummikub tile arrangements and processing board layouts.</p>

  [![PyPI version](https://img.shields.io/pypi/v/okey-solver-py.svg)](https://pypi.org/project/okey-solver-py/)
  [![tests](https://img.shields.io/badge/tests-11%2F11%20passing-brightgreen)](./tests)
  [![Python support](https://img.shields.io/badge/Python-3.10+-blue.svg)](#-requirements)
  [![License](https://img.shields.io/badge/License-Apache%202.0-yellow.svg)](./LICENSE)
</div>

---

## Features
- **Backtracking Solver**: Optimal arrangement solver for Okey / Rummikub games.
- **Pairs/Double Play**: Find identical pairs.
- **Extensible Vision Engine**: Process frames natively with numpy arrays (OpenCV), PIL, base64 strings, bytes, and paths.
- **Provider Support**: Native local YOLO (`ultralytics`) and cloud Roboflow API implementations.

---

## Installation
```bash
pip install okey-solver-py
```

---

## Quick Start

### Basic Solver Arrangement
```python
from okey_solver import SolverEngine, Tile, TileColor

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 = SolverEngine.findBestArrangement(tiles)
print(result.totalScore)
```

### With Roboflow Provider
```python
from okey_vision import RoboflowProvider, VisionSolverEngine

provider = RoboflowProvider(
    api_key="your_api_key",
    model_id="rummikub-5bldr",
    model_version=1
)

engine = VisionSolverEngine(provider)
result = engine.analyze_frame("image_path.jpg")
print(result["tiles"])
print(result["arrangement"])
```

### With Local YOLO Model
```python
from okey_vision import LocalYoloProvider, VisionSolverEngine

provider = LocalYoloProvider(
    model_path="./models/yolov8_best.pt"
)

engine = VisionSolverEngine(provider)
result = engine.analyze_frame("board_layout.jpg")
print(result["arrangement"])
```

---

## Extended Documentation

For details on architecture, rules, and APIs:
- 🏗 **[Architecture & Flow](docs/ARCHITECTURE.md)** - Details on pipeline stages, frame adapters, and observers.
- 📜 **[Game Rules Reference](docs/ALGORITHM_RULES.md)** - Okey rules, 12-13-1 circular runs, joker and false okey logic.
- 💻 **[CLI Usage Guide](docs/CLI_USAGE.md)** - Guide to running `okey-solve` and `okey-vision` terminal applications.
- 🤖 **[Telegram Bot Demo](demo/telegram/bot.py)** - Telegram Bot server example integrating image detection and layout solving.

