Deterministic State-Guardrails for Agentic Hardware & Critical Systems.

"You wouldn't let a drunk person drive a forklift. Why let a probabilistic LLM drive your physical hardware?"

Large Language Models (LLMs) like GPT-4, DeepSeek, and Claude are Probabilistic Engines. They are optimized for creativity, not safety.

When connecting Agents to Physical Hardware (IoT/Robotics) or Financial Systems, "99% accuracy" is not enough. A single hallucination can cause:

• Physical Damage: Ignoring battery/thermal limits on a device.
• Operational Failure: Attempting to control a disconnected device over BLE/MQTT.
• Financial Risk: Hallucinating discounts or executing unauthorized transactions.

Existing solutions (Bedrock Guardrails, NeMo) focus on Semantic Safety (profanity, PII). They are blind to State Safety.

SilverAi is a lightweight, dependency-free Python middleware that enforces Deterministic Contracts on your Agent's tools. It sits between the LLM's intent and your system's execution.

• 🐍 Pythonic Decorators: Clean, readable syntax using @guard.
• 🔌 Connectivity Gates: Prevents Agents from calling APIs when the device is offline (BLE, WiFi).
• 🔋 State-Aware: Validates against real-time telemetry (Battery, Heat) before execution.
• 🧪 Dry-Run Mode: Test your safety logic in CI/CD without requiring physical hardware or live APIs.

pip install silver-ai

Prevent an Agent from moving a robot if the battery is critical or the connection is unstable.

from silver_ai import guard, rules

class IndustrialRobot:
    def __init__(self):
        # In production, this state comes from live telemetry
        self.state = {
            "battery": 10, 
            "connection": "offline",
            "is_stuck": False
        }

    @guard(
        rules.BatteryMin(15),
        rules.RequireConnectivity(protocol="BLE")
        # rules.TransactionLimit(amount=50)
    )
    def start_operation(self, zone: str):
        # 🛑 This code NEVER runs because battery (10) < 15
        # AND the device is offline.
        hardware_driver.move_to(zone)

The Agent receives this structured rejection (instead of crashing):

{
  "status": "error",
  "reason": "Battery critical: 10%. Required: 15%.",
  "suggestion": "Connect device to charger before proceeding.",
  "dry_run": false
}

SilverAi acts as the "Prefrontal Cortex" for your Agent. It is a logical check before impulsive actions.

graph LR
    A[User Request] --> B[LLM / Agent]
    B -->|Unsafe Intent| C{SilverAi Guard}
    C -- Fails Rules --> D[Block & Explain]
    D -->|Feedback Loop| B
    C -- Passes Rules --> E[Execute Hardware API]

One of the hardest parts of IoT development is testing failure states (e.g., "What happens if the battery dies halfway?"). SilverAi provides a DryRun harness to test safety logic instantly.

graph TD
    Start[Agent Request] --> Check{Safety Rules}
    Check -- Unsafe --> Fail[Return Error]
    Check -- Safe --> Mode{Dry Run Active?}
    Mode -- Yes --> Dry[Return 'Success: Simulated']
    Mode -- No --> Real[Execute Real Hardware]

from silver_ai.core import DRY_RUN_FLAG
from my_robot import IndustrialRobot

def test_safety_stops_low_battery():
    # 1. Instantiate the robot
    robot = IndustrialRobot()
    
    # 2. Inject dangerous state
    robot.state = {"battery": 5, "connection": "online"}
    
    # 3. Enable Safety Override (Dry Run)
    # We manually flag this instance for simulation
    setattr(robot, DRY_RUN_FLAG, True)
    
    # 4. Run the function
    result = robot.start_operation("Zone A")
    
    # 5. Assert that SilverAi caught it
    assert result['status'] == 'error'
    assert "Battery" in result['reason']

This project uses Poetry for dependency management and Ruff for strict code quality.

• Python 3.11+;
• Poetry installed.

  pip install poetry

Clone the repo and install dependencies (including the virtual environment):

git clone https://github.com/gcl-team/SilverAi.git
cd SilverAi
poetry install

We provide a demo.py to showcase the behavior (Success, Failure, Dry Run, Exception).

poetry run python demo.py

We use pytest for unit testing.

poetry run pytest

We use ruff to enforce PEP8, import sorting, and Bandit security rules.

poetry run ruff check .

We welcome your contributions! Bug reports and feature suggestions are encouraged. Open issues or submit pull requests via Project Issues.