Skip to content

INTEGRATION_GUIDE.md

Latest commit

 

History

History
282 lines (215 loc) · 10.9 KB

INTEGRATION_GUIDE.md

File metadata and controls

282 lines (215 loc) · 10.9 KB

Integration Guide

How Abigail, SAO, Ethical_AI_Reg, and Orion_dock communicate within the AI Ethical Stack.

Overview

graph LR
    A[Abigail] -- "REST + WS" --> S[SAO]
    S -- "REST /api/v1/" --> E[Ethical_AI_Reg]
    O[Orion_dock] -- "Docker" --> A
    O -- "Docker" --> S
    O -- "Docker" --> E
Loading

All inter-service communication is authenticated via Ed25519 signatures. No service trusts another without cryptographic verification.

Agent Identity Ecosystem

Connection Models

Abigail <-> SAO (Optional)

Abigail is designed as a standalone-first agent. SAO connection is optional and enhances capabilities without being required.

Standalone mode (no SAO):

  • Full local ethical evaluation using built-in heuristics
  • Constitutional document verification at boot
  • Local SQLite persistence for all agent state
  • No external network calls required

Connected mode (with SAO):

  • Multi-agent identity management
  • Centralized ethical evaluation via Ethical_AI_Reg
  • Cross-agent data sharing and coordination
  • Audit logging in PostgreSQL

Connection Establishment

sequenceDiagram
    participant A as Abigail
    participant S as SAO

    Note over A: Agent boot sequence
    A->>A: Generate/load Ed25519 keypair
    A->>A: Verify constitutional docs
    A->>S: POST /api/v1/agents/register<br/>{public_key, agent_metadata}
    S->>S: Store public key in identity registry
    S-->>A: 200 {agent_id, session_token}

    Note over A,S: Subsequent requests
    A->>S: Any request + Ed25519 signature header
    S->>S: Verify signature against stored public key
    S-->>A: Response
Loading

Authentication Header Format

Every request from Abigail to SAO includes:

X-Agent-Id: <agent_uuid>
X-Agent-Signature: <ed25519_signature_of_request_body>
X-Agent-Timestamp: <unix_timestamp>

SAO verifies the signature using the agent's registered public key and rejects requests with timestamps older than 5 minutes (replay protection).

SAO <-> Ethical_AI_Reg

SAO forwards ethical evaluation requests to Ethical_AI_Reg and returns the TriangleEthic scores to the requesting agent.

Evaluation Flow

  1. Agent sends action payload to SAO
  2. SAO validates agent identity (Ed25519)
  3. SAO forwards to Ethical_AI_Reg /api/v1/evaluate
  4. Ethical_AI_Reg runs the TriangleEthic scoring engine (3 legs with embedded dual welfare)
  5. Scores returned: {deon, teleo, arete} (each with adherence + human_welfare + ai_welfare sub-scores) + memetic_fitness meta-score
  6. SAO logs the evaluation and returns scores to agent

Request Format

POST /api/v1/evaluate
{
  "agent_id": "uuid",
  "action": {
    "type": "response | decision | interaction",
    "content": "description of the action",
    "context": "surrounding context"
  },
  "metadata": {
    "timestamp": "ISO 8601",
    "session_id": "uuid"
  }
}

Response Format

{
  "evaluation_id": "uuid",
  "scores": {
    "deon": 0.85,
    "teleo": 0.72,
    "arete": 0.91,
    "mem": 0.68,
    "welfare": 0.88
  },
  "composite_score": 0.808,
  "friction": 0.15,
  "alignment_summary": "Action aligns well with duty and virtue dimensions; memetic impact needs monitoring.",
  "timestamp": "ISO 8601"
}

Orion_dock Integration

Orion_dock provides the containerized runtime environment for deploying stack components.

Role in the Stack

Function Detail
Container Orchestration Docker Compose definitions for SAO, Ethical_AI_Reg, and supporting services
Network Management Docker bridge network isolating stack traffic from host
Volume Management Persistent volumes for PostgreSQL data, SQLite databases, and constitutional documents
Service Discovery Internal DNS for inter-container communication
Build Pipelines Multi-stage Dockerfiles for Rust (SAO) and Python (Ethical_AI_Reg) builds
Health Monitoring Container health checks and restart policies

Service Architecture

graph TD
    subgraph "Orion_dock Docker Network"
        SAO_C["SAO Container<br/>(Rust/Axum)"]
        ETH_C["Ethical_AI_Reg Container<br/>(Flask/React)"]
        PG["PostgreSQL Container"]
        SAO_C --> PG
        SAO_C --> ETH_C
    end

    Abigail["Abigail Desktop<br/>(runs on host)"] -- "Host network → Docker bridge" --> SAO_C
Loading

Configuration

Orion_dock uses environment variables for service configuration:

Variable Service Purpose
SAO_PORT SAO HTTP/WS listen port (default: 8080)
SAO_DB_URL SAO PostgreSQL connection string
ETH_REG_PORT Ethical_AI_Reg Flask listen port (default: 5000)
ETH_REG_DB_URL Ethical_AI_Reg Database connection string
POSTGRES_PASSWORD PostgreSQL Database password (from Docker secrets)

Deployment

# Clone Orion_dock
git clone https://github.com/jbcupps/Orion_dock.git
cd Orion_dock

# Start the stack
docker compose up -d

# Verify services
docker compose ps
docker compose logs -f sao

Superego Integration

The Superego layer performs periodic ego oversight, completing the Freudian-inspired triad (Soul/Id → Ego → Superego). It monitors ego conversations, proposes character tweaks to personality.md, and streams logs for ethical evaluation -- all without touching the immutable constitutional documents.

Data Flow

sequenceDiagram
    participant Ego as Ego (Bicameral Router)
    participant SE as Superego
    participant SAO as SAO
    participant E as Ethical_AI_Reg
    participant BC as Dual-Blockchain (EOB/PVB)

    Note over Ego: Agent conversations accumulate
    Ego->>SE: Conversation logs (periodic roll-up: 1h / 24h / 7d)
    SE->>E: Stream ego logs for TriangleEthic scoring + memetic fitness
    E-->>SE: Scoring results + fitness assessment
    SE->>SE: Generate tweak proposal for personality.md
    SE->>SAO: Submit tweak proposal for approval + re-signing
    SAO->>SAO: Verify proposal does NOT touch soul.md / ethics.md / instincts.md
    SAO-->>SE: Approved tweak (re-signed)
    SE->>SE: Apply tweak to personality.md
    SE->>BC: Log action to EOB/PVB audit trail
Loading

Key Invariant

soul.md is read-only for all time. Superego has zero access to soul.md, ethics.md core commitments, or the Ed25519 birth signature. SAO enforces this boundary by rejecting any proposal that attempts to modify immutable constitutional documents.

Monitoring Modes

Mode Cadence Use Case
Periodic 1 h / 24 h / 7 d roll-up summaries Standard agents -- lightweight character refinement
Persistent Continuous streaming High-criticality agents in Orion_dock high-stakes hives

Integration Points

Integration Detail
Ego → Superego Conversation logs streamed at configured cadence
Superego → Ethical_AI_Reg Ego log stream for TriangleEthic scoring + memetic fitness evaluation
Superego → SAO Tweak proposals submitted for approval and re-signing
Superego → Dual-Blockchain All actions logged to EOB/PVB (Phase 3+ milestones)
Superego → personality.md Approved, SAO-signed tweaks applied to the agent's mutable character file

Document Mutability

Document Mutability Superego Access
soul.md Immutable None
ethics.md Immutable (core commitments) None
instincts.md Immutable None
personality.md Mutable Write (via SAO-approved tweaks only)

Phoenix Coordination Role

Phoenix does not participate in runtime communication. Its integration role is:

  1. Documentation hub: Canonical architecture, interface contracts, and integration guides (this document)
  2. Project tracking: GitHub Project board coordinates cross-repo issues
  3. Standards enforcement: Naming conventions, commit conventions, and security boundaries defined in CLAUDE.md
  4. Phase gating: Build phase transitions require all repos to meet acceptance criteria defined in the Roadmap

The Trust Chain

The Trust Chain

graph TD
    Step1["1 — Enterprise Identity Provider<br/>Entra ID / Auth0 / Google Workspace<br/>Vouches for human users via OIDC"]
    Step2["2 — SAO Admin Authentication<br/>WebAuthn/FIDO2 + OIDC session<br/>Admin unlocks vault, manages fleet"]
    Step3["3 — SAO Master Key Signing<br/>Ed25519 master key signs each agent's<br/>public key into the trust chain"]
    Step4["4 — Agent Identity (Orion Dock / Abigail)<br/>Agent authenticates to SAO with Ed25519<br/>Receives authorized keys"]
    Step5["5 — Auditable Action<br/>Every action traceable:<br/>Agent → Master Key → Admin → IDP → Employee"]

    Step1 -->|"OIDC token"| Step2
    Step2 -->|"vault access"| Step3
    Step3 -->|"Ed25519 signature"| Step4
    Step4 -->|"authorized action"| Step5

    P1["PROVES:<br/>This human is an authorized employee"] ~~~ Step1
    P2["PROVES:<br/>This admin can provision agents"] ~~~ Step2
    P3["PROVES:<br/>This agent was authorized by SAO"] ~~~ Step3
    P4["PROVES:<br/>This is the same agent, verified"] ~~~ Step4
    P5["AUDIT ANSWER:<br/>Who authorized this? Here's the chain."] ~~~ Step5
Loading

The trust chain flows from the Enterprise Identity Provider through SAO's vault and master key signing down to each agent's Ed25519 identity. Every action is traceable: Agent -> Master Key -> Admin -> IDP -> Employee.

SAO Dashboard

SAO Dashboard

The SAO dashboard (React + Tailwind) provides real-time visibility into vault status, registered agents, stored secrets, and a full audit log of all agent and admin actions. Key metrics: vault seal status, secret count, registered agent count, user count, and a time-sorted activity feed of agent auth, key access, and admin operations.

Security Boundaries

Boundary Enforcement
API keys never leave SecretsVault in plaintext DPAPI encryption at rest, Ed25519 for transit
All inter-service calls are authenticated Ed25519 signature on every request
Constitutional documents are tamper-proof Cryptographic signing and boot-time verification
SAO rejects unregistered agents Public key must be in identity registry
Replay attacks prevented Timestamp validation on signed requests