edge-cortex

<p align="center"> <img src="docs/assets/edge-cortex-hero.svg" alt="Edge-Cortex: a wind turbine dissolving into a neuro-symbolic circuit core" width="100%"> </p> <h1 align="center">Edge-Cortex</h1> <p align="center"><b>A neuro-symbolic decision OS that runs a wind farm on its own, and proves every decision.</b></p> <p align="center"> <a href="https://jtzanetatos.github.io/edge-cortex/"><img alt="Live demo" src="https://img.shields.io/badge/live_demo-offline_replay-27E0E8?style=flat-square&logo=githubpages&logoColor=071018"></a> <a href="LICENSE"><img alt="License: AGPL v3" src="https://img.shields.io/badge/license-AGPLv3-b06cf5?style=flat-square&logo=gnu&logoColor=white"></a> <img alt="Python" src="https://img.shields.io/badge/python-3.13-27E0E8?style=flat-square&logo=python&logoColor=white"> <img alt="PyTorch" src="https://img.shields.io/badge/PyTorch-2.12-b06cf5?style=flat-square&logo=pytorch&logoColor=white"> <img alt="ONNX Runtime" src="https://img.shields.io/badge/ONNX_Runtime-1.26-1FE0A0?style=flat-square&logo=onnx&logoColor=071018"> <img alt="DSPy" src="https://img.shields.io/badge/DSPy-3.2-b06cf5?style=flat-square"> <img alt="Ollama" src="https://img.shields.io/badge/Ollama-local_LLMs-27E0E8?style=flat-square&logo=ollama&logoColor=white"> <img alt="NiceGUI" src="https://img.shields.io/badge/NiceGUI-3.12-1FE0A0?style=flat-square"> <img alt="FLORIS" src="https://img.shields.io/badge/FLORIS-4.6-F5A623?style=flat-square"> <img alt="DuckDB" src="https://img.shields.io/badge/DuckDB-audit_log-F5A623?style=flat-square&logo=duckdb&logoColor=071018"> <br> <img alt="Apple Silicon" src="https://img.shields.io/badge/tested-Apple_Silicon_M4_24GB-27E0E8?style=flat-square&logo=apple&logoColor=white"> <img alt="Linux CUDA" src="https://img.shields.io/badge/tested-Linux_·_RTX_5060_16GB-1FE0A0?style=flat-square&logo=nvidia&logoColor=071018"> <img alt="Status" src="https://img.shields.io/badge/status-competition_prototype-b06cf5?style=flat-square"> </p> --- Edge-Cortex runs a wind farm on its own and proves every decision. Three neural surrogates (failure, power, wake) feed a symbolic optimisation layer of LP, MILP and a payback gate. A two-agent LLM pipeline turns farm state into deterministic tool calls, and an autonomous watchdog runs that pipeline when the state crosses a threshold. Every neural claim is checked against FLORIS physics before it can act. It runs locally on small quantised LLMs served by Ollama, with the surrogates compiled to ONNX, so nothing in the control loop needs the cloud. > Try it with no install: an offline replay of the operations HUD runs at > [the live demo](https://jtzanetatos.github.io/edge-cortex/), a baked snapshot of the real > replay week with no backend. Source in [`site/`](site/). ### Isolation The acting agents (Director and Operations) have no operator input path. There is no command box and no way to inject an instruction into the pipeline; it runs only on watchdog triggers. Operators observe, and ask questions through a separate read-only assistant. So there is no autonomous action a human can socially-engineer or prompt-inject into existence, because there is no input to attack. --- ## What it does It predicts failure per turbine with a Liquid Neural Network, giving remaining useful life and 7, 30 and 60-day failure odds with a calibrated conformal interval. It optimises dispatch and wake steering against live market prices using a trust-region LP whose objective gradients are the FNO wake-coupling Jacobian plus the KAN own-power diagonal. It acts on its own when the state crosses a threshold, then vetoes itself two ways. No plan executes if FLORIS disagrees on the sign of the gain, and none executes if the payback gate decides the wind will not hold long enough to repay the actuator wear. Both vetoes live in the tool, which withholds the setpoints itself. Every decision, autonomous or not, is written to DuckDB with replay-time and stays queryable by the agent itself. --- ## Architecture <p align="center"> <img src="docs/assets/architecture.svg" alt="Edge-Cortex architecture: the autonomous watchdog fires the Director then Operations pipeline, which calls the neural surrogates, the FLORIS physics oracle and the optimisers, emitting an EXECUTE or RECOMMEND decision with confidence into the DuckDB audit log and feeding back to SCADA. Below an isolation boundary, operators reach only a read-only assistant that reads live state and never commands the agents." width="100%"> </p> A process-wide `ReplayClock` ties every component to the same simulated "now", so the dashboard, the acting pipeline, and the watchdog all ingest ENTSO-E prices, Open-Meteo weather, and Kelmarsh SCADA windows for the *same* moment in the demo timeline. The coupling runs both ways: the neural side writes the optimiser's objective, the symbolic side vetoes the neural side. | Layer | What | Role | |---|---|---| | Neuro | LNN, KAN, FNO surrogates (ONNX, custom Fourier ops) | Fast enough to call inside an optimiser loop | | Symbolic | Trust-region LP, day-ahead MILP, payback gate, FLORIS oracle | Exact optimisation and the physics veto | | Agentic | Director and Operations pipeline, autonomous watchdog | Turns state into typed tool calls, decides when to act | --- ## Models Served as ONNX via `core/inference.py`. Weights are git-ignored (export them locally, see [docs/SETUP.md](docs/SETUP.md)); a missing weight is non-fatal and the panel falls back to a badged synthetic source. | Model | Type | Role | |---|---|---| | LNN-RUL | Liquid Time-Constant network | Per-turbine RUL + P(fail 7/30/60 d) with an attention readout; trained on ~28 M rows of Kelmarsh SCADA | | KAN-Power | Kolmogorov-Arnold network | Analytical-symbolic `P(wind, yaw)`; supplies own-power gradients to the LP | | FNO-Wake | Tensorised Fourier Neural Operator | 128×128 farm wake-velocity field; supplies cross-turbine coupling | | DCFF-MTAD | Multivariate anomaly detector | Per-turbine anomaly scores vs a learned threshold | | Fault-Graph | Graph autoencoder | Correlated common-cause detection + source attribution over the turbine graph | | FLORIS | Engineering wake physics (not learned) | Ground-truth validator for every wake claim | Two details for credibility. The FNO is physically anchored: sampled half a rotor diameter upwind of each rotor and converted through the real NREL power curve, it lands within about 9% of FLORIS with steering deltas consistent in sign and magnitude. The LNN's uncertainty is a distribution-free 90% conformal interval, shown to the operator. --- ## Autonomous functionality A deterministic watchdog (`agents/autonomous_director.py`, not an LLM) watches the replay clock for 9 triggers across 6 families. When one fires it runs the Director and Operations pipeline on a background thread. If the result is `EXECUTE` and confidence is at least `0.70` the action stands, tagged `⚡ EXECUTED`; otherwise it is logged as `◆ RECOMMENDED`. | Trigger | Family | Fires when | |---|---|---| | `rul_imminent` | Reliability | P(fail ≤ 7 d) > 0.70 for any turbine | | `rul_warning` | Reliability | P(fail ≤ 30 d) > 0.60, newly crossed | | `anomaly_rca` | Anomaly | a turbine's DCFF-MTAD score ≥ 85% of its threshold | | `anomaly_correlated` | Anomaly | the fault-graph autoencoder flags a common-cause event (falls back to ≥ 2 flagged) | | `price_spike` | Market | \|price − 24 h mean\| > 2σ | | `wake_loss` | Wake | farm-wide wake deficit ≥ 6% | | `wind_shift` | Weather | \|Δ direction\| > 30° within an hour | | `ops_review` | Scheduled | periodic operational-review heartbeat | | `daily_schedule` | Scheduled | once-per-replay-day planning pass | Each trigger debounces so a sustained condition fires once, and a single-flight gate stops pipeline calls queueing. Every decision is logged to DuckDB, pushed to the Recent Autonomous Actions strip, and rendered in the console with a purple `AUTONOMOUS` badge. --- ## The two agents and the assistant The Director is a reasoning model (`qwen3.5:4b-mxfp8`) running DSPy `ChainOfThought`, prompt-compiled. It turns one trigger into a strict, validated task spec whose `intent` must be one of seven closed values. It plans and does not execute. Operations is a tool-calling model on the same resident weights, running DSPy `ReAct`. It executes the task spec by orchestrating 22 tools on one MCP server in a Thought, Action, Observation loop, then summarises while citing tool-derived numbers only, and emits a structured EXECUTE or RECOMMEND decision with a calibrated confidence. The read-only assistant is a separate lightweight model (`lfm2.5-thinking:1.2b`) that answers operator questions and writes reports from live state. It takes no actions and has no path into the acting pipeline. ## Tool server and stack All 22 tools live on one stdio MCP server (`mcp_servers/server.py`); `agents/mcp_client.py` holds a single session to it for the life of the process. Run it standalone with `python -m mcp_servers.server`. Built on Python 3.13, PyTorch 2.12 with Lightning, `neuraloperator` 2.0, `ncps` (LNN), ONNX Runtime 1.26 with a native Fourier spectral-conv operator, DSPy 3.2 with Ollama, FLORIS 4.6, Polars 1.41, DuckDB 1.5 and NiceGUI 3.12. The offline demo in [`site/`](site/) is vanilla HTML/CSS/JS with Apache ECharts, no build step. --- ## Quick start ```bash ./start.sh ``` `start.sh` starts Ollama if needed, pulls and warms both models, and launches the dashboard at <http://127.0.0.1:8080>. First run needs the models, weights and data in place: see [docs/SETUP.md](docs/SETUP.md) for the full install, Docker, and how to drive the replay. ```bash uv run pytest -q # 122 passed, 1 skipped uv run ruff check . ``` ## Docs - [docs/SOLUTION.md](docs/SOLUTION.md) how it works, layer by layer, and the repository map - [docs/UI_FEATURES.md](docs/UI_FEATURES.md) what each dashboard panel shows - [docs/SETUP.md](docs/SETUP.md) install, run, Docker, tuning, operating the demo - [docs/DATA.md](docs/DATA.md) data sources, provenance, licensing - [eval/README.md](eval/README.md) how the per-role LLMs were chosen ## License AGPLv3 (see [`LICENSE`](LICENSE)): use, study, modify and self-host freely, but distributing it or offering it over a network obliges you to release your complete corresponding source under the same terms. Copyright © 2026 jtzanetatos (tzanetatosi@gmail.com). Commercial or closed-source use needs a separate paid license from the copyright holder; attribution alone does not grant commercial rights. Contact the author to arrange one. ## Acknowledgements Kelmarsh SCADA ([Zenodo](https://zenodo.org/records/8252025)), NREL reference turbine, ENTSO-E Transparency Platform, Open-Meteo, and the Ollama, DSPy, NiceGUI, ncps, neuraloperator and FLORIS projects.