@simbimbo/brainstem 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.0.4 — 2026-03-22
+
+Release-prep alignment for the current intake foundation state.
+
+### Highlights
+- aligns packaging/runtime version metadata for the next release cut (`0.0.4` in `package.json`, `pyproject.toml`, and `brainstem.__version__`)
+- updates README/API-facing documentation to call out only implemented runtime and listener surfaces
+- keeps claims bounded to implemented behavior; no new feature claims
+
+### Notes
+- no runtime behavior or interface changes in this release-prep pass
+- no publish action performed
+
 ## 0.0.3 — 2026-03-22
 
 Intake Foundation follow-up release for **brAInstem**.

package/README.md

@@ -48,6 +48,31 @@ For a given tenant or environment, brAInstem should answer:
 - Have we seen this before?
 - What happened right before the last similar incident?
 
+## Current implemented runtime surface
+
+Current implementation is intentionally bounded:
+- FastAPI runtime at `brainstem.api:app`
+- Implemented API endpoints include:
+  - `POST /ingest/event`, `POST /ingest/batch`, `POST /replay/raw`
+  - `GET /interesting`, `GET /candidates`, `GET /signatures`, `GET /canonical_events`
+  - `GET /stats`, `GET /failures`, `GET /failures/{id}`
+  - `GET /raw_envelopes`, `GET /ingest/recent`, `GET /sources`, `GET /sources/status`
+  - `GET /runtime`, `GET /status`, `GET /healthz`
+- UDP syslog listener at `brainstem.listener`
+- source-driver intake for `syslog` and `file`
+- SQLite-backed persistence with default DB at `.brainstem-state/brainstem.sqlite3`
+- optional API token in `BRAINSTEM_API_TOKEN`
+
+Runtime config can also be inspected at `/runtime` and includes listener defaults (`syslog_host`, `syslog_port`, thresholds, limits).
+
+## Quick run path (API + listener + file/syslog intake)
+
+See the compact run surface in:
+
+- [`docs/README.md`](docs/README.md)
+
+It covers API startup, listener ingest, and file ingest end-to-end with only implemented entry points and current payload shapes.
+
 ## Relationship to ocmemog
 
 Shared DNA:

package/brainstem/__init__.py

@@ -1,3 +1,3 @@
 """brAInstem — operational memory for weak signals."""
 
-__version__ = "0.0.3"
+__version__ = "0.0.4"

package/brainstem/adapters.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Dict, Protocol, runtime_checkable
+
+from .models import RawInputEnvelope
+
+
+@runtime_checkable
+class RawInputAdapter(Protocol):
+    """Contract for source-specific envelope producers."""
+
+    source_type: str
+
+    def parse_raw_input(
+        self,
+        payload: Any,
+        *,
+        tenant_id: str,
+        source_path: str = "",
+    ) -> RawInputEnvelope:
+        """Build a RawInputEnvelope from source payload."""
+
+
+_ADAPTER_REGISTRY: Dict[str, RawInputAdapter] = {}
+
+
+def register_raw_input_adapter(adapter: RawInputAdapter) -> None:
+    """Register/replace an adapter for a source type."""
+
+    _ADAPTER_REGISTRY[adapter.source_type] = adapter
+
+
+def get_raw_input_adapter(source_type: str) -> RawInputAdapter:
+    """Return the adapter for `source_type`."""
+
+    try:
+        return _ADAPTER_REGISTRY[source_type]
+    except KeyError as exc:
+        raise ValueError(f"unsupported source_type: {source_type}") from exc
+
+
+def list_raw_input_source_types() -> list[str]:
+    """Return currently registered source types (inspectable list)."""
+
+    return sorted(_ADAPTER_REGISTRY.keys())
+
+
+def build_raw_input_envelope(
+    source_type: str,
+    payload: Any,
+    *,
+    tenant_id: str,
+    source_path: str = "",
+) -> RawInputEnvelope:
+    """Build a RawInputEnvelope using the source-type registry."""
+
+    adapter = get_raw_input_adapter(source_type)
+    return adapter.parse_raw_input(payload, tenant_id=tenant_id, source_path=source_path)
+
+
+@dataclass(frozen=True)
+class SyslogRawInputAdapter:
+    """Simple adapter for syslog-like line-oriented payloads."""
+
+    source_type: str = "syslog"
+
+    def parse_raw_input(self, payload: Any, *, tenant_id: str, source_path: str = "") -> RawInputEnvelope:
+        text = ("" if payload is None else str(payload)).rstrip("\n")
+        timestamp = datetime.utcnow().isoformat() + "Z"
+        host = ""
+        service = ""
+        message = text
+
+        parts = text.split()
+        if len(parts) >= 5:
+            host = parts[3]
+            rest = " ".join(parts[4:])
+            if ":" in rest:
+                svc, _, msg = rest.partition(":")
+                service = svc.strip()
+                message = msg.strip() or rest.strip()
+            else:
+                message = rest.strip()
+
+        return RawInputEnvelope(
+            tenant_id=tenant_id,
+            source_type=self.source_type,
+            timestamp=timestamp,
+            message_raw=message,
+            host=host,
+            service=service,
+            source_path=source_path,
+            metadata={"raw_line": text},
+        )
+
+
+@dataclass(frozen=True)
+class FileRawInputAdapter:
+    """Simple adapter for generic line-oriented log files."""
+
+    source_type: str = "file"
+
+    def parse_raw_input(self, payload: Any, *, tenant_id: str, source_path: str = "") -> RawInputEnvelope:
+        text = "" if payload is None else str(payload)
+        timestamp = datetime.utcnow().isoformat() + "Z"
+
+        return RawInputEnvelope(
+            tenant_id=tenant_id,
+            source_type=self.source_type,
+            timestamp=timestamp,
+            message_raw=text.rstrip("\n"),
+            source_path=source_path,
+            metadata={"raw_line": text},
+        )
+
+
+register_raw_input_adapter(SyslogRawInputAdapter())
+register_raw_input_adapter(FileRawInputAdapter())