@simbimbo/brainstem 0.0.1 → 0.0.3

package/docs/v0.0.1.md

@@ -0,0 +1,277 @@
+# brAInstem v0.0.1 Scope
+
+_Status: governing release-scope doc for the first public prototype release_
+
+## Purpose
+
+This document defines the **honest scope** of brAInstem `v0.0.1`.
+
+Its job is to prevent the first release from becoming one of these failure modes:
+- a vague architecture dump with no usable artifact
+- a fake platform release that overclaims universal capability
+- a connector chase that ignores the core product thesis
+- a technically interesting prototype that still cannot tell an operator what matters
+
+If a feature or claim is not consistent with this document, it does not belong in `v0.0.1`.
+
+---
+
+## 1. What `v0.0.1` is
+
+brAInstem `v0.0.1` is an **experimental self-contained operational memory prototype**.
+
+It should prove that brAInstem can:
+1. ingest early source types into a shared internal pipeline
+2. normalize those inputs into a canonical event stream
+3. assign and describe **attention**
+4. detect recurring weak signals in a meaningful way
+5. emit concise operator-facing output that says what deserves attention
+
+This is a real release, but it is a **first stake in the ground**, not a mature operational platform.
+
+---
+
+## 2. Release thesis
+
+The thesis of `v0.0.1` is:
+
+> A self-contained local runtime can ingest operational events, normalize them into one canonical stream, assign attention, and surface weak recurring patterns in a form that a human operator can understand.
+
+If `v0.0.1` proves that cleanly, it succeeds.
+
+---
+
+## 3. Buyer/user framing for `v0.0.1`
+
+`v0.0.1` is not yet a polished commercial product release.
+It is a technically honest prototype release aimed at:
+- builders
+- early evaluators
+- operators who want to understand the product direction
+- future pilot conversations with MSP / lean ops buyers
+
+It should still be written and structured as if it is the beginning of a real product line.
+
+---
+
+## 4. In-scope for `v0.0.1`
+
+### 4.1 Canonical model
+The release must define a clear canonical event concept.
+
+At minimum, the docs and code should consistently support the idea that:
+- different source types feed one shared normalized internal event stream
+- downstream scoring/discovery logic is driven by that normalized stream
+
+### 4.2 Early ingestion path(s)
+`v0.0.1` must support at least a narrow but real ingestion story.
+
+That may be:
+- syslog-like local file/log ingestion
+- structured event ingestion through an early adapter path
+- demo or sample-driven ingestion that proves the pipeline end-to-end
+
+It does **not** need to be broad.
+It does need to be real.
+
+### 4.3 Attention-oriented language and behavior
+The release should establish **attention** as a core concept.
+
+That means:
+- docs use the term clearly
+- outputs and scoring concepts reflect attention, not only raw significance
+- weak signals are framed as events/signatures that can earn more attention over time
+
+### 4.4 Weak-signal recurrence detection
+The release must show at least one meaningful weak-signal detection path.
+
+For `v0.0.1`, recurrence is sufficient as the main proven candidate class.
+
+### 4.5 Operator-facing output
+The release must produce at least one operator-meaningful output form.
+
+Examples:
+- interesting items
+- weak-signal digest
+- concise candidate summary
+
+The output must aim to answer:
+- what is happening?
+- why should I care?
+
+### 4.6 Self-contained local runtime story
+The release should be runnable locally without requiring a large external services footprint.
+
+### 4.7 Persistence
+The release should retain enough state locally to support a meaningful prototype memory story.
+SQLite-backed storage is acceptable and desirable.
+
+### 4.8 Demoability
+`v0.0.1` must be demoable end-to-end without hand-wavy claims.
+
+A builder should be able to run the prototype and see:
+- ingest
+- normalization
+- recurrence/attention interpretation
+- operator-facing output
+
+---
+
+## 5. Explicitly out of scope for `v0.0.1`
+
+The following are **not required** for `v0.0.1` and should not be overclaimed.
+
+### 5.1 Full universal intake apparatus
+Not required yet:
+- broad connector zoo
+- mature syslog appliance behavior
+- every file/API/stream type
+- complete transport/runtime hardening across all sources
+
+### 5.2 Production-grade always-on infrastructure
+Not required yet:
+- fully hardened long-running daemon behavior
+- high-scale backpressure handling across all inputs
+- complete queue/spool runtime guarantees
+- broad operational telemetry and runtime admin surfaces
+
+### 5.3 Full multi-tenant MSP platform
+Not required yet:
+- sophisticated tenant isolation/workflows
+- tenant admin model
+- role/permission systems
+- commercial packaging of multi-client operation
+
+### 5.4 Full discovery apparatus breadth
+Not required yet:
+- mature burst detection
+- mature self-heal analysis
+- mature precursor analysis
+- mature spread correlation
+- advanced historical incident recall
+
+### 5.5 UI-heavy product surfaces
+Not required yet:
+- rich dashboard
+- review workflow UI
+- polished multi-surface operator console
+
+### 5.6 Black-box AI sophistication
+Not required yet:
+- heavy model-driven ranking
+- opaque semantic scoring
+- large-model-first product logic
+
+If those things appear, they must be described as future direction, not as completed scope.
+
+---
+
+## 6. Required acceptance criteria for `v0.0.1`
+
+A release is acceptable as `v0.0.1` only if the following are true.
+
+### 6.1 Category clarity
+The docs clearly present brAInstem as:
+- an operational memory prototype for weak signals
+- not a generic AIOps platform
+- not a generic observability or SIEM replacement
+
+### 6.2 Scope honesty
+The docs explicitly separate:
+- what the release proves now
+- what the future architecture aspires to
+
+### 6.3 Canonical event story
+The docs and code align around the idea of a normalized internal event stream.
+
+### 6.4 Attention story
+The release establishes attention as a first-class concept in architecture, scoring, or operator-facing wording.
+
+### 6.5 End-to-end proof
+There is a reproducible path that shows:
+- input
+- normalization
+- recurrence/interesting-item logic
+- operator-facing output
+
+### 6.6 Local run story
+A reader can understand how to install and run the prototype locally.
+
+### 6.7 No fake platform claims
+The release does not claim broad universal ingestion or production appliance maturity unless actually implemented and proven.
+
+---
+
+## 7. Recommended release messaging
+
+### Good release framing
+- experimental prototype
+- first operational memory runtime cut
+- weak-signal recurrence and attention prototype
+- self-contained local runtime proof
+
+### Bad release framing
+- complete AIOps platform
+- production-ready universal event appliance
+- full MSP operational intelligence suite
+- generalized autonomous operations engine
+
+---
+
+## 8. Minimal implementation target for `v0.0.1`
+
+If implementation work is done for this release, it should be tightly bounded.
+
+### Good implementation targets
+- align output terminology with attention/interesting items
+- tighten demo path so it looks more like a real product artifact
+- make recurrence output more concise and operator-readable
+- improve docs/install/demo instructions
+- ensure the current test path is runnable in a known environment
+
+### Bad implementation targets
+- broad refactors for imagined future scale
+- building many connectors prematurely
+- engineering the full day-1 robust intake appliance before cutting `v0.0.1`
+- heavy UI work
+
+---
+
+## 9. Relationship to the next milestone
+
+`v0.0.1` is intentionally narrower than the true day-1 product ambition.
+
+The next serious milestone after `v0.0.1` should focus on the **robust input apparatus** described in the governance doc:
+- stronger intake runtime
+- adapter contract
+- durable buffering/spooling
+- syslog/API intake hardening
+- parse/decode health visibility
+
+That work should happen **after** we have a truthful first release on the board.
+
+---
+
+## 10. Release checklist
+
+Before calling the release done, confirm:
+- [ ] README reflects the real wedge and scope
+- [ ] design-governance doc exists and is linked
+- [ ] architecture doc reflects the attention/canonical-stream model
+- [ ] release scope doc exists (`v0.0.1.md`)
+- [ ] current output/demo path is operator-legible
+- [ ] tests or runnable validation path are documented honestly
+- [ ] release notes do not overclaim capabilities
+
+---
+
+## 11. Final governing statement for `v0.0.1`
+
+brAInstem `v0.0.1` succeeds if it is a small, truthful, runnable release that demonstrates the beginning of a real product:
+- one canonical stream
+- one attention model
+- one weak-signal discovery path
+- one operator-facing output worth looking at
+
+That is enough for a first release.
+Anything beyond that is bonus, not the bar.

package/docs/vision.md

@@ -0,0 +1,85 @@
+# Vision
+
+## Category
+
+**Operational Memory Engine**
+
+brAInstem is an operational memory engine for logs and events. It is designed to ingest noisy machine activity, remember patterns over time, and surface the things humans should care about even when no traditional alert fired.
+
+## Problem statement
+
+MSPs and operators are flooded with logs yet still blind to meaningful issues.
+
+The missing capability is not collection. It is memory.
+
+Systems generate too many events for humans to remember:
+- what happened last week
+- which recurring glitches self-resolved
+- what patterns often precede bigger incidents
+- which low-grade anomalies matter in a specific customer environment
+
+Traditional tooling is optimized for thresholds and outages. brAInstem is optimized for weak signals and human significance.
+
+## Core promise
+
+> brAInstem notices what your systems keep doing that your team keeps missing.
+
+## Why it matters
+
+Many real problems do not present as hard failures:
+- VPN tunnels flap and recover before alerts fire
+- services restart repeatedly but come back too fast to page
+- auth weirdness accumulates below security thresholds
+- backup, DNS, firewall, or cert issues keep recurring without ever becoming a sustained outage
+
+Humans feel the pain later, but the systems never crossed the right machine thresholds at the right time.
+
+## What makes brAInstem different
+
+Existing systems ask:
+- did a threshold breach?
+- did an SLO fail?
+- is the host down?
+
+brAInstem asks:
+- has this happened repeatedly?
+- is it becoming more frequent?
+- does it correlate with other weak signals?
+- has this pattern mattered before?
+- should a human know even if the machine recovered?
+
+## Product principles
+
+- Human-threshold significance over raw severity
+- Memory over dashboard sprawl
+- Explainability over black-box scoring
+- Local-first where practical
+- Tenant-aware by default
+- Promote only meaning, not raw noise
+
+## First users
+
+Primary:
+- MSP owners
+- MSP technicians
+- NOC teams
+- infrastructure operators
+
+## First use cases
+
+- recurring VPN instability
+- repeated auth anomalies
+- service restart storms after changes
+- network flaps that self-resolve
+- weak precursors before customer-facing tickets
+
+## Non-goals
+
+For the early product, brAInstem is not trying to be:
+- a full SIEM replacement
+- a full observability suite
+- a generic metrics platform
+- a compliance engine
+- a generic chatbot over infinite logs
+
+It is a memory-driven event intelligence system.

package/package.json

@@ -1,21 +1,13 @@
 {
   "name": "@simbimbo/brainstem",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "brAInstem — operational memory for weak signals.",
   "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "test": "python3 -m pytest -q"
+  },
   "publishConfig": {
     "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/simbimbo/brainstem.git"
-  },
-  "keywords": [
-    "memory",
-    "logs",
-    "events",
-    "msp",
-    "operations",
-    "observability"
-  ]
+  }
 }

package/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brainstem"
+version = "0.0.3"
+description = "brAInstem — operational memory for weak signals."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  { name = "Steven Imbimbo" }
+]
+license = { text = "MIT" }
+dependencies = ["fastapi>=0.111"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/tests/fixtures/sample_syslog.log

@@ -0,0 +1,6 @@
+Mar 22 00:00:01 fw-01 charon: VPN tunnel dropped and recovered
+Mar 22 00:00:03 fw-01 charon: VPN tunnel dropped and recovered
+Mar 22 00:00:05 fw-01 charon: VPN tunnel dropped and recovered
+Mar 22 00:01:10 fw-01 sshd: Failed password for admin from 10.1.2.3 port 54422
+Mar 22 00:01:12 fw-01 sshd: Failed password for admin from 10.1.2.3 port 54425
+Mar 22 00:03:20 app-01 systemd: service restarted unexpectedly