booksmart 0.1.1

Booksmart CLI — a local, single-user front end over booksmart-core (embedded storage, no server).

booksmart

The Booksmart CLI — turn books into queryable knowledge, locally.

A single-user front end over booksmart-core: register PDFs/EPUBs, ingest them through the parsing → structure → profile → extraction → summaries → embeddings pipeline, and browse the results. Everything runs against an auto-migrated SQLite file and embedded Qdrant under ~/.booksmart/ — no Docker, no Postgres, no server.

Install

Needs Python 3.12 or newer. booksmart is a command-line tool, so install it into its own environment rather than into a project's:

$ uv tool install booksmart
$ pipx install booksmart

Either puts a booksmart command on your PATH. Plain pip install booksmart also works if you would rather have it in the current environment. booksmart-core comes along as a dependency in every case.

Quickstart

$ booksmart add ./clean-code.pdf --title "Clean Code" --author "Robert C. Martin"
$ booksmart ingest <book-id>
$ booksmart structure <book-id>
$ booksmart knowledge list <book-id>
$ booksmart search all "how do deep modules reduce complexity"

ingest calls an LLM and an embedding provider, so it needs credentials — ANTHROPIC_API_KEY and OPENAI_API_KEY by default. To drive the whole pipeline with no keys, no network and no cost, select the deterministic fake providers:

$ BOOKSMART_LLM_PROVIDER=fake BOOKSMART_EMBEDDING_PROVIDER=fake booksmart ingest <book-id>

Commands

add, ingest, books list/show/update, runs list/show, structure, profile, knowledge list/show, search.

Search

booksmart search <book-id|all> "<query>" ranks the chapters, sections and knowledge objects most similar to a natural-language query, over the embeddings an ingest produced. Restrict it with --type (repeatable: chapter, section, knowledge_object), cap it with --limit, and drop weak hits with --score-threshold (a cosine similarity, -1–1).

The query is embedded with the model the vector collection is locked to; if that is not the currently configured embedding model, search refuses rather than return plausible, silently wrong rankings (ADR 0001).

Configuration

Providers and locations come from BOOKSMART_* environment variables (e.g. BOOKSMART_LLM_PROVIDER, BOOKSMART_HOME). Set BOOKSMART_QDRANT_URL to use a Qdrant server instead of the embedded on-disk store.