# invariantlabs-ai/invariant architecture

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

- Interactive diagram: https://gitdiagram.com/invariantlabs-ai/invariant
- Repository: https://github.com/invariantlabs-ai/invariant

## Overview

##### Project type and purpose
- This is a Python‑based rule‑engine library and CLI/proxy called “Invariant Guardrails.”
- Purpose: sit between your application and LLM/MCP providers, intercepting and enforcing user‑defined guardrail rules at runtime (locally or via remote API).

##### File structure
Top‑level files/directories:
- invariant/__main__.py – CLI entry point (proxy/server launcher)
- invariant/analyzer/… – core rule‑engine implementation
– language/…         (parser, AST, linker, optimizer, typing)
– runtime/…          (evaluation context, functions, primitives, quantifiers, patterns, error handling)
– stdlib/…           (prebuilt detectors, builtins, parsers)
– policy.py, monitor.py, remote_policy.py, result.py, extras.py
– examples/…         (not part of runtime; demo notebooks and scripts)
- invariant/explorer/… – helper to launch the interactive playground/service
- tests/… – end‑to‑end and unit tests for analyzer and examples
- pyproject.toml, CI workflows, config files

##### README insights
- Describes architecture: acts as MCP/LLM proxy or library integration, applies rules before/after each tool call or message.
- Shows rule DSL, local vs. remote policy evaluation, and integration points with applications or Gateway.

##### Main components
A. Client Application Layer
- Your AI/agent application code
- Uses either:
– Invariant Gateway (HTTP proxy)
– Direct library calls to LocalPolicy/RemotePolicy API
B. Invariant Guardrails Layer
1. Entry Point (CLI or Python API)
– __main__.py or LocalPolicy.from_string()
2. Parser & Semantic Analyzer
– Builds AST from user rules (analyzer/language)
3. Policy Engine Core
– Policy objects, base rules (analyzer/policy.py)
4. Runtime Evaluator
– evaluation.py, evaluation_context, function_cache, nodes, patterns, quantifier, primitives
5. Standard Library
– ready‑made detectors and builtins (analyzer/stdlib/invariant)
6. Remote Policy Connector (optional)
– RemotePolicy → HTTP calls to Invariant API
C. External Services
- LLM or MCP providers (OpenAI, Azure, etc.)
- Invariant Guardrails API (if using RemotePolicy)
D. Outputs
- AnalysisResult with errors or passed flags
- Enforcement actions (block, modify, log)

##### Relationships and data flow
1. Application sends message or tool call →
2. Invariant entry point (proxy or LocalPolicy) intercepts →
3. Parses/applies guardrail rules via Analyzer:
a. Language parser → AST → Semantic checks →
b. Runtime evaluator executes patterns against trace (messages + tool calls) →
c. Stdlib detectors invoked as needed →
4. If configured, calls out to Invariant API via RemotePolicy →
5. Returns AnalysisResult →
6. Proxy either forwards to LLM/MCP (if no violation) or aborts/enforces rule

##### Architectural patterns and design principles
- Layered architecture: Presentation (CLI/Proxy), Core engine (Parser → Semantic → Runtime), Infrastructure (Remote API)
- Rule engine pattern: AST-based DSL, interpreter/evaluator
- Plugin/extensibility: stdlib detectors, user‑provided policies
- Separation of concerns: parsing, typing, linking, runtime evaluation

##### Relevant technologies/frameworks
- Python 3.x, packaging via pyproject.toml
- CLI via __main__.py
- AST/parser custom implementation (no external parser lib)
- HTTP client for remote policy
- Jupyter notebooks for examples
- GitHub Actions for CI, ruff for linting

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application Layer
    subgraph "Client Application Layer"
        direction TB
        ClientApp["Client Application"]:::app
    end

    %% Invariant Guardrails Layer
    subgraph "Invariant Guardrails" 
        direction TB

        EntryPoint["CLI/Proxy Launcher"]:::core
        LocalPolicy["LocalPolicy API"]:::core
        RemotePolicy["Remote Policy Connector"]:::core

        subgraph "Parser & Semantic Analyzer"
            direction TB
            Parser["Parser"]:::core
            AST["AST Definitions"]:::core
            Linking["Linking"]:::core
            Optimizer["Optimizer"]:::core
            TypeSystem["Type System"]:::core
            Typing["Typing"]:::core
            Scope["Scope Resolution"]:::core
        end

        subgraph "Policy Engine Core"
            direction TB
            PolicyDefs["Policy Definitions"]:::core
            Monitor["Policy Monitor"]:::core
            AnalysisResult["AnalysisResult Model"]:::core
            Extras["Extras"]:::core
        end

        subgraph "Runtime Evaluator"
            direction TB
            Evaluation["Evaluation"]:::core
            EvalContext["Evaluation Context"]:::core
            FuncCache["Function Cache"]:::core
            Functions["Primitive Functions"]:::core
            Primitives["Primitives Interface"]:::core
            InputHandling["Input Handling"]:::core
            NodesEval["AST Node Evaluator"]:::core
            Patterns["Pattern Matching"]:::core
            Quantifier["Quantifiers"]:::core
            RuleModel["Rule Runtime Model"]:::core
            RuntimeErrors["Runtime Errors"]:::core
            SymbolTable["Symbol Table"]:::core
            Utils["Utils"]:::core
        end

        subgraph "Stdlib Detectors & Builtins"
            direction TB
            Builtins["Builtins"]:::core
            AccessControl["Access Control Helpers"]:::core
            Detectors["Detectors Suite"]:::core
            ParsersStd["Stdlib Parsers"]:::core
            QuantDefs["Quantifier Definitions"]:::core
            LLMMsg["LLM & Message Support"]:::core
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMProviders["LLM/MCP Providers"]:::ext
        InvariantAPI["Invariant Guardrails API"]:::ext
    end

    %% Relationships
    ClientApp -->|"send request"| EntryPoint
    EntryPoint -->|"invoke LocalPolicy"| LocalPolicy
    LocalPolicy -->|"parse rules"| Parser
    Parser --> AST --> Linking --> Optimizer --> TypeSystem --> Typing --> Scope
    Scope -->|"semantic result"| PolicyDefs
    PolicyDefs --> Monitor --> Extras
    Monitor --> AnalysisResult
    AnalysisResult --> Evaluation
    Evaluation --> EvalContext --> FuncCache --> Functions --> Primitives
    Primitives --> InputHandling --> NodesEval --> Patterns --> Quantifier --> RuleModel --> RuntimeErrors --> SymbolTable --> Utils
    Patterns -->|"invoke detectors"| Detectors
    Detectors --> Builtins
    Detectors --> AccessControl
    Detectors --> ParsersStd
    Detectors --> QuantDefs
    Detectors --> LLMMsg
    Evaluation --> AnalysisResult
    Evaluation -->|"if remote"| RemotePolicy
    RemotePolicy -->|"HTTP call"| InvariantAPI
    AnalysisResult -->|"result"| EntryPoint
    EntryPoint -->|"forward if pass"| LLMProviders

    %% Click Events
    click EntryPoint "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/__main__.py"
    click LocalPolicy "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/base_policy.py"
    click RemotePolicy "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/remote_policy.py"
    click Parser "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/language/parser.py"
    click AST "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/language/ast.py"
    click Linking "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/language/linking.py"
    click Optimizer "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/language/optimizer.py"
    click TypeSystem "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/language/types.py"
    click Typing "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/language/typing.py"
    click Scope "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/language/scope.py"
    click PolicyDefs "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/policy.py"
    click Monitor "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/monitor.py"
    click AnalysisResult "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/result.py"
    click Extras "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/extras.py"
    click Evaluation "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/evaluation.py"
    click EvalContext "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/evaluation_context.py"
    click FuncCache "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/function_cache.py"
    click Functions "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/functions.py"
    click Primitives "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/interface/primitives.py"
    click InputHandling "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/input.py"
    click NodesEval "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/nodes.py"
    click Patterns "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/patterns.py"
    click Quantifier "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/quantifier.py"
    click RuleModel "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/rule.py"
    click RuntimeErrors "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/runtime_errors.py"
    click SymbolTable "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/runtime/symbol_table.py"
    click Utils "https://github.com/invariantlabs-ai/invariant/tree/main/invariant/analyzer/runtime/utils/"
    click Builtins "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/stdlib/invariant/builtins.py"
    click AccessControl "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/stdlib/invariant/access_control.py"
    click Detectors "https://github.com/invariantlabs-ai/invariant/tree/main/invariant/analyzer/stdlib/invariant/detectors/"
    click ParsersStd "https://github.com/invariantlabs-ai/invariant/tree/main/invariant/analyzer/stdlib/invariant/parsers/"
    click QuantDefs "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/stdlib/invariant/quantifiers.py"
    click LLMMsg "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/analyzer/stdlib/invariant/llm.py"
    click ClientApp "https://github.com/invariantlabs-ai/invariant/blob/main/invariant/explorer/launch.py"

    %% Styles
    classDef app fill:#c6f6d5,stroke:#2f855a,color:#2f855a;
    classDef core fill:#bee3f8,stroke:#2b6cb0,color:#2b6cb0;
    classDef ext fill:#ffe3b8,stroke:#dd6b20,color:#dd6b20;
```
