Merge pull request #1 from hanamorix/week-1-scaffolding

feat: Week 1 scaffolding — brain package, CLI, tests, CI matrix

Author: hanamorix

.env.example

@@ -0,0 +1,30 @@
+# ═══════════════════════════════════════════════════════════
+# companion-emergence environment configuration
+# Copy this to `.env` and fill in your values. `.env` is gitignored.
+# ═══════════════════════════════════════════════════════════
+
+# ── Core framework ────────────────────────────────────────
+# Override the default platformdirs location for all state.
+# Useful for testing, for running multiple independent instances,
+# or for pinning state to a specific disk.
+# NELLBRAIN_HOME=
+
+# ── Bridge ────────────────────────────────────────────────
+# Host:port the bridge daemon binds to (default: 127.0.0.1:8765)
+# BRIDGE_BIND=
+
+# ── LLM provider selection ────────────────────────────────
+# Overrides persona.toml's [model] section at runtime.
+# PROVIDER=ollama
+# MODEL=nell-stage13-voice
+
+# ── IPC integration (optional, opt-in) ────────────────────
+# For NanoClaw / WhatsApp outbox integration. Leave unset to
+# disable; set to your JID to enable outbox→WhatsApp delivery.
+# Format for WhatsApp: <country-code><number>@s.whatsapp.net
+# NELL_IPC_JID=
+
+# ── Provider API keys (if using commercial LLM) ───────────
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+# KIMI_API_KEY=

.gitattributes

@@ -0,0 +1,18 @@
+# Normalise line endings. Prevents CRLF vs LF edit-war churn between
+# Hana's macOS machine and her Windows test machine.
+* text=auto
+
+# Binary files stay binary.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.gguf binary
+*.bin binary
+*.safetensors binary
+*.pt binary
+*.pth binary
+*.ckpt binary
+*.npy binary

.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py ${{ matrix.python-version }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12"]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run pytest
+        run: uv run pytest -v --tb=short
+
+      - name: Lint with ruff
+        run: uv run ruff check .

brain/__init__.py

@@ -0,0 +1,6 @@
+"""companion-emergence — framework for building emotionally aware AI companions.
+
+Reference implementation: Nell. See docs/source-spec/ for the full design.
+"""
+
+__version__ = "0.0.1"

brain/cli.py

@@ -0,0 +1,84 @@
+"""Entry point CLI for companion-emergence.
+
+Invoked as `nell <subcommand> [options]`. Week 1 ships `--version`, help,
+and a set of stub subcommands that print "not implemented yet" so the CLI
+surface is stable while subsequent weeks fill in functionality.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable
+
+from brain import __version__
+
+# Subcommands the framework plans to ship. Each is a stub in Week 1;
+# filled in across Weeks 2-8 as respective modules come online.
+_STUB_COMMANDS: tuple[str, ...] = (
+    "supervisor",
+    "dream",
+    "heartbeat",
+    "reflex",
+    "status",
+    "rest",
+    "soul",
+    "memory",
+    "works",
+    "migrate",
+)
+
+
+def _make_stub(name: str) -> Callable[[argparse.Namespace], int]:
+    """Factory: build a stub command handler that prints + returns 0.
+
+    The returned handler accepts `args: argparse.Namespace` as required by
+    the `args.func(args)` dispatch protocol — stubs don't read it, but the
+    signature shape is load-bearing and should not be "cleaned up" to `_args`.
+    """
+
+    def _handler(args: argparse.Namespace) -> int:
+        print(
+            f"nell {name} — not implemented yet. "
+            "This subcommand is wired in a future week per the implementation plan."
+        )
+        return 0
+
+    return _handler
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Construct the top-level argparse parser with all stub subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="nell",
+        description=("companion-emergence — CLI for building emotionally aware AI companions"),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"companion-emergence {__version__}",
+    )
+    subparsers = parser.add_subparsers(dest="command", title="subcommands")
+
+    for name in _STUB_COMMANDS:
+        sub = subparsers.add_parser(
+            name,
+            help=f"(stub) {name} — wired in a later week",
+        )
+        sub.set_defaults(func=_make_stub(name))
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point. Returns shell exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 1
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

brain/config.py

@@ -0,0 +1,144 @@
+"""Configuration loader for companion-emergence.
+
+Merges settings from three sources in increasing priority:
+
+1. persona/<name>/persona.toml  - persona defaults (baseline)
+2. .env in repo root            - local overrides
+3. Environment variables        - runtime overrides (highest priority)
+
+Each resolved value is traced so startup can report the effective source.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Config keys supported by the framework. Extended in later weeks.
+_SUPPORTED_KEYS: tuple[str, ...] = (
+    "BRIDGE_BIND",
+    "PROVIDER",
+    "MODEL",
+    "NELL_IPC_JID",
+)
+
+# Framework-level defaults, applied as the lowest-priority source so that
+# source_trace explicitly records "default" for unset keys (startup logging
+# can then distinguish "value came from default" from "value missing").
+_DEFAULTS: dict[str, str] = {
+    "BRIDGE_BIND": "127.0.0.1:8765",
+    "PROVIDER": "ollama",
+    "MODEL": "",
+    "NELL_IPC_JID": "",
+}
+
+
+@dataclass
+class Config:
+    """Resolved configuration for a persona session.
+
+    Attributes:
+        persona_name: Name of the active persona (derived from dir basename).
+        bridge_bind: Host:port the bridge listens on.
+        provider: LLM provider key (ollama, claude, openai, kimi).
+        model: Model tag for the active provider.
+        ipc_jid: IPC target for outbox delivery (e.g. WhatsApp JID). Empty
+            disables outbox→IPC integration.
+        source_trace: Maps each resolved key to the source that provided it.
+    """
+
+    persona_name: str = ""
+    bridge_bind: str = "127.0.0.1:8765"
+    provider: str = "ollama"
+    model: str = ""
+    ipc_jid: str = ""
+    source_trace: dict[str, str] = field(default_factory=dict)
+
+
+def _load_env_file(path: Path) -> dict[str, str]:
+    """Parse a simple KEY=VALUE .env file.
+
+    Supports: comment lines starting with `#`, blank lines, surrounding
+    single/double quotes, inline comments after the value (`KEY=val # note`).
+    Does not support: shell expansion, `export` prefix, multi-line values.
+    Always read as UTF-8 regardless of platform default encoding.
+    """
+    result: dict[str, str] = {}
+    if not path.exists():
+        return result
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        value = value.strip()
+        # Strip inline comment (anything after a ` #` segment). The leading
+        # space is required so `#` inside a quoted URL or token survives.
+        if " #" in value:
+            value = value[: value.index(" #")].rstrip()
+        result[key.strip()] = value.strip('"').strip("'")
+    return result
+
+
+def _load_persona_toml(persona_dir: Path) -> dict[str, str]:
+    """Flatten persona.toml into the framework's config key namespace."""
+    toml_path = persona_dir / "persona.toml"
+    if not toml_path.exists():
+        return {}
+    with toml_path.open("rb") as fh:
+        data = tomllib.load(fh)
+
+    flat: dict[str, str] = {}
+    bridge = data.get("bridge", {})
+    if "bind" in bridge:
+        flat["BRIDGE_BIND"] = str(bridge["bind"])
+    model = data.get("model", {})
+    if "provider" in model:
+        flat["PROVIDER"] = str(model["provider"])
+    if "tag" in model:
+        flat["MODEL"] = str(model["tag"])
+    return flat
+
+
+def _read_env_vars() -> dict[str, str]:
+    """Pull supported keys from os.environ."""
+    return {k: v for k, v in os.environ.items() if k in _SUPPORTED_KEYS}
+
+
+def load_config(persona_dir: Path, env_file: Path | None = None) -> Config:
+    """Load and merge config from persona.toml + .env + env vars.
+
+    Args:
+        persona_dir: Directory containing persona.toml and persona data.
+        env_file: Optional path to a .env file to load.
+
+    Returns:
+        Resolved Config with source_trace recording where each value came from.
+    """
+    sources: list[tuple[str, dict[str, str]]] = [
+        ("default", dict(_DEFAULTS)),
+        ("persona.toml", _load_persona_toml(persona_dir)),
+    ]
+    if env_file is not None:
+        sources.append((".env", _load_env_file(env_file)))
+    sources.append(("env", _read_env_vars()))
+
+    trace: dict[str, str] = {}
+    merged: dict[str, str] = {}
+    for source_name, source_values in sources:
+        for key, value in source_values.items():
+            merged[key] = value
+            trace[key] = source_name
+
+    return Config(
+        persona_name=persona_dir.name,
+        bridge_bind=merged["BRIDGE_BIND"],
+        provider=merged["PROVIDER"],
+        model=merged["MODEL"],
+        ipc_jid=merged["NELL_IPC_JID"],
+        source_trace=trace,
+    )

brain/paths.py

@@ -0,0 +1,53 @@
+"""Platform-aware path resolution for companion-emergence.
+
+All user-facing paths route through this module so we never hard-code
+OS-specific locations. Uses platformdirs for the OS-appropriate default
+with NELLBRAIN_HOME env var for full override.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from platformdirs import PlatformDirs
+
+_APP_NAME = "companion-emergence"
+_APP_AUTHOR = "hanamorix"
+
+# PlatformDirs properties are evaluated lazily (env vars read at
+# property-access time, not at construction), so module-level
+# instantiation is safe under monkeypatching in tests.
+_dirs = PlatformDirs(appname=_APP_NAME, appauthor=_APP_AUTHOR)
+
+
+def get_home() -> Path:
+    """Root directory for all companion-emergence state.
+
+    Resolution order:
+    1. NELLBRAIN_HOME env var if set (supports ~ expansion)
+    2. platformdirs user_data_path for the current OS
+
+    Both branches return a fully resolved canonical path so symlinks
+    collapse consistently (matters on Linux CI runners with symlinked
+    home dirs).
+    """
+    override = os.environ.get("NELLBRAIN_HOME")
+    if override:
+        return Path(override).expanduser().resolve()
+    return _dirs.user_data_path.resolve()
+
+
+def get_persona_dir(name: str) -> Path:
+    """Return the directory for a specific persona's private data."""
+    return get_home() / "personas" / name
+
+
+def get_cache_dir() -> Path:
+    """Return the cache directory (embeddings, computed matrices, etc)."""
+    return _dirs.user_cache_path.resolve()
+
+
+def get_log_dir() -> Path:
+    """Return the log file directory."""
+    return _dirs.user_log_path.resolve()