@simbimbo/brainstem 0.0.1 → 0.0.3

package/docs/roadmap.md

@@ -0,0 +1,87 @@
+# Roadmap
+
+## Phase 0 — Concept and framing
+
+Deliverables:
+- product vision
+- architecture doc
+- scoring doc
+- naming and positioning
+- object model draft
+
+Success criteria:
+- a clear product story for MSP weak-signal detection
+- consensus on category: operational memory engine
+
+## Phase 1 — MVP event memory engine
+
+Scope:
+- ingest syslog and similar line-oriented logs
+- normalize events
+- fingerprint signatures
+- generate recurrence / burst / self-heal candidates
+- compute human-significance scores
+- emit a daily weak-signal digest
+- design the first external connector contract with LogicMonitor in mind
+
+Success criteria:
+- detects recurring self-resolving issues missed by classic alerting
+- produces operator-readable explanations
+
+## Phase 2 — Incident memory and retrieval
+
+Scope:
+- promote important candidates into durable incident memory
+- retrieve prior similar incidents
+- support explainable operator queries
+- add runbook hint / lesson promotion
+
+Success criteria:
+- answer "have we seen this before?" well
+- surface likely prior causes and related lessons
+
+## Phase 3 — MSP multi-tenant operation
+
+Scope:
+- tenant-aware ingestion and scoring
+- per-client baselines
+- cross-tenant pattern memory where allowed
+- technician daily briefs and review workflows
+
+Success criteria:
+- useful for a real MSP operating multiple customer environments
+- reduces log blindness and catches weak signals earlier
+
+## Phase 4 — Advanced correlation and operator assistance
+
+Scope:
+- maintenance / deployment awareness
+- precursor scoring improvements
+- root-cause hints
+- operator review loops and trust calibration
+- optional agent-assist investigation mode
+
+Success criteria:
+- stronger contextual recommendations without becoming a black box
+
+## MVP non-goals
+
+The early product should not try to be:
+- a full SIEM
+- a full observability suite
+- a full metrics backend
+- a compliance engine
+- a generic chatbot over all logs
+
+## Proposed next concrete step
+
+Build a small demo around one killer scenario:
+- recurring self-healing VPN flaps
+- repeated auth weirdness
+- recurring service restart storm after a maintenance window
+
+The first demo should output:
+- weak-signal digest
+- recurrence evidence
+- significance score
+- explanation of why a human should care

package/docs/scoring.md

@@ -0,0 +1,424 @@
+# Attention Scoring Model
+
+_Status: scoring and routing contract for early brAInstem attention behavior_
+
+## Purpose
+
+This document defines how brAInstem should think about operator attention.
+
+The key governing idea is:
+
+> brAInstem should not operate on a naive keep-vs-drop model.
+> It should assign, evolve, and spend **attention**.
+
+Scoring exists to support that attention model.
+It is not the product by itself.
+
+This document should be read together with:
+- `design-governance.md`
+- `architecture.md`
+- `adapters.md`
+- `v0.0.1.md`
+
+---
+
+## 1. Why attention matters
+
+A lot of operationally meaningful patterns begin as tiny events that do not deserve immediate human review.
+
+Examples:
+- one brief VPN rekey failure
+- one odd auth burst
+- one short service restart
+- one low-grade warning with no obvious impact
+
+Any one of those may be meaningless.
+But if the same pattern:
+- repeats
+- spreads
+- increases in frequency
+- resembles past meaningful issues
+- clusters with other weak signals
+
+then it may deserve significantly more attention later.
+
+### Therefore
+brAInstem should avoid treating early weak signals as permanently disposable.
+Instead, it should:
+- assign an initial attention score/band
+- retain enough evidence to re-evaluate later
+- allow weak signals to earn more attention over time
+
+---
+
+## 2. Core design principle
+
+### Wrong model
+- ingest
+- drop or keep
+- maybe summarize later
+
+### Better model
+- ingest
+- canonicalize
+- assign initial attention
+- update attention over time
+- route according to attention band
+- surface or promote only when attention is sufficiently earned
+
+This is the central scoring philosophy of brAInstem.
+
+---
+
+## 3. Attention vs severity
+
+brAInstem should not confuse:
+- **severity**
+with
+- **attention**
+
+### Severity
+Severity is often source-provided or source-derived.
+It answers something like:
+- how bad does the source think this event is right now?
+
+### Attention
+Attention answers:
+- how much operator attention does this deserve in context?
+
+A low-severity event may deserve high attention if it is:
+- recurring
+- self-healing repeatedly
+- spreading
+- historically meaningful
+- likely to become painful later
+
+A high-severity event may still deserve high attention, but attention is the broader and more human-centered concept.
+
+---
+
+## 4. Attention layers
+
+Attention should be thought about at three levels.
+
+### 4.1 Event attention
+The immediate attention value for an individual canonical event.
+
+Used for:
+- immediate routing
+- early retention choice
+- whether to spend more compute now
+
+### 4.2 Signature attention
+The accumulated attention value of a normalized recurring pattern/signature over time.
+
+Used for:
+- recurrence interpretation
+- burst detection
+- spread detection
+- low-level weak-signal tracking
+
+### 4.3 Candidate attention
+The operator-facing attention value of a higher-order weak-signal candidate.
+
+Used for:
+- interesting items
+- digests
+- review queues
+- promotion decisions
+
+### Design rule
+The system should not rely entirely on a single event-level score.
+It must allow attention to accumulate upward from event → signature → candidate.
+
+---
+
+## 5. Attention bands
+
+brAInstem should use explicit attention bands rather than one magical opaque score.
+
+Suggested early model:
+
+### `ignore_fast`
+For:
+- clearly low-value noise
+- highly repetitive, low-impact chatter
+- events that should be counted cheaply but not examined deeply
+
+Behavior:
+- minimal retention or aggregated counters only
+- no deep discovery work
+- no operator visibility
+
+### `background`
+For:
+- low-value individual events that might matter later if repeated
+
+Behavior:
+- retain cheap evidence
+- keep signature/frequency statistics
+- eligible for later attention growth
+
+### `watch`
+For:
+- weak but plausible patterns
+- novelty or recurrence that is not yet worth human interruption
+
+Behavior:
+- maintain more context
+- evaluate recurrence windows
+- candidate formation becomes possible
+
+### `investigate`
+For:
+- patterns that likely deserve immediate discovery analysis
+
+Behavior:
+- full weak-signal evaluation
+- history comparison
+- explanation generation
+
+### `promote`
+For:
+- operator-visible items
+- digest-worthy patterns
+- candidates that deserve durable memory or review
+
+Behavior:
+- surface to humans
+- preserve evidence more fully
+- eligible for incident-memory promotion
+
+### Design rule
+Bands are part of the product behavior.
+They are not just cosmetic labels on top of a number.
+
+---
+
+## 6. Attention score inputs
+
+The exact formula can evolve, but early attention should be based on interpretable components.
+
+## Recommended components
+
+### 6.1 Recurrence
+Measures:
+- how often the same signature has happened
+- whether the rate is increasing
+- whether it appears on a recurring schedule/pattern
+
+Questions:
+- Has this happened before?
+- Is it becoming more frequent?
+- Is recurrence now strong enough to deserve more attention?
+
+### 6.2 Recovery / self-heal behavior
+Measures:
+- whether the issue self-resolved
+- how quickly it recovered
+- whether repeated self-heal cycles are masking real instability
+
+Questions:
+- Did the issue recover too quickly to alert?
+- Is repeat recovery hiding a problem that humans should know about?
+
+### 6.3 Spread
+Measures:
+- number of affected hosts/assets
+- number of affected services
+- possible cross-tenant spread later where allowed
+
+Questions:
+- Is this isolated or systemic?
+- Is this becoming a fleet pattern instead of a single-node oddity?
+
+### 6.4 Novelty
+Measures:
+- whether the signal is new in this environment
+- whether the signature shape is unusual locally
+- whether the combination of fields/signals is rare
+
+Questions:
+- Have we seen this exact shape here before?
+- Does this deserve attention because it is unfamiliar?
+
+### 6.5 Temporal correlation
+Measures:
+- event clustering in time
+- adjacency to change/maintenance windows
+- adjacency to other weak signals in the same time slice
+
+Questions:
+- Did several low-grade signals happen together?
+- Did this show up right after a change?
+
+### 6.6 Human impact likelihood
+Measures likely operator/user pain:
+- support ticket likelihood
+- user-visible degradation likelihood
+- business disruption likelihood
+- trust erosion likelihood
+
+Questions:
+- Would a human care if they knew this was happening repeatedly?
+- Could this become user-facing even if it self-heals now?
+
+### 6.7 Precursor likelihood
+Measures whether this pattern tends to precede something worse.
+
+Questions:
+- Has this kind of signal historically preceded incidents?
+- Did similar signals show up before earlier outages?
+
+### 6.8 Memory weight
+Measures whether historically similar patterns have proven meaningful in this environment.
+
+Questions:
+- In this tenant/environment, does this kind of thing usually matter?
+- Has an operator previously promoted/reviewed similar patterns as important?
+
+### 6.9 Source trust / source criticality (optional but useful)
+Measures:
+- whether the source is operationally important
+- whether the source is known to be noisy/low-value
+- whether the source generally produces trustworthy signals
+
+Questions:
+- Should events from this source get a lower or higher starting attention bias?
+
+---
+
+## 7. Suggested early formula shape
+
+The exact math does not need to be fancy at first.
+
+Early versions should prefer:
+- deterministic components
+- transparent weighting
+- explicit thresholds
+- easy explainability
+
+### Example conceptual model
+
+`attention_score = recurrence + recovery + spread + novelty + temporal_correlation + human_impact + precursor + memory_weight (+ source_bias)`
+
+Then map the resulting value into an attention band.
+
+### Design rule
+The formula can evolve.
+The explainability contract cannot be sacrificed.
+
+---
+
+## 8. Dynamic attention growth
+
+This is one of the most important product behaviors.
+
+A weak-signal event should be able to gain more attention later because of:
+- repeated recurrence
+- spread to more assets/services
+- increased frequency
+- co-occurrence with other weak signals
+- matching prior incident memory
+- operator feedback/history
+
+### Example
+One VPN retry event:
+- maybe `background`
+
+Ten similar VPN retry events over several days, with rising frequency and historical similarity to a prior outage:
+- now likely `investigate` or `promote`
+
+### Design rule
+Low attention does not mean permanently irrelevant.
+It means currently low-cost, low-interruption, re-evaluable.
+
+---
+
+## 9. Routing behavior
+
+Scoring is only useful if it changes system behavior.
+
+Attention should drive routing decisions like:
+- ignore cheaply
+- retain in background state
+- watch for recurrence
+- send to discovery apparatus now
+- include in interesting items
+- include in digest
+- promote into durable memory later
+
+### Suggested mapping
+- `ignore_fast` → aggregated counters / short retention
+- `background` → signature tracking only
+- `watch` → lightweight candidate eligibility
+- `investigate` → full discovery path + explainability
+- `promote` → human-facing output + durable memory eligibility
+
+---
+
+## 10. Explainability contract
+
+Every surfaced candidate or interesting item should explain:
+- why it was surfaced
+- which attention inputs contributed most
+- what evidence was used
+- whether historical memory influenced the result
+- what uncertainty remains
+
+### Example
+- recurrence: high (9 similar events in 7 days)
+- recovery: medium (self-healed within 45s each time)
+- spread: low (single tenant)
+- precursor: high (matched 2 prior incident memories)
+- attention band: `investigate`
+
+### Design rule
+If the system cannot explain why it spent attention on something, operators will not trust it.
+
+---
+
+## 11. What not to do early
+
+### Do not
+- use opaque black-box ranking as the primary scoring mechanism
+- pretend one score is infallible
+- collapse all routing semantics into one number with no band meaning
+- let source severity fully dominate attention
+- overfit to fancy semantic similarity before recurrence/attention basics work
+
+### Why
+Early trust depends more on:
+- consistency
+- inspectability
+- obviousness of reasons
+than on theoretical sophistication.
+
+---
+
+## 12. v0.0.1 implications
+
+For `v0.0.1`, scoring does not need to be mathematically mature.
+
+It **does** need to establish:
+- attention as the central concept
+- interpretable components
+- at least one credible weak-signal path (recurrence is enough)
+- operator-legible output tied to attention
+
+That is enough for a truthful first release.
+
+---
+
+## 13. Final governing statement
+
+Scoring exists so brAInstem can spend operator attention wisely.
+
+The goal is not to compute a clever number.
+The goal is to ensure that:
+- tiny signals are not lost forever
+- noisy junk does not dominate human review
+- historically meaningful weak patterns can earn more attention
+- surfaced output feels justified and useful
+
+That is the standard the scoring model should serve.