Jaroslav Beneš
35b9d8c8d2
**Bases.** Documents now live in named collections rather than one flat pile, and a chat can be pointed at particular ones — "answer from the contracts folder" is a different question from "answer from everything I have ever uploaded". A chat with none attached still searches everything its owner can see, because empty means unscoped, not empty. The harness names the attached bases. Without that the model cannot tell "there is nothing about this" from "I am only allowed to see one folder", and it phrases a miss as the former. **Sharing moves to the base.** A document is visible to whoever can see the base it lives in, so `Document` is gone from the shareable types and `documents.visible()` filters through `base_id`. "This folder is the team's" is the granularity people think in; per-document grants meant answering "who can see this?" by checking every file. Moving a document between bases changes who can see it, so the destination has to be one you own. `Document.base_id` is nullable only because the column had to be added to a table that already had rows. `sweep_unfiled()` runs at startup beside the orphaned-upload sweep and files anything predating bases into its owner's default, which is what makes "always set" true everywhere else. **The file input.** `.input` gave it a fixed height and horizontal padding, so the browser's own button sat hard against the left edge while the filename floated off the centre line. A file input is two controls in one box and neither inherits anything useful, so it gets its own rule: no horizontal padding, the button sized to `--control-h` with the divider that separates it, and the text centred with line-height rather than flexbox, which file inputs do not lay out reliably. 437 tests, ruff clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
254 lines
11 KiB
Markdown
254 lines
11 KiB
Markdown
<p align="center">
|
|
<img src="assets/banner.svg" alt="LLeMbas — waybread for the long road of thought" width="100%">
|
|
</p>
|
|
|
|
<p align="center">
|
|
<strong>A self-hosted web UI for your language models, written in Python.</strong><br>
|
|
Talks to anything that speaks the OpenAI API. Themed after Middle-earth.
|
|
</p>
|
|
|
|
<p align="center">
|
|
<img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-3E6B7A?style=flat-square">
|
|
<img alt="License GPL-3.0" src="https://img.shields.io/badge/license-GPL--3.0-C9A227?style=flat-square">
|
|
<img alt="No Node required" src="https://img.shields.io/badge/build%20step-none-6B8E4E?style=flat-square">
|
|
</p>
|
|
|
|
---
|
|
|
|
*Lembas* is the Elvish waybread — one bite sustains a traveller for a day's
|
|
march. The capitals hide what it runs on: **LLeM**bas.
|
|
|
|
## Why this exists
|
|
|
|
Most self-hosted LLM front-ends are large JavaScript applications with a Python
|
|
API bolted underneath. LLeMbas is the other way round: **server-rendered
|
|
Python**, with htmx and a little Alpine for interactivity. There is no
|
|
`package.json`, no bundler, no build step, and nothing is fetched from a CDN at
|
|
runtime. Clone it, `pip install -e .`, run it.
|
|
|
|
## Features
|
|
|
|
**Working now**
|
|
|
|
- **Chats** — streaming replies, Markdown with server-side syntax highlighting,
|
|
copy and regenerate, automatic chat titles. Chats are created when you send
|
|
the first message, so an abandoned one never clutters the sidebar
|
|
- **System prompts** — instance-wide, per-model and per-chat, with the most
|
|
specific winning outright
|
|
- **Reasoning display** — thinking streams into its own collapsible block
|
|
(closed by default), labelled with how long it took, and is never replayed as
|
|
context
|
|
- **Live Markdown** — formatting appears as the model writes, not at the end
|
|
- **Stop and rewind** — cut a reply short and keep what arrived, or edit an
|
|
earlier message and run the conversation on from there
|
|
- **Replies keep running in the background** — navigate away, open another
|
|
chat, close the tab; a green dot and a notification tell you when it lands
|
|
- **Attachments** — drag, paste or pick images, PDFs and text files. Images are
|
|
downscaled and sent to vision models; PDF and text content is extracted and
|
|
put in the prompt
|
|
- **Folders** — arbitrarily nested, delete a folder without losing the chats
|
|
inside it
|
|
- **Web search** — offered to the model as a tool it calls when a question needs
|
|
it. DuckDuckGo out of the box (no account, no key), or point it at your own
|
|
SearXNG, or Firecrawl. The sources stay in the transcript
|
|
- **Speech in and out** — dictate a message and have replies read aloud, against
|
|
any OpenAI-compatible audio endpoint (whisper.cpp, Speaches, Kokoro…). Each
|
|
person picks their own voice
|
|
- **A library** — four places a model can reach for. **Knowledge**: documents,
|
|
images and web pages you collect, grouped into named bases so a chat can be
|
|
pointed at just the right one, searched before the web. **Notes**: longer
|
|
things it writes down and finds again later. **Memory**: short facts about you,
|
|
in front of it on every turn. **Skills**: saved procedures it can follow, and
|
|
write. All of it visible and editable by you, and shareable with a group or a
|
|
person, read-only
|
|
- **Installable** — add it to a phone home screen or a desktop launcher and it
|
|
runs in its own window
|
|
- **OpenAI connections** — point at OpenAI, LM Studio, vLLM, llama.cpp,
|
|
llama-swap, Ollama or OpenRouter; models are discovered and cached
|
|
- **Model settings** — searchable, filterable list with a page per model:
|
|
ordering, pinned models, an instance default and a per-user default, custom
|
|
names, descriptions and images. Scales to hundreds of models
|
|
- **Users, groups & permissions** — per-group grants that union rather than
|
|
override, and model access restricted to chosen groups
|
|
- **Accounts** — first account becomes the administrator, argon2 password
|
|
hashing, revocable server-side sessions, self-service password change,
|
|
admin-managed accounts
|
|
- **Admin settings** — open or close registration from the UI, stored in the
|
|
database and effective immediately
|
|
- **Two themes** — *Moria* (dark) and *Shire* (light), switchable per user
|
|
|
|
**Planned**
|
|
|
|
Custom tools and MCP servers · agentic execution (local and over SSH) · image
|
|
generation · OCR for scanned PDFs · semantic search in the library.
|
|
|
|
See [PLAN.md](PLAN.md) for what is built, what is not, and why.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
git clone https://git.houmeres.sk/Houmeres/LLeMbas.git
|
|
cd LLeMbas
|
|
|
|
python -m venv .venv && . .venv/bin/activate
|
|
pip install -e ".[dev,search]" # `search` adds DuckDuckGo; drop it if unwanted
|
|
|
|
cp .env.example .env
|
|
lembas secret-key # paste the result into LEMBAS_SECRET_KEY
|
|
|
|
lembas serve # http://127.0.0.1:8080
|
|
```
|
|
|
|
Open the address and create the first account — it becomes the administrator.
|
|
Then go to **Admin → Connections** and add an endpoint. For a local runner that
|
|
is usually `http://localhost:1234/v1` with no API key. Press **Test & refresh**
|
|
and its models appear in the chat model picker.
|
|
|
|
> The vendored browser libraries (htmx, Alpine) are committed, so no network
|
|
> access is needed to run. To re-fetch or bump them:
|
|
> `python scripts/fetch_vendor.py --update`.
|
|
|
|
### Web search
|
|
|
|
**Admin → Web search.** DuckDuckGo needs nothing beyond the `search` extra
|
|
above. SearXNG needs its JSON format enabled — add `- json` under
|
|
`search.formats` in its `settings.yml`, or every search fails. Firecrawl needs
|
|
an API key.
|
|
|
|
Search is offered to the model as a *tool*, so it decides when a question needs
|
|
looking up. It is only offered to models marked **tools** under
|
|
**Admin → Models**: an endpoint without tool support rejects the whole request
|
|
rather than ignoring the extra field, so the flag is a real switch and not a
|
|
hint.
|
|
|
|
### Audio
|
|
|
|
**Admin → Audio.** Two endpoints, because they are usually two servers:
|
|
|
|
| | Speaks | Example |
|
|
|---|---|---|
|
|
| Dictation | `POST /v1/audio/transcriptions` | whisper.cpp's `whisper-server`, Speaches, faster-whisper-server |
|
|
| Read aloud | `POST /v1/audio/speech` | Kokoro-FastAPI, OpenAI |
|
|
|
|
If the speech endpoint also answers `GET /v1/audio/voices` the voice list is
|
|
read from it, and each person can pick their own under **Settings → Audio**.
|
|
Recorded audio is passed straight through and never written to disk.
|
|
|
|
> The microphone needs HTTPS or localhost. Browsers do not grant it over plain
|
|
> HTTP, so a LAN install without TLS will not offer dictation.
|
|
|
|
### The library
|
|
|
|
**Sidebar → Library**, and **Settings → Memory**. Nothing is on by default for a
|
|
model: give it the tools it should have under **Admin → Models**, where
|
|
`tools` decides whether a tool list may be sent at all and the built-in tools are
|
|
chosen one by one.
|
|
|
|
Knowledge is organised into **bases** — one per subject, project or client. A
|
|
chat with no base attached searches everything you have; tick some in the chat's
|
|
settings panel and it searches only those. Sharing happens at the base: share it
|
|
and everything in it comes too, read-only.
|
|
|
|
Search is SQLite's FTS5 — keyword matching with BM25 ranking, no embedding
|
|
service to run and nothing that stops working offline. It will not match a
|
|
paraphrase, so a line of description on a document is worth writing.
|
|
|
|
> Saving a **link** makes your server fetch a URL. Addresses on your own machine
|
|
> and network are refused unless an administrator opts in under
|
|
> **Admin → Web search**, because the address can come from a model and the
|
|
> server can reach things your browser cannot.
|
|
|
|
### Installing as an app
|
|
|
|
Open it in a browser and use *Install* (Chromium) or *Share → Add to Home
|
|
Screen* (iOS). This also needs HTTPS or localhost — service workers are
|
|
unavailable over plain HTTP, and without one there is nothing to install.
|
|
|
|
There is no offline mode beyond a page saying so. Everything is rendered by your
|
|
server, so a cached conversation would be a snapshot that silently went stale.
|
|
|
|
## Configuration
|
|
|
|
All variables are prefixed `LEMBAS_` and can live in `.env`. See
|
|
[`.env.example`](.env.example) for the annotated list.
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `LEMBAS_SECRET_KEY` | *generated* | Signs sessions and encrypts stored API keys. **Set this.** A generated key changes every restart, signing everyone out and making stored API keys unreadable. |
|
|
| `LEMBAS_DATA_DIR` | `./data` | SQLite database and uploads. |
|
|
| `LEMBAS_HOST` / `LEMBAS_PORT` | `127.0.0.1` / `8080` | Bind address. |
|
|
| `LEMBAS_ALLOW_SIGNUP` | `true` | Whether new users may register themselves — the *initial* value only. Once set under **Admin → General** the stored setting wins. The first account is always an admin regardless. |
|
|
| `LEMBAS_DEFAULT_THEME` | `moria` | `moria` (dark) or `shire` (light). |
|
|
| `LEMBAS_SESSION_TTL` | `2592000` | Session lifetime in seconds. |
|
|
| `LEMBAS_REQUEST_TIMEOUT` | `300` | Seconds to wait on an upstream model. |
|
|
|
|
### Commands
|
|
|
|
```bash
|
|
lembas serve # run the server
|
|
lembas info # where data lives, what is configured
|
|
lembas secret-key # generate a value for LEMBAS_SECRET_KEY
|
|
lembas create-admin # create or promote an administrator
|
|
```
|
|
|
|
## How it fits together
|
|
|
|
```
|
|
Browser ──form POST──▶ FastAPI ──▶ SQLite
|
|
▲ │
|
|
│ └──httpx──▶ any OpenAI-compatible endpoint
|
|
└──── server-sent events ◀───────────────┘ (streamed reply)
|
|
```
|
|
|
|
Sending a message stores the turn and returns two HTML fragments: the user's
|
|
bubble and an empty assistant bubble carrying an `sse-connect`. That opens a
|
|
server-sent event stream which appends tokens as they arrive, then replaces the
|
|
whole bubble with the finished, Markdown-rendered version. Rendering and
|
|
highlighting happen in Python, so the streamed and final views cannot disagree.
|
|
|
|
```
|
|
src/lembas/
|
|
api/ routes: auth, chats, folders, admin, pages
|
|
db/models/ SQLAlchemy schema
|
|
security/ password hashing, sessions
|
|
services/ llm client, chat orchestration, markdown, crypto, sse
|
|
web/ Jinja templates and static assets
|
|
assets/ SVG artwork masters
|
|
scripts/ artwork generator, vendored-JS fetcher
|
|
deploy/ systemd unit and nginx vhost for a real install
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
pytest # test suite
|
|
ruff check . # lint
|
|
python scripts/build_artwork.py # regenerate the SVG artwork
|
|
python scripts/fetch_vendor.py # verify vendored JS against the lockfile
|
|
```
|
|
|
|
There is no Alembic. The schema is SQLite-only and synchronised at startup:
|
|
missing tables and missing columns are added automatically, so adding a field to
|
|
a model needs nothing but a restart. Renames, drops and retypes are still manual
|
|
— see `CLAUDE.md`.
|
|
|
|
## Artwork
|
|
|
|
The logo, favicon and banner are original vector work, generated by
|
|
[`scripts/build_artwork.py`](scripts/build_artwork.py) so the mallorn leaf stays
|
|
identical across every size it appears at. The wordmark is
|
|
[Source Serif 4](https://github.com/adobe-fonts/source-serif) (SIL OFL 1.1)
|
|
converted to outlines — a README banner cannot load a webfont, and `<text>`
|
|
would render in whatever serif the reader happens to have.
|
|
|
|
## Licence
|
|
|
|
[GPL-3.0](LICENSE).
|
|
|
|
## A note on the theme
|
|
|
|
This is an independent hobby project, themed as an affectionate nod to
|
|
J.R.R. Tolkien's world. It is **not affiliated with, endorsed by, or connected
|
|
to** the Tolkien Estate, Middle-earth Enterprises, or any related rights
|
|
holder. All artwork here is original.
|