--- license: apache-2.0 doi: 10.57967/hf/10549 language: - en tags: - edge-ai - industrial-ai - scientific-computing - embedded-ai - signal-processing - digital-signal-processing - predictive-maintenance - condition-monitoring - vibration-analysis - anomaly-detection - industrial-iot - iiot - telemetry - edge-computing - tinyml - on-device-learning - embedded-systems - machine-health - time-series - python - typescript - c library_name: sofia-engine --- # Sofia Engine — Scientific & Edge Intelligence Runtime Developed by **Rootcastle Engineering & Innovation** Canonical Source Repository: [github.com/rootcastleco/sofia-ai](https://github.com/rootcastleco/sofia-ai) Project Homepage: [rootcastle.com](https://rootcastle.com/) DOI: [10.57967/hf/10549](https://doi.org/10.57967/hf/10549) Storage Bucket: [huggingface.co/buckets/rootcastleengineering/sofia-bucket](https://huggingface.co/buckets/rootcastleengineering/sofia-bucket) --- ## 1. Overview **Sofia Engine** is an open-source scientific and edge intelligence runtime developed by Rootcastle Engineering & Innovation for deterministic physical telemetry processing, industrial signal analysis, machine-health diagnostics, bounded edge inference, and safety-gated technical automation. Operating under the engineering principle **"Evidence beats claims"**, Sofia Engine combines: - **Scientific DSP**: FFT, Welch PSD, Hilbert analytic amplitude envelope, and Fortescue 3-phase symmetrical components. - **Physical Telemetry Ingestion**: Bounded, unit-bearing telemetry frames with quality status (`GOOD`, `DEGRADED`, `SATURATED`). - **Versioned Feature Extraction**: 14+ statistical and spectral features packaged in ordered, reproducible `FeatureVector` contracts (Schema v3.0). - **Evidence-Based Diagnostics**: Noisy-OR evidence aggregation and machine health scoring with explicit uncertainty bands ($0-100 \pm \Delta$). - **Embedded & Edge Execution**: Hardened virtual machine (`SofiaAsmVM`), C99 zero-allocation microcontroller implementation, and experimental in-situ backpropagation. - **Safety & Policy Gating**: Strict default-DENY policy engine, Nonce + TTL replay protection, and an **actuation firewall that strictly isolates external LLMs from physical machinery**. > [!NOTE] > **Canonical Pretrained Checkpoint Status:** > No canonical pretrained Sofia checkpoint is distributed in this release. This repository provides the Sofia model/runtime specification, machine-readable manifests, reproducible examples, and future checkpoint distribution interfaces. When pre-trained foundation models are released, they will be published with complete training datasets, evaluation reports, and SHA-256 digests. --- ## 2. Subsystem Maturity Table Maturity levels are assigned strictly based on verifiable implementation and test coverage: | Subsystem | Status | Verification & Evidence | | :--- | :--- | :--- | | **Scientific DSP** | **Stable** | Parseval energy conservation verified; exact amplitude recovery to $< 10^{-14}$; 5 golden vector tests passed. | | **Telemetry Runtime** | **Stable** | Memory capacity ceilings ($\le 65536$), timestamp plausibility, unit alias normalization, IEEE 754 non-finite rejection. | | **Diagnostic Engine** | **Stable** | Deterministic Noisy-OR fusion; dynamic uncertainty intervals; quality attenuation on degraded signals. | | **Policy Engine & Replay Guard** | **Stable** | Default-DENY posture; Nonce + TTL monotonic replay protection; LLM actuation firewall; secret scrubbing. | | **Embedded C99 Runtime** | **Stable** | Zero dynamic heap allocation post-init (`malloc` prohibited); Q16.16 fixed-point arithmetic; static ceilings. | | **Sofia Assembly VM** | **Beta** | Memory and register bounds checking; cycle ceilings; structured execution result (`VMExecutionResult`). | | **In-Situ Neural Training** | **Experimental** | 2-layer analytical backpropagation in virtual assembly; validated against finite differences ($< 10^{-5}$ error). | | **Cross-Language Conformance** | **Beta** | Python, TypeScript SDK (`@rootcastle/sofia-engine`), and C99 verified against identical golden vectors. | | **LLM Copilot Integration** | **Optional** | Strictly advisory technical assistance; isolated from deterministic control core and physical actuators. | | **Quantum Emulation** | **Experimental** | Educational statevector simulation and VQE parameter exploration. | | **Native Code Generation** | **Experimental** | Preliminary x86_64 AVX2, ARM Cortex-M Thumb-2, and WebAssembly emission stubs. | --- ## 3. Architecture & Data Flow ```mermaid flowchart LR S["Physical Sensors"] --> I["Telemetry Ingestion"] I --> Q["Validation & Signal Quality"] Q --> B["Bounded Buffers"] B --> D["Scientific DSP"] D --> F["Versioned Feature Vector"] F --> M["Inference Backends"] M --> E["Evidence Fusion"] E --> H["Diagnostics & Health"] H --> P["Policy Engine"] P --> O["Advisory / Controlled Output"] ``` **Key Architectural Invariant:** External LLMs (OpenAI, NVIDIA NIM, OpenRouter) operate exclusively as optional copilots at Layer 10. They have no read or write access to the deterministic signal processing or policy enforcement layers. --- ## 4. Scientific Scope & Calculations Sofia Engine implements calculations relevant to industrial engineering standards: - **Mechanical Vibration:** Implements calculations relevant to ISO 10816 / ISO 20816 vibration severity evaluation (RMS, peak, crest factor, kurtosis, skewness). - **Spectral Analysis:** Discrete Fourier Transform (one-sided FFT magnitude), Welch's averaged periodogram with window gain corrections, spectral centroid, spectral entropy, and spectral flatness. - **Envelope Demodulation:** Hilbert transform analytic signal for bearing defect and gear-mesh modulation extraction. - **Electrical Power Quality:** Implements calculations relevant to IEEE 519 and IEC 61000-4-30 analysis, including True RMS, Active/Reactive/Apparent Power, Total Harmonic Distortion (THD), and Fortescue 3-phase symmetrical components ($V_0, V_1, V_2, \text{VUF}$). - **Process Telemetry:** Thermal rates of change ($dT/dt$), pulsation peak-to-peak, and fluid pressure crest factors. *Note: Software implementation does not constitute formal laboratory certification. Operational deployment requires qualified engineering calibration.* --- ## 5. Installation ### Core Runtime (NumPy Only) ```bash pip install sofia-engine ``` ### Industrial Telemetry Integrations (MQTT, Modbus, Serial) ```bash pip install "sofia-engine[industrial]" ``` ### From Canonical Source ```bash git clone https://github.com/rootcastleco/sofia-ai.git cd sofia-ai pip install -e . ``` --- ## 6. Reproducible Examples Executable scripts are maintained in the [`examples/`](https://huggingface.co/rootcastleengineering/sofia/tree/main/examples) directory: - [`examples/basic_inference.py`](https://huggingface.co/rootcastleengineering/sofia/raw/main/examples/basic_inference.py): Signal window packaging, 14-feature extraction, threshold anomaly detection, and evidence-based health scoring. - [`examples/signal_analysis.py`](https://huggingface.co/rootcastleengineering/sofia/raw/main/examples/signal_analysis.py): FFT magnitude, Welch PSD with Parseval energy conservation check, Hilbert analytic envelope, and Fortescue symmetrical components. - [`examples/edge_runtime.py`](https://huggingface.co/rootcastleengineering/sofia/raw/main/examples/edge_runtime.py): Bounded `SignalFrame`, Sofia Assembly VM execution, in-situ neural training step, and safe `sofia.model.v1` serialization. To execute the basic inference example: ```bash python examples/basic_inference.py ``` --- ## 7. Model Manifests & Checkpoint Policy Hugging Face distribution files are machine-readable and schema-validated: - [`config.json`](https://huggingface.co/rootcastleengineering/sofia/raw/main/config.json): Runtime capabilities, Python version, and dependency requirements. - [`model_manifest.json`](https://huggingface.co/rootcastleengineering/sofia/raw/main/model_manifest.json): Conforms to [`schemas/model.schema.json`](https://huggingface.co/rootcastleengineering/sofia/raw/main/schemas/model.schema.json). - [`runtime_manifest.json`](https://huggingface.co/rootcastleengineering/sofia/raw/main/runtime_manifest.json): Exact Git commit SHA, dependency versions, latency budgets, and subsystem maturity. ### Checkpoint Policy - **Zero-Pickle Invariant:** Model weights must be distributed in `.safetensors` or `.npz` format. Python `pickle` is strictly prohibited. - **Cryptographic Verification:** Every model artifact must declare its lowercase SHA-256 parameter digest. - See [`artifacts/README.md`](https://huggingface.co/rootcastleengineering/sofia/raw/main/artifacts/README.md) for full details. --- ## 8. Empirical Performance Benchmarks Measured on Profile A hardware (Intel64 x86_64, Windows 11, Python 3.12.10 CPython) across $N = 100$ iterations: | Metric | Measured $p_{50}$ | Target Budget | Result | | :--- | :--- | :--- | :--- | | **FFT / Welch PSD (1024 samples)** | **$307.6\,\mu\text{s}$** | $\le 500\,\mu\text{s}$ | **PASS** | | **FFT / Welch PSD (4096 samples)** | **$387.4\,\mu\text{s}$** | $\le 2000\,\mu\text{s}$ | **PASS** | | **Analytic Envelope (2048 samples)** | **$127.8\,\mu\text{s}$** | $\le 1000\,\mu\text{s}$ | **PASS** | | **Symmetrical Components (Fortescue)** | **$55.5\,\mu\text{s}$** | $\le 1500\,\mu\text{s}$ | **PASS** | | **Peak Memory Consumption** | **$7.14\text{ MB}$** | $\le 32\text{ MB}$ | **PASS** | Complete benchmark reports and JSON schema are available in [`benchmarks/`](https://huggingface.co/rootcastleengineering/sofia/tree/main/benchmarks). --- ## 9. Safety & Limitations - **Engineering Judgment:** Sofia Engine outputs are diagnostic aids. They do not replace physical inspection or qualified engineering sign-off. - **Physical Safety Interlocks:** Under no circumstance should AI or diagnostic outputs directly control machinery without external, hardware-certified safety interlocks (e.g. SIL relays). - **Sensor Calibration:** Diagnostic accuracy is bounded by sensor fidelity, mounting configuration, and signal acquisition quality. - Read [`docs/LIMITATIONS.md`](https://huggingface.co/rootcastleengineering/sofia/raw/main/docs/LIMITATIONS.md) and [`docs/SECURITY.md`](https://huggingface.co/rootcastleengineering/sofia/raw/main/docs/SECURITY.md) for detailed boundaries. --- ## 10. Citation To cite Sofia Engine in scientific software, publications, or engineering documentation: ```bibtex @software{sofia_engine_2026, author = {{Rootcastle Engineering \& Innovation}}, title = {Sofia Engine: Scientific \& Edge Intelligence Runtime}, year = {2026}, version = {3.0.0a1}, publisher = {Hugging Face}, doi = {10.57967/hf/10549}, url = {https://huggingface.co/rootcastleengineering/sofia} } ```