Python API

Install it

Use either command inside your own project. Published wheels already contain the compiled C++ extension.

pip install rubikoslav

# or, in a uv project
uv add rubikoslav

Solve normal notation

The simple API handles the cube state internally. Pass a string such as R U F2.

from rubikoslav import Rubikoslav

result = Rubikoslav().solve_scramble("R U F2")

if result.success:
    print(result.moves)
    print(result.optimal)
else:
    raise RuntimeError(result.error)

The first solve creates a local search cache. Later runs reuse it.

What happens during a solve

1. solve_scramble() builds the position with the native C++ cube.
2. Python translates that state and searches for a route.
3. The route is replayed through the C++ cube. A route that does not finish solved is rejected.
4. The result reports the moves, elapsed time, backend, and whether the shortest route was proven.

Use a raw cube state

For integrations that already track the 48 movable stickers, call the lower-level method directly.

from rubikoslav import Rubikoslav

result = Rubikoslav().solve(state)
if not result.success:
    raise RuntimeError(result.error)

state must contain 48 integers from 0 through 5, with eight of each color.

Call the local HTTP endpoint

Start the app with uv run rubikoslav --no-open. The server accepts the same data used by the browser.

import json
from urllib.request import Request, urlopen
from rubikoslav import CuboslavWrapper

history = ["R", "U"]
cube = CuboslavWrapper()
for move in history:
    cube.move(move)

body = json.dumps({
    "state": list(cube.getCube()),
    "history": history,
}).encode()

request = Request(
    "http://127.0.0.1:4173/api/solve",
    data=body,
    headers={"Content-Type": "application/json"},
)

with urlopen(request) as response:
    print(json.load(response))

state is required. history is optional, but lets the two-second web solver return a fast, C++-verified route when proving the shortest deep solution would take too long.