seren-psycheion 1.0.0__tar.gz

seren_psycheion-1.0.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: seren-psycheion
+Version: 1.0.0
+Summary: The mind's workshop for a Seren body: watch what it senses and does, set how it behaves, make its faces.
+Author: Chad Roesler
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/ChadRoesler/SerenPsycheion
+Project-URL: Repository, https://github.com/ChadRoesler/SerenPsycheion
+Project-URL: Bug Tracker, https://github.com/ChadRoesler/SerenPsycheion/issues
+Keywords: seren,stackchan,robot,console,fastapi,viewer
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: seren-meninges<7,>=6.0.0
+Requires-Dist: seren-sinew<6,>=5.5.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# seren-psycheion
+
+The console and face workshop for a [SerenSoma](https://github.com/ChadRoesler/SerenSoma) body.
+
+```
+pip install seren-psycheion
+seren-psycheion              # http://127.0.0.1:7429/viewer
+seren-psycheion --describe   # one line of JSON, for installers
+```
+
+## Configure
+
+Copy [`seren-psycheion.yaml.sample`](seren-psycheion.yaml.sample) to
+`~/seren-psycheion/seren-psycheion.yaml` (or point `--config` or
+`$SEREN_PSYCHEION_CONFIG` at it):
+
+```yaml
+soma:
+  robot:
+    url: http://192.168.0.201:8080
+    token_file: ~/seren-soma/state/control_token
+  voice:
+    url: http://127.0.0.1:7480
+    token_file: ~/seren-soma/state/token
+```
+
+The body's tokens are pointers: `token_file`, `token_env` (an environment
+variable's name) or `token_keyring` (`service/username` in the OS keychain).
+`token:` inline is the escape hatch. Psycheion makes every call to the body
+itself; the page never sees these.
+
+## Exposure
+
+Psycheion binds to loopback. It can change a robot's lights and read what a
+hand did, so a wider bind with no `server.bearer_token_env` refuses to start
+(Meninges' `enforce_server`), and says how to fix it.
+
+## Routes
+
+| | |
+|---|---|
+| `GET /viewer` | The console. |
+| `GET /api/soma` | The robot's status and the voice server's status and settings, each with why it didn't answer if it didn't. |
+| `POST /api/soma/robot/settings` | `dimmer`, `volume` (0 to 100), `brightness` (5 to 100); saved on the robot. |
+| `POST /api/soma/voice/settings` | Any part of the voice server's settings (night, work hours, overwhelm). |
+| `GET /api/soma/touch?after=N` | The touch feed since event N, and overwhelm's progress. |
+
+Everything under `/api` needs the bearer when one is set.

seren_psycheion-1.0.0/README.md

@@ -0,0 +1,48 @@
+# seren-psycheion
+
+The console and face workshop for a [SerenSoma](https://github.com/ChadRoesler/SerenSoma) body.
+
+```
+pip install seren-psycheion
+seren-psycheion              # http://127.0.0.1:7429/viewer
+seren-psycheion --describe   # one line of JSON, for installers
+```
+
+## Configure
+
+Copy [`seren-psycheion.yaml.sample`](seren-psycheion.yaml.sample) to
+`~/seren-psycheion/seren-psycheion.yaml` (or point `--config` or
+`$SEREN_PSYCHEION_CONFIG` at it):
+
+```yaml
+soma:
+  robot:
+    url: http://192.168.0.201:8080
+    token_file: ~/seren-soma/state/control_token
+  voice:
+    url: http://127.0.0.1:7480
+    token_file: ~/seren-soma/state/token
+```
+
+The body's tokens are pointers: `token_file`, `token_env` (an environment
+variable's name) or `token_keyring` (`service/username` in the OS keychain).
+`token:` inline is the escape hatch. Psycheion makes every call to the body
+itself; the page never sees these.
+
+## Exposure
+
+Psycheion binds to loopback. It can change a robot's lights and read what a
+hand did, so a wider bind with no `server.bearer_token_env` refuses to start
+(Meninges' `enforce_server`), and says how to fix it.
+
+## Routes
+
+| | |
+|---|---|
+| `GET /viewer` | The console. |
+| `GET /api/soma` | The robot's status and the voice server's status and settings, each with why it didn't answer if it didn't. |
+| `POST /api/soma/robot/settings` | `dimmer`, `volume` (0 to 100), `brightness` (5 to 100); saved on the robot. |
+| `POST /api/soma/voice/settings` | Any part of the voice server's settings (night, work hours, overwhelm). |
+| `GET /api/soma/touch?after=N` | The touch feed since event N, and overwhelm's progress. |
+
+Everything under `/api` needs the bearer when one is set.

seren_psycheion-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68", "setuptools-scm>=8", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seren-psycheion"
+dynamic = ["version"]
+description = "The mind's workshop for a Seren body: watch what it senses and does, set how it behaves, make its faces."
+license = "AGPL-3.0-or-later"
+requires-python = ">=3.10"
+authors = [{ name = "Chad Roesler" }]
+readme = "README.md"
+keywords = ["seren", "stackchan", "robot", "console", "fastapi", "viewer"]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "pyyaml>=6.0",
+    "httpx>=0.27",
+    # the shell, auth, config, update checking
+    "seren-meninges>=6.0.0,<7",
+    # the request log, and seren_sinew.soma: the wire to the body, spelled once
+    "seren-sinew>=5.5.1,<6",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+seren-psycheion = "seren_psycheion.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/ChadRoesler/SerenPsycheion"
+Repository = "https://github.com/ChadRoesler/SerenPsycheion"
+"Bug Tracker" = "https://github.com/ChadRoesler/SerenPsycheion/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["seren_psycheion*"]
+
+# Without this the viewer's .html/.css/.js are absent from the wheel, and /viewer
+# 500s on an installed copy while working from the checkout.
+[tool.setuptools.package-data]
+seren_psycheion = ["viewer/ui/*.html", "viewer/ui/*.css", "viewer/ui/*.js"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools_scm]
+root = ".."
+version_scheme = "release-branch-semver"
+version_file = "seren_psycheion/_version.py"
+tag_regex = "^v(?P<version>[0-9]+\\.[0-9]+\\.[0-9]+.*)$"
+fallback_version = "0.0.0.dev0"

seren_psycheion-1.0.0/seren-psycheion.yaml.sample

@@ -0,0 +1,22 @@
+# ════════════════════════════════════════════════════════════════════════
+#  seren-psycheion.yaml - copy to ~/seren-psycheion/seren-psycheion.yaml
+# ════════════════════════════════════════════════════════════════════════
+
+server:
+  host: 127.0.0.1          # loopback. Wider needs a token, or Psycheion refuses to start.
+  port: 7429
+  # bearer_token_env: SEREN_PSYCHEION_TOKEN
+
+# The body. Tokens are POINTERS: token_env (an env var's name), token_keyring
+# ("service/username" in the OS keychain) or token_file (a file holding only
+# the token). The browser never sees these; Psycheion makes the calls itself.
+soma:
+  robot:                   # the robot's control API (firmware)
+    url: http://192.168.0.201:8080
+    # token_file: ~/seren-soma/state/control_token
+  voice:                   # the body's voice server
+    url: http://127.0.0.1:7480
+    # token_file: ~/seren-soma/state/token
+
+updates:
+  enabled: true

seren_psycheion-1.0.0/seren_psycheion/__init__.py

@@ -0,0 +1,23 @@
+"""seren_psycheion - the mind's workshop for a Seren body.
+
+SerenSoma is the body: a Stack-chan robot's firmware and the voice server that
+is its nervous system. Psycheion is where you watch it and shape it: what it
+senses and what it was read as, how bright and loud it is, when it's night,
+and (moving in from SerenSoma) the faces it wears.
+
+It talks to the body only through seren_sinew.soma, and it holds the body's
+tokens itself: the browser only ever holds Psycheion's own.
+"""
+from __future__ import annotations
+
+try:  # the setuptools-scm build artifact (gitignored); present in installed wheels
+    from ._version import version as __version__
+except Exception:  # source checkout without a build -> metadata, then dev fallback
+    try:
+        from importlib.metadata import version as _v
+
+        __version__ = _v("seren-psycheion")
+    except Exception:
+        __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

seren_psycheion-1.0.0/seren_psycheion/__main__.py

@@ -0,0 +1,53 @@
+"""Entry point for `python -m seren_psycheion` or the `seren-psycheion` script.
+
+--config / -c like the rest of the family; --describe answers before anything
+heavy is imported, so a broken install can still say its own name.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+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()
+    if "--describe" in sys.argv[1:]:
+        from ._describe import DESCRIBE
+        print(json.dumps(DESCRIBE))
+        raise SystemExit(0)
+
+    parser = argparse.ArgumentParser(prog="seren_psycheion",
+                                     description="SerenPsycheion - the mind's workshop for a Seren body.")
+    parser.add_argument("--config", "-c", default=None,
+                        help="Path to seren-psycheion.yaml (default: $SEREN_PSYCHEION_CONFIG, then "
+                             "~/seren-psycheion/seren-psycheion.yaml, then built-in defaults).")
+    args = parser.parse_args()
+
+    import uvicorn
+    from seren_meninges.exposure import enforce_server
+
+    from ._diag import diag
+    from .app import create_app
+    from .config import load_config
+
+    cfg = load_config(args.config)
+    # This page can switch a robot's lights and read what a hand did: an open bind
+    # with no token is refused here, with the ways out printed.
+    enforce_server(cfg.server, service="seren-psycheion", env_prefix="SEREN_PSYCHEION", log=diag)
+    app = create_app(cfg)
+    diag(f"[seren-psycheion] viewer at http://{cfg.host}:{cfg.port}/viewer")
+    diag(f"[seren-psycheion] the body: robot {cfg.soma.robot.url}, voice {cfg.soma.voice.url}")
+    uvicorn.run(app, host=cfg.host, port=cfg.port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

seren_psycheion-1.0.0/seren_psycheion/_describe.py

@@ -0,0 +1,40 @@
+"""SerenPsycheion's identity card. STDLIB ONLY - nothing imported, nothing read.
+
+What an INSTALLED Psycheion answers to `--describe`, so it can be compared with
+its Starwright card once that exists. Standard library only, for the reason
+every Seren card is: the moment you most want a thing to say its own name is
+when its install is broken.
+"""
+from __future__ import annotations
+
+NAME = "seren-psycheion"
+DISPLAY = "Seren Psycheion"
+DESCRIPTION = ("The mind's workshop for a Seren body: watch what it senses and "
+               "does, set how it behaves, and make its faces.")
+
+# 7429: between Lyceum (7428) and Probe (7430). The Soma voice server is 7480
+# and the robot's own control API 8080; neither is in the family band.
+PORT = 7429
+
+GROUP = "auxiliary"
+
+# Brain colored.
+ACCENT = "#f2aeb1"
+
+# Nothing to install first. A body is reached over its own HTTP APIs, so a
+# Psycheion with no body configured still serves its pages and says so.
+REQUIRES: tuple = ()
+EXTRAS: tuple = ()
+
+DESCRIBE = {
+    "schema_version": 1,
+    "name": NAME,
+    "display": DISPLAY,
+    "description": DESCRIPTION,
+    "port": PORT,
+    "group": GROUP,
+    "accent": ACCENT,
+    "package": "seren-psycheion",
+    "requires": list(REQUIRES),
+    "extras": list(EXTRAS),
+}

seren_psycheion-1.0.0/seren_psycheion/_diag.py

@@ -0,0 +1,18 @@
+"""Startup diagnostics that survive a nulled stdout (parity with SerenTheatre's
+and SerenMargin's _diag): `pythonw` nulls sys.stdout, and a write to a closed
+stream would end the run. Print, but never let printing be what kills it."""
+from __future__ import annotations
+
+import sys
+
+
+def diag(message: str) -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            if stream is None:
+                continue
+            stream.write(message + "\n")
+            stream.flush()
+            return
+        except Exception:  # noqa: BLE001 - a broken stream must not be fatal
+            continue

seren_psycheion-1.0.0/seren_psycheion/_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 = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)
+
+__commit_id__ = commit_id = 'gba6c1ee84'

seren_psycheion-1.0.0/seren_psycheion/app.py

@@ -0,0 +1,165 @@
+"""The FastAPI app: the viewer, and the body's API passed through with the body's own tokens.
+
+The browser holds Psycheion's bearer (Meninges' token modal) and nothing else.
+Psycheion holds the robot's control token and the voice server's bearer, makes
+every call to the body itself through seren_sinew.soma, and never hands either
+token back. A route here answers with what the body said, or 502 and where it
+couldn't reach, never the token or the body's raw error text.
+
+There is no camera route. A photo is taken only when the person in the room
+says so (see seren_sinew.soma).
+"""
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+from seren_meninges.auth import bearer_auth_middleware
+from seren_sinew.cluster.dtos import to_dict
+from seren_sinew.request_log import RequestLoggingMiddleware
+from seren_sinew.soma.client import SomaRobot, SomaVoice
+
+from . import __version__ as APP_VERSION
+from ._describe import ACCENT, NAME
+from ._diag import diag
+from .config import PsycheionConfig, load_config
+
+try:
+    from seren_meninges.viewer import render_from_dir
+except Exception:  # noqa: BLE001 - the API stands without the shell, and the viewer says so
+    render_from_dir = None  # type: ignore[assignment]
+
+_VIEWER_DIR = Path(__file__).parent / "viewer" / "ui"
+
+
+def _unreachable(what: str, url: str, exc: Exception) -> HTTPException:
+    """502, saying where and roughly why, never what the body said in full (it can echo headers)."""
+    if isinstance(exc, httpx.HTTPStatusError):
+        code = exc.response.status_code
+        why = "refused the token" if code == 401 else f"answered {code}"
+        return HTTPException(502, f"the {what} at {url} {why}")
+    return HTTPException(502, f"can't reach the {what} at {url}")
+
+
+def create_app(config: Optional[PsycheionConfig] = None, *,
+               robot_transport: Optional[httpx.AsyncBaseTransport] = None,
+               voice_transport: Optional[httpx.AsyncBaseTransport] = None) -> FastAPI:
+    cfg = config or load_config()
+    soma = cfg.soma
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        app.state.robot = SomaRobot(soma.robot.url, soma.robot.resolve(), transport=robot_transport)
+        app.state.voice = SomaVoice(soma.voice.url, soma.voice.resolve(), transport=voice_transport)
+        try:
+            yield
+        finally:
+            await app.state.robot.aclose()
+            await app.state.voice.aclose()
+
+    app = FastAPI(title="SerenPsycheion", version=APP_VERSION, lifespan=lifespan)
+    app.state.cfg = cfg
+
+    # Open on loopback with no token, like the rest of the family; enforce_server
+    # refuses a wider bind without one before this ever runs.
+    app.add_middleware(bearer_auth_middleware(cfg.server.resolve_bearer()))
+    app.add_middleware(RequestLoggingMiddleware, service_name=NAME, env_prefix="SEREN_PSYCHEION")
+
+    try:
+        from seren_meninges.updates import UpdateChecker
+        app.state.updates = UpdateChecker(NAME, enabled=cfg.updates.enabled, index_url=cfg.updates.index_url,
+                                          ttl_seconds=cfg.updates.check_interval_hours * 3600.0,
+                                          allow_prerelease=cfg.updates.allow_prerelease, fallback_version=APP_VERSION)
+    except Exception as exc:  # noqa: BLE001 - cosmetic, never fatal
+        app.state.updates = None
+        diag(f"[seren-psycheion] update checking unavailable ({exc})")
+
+    @app.get("/")
+    async def root(request: Request) -> dict:
+        """The family's info route: who this is, where the page is, and the updates block, which every
+        service carries with the same seven keys whatever state its checker is in (CI pins them)."""
+        try:
+            from seren_meninges.updates import updates_payload
+            updates = await updates_payload(getattr(request.app.state, "updates", None),
+                                            distribution=NAME, installed=APP_VERSION)
+        except Exception as exc:  # noqa: BLE001 - an info route never 500s over a cosmetic check
+            updates = {"status": "unavailable", "distribution": NAME, "installed": APP_VERSION, "latest": None,
+                       "update_available": False, "checked_at": None,
+                       "detail": f"update checking could not be constructed ({exc}): pip install -U seren-psycheion"}
+        return {"service": NAME, "version": APP_VERSION, "viewer": "/viewer", "updates": updates}
+
+    @app.get("/health")
+    async def health():
+        return {"ok": True, "service": NAME, "version": APP_VERSION}
+
+    @app.get("/api/soma")
+    async def soma_snapshot(request: Request) -> JSONResponse:
+        """Everything the console's front page shows, in one call. Each side
+        answers or says why it didn't; one being down doesn't hide the other."""
+        out: dict[str, Any] = {"robot": None, "robot_error": None, "voice": None, "voice_error": None,
+                               "voice_settings": None}
+        try:
+            out["robot"] = to_dict(await request.app.state.robot.status())
+        except (httpx.HTTPError, ValueError) as exc:
+            out["robot_error"] = _unreachable("robot", soma.robot.url, exc).detail
+        try:
+            out["voice"] = to_dict(await request.app.state.voice.status())
+            out["voice_settings"] = to_dict(await request.app.state.voice.settings())
+        except (httpx.HTTPError, ValueError) as exc:
+            out["voice_error"] = _unreachable("voice server", soma.voice.url, exc).detail
+        return JSONResponse(out, headers={"Cache-Control": "no-store"})
+
+    @app.post("/api/soma/robot/settings")
+    async def robot_settings(request: Request):
+        """{"dimmer": 0..100, "volume": 0..100, "brightness": 5..100}, any of them; saved on the robot."""
+        body = await request.json()
+        change: dict[str, int] = {}
+        for key, low in (("dimmer", 0), ("volume", 0), ("brightness", 5)):
+            if key in body:
+                v = body[key]
+                if not isinstance(v, int) or isinstance(v, bool) or not low <= v <= 100:
+                    raise HTTPException(400, f"{key} is a whole number from {low} to 100")
+                change[key] = v
+        try:
+            return to_dict(await request.app.state.robot.settings(**change))
+        except (httpx.HTTPError, ValueError) as exc:
+            raise _unreachable("robot", soma.robot.url, exc)
+
+    @app.post("/api/soma/voice/settings")
+    async def voice_settings(request: Request):
+        """Any part of the voice server's settings; it checks them, and its reason for a no comes back as ours."""
+        body = await request.json()
+        if not isinstance(body, dict):
+            raise HTTPException(400, "expected an object of settings")
+        try:
+            return to_dict(await request.app.state.voice.set_settings(body))
+        except httpx.HTTPStatusError as exc:
+            if exc.response.status_code == 400:
+                raise HTTPException(400, exc.response.text[:200])
+            raise _unreachable("voice server", soma.voice.url, exc)
+        except (httpx.HTTPError, ValueError) as exc:
+            raise _unreachable("voice server", soma.voice.url, exc)
+
+    @app.get("/api/soma/touch")
+    async def touch(request: Request, after: int = 0):
+        try:
+            return to_dict(await request.app.state.voice.touch(after=after))
+        except (httpx.HTTPError, ValueError) as exc:
+            raise _unreachable("voice server", soma.voice.url, exc)
+
+    @app.get("/viewer", include_in_schema=False)
+    async def viewer():
+        if render_from_dir is None:
+            return HTMLResponse("<h1>SerenPsycheion</h1><p>The SerenMeninges UI shell is not importable, "
+                                "so the viewer can't render. <code>pip install seren-meninges</code></p>",
+                                status_code=503)
+        # no-store: the whole viewer is inlined, and a cached copy would show last week's page
+        return HTMLResponse(headers={"Cache-Control": "no-store, must-revalidate"}, content=render_from_dir(
+            _VIEWER_DIR, title="SerenPsycheion", brand="Seren<b>Psycheion</b>",
+            subtitle=f"v{APP_VERSION} · the mind's workshop for a body", accent=ACCENT))
+
+    return app