solvor 0.3.2__tar.gz → 0.3.4__tar.gz

solvor-0.3.4/.github/workflows/ci.yml

@@ -0,0 +1,209 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run linter
+        run: uv run ruff check solvor/
+
+  # Detect which solvers have changed
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      simplex: ${{ steps.filter.outputs.simplex }}
+      milp: ${{ steps.filter.outputs.milp }}
+      anneal: ${{ steps.filter.outputs.anneal }}
+      tabu: ${{ steps.filter.outputs.tabu }}
+      sat: ${{ steps.filter.outputs.sat }}
+      cp: ${{ steps.filter.outputs.cp }}
+      bayesian: ${{ steps.filter.outputs.bayesian }}
+      genetic: ${{ steps.filter.outputs.genetic }}
+      flow: ${{ steps.filter.outputs.flow }}
+      gradient: ${{ steps.filter.outputs.gradient }}
+      dlx: ${{ steps.filter.outputs.dlx }}
+      types: ${{ steps.filter.outputs.types }}
+      tests: ${{ steps.filter.outputs.tests }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            simplex:
+              - 'solvor/simplex.py'
+              - 'tests/test_simplex.py'
+            milp:
+              - 'solvor/milp.py'
+              - 'solvor/simplex.py'
+              - 'tests/test_milp.py'
+            anneal:
+              - 'solvor/anneal.py'
+              - 'tests/test_anneal.py'
+            tabu:
+              - 'solvor/tabu.py'
+              - 'tests/test_tabu.py'
+            sat:
+              - 'solvor/sat.py'
+              - 'tests/test_sat.py'
+            cp:
+              - 'solvor/cp.py'
+              - 'solvor/sat.py'
+              - 'tests/test_cp.py'
+            bayesian:
+              - 'solvor/bayesian.py'
+              - 'tests/test_bayesian.py'
+            genetic:
+              - 'solvor/genetic.py'
+              - 'tests/test_genetic.py'
+            flow:
+              - 'solvor/flow.py'
+              - 'tests/test_flow.py'
+            gradient:
+              - 'solvor/gradient.py'
+              - 'tests/test_gradient.py'
+            dlx:
+              - 'solvor/dlx.py'
+              - 'tests/test_dlx.py'
+            types:
+              - 'solvor/types.py'
+              - 'solvor/__init__.py'
+            tests:
+              - 'tests/**'
+              - 'pyproject.toml'
+
+  # Run tests for changed solvers only
+  test-simplex:
+    needs: changes
+    if: ${{ needs.changes.outputs.simplex == 'true' || needs.changes.outputs.types == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/test_simplex.py -v
+
+  test-milp:
+    needs: changes
+    if: ${{ needs.changes.outputs.milp == 'true' || needs.changes.outputs.types == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/test_milp.py -v
+
+  test-anneal:
+    needs: changes
+    if: ${{ needs.changes.outputs.anneal == 'true' || needs.changes.outputs.types == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/test_anneal.py -v
+
+  test-tabu:
+    needs: changes
+    if: ${{ needs.changes.outputs.tabu == 'true' || needs.changes.outputs.types == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/test_tabu.py -v
+
+  test-sat:
+    needs: changes
+    if: ${{ needs.changes.outputs.sat == 'true' || needs.changes.outputs.types == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/test_sat.py -v
+
+  test-cp:
+    needs: changes
+    if: ${{ needs.changes.outputs.cp == 'true' || needs.changes.outputs.types == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/test_cp.py -v
+
+  test-bayesian:
+    needs: changes
+    if: ${{ needs.changes.outputs.bayesian == 'true' || needs.changes.outputs.types == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/test_bayesian.py -v
+
+  test-genetic:
+    needs: changes
+    if: ${{ needs.changes.outputs.genetic == 'true' || needs.changes.outputs.types == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/test_genetic.py -v
+
+  test-flow:
+    needs: changes
+    if: ${{ needs.changes.outputs.flow == 'true' || needs.changes.outputs.types == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/test_flow.py -v
+
+  test-gradient:
+    needs: changes
+    if: ${{ needs.changes.outputs.gradient == 'true' || needs.changes.outputs.types == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/test_gradient.py -v
+
+  test-dlx:
+    needs: changes
+    if: ${{ needs.changes.outputs.dlx == 'true' || needs.changes.outputs.types == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/test_dlx.py -v
+
+  # Full test suite on main branch or when test infrastructure changes
+  test-all:
+    needs: changes
+    if: ${{ github.ref == 'refs/heads/main' || needs.changes.outputs.tests == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/ -v

{solvor-0.3.2 → solvor-0.3.4}/CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to Solvor
+# Contributing to solvOR
 
-Thanks for your interest in contributing to Solvor!
+Thanks for your interest in contributing to solvor!
 
 ## Development Setup
 
@@ -16,7 +16,7 @@ uv sync --extra dev
 uv run pytest
 
 # Run linter
-uv run ruff check src/
+uv run ruff check solvor/
 ```
 
 ## Code Style
@@ -33,7 +33,7 @@ Follow the project's style:
 
 ## Terminology
 
-Use consistent naming across all solvers:
+Use consistent naming across all solvors:
 
 | Term | Usage |
 |------|-------|
@@ -44,26 +44,35 @@ Use consistent naming across all solvers:
 | `neighbors` | Adjacent solutions (metaheuristics) |
 | `minimize` | Boolean flag (default `True`) |
 
-## Adding a New Solver
+## Adding a New Solvor
 
-1. Create `src/solvor/<solver_name>.py`
+1. Create `solvor/<solver_name>.py`
 2. Import shared types: `from solvor.types import Status, Result`
 3. Export `Status`, `Result`, and main solver function in `__all__`
-4. Add exports to `src/solvor/__init__.py`
-5. Add tests to `tests/test_solvers.py`
+4. Add exports to `solvor/__init__.py`
+5. Create `tests/test_<solver_name>.py` with comprehensive tests
 6. Update `README.md` with usage examples
+7. Add the solver to `.github/workflows/ci.yml` path filters
 
 ## Testing
 
-All solvers must have tests covering:
+Each solver has its own test file (`tests/test_<solver_name>.py`). Tests should cover:
 - Basic functionality
-- Edge cases (empty input, infeasible, etc.)
+- Edge cases (empty input, infeasible, single variable, etc.)
 - Minimize and maximize modes
+- Parameter variations
+- Stress tests with larger inputs
 
 ```bash
+# Run all tests
 uv run pytest tests/ -v
+
+# Run tests for a specific solver
+uv run pytest tests/test_simplex.py -v
 ```
 
+The CI runs tests selectively based on which files changed - only the affected solver's tests run.
+
 ## Pull Requests
 
 1. Fork the repo
@@ -77,4 +86,4 @@ uv run pytest tests/ -v
 1. Usable > perfect
 2. Readable > clever
 3. Simple > general
-4. Fast, but understandable
+4. Fast, but understandable

{solvor-0.3.2 → solvor-0.3.4}/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright [2025] [S.T. Grond]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

{solvor-0.3.2 → solvor-0.3.4}/PKG-INFO

@@ -1,24 +1,25 @@
 Metadata-Version: 2.4
 Name: solvor
-Version: 0.3.2
+Version: 0.3.4
 Summary: Solvor your optimization needs.
 Project-URL: Repository, https://github.com/StevenBtw/solvor
+Project-URL: PyPI, https://pypi.org/project/solvor
 Author: Steven Bytheway
-License: MIT
+License: Apache-2.0
 License-File: LICENSE
 Keywords: linear-programming,metaheuristics,operations-research,optimization,sat,solver
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Requires-Python: >=3.14
 Provides-Extra: dev
 Requires-Dist: pytest>=9.0.2; extra == 'dev'
-Requires-Dist: ruff>=0.14.9; extra == 'dev'
+Requires-Dist: ruff>=0.14.10; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# Solvor
+# solvOR
 
 ![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) 
@@ -27,15 +28,16 @@ Solvor your optimization needs..
 
 ## What's in the box?
 
-| Category | Solvers | Use Case |
+| Category | Solvors | Use Case |
 |----------|---------|----------|
 | **Linear/Integer** | `solve_lp`, `solve_milp` | Resource allocation, scheduling |
-| **Constraint** | `solve_sat`, `Model` | Sudoku, configuration, puzzles |
+| **Constraint** | `solve_sat` | Sudoku, configuration, puzzles |
 | **Local Search** | `anneal`, `tabu_search` | TSP, combinatorial optimization |
 | **Population** | `evolve` | When you want nature to do the work |
 | **Continuous** | `gradient_descent`, `momentum`, `adam` | ML, curve fitting |
 | **Black-box** | `bayesian_opt` | Hyperparameter tuning, expensive functions |
 | **Graph** | `max_flow`, `min_cost_flow`, `solve_assignment` | Matching, transportation |
+| **Exact Cover** | `solve_exact_cover` | Sudoku, N-Queens, tiling puzzles |
 
 ---
 
@@ -69,13 +71,13 @@ print(result.solution)  # {'x': 3, 'y': 7}
 
 ---
 
-## Solvers
+## Solvors
 
 <details>
 <summary><strong>Linear & Integer Programming</strong></summary>
 
 ### solve_lp
-Two-phase simplex for linear programming.
+For resource allocation, blending, production planning. Finds the exact optimum for linear objectives with linear constraints.
 
 ```python
 # minimize 2x + 3y subject to x + y >= 4, x <= 3
@@ -87,7 +89,7 @@ result = solve_lp(
 ```
 
 ### solve_milp
-Branch and bound for mixed-integer problems.
+When some variables must be integers. Diet problems, scheduling with discrete slots, set covering.
 
 ```python
 # same as above, but x must be integer
@@ -100,7 +102,7 @@ result = solve_milp(c=[2, 3], A=[[-1, -1], [1, 0]], b=[-4, 3], integers=[0])
 <summary><strong>Constraint Programming</strong></summary>
 
 ### solve_sat
-DPLL with unit propagation and clause learning.
+For "is this configuration valid?" problems. Dependencies, exclusions, implications - anything that boils down to boolean constraints.
 
 ```python
 # (x1 OR x2) AND (NOT x1 OR x3) AND (NOT x2 OR NOT x3)
@@ -109,7 +111,7 @@ print(result.solution)  # {1: True, 2: False, 3: True}
 ```
 
 ### Model (CP-SAT)
-Constraint programming via SAT encoding.
+For puzzles and scheduling with "all different", arithmetic, and logical constraints. Sudoku, N-Queens, timetabling.
 
 ```python
 m = Model()
@@ -128,7 +130,7 @@ result = m.solve()
 <summary><strong>Metaheuristics</strong></summary>
 
 ### anneal
-Simulated annealing - accepts worse solutions probabilistically.
+Simulated annealing, accepts worse solutions probabilistically.
 
 ```python
 result = anneal(
@@ -141,7 +143,7 @@ result = anneal(
 ```
 
 ### tabu_search
-Maintains a "tabu list" of recent moves to escape local optima.
+Greedy local search with memory. Prevents cycling back to recent solutions, forcing exploration of new territory. More deterministic than anneal.
 
 ```python
 result = tabu_search(
@@ -153,7 +155,7 @@ result = tabu_search(
 ```
 
 ### evolve
-Genetic algorithm with selection, crossover, mutation.
+Population-based search. More overhead than anneal/tabu, but better diversity and parallelizable.
 
 ```python
 result = evolve(
@@ -171,7 +173,7 @@ result = evolve(
 <summary><strong>Continuous Optimization</strong></summary>
 
 ### gradient_descent / momentum / adam
-First-order methods for differentiable functions.
+Follow the slope downhill. Great for polishing solutions from other methods if your objective is differentiable. Adam adapts learning rates per parameter - usually the default choice.
 
 ```python
 def grad_fn(x):
@@ -182,7 +184,7 @@ print(result.solution)  # [~0, ~0]
 ```
 
 ### bayesian_opt
-Gaussian process surrogate for expensive black-box functions.
+When each evaluation is expensive (think hyperparameter tuning, simulations). Builds a surrogate model to guess where to sample next instead of brute-forcing.
 
 ```python
 def expensive_fn(x):
@@ -198,7 +200,7 @@ result = bayesian_opt(expensive_fn, bounds=[(0, 1), (0, 1)], max_iter=30)
 <summary><strong>Network Flow</strong></summary>
 
 ### max_flow
-Ford-Fulkerson with BFS (Edmonds-Karp).
+"How much can I push through this network?" Assigning workers to tasks, finding bottlenecks. The max-flow min-cut theorem gives you bottleneck analysis for free.
 
 ```python
 graph = {
@@ -213,7 +215,7 @@ print(result.solution)   # edge flows dict
 ```
 
 ### min_cost_flow / solve_assignment
-Successive shortest paths for minimum cost flow.
+"What's the cheapest way to route X units?" Transportation, logistics, matching with costs.
 
 ```python
 # Assignment problem: 3 workers, 3 tasks
@@ -229,11 +231,31 @@ result = solve_assignment(costs)
 
 </details>
 
+<details>
+<summary><strong>Exact Cover</strong></summary>
+
+### solve_exact_cover
+For "place these pieces without overlap" or "fill this grid with exactly one of each" problems. Sudoku, pentomino tiling, scheduling where every slot must be filled exactly once.
+
+```python
+# Tiling problem: cover all columns with non-overlapping rows
+matrix = [
+    [1, 1, 0, 0],  # row 0 covers columns 0, 1
+    [0, 1, 1, 0],  # row 1 covers columns 1, 2
+    [0, 0, 1, 1],  # row 2 covers columns 2, 3
+    [1, 0, 0, 1],  # row 3 covers columns 0, 3
+]
+result = solve_exact_cover(matrix)
+# result.solution = (0, 2) or (1, 3) - rows that cover all columns exactly once
+```
+
+</details>
+
 ---
 
 ## Result Format
 
-All solvers return a consistent `Result` namedtuple:
+All solvors return a consistent `Result` namedtuple:
 
 ```python
 Result(
@@ -249,7 +271,7 @@ Result(
 
 ## When to use what?
 
-| Problem | Solver |
+| Problem | Solvor |
 |---------|--------|
 | Linear constraints, continuous variables | `solve_lp` |
 | Linear constraints, some integers | `solve_milp` |
@@ -260,6 +282,7 @@ Result(
 | Smooth, differentiable | `adam` |
 | Expensive black-box | `bayesian_opt` |
 | Assignment, matching, flow | `max_flow`, `solve_assignment` |
+| Exact cover, tiling, N-Queens | `solve_exact_cover` |
 
 ---
 
@@ -278,4 +301,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
 ## License
 
-[Apache 2.0 License](LICENSE) - free for personal and commercial use.
+[Apache 2.0 License](LICENSE) - free for personal and commercial use.

{solvor-0.3.2 → solvor-0.3.4}/README.md

@@ -1,4 +1,4 @@
-# Solvor
+# solvOR
 
 ![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) 
@@ -7,15 +7,16 @@ Solvor your optimization needs..
 
 ## What's in the box?
 
-| Category | Solvers | Use Case |
+| Category | Solvors | Use Case |
 |----------|---------|----------|
 | **Linear/Integer** | `solve_lp`, `solve_milp` | Resource allocation, scheduling |
-| **Constraint** | `solve_sat`, `Model` | Sudoku, configuration, puzzles |
+| **Constraint** | `solve_sat` | Sudoku, configuration, puzzles |
 | **Local Search** | `anneal`, `tabu_search` | TSP, combinatorial optimization |
 | **Population** | `evolve` | When you want nature to do the work |
 | **Continuous** | `gradient_descent`, `momentum`, `adam` | ML, curve fitting |
 | **Black-box** | `bayesian_opt` | Hyperparameter tuning, expensive functions |
 | **Graph** | `max_flow`, `min_cost_flow`, `solve_assignment` | Matching, transportation |
+| **Exact Cover** | `solve_exact_cover` | Sudoku, N-Queens, tiling puzzles |
 
 ---
 
@@ -49,13 +50,13 @@ print(result.solution)  # {'x': 3, 'y': 7}
 
 ---
 
-## Solvers
+## Solvors
 
 <details>
 <summary><strong>Linear & Integer Programming</strong></summary>
 
 ### solve_lp
-Two-phase simplex for linear programming.
+For resource allocation, blending, production planning. Finds the exact optimum for linear objectives with linear constraints.
 
 ```python
 # minimize 2x + 3y subject to x + y >= 4, x <= 3
@@ -67,7 +68,7 @@ result = solve_lp(
 ```
 
 ### solve_milp
-Branch and bound for mixed-integer problems.
+When some variables must be integers. Diet problems, scheduling with discrete slots, set covering.
 
 ```python
 # same as above, but x must be integer
@@ -80,7 +81,7 @@ result = solve_milp(c=[2, 3], A=[[-1, -1], [1, 0]], b=[-4, 3], integers=[0])
 <summary><strong>Constraint Programming</strong></summary>
 
 ### solve_sat
-DPLL with unit propagation and clause learning.
+For "is this configuration valid?" problems. Dependencies, exclusions, implications - anything that boils down to boolean constraints.
 
 ```python
 # (x1 OR x2) AND (NOT x1 OR x3) AND (NOT x2 OR NOT x3)
@@ -89,7 +90,7 @@ print(result.solution)  # {1: True, 2: False, 3: True}
 ```
 
 ### Model (CP-SAT)
-Constraint programming via SAT encoding.
+For puzzles and scheduling with "all different", arithmetic, and logical constraints. Sudoku, N-Queens, timetabling.
 
 ```python
 m = Model()
@@ -108,7 +109,7 @@ result = m.solve()
 <summary><strong>Metaheuristics</strong></summary>
 
 ### anneal
-Simulated annealing - accepts worse solutions probabilistically.
+Simulated annealing, accepts worse solutions probabilistically.
 
 ```python
 result = anneal(
@@ -121,7 +122,7 @@ result = anneal(
 ```
 
 ### tabu_search
-Maintains a "tabu list" of recent moves to escape local optima.
+Greedy local search with memory. Prevents cycling back to recent solutions, forcing exploration of new territory. More deterministic than anneal.
 
 ```python
 result = tabu_search(
@@ -133,7 +134,7 @@ result = tabu_search(
 ```
 
 ### evolve
-Genetic algorithm with selection, crossover, mutation.
+Population-based search. More overhead than anneal/tabu, but better diversity and parallelizable.
 
 ```python
 result = evolve(
@@ -151,7 +152,7 @@ result = evolve(
 <summary><strong>Continuous Optimization</strong></summary>
 
 ### gradient_descent / momentum / adam
-First-order methods for differentiable functions.
+Follow the slope downhill. Great for polishing solutions from other methods if your objective is differentiable. Adam adapts learning rates per parameter - usually the default choice.
 
 ```python
 def grad_fn(x):
@@ -162,7 +163,7 @@ print(result.solution)  # [~0, ~0]
 ```
 
 ### bayesian_opt
-Gaussian process surrogate for expensive black-box functions.
+When each evaluation is expensive (think hyperparameter tuning, simulations). Builds a surrogate model to guess where to sample next instead of brute-forcing.
 
 ```python
 def expensive_fn(x):
@@ -178,7 +179,7 @@ result = bayesian_opt(expensive_fn, bounds=[(0, 1), (0, 1)], max_iter=30)
 <summary><strong>Network Flow</strong></summary>
 
 ### max_flow
-Ford-Fulkerson with BFS (Edmonds-Karp).
+"How much can I push through this network?" Assigning workers to tasks, finding bottlenecks. The max-flow min-cut theorem gives you bottleneck analysis for free.
 
 ```python
 graph = {
@@ -193,7 +194,7 @@ print(result.solution)   # edge flows dict
 ```
 
 ### min_cost_flow / solve_assignment
-Successive shortest paths for minimum cost flow.
+"What's the cheapest way to route X units?" Transportation, logistics, matching with costs.
 
 ```python
 # Assignment problem: 3 workers, 3 tasks
@@ -209,11 +210,31 @@ result = solve_assignment(costs)
 
 </details>
 
+<details>
+<summary><strong>Exact Cover</strong></summary>
+
+### solve_exact_cover
+For "place these pieces without overlap" or "fill this grid with exactly one of each" problems. Sudoku, pentomino tiling, scheduling where every slot must be filled exactly once.
+
+```python
+# Tiling problem: cover all columns with non-overlapping rows
+matrix = [
+    [1, 1, 0, 0],  # row 0 covers columns 0, 1
+    [0, 1, 1, 0],  # row 1 covers columns 1, 2
+    [0, 0, 1, 1],  # row 2 covers columns 2, 3
+    [1, 0, 0, 1],  # row 3 covers columns 0, 3
+]
+result = solve_exact_cover(matrix)
+# result.solution = (0, 2) or (1, 3) - rows that cover all columns exactly once
+```
+
+</details>
+
 ---
 
 ## Result Format
 
-All solvers return a consistent `Result` namedtuple:
+All solvors return a consistent `Result` namedtuple:
 
 ```python
 Result(
@@ -229,7 +250,7 @@ Result(
 
 ## When to use what?
 
-| Problem | Solver |
+| Problem | Solvor |
 |---------|--------|
 | Linear constraints, continuous variables | `solve_lp` |
 | Linear constraints, some integers | `solve_milp` |
@@ -240,6 +261,7 @@ Result(
 | Smooth, differentiable | `adam` |
 | Expensive black-box | `bayesian_opt` |
 | Assignment, matching, flow | `max_flow`, `solve_assignment` |
+| Exact cover, tiling, N-Queens | `solve_exact_cover` |
 
 ---
 
@@ -258,4 +280,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
 ## License
 
-[Apache 2.0 License](LICENSE) - free for personal and commercial use.
+[Apache 2.0 License](LICENSE) - free for personal and commercial use.