How harrysolovay/liminal works
Project type and purpose
• Liminal is a multi-package TypeScript “toolkit” monorepo for composing conversation trees over LLMs via iterator/generator-based APIs.
• It consists of:
• A core library (/liminal) that defines runes, strands, adapters, context, schemas, etc.
• A suite of official adapter packages (/packages/liminal-*) that plug in different LLM providers.
• Example integrations (/example-integrations/*) showing usage in CF Workers, Hono HTTP servers, Vite + React apps, Docker Compose, etc.
• A VitePress-based documentation site (/liminal.land).
• Test harness rules (/.cursor) and example scripts (/examples).
File structure
• Top-level directories:
• liminal/ → core engine code
• packages/ → NPM plugin packages (openai, alchemy, ark-type, etc.)
• example-integrations/ → runnable sample projects
• examples/ → minimal TS scripts demonstrating library features
• liminal.land/ → docs site
• .cursor/ → testing rules
• Config files: tsconfig.*.json, bun.lock, vitest.ts, GitHub workflows under /.github/workflows.
• The core uses a plugin architecture (AdapterRegistry), generator patterns (yield runes), and modular packaging.
README for additional insights
• Core concept: generators yield runes (L.user, L.assistant, L.strand, L.focus) to mutate conversation state or call out to an LLM via an adapter.
• Entry point: L.run(generatorFn, { handler })
• Adapters are pluggable; examples use liminal-ollama, etc.
• Documentation lives on liminal.land, examples under /examples.
Main components & relationships
A. Core library (liminal/)
• Modules: AdapterRegistry, Config, Context, Definition, Message, Rune engine, Schema, Strand, Tool interfaces
• Patterns: generator/rune pipeline, event emission (LEvent), error handling
B. Adapter packages (/packages/liminal-<provider>)
• Each implements the Adapter interface and registers to AdapterRegistry
• Examples: liminal-openai, liminal-ollama, liminal-alchemy, etc.
C. Runtime environment(s) from example-integrations
• Cloudflare Worker
• Hono HTTP Server
• Vite + React SPA (with PGLite Web Worker)
• Docker Compose (local LLM stack)
• They import liminal + one or more /packages/liminal-* adapters, then call L.run()
D. External LLM services
• OpenAI API
• Ollama
• Alchemy
• Other HTTP/GRPC endpoints
E. Documentation site
• Built with VitePress, live at liminal.land
• Pulls markdown in /liminal.land and references code examples
F. Testing & CI
• .cursor test rules
• Vitest config (vitest.ts)
• GitHub Actions workflows for build, test, deploy
Architectural patterns & design principles
• Monorepo with workspaces: core + plugins + docs + examples
• Plugin architecture: AdapterRegistry + modular adapter packages
• Generator-based DSL (“runes”) for stateful conversation modeling
• Strict TypeScript typing with schema modules under liminal/L/schema
Elements to capture
• File-structure boundaries: show top-level workspaces
• Plugin registration: AdapterRegistry receives providers at runtime
• External dependencies: HTTP requests to LLM endpoints
• CI triggers: GitHub Actions building core, publishing packages, deploying docs