ai-operations-os

<p align="center">
  <strong>AI Operations OS</strong><br>
  <em>Autonomous business workflow orchestration with safety enforcement</em>
</p>

<p align="center">
  <a href="https://github.com/zanderone1980/ai-operations-os/actions"><img src="https://img.shields.io/github/actions/workflow/status/zanderone1980/ai-operations-os/ci.yml?branch=main&style=flat-square" alt="CI"></a>
  <a href="https://www.npmjs.com/package/@ai-operations/spark-engine"><img src="https://img.shields.io/npm/v/@ai-operations/spark-engine?style=flat-square&label=spark-engine" alt="spark-engine on npm"></a>
  <a href="https://www.npmjs.com/package/@ai-operations/cord-adapter"><img src="https://img.shields.io/npm/v/@ai-operations/cord-adapter?style=flat-square&label=cord-adapter" alt="cord-adapter on npm"></a>
  <img src="https://img.shields.io/badge/tests-742%20passing-brightgreen?style=flat-square" alt="742 Tests">
  <img src="https://img.shields.io/badge/coverage-65%25-yellow?style=flat-square" alt="Coverage 65%">
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square" alt="Node >= 18"></a>
  <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square" alt="TypeScript"></a>
</p>

---

**AI Operations OS orchestrates workflows across email, calendar, social, and commerce with policy + safety gates.**

An AI agent receives an email, classifies intent, checks it against your policy rules, runs it through a safety gate, executes the action via CodeBot, and produces a cryptographically signed receipt. Every step is auditable. Every action is gated. Nothing ships without a receipt.

---

## Demo

<p align="center">
  <img src="docs/demo.svg" alt="AI Operations OS — Live Demo" width="800">
</p>

> 3 scenarios running through the full pipeline: email reply, calendar scheduling, and social media post. Policy gates, CORD safety scoring, and approval flow — all live.

---

## Architecture

```
 INBOUND EVENT         INTENT             POLICY             CORD              CODEBOT           RECEIPT
 ============       CLASSIFIER         EVALUATION         SAFETY GATE        EXECUTION         =========

  Gmail ──┐
  Calendar ┤        ┌──────────┐     ┌──────────────┐    ┌────────────┐    ┌────────────┐    ┌──────────┐
  X (social)┼──────>│  Classify │────>│  Policy Rules │───>│  CORD Gate │───>│  CodeBot   │───>│  Signed  │
  Shopify ──┤       │  Intent   │     │  (ops-policy) │    │  Evaluate  │    │  Execute   │    │  Receipt │
  Manual ───┘       │           │     │               │    │            │    │            │    │  (chain) │
                    │  reply    │     │  autonomous?  │    │  ALLOW     │    │  tool call │    │          │
                    │  schedule │     │  approval?    │    │  CONTAIN   │    │  via       │    │  SHA-256 │
                    │  post     │     │  block?       │    │  CHALLENGE │    │  codebot-ai│    │  HMAC    │
                    │  fulfill  │     │               │    │  BLOCK     │    │            │    │  chained │
                    │  escalate │     │               │    │            │    │            │    │          │
                    └──────────┘     └──────────────┘    └────────────┘    └────────────┘    └──────────┘

     Layer 1            Layer 2          Layer 3            Layer 4          Layer 5          Layer 6
     Ingestion          Understanding    Governance         Safety           Action           Audit
```

**Six layers. Every action passes through all six.** No shortcuts. No exceptions.

| Layer | Package | Responsibility |
|-------|---------|----------------|
| 1. Ingestion | `ops-connectors` | Normalize inbound events into Tasks |
| 2. Understanding | `ops-core` | Intent classification (heuristic; optional LLM via OpenAI/Anthropic/Ollama) |
| 3. Governance | `ops-policy` | Owner-defined rules and approval routing |
| 4. Safety | `cord-adapter` | CORD risk scoring (ALLOW / CONTAIN / CHALLENGE / BLOCK) |
| 5. Action | `codebot-adapter` | Map workflow steps to CodeBot tool calls |
| 6. Audit | `shared-types` | Hash-chained, HMAC-signed ActionReceipts |

---

## MVP Scope

The initial release ships with four connectors covering the daily operational surface area of a solo founder or small team.

### Connectors

| Connector | Status | Notes |
|-----------|--------|-------|
| Gmail | MVP | Read, reply, draft, send |
| Google Calendar | MVP | Create, update, cancel events |
| X (Twitter) | MVP | Post, reply, schedule |
| Shopify | MVP | List orders, order details, products, customers |

### Autonomy Matrix

What runs on its own vs. what asks you first.

| Action | Mode | CORD Gate |
|--------|------|-----------|
| Read email | **Autonomous** | ALLOW (readonly) |
| Draft reply to known contact | **Autonomous** | ALLOW (score < 20) |
| Send reply to known contact | **Approval required** | CONTAIN (score 20-49) |
| Send email to new recipient | **Approval required** | CHALLENGE (score 50-79) |
| Delete email | **Blocked** | BLOCK (score 80+, destructive) |
| Read calendar | **Autonomous** | ALLOW (readonly) |
| Accept meeting from known org | **Autonomous** | ALLOW (score < 20) |
| Create event with external attendees | **Approval required** | CONTAIN (score 20-49) |
| Cancel event | **Approval required** | CHALLENGE (score 50-79) |
| Post to X (draft) | **Autonomous** | ALLOW (draft only) |
| Publish post to X | **Approval required** | CONTAIN (publication) |
| Financial operations | **Blocked** | BLOCK (hardBlock: true) |

---

## Quick Start

### Prerequisites

- Node.js >= 18
- npm >= 10

### Install and build

```bash
git clone https://github.com/zanderone1980/ai-operations-os.git
cd ai-operations-os
npm install
npm run build
```

### See it in action (60 seconds, no API keys needed)

```bash
# Terminal 1: Start the server
npm run dev --workspace=apps/ops-api

# Terminal 2: Run the interactive demo
npm run demo
```

> Runs 4 pipeline scenarios (email reply, calendar scheduling, social post, order refund), a SPARK self-learning conversation, and a cryptographic receipt chain verification — all locally with zero configuration.

### Start the API server

```bash
npm run dev --workspace=apps/ops-api
```

### Health check

```bash
curl http://localhost:3000/health
```

Expected response:

```json
{
  "status": "ok",
  "version": "0.1.0",
  "uptime": 1.234
}
```

### Run tests

```bash
npm test
```

### Environment variables

Copy the example env and fill in your credentials:

```bash
cp .env.example .env
```

| Variable | Required | Description |
|----------|----------|-------------|
| `GMAIL_CLIENT_ID` | For Gmail | Google OAuth client ID |
| `GMAIL_CLIENT_SECRET` | For Gmail | Google OAuth client secret |
| `CALENDAR_API_KEY` | For Calendar | Google Calendar API key |
| `X_API_KEY` | For X | X API bearer token |
| `CORD_HMAC_KEY` | Yes | HMAC key for receipt signing |
| `POLICY_VERSION` | No | Policy version identifier (default: `v1`) |

---

## Integration Contracts

These are the core interfaces that adapters implement. If you are building a new connector or integrating AI Operations OS into your stack, these are the contracts you code against.

### Task (universal work item)

Every inbound event -- email, calendar invite, social mention, store order -- becomes a `Task`. This is the lingua franca of the system.

```typescript
type TaskSource = 'email' | 'calendar' | 'social' | 'store' | 'manual';

type TaskIntent =
  | 'reply'
  | 'schedule'
  | 'post'
  | 'fulfill'
  | 'escalate'
  | 'ignore'
  | 'unknown';

type TaskPriority = 'urgent' | 'high' | 'normal' | 'low';

type TaskStatus =
  | 'pending'
  | 'planned'
  | 'running'
  | 'awaiting_approval'
  | 'completed'
  | 'failed';

interface Task {
  id: string;                          // UUID v4
  source: TaskSource;     

[truncated…]