How invariantlabs-ai/invariant works
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