Little Linked Libraian: NodeKit

An educational, self-hostable version of Little Linked Librarian that teaches AI workflows, agent tools, distributed nodes, and modern software architecture through a working neighborhood library.

Comment

Little Linked Librarian: NodeKit

## Inspiration

Little free libraries are wonderfully simple: a box, some books, and a neighborhood willing to share. Readers do not know what is available without visiting, while some boxes have owners and some do not there is no way to catalog books and assorted things; puzzle, note cards, art as they come and go.

Little Linked Librarian began as a centralized application for cataloging free little library boxes. As I developed its scanner and discovery features, I always wanted a micro service decentralized infrastructure to allow each box to remain independent; own its inventory, who can see and not see it and optionally participate in a larger discovery network.

I saw an educational opportunity as I developed in new AI tools, Replit, Cursor all locking user into their frameworks. That journey began to carve out a teaching path for centralized to decentralized, then as Vide Coders popped out, it was a good architecture to provide domain knowledge about software and AI, learners could take this repo and ask to build in any language, UX, backend and datastore, and get the kitchen sink or hand code any aspect to learn and play.

## What it does

NodeKit is a self-hostable learning kit with a complete reference application called Happy Box.

An operator can:

  • Create and personalize neighborhood library boxes
  • Photograph one book or an entire shelf
  • Extract multiple book candidates from one image
  • Review and correct titles and authors as a batch
  • Compare bibliographic editions, ISBNs, descriptions, and covers
  • Explicitly choose which candidates become canonical books
  • Search the catalogue and with vectordb option multiple languages
  • Inspect the original scan and every resulting decision
  • Use the application through its browser interface or ChatGPT
  • Make the node discoverable through an LLL-compatible network

## How we built it

NodeKit uses the Interpretable Context Methodology, or ICM, to make its development process understandable.

Rather than giving Codex one large prompt, the repository guides it through seven inspectable stages:

  1. Discovery
  2. Specification
  3. Architecture
  4. Scaffolding
  5. Build
  6. Validation
  7. Release

Each stage reads explicitly routed context, produces a reviewable artifact, and pauses when human judgment is required.

The checked-in Happy Box application is a reference run produced from this process. It demonstrates that the instructions can create a complete node, but it is not the only supported stack.

The reference implementation uses:

  • TypeScript, Node.js, and Fastify
  • SQLite and sqlite-vec
  • GPT-5.6 for multi-book visual extraction and catalogue descriptions
  • OpenAI embeddings for semantic retrieval
  • Open Library for edition and cover proposals
  • Streamable HTTP MCP and an MCP Apps widget for ChatGPT
  • Docker and a Cloudflare Tunnel for self-hosting
  • A pinned OpenAPI compatibility boundary for LLL Central

Browser, MCP, persistence, AI, and network adapters all call the same application services. This keeps the domain rules independent of any one interface or deployment platform.

## How we used Codex and GPT-5.6

Codex with GPT-5.6 helped us turn the original LLL architecture into the staged NodeKit methodology and then build the Happy Box reference application from those instructions.

Codex accelerated:

  • Translating product decisions into service and API boundaries
  • Refactoring the scanner from one result into independent batch candidates
  • Designing confirmation and idempotency safeguards
  • Building SQLite migrations and vector search
  • Implementing browser and MCP interfaces over shared services
  • Diagnosing metadata, image, deletion, and schema-contract failures
  • Creating transport, persistence, migration, and regression tests
  • Producing Docker deployment and judge-facing documentation

I made the consequential product decisions: AI may propose but not publish; unreadable items remain unresolved; editions require review; Assorted Things remain human-described; and independently owned nodes expose only a limited compatibility contract to Central.

## Challenges

### A photograph is not a clean dataset

Book spines may be rotated, obscured, damaged, or poorly lit. We learned to treat extraction as a proposal rather than truth.

### One scan produces many independent decisions

A shelf photograph may contain 15 books, but an operator must be able to approve 14, correct one, or reject several. Each candidate therefore has its own state and outcome under one parent scan.

### Metadata can look plausible and still be wrong

Recognizing a title does not identify the exact physical edition. NodeKit keeps visual observations, bibliographic proposals, and canonical records separate until a person chooses an edition.

### Conversational writes need explicit boundaries

Natural-language commands feel effortless, but they can change a real catalogue. Scanning creates pending candidates only. Publication requires reviewed selections, a destination box, and explicit confirmation.

## Accomplishments

We are proud that NodeKit is a working system rather than a simulated AI demonstration.

It now provides:

  • Real multi-book extraction from operator photographs
  • Batch review with independent candidate outcomes
  • Human-reviewed metadata, ISBN, and cover selection
  • Persistent scan history with zoomable source images
  • Semantic catalogue discovery
  • A responsive, personalized box interface
  • Ten tested MCP tools and a ChatGPT widget
  • A live independently hosted node
  • Compatibility with the broader LLL discovery network
  • 24 automated tests across application, persistence, vectors, and MCP boundaries

Most importantly, NodeKit demonstrates that useful AI does not need to pretend to be certain. It can expose uncertainty, preserve evidence, and ask a human to make the consequential decision.

## What we learned

The most important part of an AI application is often everything surrounding the model.

Image recognition alone does not create a trustworthy inventory. The complete system also needs state, provenance, validation, human correction, confirmation, retry protection, and precise tool contracts.

I also learned that agent interfaces expose architectural weaknesses quickly. If an agent cannot distinguish semantic discovery from complete inventory listing, the underlying API contract needs improvement.

Most importantly, learning becomes more meaningful when the software has a real purpose. A NodeKit learner is not moving placeholder records between sample services. They are creating a working community resource and seeing how each architectural choice affects it.

## What’s next

Next we want to extend NodeKit with:

  • Moderation
  • Unique Book Journey
  • Publishing
  • Guided lessons attached to each ICM stage
  • Additional reference implementations in other languages and datastores
  • Multi-photo capture for larger shelves
  • Stronger duplicate detection across boxes
  • Production OAuth for publicly available multi-user MCP deployments
  • Easier deployment from a laptop to a home server or hosted node
  • Classroom projects covering AI, APIs, databases, search, distributed systems, and responsible automation
Share this project:

Updates