README.md

---
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}
}
```