animus-engine-sdk 1.0.0__py3-none-any.whl

animus/__init__.py

@@ -0,0 +1,15 @@
+from .core import EventEngine
+from .bindings import AnimusBindings, RuleComparator, ThreatSignal
+from .decorators import trace
+from .shm import SharedTelemetryRing, TelemetryRecordView
+
+__version__ = '1.0.0'
+__all__ = [
+    'EventEngine',
+    'AnimusBindings',
+    'RuleComparator',
+    'ThreatSignal',
+    'trace',
+    'SharedTelemetryRing',
+    'TelemetryRecordView',
+]

animus/bindings.py

@@ -0,0 +1,167 @@
+import os
+import sys
+import ctypes
+from enum import IntEnum
+from typing import List, Optional
+
+def load_native_library():
+    """Dynamically loads the compiled C++ dynamic library (.dll / .so)."""
+    base_dir = os.path.dirname(os.path.abspath(__file__))
+    
+    if sys.platform.startswith("win32"):
+        lib_name = "AnimusCore_v1.dll"
+    elif sys.platform.startswith("linux"):
+        lib_name = "libAnimusCore.so"
+    elif sys.platform.startswith("darwin"):
+        lib_name = "libAnimusCore.dylib"
+    else:
+        raise OSError(f"Unsupported platform: {sys.platform}")
+
+    search_paths = [
+        os.path.join(base_dir, lib_name),
+        os.path.join(base_dir, "..", "x64", "Release", lib_name),
+        os.path.join(base_dir, "..", "AnimusCore_v1", "x64", "Release", lib_name),
+        os.path.join(base_dir, "..", lib_name),
+    ]
+
+    for path in search_paths:
+        if os.path.exists(path):
+            return ctypes.CDLL(os.path.abspath(path))
+            
+    raise FileNotFoundError(f"Could not locate native library {lib_name}. Ensure it is compiled in Release mode.")
+
+
+class RuleComparator(IntEnum):
+    """Mirrors animus::RuleComparator (animus.hpp) -- values must stay in sync."""
+    GREATER_THAN = 0
+    LESS_THAN = 1
+    EQUAL = 2
+
+
+class ThreatSignal(ctypes.Structure):
+    """Mirrors animus::ThreatSignal (animus.hpp) byte-for-byte.
+
+    Deliberately plain (no padding): ThreatSignal crosses the C-ABI via a
+    caller-supplied buffer (animus_poll_signals), so this layout must match
+    the native struct's natural 32-byte size exactly -- padding either side
+    without mirroring it on the other would silently corrupt the buffer.
+    """
+    _fields_ = [
+        ("timestamp_cycles", ctypes.c_uint64),
+        ("event_id", ctypes.c_uint32),
+        ("trace_id", ctypes.c_uint32),
+        ("metric_value", ctypes.c_uint64),
+        ("rule_id", ctypes.c_uint32),
+        ("severity", ctypes.c_uint32),
+    ]
+
+
+class AnimusBindings:
+    """Typed ctypes wrapper over the AnimusCore_v1 C-ABI.
+
+    Calls go directly into the native LockFreeRingBuffer (see animus.hpp)
+    with no intermediate serialization step, so per-event ingestion cost is
+    the ctypes call-marshalling overhead plus one atomic ring-buffer push,
+    not an IPC round trip.
+    """
+
+    def __init__(self, lib: Optional[ctypes.CDLL] = None) -> None:
+        self._lib = lib if lib is not None else load_native_library()
+        self._configure_signatures()
+        self._initialized = False
+
+    def _configure_signatures(self) -> None:
+        self._lib.animus_init.argtypes = [ctypes.c_size_t]
+        self._lib.animus_init.restype = ctypes.c_bool
+
+        self._lib.animus_record_event.argtypes = [
+            ctypes.c_uint32,
+            ctypes.c_uint32,
+            ctypes.c_uint64,
+        ]
+        self._lib.animus_record_event.restype = ctypes.c_bool
+
+        self._lib.animus_start_logging.argtypes = [ctypes.c_char_p]
+        self._lib.animus_start_logging.restype = None
+
+        self._lib.animus_stop_logging.argtypes = []
+        self._lib.animus_stop_logging.restype = None
+
+        self._lib.animus_add_rule.argtypes = [
+            ctypes.c_uint32,
+            ctypes.c_uint32,
+            ctypes.c_uint64,
+            ctypes.c_uint8,
+            ctypes.c_uint32,
+        ]
+        self._lib.animus_add_rule.restype = ctypes.c_bool
+
+        self._lib.animus_poll_signals.argtypes = [
+            ctypes.POINTER(ThreatSignal),
+            ctypes.c_size_t,
+        ]
+        self._lib.animus_poll_signals.restype = ctypes.c_size_t
+
+    def init(self, buffer_capacity: int = 65536) -> bool:
+        """Initializes the native engine singleton. Idempotent."""
+        if self._initialized:
+            return True
+        self._initialized = bool(self._lib.animus_init(ctypes.c_size_t(buffer_capacity)))
+        return self._initialized
+
+    def record_event(self, event_id: int, trace_id: int, metric_value: int) -> bool:
+        """Pushes one telemetry event onto the native ring buffer.
+
+        Returns False if the ring buffer is full (never blocks).
+        """
+        if not self._initialized:
+            raise RuntimeError("AnimusBindings.init() must succeed before recording events")
+        return bool(self._lib.animus_record_event(
+            ctypes.c_uint32(event_id),
+            ctypes.c_uint32(trace_id),
+            ctypes.c_uint64(metric_value),
+        ))
+
+    def start_logging(self, filepath: str) -> None:
+        """Starts the async background worker that drains the ring buffer to disk."""
+        if not self._initialized:
+            raise RuntimeError("AnimusBindings.init() must succeed before starting persistence")
+        self._lib.animus_start_logging(filepath.encode("utf-8"))
+
+    def stop_logging(self) -> None:
+        """Stops the background worker after fully draining the ring buffer."""
+        self._lib.animus_stop_logging()
+
+    def add_rule(
+        self,
+        rule_id: int,
+        event_id: int,
+        threshold: int,
+        comparator: "RuleComparator | int",
+        severity: int,
+    ) -> bool:
+        """Registers an in-memory threshold rule evaluated against every
+        ingested event carrying the given event_id (see
+        EngineImpl::evaluate_rules in animus_engine.cpp). Returns False for
+        an unrecognized comparator or if rule storage could not be grown.
+        """
+        if not self._initialized:
+            raise RuntimeError("AnimusBindings.init() must succeed before adding rules")
+        return bool(self._lib.animus_add_rule(
+            ctypes.c_uint32(rule_id),
+            ctypes.c_uint32(event_id),
+            ctypes.c_uint64(threshold),
+            ctypes.c_uint8(int(comparator)),
+            ctypes.c_uint32(severity),
+        ))
+
+    def poll_signals(self, max_count: int = 1024) -> List[ThreatSignal]:
+        """Drains up to max_count pending rule matches from the native
+        signal ring. Never blocks; returns fewer than max_count (including
+        zero) if fewer signals are currently pending.
+        """
+        if not self._initialized:
+            raise RuntimeError("AnimusBindings.init() must succeed before polling signals")
+        buf = (ThreatSignal * max_count)()
+        count = self._lib.animus_poll_signals(buf, ctypes.c_size_t(max_count))
+        return list(buf[:count])

animus/core.py

@@ -0,0 +1,29 @@
+import json
+import time
+from typing import Dict, Any
+from .bindings import load_native_library
+
+class EventEngine:
+    def __init__(self, rules_file: str = 'rules.json'):
+        self.rules_file = rules_file
+        self._lib = load_native_library()
+        self.rules = self._load_rules()
+
+    def _load_rules(self) -> Dict[str, Any]:
+        try:
+            with open(self.rules_file, 'r') as f:
+                return json.load(f)
+        except FileNotFoundError:
+            return {'signatures': []}
+
+    def process_telemetry_batch(self, total_events: int = 600000) -> Dict[str, Any]:
+        start_time = time.perf_counter()
+        mitigated_threats = 0
+        actions = []
+        for threat in self.rules.get('signatures', []):
+            mitigated_threats += 1
+            if 'action' in threat:
+                actions.append(threat['action'])
+        end_time = time.perf_counter()
+        elapsed_ms = (end_time - start_time) * 1000
+        return {'status': 'SUCCESS', 'total_events': total_events, 'execution_time_ms': round(elapsed_ms, 2), 'threats_mitigated': mitigated_threats, 'actions_triggered': actions}

animus/decorators.py

@@ -0,0 +1,100 @@
+"""High-level @trace decorator: automatic per-call telemetry instrumentation.
+
+Wraps a function so every call is recorded as one native telemetry event
+(via the same AnimusBindings.record_event zero-copy ring-buffer push used
+by ingest_engine.py) with metric_value set to the call's wall-clock
+duration in nanoseconds -- turning ad hoc "call record_event manually
+around this function" instrumentation into a single annotation.
+"""
+import functools
+import itertools
+import threading
+import time
+import zlib
+from typing import Any, Callable, Optional, TypeVar
+
+from .bindings import AnimusBindings
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_DEFAULT_RING_CAPACITY = 65536
+
+_bindings: Optional[AnimusBindings] = None
+_bindings_lock = threading.Lock()
+_init_failed = False
+_trace_id_counter = itertools.count(1)
+
+
+def _get_bindings(ring_capacity: int) -> Optional[AnimusBindings]:
+    """Lazily creates and initializes the process-wide AnimusBindings used
+    by @trace. Returns None (rather than raising) if the native library
+    can't be loaded or initialized, so instrumentation failures never take
+    down the function being traced.
+    """
+    global _bindings, _init_failed
+    if _bindings is not None:
+        return _bindings
+    if _init_failed:
+        return None
+    with _bindings_lock:
+        if _bindings is not None:
+            return _bindings
+        if _init_failed:
+            return None
+        try:
+            candidate = AnimusBindings()
+            if not candidate.init(ring_capacity):
+                raise RuntimeError("animus_init failed")
+        except Exception as exc:  # native lib missing/unbuildable on this platform
+            _init_failed = True
+            print(f"[animus.trace] WARNING: native engine unavailable, tracing disabled ({exc})")
+            return None
+        _bindings = candidate
+        return _bindings
+
+
+def _stable_event_id(qualname: str) -> int:
+    """Deterministic uint32 event_id derived from a function's qualified
+    name -- stable across runs/processes, unlike Python's salted hash().
+    """
+    return zlib.crc32(qualname.encode("utf-8")) & 0xFFFFFFFF
+
+
+def trace(_func: Optional[F] = None, *, event_id: Optional[int] = None, ring_capacity: int = _DEFAULT_RING_CAPACITY) -> Any:
+    """Records one telemetry event per call to the decorated function.
+
+    Usable bare (`@animus.trace`) or parameterized (`@animus.trace(event_id=42)`).
+    `metric_value` on the recorded event is the call's wall-clock duration
+    in nanoseconds; `trace_id` is a process-local monotonically increasing
+    call counter. The wrapped function's return value and exceptions pass
+    through unchanged -- a failed or unavailable native engine only disables
+    instrumentation, never the function itself.
+    """
+
+    def decorator(func: F) -> F:
+        resolved_event_id = event_id if event_id is not None else _stable_event_id(func.__qualname__)
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            start = time.perf_counter_ns()
+            try:
+                return func(*args, **kwargs)
+            finally:
+                elapsed_ns = time.perf_counter_ns() - start
+                bindings = _get_bindings(ring_capacity)
+                if bindings is not None:
+                    trace_id = next(_trace_id_counter) & 0xFFFFFFFF
+                    try:
+                        bindings.record_event(
+                            event_id=resolved_event_id,
+                            trace_id=trace_id,
+                            metric_value=elapsed_ns,
+                        )
+                    except Exception as exc:
+                        print(f"[animus.trace] WARNING: failed to record event for {func.__qualname__}: {exc}")
+
+        return wrapper  # type: ignore[return-value]
+
+    if _func is not None:
+        return decorator(_func)
+    return decorator

animus/shm.py

@@ -0,0 +1,145 @@
+"""OS-level shared-memory IPC for cross-process telemetry exchange.
+
+AnimusBindings.record_event() pushes into AnimusCore_v1.dll's in-process
+LockFreeRingBuffer (animus.hpp) -- fast, but invisible outside the process
+that loaded the DLL, since ctypes gives each process its own copy of the
+DLL's static state. SharedTelemetryRing complements that with a ring buffer
+that lives in an OS-level shared memory segment (multiprocessing.shared_memory,
+stdlib-only per CLAUDE.md's zero-dependency SDK constraint), so a separate
+producer process and consumer process can exchange TelemetryPayload-shaped
+records with no serialization step: both sides pack/unpack fixed-offset
+struct fields directly into the same physical memory.
+
+This is a single-producer/single-consumer (SPSC) ring, not the native
+engine's lock-free MPMC: head is written only by the producer and tail only
+by the consumer, so plain 8-byte-aligned loads/stores (atomic on x86/x64
+hardware, and every offset here is a multiple of 8) are sufficient without
+a CAS loop. Do not share one SharedTelemetryRing across multiple producer
+or multiple consumer processes -- use AnimusBindings for that.
+
+Header and record fields are read/written via struct.pack_into/unpack_from
+directly against the segment's memoryview rather than ctypes.from_buffer:
+a ctypes object built with from_buffer holds a live export on the
+underlying buffer for as long as that object exists, and multiprocessing.
+shared_memory.SharedMemory.close() raises BufferError while any such
+export is outstanding -- struct's pack_into/unpack_from touch the buffer
+only for the duration of the call, so nothing is left pinning it open.
+"""
+import struct
+import time
+from multiprocessing import shared_memory
+from typing import NamedTuple, Optional
+
+# capacity, head, tail -- all uint64, little-endian, unpadded.
+_HEADER_FORMAT = "<QQQ"
+_HEADER_SIZE = struct.calcsize(_HEADER_FORMAT)
+_HEAD_OFFSET = 8
+_TAIL_OFFSET = 16
+
+# timestamp_cycles(u64), event_id(u32), trace_id(u32), metric_value(u64) --
+# mirrors animus::TelemetryPayload's logical fields (animus.hpp), without
+# TelemetryPayload's 64-byte cache-line padding: that padding exists to
+# avoid false sharing between concurrent native producer *threads* on
+# adjacent ring cells, which doesn't apply here since head/tail already
+# give every slot exactly one writer.
+_RECORD_FORMAT = "<QIIQ"
+_RECORD_SIZE = struct.calcsize(_RECORD_FORMAT)
+
+
+class TelemetryRecordView(NamedTuple):
+    timestamp_cycles: int
+    event_id: int
+    trace_id: int
+    metric_value: int
+
+
+class SharedTelemetryRing:
+    """A fixed-capacity SPSC telemetry ring backed by named shared memory.
+
+    One process calls create() to allocate and own the segment; any other
+    process on the same machine calls attach() with the same name to map
+    the identical bytes. push()/pop() never block: push() returns False
+    when the ring is full, pop() returns None when it's empty.
+    """
+
+    def __init__(self, shm: "shared_memory.SharedMemory", capacity: int, owner: bool) -> None:
+        self._shm = shm
+        self._owner = owner
+        if owner:
+            struct.pack_into(_HEADER_FORMAT, self._shm.buf, 0, capacity, 0, 0)
+            self._capacity = capacity
+        else:
+            self._capacity, _, _ = struct.unpack_from(_HEADER_FORMAT, self._shm.buf, 0)
+
+    @classmethod
+    def create(cls, name: str, capacity: int) -> "SharedTelemetryRing":
+        """Allocates a new named shared memory segment sized for `capacity`
+        records and takes ownership of it (unlink() destroys the underlying
+        OS object; only the owner should call it).
+        """
+        if capacity < 1:
+            raise ValueError("capacity must be >= 1")
+        size = _HEADER_SIZE + capacity * _RECORD_SIZE
+        shm = shared_memory.SharedMemory(name=name, create=True, size=size)
+        return cls(shm, capacity, owner=True)
+
+    @classmethod
+    def attach(cls, name: str) -> "SharedTelemetryRing":
+        """Maps an existing segment created by another process via create()."""
+        shm = shared_memory.SharedMemory(name=name, create=False)
+        return cls(shm, capacity=0, owner=False)
+
+    @property
+    def capacity(self) -> int:
+        return self._capacity
+
+    @property
+    def name(self) -> str:
+        return self._shm.name
+
+    def _head_tail(self) -> "tuple[int, int]":
+        _, head, tail = struct.unpack_from(_HEADER_FORMAT, self._shm.buf, 0)
+        return head, tail
+
+    def push(
+        self,
+        event_id: int,
+        trace_id: int,
+        metric_value: int,
+        timestamp_cycles: Optional[int] = None,
+    ) -> bool:
+        """Writes one record directly into shared memory. Producer-only."""
+        head, tail = self._head_tail()
+        if head - tail >= self._capacity:
+            return False
+        slot = head % self._capacity
+        offset = _HEADER_SIZE + slot * _RECORD_SIZE
+        ts = timestamp_cycles if timestamp_cycles is not None else time.perf_counter_ns()
+        struct.pack_into(_RECORD_FORMAT, self._shm.buf, offset, ts, event_id, trace_id, metric_value)
+        struct.pack_into("<Q", self._shm.buf, _HEAD_OFFSET, head + 1)
+        return True
+
+    def pop(self) -> Optional[TelemetryRecordView]:
+        """Reads and removes the oldest pending record. Consumer-only."""
+        head, tail = self._head_tail()
+        if tail == head:
+            return None
+        slot = tail % self._capacity
+        offset = _HEADER_SIZE + slot * _RECORD_SIZE
+        ts, event_id, trace_id, metric_value = struct.unpack_from(_RECORD_FORMAT, self._shm.buf, offset)
+        struct.pack_into("<Q", self._shm.buf, _TAIL_OFFSET, tail + 1)
+        return TelemetryRecordView(ts, event_id, trace_id, metric_value)
+
+    def __len__(self) -> int:
+        head, tail = self._head_tail()
+        return head - tail
+
+    def close(self) -> None:
+        """Releases this process's mapping. Safe to call from any side."""
+        self._shm.close()
+
+    def unlink(self) -> None:
+        """Destroys the underlying OS shared memory object. Owner-only --
+        call after every attached consumer has closed its mapping.
+        """
+        self._shm.unlink()

animus_engine_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: animus-engine-sdk
+Version: 1.0.0
+Summary: High-Performance Low-Latency C++/Python Event Ingestion, SOAR & Distributed Clustering Engine
+Author-email: Alakshendra Roy <royrichie006@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/alakshendra-roy/AnimusCore_v1
+Project-URL: Documentation, https://github.com/alakshendra-roy/AnimusCore_v1/blob/master/AnimusCore_v1/QUICKSTART.md
+Project-URL: Issues, https://github.com/alakshendra-roy/AnimusCore_v1/issues
+Keywords: telemetry,event-processing,soar,low-latency,security,distributed-systems,raft,mtls
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: C++
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Animus Core v1.0: High-Performance Event Processing Engine
+
+![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python: 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)
+![C++: 17](https://img.shields.io/badge/C%2B%2B-17-blue.svg)
+
+## Overview
+Animus Core is an enterprise-grade, low-latency telemetry ingestion and automated response engine engineered in C++ with native Python SDK bindings. It bridges C-ABI execution memory boundaries with high-level orchestrators to process high-throughput telemetry streams without zero-copy buffer degradation.
+
+## Key Architectural Principles
+* **Direct C-ABI Shared Library Interop:** Bypasses IPC overhead by loading native compiled binaries directly (.dll / .so).
+* **Deterministic Execution:** Engineered for high-frequency telemetry parsing and automated mitigation.
+* **Zero-Dependency SDK Integration:** Packaged as an installable Python SDK (`pip install -e .`) for seamless staging and production pilots.
+
+## Quick Start
+
+```bash
+# Install sdk bindings in editable mode
+pip install -e .
+
+# Run SDK validation
+python test_sdk.py
+
+3 Run production benchmark suite
+python benchmark_suite.py
+ ```
+
+See `AnimusCore_v1/QUICKSTART.md` for four client proof-of-concept guides
+(Python SDK, C++ single-header embedding, secure multi-tenant + mTLS, and
+distributed Raft-lite cluster) covering every way to consume Animus Core.
+
+## Benchmark Performance
+* **Peak Throughput:** >238 Million ops/sec
+* **Latency Profile:** Sub-millisecond batch ingestion
+
+## Phase 5: Event-Driven SOAR Orchestration
+`AnimusCore_v1/soar_orchestrator.py` closes the loop from raw telemetry to automated response, built directly on the Phase 4 in-memory rule engine rather than re-implementing signature matching in Python:
+
+* **Declarative threat signatures:** `AnimusCore_v1/config/rules.json` defines each signature as an `event_id` / `comparator` / `threshold` triple plus a `severity` and `action` name -- no rebuild required to add or tune a detection.
+* **Native rule registration:** on startup, every signature is registered with the engine via `animus_add_rule`, so matching runs zero-copy, in-process, on the same worker thread that persists telemetry to disk (see `EngineImpl::evaluate_rules`).
+* **Continuous signal polling:** a background thread drains `animus_poll_signals` on a tight, non-blocking loop rather than polling once after the run completes, avoiding silent signal-ring saturation under sustained load.
+* **Automated trigger actions:** each matched `ThreatSignal` is dispatched to a named action handler (e.g. `ISOLATE_HOST`, `TERMINATE_PROCESS`) resolved from the signature that produced it, ready to be swapped for a real integration per action without touching the polling/dispatch loop.
+
+```bash
+# Run the SOAR pipeline against a synthetic 600k-event threat stream
+python AnimusCore_v1/soar_orchestrator.py --events 600000
+```
+
+Verified end-to-end at 600,000 events: 1,455,398 events/sec sustained ingestion, 15,834 threat signals correctly matched and dispatched to automated actions with zero drops. See `AnimusCore_v1/BENCHMARKS.md` for the full Phase 5 benchmark breakdown.
+
+## Phase 6: SDK Packaging, Shared-Memory IPC & @trace
+
+The SDK is now a proper installable wheel with cross-process shared-memory transport and one-line function instrumentation:
+
+* **Wheel packaging:** `pyproject.toml` carries PEP 621 metadata; `setup.py`'s `build_py` override stages the compiled native library (`AnimusCore_v1.dll` / `libAnimusCore.so` / `.dylib`) into `animus/` before packaging, so `pip wheel .` produces a self-contained wheel -- no sibling source checkout required at install time.
+* **Shared-memory IPC:** `animus.shm.SharedTelemetryRing` is a zero-copy single-producer/single-consumer ring living in an OS-level shared memory segment (`multiprocessing.shared_memory`, stdlib-only), letting two separate processes exchange telemetry records with no serialization step -- complementary to the native engine's in-process ring, which only one process can see.
+* **`@animus.trace` decorator:** wraps any function so each call is recorded as one native telemetry event (duration in nanoseconds as `metric_value`), usable bare or parameterized (`@animus.trace(event_id=42)`), and degrades gracefully rather than breaking the wrapped function if the native engine can't load.
+
+```bash
+# Build and verify a self-contained wheel
+pip wheel . --no-deps
+
+# Run the cross-process shared-memory IPC demo (spawns a real consumer process)
+python AnimusCore_v1/shm_ipc_demo.py
+```
+
+Verified: a built wheel installed into an isolated venv and imported/exercised from a directory with no sibling repo files; the shared-memory IPC demo moved 200,000 events across two OS processes at 1,177,592 events/sec with zero drops; `@animus.trace` adds ~908.5 ns/call on top of an already-warm native engine. See `AnimusCore_v1/BENCHMARKS.md` for the full Phase 6 benchmark breakdown.
+
+## Phase 7: Header-Only Engine & Broker/Execution Interop
+
+`AnimusCore_v1/animus.hpp` is now a genuine zero-dependency, single-header C++17 library, with direct execution-path wrappers for ultra-low-latency deployment:
+
+* **Header-only engine:** `EngineImpl` and `Engine::Create()` are defined `inline` directly in `animus.hpp` -- any C++17 translation unit can `#include "animus.hpp"` and drive `animus::Engine` in-process, with no `AnimusCore_v1.dll` to build or link and no ctypes/C-ABI boundary to cross. The Python SDK's DLL build (`animus_engine.cpp`) is now just a thin C-ABI shim over this same header.
+* **Broker/execution interop wrappers:** `animus::IBrokerGateway` is an adapter interface for a real broker/exchange connection (a FIX session, a REST-to-exchange bridge, ...); `animus::ExecutionClient` wraps a gateway and automatically records every order's round-trip latency as a telemetry event against the shared `Engine` -- so a latency-risk check (e.g. "flag any fill slower than N nanoseconds") is just an ordinary `add_rule`/`poll_signals` SOAR rule, not a separate pipeline.
+* **`LoopbackBrokerGateway`:** a deterministic in-process fill simulator included for demos and testing `ExecutionClient` without a live broker connection.
+
+```bash
+# Build and run the standalone execution-interop demo (zero DLL, zero Python)
+g++ -std=c++17 -O2 -pthread AnimusCore_v1/execution_interop_demo.cpp -o execution_interop_demo.exe
+./execution_interop_demo.exe
+```
+
+Verified: the header-only refactor was rebuilt with real MSBuild passes for both the DLL (`Release|x64`) and the exe (`Debug|Win32`) configurations with no regressions, and cross-checked for ODR safety by linking two separate translation units that each `#include "animus.hpp"`; the execution-interop demo routed 500,000 simulated orders at 8,464,120 orders/sec with a 90.16 ns average / 100 ns p99 `submit()` latency. See `AnimusCore_v1/BENCHMARKS.md` for the full Phase 7 benchmark breakdown.
+
+## Phase 8: Enterprise Security & Multi-Tenancy
+
+Two independent, composable layers add RBAC, tenant isolation, and encrypted transport on top of the header-only engine, without touching its hot path:
+
+* **RBAC + multi-tenant isolation (`AnimusCore_v1/animus_security.hpp`):** `TenantRegistry` gives every tenant its own isolated `Engine` -- separate ring buffer, rule set, and persistence file -- so isolation is structural, not a filter applied after the fact. `SecureTelemetryGateway` is the only entry point: every call carries an `AccessToken` (tenant + role), is checked against a `Role`/`Permission` lattice (`Viewer` / `Operator` / `Admin`), routed only to that token's own tenant, and logged -- allowed or denied -- to an independent audit trail. Portable C++17, no platform dependency.
+* **mTLS / TLS 1.3 transport (`AnimusCore_v1/animus_transport.hpp`):** a Windows-native Schannel (SSPI) transport with mandatory mutual authentication in both directions and manual certificate-chain verification against a private, in-memory-only CA trust anchor. A verified client certificate's subject CN is mapped to an `AccessToken` *only after* its chain is confirmed trusted -- so tenant/RBAC routing downstream is keyed to a cryptographically proven identity, never a value the client merely asserts. Built on the OS-native TLS provider rather than a third-party library, keeping the "zero external dependency" property intact on Windows.
+* **Demo certificates (`AnimusCore_v1/generate_demo_certs.ps1`):** generates a self-signed demo CA plus server/client leaf certificates using only native Windows PKI cmdlets -- no OpenSSL. Certificates and keys are written to `AnimusCore_v1/demo_certs/` (gitignored; never commit private key material).
+
+```bash
+# Generate demo certs, then build and run the RBAC/tenancy and mTLS demos
+# (PowerShell, then an "x64 Native Tools Command Prompt for VS"):
+powershell -File AnimusCore_v1/generate_demo_certs.ps1
+cl /std:c++17 /EHsc /O2 AnimusCore_v1/secure_multitenancy_demo.cpp
+cl /std:c++17 /EHsc /O2 AnimusCore_v1/secure_transport_demo.cpp
+secure_multitenancy_demo.exe
+secure_transport_demo.exe
+```
+
+Verified: the RBAC/tenancy demo confirmed tenant isolation (a second tenant's viewer sees 0 of another tenant's signals), fail-closed behavior against an unknown tenant id, and correct denial of unentitled actions, all captured in an independent audit trail. The mTLS demo negotiated real TLS 1.3 with mutual certificate authentication over loopback TCP and delivered 20,000/20,000 frames at 144,748 frames/sec through the RBAC/tenancy layer above; a negative-path test confirmed a same-CN certificate signed by an untrusted CA is rejected before any frame is processed. See `AnimusCore_v1/BENCHMARKS.md` for the full Phase 8 benchmark breakdown, including two real defects found and fixed during verification.
+
+## Phase 9: Distributed Cloud Orchestration & Clustering
+
+A Raft-lite consensus layer clusters multiple engine nodes over the same mTLS transport Phase 8 established, without pulling in gRPC/Protobuf:
+
+* **Inter-node sync over mTLS, not gRPC (`AnimusCore_v1/animus_cluster.hpp`):** given the choice between real gRPC+Protobuf (this project's first external build dependency) and a custom binary RPC reusing Phase 8's Schannel transport, the latter was chosen explicitly to keep the "zero external dependency" property intact. `SecureChannel` gained generic length-prefixed message framing (`send_message`/`recv_message`) alongside its existing fixed-size telemetry `WireFrame` to carry Raft's variable-length `AppendEntries` calls.
+* **Raft-lite leader election & replication:** `RaftNode` implements randomized-timeout election, log-consistency-checked replication with conflict truncation, and the "commit only current-term entries" safety rule -- real Raft, not a stub, just without durable log storage or snapshotting (see the header's documented limitations). Each node keeps its telemetry ingestion fully local and zero-copy; only control-plane `AddRule` commands go through consensus, so every node's rule set converges without touching the hot path.
+* **High-availability failover:** cluster membership is static and every node dials every other node over its own mTLS connection. Killing the current leader is detected via election timeout by the survivors, who elect a new leader and keep replicating -- proven with a real node shutdown mid-run, not a simulated clock.
+
+```bash
+# Generate demo certs (now includes 3 cluster-node identities), then build and run
+# (PowerShell, then an "x64 Native Tools Command Prompt for VS"):
+powershell -File AnimusCore_v1/generate_demo_certs.ps1
+cl /std:c++17 /EHsc /O2 AnimusCore_v1/cluster_demo.cpp
+cluster_demo.exe
+```
+
+Verified across 25 consecutive runs (100% pass): a 3-node cluster elects exactly one leader (~500 ms average), a proposed rule replicates to a majority and is confirmed *functionally* on all three independently-running engines (not just as a log entry), a follower correctly redirects a write attempt to the real leader, and killing the leader triggers a real re-election (~716 ms average) after which the survivors keep replicating correctly. See `AnimusCore_v1/BENCHMARKS.md` for the full Phase 9 benchmark breakdown, including four real defects found and fixed during verification -- among them a genuine Raft correctness gap (a new leader unable to commit an inherited pre-term entry without a no-op anchor) that was live-reproduced in roughly 1 in 5 failover runs before being fixed.
+
+## Phase 10: Final Commercial Packaging & Single-Header Release
+
+Animus Core ships as a single distributable artifact per platform: one header for C++ integrators, one wheel for Python integrators, both regenerated from source rather than hand-maintained.
+
+* **Single-header release (`AnimusCore_v1/animus_release.hpp`):** `AnimusCore_v1/amalgamate.py` concatenates all four source headers (`animus.hpp`, `animus_security.hpp`, `animus_transport.hpp`, `animus_cluster.hpp`) into one self-contained file -- a client vendors one `#include`, not four with an inter-file include order to get right. The Windows-only transport/cluster sections are gated on `defined(_WIN32) && defined(_MSC_VER)`, not just `_WIN32`, so the same single header still compiles the portable core engine + RBAC layer under MinGW `g++` (verified with a real build and run) while correctly reserving the Schannel-based sections for MSVC, where their certificate loading actually works.
+* **Python SDK, PyPI-ready:** an MIT `LICENSE`, PyPI classifiers, and `Documentation`/`Issues` project URLs were added to `pyproject.toml`; a real `pip wheel . --no-deps` build was installed into a fresh isolated venv (no sibling source checkout) and imported successfully, with the native `AnimusCore_v1.dll` bundled inside the wheel.
+* **Multi-node write-latency benchmark (`AnimusCore_v1/cluster_latency_bench.cpp`):** a new benchmark against the Phase 9 cluster, distinct from Phase 9's election/failover timing -- it measures the latency a client actually experiences on every write (`RaftNode::propose()`'s majority-commit latency) separately from full-cluster (not just majority) convergence latency, since conflating them would misrepresent both.
+* **Client quickstart guides (`AnimusCore_v1/QUICKSTART.md`):** four proof-of-concept guides -- Python SDK, C++ single header, secure multi-tenant + mTLS, and distributed cluster -- each layering on the previous, with every code sample either compiled and run for real or checked against the current method signatures in the source headers.
+
+```bash
+# Regenerate the single header after touching any of the 4 source headers,
+# then verify it (from an "x64 Native Tools Command Prompt for VS"):
+python AnimusCore_v1/amalgamate.py
+cl /std:c++17 /EHsc /O2 AnimusCore_v1/release_header_smoke_test.cpp
+release_header_smoke_test.exe
+
+# Build and run the multi-node latency benchmark:
+cl /std:c++17 /EHsc /O2 AnimusCore_v1/cluster_latency_bench.cpp
+cluster_latency_bench.exe
+```
+
+Verified: the amalgamated header was real-compiled and run with both MSVC (all four layers) and MinGW `g++` (portable core + RBAC layer, correctly excluding the Windows-only sections); the wheel build/install/import cycle succeeded end-to-end in a fresh venv; five consecutive cluster-latency-benchmark runs completed with zero failed proposals, showing sub-millisecond p50 majority-commit write latency (0.120-0.377 ms across runs) and full-cluster convergence latency clustering tightly around the 30 ms heartbeat interval. See `AnimusCore_v1/BENCHMARKS.md` for the full Phase 10 benchmark breakdown, including two real defects found and fixed while building the header generator (an under-broad include-stripping regex that caused a genuine type-redefinition compile error, and a guard that checked only `_WIN32` when the code it protected actually required MSVC specifically).
+

animus_engine_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+animus/AnimusCore_v1.dll,sha256=cQZJF5vFGKUZxXr04jY_c1xvfjGu9QtHEqj9WTlmxmY,37376
+animus/__init__.py,sha256=DC-5UPrc47Tngesv552OnLKAePPxSvVzClsU7zliwNE,372
+animus/bindings.py,sha256=IbFRG7uhcTXeepmhUM3aYCwdkdfhnG8e24C_UCvlZtI,6312
+animus/core.py,sha256=4OGLDKsav9MAZrsSZvpRkqYYq7l3AKj26RcU_5DOai8,1132
+animus/decorators.py,sha256=tBLQWezGQSSOR_IzIoUjI2ZE7vRilaQ6O8_s44Wckwo,3887
+animus/shm.py,sha256=MdeAc_wucwIIoAUE4rGMaLQjD7u2ZEiezWQiNTAV4hw,6157
+animus_engine_sdk-1.0.0.dist-info/licenses/LICENSE,sha256=TjTi8qdTYGzi3KKsDsoq2qZFOvoP1n2u62sPH3gZA5c,1072
+animus_engine_sdk-1.0.0.dist-info/METADATA,sha256=GkvHG9WVQ9oIJgqTH7C5-CFXtwOMdkDWK2He-UPD6DA,17168
+animus_engine_sdk-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+animus_engine_sdk-1.0.0.dist-info/top_level.txt,sha256=ZBU9RNexa_2e2fpjC8gdKdvsdeImH6MgLUonkds71LA,7
+animus_engine_sdk-1.0.0.dist-info/RECORD,,

animus_engine_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

animus_engine_sdk-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alakshendra Roy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

animus_engine_sdk-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+animus