booksmart 0.1.0__tar.gz

booksmart-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.mypy_cache/
+dist/
+dist-core/
+dist-cli/
+*.egg-info/
+
+# Object storage contents stay local; keep the layout tracked via .gitkeep
+storage/*/*
+!storage/*/.gitkeep
+
+.env

booksmart-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patryk Dwórznik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

booksmart-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: booksmart
+Version: 0.1.0
+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://github.com/dworznik/booksmart/tree/main/packages/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
+
+**Not published to PyPI yet** — install from the repo, which is private, so this
+needs an SSH key with access to it. `uv` clones the repo, resolves
+`booksmart-core` from the same checkout, and puts a `booksmart` command on your
+PATH:
+
+```console
+$ uv tool install "git+ssh://git@github.com/dworznik/booksmart.git#subdirectory=packages/cli"
+```
+
+Over HTTPS instead, with `gh auth login` (or a `repo`-scoped token) supplying git
+credentials:
+
+```console
+$ uv tool install "git+https://github.com/dworznik/booksmart.git#subdirectory=packages/cli"
+```
+
+Re-run with `--force` to pick up new commits. Once the first `cli-v*` tag ships,
+this becomes `uv tool install booksmart`, which pulls `booksmart-core` down as a
+dependency.
+
+## 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.

booksmart-0.1.0/README.md

@@ -0,0 +1,73 @@
+# booksmart
+
+The Booksmart CLI — turn books into queryable knowledge, locally.
+
+A single-user front end over
+[`booksmart-core`](https://github.com/dworznik/booksmart/tree/main/packages/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
+
+**Not published to PyPI yet** — install from the repo, which is private, so this
+needs an SSH key with access to it. `uv` clones the repo, resolves
+`booksmart-core` from the same checkout, and puts a `booksmart` command on your
+PATH:
+
+```console
+$ uv tool install "git+ssh://git@github.com/dworznik/booksmart.git#subdirectory=packages/cli"
+```
+
+Over HTTPS instead, with `gh auth login` (or a `repo`-scoped token) supplying git
+credentials:
+
+```console
+$ uv tool install "git+https://github.com/dworznik/booksmart.git#subdirectory=packages/cli"
+```
+
+Re-run with `--force` to pick up new commits. Once the first `cli-v*` tag ships,
+this becomes `uv tool install booksmart`, which pulls `booksmart-core` down as a
+dependency.
+
+## 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.

booksmart-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "booksmart"
+version = "0.1.0"
+description = "Booksmart CLI — a local, single-user front end over booksmart-core (embedded storage, no server)."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Patryk Dwórznik", email = "patryk@dworznik.com" }]
+dependencies = [
+    # Minor-pinned, and deliberately so: the CLI is a thin front end over core's
+    # public seams (Stage functions, Runner, search, VectorStore), and pre-1.0 a
+    # minor bump is where those may break. `[tool.uv.sources]` below only rewires
+    # this for local workspace development — the published wheel carries this
+    # constraint, so an unbounded requirement would let a future core install
+    # against a CLI that cannot drive it.
+    "booksmart-core>=0.1.0,<0.2.0",
+    "typer>=0.12.0",
+    "rich>=13.7.0",
+]
+
+[project.scripts]
+booksmart = "booksmart_cli.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/booksmart_cli"]
+
+[tool.uv.sources]
+booksmart-core = { workspace = true }

booksmart-0.1.0/src/booksmart_cli/errors.py

@@ -0,0 +1,42 @@
+"""CLI-facing errors.
+
+The pipeline's own failures are recorded on the Run (never raised out of
+``execute_run``); these cover the front-end concerns the removed HTTP layer used
+to answer with 4xx — an unsupported file, a duplicate, an unknown book. ``main``
+catches ``CliError`` and prints its message as one clean line, exit code 1."""
+
+
+class CliError(Exception):
+    """Base for expected, user-facing CLI failures (rendered as one line)."""
+
+
+class UnsupportedFileError(CliError):
+    """The file is not a supported format, by extension or by content (the old
+    ``415``)."""
+
+
+class DuplicateBookError(CliError):
+    """A byte-identical book is already registered (the old ``409``)."""
+
+    def __init__(self, existing_book_id: str) -> None:
+        super().__init__(
+            f"This file is already registered as book {existing_book_id} "
+            f"(byte-identical content)."
+        )
+        self.existing_book_id = existing_book_id
+
+
+class BookNotFoundError(CliError):
+    """No book with the given id (the old ``404``)."""
+
+
+class RunNotFoundError(CliError):
+    """No run with the given id (the old ``404`` on /jobs/{id})."""
+
+
+class KnowledgeNotFoundError(CliError):
+    """No knowledge object with the given id (the old ``404``)."""
+
+
+class NoProfileError(CliError):
+    """The book has no generated profile yet (the old ``404`` on /profile)."""