regulator.ai

# Vienna OS

```
██╗   ██╗██╗███████╗███╗   ███╗███╗   ██╗ █████╗      ██████╗ ███████╗
██║   ██║██║██╔════╝████╗ ████║████╗  ██║██╔══██╗    ██╔═══██╗██╔════╝
██║   ██║██║█████╗  ██╔████╔██║██╔██╗ ██║███████║    ██║   ██║███████╗
╚██╗ ██╔╝██║██╔══╝  ██║╚██╔╝██║██║╚██╗██║██╔══██║    ██║   ██║╚════██║
 ╚████╔╝ ██║███████╗██║ ╚═╝ ██║██║ ╚████║██║  ██║    ╚██████╔╝███████║
  ╚═══╝  ╚═╝╚══════╝╚═╝     ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝     ╚═════╝ ╚══════╝
```

[![npm](https://img.shields.io/npm/v/@vienna-os/sdk?color=cb3837&logo=npm)](https://www.npmjs.com/package/@vienna-os/sdk)
[![License](https://img.shields.io/badge/License-BSL%201.1-blue.svg)](LICENSE)
[![Build Status](https://img.shields.io/github/actions/workflow/status/risk-ai/regulator.ai/ci.yml?branch=main&logo=github)](https://github.com/risk-ai/regulator.ai/actions)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![GitHub Stars](https://img.shields.io/github/stars/risk-ai/regulator.ai?style=social)](https://github.com/risk-ai/regulator.ai/stargazers)

**The governance layer AI agents answer to.**

Vienna OS is the first execution control plane designed specifically for autonomous AI systems. It sits between agent intent and execution, ensuring every action is validated, authorized, and auditable before it happens.

---

## The Problem

AI agents are increasingly autonomous — managing cloud infrastructure, executing financial trades, controlling IoT devices, and making business decisions. But most agentic systems today operate without meaningful governance:

- **🚨 No pre-execution validation** — Agents can cause damage before anyone notices
- **⚠️ No risk-based authorization** — High-stakes actions get the same treatment as low-risk ones
- **📝 No verifiable audit trails** — When something goes wrong, there's no clear record of what happened or who authorized it
- **🔒 No policy enforcement** — Governance rules exist in documentation, not in the execution path

This creates an unacceptable risk profile for production AI systems handling real-world consequences.

**Vienna OS changes that.**

---

## What Vienna OS Does

Vienna OS implements a **governance-first architecture** that creates a control plane between AI agent intent and actual execution. Every agent action flows through a standardized pipeline:

```
┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌──────────────┐
│   AI Agent  │───▶│   Gateway    │───▶│   Policy    │───▶│   Warrant    │
│  (Intent)   │    │ (Validation) │    │  (Evaluation)│    │(Authorization)│
└─────────────┘    └──────────────┘    └─────────────┘    └──────────────┘
                                                                   │
                                                                   ▼
┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌──────────────┐
│ Audit Trail │◀───│   Executor   │◀───│ Verification│◀───│ Risk Assessment│
│ (Evidence)  │    │ (Execution)  │    │ (Attestation)│    │  (Tier T0-T3) │
└─────────────┘    └──────────────┘    └─────────────┘    └──────────────┘
```

Instead of agents executing actions directly, they submit **intents** to Vienna OS, which:
1. **Validates** the request structure and source
2. **Evaluates** it against policy rules  
3. **Classifies** risk tier and approval requirements
4. **Issues warrants** for approved high-risk actions
5. **Executes** through controlled adapters
6. **Verifies** completion and generates audit evidence
7. **Maintains** cryptographic proof of governance

---

## Key Features

### 🔐 **Cryptographic Warrants**
Time-limited, scoped execution tokens using HMAC-SHA256 signatures that bind together:
- Current system state preconditions
- Specific execution plan
- Authorized operator approval
- Rollback procedures

### ⚡ **4-Tier Risk Classification**
| Tier | Risk Level | Approval Process | Examples |
|------|------------|------------------|----------|
| **T0** | Minimal | Auto-approve | Health checks, read operations |
| **T1** | Moderate | Single operator approval | Deployment, config changes |
| **T2** | High | Multi-party approval + MFA | Financial transactions, data deletion |
| **T3** | Critical | Board-level approval | Major infrastructure changes |

### 🛠️ **Policy-as-Code Engine**
Visual policy builder with 11 operators (==, !=, >, <, contains, etc.) for creating governance rules without code deployment:

```javascript
IF action == "wire_transfer" 
AND payload.amount > $50000
THEN require_approval tier=T2
     AND notify channels=[compliance, cfo]
     AND require_mfa=true
```

### 📡 **Real-Time SSE Event Streaming**
Server-sent events for live monitoring of all agent activities, policy matches, and approval workflows

### 🏢 **Multi-Tenant Architecture**
Row-level security with tenant isolation, supporting multiple organizations on a single Vienna OS instance

### 🔧 **TypeScript + Python SDKs**
Native language bindings for seamless integration:

```typescript
// TypeScript
import { ViennaClient } from '@vienna-os/client';
const vienna = new ViennaClient({ endpoint: 'https://vienna.company.com' });
await vienna.submitIntent('deploy_service', { service: 'api', version: '1.2.3' });
```

```python
# Python
from vienna_os import ViennaClient
vienna = ViennaClient(endpoint='https://vienna.company.com')
await vienna.submit_intent('deploy_service', {'service': 'api', 'version': '1.2.3'})
```

### 🤖 **Framework Integrations**
Pre-built integrations for popular agent frameworks:
- **OpenClaw** — Governance middleware for agent skills
- **LangChain** — Custom tool wrapper with Vienna validation
- **CrewAI** — Crew-level approval workflows  
- **AutoGen** — Multi-agent conversation governance

### 🛡️ **SOC 2 Controls Documentation**
Built-in compliance reporting and audit trail generation for security certifications

### ⚖️ **USPTO Patent Protection**
Core governance algorithms protected under Patent Application #64/018,152

---

## Architecture Overview

```
                             ┌─────────────────────────────────────────┐
                             │              VIENNA OS                  │
                             └─────────────────────────────────────────┘
                                              │
                                              ▼
    ┌─────────────┐      ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
    │   Agent     │────▶ │   Gateway   │────▶ │   Policy    │────▶ │   Risk      │
    │   Intent    │      │ Validation  │      │   Engine    │      │   Tier      │
    └─────────────┘      └─────────────┘      └─────────────┘      └─────────────┘
           │                     │                     │                     │
           │                     ▼                     ▼                     ▼
    ┌─────────────┐      ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
    │ Audit Trail │◀──── │   Warrant   │◀──── │  Executor   │◀──── │Verification │
    │  Evidence   │      │ Generation  │      │ (Adapters)  │      │ & Attestation│
    └─────────────┘      └─────────────┘      └─────────────┘      └─────────────┘
```

**Flow:**
1. **Agent** submits execution intent
2. **Gateway** validates schema and source identity
3. **Policy Engine** evaluates against governance rules
4. **Risk Tier** classification determines approval requirements
5. **Warrant** issued for T1-T3 actions (T0 auto-approved)
6. **Executor** runs action through secure adapters
7. **Verification** generates cryptographic execution proof
8. **Audit Trail** maintains immutable evidence chain

---

## Quick Start

### Installation

```bash
npm install @vienna-os/core
```

### Basic Usage

```javascript
import { Vienna } from '@vienna-os/core';

// Initialize Vienna OS client
const vienna = new Vienna({
  endpoint: 'https://your-vienna-instance.com',
  apiKey: process.env.VIENNA_API_KEY
});

// Submit an agent intent
const result = await vienna.submitIntent({

[truncated…]