Build a solver you can reason about.
DeltaSearch is a typed, dependency-free framework for heuristic subgraph extraction. Start with a local checkout, learn the problem contract, then choose the smallest solver that answers your question.
DeltaSearch is not published to PyPI yet. The supported path today is git clone followed by pip install -e ".[dev]". The API may change before the first package release.
Getting started →
Install the repository, build a graph, define a problem, and run a first solve.
Understand the engine →
Explore states, actions, deltas, undo, feasibility, and the solver loop.
API reference →
Find the public classes and methods you will use when integrating DeltaSearch.
Diagnose a run →
Work through common graph, performance, optional dependency, and concurrency issues.
Choose a path
I want to run a built-in problem
Follow Getting started, then swap in one of the six built-in problem classes.
I want to model my own objective
Read The problem contract and implement a subclass of SubgraphExtractionProblem.
I need to understand a surprising result
Attach an observer, inspect the objective trace, and check action feasibility before changing the solver.
I want to extend search behavior
Keep problem logic in the problem class and add search policy through a solver strategy. The extension model explains the boundary.
The short mental model
An input Graph is given to a SubgraphExtractionProblem. The problem exposes candidate Actions and scores them as an incremental DeltaResult. A solver chooses a move, applies it, and keeps the best feasible state until a budget or stopping condition ends the run.
input graph
↓
problem.evaluate_initial_state()
↓
enumerate actions → calculate delta → choose best feasible action
↓ ↘ undo rejected candidate actions
new state → observe → repeat until budget / stall / targetWorking principles
Make moves local
Use calculate_delta to derive objective change from the affected neighborhood. Do not re-score the entire graph for every candidate.
Keep moves reversible
Mutations go through apply_action and undo_action. This keeps candidate evaluation isolated and makes backtracking inspectable.
Make runs observable
Observers receive action evaluations, iteration completions, and convergence. Use them for logs, metrics, plots, and debugging.
Measure the right thing
Separate candidate scoring cost, state-copy cost, and total solve time. “O(1) delta” does not mean the whole iteration is O(1).