Add a0min provider-key loader; ignore .env

Wires OpenAI/DeepSeek/xAI keys into a0min via a presence-only loader (explicit path exclusive, no value logging) and ignores .env to keep local secrets out of git.

Author: erinepshovel-code

.gitignore

@@ -1,2 +1,5 @@
 __pycache__/
 .skill-lib/
+
+# Local secrets
+.env

a0min/README.md

@@ -70,10 +70,30 @@ python3 -m a0min show a0z-12345678
 python3 -m a0min merge a0z-12345678
 python3 -m a0min superpotential            # dump the imported superpotential
 python3 -m a0min caps --tier seeker
+python3 -m a0min env                       # provider keys present (never values)
 ```
 
 Every command accepts `--json` for machine-readable output.
 
+## Provider keys
+
+`a0min.env` reads provider API keys from a local `.env` file without hardcoding
+them and without ever emitting key values:
+
+```python
+from a0min import load_provider_keys, provider_key, available_providers, presence
+
+keys = load_provider_keys()          # {'openai': ..., 'deepseek': ..., 'xai': ...}
+provider_key("openai")               # the key, or None
+available_providers()                # ('openai', 'deepseek', 'xai') subset
+presence()                           # {'openai': True, ...} — booleans only
+```
+
+Search order: `A0MIN_ENV_PATH`, then `./.env`, then `~/.env` (first match wins
+per provider). Supported variables: `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`,
+`XAI_API_KEY`. The `env` CLI command (and `presence()`) expose presence only —
+key material is returned solely to in-process callers that ask for it.
+
 ## Tests
 
 ```bash

a0min/a0min/__init__.py

@@ -1,4 +1,4 @@
-# ratios: loc_comments=32:8 imports_exports=2:1 calls_definitions=0:0
+# ratios: loc_comments=37:10 imports_exports=3:1 calls_definitions=0:0
 """a0min — minimal agent harness over the imported a0 platonic superpotential.
 
 Public surface:
@@ -7,8 +7,11 @@
 - candidate_platonic_agent — the open superpotential with current a0 regions
 - Harness — creates any potential sub-agent by projecting a declared region
 - SubAgent, PotentialSubAgent, SpawnCapExceeded
+- load_provider_keys, provider_key, available_providers, presence
+  (provider-key loader; reads .env, never exposes key values in summaries)
 """
 
+from .env import available_providers, load_provider_keys, presence, provider_key
 from .harness import (
     SUPPORTED_CUT_MODES,
     SUPPORTED_ORCHESTRATION_MODES,
@@ -41,5 +44,9 @@
     "SpawnCapExceeded",
     "SUPPORTED_ORCHESTRATION_MODES",
     "SUPPORTED_CUT_MODES",
+    "available_providers",
+    "load_provider_keys",
+    "presence",
+    "provider_key",
 ]
-# ratios: loc_comments=32:8 imports_exports=2:1 calls_definitions=0:0
+# ratios: loc_comments=37:10 imports_exports=3:1 calls_definitions=0:0

a0min/a0min/cli.py

@@ -1,4 +1,4 @@
-# ratios: loc_comments=201:10 imports_exports=8:1 calls_definitions=84:9
+# ratios: loc_comments=221:11 imports_exports=9:1 calls_definitions=92:10
 """Minimal CLI for the a0min agent harness.
 
 Commands:
@@ -8,6 +8,7 @@
     merge ID             mark a created sub-agent merged
     superpotential       dump the imported platonic superpotential
     caps                 show spawn caps for a tier
+    env                  show which provider keys are present (never the values)
 
 Every command accepts ``--json`` for machine-readable output.
 """
@@ -21,6 +22,7 @@
 from pathlib import Path
 from typing import Any
 
+from .env import presence as provider_presence
 from .harness import (
     SUPPORTED_CUT_MODES,
     SUPPORTED_ORCHESTRATION_MODES,
@@ -94,6 +96,16 @@ def _build_parser() -> argparse.ArgumentParser:
     caps_parser.add_argument("--tier", default="free", help="spawn-cap tier")
     caps_parser.add_argument("--json", action="store_true", dest="as_json")
 
+    env_parser = sub.add_parser(
+        "env", help="show which provider keys are present (never the values)"
+    )
+    env_parser.add_argument(
+        "--env-file",
+        default=None,
+        help="explicit .env file path (default: A0MIN_ENV_PATH, then ./.env, then ~/.env)",
+    )
+    env_parser.add_argument("--json", action="store_true", dest="as_json")
+
     return parser
 
 
@@ -209,6 +221,16 @@ def _superpotential(harness: Harness, as_json: bool) -> int:
     return 0
 
 
+def _env(args: argparse.Namespace) -> int:
+    report = provider_presence(explicit=args.env_file)
+    if args.as_json:
+        print(json.dumps(report, indent=2))
+        return 0
+    for provider, present in report.items():
+        print(f"{provider}: {'present' if present else 'missing'}")
+    return 0
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = _build_parser()
     args = parser.parse_args(argv)
@@ -236,11 +258,13 @@ def main(argv: list[str] | None = None) -> int:
         else:
             _print_or_json(harness.caps, False)
         code = 0
+    elif args.command == "env":
+        code = _env(args)
     else:
         parser.error(f"unknown command: {args.command}")
         code = 2
 
     if state_path and code == 0:
         harness.save(state_path)
     return code
-# ratios: loc_comments=201:10 imports_exports=8:1 calls_definitions=84:9
+# ratios: loc_comments=221:11 imports_exports=9:1 calls_definitions=92:10

a0min/a0min/env.py

@@ -0,0 +1,90 @@
+# ratios: loc_comments=53:15 imports_exports=4:4 calls_definitions=15:6
+"""Minimal provider-key loader for a0min.
+
+Reads provider API keys from a local ``.env`` file without hardcoding them and
+without ever emitting key values.
+
+When an explicit path is given, only that file is read. Otherwise the search
+order is ``./.env`` (current working directory) then ``~/.env`` (user home),
+first match wins per provider.
+
+Supported provider keys: ``OPENAI_API_KEY``, ``DEEPSEEK_API_KEY``,
+``XAI_API_KEY``. Raw key material is returned only to in-process callers on
+request; summaries expose presence only.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Mapping
+
+PROVIDER_KEY_NAMES = ("OPENAI_API_KEY", "DEEPSEEK_API_KEY", "XAI_API_KEY")
+
+_PROVIDER_BY_KEY = {
+    "OPENAI_API_KEY": "openai",
+    "DEEPSEEK_API_KEY": "deepseek",
+    "XAI_API_KEY": "xai",
+}
+
+_PROVIDER_ORDER = ("openai", "deepseek", "xai")
+
+
+def _parse_env_file(path: Path) -> dict[str, str]:
+    """Parse KEY=VALUE lines from a .env file; never logs values."""
+    values: dict[str, str] = {}
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        values[key.strip()] = value.strip().strip('"').strip("'")
+    return values
+
+
+def _candidate_paths(
+    explicit: str | os.PathLike[str] | None = None,
+) -> list[Path]:
+    if explicit:
+        return [Path(explicit)]
+    return [Path.cwd() / ".env", Path.home() / ".env"]
+
+
+def load_provider_keys(
+    explicit: str | os.PathLike[str] | None = None,
+) -> dict[str, str]:
+    """Return ``provider -> key`` for every supported key found."""
+    found: dict[str, str] = {}
+    for path in _candidate_paths(explicit):
+        if not path.is_file():
+            continue
+        for key, value in _parse_env_file(path).items():
+            provider = _PROVIDER_BY_KEY.get(key)
+            if provider and value and provider not in found:
+                found[provider] = value
+    return found
+
+
+def provider_key(
+    provider: str,
+    explicit: str | os.PathLike[str] | None = None,
+) -> str | None:
+    """Return one provider key, or None when not configured."""
+    return load_provider_keys(explicit).get(provider)
+
+
+def available_providers(
+    explicit: str | os.PathLike[str] | None = None,
+) -> tuple[str, ...]:
+    """Configured provider names in stable order."""
+    found = load_provider_keys(explicit)
+    return tuple(provider for provider in _PROVIDER_ORDER if provider in found)
+
+
+def presence(
+    explicit: str | os.PathLike[str] | None = None,
+) -> Mapping[str, bool]:
+    """Presence map for every supported provider; values never contain keys."""
+    found = load_provider_keys(explicit)
+    return {provider: provider in found for provider in _PROVIDER_ORDER}
+# ratios: loc_comments=53:15 imports_exports=4:4 calls_definitions=15:6

a0min/tests/test_a0min.py

@@ -1,4 +1,4 @@
-# ratios: loc_comments=143:4 imports_exports=9:3 calls_definitions=86:21
+# ratios: loc_comments=184:4 imports_exports=10:4 calls_definitions=112:26
 """Stdlib-only tests for the a0min harness and CLI.
 
 Run from the a0min project root:
@@ -11,6 +11,7 @@
 import json
 import subprocess
 import sys
+import tempfile
 import unittest
 from pathlib import Path
 
@@ -19,7 +20,11 @@
 from a0min import (  # noqa: E402  (project root on sys.path via test runner)
     Harness,
     SpawnCapExceeded,
+    available_providers,
     candidate_platonic_agent,
+    load_provider_keys,
+    presence,
+    provider_key,
 )
 
 
@@ -120,6 +125,37 @@ def test_save_load_roundtrip(self) -> None:
             self.assertEqual(restored._index, self.harness._index)
 
 
+class EnvLoaderTests(unittest.TestCase):
+    def test_loads_provider_keys_without_exposing_them(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            env_path = Path(tmp) / ".env"
+            env_path.write_text(
+                "OPENAI_API_KEY=sk-test-openai\n"
+                "DEEPSEEK_API_KEY=sk-test-deepseek\n"
+                "XAI_API_KEY=xai-test\n",
+                encoding="utf-8",
+            )
+            keys = load_provider_keys(explicit=env_path)
+            self.assertEqual(keys["openai"], "sk-test-openai")
+            self.assertEqual(keys["deepseek"], "sk-test-deepseek")
+            self.assertEqual(keys["xai"], "xai-test")
+
+    def test_presence_never_contains_values(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            env_path = Path(tmp) / ".env"
+            env_path.write_text("OPENAI_API_KEY=sk-secret\n", encoding="utf-8")
+            report = presence(explicit=env_path)
+            self.assertEqual(report, {"openai": True, "deepseek": False, "xai": False})
+            self.assertNotIn("sk-secret", json.dumps(report))
+
+    def test_provider_key_missing_returns_none(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            env_path = Path(tmp) / ".env"
+            env_path.write_text("", encoding="utf-8")
+            self.assertIsNone(provider_key("openai", explicit=env_path))
+            self.assertEqual(available_providers(explicit=env_path), ())
+
+
 class CliSmokeTests(unittest.TestCase):
     def run_cli(self, *args: str) -> subprocess.CompletedProcess[str]:
         return subprocess.run(
@@ -176,7 +212,17 @@ def test_superpotential_json(self) -> None:
         self.assertEqual(len(payload["dimensions"]), 13)
         self.assertEqual(len(payload["regions"]), 11)
 
+    def test_env_json_shows_presence_only(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            env_path = Path(tmp) / ".env"
+            env_path.write_text("OPENAI_API_KEY=sk-secret\n", encoding="utf-8")
+            result = self.run_cli("env", "--env-file", str(env_path), "--json")
+            self.assertEqual(result.returncode, 0, result.stderr)
+            payload = json.loads(result.stdout)
+            self.assertEqual(payload, {"openai": True, "deepseek": False, "xai": False})
+            self.assertNotIn("sk-secret", result.stdout)
+
 
 if __name__ == "__main__":
     unittest.main()
-# ratios: loc_comments=143:4 imports_exports=9:3 calls_definitions=86:21
+# ratios: loc_comments=184:4 imports_exports=10:4 calls_definitions=112:26