<div align="center">

⚡ PRINCIPIA ROBOTICA

Lex Prima: Safety is not a feature. It is the law.

World-first unified MCP gateway + Control Barrier Function (CBF-QP) safety engine for agentic robotics.

Give Claude, GPT-4o, Gemini, and any LLM mathematically proven safe control over physical robots via ROS2.

---

Created: July 29, 2026 · Author: Abdullah Bin Zafar · UET Lahore, Pakistan

"What Newton's Principia was to classical mechanics, this is to the laws governing AI-controlled machines."

</div>

---

🌍 Why This Exists (The Problem)

Every AI agent — Claude, GPT-4o, Gemini — can be told to drive a robot. But none of them can mathematically guarantee safety. They can crash, over-accelerate, collide, or violate physical limits. There was no open-source bridge between LLM intelligence and control-theoretic safety.

Until now.

---

🔬 What This Is (The World-First Innovation)

Existing World	After Principia Robotica
AI sends cmd_vel. Robot may crash.	AI's command is intercepted by CBF-QP solver. Safe command issued.
No formal safety guarantee	∀t≥0: h(x(t)) ≥ 0 — mathematically proven forward invariance
Safety = hope + testing	Safety = formal theorem (Ames et al., proven 2017)
MCP server = passive sensor reader	MCP server = active safety enforcer
Pre-simulation not available	Certify trajectory BEFORE hardware moves

---

📐 The Mathematics (The Core Law)

The CBF-QP Safety Filter solves this problem in real-time (< 1ms in Python):

$$u^* = \arg\min_{u \in \mathcal{U}} \frac{1}{2}|u - u_{\text{AI}}|^2$$

$$\text{subject to:} \quad L_f h(x) + L_g h(x) u \geq -\alpha(h(x))$$

Where:

• $u_{\text{AI}}$ = command from AI agent (Claude, GPT-4o, Gemini...)
• $h(x)$ = Control Barrier Function (encodes obstacle avoidance)
• $L_f h$, $L_g h$ = Lie derivatives along robot dynamics
• $\alpha: \mathbb{R} \to \mathbb{R}$ = class-K function (typically $\alpha(h) = \gamma h$)

Result: The robot receives the closest safe command to what the AI wanted. Formally proven optimal by KKT conditions.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    AI Agent (Claude / GPT-4o / Gemini)          │
│                    Tools: cbf_filter_velocity,                   │
│                           predict_safe_trajectory,              │
│                           lyapunov_stability_check, ...         │
└──────────────────────────┬──────────────────────────────────────┘
                           │  MCP stdio (JSON-RPC 2.0)
┌──────────────────────────▼──────────────────────────────────────┐
│               PRINCIPIA ROBOTICA MCP SERVER                     │
│  ┌──────────────────┐   ┌──────────────────┐   ┌────────────┐  │
│  │  CBF-QP Solver   │   │ Kinematic World  │   │ Lyapunov   │  │
│  │  (CVXPY + OSQP)  │   │ Model (1000Hz)   │   │ Stability  │  │
│  │  < 1ms Python    │   │ Trajectory Sim   │   │ Analyzer   │  │
│  └────────┬─────────┘   └────────┬─────────┘   └─────┬──────┘  │
│           └────────────────────┬─┘                   │         │
└────────────────────────────────┼─────────────────────┘─────────┘
                                 │  ROS2 Bridge (optional)
┌────────────────────────────────▼─────────────────────────────────┐
│         ROS2 Middleware — /cmd_vel_raw → [CBF] → /cmd_vel        │
│                        ↑ /odom (live state)                      │
└──────────────────────────────────────────────────────────────────┘
                                 │
┌────────────────────────────────▼─────────────────────────────────┐
│              PHYSICAL ROBOT (TurtleBot4 / Spot / Custom)         │
└──────────────────────────────────────────────────────────────────┘

---

🎨 Interactive Web Visualizer Dashboard (1-Second Demo)

Launch the 60 FPS live HTML5 Canvas + Web GL simulator in your browser with a single command:

python -m principia.server --ui

• Live Obstacle Field: Drag and drop circular obstacles in real-time.
• AI Command Interceptor: Adjust AI linear/angular velocity sliders to observe real-time CBF-QP minimal perturbation filtering.
• Multi-Mode Support: Unicycle differential drive, Quadrotor 2D altitude floor, Swarm fleet inter-robot collision check, and Dynamic moving obstacles.
• Visual Telemetry: Real-time $h(x)$ safety gauge, Lyapunov energy $V(x)$ plot, and predicted trajectory path.

---

🛠️ 1-Second Installation & Setup

git clone https://github.com/EngineerAbdullahBinZafar/principia-robotica
cd principia-robotica
pip install -e .

Verify everything works instantly:

python -m principia.server --doctor

---

⚡ Quickstart (3 Commands)

1. Run the MCP server:

python -m principia.server

2. Test the CBF filter directly in Python:

import numpy as np
from principia.cbf_engine import (
    DifferentialDriveModel, CircularObstacleCBF, CBFQPSafetyFilter
)

robot = DifferentialDriveModel()
obstacle = CircularObstacleCBF(obstacle_x=2.0, obstacle_y=0.0, obstacle_radius=0.5)
safety_filter = CBFQPSafetyFilter(
    robot=robot,
    cbfs=[obstacle],
    u_min=np.array([-0.5, -2.5]),
    u_max=np.array([1.5, 2.5]),
)

# Robot at (1.2, 0) heading toward obstacle at (2.0, 0)
x = np.array([1.2, 0.0, 0.0])
u_ai = np.array([1.5, 0.0])  # AI wants full speed ahead

result = safety_filter.solve(x, u_ai)

print(f"AI proposed:  v={u_ai[0]:.2f} m/s")
print(f"Safe command: v={result['u_safe'][0]:.2f} m/s")
print(f"Was modified: {result['was_modified']}")
print(f"Solve time:   {result['solve_time_ms']:.2f} ms")

3. Add to your AI client (Claude Desktop / Cursor):

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "principia-robotica": {
      "command": "python",
      "args": ["-m", "principia.server"],
      "cwd": "/path/to/principia-robotica"
    }
  }
}

---

🔧 MCP Tools (13 Total)

Tool	Type	Description
cbf_filter_velocity	🔴 WORLD-FIRST	Real-time CBF-QP safety filter for velocity commands
predict_safe_trajectory	🔴 WORLD-FIRST	Pre-simulate + certify trajectory before hardware moves
lyapunov_stability_check	🔴 WORLD-FIRST	Real-time Lyapunov stability verification
cbf_quadrotor_altitude	🔴 WORLD-FIRST	CBF altitude safety for quadrotors
minimal_perturbation_proof	🔴 WORLD-FIRST	Formal KKT proof of minimum-norm safety correction
clf_cbf_qp_solver	🔴 WORLD-FIRST	Unified Control Lyapunov + Control Barrier QP solver
swarm_cbf_fleet_safety	🔴 WORLD-FIRST	Multi-robot swarm inter-agent collision & barrier check
dynamic_obstacle_cbf	🔴 WORLD-FIRST	CBF safety filter for dynamic moving obstacles
get_cbf_spatial_map	🔴 WORLD-FIRST	ASCII radar safety map of surrounding obstacle space
batch_cbf_filter	🔴 WORLD-FIRST	Parallel batch CBF velocity filter for multi-robot fleets
get_cbf_safety_report	✅	Full safety audit of current robot state
principia_status	✅	Server status and capability report
principia_benchmark	✅	QP solver performance benchmark

---

🧬 File Structure

principia-robotica/
├── principia/
│   ├── __init__.py           # Package metadata
│   ├── server.py             # MCP JSON-RPC 2.0 server (entry point)
│   ├── cbf_engine.py         # CBF-QP solver + robot models
│   ├── world_model.py        # Kinematic trajectory predictor + Lyapunov
│   ├── tools.py              # MCP tool handler functions
│   ├── ros2_bridge.py        # ROS2 live integration (optional)
│   └── theory_and_proofs.py  # Complete mathematical derivations
├── tests/
│   └── test_principia.py     # Full test suite
├── docs/
│   └── THEORY.md             # LaTeX-formatted mathematical proofs
├── mcp_config.json           # MCP client configuration template
├── pyproject.toml            # Package metadata + build config
├── LICENSE                   # MIT + attribution clause
└── README.md                 # This file

---

📊 Performance Benchmarks

Operation	Time	Frequency
CBF margin evaluation	< 0.01 ms	> 100,000 Hz
Early exit (safe command)	< 0.05 ms	> 20,000 Hz
CBF-QP solve (CVXPY/OSQP)	< 2 ms	> 500 Hz
Trajectory pre-simulation (3s horizon)	< 5 ms	> 200 Hz
Lyapunov check	< 0.1 ms	> 10,000 Hz

Real-time control loops run at 50–200 Hz. This engine operates at > 500 Hz. ✅

---

📚 Mathematical References

1. Ames, A.D., Xu, X., Grizzle, J.W., Tabuada, P. (2017). Control barrier function based quadratic programs for safety critical systems. IEEE Transactions on Automatic Control, 62(8), 3861–3876.

2. Ames, A.D., Coogan, S., Egerstedt, M., et al. (2019). Control barrier functions: Theory and applications. European Control Conference.

3. Zafar, A.B. (2026). Principia Robotica: World-first unified MCP+CBF-QP agentic safety engine. GitHub. https://github.com/EngineerAbdullahBinZafar/principia-robotica

---

👤 Author

Abdullah Bin Zafar
UET Lahore, Pakistan
GitHub: @EngineerAbdullahBinZafar

If this helped you, please ⭐ the repo. It costs you nothing and means everything.

---

<div align="center">

© 2026 Abdullah Bin Zafar — MIT License
All derivative works must attribute the original author.

</div>