seren-hippocampus 0.5.0__tar.gz

seren_hippocampus-0.5.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: seren-hippocampus
+Version: 0.5.0
+Summary: The sleep cycle for SerenMemory: drafts the docket, resubmits on critique, purges what was flagged. The consolidator, split out.
+Author: Chad Roesler
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/ChadRoesler/SerenHippocampus
+Keywords: seren,memory,consolidation,llm,fastapi
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.26
+Requires-Dist: seren-meninges<3,>=2.4.0
+Requires-Dist: seren-sinew<2,>=1.0.0
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0; extra == "mcp"
+Provides-Extra: corp
+Requires-Dist: truststore>=0.9; extra == "corp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.26; extra == "dev"
+Requires-Dist: seren-memory>=4.0.0; extra == "dev"

seren_hippocampus-0.5.0/SerenHippocampus.py

@@ -0,0 +1 @@
+

seren_hippocampus-0.5.0/SerenHippocampus.pyproj

@@ -0,0 +1,48 @@
+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
+  <PropertyGroup>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <SchemaVersion>2.0</SchemaVersion>
+    <ProjectGuid>eb418210-7b45-47a8-99e2-65c9d922580e</ProjectGuid>
+    <ProjectHome>.</ProjectHome>
+    <StartupFile>SerenHippocampus.py</StartupFile>
+    <SearchPath>
+    </SearchPath>
+    <WorkingDirectory>.</WorkingDirectory>
+    <OutputPath>.</OutputPath>
+    <Name>SerenHippocampus</Name>
+    <RootNamespace>SerenHippocampus</RootNamespace>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
+    <DebugSymbols>true</DebugSymbols>
+    <EnableUnmanagedDebugging>false</EnableUnmanagedDebugging>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
+    <DebugSymbols>true</DebugSymbols>
+    <EnableUnmanagedDebugging>false</EnableUnmanagedDebugging>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="SerenHippocampus.py" />
+    <Compile Include="seren_hippocampus\app.py" />
+    <Compile Include="seren_hippocampus\config.py" />
+    <Compile Include="seren_hippocampus\memory_client.py" />
+    <Compile Include="seren_hippocampus\sleep.py" />
+    <Compile Include="seren_hippocampus\_version.py" />
+    <Compile Include="seren_hippocampus\__init__.py" />
+    <Compile Include="seren_hippocampus\__main__.py" />
+    <Compile Include="tests\conftest.py" />
+    <Compile Include="tests\test_sleep.py" />
+  </ItemGroup>
+  <ItemGroup>
+    <Folder Include="seren_hippocampus\" />
+    <Folder Include="tests\" />
+  </ItemGroup>
+  <Import Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\Python Tools\Microsoft.PythonTools.targets" />
+  <!-- Uncomment the CoreCompile target to enable the Build command in
+       Visual Studio and specify your pre- and post-build commands in
+       the BeforeBuild and AfterBuild targets below. -->
+  <!--<Target Name="CoreCompile" />-->
+  <Target Name="BeforeBuild">
+  </Target>
+  <Target Name="AfterBuild">
+  </Target>
+</Project>

seren_hippocampus-0.5.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=68", "setuptools-scm>=8", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seren-hippocampus"
+dynamic = ["version"]
+description = "The sleep cycle for SerenMemory: drafts the docket, resubmits on critique, purges what was flagged. The consolidator, split out."
+license = "GPL-3.0-only"
+requires-python = ">=3.10"
+authors = [{ name = "Chad Roesler" }]
+readme = "README.md"
+keywords = ["seren", "memory", "consolidation", "llm", "fastapi"]
+
+# Deliberately no chromadb and no store: the hippocampus holds nothing. It
+# talks to SerenMemory over HTTP and to a small model over /v1/chat/completions.
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "pydantic>=2.5",
+    "pyyaml>=6.0",
+    "httpx>=0.26",
+    "seren-meninges>=2.4.0,<3",
+    "seren-sinew>=1.0.0,<2",
+]
+
+[project.optional-dependencies]
+mcp = [
+    # THE <2 CAP IS LOAD-BEARING: mcp 2.0.0 removed FastMCP (see SerenMemory).
+    "mcp>=1.0,<2",
+]
+corp = [
+    "truststore>=0.9",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "httpx>=0.26",
+    # The tests run the REAL SerenMemory app in-process behind an ASGI
+    # transport, so the contract between the two is exercised, not mocked.
+    # 4.0.0 is the first Memory with /drafts (the docket rename) and without
+    # the in-process consolidator: release Memory first, then this.
+    "seren-memory>=4.0.0",
+]
+
+[project.scripts]
+seren-hippocampus = "seren_hippocampus.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/ChadRoesler/SerenHippocampus"
+
+[tool.setuptools.packages.find]
+include = ["seren_hippocampus*"]
+
+# The viewer bricks ride inside the wheel; without this pip strips non-.py
+# files and GET /viewer renders an empty shell on an installed copy.
+[tool.setuptools.package-data]
+seren_hippocampus = ["viewer/ui/*.html", "viewer/ui/*.css", "viewer/ui/*.js"]
+
+[tool.setuptools_scm]
+# .git is one level above pyproject.toml (repo root)
+root = ".."
+version_scheme = "release-branch-semver"
+version_file = "seren_hippocampus/_version.py"
+tag_regex = "^v(?P<version>[0-9]+\\.[0-9]+\\.[0-9]+.*)$"
+fallback_version = "0.0.0.dev0"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

seren_hippocampus-0.5.0/seren-hippocampus.yaml.sample

@@ -0,0 +1,74 @@
+# SerenHippocampus config - copy to ~/seren-hippocampus/seren-hippocampus.yaml
+#
+# The hippocampus is SerenMemory's sleep cycle, split out. It holds no store:
+# it reads short-terms from Memory, writes drafts to Memory, and purges what
+# was flagged. Two loops: sleep (~20h) and tend (every few minutes, picks up
+# denied operations and resubmits them).
+
+server:
+  host: 127.0.0.1        # local-only. 0.0.0.0 = reachable on the LAN - set a bearer first
+  port: 7424             # the last slot in the brain band
+  # The bearer THIS service requires of callers (its /sleep, /tend, /status).
+  # bearer_token: ""                                # inline literal - escape hatch
+  # bearer_token_env: SEREN_HIPPOCAMPUS_TOKEN       # NAME of an env var (recommended)
+  # bearer_token_keyring: "seren-hippocampus/bearer"
+
+memory:
+  url: http://127.0.0.1:7420
+  # The bearer the hippocampus presents TO Memory. A Memory installed with
+  # --gen-token answers 401 to everything without one. Same three pointers.
+  # bearer_token_env: SEREN_MEMORY_TOKEN
+  # bearer_token_keyring: "seren-memory/bearer"
+  # bearer_token: ""
+  timeout_seconds: 30
+
+model:
+  # The small model - the Inside Out workers. OpenAI-compatible
+  # /v1/chat/completions; a 2B-4B model is plenty. Empty url = mechanical
+  # mode: clusters over the threshold become new cores by the longest entry,
+  # verbatim flags are honoured, and no attach / supersede is proposed,
+  # because those are judgement calls.
+  url: http://localhost:8090/v1
+  name: default
+  timeout_seconds: 120
+  max_tokens: 900
+  # Start the model only when a sleep or a redraft needs it, stop it after.
+  # For a Nano floor or a small card: the drafting model is not loaded all day.
+  lifecycle:
+    manage: false
+    # start: "C:\\llama\\llama-server.exe -m C:\\models\\qwen3-1.7b-q4.gguf --port 8090 -ngl 99"
+    # stop: ""                 # blank = stop the process the hippocampus started
+    # observatory_url: http://127.0.0.1:7777      # or: a service the node's Observatory manages
+    # observatory_service: seren-llama
+    # observatory_token_env: SEREN_OBSERVATORY_TOKEN
+    # health_url: ""           # blank = the model url without /v1, plus /health
+    ready_timeout_seconds: 240
+    keep_warm_seconds: 300     # stays up this long after its last call, then stops on the next tick
+    retry_after_seconds: 900   # after a failed start, wait this long before trying again
+
+sleep:
+  mode: thread             # thread = loops in-process; external = POST /sleep and /tend yourself
+  interval_seconds: 72000  # bedtime: ~20h after the last sleep (not 24, on purpose: it drifts through the day)
+  # at: "03:30"            # or a wall-clock time (local HH:MM) instead of the interval
+  warmup_seconds: 300      # a process that boots overdue sleeps this soon, not a whole interval later
+  gap_grace_intervals: 3   # a sleep after a gap this long (x interval) drafts but does not age out or sweep
+  # The brief is the gate. Every tend_interval the hippocampus checks Memory for an open brief and
+  # sleeps on it. Past bedtime (interval_seconds / at) with none, it counts the misses:
+  brief_request: true      # ...and every brief_check_misses of them asks the main model for one
+  brief_check_misses: 3    #    (a near-term intent in Memory + a brief_requested event; a nudge after that)
+  brief_pull: false        # headless (no main model): let the small model pull a brief from the fragments
+  tend_interval_seconds: 300
+  max_entries_per_run: 500
+  promote_min_evidence: 3  # short-terms a topic needs before it is proposed (hints, pins, verbatim override)
+  max_attempts: 3          # drafts per chain before the last one is submitted terminal
+  candidate_cores: 5       # existing cores shown to the model per cluster
+  state_path: ~/.seren-hippocampus/state.json
+
+notify:
+  # Where to say that something happened. Events are always kept on the
+  # service (GET /events and the viewer); a webhook gets each one POSTed as
+  # JSON - Lodestar, Symposium, or a messaging bridge sits at the other end.
+  # webhook_url: http://127.0.0.1:6361/hooks/hippocampus
+  # bearer_token_env: SEREN_HIPPOCAMPUS_WEBHOOK_TOKEN
+  events: [draft_submitted, sleep_failed, chain_ended, purged]
+  timeout_seconds: 10

seren_hippocampus-0.5.0/seren_hippocampus/__init__.py

@@ -0,0 +1,22 @@
+"""
+SerenHippocampus - the sleep cycle for SerenMemory, split out.
+
+The small model (the Inside Out workers) reads the short-terms the daily
+brief steered it to and writes a DOCKET of operations on long-term - new
+cores, evidence attached to existing cores, supersessions, verbatim keeps -
+which the main model reviews per operation through SerenMemory. Denied
+operations come back here with a critique; the tend loop redrafts and
+resubmits. Flagged memories are purged at sleep, with a tombstone.
+
+This service holds no store. Everything durable lives in SerenMemory; the
+hippocampus is judgement and scheduling, reachable over HTTP and (with the
+[mcp] extra) as MCP tools.
+"""
+from __future__ import annotations
+
+try:
+    from ._version import __version__
+except Exception:  # noqa: BLE001 - source checkout without a generated _version.py
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

seren_hippocampus-0.5.0/seren_hippocampus/__main__.py

@@ -0,0 +1,39 @@
+"""Entry point for `python -m seren_hippocampus` / the `seren-hippocampus` script."""
+from __future__ import annotations
+
+import argparse
+import sys
+
+import uvicorn
+from seren_meninges.exposure import enforce_server
+
+from .app import create_app
+from .config import ENV_PREFIX, load_config
+
+
+def _force_utf8_stdio() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+        except (AttributeError, ValueError):
+            pass
+
+
+def main() -> None:
+    _force_utf8_stdio()
+    parser = argparse.ArgumentParser(
+        prog="seren_hippocampus",
+        description="SerenHippocampus - the sleep cycle for SerenMemory.")
+    parser.add_argument("--config", "-c", default=None,
+                        help="Path to seren-hippocampus.yaml (default: $SEREN_HIPPOCAMPUS_CONFIG, "
+                             "then ~/seren-hippocampus/seren-hippocampus.yaml, then defaults).")
+    args = parser.parse_args()
+    cfg = load_config(args.config)
+    enforce_server(cfg.server, service="seren-hippocampus", env_prefix=ENV_PREFIX,
+                   log=lambda m: print(m, file=sys.stderr))
+    app = create_app(cfg)
+    uvicorn.run(app, host=cfg.server.host, port=cfg.server.port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

seren_hippocampus-0.5.0/seren_hippocampus/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
+
+__commit_id__ = commit_id = 'gd0647fc30'

seren_hippocampus-0.5.0/seren_hippocampus/app.py

@@ -0,0 +1,204 @@
+"""
+The service: a small FastAPI around the sleep.
+
+    GET  /            service info
+    GET  /health      liveness (+ whether Memory answers)
+    GET  /status      last sleep, last tend, mode, intervals
+    POST /sleep       run a sleep now (409 if one is running)
+    POST /tend        pick up denied operations now
+
+Bearer + request logging come from the family (Meninges, Sinew). In
+sleep.mode=thread the two loops run here; in external, something else
+POSTs on a schedule.
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+from contextlib import asynccontextmanager
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException, Request
+from seren_meninges.auth import bearer_auth_middleware
+from seren_meninges.updates import updates_payload
+from seren_sinew.request_log import RequestLoggingMiddleware
+
+from . import __version__
+from .config import HippocampusConfig, load_config
+from .memory_client import MemoryClient, MemoryError
+from .sleep import Busy, Hippocampus
+
+
+def create_app(config: Optional[HippocampusConfig] = None,
+               memory_client: Optional[MemoryClient] = None) -> FastAPI:
+    cfg = config or load_config()
+    bearer = cfg.server.resolve_bearer()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        app.state.config = cfg
+        mem = memory_client or MemoryClient(cfg.memory.url, bearer=cfg.memory.resolve_bearer(),
+                                            timeout=cfg.memory.timeout_seconds)
+        app.state.memory = mem
+        app.state.hippocampus = Hippocampus(cfg, mem)
+        # "is there a newer seren-hippocampus" - core in Meninges, always built.
+        from seren_meninges.updates import UpdateChecker
+        app.state.updates = UpdateChecker(
+            "seren-hippocampus",
+            enabled=cfg.updates.enabled,
+            index_url=cfg.updates.index_url,
+            ttl_seconds=cfg.updates.check_interval_hours * 3600,
+            allow_prerelease=cfg.updates.allow_prerelease,
+        )
+        tasks: list[asyncio.Task] = []
+        app.state.next_at: dict[str, Optional[float]] = {"sleep": None, "tend": None}
+        if cfg.sleep.mode == "thread":
+            h: Hippocampus = app.state.hippocampus
+
+            async def tick_loop():
+                interval = cfg.sleep.tend_interval_seconds
+                print(f"[seren-hippocampus] loop active: every {interval}s tend the open chains and check "
+                      "for a brief; bedtime " + (f"daily at {cfg.sleep.at}" if cfg.sleep.at.strip()
+                                                  else f"every {cfg.sleep.interval_seconds}s") + ")")
+                while True:
+                    app.state.next_at["tick"] = time.time() + interval
+                    await asyncio.sleep(interval)
+                    try:
+                        await asyncio.to_thread(h.tick)
+                    except Busy:
+                        pass
+                    except Exception as e:  # noqa: BLE001
+                        print(f"[seren-hippocampus] tick error: {e}")
+
+            tasks.append(asyncio.create_task(tick_loop()))
+        try:
+            yield
+        finally:
+            for t in tasks:
+                t.cancel()
+            try:
+                app.state.hippocampus.model.shutdown()
+            except Exception as e:  # noqa: BLE001
+                print(f"[seren-hippocampus] model shutdown: {e}")
+            if memory_client is None:
+                mem.close()
+
+    app = FastAPI(title="SerenHippocampus", version=__version__, lifespan=lifespan,
+                  description="The sleep cycle for SerenMemory: drafts what should be kept, resubmits on critique, purges what was flagged.")
+
+    @app.get("/")
+    async def root(request: Request):
+        return {"service": "seren-hippocampus", "version": __version__,
+                "memory": cfg.memory.url, "mode": cfg.sleep.mode,
+                "model": "configured" if cfg.model.url.strip() else "mechanical",
+                "updates": await updates_payload(
+                    getattr(request.app.state, "updates", None),
+                    distribution="seren-hippocampus",
+                    installed=__version__)}
+
+    @app.get("/health")
+    async def health(request: Request):
+        mem_ok = True
+        try:
+            await asyncio.to_thread(request.app.state.memory.health)
+        except MemoryError:
+            mem_ok = False
+        return {"ok": True, "memory_reachable": mem_ok}
+
+    @app.get("/status")
+    async def status(request: Request):
+        h: Hippocampus = request.app.state.hippocampus
+        nxt = getattr(request.app.state, "next_at", {}) or {}
+        return {"mode": cfg.sleep.mode, "interval_seconds": cfg.sleep.interval_seconds,
+                "tend_interval_seconds": cfg.sleep.tend_interval_seconds,
+                "model_configured": h.model_configured,
+                "model_lifecycle": h.model.snapshot(),
+                "next_sleep_at": None,                       # no timer: the brief is the gate
+                "next_tick_at": nxt.get("tick") if cfg.sleep.mode == "thread" else None,
+                "next_tend_at": nxt.get("tick") if cfg.sleep.mode == "thread" else None,
+                "bedtime_at": h.next_sleep_due(),
+                "brief_misses": int(h.state.get("brief_misses") or 0),
+                "last_check": h.state.get("last_check"),
+                "sleep_at": cfg.sleep.at or None,
+                "catch_up_next": h.is_catch_up(),
+                "sleep_due_at": h.next_sleep_due(),
+                "brief_wanted": h.brief_wanted() is not None,
+                "brief_requested_at": (h.brief_wanted() or {}).get("asked_at"),
+                "webhook": bool(cfg.notify.webhook_url),
+                "last_sleep": h.state.get("last_sleep"), "last_tend": h.state.get("last_tend")}
+
+    @app.post("/check")
+    async def check(request: Request):
+        """One check by hand: is there a brief? Sleeps on it if so."""
+        h: Hippocampus = request.app.state.hippocampus
+        try:
+            return await asyncio.to_thread(h.check)
+        except Busy as e:
+            raise HTTPException(409, str(e))
+
+    @app.get("/events")
+    async def events(request: Request):
+        """What happened, newest first: drafts submitted, sleeps failed,
+        chains ended, purges. The same events go to notify.webhook_url when
+        one is configured; each says whether that delivery worked."""
+        h: Hippocampus = request.app.state.hippocampus
+        rows = list(h.state.get("events") or [])
+        return {"count": len(rows), "webhook": bool(cfg.notify.webhook_url),
+                "entries": list(reversed(rows))}
+
+    @app.get("/history")
+    async def history(request: Request):
+        """The last sleeps and tends this service ran, newest first."""
+        h: Hippocampus = request.app.state.hippocampus
+        rows = list(h.state.get("history") or [])
+        return {"count": len(rows), "entries": list(reversed(rows))}
+
+    @app.get("/queue")
+    async def queue(request: Request):
+        """What is waiting for review, read from SerenMemory. The queue lives
+        there; this is a window onto it so the viewer can show it without a
+        second token. A Memory that does not answer is reported, not raised."""
+        mem: MemoryClient = request.app.state.memory
+        try:
+            rows = await asyncio.to_thread(mem.drafts, "pending", 50)
+        except MemoryError as e:
+            return {"count": 0, "drafts": [], "error": str(e)}
+        return {"count": len(rows), "drafts": rows}
+
+    @app.get("/viewer")
+    async def viewer():
+        """The window for whoever runs this and did not build it: did the sleep
+        run, what is waiting for review, and when it broke, what broke. Public
+        route; its API calls carry the token via the shell's 🔑 modal."""
+        from pathlib import Path
+        from fastapi.responses import HTMLResponse
+        from seren_meninges.viewer import render_from_dir
+        html = render_from_dir(
+            Path(__file__).resolve().parent / "viewer" / "ui",
+            title="SerenHippocampus",
+            brand="Seren<b>Hippocampus</b> · the sleep",
+            subtitle=f"v{__version__} · drafts what should be kept, resubmits on critique, purges what was flagged",
+            accent="#c9a0dc",
+        )
+        return HTMLResponse(html)
+
+    @app.post("/sleep")
+    async def sleep_now(request: Request):
+        h: Hippocampus = request.app.state.hippocampus
+        try:
+            return await asyncio.to_thread(h.sleep)
+        except Busy as e:
+            raise HTTPException(409, str(e))
+
+    @app.post("/tend")
+    async def tend_now(request: Request):
+        h: Hippocampus = request.app.state.hippocampus
+        try:
+            return await asyncio.to_thread(h.tend)
+        except Busy as e:
+            raise HTTPException(409, str(e))
+
+    app.add_middleware(bearer_auth_middleware(bearer))                                   # inner
+    app.add_middleware(RequestLoggingMiddleware, service_name="seren-hippocampus",     # outer
+                       env_prefix="SEREN_HIPPOCAMPUS")
+    return app