Add LLM client interface with LiteLLM adapter (A5/A11)

PR 2 of the steps-3/4 plan.

- llm.py: LLMClient protocol — complete(events, tools, model) ->
  canonical events — present from the first real LLM call.
  LiteLLMClient renders requests via the A10 renderer, targets the
  proxy's OpenAI-compatible route, and maps provider tool-call IDs
  to locally-minted canonical IDs at the boundary
- RoleMap (A11): executor/planner/delegate/consultant resolved from
  env; pinned() returns the mapping to record at task start
- Config strictly from env: NISSE_LLM_BASE_URL, NISSE_LLM_TOKEN;
  envfile.py is a minimal .env loader where real env wins; .env now
  gitignored with a committed .env.example documenting all variables
  (Matrix ones included for the upcoming transport PR)
- Live smoke test against the proxy is integration-marked and skips
  without credentials — CI stays credential-free per operator
  decision; the test runs locally once .env exists
- httpx added as nisse-dev's HTTP client

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

nisse-dev/pyproject.toml

@@ -3,7 +3,7 @@ name = "nisse-dev"
 version = "0.1.0"
 description = "Dev agent: plans and implements software projects, produces Gitea PRs"
 requires-python = ">=3.12"
-dependencies = ["nisse-core"]
+dependencies = ["nisse-core", "httpx>=0.27"]
 
 [project.scripts]
 nisse-dev = "nisse_dev.main:main"

nisse-dev/src/nisse_dev/envfile.py

@@ -0,0 +1,22 @@
+"""Minimal .env loader (spec A5: config from env/.env, nothing hardcoded).
+
+Deliberately tiny: KEY=VALUE lines, comments and blanks ignored, existing
+environment variables never overridden (real env wins over the file).
+"""
+
+import os
+from collections.abc import MutableMapping
+from pathlib import Path
+
+
+def load_env_file(path: Path, env: MutableMapping[str, str] = os.environ) -> None:
+    if not path.exists():
+        return
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        if key and key not in env:
+            env[key] = value.strip()

nisse-dev/src/nisse_dev/llm.py

@@ -0,0 +1,144 @@
+"""LLM access (spec A5, A11).
+
+One client interface, present from the first real LLM call. All traffic goes
+to the LiteLLM proxy — the VM's single LLM destination; the agent holds one
+LiteLLM token and no vendor credentials. Config comes from the environment
+(``NISSE_LLM_BASE_URL``, ``NISSE_LLM_TOKEN``), nothing hardcoded.
+
+Model identity is expressed as roles (A11), resolved to concrete model strings
+from env config; the resolved mapping is pinned at task start so a mid-task
+config change cannot split a task across two planners.
+"""
+
+import json
+import os
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass
+from typing import Any, ClassVar, Protocol
+
+import httpx
+
+from nisse_dev.canonical import (
+    AssistantText,
+    CanonicalEvent,
+    StoredEvent,
+    ToolCall,
+    mint_call_id,
+)
+from nisse_dev.render import OpenAIChatRenderer
+
+
+class LLMError(RuntimeError):
+    pass
+
+
+class LLMClient(Protocol):
+    def complete(
+        self,
+        events: list[StoredEvent],
+        tools: list[dict[str, Any]] | None,
+        model: str,
+        system: str | None = None,
+    ) -> list[CanonicalEvent]: ...
+
+
+@dataclass(frozen=True)
+class RoleMap:
+    executor: str
+    planner: str
+    delegate: str
+    consultant: str
+
+    _ENV_VARS: ClassVar[dict[str, str]] = {
+        "executor": "NISSE_ROLE_EXECUTOR",
+        "planner": "NISSE_ROLE_PLANNER",
+        "delegate": "NISSE_ROLE_DELEGATE",
+        "consultant": "NISSE_ROLE_CONSULTANT",
+    }
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] = os.environ) -> "RoleMap":
+        missing = [var for var in cls._ENV_VARS.values() if not env.get(var)]
+        if missing:
+            raise LLMError(f"role mapping incomplete; set: {', '.join(missing)}")
+        return cls(**{role: env[var] for role, var in cls._ENV_VARS.items()})
+
+    def resolve(self, role: str) -> str:
+        if role not in self._ENV_VARS:
+            raise LLMError(f"unknown role: {role!r}")
+        return str(getattr(self, role))
+
+    def pinned(self) -> dict[str, str]:
+        """The full resolved mapping, to record at task start (A11)."""
+        return asdict(self)
+
+
+class LiteLLMClient:
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        timeout_s: float = 120.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout_s,
+            transport=transport,
+        )
+        self._renderer = OpenAIChatRenderer()
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] = os.environ) -> "LiteLLMClient":
+        base_url = env.get("NISSE_LLM_BASE_URL")
+        token = env.get("NISSE_LLM_TOKEN")
+        if not base_url or not token:
+            raise LLMError("set NISSE_LLM_BASE_URL and NISSE_LLM_TOKEN")
+        return cls(base_url, token)
+
+    def complete(
+        self,
+        events: list[StoredEvent],
+        tools: list[dict[str, Any]] | None,
+        model: str,
+        system: str | None = None,
+    ) -> list[CanonicalEvent]:
+        body = self._renderer.render(events, tools, model, system=system)
+        try:
+            response = self._http.post("/chat/completions", json=body)
+        except httpx.HTTPError as exc:
+            raise LLMError(f"LLM request failed: {exc}") from exc
+        if response.status_code != 200:
+            raise LLMError(
+                f"LLM request returned {response.status_code}: {response.text[:500]}"
+            )
+        return self._parse(response.json(), requested_model=model)
+
+    def _parse(
+        self, data: dict[str, Any], requested_model: str
+    ) -> list[CanonicalEvent]:
+        try:
+            message = data["choices"][0]["message"]
+        except (KeyError, IndexError) as exc:
+            raise LLMError(f"malformed completion response: {exc}") from exc
+        produced_by = data.get("model") or requested_model
+        out: list[CanonicalEvent] = []
+        if message.get("content"):
+            out.append(AssistantText(text=message["content"], model=produced_by))
+        # Provider tool-call IDs are mapped at the boundary (A10): each call
+        # gets a locally-minted canonical ID; the provider's is dropped, since
+        # every future request is rendered wholly from the canonical log.
+        for call in message.get("tool_calls") or []:
+            out.append(
+                ToolCall(
+                    call_id=mint_call_id(),
+                    tool=call["function"]["name"],
+                    arguments=json.loads(call["function"]["arguments"] or "{}"),
+                )
+            )
+        return out
+
+    def close(self) -> None:
+        self._http.close()

nisse-dev/tests/test_llm.py

@@ -0,0 +1,147 @@
+import json
+from pathlib import Path
+
+import httpx
+import pytest
+
+from nisse_dev.canonical import (
+    AssistantText,
+    StoredEvent,
+    ToolCall,
+    UserMessage,
+)
+from nisse_dev.envfile import load_env_file
+from nisse_dev.llm import LiteLLMClient, LLMError, RoleMap
+
+EVENTS = [StoredEvent(id=1, ts="t", event=UserMessage(text="hi", source="m:1"))]
+
+
+def make_client(handler) -> LiteLLMClient:
+    return LiteLLMClient(
+        "http://litellm.test/v1",
+        "sk-test",
+        transport=httpx.MockTransport(handler),
+    )
+
+
+def completion(message: dict) -> httpx.Response:
+    return httpx.Response(
+        200, json={"model": "gpt-test-1", "choices": [{"message": message}]}
+    )
+
+
+def test_request_shape_and_auth() -> None:
+    seen: dict = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["url"] = str(request.url)
+        seen["auth"] = request.headers.get("authorization")
+        seen["body"] = json.loads(request.content)
+        return completion({"content": "hello"})
+
+    make_client(handler).complete(EVENTS, tools=None, model="local/qwen", system="s")
+    assert seen["url"] == "http://litellm.test/v1/chat/completions"
+    assert seen["auth"] == "Bearer sk-test"
+    assert seen["body"]["model"] == "local/qwen"
+    assert seen["body"]["messages"][0] == {"role": "system", "content": "s"}
+    assert seen["body"]["messages"][1] == {"role": "user", "content": "hi"}
+
+
+def test_assistant_text_parsed_with_producing_model() -> None:
+    client = make_client(lambda request: completion({"content": "hello"}))
+    [event] = client.complete(EVENTS, tools=None, model="local/qwen")
+    assert event == AssistantText(text="hello", model="gpt-test-1")
+
+
+def test_tool_calls_get_locally_minted_canonical_ids() -> None:
+    message = {
+        "content": None,
+        "tool_calls": [
+            {
+                "id": "call_provider_abc",
+                "type": "function",
+                "function": {
+                    "name": "run_tests",
+                    "arguments": '{"path": "tests/"}',
+                },
+            }
+        ],
+    }
+    client = make_client(lambda request: completion(message))
+    [event] = client.complete(EVENTS, tools=None, model="local/qwen")
+    assert isinstance(event, ToolCall)
+    assert event.tool == "run_tests"
+    assert event.arguments == {"path": "tests/"}
+    assert event.call_id != "call_provider_abc"  # provider ID never a join key
+    assert event.call_id.startswith("call-")
+
+
+def test_http_error_status_raises_llm_error() -> None:
+    client = make_client(lambda request: httpx.Response(429, text="rate limited"))
+    with pytest.raises(LLMError, match="429"):
+        client.complete(EVENTS, tools=None, model="local/qwen")
+
+
+def test_connection_failure_raises_llm_error() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("refused")
+
+    with pytest.raises(LLMError, match="request failed"):
+        make_client(handler).complete(EVENTS, tools=None, model="local/qwen")
+
+
+def test_malformed_response_raises_llm_error() -> None:
+    client = make_client(lambda request: httpx.Response(200, json={"oops": True}))
+    with pytest.raises(LLMError, match="malformed"):
+        client.complete(EVENTS, tools=None, model="local/qwen")
+
+
+ROLE_ENV = {
+    "NISSE_ROLE_EXECUTOR": "local/qwen",
+    "NISSE_ROLE_PLANNER": "anthropic/claude-opus-5",
+    "NISSE_ROLE_DELEGATE": "anthropic/claude-opus-5",
+    "NISSE_ROLE_CONSULTANT": "anthropic/claude-opus-5",
+}
+
+
+def test_role_map_resolves_and_pins() -> None:
+    roles = RoleMap.from_env(ROLE_ENV)
+    assert roles.resolve("executor") == "local/qwen"
+    assert roles.pinned() == {
+        "executor": "local/qwen",
+        "planner": "anthropic/claude-opus-5",
+        "delegate": "anthropic/claude-opus-5",
+        "consultant": "anthropic/claude-opus-5",
+    }
+
+
+def test_role_map_missing_env_raises() -> None:
+    with pytest.raises(LLMError, match="NISSE_ROLE_PLANNER"):
+        RoleMap.from_env({"NISSE_ROLE_EXECUTOR": "local/qwen"})
+
+
+def test_unknown_role_raises() -> None:
+    with pytest.raises(LLMError, match="unknown role"):
+        RoleMap.from_env(ROLE_ENV).resolve("boss")
+
+
+def test_client_from_env_requires_config() -> None:
+    with pytest.raises(LLMError, match="NISSE_LLM_BASE_URL"):
+        LiteLLMClient.from_env({})
+
+
+def test_load_env_file(tmp_path: Path) -> None:
+    envfile = tmp_path / ".env"
+    envfile.write_text(
+        "# comment\n\nNISSE_LLM_TOKEN=sk-abc\nNISSE_LLM_BASE_URL = http://x \n"
+    )
+    env: dict[str, str] = {"NISSE_LLM_TOKEN": "sk-already-set"}
+    load_env_file(envfile, env)
+    assert env["NISSE_LLM_TOKEN"] == "sk-already-set"  # real env wins
+    assert env["NISSE_LLM_BASE_URL"] == "http://x"
+
+
+def test_load_env_file_missing_is_noop(tmp_path: Path) -> None:
+    env: dict[str, str] = {}
+    load_env_file(tmp_path / "nope.env", env)
+    assert env == {}