localgate 0.7.0__tar.gz

localgate-0.7.0/.env.example

@@ -0,0 +1,62 @@
+# Copy to .env and edit. Every setting is documented in docs/configuration.md.
+
+# --- Deployment ------------------------------------------------------------
+# `production` makes the gateway REFUSE to start with the placeholder admin key below.
+LOCALGATE_ENVIRONMENT=development
+
+# --- Auth ------------------------------------------------------------------
+# Generate a real one:  openssl rand -hex 32
+LOCALGATE_ADMIN_KEY=change-me-in-production
+LOCALGATE_DEFAULT_RATE_LIMIT_PER_MIN=60
+
+# --- Server ----------------------------------------------------------------
+LOCALGATE_HOST=0.0.0.0
+LOCALGATE_PORT=8000
+# Only needed if a browser calls the API directly. Comma-separated.
+# LOCALGATE_CORS_ORIGINS=http://localhost:3000
+
+# --- Inference backend -----------------------------------------------------
+# ollama | vllm | llamacpp | openai_compat  (or any installed plugin)
+LOCALGATE_BACKEND_TYPE=ollama
+LOCALGATE_BACKEND_URL=http://localhost:11434
+LOCALGATE_DEFAULT_MODEL=llama3
+# Raise for large models on CPU.
+LOCALGATE_BACKEND_TIMEOUT=120
+# For upstreams that need their own auth.
+# LOCALGATE_BACKEND_API_KEY=
+
+# Map friendly names to real model ids, so you can swap models without touching clients.
+# LOCALGATE_MODEL_ALIASES={"fast":"phi4-mini","smart":"llama3:70b"}
+
+# --- Database --------------------------------------------------------------
+# The driver must be ASYNC. Note `+asyncpg`, not a bare `postgresql://`.
+LOCALGATE_DATABASE_URL=sqlite+aiosqlite:///./localgate.db
+# Postgres: LOCALGATE_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/localgate
+# Neon:     LOCALGATE_DATABASE_URL=postgresql+asyncpg://user:pass@ep-xxx.neon.tech/localgate?ssl=require
+#           (Neon's copy-paste string says `sslmode=require`; asyncpg spells it `ssl=require`.)
+
+# --- Memory / RAG ----------------------------------------------------------
+LOCALGATE_MEMORY_ENABLED=true
+# Must be pulled on the backend:  ollama pull nomic-embed-text
+LOCALGATE_EMBEDDING_MODEL=nomic-embed-text
+LOCALGATE_CHUNK_SIZE=512
+LOCALGATE_CHUNK_OVERLAP=50
+LOCALGATE_MAX_RETRIEVED_CHUNKS=5
+# Cosine-similarity floor for injecting a chunk. 0.0 = no floor. With a real embedding
+# model, 0.3-0.5 is typical — see docs/rag-memory.md for how to tune it from your logs.
+LOCALGATE_MEMORY_MIN_SCORE=0.0
+# Summarize older turns past this many messages. 0 disables.
+LOCALGATE_SUMMARIZE_AFTER_MESSAGES=20
+
+# --- Prompt cache ----------------------------------------------------------
+# Off by default: caching makes identical requests return identical completions, which is
+# a real behaviour change if you sample at temperature > 0.
+LOCALGATE_CACHE_ENABLED=false
+LOCALGATE_CACHE_TTL_SECONDS=300
+LOCALGATE_CACHE_MAX_ENTRIES=512
+
+# --- Observability ---------------------------------------------------------
+LOCALGATE_LOG_LEVEL=INFO
+# `console` for humans, `json` for log ingestion.
+LOCALGATE_LOG_FORMAT=console
+LOCALGATE_METRICS_ENABLED=true

localgate-0.7.0/.github/CODEOWNERS

@@ -0,0 +1,11 @@
+# Default reviewer for everything.
+* @AnjalLLL
+
+# Changes here alter the security posture — auth, key handling, the rules that decide who
+# can call what. They always want a second pair of eyes, even on a one-line diff.
+/src/localgate/core/auth.py      @AnjalLLL
+/src/localgate/api/deps.py       @AnjalLLL
+/SECURITY.md                     @AnjalLLL
+
+# Migrations are the one thing a user cannot roll back by reverting a commit.
+/src/localgate/db/migrations/    @AnjalLLL

localgate-0.7.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+# github: [AnjalLLL]

localgate-0.7.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,13 @@
+---
+name: Bug report
+about: Report a bug
+labels: bug
+---
+
+**Describe the bug**
+
+**To reproduce**
+
+**Expected behavior**
+
+**Environment** (OS, Python version, backend used)

localgate-0.7.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

localgate-0.7.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,9 @@
+---
+name: Feature request
+about: Suggest an idea
+labels: enhancement
+---
+
+**Problem this solves**
+
+**Proposed solution**

localgate-0.7.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+## What this changes
+
+## How it was tested
+
+## Checklist
+- [ ] Tests added/updated
+- [ ] `make lint` passes

localgate-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Format check
+        run: uv run ruff format --check src/ tests/
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Test
+        run: uv run pytest -q --cov --cov-report=term-missing
+
+  postgres:
+    # The SQLite suite proves the logic. This proves the migrations and queries actually
+    # run on Postgres, which is what production uses — skipping it is how you ship a
+    # migration that only works on SQLite.
+    runs-on: ubuntu-latest
+    env:
+      LOCALGATE_DATABASE_URL: postgresql+asyncpg://localgate:localgate@localhost:5432/localgate
+      LOCALGATE_BACKEND_TYPE: fake
+      LOCALGATE_ADMIN_KEY: ci-admin-key
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: localgate
+          POSTGRES_PASSWORD: localgate
+          POSTGRES_DB: localgate
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --all-extras
+
+      - name: Migrate a real Postgres database
+        run: |
+          uv run localgate db upgrade
+          uv run localgate db current
+
+      - name: Migrations are idempotent (startup re-runs them on every boot)
+        run: uv run localgate db upgrade
+
+      - name: Create and list a key against Postgres
+        run: |
+          uv run localgate keys create --name ci-key
+          uv run localgate keys list
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build the image
+        run: docker build -t localgate:ci .
+
+      - name: The image starts and serves
+        run: |
+          docker run -d --name lg -p 8000:8000 \
+            -e LOCALGATE_BACKEND_TYPE=fake \
+            -e LOCALGATE_ADMIN_KEY=ci-admin-key \
+            localgate:ci
+          for _ in $(seq 1 30); do
+            curl -sf http://localhost:8000/health/live > /dev/null && break
+            sleep 1
+          done
+          curl -sf http://localhost:8000/health/live || (docker logs lg && exit 1)
+          docker rm -f lg

localgate-0.7.0/.github/workflows/docker.yml

@@ -0,0 +1,45 @@
+name: Docker
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  docker:
+    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 }}
+
+      - name: Tags and labels
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest
+
+      - uses: docker/build-push-action@v6
+        with:
+          push: true
+          # Local models run on Apple Silicon and on Raspberry Pis as often as on x86, so
+          # a gateway that only ships amd64 is useless to a large share of its users.
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

localgate-0.7.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  # Never publish something that doesn't pass. A tag is not a promise that CI ran — the
+  # tag can be pushed from a branch that was never tested, and PyPI releases cannot be
+  # unpublished, only yanked.
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --all-extras
+      - run: uv run ruff check src/ tests/
+      - run: uv run mypy src/
+      - run: uv run pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      # Trusted publishing: no API token to store, rotate, or leak.
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      # __version__ and pyproject's version are two places that can disagree, and the one
+      # users see at runtime is __version__. A release whose version lies about itself is
+      # worse than no release, so the tag must match both.
+      - name: Check the tag matches the declared version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          INIT=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/localgate/__init__.py)
+          TOML=$(sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml | head -1)
+          echo "tag=$TAG  __init__=$INIT  pyproject=$TOML"
+          test "$TAG" = "$INIT" && test "$TAG" = "$TOML"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

localgate-0.7.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Environments
+.venv/
+venv/
+env/
+
+# Secrets and local state. .env holds the admin key; localgate.config.json holds the
+# established database URL, credentials included.
+.env
+!.env.example
+localgate.config.json
+
+# Private planning notes — kept locally, never published.
+ROADMAP.md
+
+# Local codegen / patch scratch scripts
+apply_*.sh
+reapply_*.sh
+
+# Databases
+*.db
+*.sqlite
+*.sqlite3
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db

localgate-0.7.0/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+      # .gitignore already excludes .env, but `git add -f` exists and a committed .env
+      # leaks the admin key. This is the second line of defence.
+      - id: detect-private-key
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+      - id: mypy
+        files: ^src/
+        additional_dependencies:
+          - pydantic>=2.7
+          - pydantic-settings>=2.3

localgate-0.7.0/.python-version

@@ -0,0 +1 @@
+3.12

localgate-0.7.0/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.7.0] — 2026-07-19
+
+A coding agent, backed by whatever model localgate is already pointed at.
+
+### Added
+
+- **`localgate code`** — reads and edits files in a project directory, backed directly by
+  the configured inference backend (no API key needed, same pattern as `localgate health`).
+  Run it with no argument for an interactive REPL (`/exit`, `/clear`, `/model`, `/undo`), or
+  `localgate code "task"` for a single-shot run.
+- Tools: `read_file`, `write_file`, `list_directory`, `search_files` (grep-like), `git_status`,
+  `git_diff`. All confined to the project root; `.gitignore` and `.localgateignore` keep
+  secrets and generated directories out of the model's reach. No shell/`run_command` tool —
+  deliberately.
+- A git-aware safety net: a one-time warning before writing into a dirty tree (`--force` to
+  skip), optional `--auto-commit` (tagged `localgate-agent:`), and `/undo` to revert the last
+  write or the last agent commit.
+- Colored diffs before every write, streamed responses, and a spinner while waiting on the
+  model — via `rich`.
+- Session memory: conversation history and recalled context persist per project
+  (`.localgate/session_id`), reusing the same RAG memory tables the HTTP API uses.
+  `--no-memory` to opt out for a single run.
+- A fallback parser for models that print a tool call as plain-text JSON instead of using
+  structured `tool_calls` (observed with `qwen2.5-coder` via Ollama) — same execution path as
+  a real tool call, so confirmation/diff/memory logic isn't duplicated.
+- Shell completion: `localgate --install-completion`.
+
+## [0.6.0] — 2026-07-14
+
+The release where the advertised features actually work.
+
+### Fixed
+
+- **The vLLM, llama.cpp and generic OpenAI backends did not work at all.** They declared
+  `InferenceBackend` subclasses that implemented none of its abstract methods, so
+  `get_backend("vllm")` raised `TypeError` at startup. Three of the four advertised backends
+  were unusable. They now share a real OpenAI-compatible HTTP implementation.
+- **Malformed chat requests returned 500 instead of 422.** The handler read `body["messages"]`
+  off a raw dict, so a missing field was a crash rather than a client error. Every request
+  body is now validated by Pydantic.
+- **The admin key was compared with `==`**, which short-circuits at the first differing byte
+  and leaks the secret's prefix length through timing. Now `hmac.compare_digest`.
+- **The rate limiter never forgot a key it had seen**, leaking one dict entry per key
+  forever. Expired windows are now swept.
+- **Errors did not use the OpenAI envelope**, so the OpenAI SDK could not parse them. All
+  errors — including validation failures and mid-stream backend failures — now return
+  `{"error": {"message", "type", "code"}}`.
+- **A mid-stream backend failure left clients hanging.** It now reports the error inside the
+  stream and still terminates with `[DONE]`.
+
+### Added
+
+- **Migrations.** The schema is versioned with Alembic; `create_all` is gone. Databases from
+  0.1–0.2 (tables, but no `alembic_version`) are detected and adopted automatically without
+  data loss.
+- **A real CLI.** `keys create/list/revoke/usage`, `db upgrade/current/init`, `health`,
+  `backends` — the commands the README had been advertising all along.
+- **`/v1/models`, `/v1/embeddings`, `/v1/completions`** — previously empty files. The legacy
+  completions route is implemented by translating to chat, so it works against backends that
+  never implemented it.
+- **Rolling conversation summarization.** Past a threshold, older turns are incrementally
+  summarized and injected alongside retrieved chunks.
+- **Model aliasing.** `LOCALGATE_MODEL_ALIASES='{"fast":"phi4-mini"}'` — swap models without
+  touching clients.
+- **Prompt caching** (opt-in). Identical prompts skip inference. Off by default because it
+  makes sampling deterministic.
+- **Plugin system.** Backends are discovered via the `localgate.backends` entry point. The
+  built-ins use the same mechanism, so there's no privileged path a plugin can't take.
+- **Production hardening.** Structured JSON logs with correlation IDs, Prometheus `/metrics`,
+  a liveness/readiness split, graceful shutdown, and fail-fast config validation — production
+  now refuses to start with the placeholder admin key.
+- **`GET /admin/export`** — every row as JSON, so nobody is locked in.
+- **Retrieval score logging and `MEMORY_MIN_SCORE`** — the floor that stops irrelevant chunks
+  from filling the context window with noise.
+- **`key_prefix`** on keys, so a key can be identified in a listing.
+- **`PATCH /admin/keys/{id}`** — change a rate limit without reissuing the key.
+- **Documentation.** All seven docs were one-line stubs; they are now written, along with
+  three ADRs covering the decisions that shaped the codebase.
+
+### Changed
+
+- `GET /v1/conversations/{id}` now returns an object (messages, summary, chunk count) rather
+  than a bare array.
+- `POST /admin/keys` returns 201, not 200.
+- Usage records now carry latency and a cached flag.
+
+### Security
+
+- SECURITY.md claimed keys were bcrypted; they are SHA-256, which is the *correct* choice for
+  high-entropy random keys verified on every request. The document now says so and explains
+  why ([ADR 0003](docs/decisions/0003-sha256-for-api-keys.md)).
+
+## [0.2.0] — 2026-07-13
+
+### Added
+- Auth, token accounting, RAG memory, dashboard UI, established-database config.
+- Test suite with a deterministic `FakeBackend`.
+
+## [0.1.0] — 2026-07-13
+
+### Added
+- Initial scaffolding: FastAPI app, Ollama backend, `/v1/chat/completions`, config, CI.

localgate-0.7.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,6 @@
+# Contributor Covenant Code of Conduct
+
+This project adopts the Contributor Covenant. Be respectful, assume good faith,
+and report unacceptable behavior to the maintainers.
+
+Full text: https://www.contributor-covenant.org/version/2/1/code_of_conduct/

localgate-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing
+
+Thanks for wanting to help. This is meant to be an easy project to contribute to — the
+architecture is deliberately shaped so that the most common contributions (a new backend, a
+new database) are one file each.
+
+## Setup
+
+```bash
+git clone https://github.com/YOUR_USERNAME/localgate.git
+cd localgate
+uv sync --all-extras
+uv run pre-commit install
+
+make test      # 160 tests, no live Ollama needed
+make lint      # ruff + mypy
+```
+
+Tests run against a deterministic `FakeBackend` and an in-memory SQLite database, so the
+suite is fast and needs nothing installed.
+
+## The codebase in one minute
+
+```
+api/         routes — thin. Validate, delegate, respond. Never touch the database.
+core/        business logic — auth, rate limiting, tokens, caching. No HTTP awareness.
+backends/    one adapter per inference server.
+memory/      chunking, embedding, retrieval, summarization.
+db/          models + repositories. The only code that writes SQL.
+middleware/  request id, access log, metrics.
+```
+
+Read [docs/architecture.md](docs/architecture.md) before a substantial change, and the
+[ADRs](docs/decisions/) for *why* things are the way they are. If you're about to change
+something an ADR covers, that's fine — but say so in the PR, and update the ADR.
+
+## Adding a backend
+
+This is the highest-value contribution and it's genuinely small. If the server speaks the
+OpenAI API — most do — it's a subclass and a default port:
+
+```python
+# src/localgate/backends/my_server.py
+from localgate.backends.openai_compat import OpenAICompatBackend
+
+class MyServerBackend(OpenAICompatBackend):
+    name = "my-server"
+    default_base_url = "http://localhost:9000"
+```
+
+Register it in `pyproject.toml`:
+
+```toml
+[project.entry-points."localgate.backends"]
+my-server = "localgate.backends.my_server:MyServerBackend"
+```
+
+Add a case to `tests/unit/test_backends.py::test_every_advertised_backend_can_actually_be_instantiated`.
+That's it.
+
+If the server *doesn't* speak OpenAI, implement `InferenceBackend` directly (see
+`backends/base.py` — five methods) and translate in the adapter. Nothing above the backend
+layer should ever learn that your server is different.
+
+You can also ship a backend as **your own package** without touching this repo at all —
+declare the same entry point in your `pyproject.toml`. See
+[docs/architecture.md](docs/architecture.md#plugin-system).
+
+## Standards
+
+- **Type hints** on every function signature. `mypy src/` must pass.
+- **Comments explain *why*, never *what*.** The code already says what it does. A comment
+  earns its place by capturing the constraint, the tradeoff, or the bug that isn't visible
+  from reading the line. If it restates the code, delete it.
+- **Tests for every change.** A bug fix without a test that fails before it is not a fix.
+- **`ruff check` and `ruff format`** — pre-commit runs both.
+- **No `print`.** Use the structlog logger (`core/logging.py`).
+
+## Tests
+
+Write the test that would have caught the bug. The ones in here that earn their keep are:
+
+- `test_every_route_is_guarded` — auth is per-route, so a new route that forgets its
+  dependency would be silently public. This catches that.
+- `test_pre_migrations_database_is_adopted_without_losing_data` — the upgrade path for
+  existing users, which is exactly the thing you can't test by hand twice.
+- `test_streaming_still_records_usage_after_the_body_is_sent` — works in dev, breaks in
+  prod, if you get the session lifecycle wrong.
+
+Aim for that. Not coverage of lines, coverage of *failure modes*.
+
+## Pull requests
+
+1. Branch from `main`: `git checkout -b feat/my-thing`
+2. Make the change, with tests.
+3. `make lint && make test`
+4. Update `CHANGELOG.md` under `[Unreleased]`.
+5. Open the PR and fill in the template.
+
+Small PRs get reviewed fast. A 2000-line PR touching six subsystems will sit.
+
+## Good first issues
+
+Look for the `good-first-issue` label. Reliably useful things that are always open:
+
+- A backend adapter for a server that isn't supported yet
+- Better error messages — if something confused you, it will confuse the next person, and
+  the fix is a sentence
+- Documentation gaps, especially in [getting-started](docs/getting-started.md)
+- Anything in the [open issues](https://github.com/AnjalLLL/localgate/issues)
+
+## Code of Conduct
+
+This project follows the [Code of Conduct](CODE_OF_CONDUCT.md). It applies everywhere the
+project does.