@simbimbo/brainstem 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## 0.0.2 — 2026-03-22
+
+First fully aligned public foundation release of **brAInstem**.
+
+### Why 0.0.2
+- `0.0.1` was already published to npm earlier as the first placeholder/bootstrap package version
+- `0.0.2` is the first release where the local repo, documentation, canonical location, runtime foundation, and validation are being shipped together intentionally
+
+### What this release adds/locks in
+- canonical repo location at `~/brAInstem`
+- design governance, `v0.0.1` scope, adapter contract, and attention scoring docs
+- explicit `RawInputEnvelope` and `CanonicalEvent` foundation models
+- canonicalization path for current syslog-like ingestion
+- minimal FastAPI runtime with:
+  - `POST /ingest/event`
+  - `POST /ingest/batch`
+  - `GET /interesting`
+  - `GET /healthz`
+- focused API and canonicalization tests
+
+### Validation
+- local test suite passed (`19 passed`)
+- local end-to-end demo path executed successfully against sample syslog input
+- minimal FastAPI runtime and canonicalization tests passed locally
+
+## 0.0.1 — 2026-03-22
+
+First public prototype release of **brAInstem**.
+
+### What this release is
+- an experimental, self-contained operational memory prototype for weak signals
+- a proof that early event sources can feed one normalized internal stream
+- a first cut at attention-oriented weak-signal discovery and operator-facing interesting items
+
+### Included in 0.0.1
+- syslog-like ingestion path
+- event fingerprinting and recurrence candidate generation
+- interpretable scoring with operator-facing decision/attention output
+- SQLite persistence for events, signatures, and candidates
+- local demo path for end-to-end validation
+- initial LogicMonitor connector model/mapping work
+- design governance docs covering:
+  - product thesis
+  - `v0.0.1` scope
+  - adapter/raw-envelope/canonical-event contract
+  - attention scoring model
+
+### Not claimed in 0.0.1
+- full universal intake apparatus
+- production-grade always-on ingestion runtime
+- mature multi-tenant MSP platform behavior
+- complete discovery apparatus breadth (burst/spread/self-heal/precursor at full maturity)
+- polished operator UI
+
+### Validation
+- local test suite passed (`19 passed`)
+- local end-to-end demo path executed successfully against sample syslog input
+- minimal FastAPI runtime and canonicalization tests passed locally
+
+### Release framing
+This release puts a truthful first stake in the ground for brAInstem as an operational memory runtime focused on weak signals and operator attention.

package/README.md

@@ -1,5 +1,101 @@
-# @simbimbo/brainstem
+# brAInstem
 
-brAInstem is an operational memory engine for weak signals.
+**Operational memory for weak signals**
 
-This package name is being reserved for the upcoming brAInstem project.
+brAInstem is an always-on operational memory runtime for weak signals. Instead of treating memory as conversational context, brAInstem treats logs and operational events as raw operational experience that can be normalized into one canonical stream, assigned attention, clustered into patterns, and promoted into durable operational knowledge.
+
+## One-line pitch
+
+brAInstem helps MSPs and lean ops teams detect recurring, self-resolving, and quietly escalating issues before they become major incidents.
+
+## The problem
+
+Most operational pain never becomes a classic threshold alert.
+
+It shows up as:
+- recurring low-grade warnings
+- brief self-healing failures
+- cross-system weak signals
+- near-misses that humans forget because there is too much noise
+
+Traditional monitoring catches hard failures. brAInstem is designed to catch patterns that matter to humans before they become obvious outages.
+
+## Core idea
+
+Logs and events should not only be stored and searched. They should be:
+1. ingested into a provenance-preserving raw envelope
+2. normalized into one canonical event stream
+3. assigned and updated with **attention** over time
+4. compressed so most inconsequential noise is handled cheaply
+5. promoted into operator-facing weak-signal outputs only when enough attention is earned
+6. promoted later into incident memory, lessons, and runbook hints when justified
+7. retrieved again when similar patterns recur
+
+## Primary users
+
+- MSP owners
+- MSP technicians
+- NOC teams
+- SRE / infrastructure operators
+- small security / ops teams dealing with alert fatigue and log blindness
+
+## MVP promise
+
+For a given tenant or environment, brAInstem should answer:
+- What happened today that mattered but never alerted?
+- What self-resolving issues are recurring?
+- What patterns are likely to become tickets later?
+- Have we seen this before?
+- What happened right before the last similar incident?
+
+## Relationship to ocmemog
+
+Shared DNA:
+- ingest -> candidate -> promotion pipeline
+- compact retrieval
+- provenance and explainability
+- memory scoring and recurrence awareness
+
+Different center of gravity:
+- ocmemog = assistant memory and continuity
+- brAInstem = operational event intelligence and weak-signal detection
+
+## Initial scope
+
+The long-term product direction is an always-on self-contained runtime with a robust input apparatus, a discovery apparatus, and operator-facing outputs.
+
+For the first public prototype line, start with:
+- a narrow but real ingestion story
+- a canonical event stream
+- attention-oriented weak-signal discovery
+- operator-facing interesting items / digest output
+- syslog-like events and LogicMonitor-shaped events as early proof sources
+
+Delay until later:
+- broad universal connector coverage
+- mature syslog appliance behavior across every input mode
+- full SIEM behavior
+- broad compliance workflows
+- generic observability replacement
+- "chat with all your logs" as the primary story
+
+## Proposed docs
+
+- `docs/design-governance.md` — canonical product/design guardrails
+- `docs/v0.0.1.md` — first release scope and acceptance criteria
+- `docs/adapters.md` — intake, raw envelope, and canonical event contract
+- `docs/vision.md`
+- `docs/architecture.md`
+- `docs/scoring.md` — attention scoring and routing model
+- `docs/roadmap.md`
+
+## Design governance
+
+Before expanding scope, adding connectors, or making architecture claims, read:
+- `docs/design-governance.md`
+
+That document is the canonical governor for:
+- what brAInstem is and is not
+- how attention should work
+- what belongs in `0.0.1`
+- how the input apparatus, discovery apparatus, and operator outputs should evolve

package/brainstem/__init__.py

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

package/brainstem/api.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+import json
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from .ingest import canonicalize_raw_input_envelopes
+from .interesting import interesting_items
+from .models import Candidate, RawInputEnvelope
+from .recurrence import build_recurrence_candidates
+from .storage import init_db, list_candidates, store_candidates, store_events, store_signatures
+from .ingest import signatures_for_events
+
+
+app = FastAPI(title="brAInstem Runtime")
+
+
+class RawEnvelopeRequest(BaseModel):
+    tenant_id: str
+    source_type: str
+    message_raw: str
+    timestamp: Optional[str] = None
+    host: str = ""
+    service: str = ""
+    severity: str = "info"
+    asset_id: str = ""
+    source_path: str = ""
+    facility: str = ""
+    structured_fields: Dict[str, Any] = Field(default_factory=dict)
+    correlation_keys: Dict[str, Any] = Field(default_factory=dict)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class IngestEventRequest(RawEnvelopeRequest):
+    pass
+
+
+class IngestBatchRequest(BaseModel):
+    events: List[RawEnvelopeRequest]
+    threshold: int = Field(default=2, ge=1)
+    db_path: Optional[str] = None
+
+
+def _raw_envelope_from_request(payload: RawEnvelopeRequest) -> RawInputEnvelope:
+    return RawInputEnvelope(
+        tenant_id=payload.tenant_id,
+        source_type=payload.source_type,
+        timestamp=payload.timestamp or datetime.utcnow().isoformat() + "Z",
+        message_raw=payload.message_raw,
+        host=payload.host,
+        service=payload.service,
+        severity=payload.severity,
+        asset_id=payload.asset_id,
+        source_path=payload.source_path,
+        facility=payload.facility,
+        structured_fields=dict(payload.structured_fields),
+        correlation_keys=dict(payload.correlation_keys),
+        metadata=dict(payload.metadata),
+    )
+
+
+def _candidate_from_row(row) -> Candidate:
+    return Candidate(
+        candidate_type=row["candidate_type"],
+        title=row["title"],
+        summary=row["summary"],
+        score_total=float(row["score_total"]),
+        score_breakdown=json.loads(row["score_breakdown_json"] or "{}"),
+        decision_band=row["decision_band"],
+        source_signature_ids=json.loads(row["source_signature_ids_json"] or "[]"),
+        source_event_ids=json.loads(row["source_event_ids_json"] or "[]"),
+        confidence=float(row["confidence"]),
+        metadata=json.loads(row["metadata_json"] or "{}"),
+    )
+
+
+def _run_ingest_batch(raw_events: List[RawInputEnvelope], *, threshold: int, db_path: Optional[str]) -> Dict[str, Any]:
+    events = canonicalize_raw_input_envelopes(raw_events)
+    if not events:
+        return {"ok": True, "event_count": 0, "signature_count": 0, "candidate_count": 0, "interesting_items": []}
+
+    signatures = signatures_for_events(events)
+    candidates = build_recurrence_candidates(events, signatures, threshold=threshold)
+    if db_path:
+        init_db(db_path)
+        store_events(events, db_path)
+        store_signatures(signatures, db_path)
+        store_candidates(candidates, db_path)
+
+    return {
+        "ok": True,
+        "tenant_id": events[0].tenant_id if events else "",
+        "event_count": len(events),
+        "signature_count": len({sig.signature_key for sig in signatures}),
+        "candidate_count": len(candidates),
+        "interesting_items": interesting_items(candidates, limit=max(1, 5)),
+    }
+
+
+@app.post("/ingest/event")
+def ingest_event(payload: IngestEventRequest, threshold: int = 2, db_path: Optional[str] = None) -> Dict[str, Any]:
+    if threshold < 1:
+        raise HTTPException(status_code=422, detail="threshold must be >= 1")
+    return _run_ingest_batch([_raw_envelope_from_request(payload)], threshold=threshold, db_path=db_path)
+
+
+@app.post("/ingest/batch")
+def ingest_batch(payload: IngestBatchRequest) -> Dict[str, Any]:
+    raw_events = [_raw_envelope_from_request(event) for event in payload.events]
+    return _run_ingest_batch(raw_events, threshold=payload.threshold, db_path=payload.db_path)
+
+
+@app.get("/interesting")
+def get_interesting(
+    limit: int = Query(default=5, ge=1),
+    db_path: Optional[str] = None,
+) -> Dict[str, Any]:
+    if not db_path:
+        return {"ok": True, "items": []}
+    rows = list_candidates(db_path=db_path, limit=limit)
+    candidates = [_candidate_from_row(row) for row in rows]
+    return {"ok": True, "items": interesting_items(candidates, limit=limit)}
+
+
+@app.get("/healthz")
+def healthz() -> Dict[str, str]:
+    return JSONResponse(content={"ok": True, "status": "ok"})

package/brainstem/connectors/__init__.py

@@ -0,0 +1 @@
+"""Connector entry points for brAInstem."""

package/brainstem/connectors/logicmonitor.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from .types import ConnectorEvent
+
+
+def map_logicmonitor_event(payload: dict, *, tenant_id: str) -> ConnectorEvent:
+    metadata = payload.get("metadata") or {}
+    host = payload.get("host") or payload.get("resource_name") or ""
+    service = payload.get("service") or metadata.get("datasource") or "logicmonitor"
+    return ConnectorEvent(
+        tenant_id=tenant_id,
+        source_type="logicmonitor",
+        host=str(host),
+        service=str(service),
+        severity=str(payload.get("severity") or "info"),
+        timestamp=str(payload.get("timestamp") or ""),
+        message_raw=str(payload.get("message_raw") or payload.get("message") or ""),
+        metadata={
+            "alert_id": payload.get("alert_id"),
+            "resource_id": payload.get("resource_id"),
+            "datasource": metadata.get("datasource"),
+            "instance_name": metadata.get("instance_name"),
+            "acknowledged": metadata.get("acknowledged"),
+            "cleared_at": metadata.get("cleared_at"),
+        },
+    )

package/brainstem/connectors/types.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+
+@dataclass
+class ConnectorEvent:
+    tenant_id: str
+    source_type: str
+    host: str
+    service: str
+    severity: str
+    timestamp: str
+    message_raw: str
+    metadata: Dict[str, Any] = field(default_factory=dict)

package/brainstem/demo.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict
+from typing import Any, Dict
+
+from .ingest import ingest_syslog_file, signatures_for_events
+from .instrumentation import emit, span
+from .interesting import interesting_items
+from .recurrence import build_recurrence_candidates, digest_items
+from .storage import init_db, store_candidates, store_events, store_signatures
+
+
+def run_syslog_demo(path: str, tenant_id: str, threshold: int = 2, db_path: str | None = None) -> Dict[str, Any]:
+    with span("syslog_demo", path=path, tenant_id=tenant_id, threshold=threshold):
+        init_db(db_path)
+        events = ingest_syslog_file(path, tenant_id=tenant_id)
+        emit("syslog_demo_events_loaded", count=len(events), path=path)
+        signatures = signatures_for_events(events)
+        emit("syslog_demo_signatures_built", count=len(signatures))
+        candidates = build_recurrence_candidates(events, signatures, threshold=threshold)
+        store_events(events, db_path)
+        store_signatures(signatures, db_path)
+        store_candidates(candidates, db_path)
+        digest = digest_items(candidates)
+        items = interesting_items(candidates, limit=5)
+        payload = {
+            "ok": True,
+            "tenant_id": tenant_id,
+            "event_count": len(events),
+            "signature_count": len({sig.signature_key for sig in signatures}),
+            "candidate_count": len(candidates),
+            "canonical_stream": {
+                "event_count": len(events),
+                "signature_count": len({sig.signature_key for sig in signatures}),
+            },
+            "digest": digest,
+            "interesting_items": items,
+            "top_candidate": asdict(candidates[0]) if candidates else None,
+        }
+        emit(
+            "syslog_demo_summary",
+            event_count=payload["event_count"],
+            signature_count=payload["signature_count"],
+            candidate_count=payload["candidate_count"],
+        )
+        return payload
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run the brAInstem syslog weak-signal demo.")
+    parser.add_argument("path", help="Path to a syslog-like input file")
+    parser.add_argument("--tenant", default="demo-tenant", help="Tenant/environment identifier")
+    parser.add_argument("--threshold", type=int, default=2, help="Minimum recurrence count for candidate emission")
+    parser.add_argument("--db-path", default=None, help="Optional SQLite path for persistent state")
+    args = parser.parse_args()
+    payload = run_syslog_demo(args.path, tenant_id=args.tenant, threshold=args.threshold, db_path=args.db_path)
+    print(json.dumps(payload, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/brainstem/fingerprint.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import re
+
+from .models import Event, Signature
+
+
+_WHITESPACE_RE = re.compile(r"\s+")
+_IPV4_RE = re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")
+_NUMBER_RE = re.compile(r"\b\d+\b")
+
+
+def normalize_message(message: str) -> str:
+    text = (message or "").strip().lower()
+    text = _IPV4_RE.sub("<ip>", text)
+    text = _NUMBER_RE.sub("<n>", text)
+    text = _WHITESPACE_RE.sub(" ", text)
+    return text
+
+
+def event_family_for(event: Event) -> str:
+    message_normalized = getattr(event, "message_normalized", None) or normalize_message(event.message_raw)
+    base = message_normalized
+    if "fail" in base or "error" in base:
+        return "failure"
+    if "restart" in base or "stopped" in base or "started" in base:
+        return "service_lifecycle"
+    if "auth" in base or "login" in base:
+        return "auth"
+    return "generic"
+
+
+def fingerprint_event(event: Event) -> Signature:
+    normalized = getattr(event, "signature_input", None) or getattr(event, "message_normalized", None) or normalize_message(event.message_raw)
+    family = event_family_for(event)
+    service = (event.service or "").strip().lower()
+    host = (event.host or "").strip().lower()
+    signature_key = f"{family}|{service}|{normalized}"
+    return Signature(
+        signature_key=signature_key,
+        event_family=family,
+        normalized_pattern=normalized,
+        service=service or host,
+    )

package/brainstem/ingest.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from datetime import datetime
+from pathlib import Path
+from typing import Iterable, List
+
+from .fingerprint import fingerprint_event, normalize_message
+from .models import CanonicalEvent, Event, RawInputEnvelope, Signature
+
+
+def parse_syslog_line(line: str, *, tenant_id: str, source_path: str = "") -> CanonicalEvent:
+    return canonicalize_raw_input_envelope(
+        parse_syslog_envelope(line, tenant_id=tenant_id, source_path=source_path)
+    )
+
+
+def parse_syslog_envelope(line: str, *, tenant_id: str, source_path: str = "") -> RawInputEnvelope:
+    text = (line or "").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="syslog",
+        timestamp=timestamp,
+        message_raw=message,
+        host=host,
+        service=service,
+        source_path=source_path,
+        metadata={"raw_line": text},
+    )
+
+
+def parse_syslog_envelopes(lines: Iterable[str], *, tenant_id: str, source_path: str = "") -> List[RawInputEnvelope]:
+    return [parse_syslog_envelope(line, tenant_id=tenant_id, source_path=source_path) for line in lines if str(line).strip()]
+
+
+def canonicalize_raw_input_envelope(raw: RawInputEnvelope) -> CanonicalEvent:
+    message_normalized = normalize_message(raw.message_raw)
+    metadata = dict(raw.metadata or {})
+    metadata.setdefault("canonicalization_source", raw.source_type)
+    metadata["raw_input_seen"] = True
+    return CanonicalEvent(
+        tenant_id=raw.tenant_id,
+        source_type=raw.source_type,
+        timestamp=raw.timestamp,
+        host=raw.host,
+        service=raw.service,
+        severity=raw.severity,
+        asset_id=raw.asset_id,
+        source_path=raw.source_path,
+        facility=raw.facility,
+        message_raw=raw.message_raw,
+        structured_fields=dict(raw.structured_fields),
+        correlation_keys=dict(raw.correlation_keys),
+        message_normalized=message_normalized,
+        signature_input=message_normalized,
+        ingest_metadata={
+            "canonicalized_at": datetime.utcnow().isoformat() + "Z",
+            "source_timestamp": raw.timestamp,
+            **metadata,
+        },
+    )
+
+
+def canonicalize_raw_input_envelopes(events: Iterable[RawInputEnvelope]) -> List[CanonicalEvent]:
+    return [canonicalize_raw_input_envelope(raw_event) for raw_event in events]
+
+
+def ingest_syslog_lines(lines: Iterable[str], *, tenant_id: str, source_path: str = "") -> List[CanonicalEvent]:
+    return canonicalize_raw_input_envelopes(
+        parse_syslog_envelopes(lines, tenant_id=tenant_id, source_path=source_path),
+    )
+
+
+def ingest_syslog_file(path: str, *, tenant_id: str) -> List[Event]:
+    file_path = Path(path)
+    lines = file_path.read_text(encoding="utf-8", errors="ignore").splitlines()
+    return ingest_syslog_lines(lines, tenant_id=tenant_id, source_path=str(file_path))
+
+
+def signatures_for_events(events: Iterable[Event]) -> List[Signature]:
+    return [fingerprint_event(event) for event in events]
+
+
+def events_as_dicts(events: Iterable[Event]) -> List[dict]:
+    return [asdict(event) for event in events]

package/brainstem/instrumentation.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import json
+import sys
+import time
+from contextlib import contextmanager
+from typing import Any, Dict, Iterator
+
+
+def emit(event: str, **fields: Any) -> None:
+    payload: Dict[str, Any] = {
+        "event": event,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        **fields,
+    }
+    print(json.dumps(payload, ensure_ascii=False), file=sys.stderr)
+
+
+@contextmanager
+def span(event: str, **fields: Any) -> Iterator[None]:
+    started = time.perf_counter()
+    emit(f"{event}_start", **fields)
+    try:
+        yield
+    except Exception as exc:
+        emit(
+            f"{event}_failed",
+            error_type=type(exc).__name__,
+            error=str(exc),
+            elapsed_ms=round((time.perf_counter() - started) * 1000, 3),
+            **fields,
+        )
+        raise
+    emit(
+        f"{event}_complete",
+        elapsed_ms=round((time.perf_counter() - started) * 1000, 3),
+        **fields,
+    )

package/brainstem/interesting.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import Iterable, List, Dict, Any
+
+from .models import Candidate
+
+
+def _attention_band(decision_band: str) -> str:
+    mapping = {
+        "ignore": "ignore_fast",
+        "watch": "background",
+        "review": "watch",
+        "urgent_human_review": "investigate",
+        "promote_to_incident_memory": "promote",
+    }
+    return mapping.get(decision_band, "watch")
+
+
+def _why_it_matters(candidate: Candidate) -> str:
+    count = int((candidate.metadata or {}).get("count") or 0)
+    service = str((candidate.metadata or {}).get("service") or "").strip()
+    family = candidate.candidate_type.replace("_", " ")
+    pieces = []
+    if count:
+        pieces.append(f"observed {count} times")
+    if service:
+        pieces.append(f"around {service}")
+    band = _attention_band(candidate.decision_band)
+    if band == "promote":
+        level = "has earned high operator attention"
+    elif band == "investigate":
+        level = "has earned active operator attention"
+    elif band == "watch":
+        level = "has earned watch-level attention"
+    elif band == "background":
+        level = "is worth keeping in the background"
+    else:
+        level = "is low-attention noise"
+    detail = ", ".join(pieces) if pieces else family
+    return f"{detail}; {level}."
+
+
+def interesting_items(candidates: Iterable[Candidate], *, limit: int = 5) -> List[Dict[str, Any]]:
+    ordered = sorted(candidates, key=lambda c: (c.score_total, c.confidence), reverse=True)
+    items: List[Dict[str, Any]] = []
+    for candidate in ordered[: max(limit, 1)]:
+        attention_band = _attention_band(candidate.decision_band)
+        items.append(
+            {
+                "title": candidate.title,
+                "summary": candidate.summary,
+                "decision_band": candidate.decision_band,
+                "attention_band": attention_band,
+                "attention_score": candidate.score_total,
+                "score_total": candidate.score_total,
+                "confidence": candidate.confidence,
+                "why_it_matters": _why_it_matters(candidate),
+                "signals": dict(candidate.score_breakdown),
+                "metadata": dict(candidate.metadata),
+            }
+        )
+    return items