# relari-ai/agent-contracts architecture

> Architecture diagram of the GitHub repository relari-ai/agent-contracts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/relari-ai/agent-contracts
- Repository: https://github.com/relari-ai/agent-contracts

## Overview

##### Project Type & Purpose
- The project is a middleware/verification framework that acts as a contract-based guard for AI systems.
- Its primary purpose is to enforce formal verification (offline and runtime) and certification of AI agents by checking defined behavioral contracts.
- The README indicates that contracts are defined, verified offline (via test runs) and further processed in runtime certification scenarios, integrating tools like Docker, Relari OTEL, and Jaeger.

##### High-Level Components & Their Roles
- Agent Contracts Core (agent_contracts/core):
- Contains the definitions for data types (specifications, trace, and verification), configuration management, and prompt templates.
- Manages the representation of preconditions, pathconditions, and postconditions, and defines how contracts are structured and processed.
- Certification Module (agent_contracts/certification):
- Handles runtime certification and configuration for certifying the ongoing behavior of AI agents.
- Includes supporting elements like configuration and protocol definitions for runtime verification.
- CLI Interface (agent_contracts/cli.py):
- Provides command-line utilities for listing runs, triggering verifications, and other interactions with the framework.
- Integrations (agent_contracts/integrations):
- Contains adapters for external systems such as Jaeger and StackAI. These scope out how to integrate the framework with external tracing and monitoring tools.
- Prompts and TUI (agent_contracts/prompts and agent_contracts/tui):
- Jinja2 templates to generate and customize messages or prompts for verifying preconditions, pathconditions, and postconditions.
- TUI files suggest a simple text-based user interface for interacting with parts of the system.
- Configuration & Deployment:
- The configs folder and multiple docker-compose files indicate deployment scenarios and runtime configuration for both verification and certification modes.
- The Makefile and pyproject.toml show toolchain integrations and build/deployment automation.

##### Relationships and Interactions
- The main “core” contracts creation and verification engine make extensive use of the datatypes in the core module to structure contracts.
- The CLI (and likely the TUI) provide entry points for developers to trigger both offline verification and runtime certification.
- The integrations serve as connectors to external systems (like Jaeger) for telemetry and tracing.
- When a contract is defined (using the specifications and scenario patterns), it is then passed to the verification engine that interacts with (or simulates) an agent’s behavior, collects traces, and validates outcomes against the predefined contracts.
- The runtime certification process invoked via a separate docker-compose flow uses configurations from the certification module to check the trace data in real time.
- Utility modules assist across these components (for logging, generating IDs, telemetry, etc.).

##### Architectural Patterns and Design Principles
- Modular design: The separation of concerns is clear from the distinct directories for core, certification, integrations, and prompts.
- Layered architecture: Lower-level utilities support core functionalities, which then feed into higher-level services like verification and certification.
- Extensibility: The presence of clear integration points (e.g., for Jaeger and external telemetry) suggests the framework is designed to be extended with additional integrations as needed.
- Configuration-driven: Multiple configuration files and YAML/JSON support indicate that the system behavior is highly configurable via external files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces Subgraph
    subgraph "User Interfaces"
        CLI("CLI Interface"):::ui
        TUI("TUI Interface"):::ui
    end

    %% Core Modules Subgraph
    subgraph "Core Modules"
        Core("Core Contracts Module (Validation & Specifications)"):::core
        Prompts1("Core Prompts"):::core
        Prompts2("Prompts Module"):::core
        Util("Utilities (Telemetry & Helpers)"):::core
    end

    %% Standalone Certification Engine
    Certification("Certification Engine (Runtime Verification)"):::cert

    %% Standalone Integrations
    Integrations("Integrations (External Services)"):::integration

    %% Configuration & Deployment Subgraph
    subgraph "Configuration & Deployment"
        Configs("Configs Folder"):::config
        Docker("Docker Compose"):::config
        DockerCert("Docker Compose Certification"):::config
    end

    %% Connections
    CLI -->|"initiate"| Core
    TUI -->|"initiate"| Core
    Core -->|"verifyContracts"| Certification
    Core -->|"exportTelemetry"| Integrations
    Integrations -->|"feedback"| Core
    Configs -->|"configure"| Core
    Docker -->|"deploy"| Certification
    DockerCert -->|"deploy"| Certification

    %% Styles
    classDef ui fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef core fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef cert fill:#9acd32,stroke:#333,stroke-width:2px;
    classDef integration fill:#ffb347,stroke:#333,stroke-width:2px;
    classDef config fill:#d3d3d3,stroke:#333,stroke-width:2px;

    %% Click Events
    click Core "https://github.com/relari-ai/agent-contracts/tree/main/agent_contracts/core"
    click CLI "https://github.com/relari-ai/agent-contracts/blob/main/agent_contracts/cli.py"
    click TUI "https://github.com/relari-ai/agent-contracts/tree/main/agent_contracts/tui"
    click Certification "https://github.com/relari-ai/agent-contracts/tree/main/agent_contracts/certification"
    click Integrations "https://github.com/relari-ai/agent-contracts/tree/main/agent_contracts/integrations"
    click Prompts1 "https://github.com/relari-ai/agent-contracts/tree/main/agent_contracts/core/prompts"
    click Prompts2 "https://github.com/relari-ai/agent-contracts/tree/main/agent_contracts/prompts"
    click Util "https://github.com/relari-ai/agent-contracts/tree/main/agent_contracts/core/utils"
    click Configs "https://github.com/relari-ai/agent-contracts/tree/main/configs"
    click Docker "https://github.com/relari-ai/agent-contracts/blob/main/docker-compose.yaml"
    click DockerCert "https://github.com/relari-ai/agent-contracts/blob/main/docker-compose.certification.yaml"
```
