Docs: LLM‑optimised algorithm priorities and rationale

PROJECT_DESCRIPTION.md

@@ -86,6 +86,25 @@ When requesting a new algorithm from an LLM:
 
 Consistency between runtime code, documentation, and TypeScript declarations keeps generated code trustworthy for both humans and LLMs.
 
+### Choosing High-Value Algorithms for LLMs
+
+We prioritise algorithms that are:
+
+- Complex enough to burn tokens if generated ad‑hoc (e.g., max‑flow, automata, triangulation),
+- Reusable primitives across domains (search/text, graph, geometry, spatial), and
+- Stable with many edge cases better covered by tests than by prompt iteration.
+
+Shortlist for upcoming “LLM‑optimised” modules:
+
+- Aho–Corasick (multi‑pattern)
+- Dinic (maximum flow) + min‑cut export
+- Suffix Automaton (or Ukkonen suffix tree)
+- Delaunay Triangulation (Bowyer–Watson) + KD‑Tree nearest neighbour
+- BVH (SAH) builder
+- Polygon clipping (Greiner–Hormann / Weiler–Atherton)
+
+If you’re proposing a new module, include a brief note on token savings and typical usage scenarios to keep scope aligned with this principle.
+
 ---
 
 ## ✅ Included Implementations (v0.1.0)

README.md

@@ -49,6 +49,28 @@ npm run size        # Enforce bundle size budget
 ## API Reference
 - Full TypeScript signatures with "Use for" and performance notes live in `docs/index.d.ts`. Keep this document in sync with `src/index.ts` so tooling and LLMs can discover the complete surface area.
 
+## Why This Library Helps LLMs
+
+Generating long, stateful algorithms inside prompts is error‑prone and wastes context window. This project intentionally ships implementations that are:
+
+- Big enough to be annoying for an LLM to re‑generate each time (reducing token burn),
+- Deterministic with parameterized options and strong typing, and
+- Covered by tests and examples so agents can compose them confidently.
+
+High‑value algorithms for LLM workflows include complex matchers, graph solvers, and geometry builders that are long, fiddly, and easy to get wrong. The roadmap highlights these under “LLM‑Optimised Additions”.
+
+### LLM‑Optimised Additions (Highlights)
+
+- Aho–Corasick multi‑pattern automaton (string matcher; long to implement, widely useful)
+- Dinic / Push‑Relabel maximum flow (network flow; many moving parts and edge cases)
+- Suffix Automaton or Ukkonen’s Suffix Tree (advanced indexing; compact surface, complex internals)
+- Delaunay Triangulation (Bowyer–Watson) + fast nearest neighbour structures (KD‑Tree)
+- BVH (SAH) or R‑Tree builders (robust spatial indexes that are non‑trivial to code)
+- Polygon clipping (Greiner–Hormann or Weiler–Atherton) for boolean ops (very token‑heavy)
+- Tarjan / Kosaraju SCC (graph decomposition; lower complexity but frequently reused)
+
+See the roadmap for the full list and status.
+
 ## Roadmap Snapshot
 - Milestone 0.2 next targets crowd-flow integrations (RVO + flow fields) and behaviour-tree decorators for richer AI control.
 - Milestone 0.4 plans a procedural + gameplay systems toolkit (Wave Function Collapse, dungeon suite, L-systems, game loop, camera, particles, inventory, combat, save/load, and more).

ROADMAP.md

@@ -85,7 +85,7 @@
 - **Data pipelines & utilities**
   - [x] Flatten/unflatten helpers for nested structures
   - [x] Pagination utilities for client-side paging
-- [x] Advanced diff tooling (tree diff, selective patches)
+  - [x] Advanced diff tooling (tree diff, selective patches)
 - **Visual & simulation tools**
   - [x] Color manipulation helpers (RGB/HSL conversion, blending)
   - [x] Force-directed graph layout
@@ -94,7 +94,7 @@
 - **Graph algorithms**
   - [x] Minimum spanning tree (Kruskal)
   - [ ] Strongly connected components (Tarjan/Kosaraju)
-  - [ ] Maximum flow (Ford–Fulkerson / Edmonds–Karp)
+  - [ ] Maximum flow (Dinic preferred; Edmonds–Karp fallback)
 - **Spatial & collision expansion**
   - [ ] Octree partitioning for 3D space
   - [ ] Circle collision helpers
@@ -114,6 +114,28 @@
 - **Geometric & numeric utilities**
   - [ ] Closest pair of points solver for geometry toolkit
 
+### LLM‑Optimised Additions (Priority Rationale)
+
+These items offer the largest context and correctness savings for LLM users. Prioritize when bandwidth is limited:
+
+1) Aho–Corasick automaton (string search)
+   - Deterministic trie with failure links; long to hand-roll; great for lexing and multi‑pattern filters.
+
+2) Dinic maximum flow (graph)
+   - Level graph + blocking flow; reusable for min‑cut, image segmentation, bipartite matching.
+
+3) Suffix Automaton or Ukkonen Suffix Tree (string index)
+   - Advanced indexing primitive enabling substring queries and LCS; compact but intricate to implement.
+
+4) Delaunay Triangulation (Bowyer–Watson) + KD‑Tree (geometry)
+   - Robust triangulation and fast nearest neighbour queries are both lengthy and widely reused.
+
+5) BVH (SAH) builder (spatial)
+   - Non‑trivial tree construction with cost heuristics; useful for ray queries and collision.
+
+6) Polygon clipping (Greiner–Hormann / Weiler–Atherton)
+   - Complex boolean operations for polygons (union/intersect/diff); many edge cases.
+
 ## Milestone 1.0.0 – Production Readiness
 
 - [ ] Publish to npm with semver automation and changelog management

docs/list.md

@@ -153,3 +153,13 @@ Convex Hull (Graham Scan) - Boundary point detection
 Line Intersection - Check if lines cross
 Point in Polygon - Containment testing
 Closest Pair of Points - Find nearest points
+
+Planned (High LLM Value)
+
+Aho–Corasick Automaton - Multi‑pattern string matching
+Suffix Automaton - Compact substring index
+Maximum Flow (Dinic) - Network flow and min‑cut
+Delaunay Triangulation - Robust 2D triangulation
+KD‑Tree - Fast nearest neighbour queries
+BVH (SAH) - Spatial hierarchy for ray/collision
+Polygon Clipping - Boolean ops (union/intersect/diff)