estravon-backend 0.1.4__tar.gz

estravon_backend-0.1.4/LICENSE

@@ -0,0 +1,22 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 Zotero Marker Contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published
+by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+The full license text is available at:
+https://www.gnu.org/licenses/agpl-3.0.txt

estravon_backend-0.1.4/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: estravon-backend
+Version: 0.1.4
+Summary: FastHTML backend for Zotero Book Markdown Extractor
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: python-fasthtml<1.0,>=0.12.0
+Requires-Dist: replicate<2.0,>=0.34.0
+Requires-Dist: httpx<1.0,>=0.27.0
+Requires-Dist: python-multipart<1.0,>=0.0.9
+Requires-Dist: python-dotenv<2.0,>=1.0.0
+Requires-Dist: pypdf[cryptography]>=4.0
+Requires-Dist: mistralai<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Provides-Extra: nlp
+Requires-Dist: spacy>=3.7; extra == "nlp"
+Dynamic: license-file

estravon_backend-0.1.4/README.md

@@ -0,0 +1,143 @@
+# Estravon — self-hosted backend
+
+Extract nominated sections of a book PDF as Markdown and attach them directly
+to the Zotero item — synced, versioned, always co-located with the source.
+
+The extracted `.md` files include full provenance metadata (pages, backend,
+extraction date, schema version) and content statistics (word counts, vocabulary
+profile). They can be read in Zotero, searched, and fed into downstream tools.
+
+---
+
+## Two ways to use Estravon
+
+**Hosted (no setup):** visit [estravon.com](https://estravon.com), buy a credit pack,
+paste one API key into the plugin preferences, and start extracting. Nothing to install
+or maintain on your machine.
+
+**Self-hosted (this repo):** run the backend on your own machine with your own Mistral
+API key. AGPL-3.0. Full control, no ongoing cost beyond your Mistral usage.
+
+---
+
+## Prerequisites (self-hosted)
+
+- **Zotero 7.0** or newer
+- **Python 3.10+**
+- An API key for one of the supported extraction backends:
+
+| Backend | Pricing | Notes |
+|---|---|---|
+| [Mistral](https://console.mistral.ai/) | Pay-as-you-go | Default. No subscription needed. |
+| [Datalab](https://www.datalab.to/) | $25/month flat | Single-user subscription. Slightly higher throughput at peak. |
+| [Replicate](https://replicate.com/) | Pay-as-you-go | Runs the same Datalab model but without concurrency; lower idle cost. |
+
+Set `_ZM_BACKEND=mistral` (default), `_ZM_BACKEND=datalab`, or `_ZM_BACKEND=replicate`
+in your `.env` file to choose.
+
+---
+
+## Installation
+
+### 1 — Install the Zotero plugin
+
+Download `estravon-<version>.xpi` from the
+[latest GitHub Release](../../releases/latest).
+
+In Zotero: **Tools → Plugins → Install Add-on From File…** → select the `.xpi`.
+
+After the initial install the plugin auto-updates via Zotero's built-in update
+mechanism — no manual action needed for future releases.
+
+On first launch the plugin opens `estravon.com/start` in your browser; follow the
+"Make it yourself" path to set up the self-hosted backend.
+
+### 2 — Install and start the Python backend
+
+```bash
+pip install estravon-backend
+```
+
+Copy the example environment file and add your API key:
+
+```bash
+cp .env.example .env
+# Edit .env: set MISTRAL_API_KEY (or DATALAB_API_KEY / REPLICATE_API_TOKEN)
+# Optionally set _ZM_BACKEND=datalab or _ZM_BACKEND=replicate to switch backends
+```
+
+Start the backend:
+
+```bash
+estravon --port 7766
+```
+
+Keep this terminal running while you use the plugin. In Zotero → Settings → Estravon,
+confirm the status indicator is green.
+
+---
+
+## First extraction
+
+1. Open Zotero and right-click a **Book** item that has a PDF attachment.
+2. Select **Extract Section to Markdown…**
+3. Fill in the section name (e.g. `chapter_1`), page range (e.g. `1-40`),
+   and extraction mode (`balanced` is a good default).
+4. Click **Extract** and wait. The backend calls the Mistral OCR API and returns
+   when done (typically 30–90 seconds for 40 pages).
+5. The extracted `.md` file and any images appear as child attachments on the
+   Zotero item. An **Extraction log** child note records the provenance.
+
+---
+
+## Configuration
+
+Plugin preferences are in **Zotero → Settings → Estravon**:
+
+| Preference | Default | Description |
+|---|---|---|
+| Backend URL | `http://localhost:7766` | Self-hosted backend address |
+| Default chunk size | `80` | Pages per API call (reduce for large scanned books) |
+| Default mode | `balanced` | `fast` / `balanced` / `accurate` |
+
+---
+
+## Checking backend health
+
+```bash
+curl http://localhost:7766/ping
+# {"status":"ok","state":"idle","backend":"mistral"}
+
+curl http://localhost:7766/status
+# {"state":"idle","state_since_s":12.3,"backend":"mistral","last_job":{}}
+```
+
+The `/status` endpoint shows the current server state (idle / running / error) and
+the details of the last job — useful for debugging without SSH access.
+
+---
+
+## Roadmap
+
+**v0.4.x (now):** Self-hosted vanilla backend + Zotero plugin. Uses Mistral OCR.
+
+**v0.5.x:** Plugin session telemetry (`/jobs/{id}/ack`); per-chunk quality scores.
+
+**Post-launch:** LLM agent that extracts all chapters from a book autonomously
+(requires the tools server — separate repository, not yet public).
+
+---
+
+## Issues and feedback
+
+Please report bugs and feature requests via
+[GitHub Issues](../../issues).
+
+Feedback on extraction quality for scanned books, non-English texts, or books with
+heavy mathematical notation is especially welcome.
+
+---
+
+## License
+
+[AGPL-3.0](LICENSE) — the same license as Zotero itself.

estravon_backend-0.1.4/estravon/__init__.py

@@ -0,0 +1,3 @@
+"""Estravon backend — PDF extraction pipeline."""
+
+__version__ = "0.1.0"

estravon_backend-0.1.4/estravon/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for ``python -m estravon``."""
+
+from estravon.server import main
+
+main()