Core Concepts
Detection model, depth levels, and forcing tree analysis.
Detection model
ChessGrammar uses a two-layer detection pipeline. Each position passes through a structural scan, then optionally through a forcing tree validation. The result is a set of classified tactical patterns with confirmed material consequences.
Input (FEN/PGN)
→ Parse & validate
→ L1: Structural scan (pattern candidates)
→ L2: Forcing tree validation (confirmed patterns)
→ Output (classified tactics with metadata)
The engine does not use neural networks or stochastic search. Detection is deterministic — the same input always produces the same output.
Depth levels: L1 vs L2
Every API call accepts a depth parameter that controls the analysis depth.
L1 — Structural scan
L1 performs static pattern matching on the board geometry. It identifies candidate patterns based on piece positions, attack lines, and structural relationships.
| Property | Value |
|---|---|
| Median latency | ~3ms per position |
| What it finds | Pattern candidates based on board structure |
| Confirmation | No material gain confirmation (gain_confirmed: false) |
| Best for | Fast scanning, filtering, pre-screening large datasets |
L1 is fast but may include false positives — patterns that look structurally correct but don't hold up through best play.
L2 — Forcing tree confirmation
L2 takes each L1 candidate and validates it through a forcing tree: a sequence of forced moves (checks, captures, threats) that confirms whether the tactic actually yields material gain or checkmate.
| Property | Value |
|---|---|
| Median latency | ~42ms per position |
| What it finds | Confirmed patterns with material gain through best play |
| Confirmation | Full forcing tree validation with alpha-beta pruning (gain_confirmed: true) |
| Best for | Accurate analysis, tactics training, game annotation |
L2 is the default depth. It eliminates false positives and provides the actual material consequence of each tactic.
Choosing a depth
| Use case | Recommended depth |
|---|---|
| Scan a large database for positions with tactics | L1 |
| Pre-filter before detailed analysis | L1, then L2 on candidates |
| Accurate game annotation | L2 |
| Tactics trainer / puzzle generation | L2 |
| Real-time analysis (mobile, low-latency) | L1, or L1 then selective L2 |
Forcing tree analysis
The forcing tree is the core validation mechanism in L2. It explores sequences of forced moves — checks, captures, and direct threats — to determine if a tactical pattern leads to a concrete advantage.
For each L1 candidate, the engine:
- Plays the trigger move
- Explores the opponent's best responses
- Continues the forcing sequence until the position resolves
- Measures the material difference
If the material gain is confirmed (the tactic "works" through best play), the pattern is marked as gain_confirmed: true and the gain is recorded in centipawns.
Move sequences
By default, the API returns patterns without the explicit move sequence (for speed). Pass "with_sequence": true to include the full forcing line:
{
"fen": "...",
"with_sequence": true
}
This adds approximately 205ms per tactic to the response time. The sequence field will contain the moves in UCI format:
"sequence": ["d4e2", "g1g2", "e2c3", "b2c3"]
When with_sequence is false (default), the sequence field is null.
Pattern taxonomy
ChessGrammar detects 10 tactical patterns. Each has a formal definition based on chess theory — specific structural conditions that must be met for a position to qualify.
The 10 patterns are: Fork, Pin, Skewer, Discovered Attack, Double Check, Back Rank Mate, Smothered Mate, Deflection, Interference, Trapped Piece.
See Patterns for detailed definitions and examples of each.