Render AHBG Seed of Life motion traces

.github/workflows/ahbg-ci.yml

@@ -0,0 +1,58 @@
+name: ahbg-ci
+
+on:
+  pull_request:
+    paths:
+      - "ahbg/**"
+      - ".github/workflows/ahbg-ci.yml"
+  push:
+    branches: [main]
+    paths:
+      - "ahbg/**"
+      - ".github/workflows/ahbg-ci.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    env:
+      PYTHONDONTWRITEBYTECODE: "1"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install verification dependencies
+        run: python -m pip install --upgrade pip pytest
+      - name: Compile AHBG Python surfaces
+        run: |
+          python - <<'PY'
+          from hashlib import sha256
+          from pathlib import Path
+          import py_compile
+          import tempfile
+
+          out_dir = Path(tempfile.mkdtemp(prefix="ahbg-pyc-"))
+          for path in sorted(Path("ahbg").rglob("*.py")):
+              out = out_dir / (sha256(str(path).encode("utf-8")).hexdigest() + ".pyc")
+              py_compile.compile(str(path), cfile=str(out), doraise=True)
+          PY
+      - name: Run AHBG engine tests
+        run: python -m unittest discover -s ahbg/engine/tests -p "test*.py"
+      - name: Run AHBG presentation tests
+        run: python -m unittest discover -s ahbg/presentation/tests -p "test*.py"
+      - name: Reject generated Python caches
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+
+          caches = sorted(str(path) for path in Path("ahbg").rglob("__pycache__"))
+          if caches:
+              raise SystemExit("generated Python caches present: " + ", ".join(caches))
+          PY

.gitignore

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

a0min/README.md

@@ -0,0 +1,108 @@
+# a0min — minimal agent harness over the platonic superpotential
+
+`a0min` imports the **platonic agent** from
+[`The-Interdependency/a0`](https://github.com/The-Interdependency/a0) and wraps
+it in the smallest harness that can create any of the **potential sub-agents**
+the superpotential declares, plus a minimal CLI.
+
+## Provenance
+
+| File | Imported from | Commit |
+|---|---|---|
+| `a0min/platonic/platonic.py` | `a0/python/agents/platonic.py` | `f9470a74138da89a2d075ecf6c3241aac63923f1` |
+| `a0min/platonic/platonic_regions.py` | `a0/python/agents/platonic_regions.py` | `f9470a74138da89a2d075ecf6c3241aac63923f1` |
+| `a0min/platonic/zfae.py` | `a0/python/agents/zfae.py` | `f9470a74138da89a2d075ecf6c3241aac63923f1` |
+
+The imported files are copied **verbatim** and retain their a0 canonical ratios
+seals. Cap semantics (depth / fanout / concurrent-live, tier fallbacks, env
+overrides) mirror `a0/python/services/spawn_caps.py`.
+
+## The superpotential and its options
+
+`candidate_platonic_agent()` is the open superpotential
+(`a0.agent.platonic`): 13 dimensions and 11 declared semantic regions. Each
+region is one **potential sub-agent option**:
+
+```
+definition, instance, run, semantic_memory, ptcna_runtime_state,
+run_artifacts, zfae_inference_binding, provider_relation,
+privacy_projection, spawn_merge, resource_need_matching
+```
+
+Creating a sub-agent means projecting one region: selected, omitted, and
+unresolved dimensions stay explicit; unknown regions and unknown dimensions
+fail closed.
+
+## Harness (library)
+
+```python
+from a0min import Harness, SpawnCapExceeded
+
+harness = Harness(tier="free")                 # caps from a0 spawn_caps
+options = harness.potential_sub_agents()       # the 11 potential sub-agents
+
+sub = harness.create(
+    "definition",
+    {"identity": {"definition_id": "def-1"}},
+    task="minimal definition",
+    orchestration_mode="single",
+    cut_mode="soft",
+)
+print(sub.sub_agent_id, sub.name, sub.unresolved)
+
+harness.merge(sub.sub_agent_id)                # release concurrent-live slot
+```
+
+Caps: `A0MIN_MAX_SPAWN_DEPTH` / `A0MIN_MAX_SPAWN_FANOUT` /
+`A0MIN_MAX_SPAWN_CONCURRENT_LIVE` env vars override tier defaults
+(`free=2/5/2`, `seeker=3/5/4`, `operator=4/5/8`, `patron=5/5/12`,
+`admin=5/5/20`).
+
+## CLI
+
+```bash
+cd a0min
+python3 -m a0min list                      # potential sub-agent options
+python3 -m a0min create definition \
+    --bind 'identity={"definition_id":"def-1"}' \
+    --task "minimal definition" --mode single --cut soft
+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
+python3 -m unittest discover -s tests -v
+```
+
+## Scope
+
+The harness is intentionally **in-memory and stdlib-only**. It creates and
+tracks sub-agent records; it does not execute inference, persistence, or
+networking. Runtime realization (providers, PCNA forks, storage) is downstream
+of the projection the harness produces.

a0min/a0min/__init__.py

@@ -0,0 +1,52 @@
+# 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:
+- PlatonicAgent, AgentDimension, AgentSemanticRegion, AgentProjection
+  (imported verbatim from The-Interdependency/a0 @ f9470a74)
+- 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,
+    Harness,
+    PotentialSubAgent,
+    SpawnCapExceeded,
+    SubAgent,
+)
+from .platonic import (
+    AgentDimension,
+    AgentProjection,
+    AgentSemanticRegion,
+    PlatonicAgent,
+    ZFAE_AGENT_DEF,
+    candidate_platonic_agent,
+    compose_name,
+)
+
+__all__ = [
+    "AgentDimension",
+    "AgentSemanticRegion",
+    "AgentProjection",
+    "PlatonicAgent",
+    "candidate_platonic_agent",
+    "ZFAE_AGENT_DEF",
+    "compose_name",
+    "Harness",
+    "PotentialSubAgent",
+    "SubAgent",
+    "SpawnCapExceeded",
+    "SUPPORTED_ORCHESTRATION_MODES",
+    "SUPPORTED_CUT_MODES",
+    "available_providers",
+    "load_provider_keys",
+    "presence",
+    "provider_key",
+]
+# ratios: loc_comments=37:10 imports_exports=3:1 calls_definitions=0:0

a0min/a0min/__main__.py

@@ -0,0 +1,7 @@
+# ratios: loc_comments=2:1 imports_exports=1:0 calls_definitions=1:0
+"""python -m a0min entry point."""
+
+from .cli import main
+
+raise SystemExit(main())
+# ratios: loc_comments=2:1 imports_exports=1:0 calls_definitions=1:0