synapsen 0.1.0__py3-none-any.whl

synapsen/__init__.py

@@ -0,0 +1,63 @@
+"""synapsen — ein homöostatischer Zustandskern für Agenten.
+
+Botenstoffe statt Stimmungs-Strings: Ereignisse schütten aus, Werte zerfallen,
+koppeln sich, folgen einem Tagesrhythmus. Verhalten wird nicht gesetzt, es
+entsteht.
+
+    from synapsen import HomeostasisEngine, PromptRenderer, JsonStore
+
+    engine = HomeostasisEngine(store=JsonStore("~/.config/agent/state.json"))
+    engine.stimulus({"dopamine": +15}, kind="tool_success", context="deploy")
+    prompt_suffix = PromptRenderer().render(engine.snapshot())
+"""
+from .clock import Clock, FakeClock, SystemClock
+from .dynamics import Equilibrium, equilibrium, impulse_response
+from .engine import HomeostasisEngine, Snapshot
+from .explain import explain
+from .journal import Event, MemoryJournal, NullJournal, SqliteJournal, mood_bias
+from .profile import DEFAULT_PROFILE, Coupling, DerivedState, HormoneSpec, Profile
+from .profiles import PROFILES
+from .profiles import get as get_profile
+from .render import PromptRenderer, RenderConfig
+from .simulate import Scenario, Trajectory, chart
+from .simulate import run as simulate
+from .store import JsonStore, MemoryStore, StateStore
+from .validate import Report, check
+
+__version__ = "0.1.0"
+
+__all__ = [
+                      "DEFAULT_PROFILE",
+                      "PROFILES",
+                      "Clock",
+                      "Coupling",
+                      "DerivedState",
+                      "Equilibrium",
+                      "Event",
+                      "FakeClock",
+                      "HomeostasisEngine",
+                      "HormoneSpec",
+                      "JsonStore",
+                      "MemoryJournal",
+                      "MemoryStore",
+                      "NullJournal",
+                      "Profile",
+                      "PromptRenderer",
+                      "RenderConfig",
+                      "Report",
+                      "Scenario",
+                      "Snapshot",
+                      "SqliteJournal",
+                      "StateStore",
+                      "SystemClock",
+                      "Trajectory",
+                      "__version__",
+                      "chart",
+                      "check",
+                      "equilibrium",
+                      "explain",
+                      "get_profile",
+                      "impulse_response",
+                      "mood_bias",
+                      "simulate",
+]

synapsen/cli.py

@@ -0,0 +1,262 @@
+"""Kommandozeile.
+
+    synapsen doctor                    Profil prüfen
+    synapsen show                      aktuellen Zustand ansehen
+    synapsen why                       Zustand auf seine Ursachen zurückführen
+    synapsen simulate --days 14        Verlauf durchrechnen
+    synapsen events                    verfügbare Ereignisse auflisten
+    synapsen profiles                  mitgelieferte Profile auflisten
+    synapsen mcp                       als MCP-Server laufen
+
+Alle Unterbefehle nehmen `--profile` (mitgeliefert oder Pfad zu einer
+JSON-Datei) und `--state` (Zustandsdatei).
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .profile import Profile
+from .profiles import get as get_profile
+from .profiles import names as profile_names
+
+
+def _load_profile(spec: str) -> Profile:
+    path = Path(spec).expanduser()
+    if path.suffix == ".json" and path.exists():
+        return Profile.from_json(path)
+    return get_profile(spec)
+
+
+def _engine(args):
+    from .engine import HomeostasisEngine
+    from .journal import SqliteJournal
+    from .store import JsonStore
+    profile = _load_profile(args.profile)
+    return HomeostasisEngine(
+        profile,
+        store=JsonStore(args.state),
+        journal=(SqliteJournal.for_profile(args.journal, profile)
+                 if args.journal else None),
+    )
+
+
+# ── Unterbefehle ───────────────────────────────────────────────────────────
+
+def cmd_doctor(args) -> int:
+    from .validate import check
+    profile = _load_profile(args.profile)
+    report = check(profile)
+    if args.profile != profile.name:
+        print(f"Aufgerufen als: {args.profile}")
+    print(report)
+    print()
+    if report.ok:
+        print("✓ Profil ist tragfähig.")
+    else:
+        print(f"✗ {len(report.errors)} Fehler — so sollte das Profil nicht laufen.")
+    return 0 if report.ok else 1
+
+
+def cmd_show(args) -> int:
+    from .render import PromptRenderer, RenderConfig
+    engine = _engine(args)
+    snap = engine.snapshot()
+    if args.raw:
+        import json
+        print(json.dumps({
+            "hormones": {k: round(v, 2) for k, v in snap.hormones.items()},
+            "baselines": {k: round(v, 2) for k, v in snap.baselines.items()},
+            "states": {k: round(v, 3) for k, v in snap.states.items()},
+            "bond": round(snap.bond, 2),
+            "fatigue": round(snap.adenosine, 2),
+        }, ensure_ascii=False, indent=2))
+    else:
+        print(PromptRenderer(RenderConfig(
+            partner=args.partner, language=args.language)).render(snap))
+    engine.flush()
+    return 0
+
+
+def cmd_why(args) -> int:
+    from .explain import explain
+    print(explain(_engine(args)))
+    return 0
+
+
+def cmd_event(args) -> int:
+    engine = _engine(args)
+    engine.event(args.event, intensity=args.intensity, context=args.context)
+    engine.flush()
+    snap = engine.snapshot()
+    pos, value = snap.dominant("positive")
+    print(f"{args.event} verbucht.  "
+          + "  ".join(f"{k} {v:.1f}" for k, v in snap.hormones.items()))
+    print(f"Vorherrschend: {pos} {value:.2f}")
+    return 0
+
+
+def cmd_simulate(args) -> int:
+    from .simulate import Scenario, chart, profile_chart, run
+
+    profile = _load_profile(args.profile)
+    days = args.days
+
+    event = args.event or _default_event(profile)
+    if args.scenario != "quiet" and event not in profile.events:
+        print(f"Profil {profile.name!r} kennt kein Ereignis {event!r}.",
+              file=sys.stderr)
+        print(f"Bekannt: {', '.join(sorted(profile.events)) or '(keine)'}",
+              file=sys.stderr)
+        return 2
+
+    if args.scenario == "workweek":
+        # Nebenereignisse nur, wenn das Profil sie kennt — ein Arbeitsprofil
+        # ohne Beziehung hat kein "warm_contact".
+        morning = _first_known(profile, ["warm_contact", "session_start", "calm"])
+        evening = _first_known(profile, ["conversation_end", "session_end", "calm"])
+        s = Scenario(f"Arbeitswoche ({event})", days=days, start_hour=8)
+        for d in range(int(days)):
+            for hour in (9, 11, 14, 16, 18):
+                s.at(d * 24 + hour, event)
+            if morning:
+                s.at(d * 24 + 8.5, morning)
+            if evening:
+                s.at(d * 24 + 22, evening)
+    elif args.scenario == "steady":
+        s = Scenario(f"gleichmäßig ({event})", days=days)
+        s.every(hours=args.interval, event=event)
+    elif args.scenario == "quiet":
+        s = Scenario("ohne jeden Reiz", days=days)
+    else:
+        print(f"Unbekanntes Szenario: {args.scenario}", file=sys.stderr)
+        return 2
+
+    traj = run(s, profile)
+
+    if args.csv:
+        Path(args.csv).write_text(traj.to_csv(), encoding="utf-8")
+        print(f"{len(traj.samples)} Messpunkte nach {args.csv} geschrieben.")
+        return 0
+
+    if args.plot:
+        print(profile_chart(traj, args.plot))
+        return 0
+
+    keys = args.keys.split(",") if args.keys else None
+    print(chart(traj, keys))
+    return 0
+
+
+def _first_known(profile, candidates: list[str]) -> str | None:
+    return next((c for c in candidates if c in profile.events), None)
+
+
+def _default_event(profile) -> str:
+    """Ein Ereignis, das dieses Profil kennt — für den Aufruf ohne --event."""
+    return (_first_known(profile, ["task_success", "reward", "praise"])
+            or (min(profile.events) if profile.events else ""))
+
+
+def cmd_events(args) -> int:
+    profile = _load_profile(args.profile)
+    if not profile.events:
+        print(f"Profil {profile.name!r} definiert keine benannten Ereignisse.")
+        return 0
+    print(f"Ereignisse in Profil {profile.name!r}:")
+    for name, spec in sorted(profile.events.items()):
+        parts = ", ".join(f"{k} {v:+g}" for k, v in spec.items() if k != "severity")
+        print(f"  {name:<22} {parts}   (Schwere {spec.get('severity', 0):+g})")
+    return 0
+
+
+def cmd_profiles(args) -> int:
+    from .dynamics import equilibrium
+    from .validate import check
+    for name in profile_names():
+        p = get_profile(name)
+        report = check(p)
+        eq = equilibrium(p)
+        mark = "✓" if report.ok and eq.healthy else "✗"
+        print(f"  {mark} {name:<8} {len(p.hormones)} Botenstoffe, "
+              f"{len(p.states)} Zustände, {len(p.couplings)} Kopplungen")
+        print(f"      {', '.join(p.hormone_names())}")
+    return 0
+
+
+def cmd_mcp(args) -> int:
+    from .mcp_server import serve
+    return serve(_engine(args))
+
+
+# ── Verdrahtung ────────────────────────────────────────────────────────────
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="synapsen",
+        description="Homöostatischer Zustandskern für Agenten.")
+    p.add_argument("--version", action="version", version=f"synapsen {__version__}")
+    p.add_argument("--profile", default="kira",
+                   help=f"mitgeliefert ({', '.join(profile_names())}) oder Pfad zu einer JSON-Datei")
+    p.add_argument("--state", default="~/.config/synapsen/state.json")
+    p.add_argument("--journal", default=None, help="SQLite-Datei fürs Ereignisprotokoll")
+
+    sub = p.add_subparsers(dest="command", required=True)
+
+    d = sub.add_parser("doctor", help="Profil auf Fehler prüfen")
+    d.set_defaults(func=cmd_doctor)
+
+    s = sub.add_parser("show", help="aktuellen Zustand ansehen")
+    s.add_argument("--raw", action="store_true", help="als JSON statt als Prompt")
+    s.add_argument("--partner", default="dein Gegenüber")
+    s.add_argument("--language", default="de", choices=["de", "en"])
+    s.set_defaults(func=cmd_show)
+
+    w = sub.add_parser("why", help="Zustand auf seine Ursachen zurückführen")
+    w.set_defaults(func=cmd_why)
+
+    e = sub.add_parser("event", help="ein Ereignis verbuchen")
+    e.add_argument("event")
+    e.add_argument("--intensity", type=float, default=1.0)
+    e.add_argument("--context", default="")
+    e.set_defaults(func=cmd_event)
+
+    sim = sub.add_parser("simulate", help="Verlauf durchrechnen")
+    sim.add_argument("--days", type=float, default=14)
+    sim.add_argument("--scenario", default="workweek",
+                     choices=["workweek", "steady", "quiet"])
+    sim.add_argument("--event", default=None,
+                     help="ohne Angabe ein Ereignis, das das Profil kennt")
+    sim.add_argument("--interval", type=float, default=4.0)
+    sim.add_argument("--keys", default=None, help="Komma-getrennt, z. B. cortisol,RUHIG")
+    sim.add_argument("--plot", default=None, help="eine Reihe groß darstellen")
+    sim.add_argument("--csv", default=None, help="in eine CSV-Datei schreiben")
+    sim.set_defaults(func=cmd_simulate)
+
+    ev = sub.add_parser("events", help="verfügbare Ereignisse auflisten")
+    ev.set_defaults(func=cmd_events)
+
+    pr = sub.add_parser("profiles", help="mitgelieferte Profile auflisten")
+    pr.set_defaults(func=cmd_profiles)
+
+    m = sub.add_parser("mcp", help="als MCP-Server laufen")
+    m.set_defaults(func=cmd_mcp)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyError as exc:
+        print(f"Fehler: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

synapsen/clock.py

@@ -0,0 +1,59 @@
+"""Zeitquelle — injizierbar, damit die Engine testbar und simulierbar ist.
+
+Der Grund: die Original-Engine ruft an ~20 Stellen `time.time()` und
+`datetime.now()` direkt auf. Damit lässt sich kein Verlauf über Tage testen,
+ohne wirklich Tage zu warten. Eine injizierte Uhr macht aus dem Zustandsmodell
+ein *simulierbares* Modell — man kann 6 Monate Beziehungsverlauf in
+Millisekunden durchrechnen.
+"""
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from typing import Protocol
+
+
+class Clock(Protocol):
+    def now(self) -> float:
+        """Unix-Zeitstempel in Sekunden."""
+        ...
+
+    def local(self) -> datetime:
+        """Lokale Wanduhrzeit (für circadiane Rhythmen)."""
+        ...
+
+
+class SystemClock:
+    """Echte Zeit. Der Default im Betrieb."""
+
+    def now(self) -> float:
+        return time.time()
+
+    def local(self) -> datetime:
+        return datetime.now()
+
+
+class FakeClock:
+    """Steuerbare Zeit für Tests und Simulationen.
+
+    >>> c = FakeClock(start=0.0)
+    >>> c.advance(hours=8)
+    >>> c.now()
+    28800.0
+    """
+
+    def __init__(self, start: float = 0.0):
+        self._t = float(start)
+
+    def now(self) -> float:
+        return self._t
+
+    def local(self) -> datetime:
+        return datetime.fromtimestamp(self._t)
+
+    def advance(self, seconds: float = 0.0, minutes: float = 0.0,
+                hours: float = 0.0, days: float = 0.0) -> None:
+        self._t += seconds + minutes * 60 + hours * 3600 + days * 86400
+
+    def set(self, t: float) -> None:
+        self._t = float(t)

synapsen/dynamics.py

@@ -0,0 +1,240 @@
+"""Die Dynamik: was sich pro Stunde ändert, und wo das System landet.
+
+Diese Datei ist der Grund, warum die Bibliothek analysierbar ist statt nur
+lauffähig. Alles, was den Zustand bewegt, ist hier als **Rate pro Stunde**
+formuliert. Damit lässt sich das Gleichgewicht ausrechnen, statt es abzuwarten
+— und ein Profil auf Stabilität prüfen, bevor es in Betrieb geht.
+
+Warum das nötig war
+-------------------
+In der Ursprungsfassung war die Kopplung *aufrufbasiert*:
+
+    delta = (excess / per) * gain * 0.02 * min(dt_sekunden, 60)
+
+Der Faktor `min(dt, 60)` deckelt den Schritt, aber die Wirkung hängt damit
+daran, **wie oft** getickt wird — nicht daran, wie viel Zeit vergeht:
+
+    Tick jede Minute   ->  -115,2 Einheiten Cortisol pro Stunde
+    Tick jede Stunde   ->    -1,9 Einheiten Cortisol pro Stunde
+
+Ein Faktor 60 Unterschied, allein durch die Aufruf-Frequenz. In KIRAs Betrieb
+wurde bei jedem Reiz und jeder Prompt-Erzeugung getickt, also oft. Das
+rechnerische Gleichgewicht für Cortisol lag bei −124 — also am Boden.
+
+In der echten `hormones.json` steht denn auch:
+
+    cortisol      0.0      (Boden)
+    serotonin   140.2      (Decke 150)
+    oxytocin    210.7      (Ruhewert-Decke 250)
+
+Jeder Wert klebt an einer Grenze. Das System war vollständig gesättigt: kein
+Reiz konnte mehr etwas bewirken, weil die Grenzen alles auffingen.
+
+Die Lösung
+----------
+Kopplungen sind jetzt in Einheiten *pro Stunde* definiert und werden über die
+tatsächlich verstrichene Zeit integriert (Sub-Stepping mit fester Schrittweite).
+Damit ist das Verhalten frequenzunabhängig — und `equilibrium()` kann
+vorhersagen, wo es landet.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .profile import Profile
+
+# Schrittweite für die numerische Integration. 6 Minuten ist deutlich kleiner
+# als die schnellste Zeitkonstante im Standardprofil (Cortisol, 1/0.8 h = 75 min)
+# und damit stabil, bleibt aber billig.
+STEP_HOURS = 0.1
+
+# Ab dieser Lücke wird nicht mehr integriert, sondern direkt auf das
+# Gleichgewicht gesprungen — nach dem Fünffachen der langsamsten Zeitkonstante
+# ist der Unterschied ohnehin nicht mehr messbar.
+SETTLED_AFTER_HOURS = 30.0
+
+
+def coupling_flux(profile: Profile, hormones: dict[str, float]) -> dict[str, float]:
+    """Wirkung aller Kopplungen, in Einheiten pro Stunde."""
+    out = {name: 0.0 for name in profile.hormones}
+    for c in profile.couplings:
+        src = hormones.get(c.source)
+        if src is None or c.target not in out or not c.per:
+            continue
+        excess = src - c.threshold
+        if excess <= 0:
+            continue
+        out[c.target] += (excess / c.per) * c.gain
+    return out
+
+
+def fatigue_flux(profile: Profile, adenosine: float) -> dict[str, float]:
+    """Ermüdungsdruck auf Antrieb und Wachheit, in Einheiten pro Stunde."""
+    out: dict[str, float] = {}
+    excess = adenosine - profile.adenosine_threshold
+    if excess <= 0:
+        return out
+    drag = excess * profile.fatigue_gain
+    for name, share in profile.fatigue_targets.items():
+        if name in profile.hormones:
+            out[name] = -drag * share
+    return out
+
+
+def flux(profile: Profile, hormones: dict[str, float],
+         baselines: dict[str, float], adenosine: float = 0.0) -> dict[str, float]:
+    """Gesamte Änderungsrate je Botenstoff, in Einheiten pro Stunde.
+
+    Setzt sich zusammen aus dem Rückzug zum Ruhewert, den Kopplungen und dem
+    Ermüdungsdruck.
+    """
+    coup = coupling_flux(profile, hormones)
+    fat = fatigue_flux(profile, adenosine)
+    out: dict[str, float] = {}
+    for name, spec in profile.hormones.items():
+        pull = spec.decay * (baselines.get(name, spec.baseline) - hormones.get(name, spec.baseline))
+        out[name] = pull + coup.get(name, 0.0) + fat.get(name, 0.0)
+    return out
+
+
+def step(profile: Profile, hormones: dict[str, float],
+         baselines: dict[str, float], hours: float,
+         adenosine: float = 0.0) -> dict[str, float]:
+    """Integriert die Dynamik über `hours` und gibt den neuen Zustand zurück.
+
+    Frequenzunabhängig: hundert Aufrufe à 0,01 h ergeben dasselbe wie ein
+    Aufruf à 1 h (bis auf Integrationsfehler).
+    """
+    if hours <= 0:
+        return dict(hormones)
+
+    current = dict(hormones)
+    remaining = hours
+    while remaining > 1e-9:
+        dt = min(STEP_HOURS, remaining)
+        rates = flux(profile, current, baselines, adenosine)
+        for name, spec in profile.hormones.items():
+            value = current.get(name, spec.baseline) + rates[name] * dt
+            current[name] = max(spec.floor, min(spec.ceiling, value))
+        remaining -= dt
+    return current
+
+
+@dataclass
+class Equilibrium:
+    """Wo ein Profil ohne jeden Reiz landet."""
+    values: dict[str, float]
+    converged: bool
+    iterations: int
+    residual: float
+    at_bounds: list[str]
+
+    @property
+    def healthy(self) -> bool:
+        """Ein Gleichgewicht an einer Grenze ist keins — dort ist das System
+        gesättigt und reagiert nicht mehr auf Reize."""
+        return self.converged and not self.at_bounds
+
+
+def equilibrium(profile: Profile, baselines: dict[str, float] | None = None,
+                *, adenosine: float = 0.0, start: dict[str, float] | None = None,
+                max_hours: float = 720.0, tolerance: float = 1e-4) -> Equilibrium:
+    """Rechnet den Ruhezustand aus, statt ihn abzuwarten.
+
+    Integriert von den Ruhewerten aus vorwärts, bis sich nichts mehr ändert.
+    Weil dieselbe `step()`-Funktion verwendet wird wie im Betrieb, beschreibt
+    das Ergebnis garantiert die echte Dynamik — es ist kein Parallelmodell,
+    das auseinanderlaufen kann.
+
+    >>> from synapsen import DEFAULT_PROFILE
+    >>> eq = equilibrium(DEFAULT_PROFILE)
+    >>> eq.healthy
+    True
+    """
+    base = dict(baselines) if baselines else {
+        k: s.baseline for k, s in profile.hormones.items()}
+    current = dict(start) if start else dict(base)
+
+    if not current:
+        # Ein Profil ohne Botenstoffe hat ein triviales Gleichgewicht. Das ist
+        # ein Fall für die Prüfung, kein Grund für einen Abbruch.
+        return Equilibrium({}, converged=True, iterations=0,
+                           residual=0.0, at_bounds=[])
+
+    elapsed = 0.0
+    iterations = 0
+    residual = float("inf")
+
+    while elapsed < max_hours:
+        previous = dict(current)
+        current = step(profile, current, base, STEP_HOURS, adenosine)
+        iterations += 1
+        elapsed += STEP_HOURS
+        residual = max(abs(current[k] - previous[k]) for k in current)
+        if residual < tolerance:
+            break
+
+    at_bounds = []
+    for name, spec in profile.hormones.items():
+        v = current[name]
+        if v <= spec.floor + 1e-6:
+            at_bounds.append(f"{name}=Boden({spec.floor:g})")
+        elif v >= spec.ceiling - 1e-6:
+            at_bounds.append(f"{name}=Decke({spec.ceiling:g})")
+
+    return Equilibrium(
+        values=current,
+        converged=residual < tolerance,
+        iterations=iterations,
+        residual=residual,
+        at_bounds=at_bounds,
+    )
+
+
+@dataclass
+class Response:
+    """Wie das System auf einen einzelnen Reiz reagiert."""
+    hormone: str
+    amount: float
+    peak: dict[str, float]
+    half_life_hours: float
+    settles_to: dict[str, float]
+    side_effects: dict[str, float]
+
+
+def impulse_response(profile: Profile, hormone: str, amount: float = 50.0,
+                     *, horizon_hours: float = 48.0) -> Response:
+    """Ein Reiz, dann Ruhe — was passiert?
+
+    Zeigt Halbwertszeit und Nebenwirkungen über die Kopplungen. Nützlich, um
+    ein Profil zu justieren: „Ein Lob wirkt wie lange nach, und was zieht es
+    sonst noch mit?"
+    """
+    base = {k: s.baseline for k, s in profile.hormones.items()}
+    eq = equilibrium(profile, base)
+    rest = eq.values
+
+    current = dict(rest)
+    spec = profile.hormones[hormone]
+    current[hormone] = max(spec.floor, min(spec.ceiling, current[hormone] + amount))
+    peak = dict(current)
+
+    start_offset = current[hormone] - rest[hormone]
+    half_life = float("inf")
+    elapsed = 0.0
+
+    while elapsed < horizon_hours:
+        current = step(profile, current, base, STEP_HOURS)
+        elapsed += STEP_HOURS
+        if half_life == float("inf") and start_offset != 0:
+            offset = current[hormone] - rest[hormone]
+            if abs(offset) <= abs(start_offset) / 2:
+                half_life = elapsed
+
+    side = {k: round(current[k] - rest[k], 3) for k in current
+            if k != hormone and abs(current[k] - rest[k]) > 0.05}
+
+    return Response(
+        hormone=hormone, amount=amount, peak=peak,
+        half_life_hours=half_life, settles_to=current, side_effects=side,
+    )