ark-trust 0.5.1

ARK - Agent Reliability Kit. Trust infrastructure for AI agents.

ARK — Agent Reliability Kit 🛡

Trust infrastructure for AI agents. Stripe-level idempotency × Sentinel circuit breakers × OpenTelemetry tracing × IDE-style validation. For AI agents.

---

🤔 Why ARK?

Your AI agent says it sent an email. Did it really? Your AI agent says it charged $10. Did it charge $10... or $100? Your AI agent retries on failure. Did it just send 3 duplicate payments?

"Agent does not actually invoke tools, only simulates tool usage with fabricated output" — CrewAI Bug #?, 63 comments

ARK proves every agent action is real.

⚡ Quick Start

pip install ark-trust

from ark import IdempotencyGuard, CircuitBreaker, OutputValidator

# 🛡 1. Never run duplicate payments
guard = IdempotencyGuard()

@guard.wrap
def charge(amount: float):
    return stripe.charge(amount)

charge(99.99)  # ✅ Charged
charge(99.99)  # 🛡 Intercepted — no duplicate!

# ⚡ 2. Auto-fallback when models fail
breaker = CircuitBreaker("gpt-4", failure_threshold=3)

result = breaker.call(
    primary=lambda: gpt4.generate(prompt),
    fallback=lambda: claude.generate(prompt)  # Auto-switch!
)

# 🔧 3. Validate agent output
from pydantic import BaseModel

class PaymentResult(BaseModel):
    amount: float
    txn_id: str

validator = OutputValidator()
result = validator.validate(PaymentResult, agent_output)
if not result.valid:
    print(f"ARK blocked invalid output: {result.errors}")

🔱 The Four Pillars

Pillar	Gene Source	What It Does
🛡 Idempotency Guard	Stripe payments	Prevents duplicate tool execution
⚡ Circuit Breaker	Sentinel microservices	Auto-meltdown → safe fallback
🔧 Output Validator	IDE type checking	Validates agent output against schema
👁 Trace	OpenTelemetry	Full execution trace visibility

📊 What ARK Catches

CrewAI agents fake tool calls     → ARK validates real execution
GPT-4 fails 6 times in a row      → ARK auto-switches to Claude
Agent retries a payment 3 times   → ARK blocks duplicates 2&3
Streaming response returns null   → ARK detects + reloads

🎯 The Numbers

• 8847 error issues across top 3 agent frameworks
• 50+ comments on a single "duplicate payment" bug
• 75% of agent outputs need validation
• 0 existing products in this space (max competitor: 129⭐)

🏗 Architecture

Your Agent
    ↓
┌─── ARK Trust Layer ───┐
│  🛡 Guard   ⚡ Breaker │
│  🔧 Validator 👁 Trace │
└───────────────────────┘
    ↓
Your Tools & APIs

🚀 Roadmap

• MVP — 4 core pillars (v0.1.0)
• LangChain integration — ARKCallbackHandler (v0.1.0)
• CrewAI integration — ARKCrewCallback (v0.1.1)
• Auto-detect frameworks (v0.2.0)
• Reliability Score + Schema Registry — 13 schemas (v0.2.0)
• Dashboard UI — real-time trust monitoring (v0.3.0)
• Achievement system — gamified reliability badges (v0.3.0)
• PyPI publish automation (v0.3.0)
• Community Schema Hub (v0.4.0)
• Benchmarks — 7 performance baselines (v0.4.0)
• OpenTelemetry Exporter — 8 reliability event types (v0.5.0)
• Zero-touch instrumentation — one env var to activate (v0.5.0)

🔭 OpenTelemetry Integration (v0.5.0)

ARK reliability events are emitted to your observability stack via standard OTLP/JSON. Zero code changes to existing agents — set one env var:

export ARK_OTEL_ENDPOINT="http://otel-collector:4318/v1/events"

Event Type	Trigger
ark.idempotency.miss	Tool first called
ark.guardian.intercept	Duplicate call blocked (saves real ms)
ark.circuit.open	Breaker tripped
ark.circuit.half_open	Recovery probe
ark.circuit.close	Service recovered
ark.validation.pass	Output schema valid
ark.validation.fail	Output schema invalid

Compatible with Langfuse, Jaeger, Tempo, Honeycomb — any OTLP receiver.

⚡ 5-Minute Live Demo

See ARK events flow into Langfuse with one command:

cd examples/langfuse-demo
docker compose up -d
pip install -e ../..
python app.py
# Open http://localhost:3000 → watch ARK reliability events stream in

📜 License

MIT — Free forever. ARK is open infrastructure.

---

Built with 🧬 gene recombination: Stripe × Sentinel × OpenTelemetry × IDE