lio-nix-bridge (Nix Bridge Gateway)

This repo is a minimal, CI-proven example of:

1. a reproducible dev environment (Nix flake devShell), and
2. a reproducible deployable artifact (gateway) that runs a FastAPI/Uvicorn service.

The point: one repo → same tools, same build, same runnable artifact, locally and in CI.

---

What’s in here

• Nix flake
  • devShells.default: pinned toolchain for development (Python + uv + ruff + Node, etc.)
  • packages.gateway + apps.gateway: lets both work:
    • nix build .#gateway → produces a runnable artifact
    • nix run .#gateway → runs it directly
• Gateway service
  • FastAPI/Uvicorn app
  • Endpoints:
    • GET /health
    • GET /v1/models
    • POST /v1/chat/completions
  • Adds request-id + backend metadata (useful for debugging and for validating backend selection)
• CI (Linux runner)
  • Installs Nix
  • Builds the package
  • Starts the gateway
  • Waits for /health
  • Runs a tiny smoke test
  • Prints logs if startup fails (so debugging isn’t random)

---

Quick start

1) Enter the pinned dev environment

nix develop

If you use direnv, run once:

direnv allow

2) Run the gateway

nix run .#gateway

Default port is 8000. Override with:

PORT=9000 nix run .#gateway

3) Smoke test

curl -sS localhost:${PORT:-8000}/health
curl -sS localhost:${PORT:-8000}/v1/models

---

Build the deployable artifact

nix build .#gateway
./result/bin/gateway

---

Repo hygiene

Local state is ignored so your working tree stays clean:

• .direnv/
• result/ (Nix build output symlink)

---

Common commands (muscle memory)

nix develop
direnv allow          # once, if using direnv
nix run .#gateway
nix build .#gateway
nix flake check

---

Roadmap (high ROI, minimal rabbit holes)

Phase 1 — Make it feel like a real mini-platform

• Package the Python code properly
  • Add pyproject.toml
  • Make src/lio_gateway/... an installable package
  • Update the Nix artifact so it runs without PYTHONPATH hacks
• Add a tiny config layer
  • File config (YAML/JSON) + env overrides
  • CI smoke test sets LIO_BACKEND and checks /backend and /v1/models
• Add one fast test
  • pytest using FastAPI TestClient (no network, fast)
  • Wire into nix flake check

Phase 2 (optional) — “Deploy artifact story”

• Build an OCI container image via Nix
• CI builds the image, runs it, hits /health

Phase 3 — Direct reuse in LIO

Move this exact pattern into the main LIO repo:

• flake/devShell/direnv
• CI smoke tests
• gateway packaging + config + backend selection hooks

---

Notes

• This repo is intentionally small. The goal is a clean reproducible baseline you can reuse elsewhere.
• If CI fails, check the Actions logs; the workflow prints gateway logs on startup failures.