vaara 0.3.0

Adaptive AI Agent Execution Layer — risk scoring, audit trails, regulatory compliance

Vaara

Adaptive AI agent execution layer. Sits between agents and actions, scores risk in real time, and produces EU AI Act conformity evidence as a byproduct.

Three questions for every agent action:

1. Should this happen? (adaptive risk scoring with conformal prediction)
2. What is this? (action taxonomy with regulatory classification)
3. What happened and why? (hash-chained audit trail)

Why Vaara

AI governance tools audit models. Vaara governs actions.

Models are scored once at deployment. Agents act continuously at runtime -- calling tools, moving money, modifying infrastructure. Individual actions may be safe, but sequences can be catastrophic. read_data + export_data + delete_data is a data exfiltration pattern where each step alone is benign.

Vaara catches this. It learns which risk signals predict bad outcomes, adapts its scoring online, and wraps every estimate in a distribution-free confidence interval. No retraining. No manual threshold tuning.

Install

pip install vaara

Python 3.10+. Zero runtime dependencies.

Quick Start

from vaara.pipeline import InterceptionPipeline

pipeline = InterceptionPipeline()

# Agent wants to execute a tool
result = pipeline.intercept(
    agent_id="agent-007",
    tool_name="tx.transfer",
    parameters={"to": "0x...", "amount": 1000},
    agent_confidence=0.8,
)

if result.allowed:
    execute_tool("tx.transfer", {"to": "0x...", "amount": 1000})
    # Report outcome so the scorer learns
    pipeline.report_outcome(result.action_id, outcome_severity=0.0)
else:
    print(f"Blocked: {result.reason}")
    # result.decision is "deny" or "escalate"
    # result.risk_score and result.risk_interval available

How It Works

Risk Scoring (Adaptive)

Five expert signals scored per action, combined via Multiplicative Weight Update:

Signal	What it measures
Taxonomy base	Static risk from action metadata (reversibility, blast radius, urgency)
Agent history	This agent's track record (denial rate, bad outcomes)
Sequence pattern	Dangerous action sequences (data exfiltration, privilege escalation, flash loan attacks)
Burst detection	Unusual action frequency spikes
Confidence gap	High confidence on high-risk actions = suspicious

MWU learns which signals actually predict bad outcomes and shifts weight toward them. Converges to within 6% of the best expert within 1,000 observations.

Conformal Prediction

Every risk score is wrapped in a conformal prediction interval:

P(true_risk in [lower, upper]) >= 1 - alpha

No distributional assumptions. No model retraining. The decision uses the upper bound -- conservative by construction. Under distribution shift, FACI adaptive alpha maintains long-run coverage.

Decisions

ALLOW     — upper bound < 0.3 (configurable)
ESCALATE  — between 0.3 and 0.7 → route to human
DENY      — upper bound > 0.7

Cold start is maximally cautious: wide intervals route most actions through human review. As outcomes accumulate, intervals tighten and the system becomes autonomous.

Framework Integrations

LangChain

from vaara.integrations.langchain import VaaraCallbackHandler

pipeline = InterceptionPipeline()
handler = VaaraCallbackHandler(pipeline, agent_id="my-agent")
agent = create_react_agent(llm, tools, callbacks=[handler])

OpenAI Agents SDK

from vaara.integrations.openai_agents import VaaraToolGuardrail

pipeline = InterceptionPipeline()
guardrail = VaaraToolGuardrail(pipeline)
agent = Agent(name="my-agent", tools=[...], output_guardrails=[guardrail])

CrewAI

from vaara.integrations.crewai import VaaraCrewGovernance

pipeline = InterceptionPipeline()
gov = VaaraCrewGovernance(pipeline)
safe_crew = gov.governed_kickoff(crew)

MCP Server (Claude Code, Cursor)

python -m vaara.integrations.mcp_server

Add to Claude Code settings:

{
  "mcpServers": {
    "vaara": {
      "command": "python",
      "args": ["-m", "vaara.integrations.mcp_server"]
    }
  }
}

Microsoft Agent Governance Toolkit

Vaara implements the ExternalPolicyBackend protocol -- plug it into any AGT PolicyEvaluator chain.

DeFi Extension

25 DeFi action types with MEV vulnerability scoring, atomicity classification, and 17 dangerous sequence patterns:

from vaara.taxonomy.defi import register_defi_actions

register_defi_actions(pipeline.registry)

# Now catches: flash loan attacks, rug pulls, governance attacks,
# bridge exploits, vault manipulation, oracle sandwiches, and more

Compliance

Built-in conformity assessment against EU AI Act and DORA:

report = pipeline.run_compliance_assessment(
    system_name="My Agent System",
    system_version="1.0.0",
)

# Article-by-article evidence mapping
for article in report.articles:
    print(f"{article.reference}: {article.status}")
    # EU AI Act Art. 9(1): COMPLIANT
    # EU AI Act Art. 12(1): COMPLIANT
    # ...

Mapped requirements:

• EU AI Act: Articles 9, 11-15, 61 (risk management, documentation, logging, transparency, human oversight, accuracy, post-market monitoring)
• DORA: Articles 10, 12, 13 (ICT risk management, incident detection, incident response)

The audit trail is hash-chained (SHA-256) and tamper-evident, satisfying Article 12(1) logging requirements.

Cold Start

Generate synthetic traces to pre-calibrate the scorer:

from vaara.sandbox.trace_gen import TraceGenerator

gen = TraceGenerator()
traces = gen.generate(n_traces=100)
gen.pre_calibrate(pipeline.scorer, traces)
# Calibration in minutes instead of hours

Three agent archetypes (benign, careless, adversarial) with realistic outcome distributions.

Architecture

Agent (LangChain / OpenAI / CrewAI / MCP)
    |
    v
InterceptionPipeline.intercept()
    |
    +-- ActionRegistry     ->  classify tool_name to ActionType
    +-- AdaptiveScorer     ->  MWU + conformal risk interval
    +-- AuditTrail         ->  hash-chained immutable log
    +-- ComplianceEngine   ->  EU AI Act + DORA evidence mapping
    |
    v
InterceptionResult { allowed, risk_score, risk_interval, reason }
    |
    v
Execute or Block
    |
    v
report_outcome()  ->  closes feedback loop, MWU learns

Persistence

from vaara.audit.sqlite_backend import SQLiteAuditBackend

backend = SQLiteAuditBackend("audit.db")
trail = AuditTrail(on_record=backend.write)
pipeline = InterceptionPipeline(trail=trail)

WAL-mode SQLite, append-only, hash chain verified on load.

Formal Specification

See docs/formal_specification.md for the mathematical foundations: MWU regret bounds, conformal coverage guarantees, convergence rates, and security properties.

Tests

pip install vaara[dev]
pytest

169 tests, 86% coverage, runs in <0.5s.

License

See LICENSE.