Patron of Alexandria is a lightweight desktop client for the Librarian of Alexandria RAG backend.
It gives you a clean, focused chat and upload interface to your private Librarian instance. The heavy lifting (RAG, embeddings, indexing, LLM calls) lives entirely on the Librarian backend – Patron is the “reading room” and chat terminal.
- Overview
- Features
- Architecture
- System Requirements
- Installation
- Configuration
- Running the App
- Using Patron
- Network & Security Notes
- Troubleshooting
- For Developers
- License
Patron of Alexandria is a simple, opinionated desktop client for the Librarian of Alexandria retrieval‑augmented generation (RAG) backend.
It is designed to:
- Give you a dedicated chat and upload interface for your Librarian instance.
- Keep RAG logic, embeddings, and models on the server side.
- Keep the client UI clean, text‑first, and focused on research and reading.
- Fit visually into the Botwin ecosystem (creme + mint‑green aesthetic).
Patron does not run models or embeddings locally. It simply connects to a Librarian API that you host and control.
-
🗨️ Clean chat interface
Ask questions and get answers from your Librarian of Alexandria backend in a conversation-style layout. -
📄 One-click document uploads
Select files from your desktop and send them to your Librarian upload endpoint for ingestion and indexing. -
🌐 Configurable API endpoint
Set the base Librarian API URL and API key in the top bar. Point Patron at any Librarian instance you own (local, LAN, VPN, or remote). -
🎛 Light / dark theme toggle
Switch between a creme-based light mode and a dark, mint-accented theme designed for longer reading sessions. -
🧩 Thin backend proxy
A small local FastAPI service forwards chat and upload requests to Librarian, keeping API keys and network details out of the frontend. -
🧱 Simple architecture
Vite + React frontend, FastAPI backend proxy, standard HTTP calls to Librarian’s documented API.
At a high level:
+--------------------+ HTTP +------------------------+
| Patron Frontend | <------------> | Local Backend Proxy |
| (Vite + React) | | (FastAPI) |
+--------------------+ +-----------+------------+
|
| HTTP(S)
v
+------------------------+
| Librarian of Alexandria|
| (RAG backend) |
+------------------------+
- The frontend renders the UI and talks only to the local proxy.
- The local proxy stores the Librarian API URL + API key and forwards requests to the Librarian backend.
- The Librarian backend handles:
- Document ingestion and indexing
- Retrieval and reranking
- LLM calls and final answer generation
- Windows: supported (development target).
- macOS: planned / supported depending on how you package and ship the app.
- A running Librarian of Alexandria deployment with:
- An accessible API base URL (HTTP or HTTPS).
- A configured API key for client access.
- A network path from the machine running Patron to your Librarian backend
- Same machine, LAN, VPN, or public HTTPS endpoint.
Note: Patron does not ship with Librarian. You are responsible for deploying and securing your own Librarian of Alexandria instance.
These steps assume you are comfortable with Node.js, npm, Python, and virtual environments.
git clone https://github.com/your-org/patron-of-alexandria.git
cd patron-of-alexandria(Replace the URL above with the actual repo URL.)
From the project root (or frontend subfolder if you have one):
npm installTo run the dev server:
npm run devThis will start the Vite dev server, typically at:
http://localhost:5173
or another port depending on your config.
In the backend/ folder:
cd backend
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txtRun the local backend proxy:
uvicorn main:app --reload --host 127.0.0.1 --port 5055- The frontend should be configured to talk to this local proxy (e.g.
http://127.0.0.1:5055). - The proxy will then forward requests to your Librarian API based on the configuration you set in the UI.
Configuration is done from inside the Patron UI via the top bar.
Enter the base URL of your Librarian of Alexandria backend, for example:
http://your-librarian-host:8000
or
https://your-librarian-domain.example.com
Do not include endpoint paths (like /api/chat or /api/documents). Patron’s backend proxy will append those as needed.
Enter your Librarian API key in the API key field.
- Treat this like a password.
- Do not commit it to source control.
- Do not share screenshots that contain the raw key.
When you click Connect, the frontend sends these values to the local proxy, which stores them in memory and uses them for all subsequent requests to Librarian.
In development, you’ll typically have:
- Vite dev server for the frontend.
- Uvicorn for the local proxy.
- Your Librarian backend running elsewhere.
Example:
# Terminal 1 – Patron backend proxy
cd backend
source .venv/bin/activate
uvicorn main:app --reload --host 127.0.0.1 --port 5055# Terminal 2 – Patron frontend
npm run devThen open the Vite dev URL in your browser.
You can also create a small launcher script or a packaged app that:
- Starts the local backend proxy.
- Starts the frontend (or opens a packaged UI) in its own window.
- Optionally uses a custom app icon to distinguish Patron from a regular browser window.
The exact packaging strategy (Electron, Tauri, native wrapper, etc.) is left to the implementer.
- Start your Librarian of Alexandria backend.
- Start the Patron backend proxy.
- Start the Patron frontend.
- In the top bar:
- Paste your Librarian API URL.
- Paste your API key.
- Click Connect.
- Wait for a success indication (or check logs if it fails).
- Type a question into the chat input area.
- Click Send.
- Patron forwards the question to your Librarian chat endpoint via the proxy.
- The response appears in the chat history.
Examples:
- “What documents are currently indexed in the system?”
- “Summarize the latest design doc in 5 bullet points.”
- “Compare the two most recent incident reports and list the main differences.”
- Open the upload panel in Patron.
- Choose a file from your local filesystem.
- Click Upload.
- Patron sends the file to the Librarian upload endpoint.
- Once Librarian finishes ingesting and indexing, you can query the new content from the chat panel.
Typical supported formats depend on your Librarian configuration (commonly PDFs and text-based documents).
- Use the theme toggle in the top bar to switch between light and dark modes.
- The overall visual style matches the broader Botwin ecosystem:
- Creme / off‑white base.
- Mint‑green accents.
- Clean, text‑centric layout.
- Patron is a client, not a RAG engine.
- All retrieval and generation happens on your Librarian backend.
- Patron’s local proxy:
- Stores the Librarian API URL and API key.
- Adds authentication headers to outbound requests.
- Forwards chat and upload calls from the frontend.
Recommended practices:
- Use HTTPS for any Librarian endpoint exposed over the internet.
- Restrict access to your Librarian API with proper authentication and firewall rules.
- Use separate API keys for different environments (dev/stage/prod).
- Rotate keys periodically.
Common issues:
-
Cannot connect to backend
- Check that Librarian is running and reachable at the URL you entered.
- Verify that the local proxy is running and the frontend is pointing to it.
-
401/403 errors
- API key is missing or invalid. Double-check the key and try again.
-
Uploads failing
- Ensure a file is selected.
- Check that the file type and size are supported by your Librarian instance.
- Look at Librarian logs for ingestion errors.
-
Frontend shows no responses
- Check the local proxy logs for errors when forwarding to Librarian.
- Verify that the Librarian chat endpoint is working by calling it directly from the command line or an HTTP client.
If you want to extend Patron:
- Add new proxy endpoints in the FastAPI backend for additional Librarian features (document listing, admin tasks, etc.).
- Update the React UI to call those endpoints and display the results.
- Keep the separation of concerns:
- UI should stay small and focused.
- Proxy handles keys and networking.
- Librarian remains the authoritative RAG backend.
Pull requests and contributions that improve the developer experience, logging, and platform support are welcome (depending on how you run your fork).
This project is licensed under the terms of the repository’s LICENSE file.
Please refer to LICENSE for full details.