llm-webchat 1.0.0__tar.gz

llm_webchat-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+
+jobs:
+  backend:
+    name: Backend Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync
+      - name: Lint
+        run: uv run ruff check .
+      - name: Run tests
+        run: uv run pytest
+
+  frontend:
+    name: Frontend Tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install dependencies
+        run: npm ci
+      - name: Lint
+        run: npm run lint
+      - name: Run tests
+        run: npm test

llm_webchat-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+
+# Frontend build output (regenerated by `npm run build` in frontend/)
+src/llm_webchat/static/
+
+# Frontend dependencies
+frontend/node_modules/
+frontend/dist/

llm_webchat-1.0.0/AGENTS.md

@@ -0,0 +1,33 @@
+# llm-webchat
+
+See README.md for context and the vision for the project.
+
+## Coding style guide
+
+- Prefer functional, stateless logic as much as possible.
+- Use immutable data structures as much as possible.
+- Do not use abbreviations in variable (class, function, ...) names. It's fine for names to be somewhat verbose.
+- Omit docstrings and comments if they don't add any value beyond what can be obviously inferred from the function signature / class name.
+- Do not throw builtin errors; always replace them with dedicated error subclasses.
+- Make sure to use up-to-date versions of all libraries.
+
+### Python
+
+- Use modern typed Python code (assume pyre check).
+- Use uv for python project management.
+- Use frozen pydantic models for most classes.
+- Use pytest for testing.
+- Always place imports at the top level.
+- Avoid async code when possible; prefer synchronous implementations.
+- When done, validate your changes by running `uv run pytest`.
+
+### Typescript
+
+- Use modern Typescript code.
+- When done, validate your changes by running `npm lint` and `npm test`.
+- Use async / await instead of raw Promise primitives where possible.
+
+### CSS
+
+- Add semantic class names to components make restyling easy.
+- Make most important values part of `@theme` as variables that can be referenced by extension authors.

llm_webchat-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Imbue, Inc.
+
+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.

llm_webchat-1.0.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: llm-webchat
+Version: 1.0.0
+Summary: A web chat interface plugin for llm
+Project-URL: Homepage, https://github.com/imbue-ai/llm-webchat
+Project-URL: Repository, https://github.com/imbue-ai/llm-webchat
+Project-URL: Issues, https://github.com/imbue-ai/llm-webchat/issues
+Project-URL: Changelog, https://github.com/imbue-ai/llm-webchat/releases
+Author-email: Hynek Urban <hynek@imbue.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: llm>=0.28
+Requires-Dist: pluggy>=1.5
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: sqlite-utils>=3.39
+Requires-Dist: starlette>=0.45
+Requires-Dist: uvicorn>=0.34
+Description-Content-Type: text/markdown
+
+# LLM Webchat
+
+A plugin for the [LLM](https://github.com/simonw/llm) tool.
+When installed, running `llm webchat` starts a local webserver.
+Visiting its address in the browser lets you see the
+conversations in your `llm` database and chat with supported
+language models.
+
+The appearance and functionality of `llm-webchat` is heavily
+customizable - styles, frontend appearance and behavior and even
+the backend logic.
+
+## Quickstart
+
+```bash
+llm install llm-webchat
+llm webchat
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.10+ with [uv](https://github.com/astral-sh/uv)
+- Node.js 18+
+
+### Building and running
+
+Build the frontend (output goes to `src/llm_webchat/static/`):
+
+```bash
+cd frontend
+npm install
+npm run build
+```
+
+Run the backend (serves the built frontend at `/`):
+
+```bash
+uv run llm-webchat
+```
+
+For frontend development with hot reload (proxies `/api` requests to the backend):
+
+```bash
+cd frontend
+npm run dev
+```
+
+### Running tests
+
+```bash
+uv run pytest
+cd frontend
+npm test
+```

llm_webchat-1.0.0/README.md

@@ -0,0 +1,56 @@
+# LLM Webchat
+
+A plugin for the [LLM](https://github.com/simonw/llm) tool.
+When installed, running `llm webchat` starts a local webserver.
+Visiting its address in the browser lets you see the
+conversations in your `llm` database and chat with supported
+language models.
+
+The appearance and functionality of `llm-webchat` is heavily
+customizable - styles, frontend appearance and behavior and even
+the backend logic.
+
+## Quickstart
+
+```bash
+llm install llm-webchat
+llm webchat
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.10+ with [uv](https://github.com/astral-sh/uv)
+- Node.js 18+
+
+### Building and running
+
+Build the frontend (output goes to `src/llm_webchat/static/`):
+
+```bash
+cd frontend
+npm install
+npm run build
+```
+
+Run the backend (serves the built frontend at `/`):
+
+```bash
+uv run llm-webchat
+```
+
+For frontend development with hot reload (proxies `/api` requests to the backend):
+
+```bash
+cd frontend
+npm run dev
+```
+
+### Running tests
+
+```bash
+uv run pytest
+cd frontend
+npm test
+```

llm_webchat-1.0.0/docs/architecture.md

@@ -0,0 +1,88 @@
+# LLM Webchat architecture
+
+There is a backend in Python and a frontend written in Typescript. The
+PyPI package contains compiled static frontend assets so users
+don't need to have node or typescript installed at all.
+
+## Backend
+
+Backend uses fastapi + uvicorn. It provides the following endpoints:
+
+- GET "/api/models" to list all available LLM models
+- GET "/api/conversations" to list the most recent conversations
+    - accepts the `?count=` parameter, by default `count=10`.
+- GET "/api/conversations/:id/responses to get all responses in a given conversation
+- POST "/api/conversations/ to create a conversation (requires `name` and `model` in the request body)
+- POST "/api/conversations/:id/ to send a new user message to an existing conversation (requires `message` and `model` in the request body).
+- GET /api/conversations/:id/stream get a stream of events in
+a given conversation. There are several kinds of events:
+    - `user_message`: user message that arrived
+    - `message_start`, `message_delta`, `message_end`: to stream the current LLM response
+    - `error`: to provide details about potential errors
+
+Static files are served from `/static`. The only exception is `index.html` which is served from the root.
+
+
+The following environment variables are recognized:
+
+- `LLM_WEBCHAT_CONVERSATION_IDS`: a comma-separated list. If provided, only these conversations are ever returned.
+- `LLM_WEBCHAT_JAVASCRIPT_PLUGINS`: a comma separated list of .js files containing frontend plugins (see below).
+- `LLM_WEBCHAT_STATIC_PATHS`: a comma separated list of additional paths to resources that should be served from under `/static`. Files and directories are both accepted.
+- `LLM_WEBCHAT_HOST`: the host address the server binds to. Defaults to `127.0.0.1`.
+- `LLM_WEBCHAT_PORT`: the port the server listens on. Defaults to `8000`.
+
+The web server can be extended using [pluggy](https://github.com/pytest-dev/pluggy) by providing implementations of the following hookspecs (defined in `llm_webchat.hookspecs`):
+
+- `endpoint(app)` — Register additional endpoints (including static file routes) on the FastAPI application.
+- `register_event_broadcaster(broadcaster)` — Receive a reference to the event broadcaster callable. The broadcaster has the signature `(conversation_id: str, event: dict[str, str]) -> None` and can be stored and called at any time to inject custom events into the SSE stream for a given conversation.
+
+
+## Frontend
+
+Frontend is written in Typescript, using mithril.js and
+tailwind. Its appearance and functionality should be familiar to
+users of other well-known chat-based web AI assistants.
+
+Both the appearance and functionality are highly customizable
+using a framework-agnostic plugin system. Plugins can run
+arbitrary javascript making arbitrary changes to the page. To
+make this easier, the default DOM will contain certain stable
+elements / containers with well data attributes which plugins
+can use as anchor points:
+
+- `<div data-slot="header">` — the top header bar
+- `<div data-slot="header-actions">` — empty container inside the header, right-aligned (for buttons, indicators)
+- `<div data-slot="sidebar">` — the full sidebar
+- `<div data-slot="sidebar-header">` — the sidebar title, collapse button, and "New Conversation" button
+- `<div data-slot="sidebar-before-list">` — empty container between the sidebar header and the conversation list (for search, filters)
+- `<div data-slot="conversation-selector-item">` — an individual conversation entry in the sidebar
+- `<div data-slot="conversation-after-header">` — empty container below the header, above the message list (for banners, breadcrumbs)
+- `<div data-slot="conversation-content">` — the scrollable message list area
+- `<div data-slot="conversation-before-input">` — empty container inside the footer, above the message input (for toolbars, attachments)
+- `<div data-slot="conversation-footer">` — the footer containing the message input
+- `<div data-slot="new-conversation-content">` — the new conversation form area
+- `<div data-slot="new-conversation-footer">` — the footer on the new conversation screen
+- `<div data-slot="message" data-message-id="...">` — an individual assistant message
+
+Slots marked "empty" render as empty `<div>` elements by default and exist purely as extension points — plugins can claim them and inject content without replacing any built-in UI.
+
+Furthermore, there's a global "$llm" object that can be used to:
+
+- Claim ownership of a specific component type:
+    - `$llm.claim("header")` (or `"sidebar"`, `"content"`, `"message"`, ...)
+    - When claimed, only the component container is rendered by the core loop (contents are expected to be provided by the plugin).
+    - Returns true when the claim succeeded, false otherwise (e.g. when already claimed by another plugin).
+    - (This is to prevent conflicts between the renders done by the core mithril.js loop and the renders done by the plugin.)
+- Get specific parts of the current page state:
+    - `$llm.getMessage(messageId)`
+    - `$llm.getConversations()`
+    - `$llm.getConversation(conversationId)`
+    - `$llm.getModels()`
+- Register for certain events:
+    - `$llm.on("ready")` - when the main APP is initialized
+    - `$llm.on("get_conversations")` - when a response to `GET /api/conversations` arrives.
+    - `$llm.on("get_conversation")`
+    - `$llm.on("post_conversation")`
+    - `$llm.on("post_conversation_message")`
+    - `$llm.on("get_message")`
+    - `$llm.on("stream_event")`

llm_webchat-1.0.0/extension_examples/conversation_search/README.md

@@ -0,0 +1,16 @@
+# Conversation Search
+
+Adds full-text search across all conversation messages. Demonstrates:
+
+- A custom backend endpoint (`GET /api/search?q=...`).
+- A vanilla JS frontend plugin that adds a search box to the sidebar.
+- Navigating to a specific response within a conversation via anchor links.
+
+## Installation and usage
+
+From the repository root:
+
+```bash
+uv pip install -e extension_examples/conversation_search
+llm webchat-with-search
+```

llm_webchat-1.0.0/extension_examples/conversation_search/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "llm-webchat-search"
+version = "0.1.0"
+description = "Full-text conversation search for llm-webchat"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "llm-webchat",
+]
+
+[project.entry-points.llm]
+webchat-search = "llm_webchat_search"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/llm_webchat_search"]

llm_webchat-1.0.0/extension_examples/conversation_search/src/llm_webchat_search/__init__.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import click
+import llm
+import uvicorn
+from fastapi import Query
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from llm_webchat.hookspecs import hookimpl
+
+STATIC_DIRECTORY = Path(__file__).parent / "static"
+
+SNIPPET_CONTEXT_LENGTH = 80
+
+
+class SearchResult:
+    def __init__(
+        self,
+        conversation_id: str,
+        conversation_name: str,
+        model: str,
+        response_id: str,
+        snippet: str,
+        field: str,
+    ) -> None:
+        self.conversation_id = conversation_id
+        self.conversation_name = conversation_name
+        self.model = model
+        self.response_id = response_id
+        self.snippet = snippet
+        self.field = field
+
+
+def _extract_snippet(text: str, query: str, context_length: int = SNIPPET_CONTEXT_LENGTH) -> str:
+    lower_text = text.lower()
+    lower_query = query.lower()
+    position = lower_text.find(lower_query)
+    if position == -1:
+        return text[: context_length * 2] + ("…" if len(text) > context_length * 2 else "")
+
+    start = max(0, position - context_length)
+    end = min(len(text), position + len(query) + context_length)
+
+    snippet = text[start:end]
+    if start > 0:
+        snippet = "…" + snippet
+    if end < len(text):
+        snippet = snippet + "…"
+
+    return snippet
+
+
+def _search_conversations(query: str, limit: int = 20) -> list[dict[str, str]]:
+    from llm_webchat.database import open_database
+
+    database = open_database()
+
+    if "responses" not in database.table_names():
+        return []
+    if "conversations" not in database.table_names():
+        return []
+
+    like_pattern = f"%{query}%"
+
+    rows = database.execute(
+        """
+        SELECT
+            r.id AS response_id,
+            r.conversation_id,
+            r.prompt,
+            r.response,
+            c.name AS conversation_name,
+            c.model
+        FROM responses r
+        JOIN conversations c ON c.id = r.conversation_id
+        WHERE r.prompt LIKE ? COLLATE NOCASE
+           OR r.response LIKE ? COLLATE NOCASE
+        ORDER BY r.datetime_utc DESC
+        LIMIT ?
+        """,
+        [like_pattern, like_pattern, limit],
+    ).fetchall()
+
+    results = []
+    for row in rows:
+        prompt = row["prompt"] or ""
+        response = row["response"] or ""
+
+        if query.lower() in prompt.lower():
+            snippet = _extract_snippet(prompt, query)
+            field = "prompt"
+        else:
+            snippet = _extract_snippet(response, query)
+            field = "response"
+
+        results.append(
+            {
+                "conversation_id": row["conversation_id"],
+                "conversation_name": row["conversation_name"] or "",
+                "model": row["model"] or "",
+                "response_id": row["response_id"],
+                "snippet": snippet,
+                "field": field,
+            }
+        )
+
+    return results
+
+
+class SearchPlugin:
+    @hookimpl
+    def endpoint(self, app: object) -> None:
+        @app.get("/api/search")  # type: ignore[union-attr]
+        def search_conversations(
+            request: Request,
+            q: str = Query(..., min_length=1),
+            limit: int = Query(default=20, ge=1, le=100),
+        ) -> JSONResponse:
+            results = _search_conversations(q, limit)
+            return JSONResponse(content={"query": q, "results": results})
+
+
+@llm.hookimpl
+def register_commands(cli: click.Group) -> None:
+    @cli.command(name="webchat-with-search")
+    def webchat_with_search() -> None:
+        """Open a web chat interface with conversation search."""
+        from llm_webchat.config import load_config
+        from llm_webchat.plugins import get_plugin_manager
+        from llm_webchat.server import create_application
+
+        search_plugin = SearchPlugin()
+        get_plugin_manager().register(search_plugin)
+
+        javascript_plugin_path = str(STATIC_DIRECTORY / "search.js")
+        existing_plugins = os.environ.get("LLM_WEBCHAT_JAVASCRIPT_PLUGINS", "")
+        if existing_plugins:
+            os.environ["LLM_WEBCHAT_JAVASCRIPT_PLUGINS"] = f"{existing_plugins},{javascript_plugin_path}"
+        else:
+            os.environ["LLM_WEBCHAT_JAVASCRIPT_PLUGINS"] = javascript_plugin_path
+
+        config = load_config()
+        application = create_application(config)
+        uvicorn.run(application, host=config.llm_webchat_host, port=config.llm_webchat_port)