# Sudoku Engine: Generator, Solver & Tutor (`komeil_mehranfar/sudoku-engine`) Actor

The go-to Sudoku engine: generate unique puzzles (L1-L10), solve with human techniques, get step-by-step hints, analysis, and teaching traces. Built for apps, games, printables, and learning products.

- **URL**: https://apify.com/komeil_mehranfar/sudoku-engine.md
- **Developed by:** [Komeil Mehranfar](https://apify.com/komeil_mehranfar) (community)
- **Categories:** AI, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 66.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $8.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Sudoku Engine: Generate, Solve & Teach with Human Logic

The **go-to Sudoku engine** for apps, games, printables, and learning products. Generate **unique** puzzles with real difficulty bands, then solve them the way a strong human would, with named techniques, not blind computer search.

**Keywords people search for:** Sudoku generator · Sudoku solver · Sudoku API · puzzle difficulty · step-by-step Sudoku · Sudoku hints · Sudoku techniques (X-Wing, naked pairs, …)

***

### What you can do

- **Generate Sudoku puzzles** at precise difficulties (**L1–L10**, easy → extreme)
- **Batch-generate** many unique grids with optional seeds (reproducible)
- **Solve Sudoku** using human tactics, with **summary** or **detailed** step traces
- **Hint** the next move, **analyze** difficulty, **validate** boards
- **Teach** step-by-step with candidates and technique payloads

***

### Why this Sudoku engine

Most tools either spit out a random grid or dump a machine solution. This engine:

| You need | You get |
| --- | --- |
| Fair printables / games | Puzzles graded to a real band (L1–L10) |
| Learning & tutoring UX | Named strategies + cause→effect steps |
| Stable integrations | 81-char boards, seeds, analysis JSON |

Unique solutions, human-logic paths, and technique metadata, built to be the default Sudoku backend you plug into anything.

***

### Difficulty bands (L1–L10)

| Band | Level | Typical techniques |
| --- | --- | --- |
| **L1** | Easy | Open singles |
| **L2–L3** | Easy / Medium | Singles, simple locked candidates |
| **L4–L6** | Medium / Hard | Pairs, pointing, box-line |
| **L7–L8** | Hard / Expert | Wings, early chains |
| **L9–L10** | Extreme | Advanced & rare tactics |

Start with **L1–L3** while testing; raise `timeoutMs` (30–60s) for harder bands.

***

### Operations

Set `operation` once per run. Results go to the **dataset** and key-value **OUTPUT**.

#### Sudoku generator

| Operation | Input | Output |
| --- | --- | --- |
| `generate` | `difficulty`, optional `seed`, `timeoutMs` | `puzzle`, `solution`, `analysis` |
| `batchGenerate` | same + `count` (1–50) | one dataset row **per** puzzle |

```json
{
  "operation": "generate",
  "difficulty": "L3",
  "seed": 42,
  "timeoutMs": 30000
}
```

#### Sudoku solver & helpers

Boards are **81 characters**, row-major, digits `1–9`, empty = `0`.

| Operation | Returns |
| --- | --- |
| `solve` | Solved grid + analysis |
| `solveSummary` | Compact human-logic steps |
| `solveDetailed` | Detailed cause → effect traces |
| `analyze` | Uniqueness, difficulty, hardest technique, score |
| `hint` | Next human step (no full solve) |
| `validate` | Rule / structure checks |
| `teach` | Teaching payload (board, candidates, step) |
| `candidates` | Pencil marks for every cell |

```json
{
  "operation": "solveSummary",
  "board": "530070000600195000098000060800060003400803001700020006060000280000419005000080079"
}
```

***

### Input reference

| Field | Required | Notes |
| --- | --- | --- |
| `operation` | ✅ | See list above |
| `difficulty` | generate\* | `L1`…`L10` (default `L3`) |
| `board` | solve\* / analyze / … | 81-char string |
| `seed` | optional | Reproducible generation |
| `count` | optional | Batch (1–50) |
| `timeoutMs` | optional | Default `30000` |

***

### Output

1. **Dataset**: one item per result (batch expands to N rows)
2. **Key-value `OUTPUT`**: full JSON payload

Console views: **Overview** · **Analysis** · **Solve steps**

```json
{
  "puzzle": "054063009962010730…",
  "solution": "854763129962418735…",
  "analysis": {
    "hasSolution": true,
    "hasUniqueSolution": true,
    "difficulty": "L3",
    "hardestTechnique": "…",
    "score": 12.4
  },
  "seed": 42
}
```

Errors look like `{ "error": { "code": "bad_request", "message": "…" } }`\
(`bad_request`, `unsolvable`, `timeout`, `internal`, …).

***

### How to run

**Console:** Start → choose `operation` → open Dataset / OUTPUT.

**API:**

```bash
curl "https://api.apify.com/v2/acts/komeil_mehranfar~sudoku-engine/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"operation":"generate","difficulty":"L1","seed":1}'
```

```js
import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client
  .actor("komeil_mehranfar/sudoku-engine")
  .call({ operation: "generate", difficulty: "L3", seed: 42 });

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]);
```

***

### Pricing (pay-per-event)

| Event | Free / Starter | Scale | Business |
| --- | --- | --- | --- |
| Actor start | **$0.001** / GB | **$0.001** / GB | **$0.001** / GB |
| Result *(primary)* | **$20** / 1,000 | **$12** / 1,000 | **$8** / 1,000 |

One puzzle on Starter ≈ **$0.021**. Scale and Business cut the per-result rate. Set a max charge per run if you want a ceiling (suggested min **$0.05**).

***

### Performance

- **L1–L3**: usually a few seconds
- **L7–L10**: increase `timeoutMs`
- Batch size multiplies result charges 1:1 with puzzles written

***

### Support

Questions or feature requests: use the **Issues** / contact options on this Actor’s Apify Store page.

# Actor input Schema

## `operation` (type: `string`):

generate / batchGenerate need difficulty. solve\* / analyze / hint / validate / teach / candidates need board.

## `difficulty` (type: `string`):

Engine band L1 (open singles) → L10 (extreme). Used by generate and batchGenerate.

## `board` (type: `string`):

81-digit row-major string. Use 0 for empty cells. Required for solve, analyze, hint, validate, teach, candidates.

## `seed` (type: `integer`):

Optional RNG seed for reproducible generate / batchGenerate.

## `count` (type: `integer`):

How many puzzles batchGenerate should produce.

## `timeoutMs` (type: `integer`):

Soft timeout for generate-family operations. Harder bands need more time.

## Actor input object example

```json
{
  "operation": "generate",
  "difficulty": "L3",
  "board": "530070000600195000098000060800060003400803001700020006060000280000419005000080079",
  "count": 1,
  "timeoutMs": 30000
}
```

# Actor output Schema

## `results` (type: `string`):

Default dataset: one row per generated puzzle or solve/hint/teach result. Switch views in Console for Overview / Analysis / Solve steps.

## `fullOutput` (type: `string`):

Complete operation payload (including nested batch/example wrappers) stored as key OUTPUT.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "operation": "generate",
    "difficulty": "L3",
    "board": "530070000600195000098000060800060003400803001700020006060000280000419005000080079",
    "count": 1,
    "timeoutMs": 30000
};

// Run the Actor and wait for it to finish
const run = await client.actor("komeil_mehranfar/sudoku-engine").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "operation": "generate",
    "difficulty": "L3",
    "board": "530070000600195000098000060800060003400803001700020006060000280000419005000080079",
    "count": 1,
    "timeoutMs": 30000,
}

# Run the Actor and wait for it to finish
run = client.actor("komeil_mehranfar/sudoku-engine").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "operation": "generate",
  "difficulty": "L3",
  "board": "530070000600195000098000060800060003400803001700020006060000280000419005000080079",
  "count": 1,
  "timeoutMs": 30000
}' |
apify call komeil_mehranfar/sudoku-engine --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,komeil_mehranfar/sudoku-engine"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/QZHKg4FkCAAEtHdfA/builds/PApMF219KxYJoiyg3/openapi.json