silver-ai 0.1.0

Deterministic State-Guardrails for Agentic Hardware

🛡️ SilverAi

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?"

🚨 The Problem

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.

⚡ The Solution

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.

✨ Key Features

• 🐍 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.

---

🚀 Quick Start

Installation

pip install silver-ai

Usage: Protecting a Robot

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"),
        on_fail="raise" # Make the script to crash (e.g., during unit tests).
    )
    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",
  "code": "SAFETY_BLOCK",
  "reason": "Operation blocked: Battery level 10% is below minimum threshold 15%. Device is OFFLINE.",
  "suggestion": "Charge device and re-establish BLE connection."
}

🏛️ Architecture

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]

🎯 Domain Modules

While architected for Robotics, the state machine of SilverAi is universal.

🤖 IoT / Robotics Module

@guard(rules.MaxTemp(80), rules.DeviceIdle())
def firmware_update(self): ...

💸 FinTech / E-Commerce Module

Prevent Chatbots from hallucinating prices or authorizing large transactions.

@guard(
    rules.TransactionLimit(50.00), 
    rules.AllowedDomains(["official-store.com"])
)
def generate_payment_link(self, amount): ...

🧪 Simulation & Testing (No Hardware Required)

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.test import DryRun
from my_robot import IndustrialRobot

def test_safety_stops_low_battery():
    # 1. Mock a dangerous state
    dangerous_state = {"battery": 5, "connection": "online"}
    
    # 2. Run the function in "Dry Run" mode (skips real hardware)
    result = DryRun(IndustrialRobot.start_operation, state=dangerous_state)
    
    # 3. Assert that SilverAi caught it
    assert result['success'] is False
    assert "Battery" in result['reason']

🛠️ Development on Local Machine

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

1. Prerequisities

• Python 3.11+;
• Poetry installed.

  pip install poetry
  

2. Setup

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

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

3. Running the Demo

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

poetry run python demo.py

4. Running

We use pytest for unit testing.

poetry run pytest

5. Linting & Security

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

poetry run ruff check .

🤝 Contributing

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