lmrelay 0.0.0__tar.gz

lmrelay-0.0.0/.dockerignore

@@ -0,0 +1,32 @@
+__pycache__/
+*.pyc
+*.pyo
+.Python
+.venv/
+venv/
+*.egg-info/
+build/
+dist/
+.env
+.env.local
+node_modules/
+.DS_Store
+Thumbs.db
+data/
+models/
+*.log
+.idea/
+.vscode/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+.lmrelay/
+.git/
+.github/
+tests/
+docs/
+ROADMAP.md
+CHANGELOG.md

lmrelay-0.0.0/.env.example

@@ -0,0 +1,60 @@
+# lmrelay configuration.
+# Copy to ~/.lmrelay/.env and fill in keys for the providers you have.
+
+# Server bind
+LMRELAY_HOST=0.0.0.0
+LMRELAY_PORT=11434
+
+# State directory (default ~/.lmrelay)
+# LMRELAY_HOME=~/.lmrelay
+
+# Security: shared-secret. Empty / unset = auth disabled.
+# LMRELAY_TOKEN=
+
+# Behaviour
+LMRELAY_LOG_LEVEL=INFO
+LMRELAY_TELEMETRY=off
+LMRELAY_COOLDOWN_SECONDS=60
+LMRELAY_REQUEST_TIMEOUT=120
+LMRELAY_HEALTH_WINDOW=50
+LMRELAY_MODEL_CATALOG_TTL=21600
+
+# CORS (default *)
+# LMRELAY_CORS_ORIGINS=*
+
+# Metrics endpoint (default off)
+# LMRELAY_METRICS=off
+
+# Comma-separated provider names the router should skip, even when their
+# key is set. Useful for temporarily pausing a flaky provider while
+# leaving its key in the .env. Names: openrouter, groq, nvidia_nim,
+# huggingface, cerebras, cloudflare_wai, gemini, ollama_backend.
+# LMRELAY_DISABLED_PROVIDERS=cloudflare_wai,huggingface
+
+# Optional local Ollama as a backend provider
+# OLLAMA_BACKEND_URL=http://127.0.0.1:11435
+
+# Provider keys (uncomment + fill).
+# All providers support multi-key: <PREFIX>, <PREFIX>_2, <PREFIX>_3, ...
+
+# OPENROUTER_API_KEY=sk-or-v1-...
+# OPENROUTER_API_KEY_2=
+
+# GROQ_API_KEY=gsk_...
+# GROQ_API_KEY_2=
+
+# NVIDIA_NIM_API_KEY=nvapi-...
+# NVIDIA_NIM_API_KEY_2=
+
+# HUGGINGFACE_API_KEY=hf_...
+# HUGGINGFACE_API_KEY_2=
+
+# CEREBRAS_API_KEY=csk-...
+# CEREBRAS_API_KEY_2=
+
+# CLOUDFLARE_WAI_API_KEY=
+# CLOUDFLARE_ACCOUNT_ID=
+
+# Google AI Studio (Gemini). Get a key at https://aistudio.google.com/apikey
+# GEMINI_API_KEY=AIza...
+# GEMINI_API_KEY_2=

lmrelay-0.0.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+
+jobs:
+  lint-and-type:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy lmrelay
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -m "not e2e" --cov=lmrelay --cov-report=term-missing

lmrelay-0.0.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish
+on:
+  push:
+    tags:
+      - "*.*.*"
+      - "v*"
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -U build
+      - run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

lmrelay-0.0.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build-and-publish-pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install --upgrade build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository }}:latest
+            ghcr.io/${{ github.repository }}:${{ github.ref_name }}

lmrelay-0.0.0/.gitignore

@@ -0,0 +1,36 @@
+# Local lmrelay config — never commit your keys.
+lmrelay.toml
+!lmrelay.toml.example
+
+.idea/
+.vscode/
+.cursor/
+.claude/
+.codex
+
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.pyright/
+.coverage
+htmlcov/
+site/
+
+.env
+.env.*
+!.env.example
+
+*.md
+!README.md
+!CHANGELOG.md
+!CONTRIBUTING.md
+!docs/**/*.md

lmrelay-0.0.0/CHANGELOG.md

@@ -0,0 +1,146 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+- **Project renamed `freellama` → `lmrelay`.** Reflects the broader
+  scope: balancer / gateway for LLM providers with upcoming profiles
+  and tokens, not just a free-tier-only Ollama drop-in.
+  - PyPI: `pip install lmrelay`
+  - CLI: `lmrelay`, `lmrelay-watcher`
+  - Env vars: `FREELLAMA_*` → `LMRELAY_*`
+  - State dir: `~/.freellama/` → `~/.lmrelay/`
+  - Config file: `freellama.toml` → `lmrelay.toml`
+  - Docker prefix: `frl_*` → `lmr_*`
+  - systemd: `freellama.service` → `lmrelay.service`
+  - HTTP header: `X-Freellama-Request-Id` → `X-Lmrelay-Request-Id`
+  - Integration stub-token: `freellama-stub-token` → `lmrelay-stub-token`
+  Existing installs must migrate config + state by hand; there is no
+  automatic shim.
+
+### Added
+- Google Gemini as an upstream provider via the OpenAI-compatible endpoint
+  (`generativelanguage.googleapis.com/v1beta/openai`). `GEMINI_API_KEY[_N]`
+  recognised on startup. Capabilities: chat, stream, tools, embed, vision,
+  json. Short names `gemini`, `gemini-flash`, `gemini-pro`, `gemini-2.5`,
+  `gemini-2.0`, `gemini-1.5`, `gemini-3` resolve to Gemini models; `gemini`
+  is also considered by the `free`, `fast`, `quality`, `coding`, `vision`,
+  and `embed` virtual aliases.
+- Catalog entries from GeminiProvider carry a `task` tag (`chat` or
+  `embedding`); `core.aliases.model_task()` reads it (or falls back to
+  a substring heuristic for other providers). `resolve_alias` filters by
+  task so chat aliases never accidentally route to an embedding model.
+- `lmrelay ping` — lists every provider with its enabled/disabled
+  status (key configured / explicitly disabled / ready) and, unless
+  `--no-probe` is passed, sends a minimal `Reply with one word: pong`
+  chat request (max_tokens=4) to the first model of each enabled
+  provider. Supports `--provider`, `--no-probe`, `--json`.
+- `LMRELAY_DISABLED_PROVIDERS` env var — comma-separated list of
+  provider names that the router will skip even when their key is set.
+  Disabled providers are dropped from `app.state.providers` at lifespan
+  startup.
+- Per-provider free/paid catalog toggle. Each `[provider.X]` table
+  takes four optional fields:
+  `include_free` (default `true`), `include_paid` (default `false`),
+  `include_extra` (fnmatch globs always included), `exclude`
+  (fnmatch globs always dropped — wins over the other rules).
+  `BaseProvider.list_models()` is now non-abstract and returns the
+  subset that `self.filter.allows()` keeps. Each catalog entry carries
+  a `tier` tag (`"free"` or `"paid"`); OpenRouter classifies by the
+  `pricing.prompt` field, other providers default to free.
+  Added `BaseProvider.list_all_models()` that bypasses the filter.
+- `core.provider_filter.ProviderFilter` + `build_provider_filter`;
+  `providers.registry.load_provider_filters()` and a wiring step in
+  `build_providers` that applies them.
+
+- `lmrelay.toml` config — sectioned by `[provider.X]` with one
+  `[[provider.X.keys]]` block per credential. Resolution order:
+  `./lmrelay.toml` (local checkout, gitignored) →
+  `~/.lmrelay/lmrelay.toml` (installed) → built-in defaults.
+  Process env vars override.
+- `lmrelay reload` CLI command + `POST /admin/reload` endpoint.
+  Re-reads `lmrelay.toml` and `.env`, rebuilds the key ring + active
+  provider list, clears the cooldown matrix. Host/port stay bound.
+  Auth via the existing `Authorization: Bearer <LMRELAY_TOKEN>`.
+- `lmrelay.toml.example` template.
+- `deploy/systemd/lmrelay.service` and
+  `deploy/systemd/lmrelay-watcher.service` with `ExecReload=`
+  wired to `lmrelay reload`; `deploy/README.md` install guide.
+- `docker-compose.yml`: documents `lmrelay.toml` mount via
+  `./.lmrelay/`; sets `LMRELAY_HOME=/root/.lmrelay`.
+- Per-key model filter — each `[[provider.X.keys]]` block may carry a
+  `models = ["pattern", ...]` allow-list of fnmatch globs (e.g.
+  `["*:free"]`, `["meta-llama/*"]`, `["gemini-2.5-*"]`). The router's
+  candidate chain only includes a `(provider, key, model)` triple if
+  the key's allow-list (when present) matches the model id. Empty /
+  missing → no filter. `KeyRing` now exposes `KeyEntry` records via
+  `get_entries(provider)` and `find_entry(provider, api_key)`;
+  `get(provider)` still returns `list[str]` for backward compatibility.
+  `lmrelay keys` shows `label` and `models` columns.
+- `Makefile` with developer targets:
+  `install`, `test`, `lint`, `fmt`, `typecheck`, `check`,
+  `clean`, `serve`, `reload`, `ping`, `build`, `docker`,
+  `compose-up`, `compose-down`. `make` (no args) prints help.
+- `.gitignore`: ignores local `lmrelay.toml`, keeps
+  `lmrelay.toml.example` tracked; restructured into IDE / Python
+  build / type-checker / dotenv / markdown sections, with broad
+  `*.md` ignore + whitelist for `README.md`, `CHANGELOG.md`,
+  `CONTRIBUTING.md`, and `docs/**/*.md`.
+
+### Changed
+- All provider subclasses now call `super().__init__()` in their
+  `__init__` to seed `self.catalog` and `self.filter`. Their custom
+  `list_models` overrides were removed; tier tagging happens in
+  `refresh_catalog`.
+- Gemini chat-model whitelist is now a generation-agnostic regex
+  (`gemini-<N>[.<M>]-(flash|pro)[-suffix]*`) instead of a static
+  substring list. Gemini 3 (`gemini-3-flash-preview`, `gemini-3-pro`,
+  ...) and any future `gemini-<N>-flash/pro` lines come online without
+  code edits. Short names `gemini`, `gemini-flash`, `gemini-pro` now
+  prefer 3-family first; new short name `gemini-3` resolves to the
+  3 family. `coding` and `vision` keyword filters extended for
+  `gemini-3-flash` / `gemini-3-pro`.
+
+### Fixed
+- `gemini-pro` short name no longer falls back to the sunsetted
+  `gemini-1.5-pro`; it points at `gemini-3-pro` / `gemini-2.5-pro`.
+- `vision` alias keyword filter narrowed from the over-broad `gemini-2`
+  prefix to explicit family entries.
+- Removed dead `model_supports_vision` helper from `providers/gemini.py`.
+- `test_gemini_provider` no longer constructs `GeminiProvider(http=None)`.
+
+### Removed
+- Local-only repo-root docs untracked: `CLAUDE.md`, `CONTEXT.md`,
+  `ROADMAP.md` (kept on disk, ignored going forward).
+- `install.sh` — redundant with `pipx install lmrelay` /
+  `pip install lmrelay` / `uv tool install lmrelay`. The README
+  now points to those directly.
+
+## [0.0.0] - 2026-05-18 (as `freellama`)
+
+### Added
+- Drop-in Ollama-compatible server on port 11434
+- Three wire protocols on one port: Ollama `/api/*`, OpenAI `/v1/*`, Anthropic `/anthropic/v1/*`
+- Seven providers: OpenRouter, Groq, NVIDIA NIM, HuggingFace, Cerebras, Cloudflare Workers AI, local Ollama backend
+- Canonical request/response model (`ChatRequest`, `ChatResponseChunk`, `EmbeddingRequest`)
+- Translators ↔ canonical for all three wire protocols, plus NDJSON/SSE stream framing
+- Failover router with canonical error taxonomy (auth, rate_limit, quota_exhausted, model_not_found, upstream_5xx, timeout, transport, unknown)
+- Per-(provider, key) cooldown matrix with per-class TTL
+- Persistent health tracker (sliding window of 50, JSON-on-disk)
+- Multi-key parsing (`OPENROUTER_API_KEY`, `OPENROUTER_API_KEY_2`, `_3`, ...)
+- Model resolver supporting virtual aliases (`free`, `fast`, `quality`, `coding`, `vision`, `embed`), Ollama-style short names, and pass-through provider IDs
+- CLI: `init`, `serve`, `keys`, `list`, `doctor`, `audit-models`, `bench`, `run`, `bind`, `migrate-ollama`, `telemetry`, `dashboard`, `version`
+- Agent integrations: `claude`, `openclaw`, `codex`, `gemini` (runners) and `aider`, `continue`, `cursor`, `lobechat` (binders)
+- `lmrelay-watcher` daemon that probes head-of-chain on a configurable interval
+- TUI dashboard (`lmrelay dashboard`) with live event tail and provider health bars
+- Bearer-token auth (optional, via `LMRELAY_TOKEN`)
+- Loud LAN security banner when listening on `0.0.0.0` without an auth token
+- Opt-in telemetry (`LMRELAY_TELEMETRY=on`), default OFF
+- Docker image + `docker-compose.yml` (`frl_app` + `frl_watcher` services)
+- GitHub Actions CI: lint + mypy + pytest matrix py3.11/3.12/3.13
+- MIT license

lmrelay-0.0.0/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+WORKDIR /opt/app
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+COPY pyproject.toml README.md ./
+COPY lmrelay ./lmrelay
+
+RUN pip install --no-cache-dir .
+
+EXPOSE 11434
+
+CMD ["lmrelay", "serve"]

lmrelay-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lmrelay contributors
+
+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.

lmrelay-0.0.0/Makefile

@@ -0,0 +1,83 @@
+# lmrelay developer Makefile.
+#
+#   make             — show this help
+#   make install     — create .venv and install with dev extras
+#   make check       — lint + typecheck + tests
+#   make serve       — run the dev gateway (reload + bind to 127.0.0.1)
+#
+# Everything respects an externally activated venv; if .venv/bin/python
+# is missing, `make install` creates one.
+
+SHELL := /usr/bin/env bash
+
+VENV       := .venv
+PYTHON     := $(VENV)/bin/python
+PIP        := $(VENV)/bin/pip
+PYTEST     := $(VENV)/bin/pytest
+RUFF       := $(VENV)/bin/ruff
+MYPY       := $(VENV)/bin/mypy
+LMRELAY  := $(VENV)/bin/lmrelay
+
+.DEFAULT_GOAL := help
+.PHONY: help install dev test lint fmt format typecheck check clean \
+        serve reload ping build docker compose-up compose-down
+
+help:  ## Show this help
+	@awk 'BEGIN {FS = ":.*##"; printf "lmrelay — make targets:\n\n"} \
+	      /^[a-zA-Z][a-zA-Z0-9_-]*:.*##/ \
+	      { printf "  \033[1m%-14s\033[0m %s\n", $$1, $$2 }' \
+	      $(MAKEFILE_LIST)
+
+$(VENV):  ## (internal) create the dev virtualenv
+	python3 -m venv $(VENV)
+	$(PIP) install --upgrade pip
+
+install: $(VENV)  ## Create .venv and install lmrelay with dev extras
+	$(PIP) install -e ".[dev]"
+
+dev: install  ## Alias for install
+
+test:  ## Run the test suite (quiet)
+	$(PYTEST) -q
+
+lint:  ## ruff check
+	$(RUFF) check lmrelay tests
+
+fmt:  ## ruff --fix + ruff format
+	$(RUFF) check --fix lmrelay tests
+	$(RUFF) format lmrelay tests
+
+format: fmt  ## Alias for fmt
+
+typecheck:  ## mypy
+	$(MYPY) lmrelay
+
+check: lint typecheck test  ## lint + typecheck + tests
+
+clean:  ## Remove build artifacts and tool caches
+	rm -rf build dist *.egg-info \
+	       .pytest_cache .mypy_cache .ruff_cache \
+	       htmlcov .coverage coverage.xml
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +
+
+serve:  ## Run lmrelay serve in dev mode (--reload, bound to 127.0.0.1)
+	$(LMRELAY) serve --reload --host 127.0.0.1
+
+reload:  ## Tell a running gateway to re-read its config
+	$(LMRELAY) reload
+
+ping:  ## List providers (enabled/disabled) and ping each enabled one
+	$(LMRELAY) ping
+
+build:  ## Build sdist and wheel into ./dist/
+	$(PYTHON) -m pip install --upgrade build
+	$(PYTHON) -m build
+
+docker:  ## Build the local docker image (tag: lmrelay:dev)
+	docker build -t lmrelay:dev .
+
+compose-up:  ## docker compose up -d (frl_app + frl_watcher)
+	docker compose up -d
+
+compose-down:  ## docker compose down
+	docker compose down