feat(web): load API keys from git-ignored .env at startup (fixes ollama:*-cloud key error)

proteus/env_loader.py

@@ -0,0 +1,74 @@
+"""Minimal, dependency-free ``.env`` loader.
+
+The project keeps provider API keys (``OLLAMA_API_KEY``, ``OPENAI_API_KEY``,
+``ANTHROPIC_API_KEY``, …) in a git-ignored ``.env`` at the repo root. Nothing
+loads it automatically, so a freshly launched web/CLI process doesn't see those
+keys unless the user exported them by hand — which is why ``ollama:…-cloud``
+fails with "API key must be provided".
+
+``load_dotenv()`` finds the nearest ``.env`` walking up from the current working
+directory and copies its ``KEY=VALUE`` lines into ``os.environ``. Real
+environment variables win by default (``override=False``), so an explicitly
+exported key is never clobbered. No third-party dependency (keeps the offline
+test suite dependency-free).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def _parse(text: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.lower().startswith("export "):
+            line = line[len("export "):].lstrip()
+        key, _, val = line.partition("=")
+        key = key.strip()
+        val = val.strip()
+        if val[:1] in {'"', "'"} and val[-1:] == val[:1]:
+            val = val[1:-1]                 # quoted: keep verbatim (may contain '#')
+        else:
+            cut = val.find(" #")            # unquoted: drop a whitespace-led inline comment
+            if cut != -1:
+                val = val[:cut].rstrip()
+        if key:
+            out[key] = val
+    return out
+
+
+def find_dotenv(start: str | os.PathLike[str] | None = None) -> Path | None:
+    """Return the nearest ``.env`` walking up from *start* (default CWD)."""
+    base = Path(start) if start is not None else Path.cwd()
+    base = base.resolve()
+    for d in (base, *base.parents):
+        candidate = d / ".env"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load_dotenv(
+    start: str | os.PathLike[str] | None = None, *, override: bool = False
+) -> str | None:
+    """Load the nearest ``.env`` into ``os.environ``.
+
+    Args:
+        start: Directory to begin the upward search (default: CWD).
+        override: If True, ``.env`` values replace existing env vars. Default
+            False — a key already in the environment is left untouched.
+
+    Returns:
+        The path of the ``.env`` that was loaded, or ``None`` if none was found.
+    """
+    path = find_dotenv(start)
+    if path is None:
+        return None
+    for key, val in _parse(path.read_text(encoding="utf-8")).items():
+        if override or key not in os.environ:
+            os.environ[key] = val
+    return str(path)

proteus/web/local/__main__.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 import argparse
 
 import proteus.game.scenarios  # noqa: F401  (registers scenarios before any request)
+from proteus.env_loader import load_dotenv
 from proteus.web.local.server import make_server
 
 
@@ -13,6 +14,12 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--port", type=int, default=8000)
     args = parser.parse_args(argv)
 
+    # Load provider API keys from the repo's git-ignored .env so cloud models
+    # (ollama:*-cloud, openai, anthropic, …) work without a manual `export`.
+    loaded = load_dotenv()
+    if loaded:
+        print(f"loaded API keys from {loaded}")
+
     server = make_server(args.host, args.port)
     host, port = server.server_address[0], server.server_address[1]
     print(f"AgentnessBench — open http://{host}:{port}/  (Ctrl-C to stop)")

tests/test_env_loader.py

@@ -0,0 +1,35 @@
+"""env_loader: load the nearest .env without clobbering real env vars."""
+import os
+
+from proteus.env_loader import find_dotenv, load_dotenv
+
+
+def test_loads_keys_without_overriding_existing(tmp_path, monkeypatch):
+    (tmp_path / ".env").write_text(
+        "# provider keys\n"
+        "OLLAMA_API_KEY=from_dotenv\n"
+        'OPENAI_API_KEY="quoted_value"\n'
+        "export ANTHROPIC_API_KEY=exported_style  # inline note\n"
+        "ALREADY_SET=should_not_win\n"
+    )
+    monkeypatch.setenv("ALREADY_SET", "real_env")     # real env must win
+    for k in ("OLLAMA_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY"):
+        monkeypatch.delenv(k, raising=False)          # ensure .env values can land
+
+    loaded = load_dotenv(start=tmp_path)
+    assert loaded == str(tmp_path / ".env")
+    assert os.environ["OLLAMA_API_KEY"] == "from_dotenv"
+    assert os.environ["OPENAI_API_KEY"] == "quoted_value"          # quotes stripped
+    assert os.environ["ANTHROPIC_API_KEY"] == "exported_style"     # export + inline comment handled
+    assert os.environ["ALREADY_SET"] == "real_env"                 # not overridden
+
+
+def test_finds_dotenv_walking_up(tmp_path):
+    (tmp_path / ".env").write_text("K=v\n")
+    deep = tmp_path / "a" / "b" / "c"
+    deep.mkdir(parents=True)
+    assert find_dotenv(start=deep) == tmp_path / ".env"            # walks up to the root .env
+
+
+def test_returns_none_when_absent(tmp_path):
+    assert load_dotenv(start=tmp_path) is None