From 3bb43f208375035fe52f965bb122bb9a93930d53 Mon Sep 17 00:00:00 2001 From: Francois Date: Thu, 9 Oct 2025 09:30:18 +0900 Subject: [PATCH] docs: add LLM-optimised additions, priorities, and rationale across README/ROADMAP/PROJECT_DESCRIPTION --- PROJECT_DESCRIPTION.md | 19 +++++++++++++++++++ README.md | 22 ++++++++++++++++++++++ ROADMAP.md | 26 ++++++++++++++++++++++++-- docs/list.md | 10 ++++++++++ 4 files changed, 75 insertions(+), 2 deletions(-) diff --git a/PROJECT_DESCRIPTION.md b/PROJECT_DESCRIPTION.md index a67d229..4216193 100644 --- a/PROJECT_DESCRIPTION.md +++ b/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) diff --git a/README.md b/README.md index c15774e..8863584 100644 --- a/README.md +++ b/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). diff --git a/ROADMAP.md b/ROADMAP.md index d5df7b3..209b3ea 100644 --- a/ROADMAP.md +++ b/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 diff --git a/docs/list.md b/docs/list.md index cce8a02..e15c396 100644 --- a/docs/list.md +++ b/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)