|
| 1 | +# LLM Algorithm Library – Reference Companion |
| 2 | + |
| 3 | +This document complements `docs/index.d.ts` with high-level navigation notes that help human developers and coding assistants discover the right algorithms quickly. |
| 4 | + |
| 5 | +## 📚 Quick Start |
| 6 | + |
| 7 | +### For LLMs and automation |
| 8 | +1. Inspect the TypeScript definitions in `docs/index.d.ts` for signatures, “Use for” blurbs, and performance notes. |
| 9 | +2. Pick the algorithm that matches your task from the selection guide below. |
| 10 | +3. Import from the package entry point or CDN: |
| 11 | + |
| 12 | +```ts |
| 13 | +import { astar } from 'llm-algorithms/dist/index.js'; |
| 14 | +``` |
| 15 | + |
| 16 | +```html |
| 17 | +<script type="module"> |
| 18 | + import { astar, perlin } from "https://cdn.jsdelivr.net/npm/llm-algorithms/dist/index.js"; |
| 19 | +</script> |
| 20 | +``` |
| 21 | + |
| 22 | +### For local development |
| 23 | + |
| 24 | +```bash |
| 25 | +npm install llm-algorithms |
| 26 | +npm run build # emit dist/ |
| 27 | +``` |
| 28 | + |
| 29 | +Examples in `examples/` are runnable with `tsx`/`ts-node` for quick validation. |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +## 🎯 Algorithm Selection Guide |
| 34 | + |
| 35 | +| Need | Algorithm(s) | Import From | Example | |
| 36 | +| ---- | ------------ | ----------- | ------- | |
| 37 | +| Grid pathfinding | `astar`, `dijkstra`, `manhattanDistance`, `gridFromString` | `pathfinding/astar.ts`, `pathfinding/dijkstra.ts` | `examples/astar.ts` | |
| 38 | +| Procedural generation | `perlin`, `perlin3D`, `simplex2D`, `simplex3D`, `worley`, `worleySample` | `procedural/*.ts` | `examples/simplex.ts`, `examples/worley.ts` | |
| 39 | +| Spatial queries & collision | `Quadtree`, `aabbCollision`, `aabbIntersection`, `satCollision`, `circleRayIntersection`, `sweptAABB` | `spatial/*.ts` | `examples/sat.ts` | |
| 40 | +| AI behaviours & crowds | `seek`, `flee`, `arrive`, `pursue`, `wander`, `updateBoids`, `BehaviorTree`, `rvoStep` | `ai/steering.ts`, `ai/boids.ts`, `ai/behaviorTree.ts`, `ai/rvo.ts` | `examples/steering.ts`, `examples/boids.ts`, `examples/rvo.ts` | |
| 41 | +| Web performance & UI | `debounce`, `throttle`, `LRUCache`, `memoize`, `deduplicateRequest`, `clearRequestDedup`, `calculateVirtualRange` | `util/*.ts` | `examples/requestDedup.ts`, `examples/virtualScroll.ts` | |
| 42 | +| Text & search | `fuzzySearch`, `fuzzyScore`, `Trie`, `binarySearch`, `levenshteinDistance` | `search/*.ts` | `tests/search.test.ts` | |
| 43 | +| Data transforms & diffing | `diff`, `deepClone`, `groupBy`, `diffJson`, `applyJsonDiff` | `data/*.ts` | `tests/jsonDiff.test.ts` | |
| 44 | +| Graph algorithms | `graphBFS`, `graphDFS`, `topologicalSort` | `graph/traversal.ts` | `tests/graph.test.ts` | |
| 45 | +| Geometry & visuals | `convexHull`, `lineIntersection`, `pointInPolygon`, `easing`, `quadraticBezier`, `cubicBezier` | `geometry/*.ts`, `visual/*.ts` | `tests/geometry.test.ts`, `tests/visual.test.ts` | |
| 46 | + |
| 47 | +--- |
| 48 | + |
| 49 | +## 📦 Project Structure (TypeScript) |
| 50 | + |
| 51 | +``` |
| 52 | +llm-algorithms/ |
| 53 | +├── docs/ |
| 54 | +│ ├── index.d.ts # Authoritative type surface + “Use for” notes |
| 55 | +│ ├── index2.d.ts # Quick navigation helper (references index.d.ts) |
| 56 | +│ └── project.md # This guide |
| 57 | +├── examples/ # Runnable scripts (astar, steering, boids, rvo, sat, simplex, worley, requestDedup, virtualScroll) |
| 58 | +├── src/ |
| 59 | +│ ├── ai/ # Steering, boids, behaviour tree, RVO |
| 60 | +│ ├── data/ # Diff, deep clone, groupBy, JSON diff |
| 61 | +│ ├── graph/ # BFS, DFS, topological sort |
| 62 | +│ ├── pathfinding/ # A*, Dijkstra helpers |
| 63 | +│ ├── procedural/ # Noise generators |
| 64 | +│ ├── search/ # Fuzzy search, trie, binary search, Levenshtein |
| 65 | +│ ├── spatial/ # Quadtree, AABB, SAT, circle-ray, swept AABB |
| 66 | +│ ├── util/ # Debounce, throttle, LRU, memoize, dedup, virtual scroll |
| 67 | +│ ├── visual/ # Easing curves, Bezier helpers |
| 68 | +│ ├── types.ts # Shared geometric and agent types |
| 69 | +│ └── index.ts # Barrel exports |
| 70 | +├── tests/ # Vitest coverage ensuring examples remain truthful |
| 71 | +└── README.md # High-level summary + selection table |
| 72 | +``` |
| 73 | + |
| 74 | +--- |
| 75 | + |
| 76 | +## 🧠 Working With LLMs |
| 77 | + |
| 78 | +When prompting an LLM to add or extend functionality, ensure it follows these guardrails: |
| 79 | + |
| 80 | +1. **Implementation** – add runtime code to `src/<category>/<name>.ts` using modern TypeScript, rich JSDoc, and small pure helpers. Provide at least two `@example` blocks. |
| 81 | +2. **Types & docs** – update `docs/index.d.ts` (and this guide if applicable) with description, “Use for” line, performance note, import path, and any new interfaces/options. |
| 82 | +3. **Exports** – wire the module through `src/index.ts` and add/extend the relevant types in `src/types.ts` when necessary. |
| 83 | +4. **Tests** – create Vitest coverage in `tests/` demonstrating success paths and edge cases. Prefer deterministic fixtures to keep CI stable. |
| 84 | +5. **Examples** – add or update an entry under `examples/` so users can run the algorithm quickly. |
| 85 | +6. **Quality gate** – ensure `npm run lint`, `npm run typecheck`, `npm run build`, `npm run size`, and `npm run test:coverage` succeed before opening a PR. |
| 86 | + |
| 87 | +Following these steps keeps the documentation aligned with the code and makes the library predictable for both humans and language models. |
| 88 | + |
| 89 | +--- |
| 90 | + |
| 91 | +## ✅ Included Implementations (Snapshot) |
| 92 | + |
| 93 | +- **Pathfinding:** A*, Dijkstra, Manhattan heuristic, grid helpers. |
| 94 | +- **Procedural:** Perlin (2D/3D), Simplex (2D/3D), Worley noise. |
| 95 | +- **Spatial:** Quadtree, AABB helpers, SAT collision, circle-ray intersection, swept AABB. |
| 96 | +- **Web performance:** Debounce, throttle, LRU cache, memoize, request deduplication, virtual scroll windowing. |
| 97 | +- **Search & text:** Fuzzy search/scoring, Trie autocomplete, binary search, Levenshtein distance. |
| 98 | +- **Data pipelines:** Diff (LCS), deep clone, groupBy, JSON diff/patch helpers. |
| 99 | +- **Graph:** BFS distance map, DFS traversal, topological ordering. |
| 100 | +- **Geometry & visuals:** Convex hull, line intersection, point-in-polygon, easing curves, Bezier evaluation. |
| 101 | +- **AI behaviours:** Steering helpers, boids, behaviour trees, RVO crowd steering. |
| 102 | + |
| 103 | +--- |
| 104 | + |
| 105 | +## 🔭 Upcoming Focus |
| 106 | + |
| 107 | +- Flow-field integration with RVO for smoother large crowd routing. |
| 108 | +- Behaviour-tree decorators and reusable condition/action packs. |
| 109 | +- Additional procedural generators (erosion, domain-warped noise). |
| 110 | +- Expanded example gallery with visualization snippets. |
| 111 | + |
| 112 | +Contributions welcome! Follow conventional commits and keep examples runnable so docs stay in sync. |
0 commit comments