Deploy Pulse Familiar Space

README.md

@@ -1,13 +1,115 @@
 ---
 title: Pulse Familiar
-emoji: 🏆
-colorFrom: indigo
-colorTo: blue
+emoji: 🌿
+colorFrom: green
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.12'
+sdk_version: 5.49.1
 app_file: app.py
+python_version: "3.10.13"
 pinned: false
+license: other
+short_description: A local body-diff familiar alive on a real heartbeat
+startup_duration_timeout: 1h
+models:
+  - nvidia/Nemotron-Mini-4B-Instruct
+  - build-small-hackathon/pulse-familiar-fenn-lora
+tags:
+  - track:thousand-token-wood
+  - sponsor:nvidia
+  - achievement:offgrid
+  - achievement:well-tuned
+  - achievement:offbrand
+  - achievement:tiny-titan
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🌿 Pulse Familiar
+
+> A small woodland familiar named **Fenn** that is *alive because of a real human
+> heartbeat*. It turns derived ring signals into a daily body-diff brief, replayable
+> biometric memories, and a tiny CRT creature voiced by **≤4B NVIDIA Nemotron**.
+
+Built for the **Hugging Face × Gradio Build Small Hackathon** — 🍄 *Thousand Token
+Wood* track.
+
+## What it is
+
+There is no chatbot here. Every line Fenn speaks is generated **from a heartbeat**:
+
+```
+ HR / HRV ──▶ state.py ──▶ a mood ──▶ creature.py ──▶ Fenn's ASCII face
+              (pure math,    (sleepy …    + the mood-only cue ──▶ brain.py ──▶ one-line voice
+               vs the         alarmed)                            (≤4B Nemotron)
+               wearer's
+               baseline)
+```
+
+- **The mood** is deterministic math against the wearer's *own* baseline
+  (`familiar/state.py`) — faster-than-usual heart pushes arousal up; high HRV pulls
+  it back toward calm. Seven moods: `sleepy · serene · content · restless · anxious
+  · alarmed · excited`.
+- **The voice** is a small model told only *how the heartbeat feels* — never the
+  numbers — so it speaks like a creature, not a doctor (`familiar/brain.py`).
+
+## Four ways to use it
+
+1. **🌙 Memories** — replay an anonymized **real** episode recorded from the maker's
+   Ultrahuman smart-ring (a calm night, a hard workout, a stressed afternoon) and
+   watch Fenn live through it.
+2. **🌤 Daily Pulse Brief** — read a derived daily feature vector
+   (`data/daily_features.jsonl` when present locally), separate physical load from
+   sedentary strain, and get one recovery/output constraint for the day.
+3. **🫁 Breathe with me** — a tiny **RL policy** (`familiar/rl.py`, REINFORCE,
+   trains in ~2s on CPU) that *learned which calming action settles a racing heart*
+   in a body-simulator built from the real ring stats. Start stressed; Fenn coaches
+   you down with paced breathing while the simulated heart settles live.
+4. **🧪 Simulated pulse changes** — hidden dev/demo controls for mocked BPM transitions.
+
+## Voice fine-tune (optional, drop-in)
+
+`tools/generate_dataset.py` builds a 1,944-example chat-format SFT set from a
+multi-teacher panel; `tools/modal_finetune.py` LoRA-tunes Nemotron-Mini-4B on it.
+The public Space uses `build-small-hackathon/pulse-familiar-fenn-lora`. Set
+`FAMILIAR_ADAPTER=<repo-or-path>` to swap adapters locally. Any future Modal run
+requires W&B tracking via a Modal `wandb` secret.
+
+## The model
+
+- **`nvidia/Nemotron-Mini-4B-Instruct`** — a plain ≤4B transformer.
+- Runs **in-process on ZeroGPU** (`familiar/hf_model.py`, `@spaces.GPU`) in the
+  public Space. The local demo can also use llama.cpp on linuxbox. The app makes
+  **zero external model API calls**.
+- Degrades gracefully: if the model can't load, Fenn falls back to canned
+  in-character lines so the demo never hard-fails.
+
+Backends are swappable via `FAMILIAR_PROVIDER` (`transformers` ships; `local`
+llama.cpp and `openrouter` are for development).
+
+## Run locally
+
+```bash
+uv venv
+uv pip install -r requirements.txt
+. .venv/bin/activate
+python app.py            # FAMILIAR_PROVIDER defaults to transformers/ZeroGPU-style
+```
+
+## Where the heartbeat comes from
+
+`data/sessions.json` holds a few short, **anonymized** real episodes (relative time
++ HR/HRV only, no dates) carved from the maker's ring history with
+`tools/extract_sessions.py`. `familiar/features.py` can derive local day-level
+features for the Daily Pulse Brief, but `data/daily_features.jsonl` is gitignored.
+The full raw export stays private and out of the repo.
+
+## Submission
+
+- 🤗 **Space:** https://huggingface.co/spaces/build-small-hackathon/pulse-familiar
+- 🧬 **LoRA:** https://huggingface.co/build-small-hackathon/pulse-familiar-fenn-lora
+- 🎥 **Demo video:** _link added at submission_
+- 📣 **Social post:** _link added at submission_
+
+## Credits
+
+Heartbeat data: the maker's own Ultrahuman ring. Voice: NVIDIA Nemotron-Mini-4B
+(`license: other` — see the model card). Built with Gradio on Hugging Face Spaces.

app.py

@@ -0,0 +1,662 @@
+"""
+Pulse Familiar — a tiny ASCII creature that is alive because of a real heartbeat.
+
+Fenn is a small woodland familiar. Its mood, its face, and its voice are driven
+by heart-rate and heart-rate-variability — either yours, live, via the sliders
+("Live touch"), or a *real* episode replayed from the maker's own smart-ring
+history ("Memories"). The Daily Pulse Brief turns local derived ring features into
+a body-diff and one action. The voice is a ≤4B NVIDIA Nemotron model running
+locally via llama.cpp in dev or in-process on the Space. Built for the Hugging Face × Gradio
+Build Small Hackathon — Thousand Token Wood track.
+
+    HR / HRV  ->  state.py (mood)  ->  creature.py (body)  +  brain.py (voice)
+
+The creature lives inside a CRT terminal screen (gr.HTML) with a live ECG that
+beats at the real BPM — driven by one render_screen() helper shared across modes.
+"""
+from __future__ import annotations
+
+import html
+import json
+import os
+import time
+from pathlib import Path
+
+import gradio as gr
+
+from familiar import classify, speak
+from familiar.brain import MODEL, _PROVIDER
+from familiar.creature import MOOD_COLOR, render as render_fenn
+from familiar.state import DEFAULT_HR_BASELINE, DEFAULT_HRV_BASELINE
+from familiar import trace, memories, coach, hf_model
+
+_DAILY_FEATURES = Path(__file__).resolve().parent / "data" / "daily_features.jsonl"
+_ADAPTER = os.environ.get(
+    "FAMILIAR_ADAPTER", "build-small-hackathon/pulse-familiar-fenn-lora"
+).strip()
+
+
+# --------------------------------------------------------------------------- #
+# the CRT screen — one renderer, shared by all three tabs
+# --------------------------------------------------------------------------- #
+def _ascii_fenn(mood: str, color: str) -> str:
+    return html.escape(render_fenn(mood))
+
+
+def _badge_for(source: str, color: str) -> str:
+    model_label = "Nemotron · LoRA · live" if _ADAPTER else "Nemotron · live"
+    labels = {
+        "model": f"<span class='live-dot' style='color:{color}'>● {model_label}</span>",
+        "fallback": "<span class='fb-dot'>● fallback voice</span>",
+        "coach": "<span class='sim-dot'>● learned body-sim coach</span>",
+        "brief": "<span class='brief-dot'>● local daily pulse brief</span>",
+        "sample": "<span class='brief-dot'>● sample brief</span>",
+        "idle": "<span class='brief-dot'>● waiting for touch</span>",
+        "rule": "<span class='brief-dot'>● rule voice / no LLM</span>",
+    }
+    return labels.get(source, f"<span class='fb-dot'>● {html.escape(source)}</span>")
+
+
+def render_screen(
+    mood: str,
+    line: str,
+    source: str,
+    hr: float,
+    hrv: float,
+    *,
+    title: str | None = None,
+    lens: str | None = None,
+    action: str | None = None,
+    stats: list[tuple[str, str]] | None = None,
+    progress: str = "",
+) -> str:
+    """Return the living-terminal HTML for one moment. data-bpm/data-color drive
+    the client-side ECG animation defined in the page <head>."""
+    color = MOOD_COLOR.get(mood, ("#7dffb0", 71))[0]
+    badge = _badge_for(source, color)
+    face = _ascii_fenn(mood, color)
+    beat = max(0.3, min(2.0, 60.0 / max(30.0, min(200.0, hr))))
+    title = title or mood.replace("_", " ").upper()
+    lens = lens or "Fenn is reading the pulse shape, not diagnosing it."
+    action = action or "watch the pulse, then choose one small next move."
+    stats = stats or [
+        ("heart", f"{hr:.0f} bpm"),
+        ("hrv", f"{hrv:.0f} ms"),
+        ("mood", mood),
+    ]
+    chips = "\n".join(
+        f"<div class='stat-chip'><span>{html.escape(k)}</span><b>{html.escape(str(v))}</b></div>"
+        for k, v in stats
+    )
+    return f"""
+<div class="fenn-screen" data-bpm="{hr:.0f}" data-color="{color}"
+     style="--mood:{color};--beat:{beat:.2f}s">
+  <div class="fenn-left">
+    <div class="source-line">{badge}</div>
+    <pre class="fenn-face">{face}</pre>
+    <canvas class="ecg" width="720" height="96"></canvas>
+  </div>
+  <div class="fenn-right">
+    <div class="stage-title">{html.escape(title)}</div>
+    <div class="fenn-voice">“{html.escape(line)}”</div>
+    <div class="stat-grid">{chips}</div>
+    <div class="brief-card"><span>WHY</span>{html.escape(lens)}</div>
+    <div class="brief-card"><span>NEXT</span>{html.escape(action)}</div>
+    <div class="fenn-row">
+      <span>MOOD: {mood.upper()}</span>
+      <span>♥ {hr:.0f} BPM &nbsp; ~ {hrv:.0f} MS</span>
+      <span>{html.escape(progress)}</span>
+    </div>
+  </div>
+</div>"""
+
+
+# --------------------------------------------------------------------------- #
+# core reaction (shared by all modes)
+# --------------------------------------------------------------------------- #
+def react(hr: float, hrv: float, prev_hr: float | None):
+    state = classify(hr, hrv, prev_hr=prev_hr)
+    line, source = speak(state)
+    trace.log(state, line, source)
+    return render_screen(state.mood, line, source, hr, hrv), state.as_dict(), hr
+
+
+def boot_live(hr: float, hrv: float, prev_hr: float | None):
+    state = classify(hr, hrv, prev_hr=prev_hr)
+    line = "touch the pulse; i'll listen."
+    return render_screen(state.mood, line, "idle", hr, hrv), state.as_dict(), hr
+
+
+def replay(ep_id: str):
+    ep = memories.get_episode(ep_id)
+    if not ep:
+        yield render_screen("content", "no memory loaded", "fallback", 62, 140), {}, ""
+        return
+    samples = ep["samples"]
+    prev_hr = last_mood = None
+    last_line, last_source = "", "model"
+    n = len(samples)
+    for i, s in enumerate(samples):
+        hr, hrv = s["hr"], s["hrv"]
+        state = classify(hr, hrv, prev_hr=prev_hr)
+        if state.mood != last_mood:
+            last_line, last_source = speak(state)
+            trace.log(state, last_line, last_source)
+            last_mood = state.mood
+        prev_hr = hr
+        prog = (f"**{ep['title']}** — *{ep['blurb']}*  \n"
+                f"reliving moment {i + 1}/{n}  ·  ♥ {hr:.0f} bpm  ~ {hrv:.0f} ms")
+        yield render_screen(state.mood, last_line, last_source, hr, hrv), state.as_dict(), prog
+        time.sleep(0.5)
+
+
+def breathe(start: str):
+    for body_html, _v, breath, st, prog in coach.breathe_session(start):
+        # coach yields its own pieces; re-render through the screen for consistency
+        yield (render_screen(st["mood"], _coach_line(_v), "coach", st["hr"], st["hrv"]),
+               breath, st, prog)
+
+
+def _coach_line(voice_md: str) -> str:
+    # coach.breathe_session yields a styled <div>…</div>; pull the quoted line out
+    import re
+    m = re.search(r"“(.+?)”", voice_md)
+    return m.group(1) if m else voice_md
+
+
+# --------------------------------------------------------------------------- #
+# daily pulse brief — the useful daily layer over the Fenn toy
+# --------------------------------------------------------------------------- #
+_SAMPLE_DAY = {
+    "date": "sample",
+    "n_hr": 144,
+    "hr_median": 78,
+    "hr_rhr": 58,
+    "hr_max": 118,
+    "hrv_mean": 122,
+    "hrv_night": 118,
+    "steps_total": 2100,
+    "motion_mean": 42,
+    "exertion_frac": 0.0,
+    "hrv_z": -0.7,
+    "rhr_z": 0.9,
+    "hrv_trend3": "falling",
+    "hrv_cue": "lower",
+    "strain_cue": "strained",
+}
+
+
+def _load_daily_features() -> list[dict]:
+    if not _DAILY_FEATURES.exists():
+        return []
+    rows = []
+    for line in _DAILY_FEATURES.read_text().splitlines():
+        try:
+            rows.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return rows
+
+
+def _daily_choices() -> list[tuple[str, str]]:
+    rows = _load_daily_features()
+    if not rows:
+        return [("sample day · no private feature file on this Space", "sample")]
+    choices = []
+    for row in rows[-21:]:
+        label = (
+            f"{row['date']} · {row.get('hrv_cue', 'usual')} HRV · "
+            f"{row.get('strain_cue', 'restful')}"
+        )
+        choices.append((label, row["date"]))
+    return choices
+
+
+def _daily_row(date: str) -> tuple[dict, str]:
+    rows = _load_daily_features()
+    for row in rows:
+        if row.get("date") == date:
+            return row, "brief"
+    if rows:
+        return rows[-1], "brief"
+    return _SAMPLE_DAY, "sample"
+
+
+def _day_mood(row: dict) -> str:
+    hrv_cue = row.get("hrv_cue", "usual")
+    strain = row.get("strain_cue", "restful")
+    if strain == "strained":
+        return "anxious" if hrv_cue in {"lower", "much_lower"} else "restless"
+    if strain == "active":
+        return "excited" if hrv_cue != "much_lower" else "restless"
+    if hrv_cue == "higher":
+        return "serene"
+    if hrv_cue in {"lower", "much_lower"}:
+        return "restless"
+    return "content"
+
+
+def _workload_lens(row: dict) -> str:
+    steps = float(row.get("steps_total") or 0)
+    motion = float(row.get("motion_mean") or 0)
+    rhr_z = row.get("rhr_z")
+    hrv_cue = row.get("hrv_cue", "usual")
+    strain = row.get("strain_cue", "restful")
+    if strain == "active" and (steps >= 3000 or motion >= 70):
+        return "physical load dominated; do not misread this as pure anxiety."
+    if rhr_z is not None and rhr_z >= 0.8 and steps < 2500 and motion < 70:
+        return "likely sedentary stress / deep-work load: high resting cost without much movement."
+    if hrv_cue in {"lower", "much_lower"}:
+        return "recovery debt: keep output smaller until the night signal rebounds."
+    if hrv_cue == "higher":
+        return "green-ish day: use the window, but do not spend it twice."
+    return "ordinary baseline day: keep the plan boring and clean."
+
+
+def _one_action(row: dict) -> str:
+    hrv_cue = row.get("hrv_cue", "usual")
+    strain = row.get("strain_cue", "restful")
+    if strain == "active":
+        return "walk easy, hydrate, and keep the next hard push short."
+    if hrv_cue == "much_lower":
+        return "cut one ambitious task; add a 20-minute no-screen reset."
+    if hrv_cue == "lower":
+        return "ship one thing, then stop before the second spiral starts."
+    if hrv_cue == "higher":
+        return "use the clean window for one hard block, not scattered errands."
+    return "keep the day steady: one main block, one recovery block."
+
+
+def _daily_line(row: dict) -> str:
+    hrv_cue = row.get("hrv_cue", "usual")
+    strain = row.get("strain_cue", "restful")
+    if strain == "active":
+        return "you spent sparks. let the little fire bank low."
+    if hrv_cue == "much_lower":
+        return "the drum sounds thin today. i make the nest smaller."
+    if hrv_cue == "lower":
+        return "less chase, more moss. i guard one clean task."
+    if hrv_cue == "higher":
+        return "green light in the ribs. step gently into it."
+    return "steady weather. i hum beside the plan."
+
+
+def daily_pulse(date: str):
+    row, source = _daily_row(date)
+    hr = float(row.get("hr_rhr") or row.get("hr_median") or DEFAULT_HR_BASELINE)
+    hrv = float(row.get("hrv_night") or row.get("hrv_mean") or DEFAULT_HRV_BASELINE)
+    mood = _day_mood(row)
+    line = _daily_line(row)
+    lens = _workload_lens(row)
+    action = _one_action(row)
+    brief = f"""
+### Daily Pulse Brief — {row.get('date', 'sample')}
+
+**Body diff**
+- HRV cue: `{row.get('hrv_cue', 'usual')}` · trend: `{row.get('hrv_trend3', 'steady')}`
+- Strain cue: `{row.get('strain_cue', 'restful')}` · workload lens: **{lens}**
+- Resting proxy: `{row.get('hr_rhr')}` bpm · night HRV: `{row.get('hrv_night')}` · steps: `{row.get('steps_total')}`
+
+**One move**
+{action}
+
+**Why this is useful**
+This turns Fenn from “cute heartbeat toy” into a local body debugger: a daily
+body diff, one constraint for the day, and no raw health export leaving disk.
+"""
+    details = {
+        k: row.get(k)
+        for k in (
+            "date", "n_hr", "hr_median", "hr_rhr", "hr_max", "hrv_mean",
+            "hrv_night", "steps_total", "motion_mean", "exertion_frac",
+            "hrv_z", "rhr_z", "hrv_trend3", "hrv_cue", "strain_cue",
+        )
+    }
+    return render_screen(mood, line, source, hr, hrv), brief, details
+
+
+def _day_title(row: dict) -> str:
+    strain = row.get("strain_cue", "restful")
+    hrv_cue = row.get("hrv_cue", "usual")
+    if strain == "active":
+        return "ACTIVE LOAD DAY"
+    if strain == "strained":
+        return "SEDENTARY STRAIN"
+    if hrv_cue in {"lower", "much_lower"}:
+        return "RECOVERY DEBT"
+    if hrv_cue == "higher":
+        return "GREEN WINDOW"
+    return "STEADY BASELINE"
+
+
+def _stage_stats(row: dict, hr: float, hrv: float) -> list[tuple[str, str]]:
+    return [
+        ("heart", f"{hr:.0f} bpm"),
+        ("hrv", f"{hrv:.0f} ms"),
+        ("steps", f"{float(row.get('steps_total') or 0):,.0f}"),
+    ]
+
+
+def today_stage(date: str):
+    row, source = _daily_row(date)
+    hr = float(row.get("hr_rhr") or row.get("hr_median") or DEFAULT_HR_BASELINE)
+    hrv = float(row.get("hrv_night") or row.get("hrv_mean") or DEFAULT_HRV_BASELINE)
+    mood = _day_mood(row)
+    details = {
+        "mode": "daily derived",
+        "date": row.get("date"),
+        "hrv_cue": row.get("hrv_cue"),
+        "strain_cue": row.get("strain_cue"),
+        "hrv_z": row.get("hrv_z"),
+        "rhr_z": row.get("rhr_z"),
+        "steps_total": row.get("steps_total"),
+    }
+    html_stage = render_screen(
+        mood, _daily_line(row), "rule", hr, hrv,
+        title=_day_title(row),
+        lens=_workload_lens(row),
+        action=_one_action(row),
+        stats=_stage_stats(row, hr, hrv),
+        progress=f"daily derived / {source}",
+    )
+    return html_stage, details
+
+
+_SCENARIOS = {
+    "rest": {
+        "target": (62, 145),
+        "title": "SIMULATED REST",
+        "line": "steady weather. i hum beside the plan.",
+        "lens": "mocked calm baseline: the character should stay small and steady.",
+        "action": "hold the line; no intervention needed.",
+    },
+    "deep work": {
+        "target": (92, 70),
+        "title": "SIMULATED DEEP WORK",
+        "line": "the drum leans forward. i keep the room small.",
+        "lens": "mocked focus load: higher heart, lower HRV, little movement.",
+        "action": "finish one block, then deliberately downshift.",
+    },
+    "panic": {
+        "target": (122, 28),
+        "title": "SIMULATED PANIC",
+        "line": "loud, loud. i stay close until it softens.",
+        "lens": "mocked stress spike: fast heart plus very low HRV.",
+        "action": "breathe down; do not make decisions at the peak.",
+    },
+    "workout": {
+        "target": (150, 120),
+        "title": "SIMULATED WORKOUT",
+        "line": "you blaze. i count sparks, not danger.",
+        "lens": "mocked physical exertion: high heart with enough HRV/movement context.",
+        "action": "cool down; do not mistake useful exertion for anxiety.",
+    },
+    "recovery": {
+        "target": (54, 185),
+        "title": "SIMULATED RECOVERY",
+        "line": "green hush in the ribs. i curl beside it.",
+        "lens": "mocked recovery: low heart and high HRV.",
+        "action": "use one clean block, then preserve the surplus.",
+    },
+}
+
+
+def simulate_stage(name: str):
+    cfg = _SCENARIOS.get(name, _SCENARIOS["panic"])
+    start_hr, start_hrv = DEFAULT_HR_BASELINE, DEFAULT_HRV_BASELINE
+    target_hr, target_hrv = cfg["target"]
+    prev_hr = None
+    steps = 18
+    for i in range(steps + 1):
+        t = i / steps
+        # ease-in-out, so the mocked BPM change feels like physiology, not a jump cut
+        ease = t * t * (3 - 2 * t)
+        hr = start_hr + (target_hr - start_hr) * ease
+        hrv = start_hrv + (target_hrv - start_hrv) * ease
+        st = classify(hr, hrv, prev_hr=prev_hr)
+        prev_hr = hr
+        yield render_screen(
+            st.mood, cfg["line"], "rule", hr, hrv,
+            title=cfg["title"],
+            lens=cfg["lens"],
+            action=cfg["action"],
+            stats=[("heart", f"{hr:.0f} bpm"), ("hrv", f"{hrv:.0f} ms"), ("source", "mock")],
+            progress=f"simulated {i}/{steps}",
+        ), st.as_dict()
+        time.sleep(0.07)
+
+
+def replay_stage(ep_id: str):
+    ep = memories.get_episode(ep_id)
+    if not ep:
+        yield render_screen(
+            "content", "no memory loaded", "fallback", 62, 140,
+            title="NO MEMORY",
+            lens="No anonymized ring replay was found.",
+            action="Choose a memory after data is loaded.",
+            progress="real replay",
+        ), {}
+        return
+    prev_hr = last_mood = None
+    last_line, last_source = "", "fallback"
+    samples = ep["samples"]
+    for i, s in enumerate(samples):
+        hr, hrv = s["hr"], s["hrv"]
+        st = classify(hr, hrv, prev_hr=prev_hr)
+        if st.mood != last_mood:
+            last_line, last_source = speak(st)
+            last_mood = st.mood
+        prev_hr = hr
+        yield render_screen(
+            st.mood, last_line, last_source, hr, hrv,
+            title=f"REAL REPLAY — {ep['title']}",
+            lens=ep["blurb"],
+            action="Watch Fenn change only when the body state changes.",
+            stats=[("heart", f"{hr:.0f} bpm"), ("hrv", f"{hrv:.0f} ms"), ("sample", f"{i + 1}/{len(samples)}")],
+            progress="real replay",
+        ), st.as_dict()
+        time.sleep(0.35)
+
+
+def replay_sleep():
+    yield from replay_stage("calm_night")
+
+
+def replay_workout():
+    yield from replay_stage("workout")
+
+
+def replay_stress():
+    yield from replay_stage("stress")
+
+
+def breathe_stage():
+    for _body_html, voice, breath, st, prog in coach.breathe_session("panic", max_steps=18):
+        line = _coach_line(voice)
+        yield render_screen(
+            st["mood"], line, "coach", st["hr"], st["hrv"],
+            title="BREATHE IT DOWN",
+            lens="body-sim: Fenn chooses a calming action and the mocked body responds.",
+            action=_coach_line(breath) if "“" in breath else "follow the paced breath until the pulse settles.",
+            stats=[("heart", f"{st['hr']:.0f} bpm"), ("hrv", f"{st['hrv']:.0f} ms"), ("source", "body-sim")],
+            progress=prog.replace("·", "/"),
+        ), st
+
+
+# --------------------------------------------------------------------------- #
+# page chrome
+# --------------------------------------------------------------------------- #
+_HEAD = """
+<script>
+(function(){
+  function pqrst(p){
+    if(p<0.12) return Math.sin(p/0.12*Math.PI)*0.12;
+    if(p<0.20) return 0;
+    if(p<0.24) return -0.25;
+    if(p<0.28) return 1.0;
+    if(p<0.33) return -0.45;
+    if(p<0.55) return 0;
+    if(p<0.75) return Math.sin((p-0.55)/0.20*Math.PI)*0.30;
+    return 0;
+  }
+  let last=0,t=0;
+  function loop(ts){
+    const dt=(ts-last)/1000||0; last=ts;
+    document.querySelectorAll('.fenn-screen').forEach(function(scr){
+      const cv=scr.querySelector('canvas.ecg'); if(!cv) return;
+      const ctx=cv.getContext('2d');
+      const bpm=Math.max(30,Math.min(200,parseFloat(scr.dataset.bpm||'62')));
+      const color=scr.dataset.color||'#7dffb0';
+      const beat=60/bpm; t=(t+dt)%beat;
+      if(cv._x===undefined) cv._x=0;
+      ctx.fillStyle='rgba(4,20,12,0.16)'; ctx.fillRect(0,0,cv.width,cv.height);
+      const y=cv.height/2 - pqrst(t/beat)*(cv.height*0.40);
+      ctx.fillStyle=color; ctx.shadowColor=color; ctx.shadowBlur=10;
+      ctx.fillRect(cv._x,y,2.6,2.6);
+      cv._x+=3; if(cv._x>cv.width){cv._x=0; ctx.clearRect(0,0,cv.width,cv.height);}
+    });
+    requestAnimationFrame(loop);
+  }
+  requestAnimationFrame(loop);
+})();
+</script>
+"""
+
+_CSS = """
+.gradio-container{background:#090b09!important;color:#ece8dc!important;}
+.gradio-container,.gradio-container *{font-family:"JetBrains Mono","SF Mono",
+  ui-monospace,Menlo,monospace!important;}
+.app-wrap{max-width:1040px;margin:0 auto 10px;padding:8px 2px 0;}
+.app-title{font-size:34px;line-height:1.05;margin:0 0 8px;color:#f4f0df;}
+.app-sub{color:#8d9188;font-size:13px;max-width:680px;}
+.episode-label{max-width:1040px;margin:18px auto 2px;color:#d6a849;font-size:12px;
+  letter-spacing:.18em;text-transform:uppercase;}
+.episode-help{max-width:1040px;margin:0 auto;color:#74796f;font-size:12px;}
+.controls{max-width:1040px;margin:14px auto 0;}
+.episode-controls{margin-top:10px;}
+.controls .form,.controls .block{background:transparent!important;border:0!important;box-shadow:none!important;
+  padding:0!important;}
+.controls input{background:#10130f!important;color:#eee9d8!important;border:1px solid #2a2f26!important;
+  border-radius:999px!important;min-height:46px!important;text-align:center!important;}
+.controls svg{color:#8d9188!important;}
+button.primary,button.secondary{border-radius:999px!important;border:1px solid #33382f!important;
+  background:#11140f!important;color:#e9e5d7!important;box-shadow:none!important;}
+button.primary{border-color:#d6a849!important;color:#fff4cf!important;}
+.fenn-screen{max-width:1040px;margin:16px auto 4px;position:relative;display:grid;
+  grid-template-columns:minmax(260px,390px) 1fr;gap:26px;align-items:center;
+  border:1px solid #242820;border-radius:24px;padding:30px;background:
+  radial-gradient(600px 260px at 20% 20%,color-mix(in srgb,var(--mood) 12%,transparent),transparent 70%),
+  linear-gradient(180deg,#11140f,#0b0d0a);overflow:hidden;}
+.fenn-left{display:flex;flex-direction:column;align-items:center;gap:12px;}
+.source-line{align-self:flex-start;font-size:12px;letter-spacing:.06em;text-transform:uppercase;color:#878b81;}
+.fenn-face{font-size:18px;line-height:1.18;white-space:pre;text-align:center;color:#f1eddd;
+  text-shadow:0 0 18px color-mix(in srgb,var(--mood) 55%,transparent);margin:0;
+  transform-origin:50% 62%;animation:fenn-bob 4s ease-in-out infinite,
+  fenn-pulse var(--beat) ease-out infinite;}
+canvas.ecg{display:block;width:100%;height:52px;opacity:.78;
+  filter:drop-shadow(0 0 8px var(--mood));}
+.fenn-right{min-width:0;}
+.stage-title{color:var(--mood);font-size:13px;letter-spacing:.18em;font-weight:700;
+  margin-bottom:14px;text-transform:uppercase;}
+.fenn-voice{font-size:34px;line-height:1.12;color:#f4f0df;letter-spacing:-.03em;
+  max-width:620px;margin-bottom:22px;}
+.stat-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:10px;margin:10px 0 18px;}
+.stat-chip{border:1px solid #252a22;border-radius:14px;padding:12px;background:#0c0f0b;}
+.stat-chip span{display:block;color:#74796f;font-size:11px;text-transform:uppercase;letter-spacing:.1em;}
+.stat-chip b{display:block;margin-top:4px;color:#ebe7d8;font-size:16px;font-weight:600;}
+.brief-card{border-left:1px solid #30362c;padding:9px 0 9px 14px;color:#bbb8aa;font-size:14px;
+  line-height:1.45;margin-top:8px;}
+.brief-card span{display:block;color:#74796f;font-size:10px;letter-spacing:.16em;margin-bottom:3px;}
+.fenn-row{display:flex;justify-content:space-between;gap:12px;flex-wrap:wrap;color:#686d64;
+  font-size:11px;letter-spacing:.08em;margin-top:18px;text-transform:uppercase;}
+.live-dot,.fb-dot,.sim-dot,.brief-dot{color:#878b81!important;text-shadow:none!important;}
+@keyframes fenn-bob{0%,100%{translate:0 0}50%{translate:0 -4px}}
+@keyframes fenn-pulse{0%,82%,100%{scale:1}10%{scale:1.035}}
+@media(max-width:760px){.fenn-screen{grid-template-columns:1fr;padding:22px}.fenn-voice{font-size:25px}
+  .stat-chip{padding:10px}.source-line{align-self:center}}
+"""
+
+_STORY = """
+### What is this?
+**Fenn** is a tiny familiar that only feels what your heart does. There's no
+chatbot — every line is generated *from a heartbeat*:
+
+```
+HR / HRV  →  a mood (calm … alarmed)  →  Fenn's face + a one-line voice
+```
+
+The **mood** is pure math against the wearer's own baseline (`state.py`). The
+**voice** is **NVIDIA's `Nemotron-Mini-4B-Instruct`** served locally through
+llama.cpp in this demo, with the `fenn-lora` adapter loaded for the creature
+voice. No cloud API is called.
+
+**Daily Pulse Brief** is the practical layer: it reads a local, derived daily
+feature vector (not the raw ring export), separates physical exertion from
+sedentary strain, and gives one recovery/output constraint for the day.
+
+**Memories** replays anonymized real episodes from the maker's own smart-ring.
+"""
+
+
+def build() -> gr.Blocks:
+    backend = {"transformers": "in-process (ZeroGPU)", "local": "llama.cpp",
+               "openrouter": "OpenRouter (dev)"}.get(_PROVIDER, _PROVIDER)
+    st = hf_model.status() if _PROVIDER == "transformers" else {}
+    dep = " · deps ready" if st.get("deps_present") else ""
+    adapter = f" · LoRA `{_ADAPTER}`" if _ADAPTER else ""
+    status = f"voice: NVIDIA `{MODEL}` · {backend}{dep}{adapter} · no cloud calls"
+
+    with gr.Blocks(title="Pulse Familiar", theme=gr.themes.Soft(),
+                   css=_CSS, head=_HEAD) as demo:
+        gr.HTML(
+            "<div class='app-wrap'>"
+            "<div class='app-title'>Pulse Familiar</div>"
+            "<div class='app-sub'>A small ASCII familiar for a private body debugger: "
+            "daily body diff, real ring replay, and honest simulated pulse changes.</div>"
+            f"<div class='app-sub'>{html.escape(status)}</div>"
+            "</div>"
+        )
+
+        stage = gr.HTML()
+        choices = _daily_choices()
+
+        gr.HTML(
+            "<div class='episode-label'>real ring replay</div>"
+            "<div class='episode-help'>choose a 90-minute slice from the private ring history</div>"
+        )
+        with gr.Row(elem_classes=["controls", "episode-controls"]):
+            sleep_btn = gr.Button("deep sleep", variant="primary", scale=1)
+            workout_btn = gr.Button("workout", scale=1)
+            stress_btn = gr.Button("stressed afternoon", scale=1)
+            today = gr.Button("today brief", scale=1)
+
+        with gr.Accordion("simulate / breathe / dev controls", open=False):
+            with gr.Row(elem_classes=["controls"]):
+                day = gr.Dropdown(choices=choices, value=choices[-1][1],
+                                  label="day", show_label=False, scale=2)
+                scenario = gr.Dropdown(
+                    choices=list(_SCENARIOS), value="panic", label="mock transition",
+                    show_label=False, scale=2
+                )
+                sim_btn = gr.Button("simulate bpm", variant="primary", scale=1)
+                breathe_btn = gr.Button("breathe down", scale=1)
+
+        with gr.Accordion("details / story", open=False):
+            gr.Markdown(_STORY)
+            details = gr.JSON(label="state")
+
+        demo.load(replay_sleep, [], [stage, details])
+        sleep_btn.click(replay_sleep, [], [stage, details])
+        workout_btn.click(replay_workout, [], [stage, details])
+        stress_btn.click(replay_stress, [], [stage, details])
+        today.click(today_stage, [day], [stage, details])
+        sim_btn.click(simulate_stage, [scenario], [stage, details])
+        breathe_btn.click(breathe_stage, [], [stage, details])
+
+    return demo
+
+
+demo = build()
+
+if __name__ == "__main__":
+    demo.launch()

data/sessions.json

@@ -0,0 +1,372 @@
+{
+  "episodes": [
+    {
+      "id": "calm_night",
+      "title": "A calm night",
+      "blurb": "deep sleep \u2014 the slowest, kindest the drum gets",
+      "samples": [
+        {
+          "dt": 0,
+          "hr": 76,
+          "hrv": 34
+        },
+        {
+          "dt": 304,
+          "hr": 60,
+          "hrv": 150
+        },
+        {
+          "dt": 600,
+          "hr": 59,
+          "hrv": 194
+        },
+        {
+          "dt": 1200,
+          "hr": 53,
+          "hrv": 217
+        },
+        {
+          "dt": 1505,
+          "hr": 53,
+          "hrv": 188
+        },
+        {
+          "dt": 1800,
+          "hr": 59,
+          "hrv": 149
+        },
+        {
+          "dt": 2105,
+          "hr": 52,
+          "hrv": 230
+        },
+        {
+          "dt": 2409,
+          "hr": 52,
+          "hrv": 230
+        },
+        {
+          "dt": 2705,
+          "hr": 57,
+          "hrv": 221
+        },
+        {
+          "dt": 3000,
+          "hr": 55,
+          "hrv": 208
+        },
+        {
+          "dt": 3600,
+          "hr": 50,
+          "hrv": 230
+        },
+        {
+          "dt": 3904,
+          "hr": 53,
+          "hrv": 46
+        },
+        {
+          "dt": 4200,
+          "hr": 52,
+          "hrv": 189
+        },
+        {
+          "dt": 4504,
+          "hr": 54,
+          "hrv": 58
+        },
+        {
+          "dt": 4805,
+          "hr": 55,
+          "hrv": 132
+        },
+        {
+          "dt": 5100,
+          "hr": 52,
+          "hrv": 161
+        },
+        {
+          "dt": 5405,
+          "hr": 51,
+          "hrv": 132
+        },
+        {
+          "dt": 5700,
+          "hr": 59,
+          "hrv": 187
+        }
+      ]
+    },
+    {
+      "id": "workout",
+      "title": "A hard workout",
+      "blurb": "heart racing, but the body is moving \u2014 good fire",
+      "samples": [
+        {
+          "dt": 0,
+          "hr": 127,
+          "hrv": 106
+        },
+        {
+          "dt": 305,
+          "hr": 125,
+          "hrv": 142
+        },
+        {
+          "dt": 605,
+          "hr": 136,
+          "hrv": 119
+        },
+        {
+          "dt": 905,
+          "hr": 141,
+          "hrv": 129
+        },
+        {
+          "dt": 1205,
+          "hr": 134,
+          "hrv": 119
+        },
+        {
+          "dt": 1505,
+          "hr": 121,
+          "hrv": 92
+        },
+        {
+          "dt": 1805,
+          "hr": 121,
+          "hrv": 35
+        },
+        {
+          "dt": 2100,
+          "hr": 143,
+          "hrv": 59
+        },
+        {
+          "dt": 2405,
+          "hr": 133,
+          "hrv": 194
+        },
+        {
+          "dt": 2705,
+          "hr": 137,
+          "hrv": 123
+        },
+        {
+          "dt": 3000,
+          "hr": 124,
+          "hrv": 162
+        },
+        {
+          "dt": 3305,
+          "hr": 123,
+          "hrv": 192
+        },
+        {
+          "dt": 3600,
+          "hr": 125,
+          "hrv": 114
+        },
+        {
+          "dt": 5704,
+          "hr": 104,
+          "hrv": 191
+        },
+        {
+          "dt": 6000,
+          "hr": 102,
+          "hrv": 233
+        },
+        {
+          "dt": 6305,
+          "hr": 102,
+          "hrv": 150
+        },
+        {
+          "dt": 6905,
+          "hr": 100,
+          "hrv": 115
+        },
+        {
+          "dt": 7200,
+          "hr": 116,
+          "hrv": 224
+        }
+      ]
+    },
+    {
+      "id": "stress",
+      "title": "A stressed afternoon",
+      "blurb": "fast and tight, HRV crushed, sitting still",
+      "samples": [
+        {
+          "dt": 0,
+          "hr": 92,
+          "hrv": 57
+        },
+        {
+          "dt": 301,
+          "hr": 88,
+          "hrv": 10
+        },
+        {
+          "dt": 902,
+          "hr": 103,
+          "hrv": 68
+        },
+        {
+          "dt": 1502,
+          "hr": 118,
+          "hrv": 113
+        },
+        {
+          "dt": 2402,
+          "hr": 120,
+          "hrv": 35
+        },
+        {
+          "dt": 2702,
+          "hr": 125,
+          "hrv": 62
+        },
+        {
+          "dt": 3302,
+          "hr": 118,
+          "hrv": 99
+        },
+        {
+          "dt": 3602,
+          "hr": 112,
+          "hrv": 135
+        },
+        {
+          "dt": 3902,
+          "hr": 110,
+          "hrv": 136
+        },
+        {
+          "dt": 4502,
+          "hr": 114,
+          "hrv": 89
+        },
+        {
+          "dt": 6002,
+          "hr": 98,
+          "hrv": 20
+        },
+        {
+          "dt": 6602,
+          "hr": 98,
+          "hrv": 38
+        },
+        {
+          "dt": 6902,
+          "hr": 104,
+          "hrv": 91
+        },
+        {
+          "dt": 8401,
+          "hr": 121,
+          "hrv": 103
+        }
+      ]
+    },
+    {
+      "id": "morning",
+      "title": "An ordinary morning",
+      "blurb": "just a normal day, near the usual rhythm",
+      "samples": [
+        {
+          "dt": 0,
+          "hr": 82,
+          "hrv": 174
+        },
+        {
+          "dt": 302,
+          "hr": 84,
+          "hrv": 123
+        },
+        {
+          "dt": 903,
+          "hr": 71,
+          "hrv": 107
+        },
+        {
+          "dt": 1203,
+          "hr": 71,
+          "hrv": 107
+        },
+        {
+          "dt": 1500,
+          "hr": 77,
+          "hrv": 152
+        },
+        {
+          "dt": 1803,
+          "hr": 70,
+          "hrv": 95
+        },
+        {
+          "dt": 2100,
+          "hr": 71,
+          "hrv": 142
+        },
+        {
+          "dt": 2403,
+          "hr": 72,
+          "hrv": 94
+        },
+        {
+          "dt": 2700,
+          "hr": 79,
+          "hrv": 84
+        },
+        {
+          "dt": 3002,
+          "hr": 70,
+          "hrv": 77
+        },
+        {
+          "dt": 3300,
+          "hr": 70,
+          "hrv": 207
+        },
+        {
+          "dt": 3603,
+          "hr": 64,
+          "hrv": 175
+        },
+        {
+          "dt": 3900,
+          "hr": 64,
+          "hrv": 143
+        },
+        {
+          "dt": 4203,
+          "hr": 65,
+          "hrv": 69
+        },
+        {
+          "dt": 4500,
+          "hr": 62,
+          "hrv": 128
+        },
+        {
+          "dt": 4803,
+          "hr": 69,
+          "hrv": 138
+        },
+        {
+          "dt": 5100,
+          "hr": 70,
+          "hrv": 148
+        },
+        {
+          "dt": 5402,
+          "hr": 70,
+          "hrv": 148
+        }
+      ]
+    }
+  ]
+}

familiar/__init__.py

@@ -0,0 +1,10 @@
+"""Pulse Familiar — a tiny creature that lives off a real heartbeat."""
+from .state import classify, CreatureState, MOODS
+from .creature import render, beat_period_seconds, MOOD_COLOR
+from .brain import speak, server_alive
+
+__all__ = [
+    "classify", "CreatureState", "MOODS",
+    "render", "beat_period_seconds", "MOOD_COLOR",
+    "speak", "server_alive",
+]

familiar/brain.py

@@ -0,0 +1,179 @@
+"""
+brain.py — the familiar's voice.
+
+Talks to a local llama.cpp `llama-server` (OpenAI-compatible /v1/chat/completions)
+running a <=4B Nemotron model. Fully offline — no cloud APIs (Off-the-Grid badge).
+
+The model only ever receives the creature's *mood* and a few soft physiological
+cues, never clinical numbers. It speaks in short, in-character fragments. If the
+server is unreachable, we fall back to canned lines so the app never hard-fails.
+"""
+from __future__ import annotations
+
+import os
+import random
+import re
+import requests
+
+from .state import CreatureState
+
+# --- backend selection (env FAMILIAR_PROVIDER):
+#   transformers : in-process <=4B model on the Space (ZeroGPU). SHIPS THIS.
+#   local        : external llama.cpp llama-server over HTTP (linuxbox dev).
+#   openrouter   : hosted HTTP, dev only (fast iteration on the voice).
+#   any failure  -> canned in-character fallback, so the app never hard-fails.
+_TIMEOUT = float(os.environ.get("LLAMA_TIMEOUT", "20"))
+_PROVIDER = os.environ.get("FAMILIAR_PROVIDER", "transformers").lower()
+
+if _PROVIDER == "transformers":
+    # in-process backend (the deployed Space). MODEL is the EXACT HF id the
+    # NVIDIA Nemotron Quest is verified on — keep it identical to hf_model.MODEL_ID.
+    from .hf_model import MODEL_ID as MODEL
+    BASE_URL = ""
+    API_KEY = ""
+elif _PROVIDER == "openrouter":
+    BASE_URL = os.environ.get("FAMILIAR_BASE_URL", "https://openrouter.ai/api/v1")
+    API_KEY = os.environ.get("OPENROUTER_API_KEY", "")
+    MODEL = os.environ.get("FAMILIAR_MODEL", "meta-llama/llama-3.2-3b-instruct")
+else:  # local llama-server (linuxbox dev)
+    BASE_URL = os.environ.get("FAMILIAR_BASE_URL", "http://127.0.0.1:8080/v1")
+    API_KEY = os.environ.get("FAMILIAR_API_KEY", "")
+    MODEL = os.environ.get("FAMILIAR_MODEL", "nemotron-mini-4b")
+
+SYSTEM_PROMPT = (
+    "You are Fenn, a small woodland familiar that lives off a human's heartbeat. "
+    "You can feel their pulse but you are not a doctor and never give medical advice "
+    "or numbers. You speak in ONE short line (max ~15 words), warm, a little strange, "
+    "present-tense, like a creature who only knows feelings. You never explain yourself. "
+    "You react to how the heartbeat FEELS, not to data. Use lowercase. Do not say "
+    "you are an assistant. Do not narrate a generic forest scene. Do not say 'my heart'. "
+    "Prefer body words like drum, pulse, beat, breath, ribs, nest. Avoid paths, shadows, "
+    "moons, rivers, stars, and quoted speech."
+)
+
+# Soft, qualitative cue per mood handed to the model (keeps it from reciting vitals).
+_MOOD_CUE = {
+    "sleepy":   "their pulse is slow and heavy, they are drifting toward sleep",
+    "serene":   "their heartbeat is calm and even, deeply at peace",
+    "content":  "their pulse is steady and easy, all is well",
+    "restless": "their heartbeat is picking up, a little fidgety",
+    "anxious":  "their pulse is fast and tight, unsettled, maybe worried",
+    "alarmed":  "their heart is pounding hard and ragged, something is wrong",
+    "excited":  "their heart races bright and open, thrilled and alive",
+}
+
+# Richer per-mood cue bank (the diverse cues the teachers wrote during data-gen).
+# Sampling from these makes Fenn's INPUT vary call-to-call, so it stops feeling
+# canned — and matches the distribution the LoRA was trained on. Falls back to the
+# single hand-written cue above if the bank isn't present.
+import json as _json
+from pathlib import Path as _Path
+
+_CUE_BANK: dict[str, list[str]] = {}
+try:
+    _bp = _Path(__file__).resolve().parent.parent / "data" / "finetune" / "cue_bank.json"
+    if _bp.exists():
+        _CUE_BANK = _json.loads(_bp.read_text())
+except Exception:
+    _CUE_BANK = {}
+
+
+def _normalize_cue(cue: str) -> str:
+    cue = cue.strip().strip('"“”').rstrip(".").strip()
+    cue = re.sub(r"(?i)^right now\s+", "", cue).strip()
+    return cue or _MOOD_CUE["content"]
+
+
+def _cue_for(mood: str) -> str:
+    bank = _CUE_BANK.get(mood)
+    if bank:
+        return _normalize_cue(random.choice(bank))
+    return _normalize_cue(_MOOD_CUE.get(mood, _MOOD_CUE["content"]))
+
+# Fallback lines if llama-server is down — keeps the loop demoable offline.
+_FALLBACK = {
+    "sleepy":   ["mmh… the drum slows. i curl up with it.", "soft… so soft now. i yawn with you."],
+    "serene":   ["your tide is glass-still. i float.", "calm water in here. i breathe slow."],
+    "content":  ["steady little drum. i'm happy by it.", "all even. i hum along."],
+    "restless": ["oh—it twitches. what stirs you?", "your drum fidgets. i tilt my head."],
+    "anxious":  ["it's tight and quick… come back to me.", "the beat frets. i hold still for you."],
+    "alarmed":  ["it POUNDS—! breathe, please, breathe.", "loud, loud, ragged. i grip your hand."],
+    "excited":  ["you blaze! my whole self lights up!", "fast and bright—i dance in it!"],
+}
+
+
+def _messages(state: CreatureState) -> list[dict]:
+    cue = _cue_for(state.mood)
+    trend = {"rising": " and rising", "falling": " and settling"}.get(state.trend, "")
+    user = f"Right now {cue}{trend}. Say one line to them."
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": "Right now their pulse is slow and heavy. Say one line to them."},
+        {"role": "assistant", "content": "mmh… the drum slows. i curl beside it."},
+        {"role": "user", "content": "Right now their pulse is fast and tight, unsettled. Say one line to them."},
+        {"role": "assistant", "content": "the beat frets. i hold still for you."},
+        {"role": "user", "content": user},
+    ]
+
+
+def _client_speak(state: CreatureState, *, max_tokens: int = 32,
+                  temperature: float = 0.8) -> str | None:
+    # In-process transformers backend (the deployed Space).
+    if _PROVIDER == "transformers":
+        from . import hf_model
+        text = hf_model.generate(_messages(state), max_new_tokens=max_tokens,
+                                 temperature=temperature)
+        return _clean(text) if text else None
+
+    # HTTP backends (local llama-server / OpenRouter).
+    headers = {"Authorization": f"Bearer {API_KEY}"} if API_KEY else {}
+    try:
+        r = requests.post(
+            f"{BASE_URL}/chat/completions",
+            headers=headers,
+            json={
+                "model": MODEL,
+                "messages": _messages(state),
+                "max_tokens": max_tokens,
+                "temperature": temperature,
+                "stop": ["\n", "<|im_end|>", "<extra_id_1>", "</s>"],
+            },
+            timeout=_TIMEOUT,
+        )
+        r.raise_for_status()
+        text = r.json()["choices"][0]["message"]["content"]
+        return _clean(text) or None
+    except Exception:
+        return None
+
+
+def _clean(text: str) -> str:
+    """Strip special tokens / quoting the model sometimes emits."""
+    for tok in ("<|im_end|>", "<extra_id_1>", "</s>", "<|endoftext|>"):
+        text = text.replace(tok, "")
+    text = text.strip().split("\n")[0]
+    text = re.sub(r"(?i)^(fenn|assistant|heartbeat|pulse|drum)\s*(whispers|says|murmurs)?\s*:\s*", "", text)
+    return text.strip(' "“”-')
+
+
+def speak(state: CreatureState) -> tuple[str, str]:
+    """Return (line, source) where source is 'model' or 'fallback'."""
+    line = _client_speak(state)
+    if line:
+        return line, "model"
+    return random.choice(_FALLBACK.get(state.mood, _FALLBACK["content"])), "fallback"
+
+
+def server_alive() -> bool:
+    if _PROVIDER == "transformers":
+        from . import hf_model
+        return hf_model.available()
+    if _PROVIDER == "openrouter":
+        return bool(API_KEY)
+    # local llama-server exposes /health at the root (strip the trailing /v1)
+    root = BASE_URL[:-3] if BASE_URL.endswith("/v1") else BASE_URL
+    try:
+        requests.get(f"{root}/health", timeout=2).raise_for_status()
+        return True
+    except Exception:
+        return False

familiar/coach.py

@@ -0,0 +1,99 @@
+"""
+coach.py — "breathe with me": Fenn uses a LEARNED policy to settle a body.
+
+The RL proof-of-concept in rl.py is wired into the live app here. On first use we
+train a tiny REINFORCE policy against PulseEnv (the body-simulator grown from real
+ring stats) — ~1-2s on CPU, numpy only. Then a session starts the simulated body
+elevated and lets Fenn's *learned* policy pick a calming action each step; the
+body responds, and the user watches the heart settle while Fenn coaches.
+
+Honest scope: the policy is trained in SIMULATION (a model of the body fit to the
+wearer's real percentiles + physiology priors), not on live physiology.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from .sim import PulseEnv, ACTIONS
+from .rl import train, policy_action
+from .creature import render
+from .state import classify
+
+_theta = None  # cached learned policy (trained once, lazily)
+
+# Fenn's coaching line + a paced-breath instruction per action. These are the
+# creature's *own* voice for the breathing mode (kept canned so the animation
+# stays smooth — the Nemotron model carries the other two tabs).
+_ACTION_VOICE = {
+    "pace_breath": ("breathe with me… in… and slow out…", "breathe"),
+    "reassure":    ("i'm here. you're safe. i've got your drum.", "hold"),
+    "distract":    ("look — a leaf just spun by. follow it with me.", "soft"),
+    "stay_quiet":  ("…i'll just stay close and quiet now.", "rest"),
+}
+
+# A small paced-breathing guide (≈ resonance breathing). Phase cycles per step.
+_BREATH = [
+    "inhale   ●○○○○○○○",
+    "inhale   ●●●●○○○○",
+    "inhale   ●●●●●●●●",
+    "hold     ●●●●●●●●",
+    "exhale   ●●●●○○○○",
+    "exhale   ●○○○○○○○",
+    "rest     ○○○○○○○○",
+]
+
+
+def _get_policy():
+    global _theta
+    if _theta is None:
+        _theta, _ = train(episodes=2500, seed=0)
+    return _theta
+
+
+def breathe_session(start: str = "panic", max_steps: int = 28):
+    """Generator: yield (body, voice_md, breath_md, state_dict, progress_md).
+
+    Fenn's learned policy acts on the simulated body until it settles or we hit
+    max_steps. The displayed HR/HRV is the *simulated* body responding to Fenn.
+    """
+    theta = _get_policy()
+    env = PulseEnv(start=start, max_steps=max_steps, seed=7)
+    obs = env.reset(start=start)
+    hr0, hrv0 = float(obs[0]), float(obs[1])
+
+    for i in range(max_steps):
+        a = policy_action(theta, obs)
+        action = ACTIONS[a]
+        obs, _r, done, info = env.step(a)
+        hr, hrv = float(obs[0]), float(obs[1])
+        st = classify(hr, hrv)
+
+        line, _tone = _ACTION_VOICE.get(action, _ACTION_VOICE["stay_quiet"])
+        body = render(st.mood, beat_phase=0.7, hr=hr, hrv=hrv)
+        voice = (
+            f"<div style='font-size:1.2rem;font-style:italic;color:#5aa6a0'>"
+            f"“{line}”</div>"
+        )
+        breath = (
+            f"<pre style='font-size:1.15rem;line-height:1.5;color:#7bb86a'>"
+            f"{_BREATH[i % len(_BREATH)]}</pre>"
+            f"<sub>Fenn chose: <b>{action}</b> · the body is responding</sub>"
+        )
+        prog = (
+            f"settling… step {i + 1}/{max_steps}  ·  "
+            f"♥ {hr:.0f} bpm (started {hr0:.0f})  ~ {hrv:.0f} ms (started {hrv0:.0f})"
+        )
+        yield body, voice, breath, st.as_dict(), prog
+
+        import time
+        time.sleep(0.45)
+        if done:
+            settled = (
+                f"**you settled.** ♥ {hr0:.0f}→{hr:.0f} bpm · ~ {hrv0:.0f}→{hrv:.0f} ms "
+                f"in {i + 1} breaths. Fenn learned this in a simulator built from real "
+                f"ring data — it trains in ~2 seconds."
+            )
+            yield body, ("<div style='font-size:1.2rem;font-style:italic;color:#5aa6a0'>"
+                         "“there… your tide is glass-still again.”</div>"), breath, \
+                st.as_dict(), settled
+            return

familiar/creature.py

@@ -0,0 +1,105 @@
+"""
+creature.py — the familiar's body, drawn in text.
+
+One small ASCII creature ("Fenn") with a face per mood and a heartbeat that
+beats: on each beat the chest glyph swells. Everything returns plain strings so
+it renders identically in a terminal, a Gradio textbox, or the gr.Server frontend.
+"""
+from __future__ import annotations
+
+FACES = _FACES = {
+    "sleepy":   ("-.-", "_"),
+    "serene":   ("^.^", "u"),
+    "content":  ("o.o", "w"),
+    "restless": ("o.O", "~"),
+    "anxious":  ("O.O", "o"),
+    "alarmed":  (">.<", "!"),
+    "excited":  ("*.*", "v"),
+}
+
+# A color hint per mood (ANSI 256 + hex) — used by the gr.Server frontend later.
+MOOD_COLOR = {
+    "sleepy":   ("#6b7a99", 61),
+    "serene":   ("#5aa6a0", 73),
+    "content":  ("#7bb86a", 71),
+    "restless": ("#d6a849", 179),
+    "anxious":  ("#d6803c", 173),
+    "alarmed":  ("#c0432b", 167),
+    "excited":  ("#d65a9a", 175),
+}
+
+# heartbeat chest glyphs, indexed by beat phase (0 = rest, 1 = full contraction)
+_HEART = (" .  ", " v  ", "<3 ", "<3>", " V  ")
+
+_AURA = {
+    "sleepy":   "          z     z",
+    "serene":   "        .       .",
+    "content":  "           . .",
+    "restless": "        ?       ?",
+    "anxious":  "       ...   ...",
+    "alarmed":  "        !  !  !",
+    "excited":  "        *  *  *",
+}
+
+_CHEST = {
+    "sleepy": "zzz",
+    "serene": "<3",
+    "content": "<3",
+    "restless": "??",
+    "anxious": "!!",
+    "alarmed": "!!!",
+    "excited": "***",
+}
+
+_TAIL = {
+    "sleepy": "~",
+    "serene": "~",
+    "content": "~",
+    "restless": "?",
+    "anxious": "...",
+    "alarmed": "!!",
+    "excited": "**",
+}
+
+
+def heart_glyph(beat_phase: float) -> str:
+    """beat_phase in 0..1 -> a chest glyph. ~middle of the cycle = full beat."""
+    idx = min(len(_HEART) - 1, int(beat_phase * len(_HEART)))
+    return _HEART[idx]
+
+
+def render(mood: str, *, beat_phase: float = 0.5, hr: float | None = None,
+           hrv: float | None = None) -> str:
+    """Return the creature as a multi-line string for the given mood + beat."""
+    eyes, mouth = _FACES.get(mood, _FACES["content"])
+    heart = _CHEST.get(mood) or heart_glyph(beat_phase).strip()
+    vitals = ""
+    if hr is not None:
+        vitals = f"   ♥ {hr:.0f} bpm" + (f"   ~ {hrv:.0f} ms" if hrv is not None else "")
+    tag = f"{mood.upper()}{vitals}" if hr is not None else ""
+    middle = f"       |  ___  |        {tag}" if tag else "       |  ___  |"
+    return (
+        f"{_AURA.get(mood, _AURA['content'])}\n"
+        "        /\\_/\\\n"
+        f"      _( {eyes} )_\n"
+        f"     /    {mouth:^3}    \\\n"
+        f"    /  | {heart:^5} |  \\  {_TAIL.get(mood, '~')}\n"
+        "   /__/|_______|\\__\\\n"
+        f"{middle}\n"
+        "      /|       |\\\n"
+        "     (_|       |_)\n"
+        "       '.___.'\n"
+        "       .-'   '-."
+    )
+
+
+# Beats-per-minute -> how long one beat cycle lasts, for the animation clock.
+def beat_period_seconds(hr: float) -> float:
+    hr = max(30.0, min(220.0, hr))
+    return 60.0 / hr
+
+
+if __name__ == "__main__":  # quick visual smoke test
+    for m in _FACES:
+        print(render(m, beat_phase=0.5, hr=70, hrv=50))
+        print()

familiar/features.py

@@ -0,0 +1,216 @@
+"""
+features.py — per-day biometric feature vectors from the real ring history.
+
+This is the data layer for two things:
+  1. the morning-briefing agent (today's vector vs the wearer's own baselines), and
+  2. fine-tune training slice #1 (one grounded example per real day).
+
+Source: ~/Health/data/uh_export_raw.jsonl (135K rows, ~65 days with HR over 10mo).
+Each row: {"t": ISO8601, "metric": ..., "value": ..., "ts_epoch": ...}.
+
+Key design choices (verified against the real data, 2026-06-09):
+  - HR and HRV share EXACT timestamps for ~93% of HR rows, so we INNER-JOIN on
+    timestamp (a dict keyed by `t`) — NOT zip-by-index, which misaligns them.
+  - Baselines are CAUSAL: each day's z-score uses only days strictly before it
+    (14-day EWMA), so the vector is honest for a "this morning" briefing.
+  - motion/steps gate the exercise-vs-stress confound: high HR + high motion =
+    exertion (good), high HR + low motion = strain/stress (the discriminator
+    state.py alone can't make).
+"""
+from __future__ import annotations
+
+import json
+import math
+from collections import defaultdict
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+RAW = Path.home() / "Health" / "data" / "uh_export_raw.jsonl"
+OUT = Path(__file__).resolve().parent.parent / "data" / "daily_features.jsonl"
+
+NIGHT_HOURS = range(0, 7)          # 00:00–06:59 local — sleep-window proxy
+EWMA_HALFLIFE = 14                 # days; matches health_pulse.py adaptation scale
+MIN_HISTORY = 3                    # need >=3 prior days before a z-score is meaningful
+
+
+@dataclass
+class DayFeatures:
+    date: str
+    n_hr: int                      # aligned (HR,HRV) samples that day
+    hr_median: float
+    hr_rhr: float | None           # min HR in night window = resting proxy
+    hr_max: float
+    hrv_mean: float
+    hrv_night: float | None        # mean HRV in night window
+    resp_mean: float | None
+    temp_mean: float | None
+    spo2_min: float | None
+    steps_total: float
+    motion_mean: float | None
+    exertion_frac: float           # of high-HR samples, fraction co-occurring w/ motion
+    # causal baselines (only days strictly before this one)
+    hrv_z: float | None            # (night HRV - trailing EWMA) / trailing sd
+    rhr_z: float | None
+    hrv_trend3: str                # 3-day direction of night HRV: rising/falling/steady
+    # coarse ordinal cues for the model (Fable: bin, don't feed raw floats)
+    hrv_cue: str                   # much_lower | lower | usual | higher (vs own baseline)
+    strain_cue: str                # restful | active | strained
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+def _load_by_day() -> dict[str, dict[str, list]]:
+    """Group raw rows into day -> metric -> list[(t, value)]."""
+    days: dict[str, dict[str, list]] = defaultdict(lambda: defaultdict(list))
+    with open(RAW) as f:
+        for line in f:
+            o = json.loads(line)
+            t = o["t"]
+            days[t[:10]][o["metric"]].append((t, o["value"]))
+    return days
+
+
+def _ts_map(rows: list) -> dict[str, float]:
+    return {t: v for t, v in rows}
+
+
+def _hour(t: str) -> int:
+    # "2025-07-09T17:01:28" -> 17
+    return int(t[11:13])
+
+
+def _ewma(values: list[float]) -> tuple[float, float] | None:
+    """Causal EWMA mean + sd over a sequence (oldest..newest). Returns (mean, sd)."""
+    if len(values) < MIN_HISTORY:
+        return None
+    alpha = 1 - math.exp(math.log(0.5) / EWMA_HALFLIFE)
+    mean = values[0]
+    var = 0.0
+    for v in values[1:]:
+        diff = v - mean
+        mean += alpha * diff
+        var = (1 - alpha) * (var + alpha * diff * diff)
+    return mean, math.sqrt(var)
+
+
+def _cue_from_z(z: float | None) -> str:
+    if z is None:
+        return "usual"
+    if z <= -1.5:
+        return "much_lower"
+    if z <= -0.5:
+        return "lower"
+    if z >= 0.5:
+        return "higher"
+    return "usual"
+
+
+def compute() -> list[DayFeatures]:
+    days = _load_by_day()
+    ordered = sorted(d for d in days if days[d].get("raw_hr"))
+
+    night_hrv_history: list[float] = []   # one value per processed day (causal)
+    rhr_history: list[float] = []
+    out: list[DayFeatures] = []
+
+    for date in ordered:
+        d = days[date]
+        hr_map = _ts_map(d.get("raw_hr", []))
+        hrv_map = _ts_map(d.get("raw_hrv_2", []))
+        # INNER JOIN on exact timestamp — the verified-correct alignment.
+        shared = sorted(set(hr_map) & set(hrv_map))
+        if not shared:
+            continue
+        hr = [hr_map[t] for t in shared]
+        hrv = [hrv_map[t] for t in shared]
+
+        hr_sorted = sorted(hr)
+        hr_median = hr_sorted[len(hr_sorted) // 2]
+        hr_max = max(hr)
+        hrv_mean = sum(hrv) / len(hrv)
+
+        night_idx = [i for i, t in enumerate(shared) if _hour(t) in NIGHT_HOURS]
+        hr_rhr = min(hr[i] for i in night_idx) if night_idx else None
+        hrv_night = (sum(hrv[i] for i in night_idx) / len(night_idx)) if night_idx else None
+
+        # motion/steps context (own cadence; aggregate over the day)
+        motion_vals = [v for _, v in d.get("raw_motion", [])]
+        motion_mean = (sum(motion_vals) / len(motion_vals)) if motion_vals else None
+        steps_total = sum(v for _, v in d.get("steps", []))
+        resp_vals = [v for _, v in d.get("respiratory_rate", [])]
+        resp_mean = (sum(resp_vals) / len(resp_vals)) if resp_vals else None
+        temp_vals = [v for _, v in d.get("temp", [])]
+        temp_mean = (sum(temp_vals) / len(temp_vals)) if temp_vals else None
+        spo2_vals = [v for _, v in d.get("spo2", [])]
+        spo2_min = min(spo2_vals) if spo2_vals else None
+
+        # exertion fraction: of the day's high-HR samples, how many co-occur with
+        # real motion? high motion_mean threshold = the exercise/stress discriminator.
+        hi = [hr_map[t] for t in shared if hr_map[t] >= (hr_sorted[int(len(hr_sorted) * 0.75)])]
+        motion_active = (motion_mean is not None and motion_mean > 90) or steps_total > 200
+        exertion_frac = (1.0 if motion_active else 0.0) if hi else 0.0
+
+        # causal baselines (use history BEFORE appending today)
+        ewma_hrv = _ewma(night_hrv_history) if hrv_night is not None else None
+        ewma_rhr = _ewma(rhr_history) if hr_rhr is not None else None
+        hrv_z = ((hrv_night - ewma_hrv[0]) / ewma_hrv[1]) if (ewma_hrv and ewma_hrv[1] > 0) else None
+        rhr_z = ((hr_rhr - ewma_rhr[0]) / ewma_rhr[1]) if (ewma_rhr and ewma_rhr[1] > 0) else None
+
+        trend3 = "steady"
+        if len(night_hrv_history) >= 3 and hrv_night is not None:
+            recent = night_hrv_history[-3:]
+            if hrv_night > recent[-1] > recent[0]:
+                trend3 = "rising"
+            elif hrv_night < recent[-1] < recent[0]:
+                trend3 = "falling"
+
+        if motion_active:
+            strain_cue = "active"
+        elif hr_rhr is not None and rhr_z is not None and rhr_z > 0.8:
+            strain_cue = "strained"
+        else:
+            strain_cue = "restful"
+
+        out.append(DayFeatures(
+            date=date, n_hr=len(shared),
+            hr_median=round(hr_median, 1), hr_rhr=round(hr_rhr, 1) if hr_rhr else None,
+            hr_max=round(hr_max, 1), hrv_mean=round(hrv_mean, 1),
+            hrv_night=round(hrv_night, 1) if hrv_night else None,
+            resp_mean=round(resp_mean, 1) if resp_mean else None,
+            temp_mean=round(temp_mean, 2) if temp_mean else None,
+            spo2_min=spo2_min, steps_total=round(steps_total, 0),
+            motion_mean=round(motion_mean, 1) if motion_mean else None,
+            exertion_frac=round(exertion_frac, 2),
+            hrv_z=round(hrv_z, 2) if hrv_z is not None else None,
+            rhr_z=round(rhr_z, 2) if rhr_z is not None else None,
+            hrv_trend3=trend3,
+            hrv_cue=_cue_from_z(hrv_z), strain_cue=strain_cue,
+        ))
+
+        # NOW append today to history (so next day's baseline is causal)
+        if hrv_night is not None:
+            night_hrv_history.append(hrv_night)
+        if hr_rhr is not None:
+            rhr_history.append(hr_rhr)
+
+    return out
+
+
+def main() -> None:
+    feats = compute()
+    OUT.parent.mkdir(parents=True, exist_ok=True)
+    with open(OUT, "w") as f:
+        for fv in feats:
+            f.write(json.dumps(fv.as_dict()) + "\n")
+    print(f"wrote {len(feats)} daily feature vectors -> {OUT}")
+    # show a few with established baselines
+    withz = [fv for fv in feats if fv.hrv_z is not None]
+    print(f"{len(withz)} days have a causal HRV baseline (>= {MIN_HISTORY} prior nights)")
+    for fv in withz[len(withz) // 2: len(withz) // 2 + 4]:
+        print(f"  {fv.date}: HRVnight={fv.hrv_night} z={fv.hrv_z} cue={fv.hrv_cue} "
+              f"strain={fv.strain_cue} RHR={fv.hr_rhr} steps={fv.steps_total:.0f} trend={fv.hrv_trend3}")
+
+
+if __name__ == "__main__":
+    main()

familiar/hf_model.py

@@ -0,0 +1,139 @@
+"""
+hf_model.py — in-process <=4B model for the deployed Space (ZeroGPU).
+
+On Hugging Face Spaces there is no external llama-server, so Fenn's voice runs
+*inside the app* on a NVIDIA Nemotron-Mini-4B-Instruct (plain transformer, ≤4B —
+Tiny Titan + Nemotron Quest). On ZeroGPU the GPU is granted per-call via the
+`@spaces.GPU` decorator; everything stays self-hosted (no cloud API calls).
+
+This module is import-safe everywhere: torch / transformers / spaces are imported
+lazily, so a laptop without them (or without a GPU) just never selects this
+backend and brain.py falls back to the HTTP providers or canned lines.
+"""
+from __future__ import annotations
+
+import os
+
+MODEL_ID = os.environ.get("FAMILIAR_HF_MODEL", "nvidia/Nemotron-Mini-4B-Instruct")
+# Optional Fenn LoRA adapter (HF repo id or local path). If set and loadable, the
+# fine-tuned voice is used; otherwise the base model runs prompt-only. Drop-in.
+ADAPTER = os.environ.get(
+    "FAMILIAR_ADAPTER", "build-small-hackathon/pulse-familiar-fenn-lora"
+).strip()
+
+_tok = None
+_model = None
+_load_error: str | None = None
+_spoke_live = False   # flips True the first time the real model generates (honesty)
+
+# `spaces` only exists on HF infra; degrade to a no-op decorator off-platform so
+# the same code runs locally on CPU/MPS for testing. Duration is generous: a cold
+# 4B load + first generate must fit inside ONE GPU grant on ZeroGPU, or the first
+# interaction times out and the judge only ever sees the canned fallback.
+try:  # pragma: no cover - environment dependent
+    import spaces  # type: ignore
+
+    _gpu = spaces.GPU(duration=120)
+except Exception:  # pragma: no cover
+    def _gpu(fn):
+        return fn
+
+
+def _ensure_loaded() -> bool:
+    """Lazy-load the model+tokenizer once. Returns True if usable."""
+    global _tok, _model, _load_error
+    if _model is not None:
+        return True
+    if _load_error is not None:
+        return False
+    try:
+        import torch
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+
+        use_cuda = torch.cuda.is_available()
+        dtype = torch.bfloat16 if use_cuda else torch.float32
+        device = "cuda" if use_cuda else "cpu"
+        # pass an HF token if present, in case the NVIDIA repo is gated — otherwise
+        # from_pretrained 401s and we'd silently fall back (fake-Nemotron trap).
+        token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+        kw = {"token": token} if token else {}
+        _tok = AutoTokenizer.from_pretrained(MODEL_ID, **kw)
+        _model = AutoModelForCausalLM.from_pretrained(
+            MODEL_ID, torch_dtype=dtype, low_cpu_mem_usage=True, **kw
+        )
+        if ADAPTER:
+            try:
+                from peft import PeftModel
+
+                _model = PeftModel.from_pretrained(_model, ADAPTER)
+            except Exception:
+                pass  # adapter missing/incompatible -> fall back to base model
+        _model = _model.to(device)
+        _model.eval()
+        return True
+    except Exception as e:  # transformers/torch missing, OOM, gated repo, etc.
+        _load_error = f"{type(e).__name__}: {e}"
+        return False
+
+
+def available() -> bool:
+    """Cheap check used by brain.py / the UI status line."""
+    try:
+        import importlib.util
+
+        return all(
+            importlib.util.find_spec(m) is not None
+            for m in ("torch", "transformers")
+        )
+    except Exception:
+        return False
+
+
+@_gpu
+def generate(messages: list[dict], *, max_new_tokens: int = 48,
+             temperature: float = 0.9) -> str | None:
+    """Run one short generation. Returns raw text or None on any failure."""
+    if not _ensure_loaded():
+        return None
+    try:
+        import torch
+
+        inputs = _tok.apply_chat_template(
+            messages, add_generation_prompt=True, return_tensors="pt"
+        ).to(_model.device)
+        with torch.no_grad():
+            out = _model.generate(
+                inputs,
+                max_new_tokens=max_new_tokens,
+                do_sample=True,
+                temperature=temperature,
+                top_p=0.9,
+                pad_token_id=_tok.eos_token_id,
+            )
+        text = _tok.decode(out[0][inputs.shape[-1]:], skip_special_tokens=True)
+        global _spoke_live
+        _spoke_live = True
+        return text
+    except Exception:
+        return None
+
+
+def load_error() -> str | None:
+    return _load_error
+
+
+def spoke_live() -> bool:
+    """True once the real model has generated at least one line this session."""
+    return _spoke_live
+
+
+def status() -> dict:
+    """Honest backend state for the UI — so we can SEE Nemotron is real, not faked."""
+    return {
+        "model_id": MODEL_ID,
+        "adapter": ADAPTER or None,
+        "loaded": _model is not None,
+        "spoke_live": _spoke_live,
+        "load_error": _load_error,
+        "deps_present": available(),
+    }

familiar/memories.py

@@ -0,0 +1,35 @@
+"""
+memories.py — load the curated real-ring episodes for the Memories replay.
+
+data/sessions.json holds a few short, anonymized episodes carved from the
+wearer's actual Ultrahuman history (see tools/extract_sessions.py). Each is a
+list of {dt, hr, hrv} samples. The UI replays them so Fenn reacts to a *real*
+lived heartbeat, not a synthetic one — the whole point of the project.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+_PATH = Path(__file__).resolve().parent.parent / "data" / "sessions.json"
+
+
+def load_episodes() -> list[dict]:
+    if not _PATH.exists():
+        return []
+    try:
+        return json.loads(_PATH.read_text()).get("episodes", [])
+    except Exception:
+        return []
+
+
+def episode_titles() -> list[tuple[str, str]]:
+    """(label, id) pairs for a Gradio dropdown."""
+    return [(e["title"], e["id"]) for e in load_episodes()]
+
+
+def get_episode(ep_id: str) -> dict | None:
+    for e in load_episodes():
+        if e["id"] == ep_id:
+            return e
+    return None

familiar/rl.py

@@ -0,0 +1,109 @@
+"""
+rl.py — can Fenn LEARN to calm a body? A tiny REINFORCE policy on PulseEnv.
+
+This is the "fun" proof-of-concept: a linear softmax policy over the (normalized)
+state picks one of the calming ACTIONS each step; we train it by policy gradient
+against the simulated body (sim.PulseEnv). No torch — numpy only, trains in
+seconds on CPU because the environment is the mock built from real ring stats.
+
+What it should learn: when the heart is elevated, prefer pace_breath / reassure;
+when already calm, stop fussing. A learned policy should beat a random one and a
+single fixed action. Honest scope: trained in SIMULATION (a model of the body),
+not on live physiology — that's the disclosure for the writeup.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from .sim import PulseEnv, ACTIONS
+
+_N_ACT = len(ACTIONS)
+
+
+def _features(obs: np.ndarray) -> np.ndarray:
+    """Normalize (hr, hrv, step) -> small feature vector + bias."""
+    hr, hrv, step = obs
+    return np.array([1.0, (hr - 80) / 30.0, (hrv - 120) / 60.0, step / 40.0])
+
+
+def _policy(theta: np.ndarray, feat: np.ndarray):
+    logits = theta @ feat                 # (n_act,)
+    logits -= logits.max()
+    p = np.exp(logits)
+    return p / p.sum()
+
+
+def train(episodes: int = 4000, lr: float = 0.02, seed: int = 0,
+          starts=("stress", "panic", "light")):
+    rng = np.random.default_rng(seed)
+    theta = np.zeros((_N_ACT, 4))
+    env = PulseEnv(seed=seed)
+    returns = []
+    for ep in range(episodes):
+        start = starts[ep % len(starts)]
+        obs = env.reset(start=start)
+        traj = []           # (feat, action, reward)
+        done = False
+        while not done:
+            feat = _features(obs)
+            p = _policy(theta, feat)
+            a = int(rng.choice(_N_ACT, p=p))
+            obs, r, done, _ = env.step(a)
+            traj.append((feat, a, r))
+        # discounted returns-to-go
+        G, gamma, grets = 0.0, 0.97, []
+        for (_, _, r) in reversed(traj):
+            G = r + gamma * G
+            grets.append(G)
+        grets.reverse()
+        grets = np.array(grets)
+        grets = (grets - grets.mean()) / (grets.std() + 1e-6)   # baseline
+        # REINFORCE update
+        for (feat, a, _), Gt in zip(traj, grets):
+            p = _policy(theta, feat)
+            grad = -np.outer(p, feat)
+            grad[a] += feat
+            theta += lr * Gt * grad
+        returns.append(sum(r for _, _, r in traj))
+    return theta, returns
+
+
+def policy_action(theta: np.ndarray, obs: np.ndarray) -> int:
+    return int(np.argmax(_policy(theta, _features(obs))))
+
+
+def _eval(theta, n=300, start="stress", seed=99):
+    env = PulseEnv(seed=seed)
+    rng = np.random.default_rng(seed)
+    learned = fixed = rand = 0.0
+    for i in range(n):
+        # learned (greedy)
+        obs, done, tot = env.reset(start=start), False, 0.0
+        while not done:
+            obs, r, done, _ = env.step(policy_action(theta, obs)); tot += r
+        learned += tot
+        # fixed: always pace_breath
+        obs, done, tot = env.reset(start=start), False, 0.0
+        while not done:
+            obs, r, done, _ = env.step(ACTIONS.index("pace_breath")); tot += r
+        fixed += tot
+        # random
+        obs, done, tot = env.reset(start=start), False, 0.0
+        while not done:
+            obs, r, done, _ = env.step(int(rng.integers(_N_ACT))); tot += r
+        rand += tot
+    return learned / n, fixed / n, rand / n
+
+
+if __name__ == "__main__":
+    theta, returns = train(episodes=4000, seed=0)
+    early = np.mean(returns[:200]); late = np.mean(returns[-200:])
+    print(f"train return: {early:.2f} (early) -> {late:.2f} (late)")
+    for start in ("stress", "panic"):
+        L, F, R = _eval(theta, start=start)
+        print(f"[{start:6}] learned={L:6.2f}  fixed(pace)={F:6.2f}  random={R:6.2f}")
+    # what did it learn?
+    print("\nlearned action by state:")
+    for hr, hrv in [(120, 30), (95, 70), (70, 140), (60, 160)]:
+        a = ACTIONS[policy_action(theta, np.array([hr, hrv, 5]))]
+        print(f"  HR{hr:3} HRV{hrv:3} -> {a}")

familiar/sim.py

@@ -0,0 +1,159 @@
+"""
+sim.py — a mock heartbeat, grown from real data.
+
+Two jobs, one model:
+  1. generate_session(arc) -> a realistic HR/HRV time-series the creature can
+     "live through" (demo/replay without needing a fresh ring export).
+  2. PulseEnv -> a reinforcement-learning environment: Fenn picks a calming
+     action, the simulated body responds, reward = the body settling. Trainable
+     in minutes on CPU because episodes are simulated, not lived.
+
+Grounding (measured from ~/Health/data/uh_export_raw.jsonl, n=14.3K HR / 16.8K HRV):
+  HR  median 72, resting ~62, sd 21, p05 46 (deep sleep) .. p95 113 (exertion)
+  HRV median 131, sd 67, p05 5 .. p95 235
+  HR 5-min step sd ~18 (cross-regime); within a regime it's much smaller.
+
+Physiology priors (established, not measured here):
+  - Higher arousal -> higher HR, lower HRV.
+  - STRESS vs EXERCISE both raise HR, but stress crushes HRV while a relaxed
+    high-HR (excitement) keeps HRV up. The env reward leans on this.
+  - Slow paced breathing (~6 breaths/min, resonance freq) raises HRV / lowers HR.
+
+Determinism: no global RNG. Pass a seed; we derive a numpy Generator from it so
+runs are reproducible (and the workflow/Date-free constraint is respected).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+# Regime archetypes: (target_hr, target_hrv). Pulled from the real percentiles.
+REGIMES = {
+    "deep_sleep": (48.0, 200.0),
+    "rest":       (62.0, 150.0),
+    "calm":       (66.0, 145.0),
+    "light":      (88.0, 95.0),
+    "exercise":   (118.0, 55.0),   # high HR, but HRV not floored -> "excited"
+    "stress":     (102.0, 38.0),   # high HR AND crushed HRV -> "anxious/alarmed"
+    "panic":      (128.0, 22.0),
+}
+
+# how fast HR pulls toward the regime target each step (Ornstein-Uhlenbeck theta)
+_THETA_HR = 0.25
+_THETA_HRV = 0.20
+_SAMPLE_SEC = 30          # one simulated reading per 30s (denser than the 5-min export)
+
+
+@dataclass
+class Reading:
+    t: float        # seconds from session start
+    hr: float
+    hrv: float
+    regime: str
+
+
+def _step(hr, hrv, tgt_hr, tgt_hrv, rng, vol_hr=2.2, vol_hrv=7.0):
+    """One OU step toward a regime target, with noise. Returns (hr, hrv)."""
+    hr = hr + _THETA_HR * (tgt_hr - hr) + rng.normal(0, vol_hr)
+    hrv = hrv + _THETA_HRV * (tgt_hrv - hrv) + rng.normal(0, vol_hrv)
+    return float(np.clip(hr, 38, 200)), float(np.clip(hrv, 4, 260))
+
+
+def generate_session(arc: list[tuple[str, float]], *, seed: int = 0,
+                     sample_sec: int = _SAMPLE_SEC) -> list[Reading]:
+    """arc = [(regime, minutes), ...] -> a smooth HR/HRV walk through those regimes.
+
+    Example (a stressful afternoon that resolves):
+        [("calm", 2), ("stress", 4), ("panic", 1.5), ("rest", 4)]
+    """
+    rng = np.random.default_rng(seed)
+    hr, hrv = REGIMES.get(arc[0][0], REGIMES["rest"])
+    out: list[Reading] = []
+    t = 0.0
+    for regime, minutes in arc:
+        tgt_hr, tgt_hrv = REGIMES.get(regime, REGIMES["rest"])
+        for _ in range(int(minutes * 60 / sample_sec)):
+            hr, hrv = _step(hr, hrv, tgt_hr, tgt_hrv, rng)
+            out.append(Reading(round(t, 1), round(hr, 1), round(hrv, 1), regime))
+            t += sample_sec
+    return out
+
+
+# ---------------------------------------------------------------------------
+# RL environment — Fenn tries to settle a simulated body.
+# ---------------------------------------------------------------------------
+ACTIONS = ("stay_quiet", "pace_breath", "reassure", "distract")
+
+
+class PulseEnv:
+    """Contextual episodic env. State = (hr, hrv, step). Fenn picks an action;
+    the body responds; reward favors HRV up + HR toward rest. The 'right' action
+    depends on the current state (pace_breath helps a racing heart; staying quiet
+    is fine when already calm) — so a learned policy beats a fixed one.
+    """
+
+    def __init__(self, *, max_steps: int = 40, start: str = "stress", seed: int = 0):
+        self.max_steps = max_steps
+        self.start_regime = start
+        self.rng = np.random.default_rng(seed)
+        self.reset()
+
+    def reset(self, start: str | None = None):
+        hr, hrv = REGIMES.get(start or self.start_regime, REGIMES["stress"])
+        self.hr, self.hrv = hr, hrv
+        self.step_i = 0
+        return self._obs()
+
+    def _obs(self):
+        return np.array([self.hr, self.hrv, self.step_i], dtype=np.float32)
+
+    def step(self, action: int):
+        a = ACTIONS[action]
+        # action shifts the body's *target* (where the OU pull goes) + a compliance
+        # roll (the human doesn't always follow). pace_breath is strongest when the
+        # heart is elevated; distract can backfire when already calm.
+        tgt_hr, tgt_hrv = self.hr, self.hrv
+        elevated = self.hr > 80
+        comply = self.rng.random() < (0.85 if a == "pace_breath" else 0.6)
+        if comply:
+            if a == "pace_breath":
+                tgt_hr, tgt_hrv = (62.0, 150.0) if elevated else (self.hr - 2, self.hrv + 8)
+            elif a == "reassure":
+                tgt_hr, tgt_hrv = self.hr - 6, self.hrv + 18
+            elif a == "distract":
+                # helps if anxious, slightly agitates if already calm
+                tgt_hr = self.hr - 8 if elevated else self.hr + 4
+                tgt_hrv = self.hrv + 10 if elevated else self.hrv - 6
+            else:  # stay_quiet: gentle natural drift toward rest
+                tgt_hr, tgt_hrv = self.hr - 1.5, self.hrv + 3
+
+        hrv_before = self.hrv
+        self.hr, self.hrv = _step(self.hr, self.hrv, tgt_hr, tgt_hrv, self.rng,
+                                  vol_hr=1.5, vol_hrv=5.0)
+        self.step_i += 1
+
+        # reward: HRV gained this step + a pull toward restful HR, scaled small
+        reward = (self.hrv - hrv_before) / 10.0 + (70 - self.hr) / 60.0
+        done = self.step_i >= self.max_steps or (self.hr < 66 and self.hrv > 140)
+        if done and self.hr < 66 and self.hrv > 140:
+            reward += 5.0  # bonus for actually settling the body
+        return self._obs(), float(reward), done, {"action": a, "complied": comply}
+
+
+if __name__ == "__main__":  # smoke: generate a session + a random-policy rollout
+    from .state import classify
+    sess = generate_session([("calm", 1), ("stress", 2), ("panic", 1), ("rest", 2)], seed=1)
+    print(f"session: {len(sess)} readings, {sess[-1].t/60:.1f} min")
+    for r in sess[::8]:
+        print(f"  t={r.t/60:4.1f}m  HR={r.hr:5.1f}  HRV={r.hrv:5.0f}  {r.regime:10} -> {classify(r.hr, r.hrv).mood}")
+    print("\nrandom-policy env rollout:")
+    env = PulseEnv(start="stress", seed=2)
+    rng = np.random.default_rng(2)
+    obs, tot = env.reset(), 0.0
+    for _ in range(40):
+        obs, rew, done, info = env.step(int(rng.integers(len(ACTIONS))))
+        tot += rew
+        if done:
+            break
+    print(f"  ended HR={obs[0]:.0f} HRV={obs[1]:.0f} after {int(obs[2])} steps, return={tot:.2f}")

familiar/state.py

@@ -0,0 +1,101 @@
+"""
+state.py — turn a heartbeat into a creature's emotional state.
+
+Pure, deterministic. No model here: this is the bridge between physiology and
+feeling. HR + HRV (relative to the wearer's own baseline) collapse into one of a
+small set of moods plus an intensity 0..1. The model (brain.py) only ever sees
+the *mood*, never raw clinical numbers — the creature feels, it doesn't diagnose.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+
+# The wearer's real baselines, measured from ~/Health/data/uh_export_raw.jsonl
+# (14.3K raw_hr, 16.8K raw_hrv_2 samples): HR median 72 / resting ~62, sd 21;
+# HRV (raw_hrv_2) median 131, sd 67. Spreads below are the std-devs we
+# standardize against. Overridable per-person in pulse.py.
+DEFAULT_HR_BASELINE = 62.0      # bpm, calm resting
+DEFAULT_HRV_BASELINE = 140.0    # ms, rested (real median ~131)
+DEFAULT_HR_SPREAD = 16.0        # bpm, ~0.75 of real sd (resting-context, not all-day)
+DEFAULT_HRV_SPREAD = 55.0       # ms
+
+# Moods, ordered roughly low-arousal -> high-arousal. Each maps to an ASCII face
+# in creature.py and a voice register in brain.py.
+MOODS = ("sleepy", "serene", "content", "restless", "anxious", "alarmed", "excited")
+
+
+@dataclass
+class CreatureState:
+    mood: str            # one of MOODS
+    intensity: float     # 0..1, how strongly the mood is felt
+    hr: float            # current heart rate (bpm)
+    hrv: float           # current HRV (ms)
+    hr_z: float          # HR standardized vs baseline (+ = faster than usual)
+    hrv_z: float         # HRV standardized vs baseline (+ = more relaxed)
+    trend: str           # "rising" | "falling" | "steady" — short-term HR drift
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+def _z(value: float, baseline: float, spread: float) -> float:
+    """Standardize a reading against the wearer's own baseline."""
+    if spread <= 0:
+        spread = 1.0
+    return (value - baseline) / spread
+
+
+def classify(
+    hr: float,
+    hrv: float,
+    *,
+    hr_baseline: float = DEFAULT_HR_BASELINE,
+    hrv_baseline: float = DEFAULT_HRV_BASELINE,
+    hr_spread: float = DEFAULT_HR_SPREAD,
+    hrv_spread: float = DEFAULT_HRV_SPREAD,
+    prev_hr: float | None = None,
+) -> CreatureState:
+    """Map a single (HR, HRV) reading to a CreatureState.
+
+    Arousal is driven mostly by HR (how fast the heart is going relative to the
+    wearer's normal); HRV refines it (low HRV under a high HR = stress, not joy).
+    """
+    hr_z = _z(hr, hr_baseline, hr_spread)
+    hrv_z = _z(hrv, hrv_baseline, hrv_spread)
+
+    # arousal: faster-than-usual heart pushes up; high HRV pulls back toward calm
+    arousal = hr_z - 0.4 * hrv_z
+
+    if arousal < -1.2:
+        mood = "sleepy"
+    elif arousal < -0.4:
+        mood = "serene"
+    elif arousal < 0.5:
+        mood = "content"
+    elif arousal < 1.3:
+        mood = "restless"
+    elif arousal < 2.6:
+        # high arousal: low HRV => anxious (stress), decent HRV => excited (good)
+        mood = "anxious" if hrv_z < -0.1 else "excited"
+    else:
+        mood = "alarmed" if hrv_z < 0.0 else "excited"
+
+    intensity = max(0.0, min(1.0, abs(arousal) / 2.5))
+
+    trend = "steady"
+    if prev_hr is not None:
+        d = hr - prev_hr
+        if d > 2.5:
+            trend = "rising"
+        elif d < -2.5:
+            trend = "falling"
+
+    return CreatureState(
+        mood=mood,
+        intensity=round(intensity, 3),
+        hr=round(hr, 1),
+        hrv=round(hrv, 1),
+        hr_z=round(hr_z, 2),
+        hrv_z=round(hrv_z, 2),
+        trend=trend,
+    )

familiar/trace.py

@@ -0,0 +1,33 @@
+"""
+trace.py — append-only log of every (state -> prompt -> utterance) the familiar
+produces. Uploaded later as an HF dataset (Sharing-is-Caring badge) so others can
+study how a tiny model voices a creature from biometrics.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+from .state import CreatureState
+
+_TRACE_PATH = Path(os.environ.get("TRACE_PATH", "data/traces.jsonl"))
+
+
+def log(state: CreatureState, line: str, source: str) -> None:
+    _TRACE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    rec = {
+        "ts": round(time.time(), 3),
+        "mood": state.mood,
+        "intensity": state.intensity,
+        "hr": state.hr,
+        "hrv": state.hrv,
+        "hr_z": state.hr_z,
+        "hrv_z": state.hrv_z,
+        "trend": state.trend,
+        "line": line,
+        "source": source,
+    }
+    with _TRACE_PATH.open("a") as f:
+        f.write(json.dumps(rec, ensure_ascii=False) + "\n")

requirements.txt

@@ -0,0 +1,10 @@
+gradio==5.49.1
+spaces
+torch
+transformers>=4.44.0
+accelerate>=0.33.0
+peft>=0.12.0
+sentencepiece
+protobuf
+numpy
+requests