Petr Polezhaev
084d1aebd5
Photo-based book cataloger with AI identification. Room → Cabinet → Shelf → Book hierarchy; FastAPI + SQLite backend; vanilla JS SPA; OpenAI-compatible plugin system for boundary detection, text recognition, and archive search.
74 lines
2.4 KiB
Markdown
74 lines
2.4 KiB
Markdown
# Bookshelf
|
|
|
|
Photo-based book cataloger. Organizes books in a Room -> Cabinet -> Shelf -> Book hierarchy. Photographs shelf spines; AI plugins identify books and look up metadata in library archives.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.11+, [Poetry](https://python-poetry.org/)
|
|
- An OpenAI-compatible API endpoint (OpenRouter recommended)
|
|
|
|
## Setup
|
|
|
|
```
|
|
poetry install
|
|
```
|
|
|
|
Create `config/credentials.user.yaml` with your API key:
|
|
|
|
```yaml
|
|
credentials:
|
|
openrouter:
|
|
api_key: "sk-or-your-key-here"
|
|
```
|
|
|
|
Start the server:
|
|
|
|
```
|
|
poetry run serve
|
|
```
|
|
|
|
Open `http://localhost:8000` in a browser.
|
|
|
|
## Configuration
|
|
|
|
Config is loaded from `config/*.default.yaml` merged with `config/*.user.yaml` overrides. User files take precedence; dicts merge recursively, lists replace entirely. User files are gitignored.
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `credentials.default.yaml` | API endpoints and keys |
|
|
| `models.default.yaml` | Model selection and prompts per AI function |
|
|
| `functions.default.yaml` | Plugin definitions (boundary detection, text recognition, identification, archive search) |
|
|
| `ui.default.yaml` | UI display settings |
|
|
|
|
To use a different model for a function, create `config/models.user.yaml`:
|
|
|
|
```yaml
|
|
models:
|
|
vl_recognize:
|
|
credentials: openrouter
|
|
model: "google/gemini-2.0-flash"
|
|
```
|
|
|
|
To add an alternative provider, add it to `config/credentials.user.yaml` and reference it in `models.user.yaml`.
|
|
|
|
## Usage
|
|
|
|
1. Add a room, then cabinets and shelves using the tree in the sidebar.
|
|
2. Upload a photo of each cabinet or shelf.
|
|
3. Drag boundary lines on the photo to segment shelves (or books within a shelf). The AI boundary detector can suggest splits automatically.
|
|
4. Run the text recognizer on a book to extract spine text, then the book identifier to match it against library archives.
|
|
5. Review and approve AI suggestions in the detail panel. Use the batch button to process all unidentified books at once.
|
|
6. On mobile, use the photo queue button on a cabinet or shelf to photograph books one by one with automatic AI processing.
|
|
|
|
## Development
|
|
|
|
```
|
|
poetry run presubmit # black check + flake8 + pyright + pytest + JS tests
|
|
poetry run fmt # auto-format Python with black
|
|
npm install # install JS dev tools (ESLint, Prettier) — requires network
|
|
npm run lint # ESLint
|
|
npm run fmt # Prettier
|
|
```
|
|
|
|
Tests are in `tests/` (Python) and `tests/js/` (JavaScript).
|