IRIS Ecosystem Overview

ELI5

Imagine a board of directors for AI agents. Each director is a “sprite” — a versioned, fingerprinted expert with a specific job (architect, reviewer, operator). They form a “council” with rules and a designated gatekeeper who can veto bad decisions. Work moves through the council as a “chain” of sequential steps. IRIS is the system that builds, registers, orchestrates, and audits these councils.

Technical Deep Dive

Full Repository Inventory

The iris-hq GitHub organisation owns 8 repositories spanning 3 tiers:

Entity Relationship

mindmap
  root((IRIS Ecosystem))
    Tier 1 -- IRIS Core
      Sprite Registry
      Council Orchestrator
      Chain Executor
      Gate Engine
    Tier 2 -- Choco Bridge
      MCP Server
      Documentation Sync
    Tier 3 -- MERIDIAN
      STRATT Federation
      Cross-System Verification
    Supporting
      iris-specs -- Schemas
      iris-web -- Docs
      SDKs -- Python + TS

Data Model Trinity

IRIS revolves around three top-level entities (mutually exclusive in iris.schema.json via oneOf):

External Integrations

flowchart TB
    subgraph Clients["Clients"]
        A[Python Scripts]
        B[Web Apps]
        C[Claude via MCP]
        D[MERIDIAN / STRATT]
    end
    subgraph Tier1["Tier 1: IRIS Core"]
        E[iris-service<br/>FastAPI]
    end
    subgraph Tier2["Tier 2: Bridge"]
        F[iris-mcp-server<br/>MCP over stdio]
    end
    subgraph Tier3["Tier 3: Federation"]
        G[iris-meridian-adapter<br/>gRPC]
    end
    subgraph Source["Source of Truth"]
        H[iris-specs<br/>JSON Schema + OpenAPI + Protobuf]
    end
    A -->|REST| E
    B -->|REST| E
    C -->|MCP| F
    F -->|REST| E
    D -->|gRPC| G
    G -->|REST| E
    H -.->|consumes| E
    H -.->|consumes| F
    H -.->|consumes| G

Key Terms

• Sprite → A versioned, fingerprinted AI agent definition with capabilities, system prompt, and role
• Council → A governance domain containing sprites, chains, rules, and exactly one gate authority
• Chain → A synchronous, ordered sequence of steps executed through council sprites
• Gate → A veto-capable checkpoint evaluated before, after, or on error within a chain
• Fingerprint → A Blake3 cryptographic hash of a canonical sprite representation (STRATT-compatible)
• MCP → Model Context Protocol; the bridge protocol used by Tier 2 to connect AI clients to IRIS
• MERIDIAN → The STRATT protocol’s council ecosystem; Tier 3 federates IRIS sprites into it

Q&A

Q: Why is the org called “iris-hq” and not just “iris”? A: It mirrors the naming convention of sibling orgs (stratt-hq, choco-hq, grace-hq) in the devarno-cloud ecosystem. “HQ” denotes the home organisation for a protocol or platform.

Q: Can I use IRIS without MERIDIAN or Choco? A: Yes. Tier 1 (IRIS Core) is fully standalone. Tiers 2 and 3 are optional bridges. Only iris-specs is a hard dependency for all tiers.

Q: How many programming languages are used across iris-hq? A: Two primary languages: Python (service, SDK, meridian adapter) and TypeScript (SDK, MCP server, web frontend). Schema definitions use YAML, JSON, and Protocol Buffers.

Q: What is the relationship between IRIS and STRATT? A: IRIS is an independent sprite system. The iris-meridian-adapter (Tier 3) bridges IRIS sprites into the MERIDIAN ecosystem, which is part of the broader STRATT protocol. They share Blake3 canonical fingerprinting for cross-system verification.

Examples

Think of IRIS like a theatre production company:

• Sprites are the actors, each with a specific script (system_prompt) and skills (capabilities)
• Councils are the production teams (director, lighting, sound, stage manager)
• Chains are the run-of-show: cue 1 → lights, cue 2 → sound, cue 3 → actors
• Gates are the stage manager who can yell “STOP!” if something unsafe is happening
• Fingerprints are the ID badges every actor wears — cryptographically verifiable so you know they are who they say they are