booksmart 0.1.0__py3-none-any.whl

booksmart-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+booksmart_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+booksmart_cli/errors.py,sha256=b3e-gfBNrJWQ7bO7vAI4Opnn9NGeHB1LzBdqV6LXMIc,1368
+booksmart_cli/main.py,sha256=xg8LyDmUsCaP6yqP1ZWBvzkpQazbdIHupHYjaSfUI98,16203
+booksmart_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+booksmart_cli/reads.py,sha256=zVCgDnk5CoYr4dE9-qjUPBaY3RGQPIlb4gdznCnBzYc,7366
+booksmart_cli/registration.py,sha256=NtgyyiQagpiPL8XKAQR79cRnbCKLRuuEhjJp41JarIE,4802
+booksmart_cli/runtime.py,sha256=HCt8kZ41U7uxXUPhBvPNeeoZGtWdpaJRMoPkeksfIfk,4834
+booksmart-0.1.0.dist-info/METADATA,sha256=bWgM34DMuinT0iqIql5nkfQapK5zbeZ8hp4ihEEdfdw,3215
+booksmart-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+booksmart-0.1.0.dist-info/entry_points.txt,sha256=j9LxhuL1tOqDnwj7wmqtDVPgeihNJhSUNYT1Sk_H6lg,53
+booksmart-0.1.0.dist-info/licenses/LICENSE,sha256=xoY93aB8kgbAVe7BD6cLNNd7iOyxZGcbJrS49Kaeats,1073
+booksmart-0.1.0.dist-info/RECORD,,

booksmart-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

booksmart-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+booksmart = booksmart_cli.main:app

booksmart-0.1.0.dist-info/licenses/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_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)."""

booksmart_cli/main.py

@@ -0,0 +1,449 @@
+"""Booksmart CLI — a local, single-user front end over booksmart-core.
+
+Register and ingest books, browse their runs, structure, profile and extracted
+knowledge, and search across everything embedded. Everything runs locally against
+an auto-migrated SQLite file and embedded Qdrant — no Docker, no Postgres, no
+server. Every command but ``search`` mirrors the removed HTTP surface exactly
+(docs/api-notes/); ``search`` is the first post-split feature (issue #30)."""
+
+import functools
+import uuid
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Optional, TypeVar
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from booksmart_core.errors import BooksmartError
+from booksmart_core.models import Book, KnowledgeObject, Run
+from booksmart_core.runner import SCOPE_STAGES, has_successful_run
+
+from booksmart_cli import reads, registration
+from booksmart_cli.errors import CliError
+from booksmart_cli.runtime import Runtime
+
+app = typer.Typer(
+    help="Booksmart — turn books into queryable knowledge, locally.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+books_app = typer.Typer(help="Register, list, inspect, and edit books.", no_args_is_help=True)
+runs_app = typer.Typer(help="Inspect ingestion run history.", no_args_is_help=True)
+knowledge_app = typer.Typer(help="Browse extracted knowledge objects.", no_args_is_help=True)
+app.add_typer(books_app, name="books")
+app.add_typer(runs_app, name="runs")
+app.add_typer(knowledge_app, name="knowledge")
+
+console = Console()
+
+F = TypeVar("F", bound=Callable[..., object])
+
+
+def _error(message: str) -> None:
+    """One red error line to stderr, via click's stream (captured in tests)."""
+    typer.secho(f"error: {message}", fg=typer.colors.RED, err=True)
+
+
+def _handle_errors(fn: F) -> F:
+    """Render expected failures (bad input, pipeline errors) as one clean line
+    and exit non-zero, instead of dumping a traceback. The pipeline's own
+    BooksmartError carries retriability for API consumers; the CLI stays human
+    and shows only the message."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: object, **kwargs: object) -> object:
+        try:
+            return fn(*args, **kwargs)
+        except (CliError, BooksmartError) as exc:
+            _error(str(exc))
+            raise typer.Exit(1) from exc
+
+    return wrapper  # type: ignore[return-value]
+
+
+def _parse_uuid(value: str) -> uuid.UUID:
+    try:
+        return uuid.UUID(value)
+    except ValueError:
+        raise CliError(f"Not a valid id: {value}") from None
+
+
+# --- add / ingest -----------------------------------------------------------
+
+
+@app.command()
+@_handle_errors
+def add(
+    file: Annotated[Path, typer.Argument(help="Path to a .pdf or .epub file.")],
+    title: Annotated[str, typer.Option(help="Book title (required).")],
+    author: Annotated[str, typer.Option(help="Book author (required).")],
+    edition: Annotated[Optional[str], typer.Option()] = None,
+    publication_year: Annotated[Optional[int], typer.Option()] = None,
+    isbn: Annotated[Optional[str], typer.Option()] = None,
+    primary_topic: Annotated[Optional[str], typer.Option()] = None,
+    language: Annotated[Optional[str], typer.Option()] = None,
+    framework: Annotated[Optional[str], typer.Option()] = None,
+    methodology: Annotated[Optional[str], typer.Option()] = None,
+    notes: Annotated[Optional[str], typer.Option()] = None,
+    trust_level: Annotated[Optional[str], typer.Option()] = None,
+    intended_use: Annotated[Optional[str], typer.Option()] = None,
+) -> None:
+    """Register a book from a local file (validate, dedup, store). Does not
+    ingest — run `booksmart ingest <id>` next."""
+    runtime = Runtime.load()
+    metadata: dict[str, object] = {
+        "edition": edition,
+        "publication_year": publication_year,
+        "isbn": isbn,
+        "primary_topic": primary_topic,
+        "language": language,
+        "framework": framework,
+        "methodology": methodology,
+        "notes": notes,
+        "trust_level": trust_level,
+        "intended_use": intended_use,
+    }
+    book = registration.register_book(
+        runtime, file, title=title, author=author, metadata=metadata
+    )
+    console.print(f"Registered [bold]{book.title}[/bold] as [cyan]{book.id}[/cyan]")
+
+
+@app.command()
+@_handle_errors
+def ingest(
+    book: Annotated[str, typer.Argument(help="Book id.")],
+    scope: Annotated[
+        str, typer.Option(help="full | profile | extraction | embeddings.")
+    ] = "full",
+) -> None:
+    """Run the pipeline over a book, foreground, streaming stage progress. Exits
+    non-zero if the run fails."""
+    if scope not in SCOPE_STAGES:
+        raise CliError(
+            f"Unknown scope {scope!r}; expected one of {', '.join(sorted(SCOPE_STAGES))}"
+        )
+    book_id = _parse_uuid(book)
+    runtime = Runtime.load()
+
+    # Incremental scopes build on a prior successful run (the old reprocess 409).
+    if scope != "full" and not _has_prior_success(runtime, book_id):
+        raise CliError(
+            f"Scope {scope!r} needs a prior successful run; run `ingest {book}` first"
+        )
+
+    console.print(f"Ingesting [cyan]{book_id}[/cyan] (scope: {scope})")
+    run_id = runtime.ingest(
+        book_id,
+        scope,
+        on_stage=lambda stage: console.print(f"  • {stage}…"),
+    )
+    run = reads.get_run(runtime, run_id)
+    if run.status == "succeeded":
+        console.print(f"[green]✓[/green] run [cyan]{run.id}[/cyan] succeeded")
+    else:
+        _error(f"run {run.id} failed: {run.error}")
+        raise typer.Exit(1)
+
+
+def _has_prior_success(runtime: Runtime, book_id: uuid.UUID) -> bool:
+    with runtime.session_factory() as session:
+        return has_successful_run(session, book_id)
+
+
+# --- books -------------------------------------------------------------------
+
+
+@books_app.command("list")
+@_handle_errors
+def books_list() -> None:
+    """List every registered book, oldest first."""
+    runtime = Runtime.load()
+    books = reads.list_books(runtime)
+    if not books:
+        console.print("No books registered yet. Add one with `booksmart add <file>`.")
+        return
+    table = Table("id", "title", "author", "format")
+    for book in books:
+        table.add_row(str(book.id), book.title, book.author, book.file_format)
+    console.print(table)
+
+
+@books_app.command("show")
+@_handle_errors
+def books_show(book: Annotated[str, typer.Argument(help="Book id.")]) -> None:
+    """Show one book's full metadata."""
+    runtime = Runtime.load()
+    _print_book_detail(reads.get_book(runtime, _parse_uuid(book)))
+
+
+@books_app.command("update")
+@_handle_errors
+def books_update(
+    book: Annotated[str, typer.Argument(help="Book id.")],
+    title: Annotated[Optional[str], typer.Option()] = None,
+    author: Annotated[Optional[str], typer.Option()] = None,
+    edition: Annotated[Optional[str], typer.Option()] = None,
+    # A string (not int) so an empty value can clear it, matching the other
+    # optional fields; a non-empty value must still parse as an integer.
+    publication_year: Annotated[Optional[str], typer.Option()] = None,
+    isbn: Annotated[Optional[str], typer.Option()] = None,
+    primary_topic: Annotated[Optional[str], typer.Option()] = None,
+    language: Annotated[Optional[str], typer.Option()] = None,
+    framework: Annotated[Optional[str], typer.Option()] = None,
+    methodology: Annotated[Optional[str], typer.Option()] = None,
+    notes: Annotated[Optional[str], typer.Option()] = None,
+    trust_level: Annotated[Optional[str], typer.Option()] = None,
+    intended_use: Annotated[Optional[str], typer.Option()] = None,
+) -> None:
+    """Edit a book's metadata. Only the flags you pass change; title/author can
+    be changed but not cleared; any other field clears with an empty value."""
+    if title is not None and not title.strip():
+        raise CliError("title may be changed but not cleared")
+    if author is not None and not author.strip():
+        raise CliError("author may be changed but not cleared")
+
+    # Only the flags the user actually passed become changes; title/author only
+    # ever set a new value, other fields also clear on an empty value (-> None).
+    provided: dict[str, Optional[str]] = {
+        "title": title,
+        "author": author,
+        "edition": edition,
+        "publication_year": publication_year,
+        "isbn": isbn,
+        "primary_topic": primary_topic,
+        "language": language,
+        "framework": framework,
+        "methodology": methodology,
+        "notes": notes,
+        "trust_level": trust_level,
+        "intended_use": intended_use,
+    }
+    changes: dict[str, object] = {}
+    for field, value in provided.items():
+        if value is None:
+            continue
+        if field in ("title", "author"):
+            changes[field] = value
+        elif value == "":
+            changes[field] = None  # explicit clear of an optional field
+        elif field == "publication_year":
+            changes[field] = _parse_year(value)
+        else:
+            changes[field] = value
+    if not changes:
+        raise CliError("Nothing to update; pass at least one field to change.")
+
+    runtime = Runtime.load()
+    _print_book_detail(registration.update_book(runtime, _parse_uuid(book), changes))
+
+
+def _parse_year(value: str) -> int:
+    try:
+        return int(value)
+    except ValueError:
+        raise CliError(f"publication-year must be an integer, got {value!r}") from None
+
+
+def _print_book_detail(book: Book) -> None:
+    table = Table("field", "value", show_header=False)
+    table.add_row("id", str(book.id))
+    table.add_row("title", book.title)
+    table.add_row("author", book.author)
+    for field in (*registration.METADATA_FIELDS, "file_format", "parser_used"):
+        value = getattr(book, field)
+        if value is not None:
+            table.add_row(field, str(value))
+    console.print(table)
+
+
+# --- runs --------------------------------------------------------------------
+
+
+@runs_app.command("list")
+@_handle_errors
+def runs_list(book: Annotated[str, typer.Argument(help="Book id.")]) -> None:
+    """A book's run history, oldest first (failures included)."""
+    runtime = Runtime.load()
+    runs = reads.list_runs(runtime, _parse_uuid(book))
+    if not runs:
+        console.print("No runs yet for this book.")
+        return
+    table = Table("id", "scope", "status", "created")
+    for run in runs:
+        table.add_row(str(run.id), run.scope, _status_markup(run.status), _when(run))
+    console.print(table)
+
+
+@runs_app.command("show")
+@_handle_errors
+def runs_show(run: Annotated[str, typer.Argument(help="Run id.")]) -> None:
+    """Show one run's outcome, versions, and token spend."""
+    runtime = Runtime.load()
+    run_row = reads.get_run(runtime, _parse_uuid(run))
+    table = Table("field", "value", show_header=False)
+    table.add_row("id", str(run_row.id))
+    table.add_row("book_id", str(run_row.book_id))
+    table.add_row("scope", run_row.scope)
+    table.add_row("status", _status_markup(run_row.status))
+    for field in (
+        "error",
+        "parser_used",
+        "extraction_version",
+        "model_version",
+        "prompt_version",
+        "input_tokens",
+        "output_tokens",
+    ):
+        value = getattr(run_row, field)
+        if value is not None:
+            table.add_row(field, str(value))
+    console.print(table)
+
+
+def _status_markup(status: str) -> str:
+    colour = {"succeeded": "green", "failed": "red", "running": "yellow"}.get(status, "white")
+    return f"[{colour}]{status}[/{colour}]"
+
+
+def _when(run: Run) -> str:
+    return run.created_at.isoformat() if run.created_at else ""
+
+
+# --- structure / profile -----------------------------------------------------
+
+
+@app.command()
+@_handle_errors
+def structure(book: Annotated[str, typer.Argument(help="Book id.")]) -> None:
+    """Show a book's detected chapter/section tree."""
+    runtime = Runtime.load()
+    chapters = reads.book_structure(runtime, _parse_uuid(book))
+    if not chapters:
+        console.print("No structure yet; run an ingest first.")
+        return
+    for chapter in chapters:
+        suffix = "" if chapter.kind == "chapter" else f" [dim]({chapter.kind})[/dim]"
+        console.print(f"[bold]{chapter.position + 1}. {chapter.title}[/bold]{suffix}")
+        for section in chapter.sections:
+            console.print(f"    {section.position + 1}. {section.title}")
+
+
+@app.command()
+@_handle_errors
+def profile(book: Annotated[str, typer.Argument(help="Book id.")]) -> None:
+    """Show a book's latest generated profile."""
+    runtime = Runtime.load()
+    book_profile = reads.latest_profile(runtime, _parse_uuid(book))
+    console.print(book_profile.content)
+    console.print(
+        f"[dim]— {book_profile.model} (prompt v{book_profile.prompt_version})[/dim]"
+    )
+
+
+# --- knowledge ---------------------------------------------------------------
+
+
+@knowledge_app.command("list")
+@_handle_errors
+def knowledge_list(
+    book: Annotated[str, typer.Argument(help="Book id.")],
+    type: Annotated[Optional[str], typer.Option(help="Filter by knowledge type.")] = None,
+) -> None:
+    """List a book's extracted knowledge objects."""
+    runtime = Runtime.load()
+    objects = reads.list_knowledge(runtime, _parse_uuid(book), type)
+    if not objects:
+        console.print("No knowledge objects for this book.")
+        return
+    table = Table("id", "type", "title", "confidence")
+    for obj in objects:
+        table.add_row(str(obj.id), obj.type, obj.title, f"{obj.confidence:.2f}")
+    console.print(table)
+
+
+@knowledge_app.command("show")
+@_handle_errors
+def knowledge_show(
+    object_id: Annotated[str, typer.Argument(help="Knowledge object id.")],
+) -> None:
+    """Show one knowledge object in full."""
+    runtime = Runtime.load()
+    _print_knowledge_detail(reads.get_knowledge(runtime, _parse_uuid(object_id)))
+
+
+# --- search ------------------------------------------------------------------
+
+SEARCH_SCOPE_ALL = "all"
+
+
+@app.command()
+@_handle_errors
+def search(
+    scope: Annotated[
+        str, typer.Argument(help="Book id to search within, or `all` for every book.")
+    ],
+    query: Annotated[str, typer.Argument(help="What to look for, in plain language.")],
+    type: Annotated[
+        Optional[list[str]],
+        typer.Option(help="Restrict to a record type; repeatable."),
+    ] = None,
+    limit: Annotated[int, typer.Option(help="Maximum number of hits.")] = 10,
+    score_threshold: Annotated[
+        Optional[float],
+        typer.Option(help="Drop hits below this cosine similarity (-1 to 1)."),
+    ] = None,
+) -> None:
+    """Find the chapters, sections and knowledge objects most similar to a query.
+
+    Searches the embeddings an ingest produced, so a book has to be ingested
+    before it can be found.
+    """
+    book_id = None if scope == SEARCH_SCOPE_ALL else _parse_uuid(scope)
+    runtime = Runtime.load()
+    hits = reads.semantic_search(
+        runtime,
+        query,
+        book_id=book_id,
+        record_types=type,
+        limit=limit,
+        score_threshold=score_threshold,
+    )
+    if not hits:
+        console.print("No matches. Ingest a book first, or try a broader query.")
+        return
+
+    table = Table("score", "type", "title", "match")
+    if book_id is None:
+        table.add_column("book")
+    for hit in hits:
+        row = [f"{hit.score:.3f}", hit.record_type, hit.title, _snippet(hit.text)]
+        if book_id is None:
+            row.append(str(hit.book_id))
+        table.add_row(*row)
+    console.print(table)
+
+
+def _snippet(text: str, width: int = 60) -> str:
+    """The embedded text as one line, short enough to sit in a table cell."""
+    flattened = " ".join(text.split())
+    if len(flattened) <= width:
+        return flattened
+    return flattened[: width - 1].rstrip() + "…"
+
+
+def _print_knowledge_detail(obj: KnowledgeObject) -> None:
+    console.print(f"[bold]{obj.type}: {obj.title}[/bold]")
+    console.print(obj.summary)
+    console.print()
+    console.print(obj.content)
+    console.print(
+        f"[dim]source: {obj.source_location} · confidence {obj.confidence:.2f} · "
+        f"{obj.extraction_model}[/dim]"
+    )
+
+
+if __name__ == "__main__":
+    app()

booksmart_cli/reads.py

@@ -0,0 +1,214 @@
+"""Read queries behind the display commands — the shapes the removed GET routers
+served (see docs/api-notes/http-surface.md and the conftest read-model helpers).
+
+Each opens a short session and returns detached ORM rows (or plain dicts for the
+chapter/section tree, whose relationship would otherwise lazy-load after the
+session closes), so command code can render without holding a session open.
+"""
+
+import uuid
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import cast
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from booksmart_core.extraction import KNOWLEDGE_OBJECT_TYPES
+from booksmart_core.llm import build_embedding_provider
+from booksmart_core.models import Book, BookProfile, Chapter, KnowledgeObject, Run
+from booksmart_core.search import SearchHit
+from booksmart_core.search import search as core_search
+from booksmart_core.vectors import (
+    RECORD_TYPES,
+    RecordType,
+    build_vector_store,
+    unknown_record_types,
+)
+
+from booksmart_cli.errors import (
+    BookNotFoundError,
+    CliError,
+    KnowledgeNotFoundError,
+    NoProfileError,
+    RunNotFoundError,
+)
+from booksmart_cli.runtime import Runtime
+
+
+@dataclass(frozen=True)
+class SectionView:
+    position: int
+    title: str
+
+
+@dataclass(frozen=True)
+class ChapterView:
+    position: int
+    title: str
+    kind: str
+    sections: list[SectionView]
+
+
+def _require_book(session: Session, book_id: uuid.UUID) -> Book:
+    book = session.get(Book, book_id)
+    if book is None:
+        raise BookNotFoundError(f"No book with id {book_id}")
+    return book
+
+
+def list_books(runtime: Runtime) -> list[Book]:
+    """Every book, oldest first (the old GET /books)."""
+    with runtime.session_factory() as session:
+        books = list(session.scalars(select(Book).order_by(Book.uploaded_at, Book.id)))
+        session.expunge_all()
+    return books
+
+
+def get_book(runtime: Runtime, book_id: uuid.UUID) -> Book:
+    with runtime.session_factory() as session:
+        book = _require_book(session, book_id)
+        session.expunge(book)
+    return book
+
+
+def book_structure(runtime: Runtime, book_id: uuid.UUID) -> list[ChapterView]:
+    """The chapter/section tree (the old GET /books/{id}/structure)."""
+    with runtime.session_factory() as session:
+        _require_book(session, book_id)
+        chapters = session.scalars(
+            select(Chapter).where(Chapter.book_id == book_id).order_by(Chapter.position)
+        )
+        return [
+            ChapterView(
+                position=chapter.position,
+                title=chapter.title,
+                kind=chapter.kind,
+                sections=[
+                    SectionView(position=section.position, title=section.title)
+                    for section in chapter.sections
+                ],
+            )
+            for chapter in chapters
+        ]
+
+
+def latest_profile(runtime: Runtime, book_id: uuid.UUID) -> BookProfile:
+    """The newest generated profile (the old GET /books/{id}/profile)."""
+    with runtime.session_factory() as session:
+        _require_book(session, book_id)
+        profile = session.scalars(
+            select(BookProfile)
+            .where(BookProfile.book_id == book_id)
+            .order_by(BookProfile.created_at.desc(), BookProfile.id.desc())
+            .limit(1)
+        ).first()
+        if profile is None:
+            raise NoProfileError(f"Book {book_id} has no profile yet; run an ingest first")
+        session.expunge(profile)
+    return profile
+
+
+def list_runs(runtime: Runtime, book_id: uuid.UUID) -> list[Run]:
+    """A book's run history, oldest first (the old GET /books/{id}/jobs)."""
+    with runtime.session_factory() as session:
+        _require_book(session, book_id)
+        runs = list(
+            session.scalars(
+                select(Run).where(Run.book_id == book_id).order_by(Run.created_at, Run.id)
+            )
+        )
+        session.expunge_all()
+    return runs
+
+
+def get_run(runtime: Runtime, run_id: uuid.UUID) -> Run:
+    with runtime.session_factory() as session:
+        run = session.get(Run, run_id)
+        if run is None:
+            raise RunNotFoundError(f"No run with id {run_id}")
+        session.expunge(run)
+    return run
+
+
+def list_knowledge(
+    runtime: Runtime, book_id: uuid.UUID, type_filter: str | None = None
+) -> list[KnowledgeObject]:
+    """A book's knowledge objects (the old GET /books/{id}/knowledge-objects)."""
+    if type_filter is not None and type_filter not in KNOWLEDGE_OBJECT_TYPES:
+        raise CliError(
+            f"Unknown knowledge type {type_filter!r}; expected one of "
+            f"{', '.join(sorted(KNOWLEDGE_OBJECT_TYPES))}"
+        )
+    with runtime.session_factory() as session:
+        _require_book(session, book_id)
+        query = (
+            select(KnowledgeObject)
+            .where(KnowledgeObject.book_id == book_id)
+            .order_by(KnowledgeObject.created_at, KnowledgeObject.id)
+        )
+        if type_filter is not None:
+            query = query.where(KnowledgeObject.type == type_filter)
+        objects = list(session.scalars(query))
+        session.expunge_all()
+    return objects
+
+
+def get_knowledge(runtime: Runtime, object_id: uuid.UUID) -> KnowledgeObject:
+    with runtime.session_factory() as session:
+        obj = session.get(KnowledgeObject, object_id)
+        if obj is None:
+            raise KnowledgeNotFoundError(f"No knowledge object with id {object_id}")
+        session.expunge(obj)
+    return obj
+
+
+def semantic_search(
+    runtime: Runtime,
+    query: str,
+    *,
+    book_id: uuid.UUID | None = None,
+    record_types: Sequence[str] | None = None,
+    limit: int = 10,
+    score_threshold: float | None = None,
+) -> list[SearchHit]:
+    """Rank embedded records against a natural-language query (no HTTP ancestor —
+    this is the first post-split feature, issue #30).
+
+    Validates the user's input before building any provider, so a typo'd book id
+    or record type never demands an embedding API key. The embedded Qdrant client
+    is closed on the way out: it holds a single-process lock on the on-disk
+    directory, and the next command has to be able to open it."""
+    if not query.strip():
+        raise CliError("Search query must not be empty")
+    if limit < 1:
+        raise CliError(f"--limit must be at least 1, got {limit}")
+    unknown = unknown_record_types(record_types or ())
+    if unknown:
+        raise CliError(
+            f"Unknown record type {', '.join(repr(name) for name in unknown)}; "
+            f"expected one of {', '.join(RECORD_TYPES)}"
+        )
+    if book_id is not None:
+        with runtime.session_factory() as session:
+            _require_book(session, book_id)
+
+    embedder = build_embedding_provider(runtime.settings)
+    vector_store = build_vector_store(runtime.settings)
+    try:
+        with runtime.session_factory() as session:
+            return core_search(
+                session,
+                vector_store,
+                embedder,
+                query,
+                book_id=book_id,
+                # Validated against RECORD_TYPES above.
+                record_types=(
+                    cast("list[RecordType]", list(record_types)) if record_types else None
+                ),
+                limit=limit,
+                score_threshold=score_threshold,
+            )
+    finally:
+        vector_store.close()

booksmart_cli/registration.py

@@ -0,0 +1,144 @@
+"""Book registration: the validation, dedup, and storage the removed upload
+endpoint owned (docs/api-notes/upload-validation.md), ported for a local file
+path instead of a multipart stream.
+"""
+
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+from sqlalchemy import select
+
+from booksmart_core.models import Book
+from booksmart_core.storage import hash_stream
+
+from booksmart_cli.errors import (
+    BookNotFoundError,
+    CliError,
+    DuplicateBookError,
+    UnsupportedFileError,
+)
+from booksmart_cli.runtime import Runtime
+
+
+@dataclass(frozen=True)
+class SupportedFormat:
+    name: str
+    magic: bytes
+
+
+# Suffix must match AND the leading bytes must match — a .pdf of HTML is
+# rejected. EPUB is a ZIP container, so its magic is the ZIP local-file header.
+SUPPORTED_FORMATS = {
+    ".pdf": SupportedFormat("pdf", b"%PDF"),
+    ".epub": SupportedFormat("epub", b"PK\x03\x04"),
+}
+
+# The optional bibliographic metadata + hints a user may set on `add`/`update`
+# — the single source of truth for what is editable and what `books show`
+# prints. File-provenance columns (storage_path, checksum, file_hash, …) are
+# never here: the old PATCH rejected them 422, and the CLI never exposes them.
+METADATA_FIELDS = (
+    "edition",
+    "publication_year",
+    "isbn",
+    "primary_topic",
+    "language",
+    "framework",
+    "methodology",
+    "notes",
+    "trust_level",
+    "intended_use",
+)
+
+
+def validated_format(path: Path) -> str:
+    """Format name if ``path``'s suffix and magic bytes agree, else raise."""
+    supported = SUPPORTED_FORMATS.get(path.suffix.lower())
+    if supported is None:
+        raise UnsupportedFileError(
+            f"Unsupported file type {path.suffix or '(none)'}; expected .pdf or .epub"
+        )
+    with path.open("rb") as stream:
+        header = stream.read(len(supported.magic))
+    if not header.startswith(supported.magic):
+        raise UnsupportedFileError(
+            f"File content does not look like a {supported.name.upper()} file"
+        )
+    return supported.name
+
+
+def register_book(
+    runtime: Runtime,
+    path: Path,
+    *,
+    title: str,
+    author: str,
+    metadata: dict[str, object] | None = None,
+) -> Book:
+    """Validate the file, reject a byte-identical duplicate, store the original,
+    and persist the Book row — rolling the stored file back if the insert fails.
+    Returns the persisted (detached) Book."""
+    if not path.is_file():
+        raise UnsupportedFileError(f"No such file: {path}")
+    file_format = validated_format(path)
+
+    with path.open("rb") as stream:
+        file_hash = hash_stream(stream)
+
+    with runtime.session_factory() as session:
+        existing = session.scalars(
+            select(Book).where(Book.file_hash == file_hash)
+        ).first()
+        if existing is not None:
+            raise DuplicateBookError(str(existing.id))
+
+    book_id = uuid.uuid4()
+    with path.open("rb") as stream:
+        stored = runtime.storage.save_original(book_id, path.name, stream, file_hash)
+
+    book = Book(
+        id=book_id,
+        title=title,
+        author=author,
+        original_filename=stored.path.name,
+        file_format=file_format,
+        storage_path=str(stored.path),
+        checksum=stored.checksum,
+        file_hash=stored.file_hash,
+        **{k: v for k, v in (metadata or {}).items() if v is not None},
+    )
+    try:
+        with runtime.session_factory() as session:
+            session.add(book)
+            session.commit()
+            session.refresh(book)
+            session.expunge(book)
+    except Exception:
+        # Store-then-rollback guard: drop the orphaned original if the DB
+        # insert fails, so a failed registration leaves nothing behind.
+        runtime.storage.discard(book_id)
+        raise
+    return book
+
+
+def update_book(runtime: Runtime, book_id: uuid.UUID, changes: dict[str, object]) -> Book:
+    """Apply metadata changes to a book. ``title``/``author`` may be changed but
+    not cleared; any editable field may be set or cleared (``None``). Absent keys
+    are untouched. Returns the updated (detached) Book."""
+    allowed = {"title", "author", *METADATA_FIELDS}
+    unknown = set(changes) - allowed
+    if unknown:
+        # Guards against a caller reaching a file-provenance column; the old
+        # PATCH answered 422 for these, the CLI never exposes them.
+        raise CliError(f"Fields are not editable: {', '.join(sorted(unknown))}")
+    with runtime.session_factory() as session:
+        book = session.get(Book, book_id)
+        if book is None:
+            raise BookNotFoundError(f"No book with id {book_id}")
+        for field, value in changes.items():
+            setattr(book, field, value)
+        session.commit()
+        session.refresh(book)
+        session.expunge(book)
+    return book

booksmart_cli/runtime.py

@@ -0,0 +1,119 @@
+"""The CLI's local runtime: home-dir settings, an auto-migrated SQLite database,
+embedded Qdrant, and a synchronous foreground Runner.
+
+Everything lives under one home directory (``~/.booksmart`` by default) so the
+whole installation is a single portable data dir — the SQLite file, ``storage/``,
+and the embedded Qdrant directory move together (issue #25's portability, proven
+end to end by the CLI e2e). No Docker, no Postgres, no server.
+"""
+
+import os
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from sqlalchemy.orm import Session, sessionmaker
+
+from booksmart_core.config import Settings
+from booksmart_core.database import create_engine, upgrade_to_head
+from booksmart_core.llm import (
+    EmbeddingProvider,
+    LLMProvider,
+    build_embedding_provider,
+    build_llm_provider,
+)
+from booksmart_core.runner import SCOPE_STAGES, execute_run
+from booksmart_core.stages import LLM_STAGES, Stage
+from booksmart_core.storage import BookStorage
+from booksmart_core.vectors import VectorStore, build_vector_store
+
+
+def default_home() -> Path:
+    """The CLI's home directory: ``$BOOKSMART_HOME`` or ``~/.booksmart``."""
+    return Path(os.environ.get("BOOKSMART_HOME") or Path.home() / ".booksmart")
+
+
+def load_settings(home: Path | None = None) -> Settings:
+    """Settings pointed at the local home dir, with env still able to override.
+
+    Only the location fields default to the home dir, and only when the matching
+    ``BOOKSMART_*`` env var is unset — so ``BOOKSMART_DATABASE_URL`` /
+    ``BOOKSMART_STORAGE_ROOT`` still win, and setting ``BOOKSMART_QDRANT_URL``
+    opts out of embedded Qdrant onto a server. Everything else (provider, model,
+    API keys) comes from the environment as usual."""
+    home = home or default_home()
+    home.mkdir(parents=True, exist_ok=True)
+
+    overrides: dict[str, object] = {}
+    if "BOOKSMART_DATABASE_URL" not in os.environ:
+        overrides["database_url"] = f"sqlite:///{home / 'booksmart.db'}"
+    if "BOOKSMART_STORAGE_ROOT" not in os.environ:
+        overrides["storage_root"] = home / "storage"
+    # Embedded Qdrant unless the user pointed us at a server explicitly.
+    if "BOOKSMART_QDRANT_URL" not in os.environ:
+        overrides["qdrant_path"] = home / "qdrant"
+    return Settings(**overrides)  # type: ignore[arg-type]
+
+
+def _build_providers(
+    settings: Settings, scope: str
+) -> tuple[LLMProvider | None, EmbeddingProvider | None, VectorStore | None]:
+    """Build only the providers this scope's stages need — so a profile-only run
+    never constructs an embedder, and an embeddings-only run never an LLM."""
+    stages = SCOPE_STAGES.get(scope, ())
+    llm = build_llm_provider(settings) if any(s in LLM_STAGES for s in stages) else None
+    embedder = build_embedding_provider(settings) if "embeddings" in stages else None
+    vector_store = build_vector_store(settings) if "embeddings" in stages else None
+    return llm, embedder, vector_store
+
+
+@dataclass
+class Runtime:
+    """A ready-to-use local environment: settings, a migrated session factory,
+    and object storage. Build it once per command with ``Runtime.load()``."""
+
+    settings: Settings
+    session_factory: sessionmaker[Session]
+    storage: BookStorage
+
+    @classmethod
+    def load(cls, home: Path | None = None) -> "Runtime":
+        """Resolve settings, auto-migrate the SQLite file to head (invisible to
+        the user), and wire up storage."""
+        settings = load_settings(home)
+        upgrade_to_head(settings.database_url)
+        engine = create_engine(settings.database_url)
+        return cls(
+            settings=settings,
+            session_factory=sessionmaker(bind=engine),
+            storage=BookStorage(settings.storage_root),
+        )
+
+    def ingest(
+        self,
+        book_id: uuid.UUID,
+        scope: str = "full",
+        *,
+        on_stage: Callable[[Stage], None] | None = None,
+    ) -> uuid.UUID:
+        """Run a scope over a book to completion, foreground and synchronous,
+        streaming stage progress through ``on_stage``. Returns the Run id; the
+        outcome is recorded on the Run (this never raises for a Stage failure)."""
+        llm, embedder, vector_store = _build_providers(self.settings, scope)
+        try:
+            return execute_run(
+                self.session_factory,
+                self.settings.storage_root,
+                book_id,
+                scope,
+                llm=llm,
+                embedder=embedder,
+                vector_store=vector_store,
+                on_stage=on_stage,
+            )
+        finally:
+            # Release the embedded Qdrant on-disk lock so the next command (or a
+            # relocated copy of the data dir) can open it.
+            if vector_store is not None:
+                vector_store.close()