Metadata-Version: 2.4
Name: booksmart
Version: 0.1.1
Summary: Booksmart CLI — a local, single-user front end over booksmart-core (embedded storage, no server).
Author-email: Patryk Dwórznik <patryk@dworznik.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: booksmart-core<0.2.0,>=0.1.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# booksmart

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

A single-user front end over
[`booksmart-core`](https://pypi.org/project/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:

```console
$ 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

```console
$ 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:

```console
$ 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.
