speed-core 0.1.1

Agentic governance and workflow infrastructure for domain systems

SPEED-CORE

pip install speed-core
# With LLM provider support:
pip install "speed-core[litellm]"
# With SQLite/PostgreSQL durable backends:
pip install "speed-core[postgres]"

Sensing, Planning, Executive, Effecting, Distributing (SPEED) defines agentic decision roles, which is a type of CGA (Capability Gated Architecture). SPEED is an architecture for stateless decision workers performing continuous refinement of a a domain model and implementation of actions (effectors) based upon the domain model.

Inspired by military C2 systems (AEGIS CIC, AWACS, Submarine Conn) whose rules of engagement and structured procedures form a strong basis for agentic LLM governance, enabling an Information Center without full personnel deployment.

General Goals: Coherence, Timeliness, Truthfulness, Actionability, Governance. SPEED agents coordinate, interpret, and govern — they don't block the critical path.

While Timelineness is an important goal, and the acroynm is SPEED, note that this will likely not be the fastest agentic pattern due to the formal patterns it follows.

SPEED for the MinimapPR Common Operating Picture

The technical core is sound localization. Combined with ifcplot (detailed 3D structure database) and Home Assistant (consumer device integration), this becomes a Common Operating Picture with CIC-style agentic LLM coordination above deterministic localization, tracking, and rules enforcement. The system models real-time and long-term environment, tracking and coordinating spatial automations (including future drones and autonomous equipment). Military patterns are followed because they are among the most tested examples for these tasks, and some use cases may see integration by trained NATO personnel.

The goal of this TODO.md is to cover an expansive vision of a product which may take many years to build, in order that all design elements are built with future needs in mind.

Of the main tasks here, one is bringing Agentic (LLM) C2 deeper. The design assumes high-quality LLMs (2026 state of the art) can fill staff-style decision and coordination roles analogous to an AEGIS CIC, while the underlying execution plane remains deterministic and stateful.

For an initial design, the following agents are proposed, which map to SPEED roles: Tactical Action Officer: ultimate decision maker agent that coordinates the intent of the system commander (here the human controller is the commanding officer). Sensor Supervisor: responsible for clarifying data about sensors (for example, helping classify a track, dynamically adding extra noise cancellation preprocessing if facing interference, etc). Operations Coordinator: responsible for multimodal fusion and reacting to events like a loss of track or loss of sensor. Can combine camera feeds and sound classifications along with information lookups to confirm classification, IFF, etc. Engagement Control Coordinator: responsible for overseeing individual effector engagements. Tactical Information Coordinator: interacts with external agents to provide information import and export

Unlike humans, agents are stateless — many copies can be spun up as needed, but they need a real-time log of past actions. An agent ledger database is necessary (implemented via the EventLog Blackboard Pattern + Distributed Locks and Leases). Agents operate at a higher cognitive tier, but are strictly governed by the rules/policy engine. They sit above real-time systems like TDOA localization. The deterministic execution plane continues regardless of whether any agent is active. Hard-coded rules still prevent unsafe actions (e.g., activating sprinklers if high-confidence human tracks are present).

One potential side use: an agentic workflow for classifying unknown signals using LLM models and query tools, pulling examples from online until a high-confidence match is found, gradually building a training dataset.

The MinimapPR agent layer acts as the Operators and staff (interpret, recommend, coordinate, report), with humans as Commanders. It does not replace the deterministic execution plane. This requires proper integration of LLM rules into the full ROE and protocols. Authority must be strictly defined (e.g., lights are safe to authorize autonomously, but door locks always require human authorization). Structured messages are already part of a military-grade COP and useful for LLMs. A separate narrative schema may be defined for human readability. Some alerts fire directly from deterministic logic (e.g., high-confidence fire alarm). Others go through an LLM C2 pathway. Agentic workflows may also build protocols for frequent procedures, gradually removing LLM overhead.

COP (Common Operating Picture) and SPEED for Time Series

Unlike MinimapPR where tracks represent concrete objects, time series tracks represent derived "composite trends" — long-term (consumer demand), short-term (discrete anomaly events), or predictable (holidays). Goals: build composite tracks with high accuracy, explain individual sensor data fully through composites, and minimize the number of composites needed (e.g., one composite anomaly for a winter storm affecting multiple series). Open questions: how composites compose into each other (a winter storm impacts overall demand but isn't part of its long-term trajectory), and how related trends reference each other across geographies. Uniquely here, forecast tracks of individual series are desired. These should be built from or conform to their related composite tracks. An important downstream question is staffing (warehouse or data center capacity). Products undergo frequent packaging/platform changes with varying impact on demand and operations. Goals: annotate changes on historical data, assess impact, and estimate future planned event impact from historical patterns.

Agentic LLM workflows are seen as critical for making this system feasible and increase its sophistication over time. They need to interact cleanly with deterministic processes (which handle most needs, and trigger agents where needed), rigidly defined rules and processes, and human oversight and input.

Three track types: sensor (raw time series), digital twins (reconstructed from derived), and derived tracks (underlying factors like consumer demand, category demand, holidays). Derived tracks and digital twins have forecast values; sensor forecasts are the digital twin forecast.

• Identification: anomaly/not-anomaly, trending, fading, etc.
• Effectors: internal management (new derived tracks), direct actions (marketing spend), tickets for human review
• Rules scope: product categories or service lines rather than geographic zones
• Policy/ROE Engine: manage components (holiday tracks stay holidays, not anomalies) and constrain effectors (budget limits)
• Versioning: important, with functionality to backtest policy changes

Limitation: can adjust marketing allocation but won't create new materials. Focuses on operational questions ("how many staff tomorrow") not strategic ones ("should we build a new warehouse"), though agents may raise tickets for such analysis.

SPEED roles mapped:

• Sensing: deterministic anomaly detection; agentic review for gray-area data
• Planning: graph auditor suggests constraints; event linkage agent proposes linked events
• Executive: reviews plans against policies, approves effectors
• Effecting: supervised execution loop that reruns graph with new params to assess accuracy
• Distributing: explainable forecast outputs with anomaly/changepoint annotations

Details on the time series COP - Time Variant Architecture COP

Decomposition model: All time series decompose into trend, seasonality, level shifts (sudden jumps, usually from metric redefinitions), holidays, and anomalies. New series start with univariate breakdown; only holidays (geo-shared) form initial cross-series connections.

Graph construction from shared stories: Anomalies and changepoints are linked to labeled stories, forming cross-series connections. These shared stories provide constraints for building the trend graph. Series with shared changepoints should derive them from a common derived track. Impacts may differ in direction/magnitude (winter storm increases shovels, decreases other products). Key techniques: Bayesian edge priors, lag-tolerant linkages, regularization. Graph built in numpy/scipy (connections mask), forecasts via PyTorch/Jax. Linkages represented by masked sparse attention (time-varying).

Component scope: Trend graph is the primary structure. Holidays and anomalies have their own subgraphs. Seasonality is fully local.

What-If backprop: Users input adjustments to forecasts, backpropagated as constraints with attention frozen. Bayesian updating shifts high-variance components first, preserving deterministic holidays and high-confidence national trends.

Hard constraints:

• Level shifts strictly quarantined as local intercept adjustments (β_local); never propagate through edges
• Trends must be modeled from derived components (strong penalty on independent trend usage)
• Penalize correlation between derived tracks and known deterministic components (holidays, day-of-week)
• Encourage derived track smoothness Graph updates: Incremental (pull old weights, learn for new/removed series). Learning starts with 1-step-ahead, extends to longer windows. Long horizons focus on trend, seasonality, holidays — no far-ahead anomaly prediction.

Digital twin composition: Trend + seasonality + holiday + level shift + anomaly, combined via attention (not purely additive/multiplicative).

Hierarchical reconciliation: Orthogonal cascading with differentiable reconciliation. Network outputs distribution parameters (μ, σ²) optimized via NLL. Reconciliation updates covariance matrices across geographic nodes.

Agent roles: Build events databases from company/news stories (external pipeline), link anomalies/changepoints to stories, audit graph and propose constraints where connections contradict known business procedures.

COP and SPEED for Personal Digital Assistant

Potential third use case (not built out): real-time data from fitness wearables and calendars, with tracks for health states and time allocation. Effectors like bedtime notifications. Could integrate with a household MinimapPR instance (admin/viewer access levels).

SPEED for Conversational Agents

SPEED may also frame conversational agents: SENSING reviews inputs (spelling, adversarial detection), PLANNING processes content and pulls context and recommends effector, EXECUTIVE reviews against rules and triggers an effector to respond, EFFECTING is the actual response generation (a dedicated code creator, or code reviewer is called). DISTRIBUTING applies formatting and reviews if additional actions are needed before returning output to user. In this case, the COP is the collection of memories and skills attributed to the User (not even needing a full separate domain model, but simply rules and policies to guide how these memories are created, organized, and used). The higher overhead of this pattern make this more suited for conversational platforms requiring higher response quality (for example, a banking agent).

Time Series COP Flow Chart

graph TB
    classDef input fill:#eceff1,stroke:#607d8b,stroke-width:2px;
    classDef processing fill:#fff3e0,stroke:#ff9800,stroke-width:2px;
    classDef agent fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px;
    classDef core fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px;
    classDef output fill:#e8f5e9,stroke:#4caf50,stroke-width:2px;
    classDef user fill:#ffebee,stroke:#f44336,stroke-width:2px;
    classDef strict fill:#ffebee,stroke:#b71c1c,stroke-width:2px,stroke-dasharray: 5 5;
    classDef note fill:#fffde7,stroke:#fbc02d,stroke-width:1px,stroke-dasharray: 5 5;

    %% --- THE DATA ENGINE ---
    subgraph Inputs
                Sensors[(Raw Sensor Series)]:::input --> Decomp[Univariate Decomposition]:::processing
        News[(Business & News Context)]:::input --> Agents[SPEED Event Agents]:::agent
        
        Decomp --> T[Trend]
        Decomp --> C[Changepoints]
        Decomp --> A[Anomalies]
        Decomp --> H[Holidays / Geo-Shared]
        Decomp --> S[Seasonality / Local]
        Decomp --> LS[Level Shifts / Quarantined]:::strict
    end
    subgraph Engine [The COP Processing Engine]
        direction TB
    
        
        C -.-> |Triggers| Agents
        A -.-> |Triggers| Agents
        Agents --> Stories[(Shared Stories DB)]:::core
        
        Stories --> |Bayesian Edge Priors| MaskBuilder[Graph Edge Builder]:::processing
        MaskBuilder --> SparseAttn{Sparse Masked Attention}:::processing
        
        T --> SparseAttn
        SparseAttn --> T_Graph((Derived Trend Network<br/>*Macro to Micro*)):::core
        MaskBuilder --> A_Graph((Anomaly Network)):::core
        H --> H_Graph((Holiday Network)):::core

        T_Graph --> Fusion{Dynamic Fusion Layer<br/>*Attention Weighted*}:::processing
        A_Graph --> Fusion
        H_Graph --> Fusion
        S --> |Local Priors| Fusion
        LS --> |Local Intercept| Fusion
        
        Fusion --> Twin[Digital Twin Distributions]:::processing
        Twin --> Recon[Differentiable Reconciliation]:::processing
        Recon --- Note>COP Value: Guarantees 100% mathematical consistency across all geographic & product hierarchies]:::note
    end

    %% --- THE EXECUTIVE VIEW ---
    subgraph Outputs [Executive Outputs & Deliverables]
        direction LR
        T_Graph ====> ExecTrends[Macro Demand Indicators<br/>*Overall Market Health*]:::output
        Stories ====> Annotations[Business Impact Annotations<br/>*The 'Why' Behind the Data*]:::output
        Recon ====> FinalForecast[Final Coherent Forecasts<br/>*Aligned from Node to Global*]:::output
    end

    %% --- SCENARIO PLANNING ---
    subgraph Scenarios [Scenario Planning & Adaptation]
        FinalForecast -.-> UserAgent((Leadership & Agents)):::user
        UserAgent -.->|Inputs 'What-If' Adjustments| Backprop[Inference Optimizer]:::processing
        Backprop -.->|Backpropagate Adjustments| Fusion
    end

SPEED graph

graph TD
    classDef sense fill:#e8f5e9,stroke:#4caf50,stroke-width:2px;
    classDef plan fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px;
    classDef exec fill:#fff3e0,stroke:#ff9800,stroke-width:2px;
    classDef effect fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px;
    classDef dist fill:#eceff1,stroke:#607d8b,stroke-width:2px;
    classDef human fill:#ffebee,stroke:#f44336,stroke-width:2px;

    %% SENSING
    subgraph S [1. SENSING: Identify & Flag]
        Det[Deterministic Processes<br/>*Flags Clear Anomalies*]:::sense
        Gray[Agentic Review<br/>*Investigates Gray Area / Near-Thresholds*]:::sense
        Det --> Gray
    end

    %% PLANNING
    subgraph P [2. PLANNING: Propose Changes]
        Gray --> Auditor[Graph Auditor Agent<br/>*Suggests Constraints & Mask Updates*]:::plan
        Gray --> Linker[Event Linker Agent<br/>*Proposes Event Linkages*]:::plan
    end

    %% EXECUTIVE
    subgraph E [3. EXECUTIVE: Review & Approve]
        Auditor --> ROE{Policy & ROE Engine<br/>*Hard-Coded Rules*}:::exec
        Linker --> ROE
        ROE --> Gatekeeper[Decision Gatekeeper]:::exec
        Human((Human Oversight)):::human -.-> |Monitor & Override| Gatekeeper
    end

    %% EFFECTING
    subgraph F [4. EFFECTING: Execute & Test]
        Gatekeeper --> |Approved Plans| Runner[Graph Test Runner<br/>*Reruns Graph with New Params*]:::effect
        Runner --> Eval[Accuracy Assessor]:::effect
        Eval --> |If Accurate| Update[Commit Updates to COP]:::effect
    end

    %% DISTRIBUTING
    subgraph D [5. DISTRIBUTING: Explainable Outputs]
        Update --> Dash[Dashboards & Agent Queries]:::dist
        Dash --> Highlights[Provide Explainable Outputs<br/>*Highlight Critical Anomalies & Changepoints*]:::dist
    end
    
    %% Feedback Loop
    Highlights -.-> |Refines Baseline Understanding| Det

SPEED Domain Integration Overview (simplified integration view; see architecture.mmd and TODO.md for the full authority map)

flowchart TB
    classDef kernel   fill:#243447,stroke:#7fa3c8,color:#fff
    classDef truth    fill:#173a2b,stroke:#4fa574,color:#fff
    classDef gov      fill:#3b2a1f,stroke:#c08b5c,color:#fff
    classDef domain   fill:#402433,stroke:#c06f9f,color:#fff,stroke-width:3px
    classDef agent    fill:#2d2a4a,stroke:#8a7de0,color:#fff
    classDef obs      fill:#3f3b1d,stroke:#c7b454,color:#fff

    subgraph K["Kernel Authorities  (accessed exclusively through kernel services)"]
        KEC["KernelEventContract\ngenerates typed constructors · sole write-path legality authority\nderives append guards from one declarative artifact"]
        SR["SchemaRegistry\nvalidates every payload at append time\nschema_intent governs projection and context-assembly priority"]
        PE["PolicyEngine\nAllow · Deny · Escalate · Defer\nevaluates proposals against DecisionEvidenceRecord facts\nfact resolution via PolicyFactProvider + DomainPort.health()"]
        KSV["KernelCommandService · KernelQueryService · KernelEventStream\ncomplete and exclusive kernel access boundary\nno direct kernel-internal imports permitted from outside kernel package"]
    end

    subgraph T["Durable Truth"]
        LOG["EventLog\nappend-only LedgerEvent log\nledger_sequence is the authoritative ordering key"]
    end

    subgraph G["Governance and Workflow  (kernel subsystems)"]
        DISP["Dispatcher\nstarts · resumes · cancels workflows from admitted requests\nclaim queue · priority ordering · spawn coalescing"]
        SPM["WorkflowRuntime\norchestrates governed flows\nS→P→E→E→D phase machine · liveness · timeout · recovery\nowns WorkflowState — the authoritative runtime view"]
        AQ["ApprovalQueue\nhuman escalation surface\nAPPROVAL · INTERVENTION · GUIDANCE_REQUEST"]
    end

    subgraph D["Your Domain Integration Boundary  — implement this"]
        DM["① DomainManifest  committed doctrine — not runtime-mutable\ndeclare: effectors · schemas · request admission policy\nrequest_rate_policy · temporal defaults"]
        DP["② DomainPort  interface to implement\nexecute(DomainCommand) → CommandOutcome\nhealth() → SystemHealth feed"]
        OI["③ RequestIngress  rate-controlled ledger ingress\nnormalize · dedup · rate-gate high-frequency domains\nraw observations stay in domain storage — never ledger events"]
        PFP["④ PolicyFactProvider  domain fact resolution for governance\nresolves FieldRef values at policy evaluation time — on demand only\nnever a free-standing ambient fact stream on the ledger"]
    end

    subgraph A["Host Services  agent and effector layer"]
        AH["AgentHandle\nsubmit_command · query · call_judgment\nwrite_event · acquire_lease · dry_run\nscoped CapabilityToken — sole authority carrier"]
        TOOLS["ToolRegistry\nEFFECTOR · QUERY · PROCESSING · JUDGMENT\nschema-validated I/O · idempotent memo"]
        EW["Effecting Workers  host-side actors only\nexecute already-authorized intent via DomainPort\ninteract with kernel exclusively through KCS and KES"]
    end

    subgraph O["Observability  derived — non-authoritative"]
        PROJ["Projections\ncorrelation timeline · active agents · analytics\nindex and summarize only — no timers or state transitions"]
        OV["OperationView\noperator-facing rendering of WorkflowState\nACTIVE · WAITING · COMPLETED · FAILED\nworkflow_phase reads from phase-exit LifecycleEvents"]
        MP["MetricProjection / MLOps Worker\nPROJECTION-class: replayable counts · latencies · enforcement rates\nEVALUATOR-class: value attribution · guidance coherence · A/B scoring\nread-only log-tailer — zero effect on any governed path"]
    end

    KEC -->|"generates typed constructors and append guards"| LOG
    SR -->|"validates payloads at append"| LOG
    KSV -->|"routes all external writes and reads"| LOG

    DM -->|"declares effectors and tasks for"| DP
    DM -->|"declares request admission policy for"| OI

    OI -->|"rate-controlled admitted requests"| KSV
    OI -->|"admitted workflows dispatched to"| DISP

    DISP -->|"starts / resumes / cancels workflow"| SPM
    SPM -->|"submits proposed actions for policy decision"| PE
    PE -->|"governance decision appended"| LOG
    PE -->|"dry-run permit or deny"| AH

    SPM -->|"dispatches DomainCommand"| DP
    DP -->|"health() feeds system risk posture"| PE
    PFP -->|"resolves domain facts at evaluation time"| PE
    DP -->|"CommandOutcome appended via KCS"| KSV
    SPM -->|"uncertain execution escalated"| AQ
    AQ -->|"human decision appended"| LOG

    SPM -->|"spawns governed agent task with CapabilityToken"| AH
    LOG -->|"replay / context via KernelQueryService"| AH
    AH -->|"ProposedAction appended via KCS"| KSV
    AH -->|"governed tool calls"| TOOLS
    TOOLS -->|"tool outputs appended via KCS"| KSV

    EW -->|"progress events · claim advances via KCS"| KSV
    KSV -->|"authorized-action signals via KES"| EW
    EW -->|"executes authorized intent"| DP

    GR -->|"injects scoped guidance into agent context"| AH

    LOG -->|"feeds analytics"| PROJ
    SPM -->|"WorkflowState renders as"| OV
    KSV -->|"read-only log-tailer via KernelEventStream"| MP
    MP -->|"AUDIT_ONLY metric snapshots via KCS"| KSV

    class KEC,SR,PE,KSV kernel
    class LOG truth
    class DISP,SPM,AQ,GR gov
    class DM,DP,OI,PFP domain
    class AH,TOOLS,EW agent
    class PROJ,OV,MP obs