{"id":48434039,"url":"https://github.com/kretski/microsafe-rl","last_synced_at":"2026-04-06T12:02:23.706Z","repository":{"id":348975205,"uuid":"1199388288","full_name":"Kretski/MicroSafe-RL","owner":"Kretski","description":"Proprietary Edge AI safety engine for Reinforcement Learning. Implements real-time Operational Stability Signatures to prevent hardware failure on microcontrollers (STM32/ESP32)","archived":false,"fork":false,"pushed_at":"2026-04-03T17:13:40.000Z","size":7741,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T19:00:37.966Z","etag":null,"topics":["bare-metal","edge-ai","embedded","fault-tolerance","real-time","reinforcement-learning","robotics","safe-rl","stm32","tinyml"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kretski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T09:52:22.000Z","updated_at":"2026-04-03T17:46:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"278419e9-d44a-412f-88bc-e977f49469b8","html_url":"https://github.com/Kretski/MicroSafe-RL","commit_stats":null,"previous_names":["kretski/microsafe-rl"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Kretski/MicroSafe-RL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kretski%2FMicroSafe-RL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kretski%2FMicroSafe-RL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kretski%2FMicroSafe-RL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kretski%2FMicroSafe-RL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kretski","download_url":"https://codeload.github.com/Kretski/MicroSafe-RL/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kretski%2FMicroSafe-RL/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31471469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bare-metal","edge-ai","embedded","fault-tolerance","real-time","reinforcement-learning","robotics","safe-rl","stm32","tinyml"],"created_at":"2026-04-06T12:02:20.357Z","updated_at":"2026-04-06T12:02:23.695Z","avatar_url":"https://github.com/Kretski.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛡️ MicroSafe-RL\n\n**Deterministic Sub-Microsecond Safety Layer for Edge AI \u0026 Robotics**\n\nMicroSafe-RL is an ultra-lightweight, bare-metal C++ interceptor designed to protect physical hardware from Reinforcement Learning (RL) instability and Edge LLMs \"hallucinations\".\n\n## 📈 Executive Summary\n\nRL policies trained in simulation often produce out-of-range commands when deployed on real hardware. This library \"clamps\" these commands **deterministically** in **O(1)** time before they reach the execution engine.\n\n| Metric                        | Value                                          |\n|-------------------------------|------------------------------------------------|\n| **Worst-Case Latency (WCET)** | 1.18 µs (Cortex-M3 @ 72 MHz)                   |\n| **RAM Footprint**             | 24 bytes, zero dynamic allocation              |\n| **Compliance**                | MISRA-C:2012 (Zero Critical Violations)        |\n| **Complexity**                | O(1) constant time per step                    |\n\n## 🎬 Demonstration Video\n\nSee MicroSafe-RL in action, preventing critical failure in real time:\n\n[▶ Watch Demo](media/demo.mp4)\n\n## 🛡️ How It Works\n\nThe interceptor monitors the signal behavior using an **Exponential Moving Average (EMA)**. When the input command deviates significantly from the established baseline, a \"gravity factor\" is applied to smoothly return the command to the safe operating zone.\n\n$$\npenalty = \\kappa \\times (EMA\\_MAD + \\alpha \\times (1 - coherence) + 0.3 \\times velocity)\n$$\n\n$$\ngravity = \\max(0, 1 - penalty \\times g)\n$$\n\n$$\nsafe\\_out = clip(ai\\_action \\times gravity, min\\_limit, max\\_limit)\n$$\n\n$$\nreward = 1 - penalty\n$$\n\n**Hard Shield**: The hard clip (`min_limit` / `max_limit`) is always active from the very first step, ensuring safety even before the EMA has collected sufficient history.\n## 🔗 Integration with Local AI Bots / Edge LLMs\n\nMicroSafe-RL now includes a **Python-C++ Bridge** that enables seamless and safe connection with local Large Language Models.\n\n### Supported Use Cases\n- Using **Ollama** (Gemma 4, Llama 3.2, Phi-4, Mistral, etc.) as a robotic controller\n- Running local vision-language models for perception + reasoning\n- Edge LLM agents that output high-level actions (velocity, torque, joint targets)\n\nThe bridge forwards the LLM-generated action to MicroSafe-RL, which applies deterministic safety clamping before the command reaches the hardware. This combination gives you the flexibility and intelligence of a local LLM while maintaining sub-microsecond physical safety guarantees.\n\n### Example Bridge Usage (Python)\n\n```python\nimport ollama\nfrom microsafe_bridge import MicroSafeBridge\n\nsafety_bridge = MicroSafeBridge(\n    model_name=\"gemma:2b\",          # or any local model via Ollama\n    safety_params={\"kappa\": 0.078, \"alpha\": 0.55, ...}\n)\n\nwhile True:\n    prompt = get_current_observation()   # sensor data, camera, etc.\n    response = ollama.chat(model=\"gemma:2b\", messages=[{\"role\": \"user\", \"content\": prompt}])\n    \n    try:\n        ai_action = parse_action(response['message']['content'])   # extract float/vector\n        safe_action = safety_bridge.apply(ai_action)               # MicroSafe-RL protection\n        actuator_command(safe_action)\n    except:\n        # fallback to safe default\n        actuator_command(0.0)\n## 📊 Benchmark Results\n\nTested against a Kalman-filter detector and a PLC threshold system across 120 scenarios (runaway, adversarial, and safe conditions).\n\n| System              | Mean Detection Margin (steps before failure) | Std Dev |\n|---------------------|----------------------------------------------|---------|\n| **MicroSafe-RL**    | 19.2                                         | ±1.4    |\n| Kalman-filter       | 11.0                                         | ±1.6    |\n| PLC threshold       | 8.0                                          | ±0.7    |\n\n**Hardware Validation** (Arduino Uno + MPU-6050):  \nAverage end-to-end intercept latency — 3.2 ms, with **1.18 µs** pure computational latency of the protection algorithm.\n\n## 🧪 Integration Example (Embedded C++)\n\n```cpp\n#include \"MicroSafeRL_misra.h\"\n\n// Parameters: kappa, alpha, decay, beta, g, min, max, vel_weight\nMicroSafeRL safety(0.078f, 0.55f, 2.2f, 0.12f, 1.0f, -1.5f, 1.5f, 0.05f);\n\nvoid loop() {\n    float safe_val = safety.apply_safe_control(ai_action, sensor_val);\n    float reward   = safety.get_current_reward();\n\n    actuator.set(safe_val);\n    agent.update(reward);\n}\n⚠️ Limitations\n\nWarm-up Period: EMA requires approximately 20 calibration steps. During this time, only the hard clip is active.\nHardware Protection: This is a software safety layer and does not replace physical protections such as fuses and current limiters.\nTuning: Parameters (κ, α, g, etc.) significantly affect behavior and should be profiled for the specific hardware.\n\n🔬 Academic Status\nSubmitted for Review:\n\"A Control Lyapunov Metric for Autonomous Fault Recovery in Embedded and Aerospace Systems\" — IEEE Transactions on Aerospace and Electronic Systems.\nPreprint:\nKretski, D. (2026). ORAC-NT v5.x: Optimal and Stable FDIR Architecture. Zenodo.\nDOI: 10.5281/zenodo.19019599\n📬 Licensing\n\nMIT License for academic and non-commercial use.\nFor production deployment in safety-critical systems, please contact: kretski1@gmail.com\n\n\nReady to copy and paste.\nLet me know if you want any changes (shorter version, badges, different tone, etc.)!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkretski%2Fmicrosafe-rl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkretski%2Fmicrosafe-rl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkretski%2Fmicrosafe-rl/lists"}