ark-trust 0.4.1__tar.gz

ark_trust-0.4.1/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+Copyright (c) 2026 ARK Contributors
+Permission is hereby granted, free of charge, to any person obtaining a copy...

ark_trust-0.4.1/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: ark-trust
+Version: 0.4.1
+Summary: ARK - Agent Reliability Kit. Trust infrastructure for AI agents.
+Author: ARK Contributors
+License: MIT
+Keywords: ai,agent,reliability,trust,guard,circuit-breaker,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.28
+Requires-Dist: structlog>=23.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# ARK — Agent Reliability Kit 🛡
+
+> **Trust infrastructure for AI agents.**
+> Stripe-level idempotency × Sentinel circuit breakers × OpenTelemetry tracing × IDE-style validation.
+> For AI agents.
+
+[![Tests](https://img.shields.io/badge/tests-169/169-green)](https://github.com/wzg0911/ark)
+[![Python](https://img.shields.io/badge/python-3.9+-blue)](https://pypi.org)
+[![License](https://img.shields.io/badge/license-MIT-purple)](LICENSE)
+
+---
+
+## 🤔 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
+
+```bash
+pip install ark-trust
+```
+
+```python
+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
+
+- [x] MVP — 4 core pillars (v0.1.0)
+- [x] LangChain integration — `ARKCallbackHandler` (v0.1.0)
+- [x] CrewAI integration — `ARKCrewCallback` (v0.1.1)
+- [x] Auto-detect frameworks (v0.2.0)
+- [x] Reliability Score + Schema Registry — 13 schemas (v0.2.0)
+- [x] Dashboard UI — real-time trust monitoring (v0.3.0)
+- [x] Achievement system — gamified reliability badges (v0.3.0)
+- [x] PyPI publish automation (v0.3.0)
+
+## 📜 License
+
+MIT — Free forever. ARK is open infrastructure.
+
+---
+
+**Built with 🧬 gene recombination: Stripe × Sentinel × OpenTelemetry × IDE**

ark_trust-0.4.1/README.md

@@ -0,0 +1,119 @@
+# ARK — Agent Reliability Kit 🛡
+
+> **Trust infrastructure for AI agents.**
+> Stripe-level idempotency × Sentinel circuit breakers × OpenTelemetry tracing × IDE-style validation.
+> For AI agents.
+
+[![Tests](https://img.shields.io/badge/tests-169/169-green)](https://github.com/wzg0911/ark)
+[![Python](https://img.shields.io/badge/python-3.9+-blue)](https://pypi.org)
+[![License](https://img.shields.io/badge/license-MIT-purple)](LICENSE)
+
+---
+
+## 🤔 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
+
+```bash
+pip install ark-trust
+```
+
+```python
+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
+
+- [x] MVP — 4 core pillars (v0.1.0)
+- [x] LangChain integration — `ARKCallbackHandler` (v0.1.0)
+- [x] CrewAI integration — `ARKCrewCallback` (v0.1.1)
+- [x] Auto-detect frameworks (v0.2.0)
+- [x] Reliability Score + Schema Registry — 13 schemas (v0.2.0)
+- [x] Dashboard UI — real-time trust monitoring (v0.3.0)
+- [x] Achievement system — gamified reliability badges (v0.3.0)
+- [x] PyPI publish automation (v0.3.0)
+
+## 📜 License
+
+MIT — Free forever. ARK is open infrastructure.
+
+---
+
+**Built with 🧬 gene recombination: Stripe × Sentinel × OpenTelemetry × IDE**

ark_trust-0.4.1/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "ark-trust"
+version = "0.4.1"
+description = "ARK - Agent Reliability Kit. Trust infrastructure for AI agents."
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "ARK Contributors"}]
+keywords = ["ai", "agent", "reliability", "trust", "guard", "circuit-breaker", "validation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "pydantic>=2.0",
+    "httpx>=0.28",
+    "structlog>=23.0",
+]
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+dev = ["pytest", "pytest-asyncio", "ruff"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

ark_trust-0.4.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ark_trust-0.4.1/src/ark/__init__.py

@@ -0,0 +1,49 @@
+"""
+ARK - Agent Reliability Kit
+Trust infrastructure for AI agents.
+
+基因重组:
+  🏦 Stripe → 幂等守护 (Idempotency Guard)
+  ⚡ Sentinel → 熔断控制器 (Circuit Breaker)
+  👁 OpenTelemetry → 链路追踪 (Trace)
+  🔧 IDE → 输出验证 (Output Validator)
+  🎮 Gaming → 可靠性评分 (Reliability Score)
+  📦 Community → Schema注册表 (Schema Registry)
+  🔮 memU → 预测性守护 (ProactiveGuard)
+  💾 EverOS/MemBrain → 状态持久化 (StatefulBreaker)
+  🧩 GenericAgent → 模块化能力 (ModuleKit)
+  🤝 PraisonAI → 多Agent协议 (MultiAgentProtocol)
+
+v0.4.0.dev1 - 四大增强模块
+"""
+
+from .guard import IdempotencyGuard
+from .breaker import CircuitBreaker
+from .validator import OutputValidator
+from .trace import Trace
+from .score import ReliabilityScore
+from .schema_registry import SchemaRegistry
+from .schema_hub import SchemaHub, get_schema_hub
+from .auto import auto_init, detect_frameworks
+from .dashboard import Dashboard, get_dashboard, Event
+from .achievements import Achievements, Achievement, Tier
+from .benchmarks import Benchmarks, BenchmarkResult
+from .proactive import ProactiveGuard, ProactiveBlockError
+from .stateful_breaker import StatefulBreaker, CircuitOpenError
+from .module_kit import ModulePipeline, Module, RateLimitModule, SchemaValidationModule, LoggingModule, ModuleBlockError
+from .multi_agent import MultiAgentProtocol, AgentMessage, AgentHeartbeat, MessageStatus, AgentStatus
+
+__version__ = "0.4.0.dev1"
+__all__ = [
+    "IdempotencyGuard", "CircuitBreaker", "OutputValidator", "Trace",
+    "ReliabilityScore", "SchemaRegistry", "auto_init", "detect_frameworks",
+    "Dashboard", "get_dashboard", "Event", "Achievements", "Achievement", "Tier",
+    "Benchmarks", "BenchmarkResult",
+    "SchemaHub", "get_schema_hub",
+    "ProactiveGuard", "ProactiveBlockError",
+    "StatefulBreaker", "CircuitOpenError",
+    "ModulePipeline", "Module", "RateLimitModule",
+    "SchemaValidationModule", "LoggingModule", "ModuleBlockError",
+    "MultiAgentProtocol", "AgentMessage", "AgentHeartbeat",
+    "MessageStatus", "AgentStatus",
+]

ark_trust-0.4.1/src/ark/achievements.py

@@ -0,0 +1,226 @@
+"""
+ARK Achievements — Gamification engine for agent trust
+v0.3.0 — Unlock badges as your agents become more reliable.
+
+Usage:
+    from ark import Achievements
+    ach = Achievements()
+    ach.record("intercept", agent="checkout-bot")
+    ach.record("validate_pass", agent="checkout-bot")
+    print(ach.summary())
+"""
+
+import time
+from typing import Dict, List, Set
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class Tier(Enum):
+    BRONZE = ("🥉", 1)
+    SILVER = ("🥈", 2)
+    GOLD = ("🥇", 3)
+    PLATINUM = ("💎", 4)
+
+    def __init__(self, emoji: str, level: int):
+        self.emoji = emoji
+        self.level = level
+
+
+@dataclass
+class Achievement:
+    id: str
+    name: str
+    description: str
+    icon: str
+    progress: int = 0           # current count
+    target: int = 1             # count needed
+    tiers: List[Tier] = field(default_factory=lambda: [Tier.BRONZE, Tier.SILVER, Tier.GOLD, Tier.PLATINUM])
+    unlocked_at: List[float] = field(default_factory=list)  # timestamps of unlocks
+    _previous_tier: int = 0
+
+    @property
+    def current_tier(self) -> Tier:
+        return self.tiers[min(len(self.unlocked_at), len(self.tiers) - 1)]
+
+    @property
+    def is_maxed(self) -> bool:
+        return len(self.unlocked_at) >= len(self.tiers)
+
+    @property
+    def next_tier_target(self) -> int:
+        """Target for the next tier, or -1 if maxed."""
+        if self.is_maxed:
+            return -1
+        idx = len(self.unlocked_at)
+        multiplier_map = {0: 1, 1: 10, 2: 100, 3: 1000}
+        return self.target * multiplier_map.get(idx, self.target)
+
+    def progress_pct(self) -> float:
+        if self.is_maxed:
+            return 100.0
+        return min(100.0, round(self.progress / self.next_tier_target * 100, 1))
+
+
+# ── Predefined Achievements ────────────────────────────────────
+
+ACHIEVEMENTS = {
+    "guardian": Achievement(
+        id="guardian",
+        name="Guardian",
+        icon="🛡",
+        description="Intercept duplicate calls",
+        target=10,  # Bronze at 10, Silver at 100, Gold at 1000, Platinum at 10000
+    ),
+    "survivor": Achievement(
+        id="survivor",
+        name="Survivor",
+        icon="⚡",
+        description="Circuit breaker recovers",
+        target=1,   # Bronze at 1, Silver at 10, Gold at 100, Platinum at 1000
+    ),
+    "inspector": Achievement(
+        id="inspector",
+        name="Inspector",
+        icon="🔧",
+        description="Validations passed",
+        target=10,  # Bronze at 10, Silver at 100, Gold at 1000, Platinum at 10000
+    ),
+    "watcher": Achievement(
+        id="watcher",
+        name="Watcher",
+        icon="👁",
+        description="Spans traced",
+        target=10,  # Bronze at 10, Silver at 100, Gold at 1000, Platinum at 10000
+    ),
+    "ark_master": Achievement(
+        id="ark_master",
+        name="ARK Master",
+        icon="🎖",
+        description="All four achievements at Gold+",
+        target=1,
+        tiers=[Tier.PLATINUM],  # one-time ultimate unlock
+    ),
+}
+
+
+@dataclass
+class Achievements:
+    """Tracks agent achievements and triggers unlocks."""
+
+    achievements: Dict[str, Achievement] = field(
+        default_factory=lambda: {k: Achievement(**v.__dict__) for k, v in ACHIEVEMENTS.items()}
+    )
+    recent_unlocks: List[Dict] = field(default_factory=list)  # push notifications
+
+    # ── recording ──────────────────────────────────────────────
+
+    def record(self, kind: str, agent: str = "default", count: int = 1) -> List[str]:
+        """Record an event that may unlock achievements. Returns list of just-unlocked IDs."""
+        unlocked = []
+
+        mapping = {
+            "intercept": "guardian",
+            "recover": "survivor",
+            "validate_pass": "inspector",
+            "span": "watcher",
+        }
+
+        ach_id = mapping.get(kind)
+        if not ach_id:
+            return unlocked
+
+        ach = self.achievements[ach_id]
+        ach.progress += count
+
+        # Try to unlock next tier
+        while not ach.is_maxed:
+            target = ach.next_tier_target
+            if ach.progress >= target:
+                ach.unlocked_at.append(time.time())
+                tier_emoji = ach.current_tier.emoji
+                tier_name = ach.current_tier.name
+                self.recent_unlocks.append({
+                    "achievement": ach.name,
+                    "tier": tier_name,
+                    "emoji": f"{ach.icon} {tier_emoji}",
+                    "agent": agent,
+                    "ts": ach.unlocked_at[-1],
+                })
+                unlocked.append(f"{ach.icon} {tier_emoji} {ach.name} ({tier_name}) — {agent}")
+            else:
+                break
+
+        # Check ARK Master (all 4 at Gold+)
+        core = ["guardian", "survivor", "inspector", "watcher"]
+        master = self.achievements["ark_master"]
+        if not master.is_maxed:
+            all_gold = all(
+                len(self.achievements[a].unlocked_at) >= 3 for a in core
+            )
+            if all_gold:
+                master.progress = 1
+                master.unlocked_at.append(time.time())
+                self.recent_unlocks.append({
+                    "achievement": "ARK Master",
+                    "tier": "PLATINUM",
+                    "emoji": "🎖 💎",
+                    "agent": agent,
+                    "ts": master.unlocked_at[-1],
+                })
+                unlocked.append("🎖 💎 ARK Master — ALL CORE ACHIEVEMENTS UNLOCKED!")
+
+        return unlocked
+
+    # ── rendering ───────────────────────────────────────────────
+
+    @property
+    def summary(self) -> List[Dict]:
+        return [
+            {
+                "id": ach.id,
+                "name": ach.name,
+                "icon": ach.icon,
+                "progress": ach.progress,
+                "next_target": ach.next_tier_target,
+                "progress_pct": ach.progress_pct(),
+                "tier": f"{ach.current_tier.emoji} {ach.current_tier.name}" if ach.unlocked_at else "🔒 Locked",
+                "unlocked_at": ach.unlocked_at.copy() if ach.unlocked_at else [],
+                "maxed": ach.is_maxed,
+            }
+            for ach in self.achievements.values()
+        ]
+
+    def render(self) -> str:
+        lines = [
+            "┌──────────────────────────────────────────────────────────┐",
+            "│  🏆 ARK Achievements                                    │",
+            "├────────────────────┬──────────┬───────────┬────────────┤",
+            "│ Achievement        │ Progress │ Progress  │ Tier       │",
+            "├────────────────────┼──────────┼───────────┼────────────┤",
+        ]
+        for s in self.summary:
+            pct = f"{s['progress_pct']}%"
+            tier = s["tier"]
+            bar = _progress_bar(s["progress_pct"])
+            lines.append(
+                f"│ {s['icon']} {s['name']:<16} │ {s['progress']:>8} │ {bar:<9} │ {tier:<10} │"
+            )
+        lines.append("└────────────────────┴──────────┴───────────┴────────────┘")
+
+        if self.recent_unlocks:
+            lines.append("\n🎉 Recent Unlocks:")
+            for u in self.recent_unlocks[-5:]:
+                lines.append(f"   {u['emoji']} {u['achievement']} ({u['tier']})")
+
+        return "\n".join(lines)
+
+    def to_json(self) -> str:
+        import json
+        return json.dumps(self.summary, indent=2, default=str)
+
+
+def _progress_bar(pct: float, width: int = 8) -> str:
+    filled = int(pct / 100 * width)
+    empty = width - filled
+    return "█" * filled + "░" * empty

ark_trust-0.4.1/src/ark/auto.py

@@ -0,0 +1,68 @@
+"""
+ARK Auto-detection + Zero-config bootstrap
+Auto-scans environment for agent frameworks and configures ARK accordingly.
+"""
+
+import sys
+import importlib
+from typing import Dict, List, Optional
+
+
+def detect_frameworks() -> List[str]:
+    """扫描环境中已安装的Agent框架"""
+    frameworks = {
+        "langchain_core": "LangChain",
+        "crewai": "CrewAI", 
+        "autogen": "AutoGen",
+        "agno": "Agno",
+        "openai": "OpenAI SDK",
+        "anthropic": "Anthropic SDK",
+        "google.generativeai": "Gemini SDK",
+        "llama_index": "LlamaIndex",
+    }
+    detected = []
+    for mod, name in frameworks.items():
+        try:
+            importlib.import_module(mod)
+            detected.append(name)
+        except ImportError:
+            pass
+    return detected
+
+
+def auto_init() -> Dict:
+    """一键初始化ARK — 零配置"""
+    from .guard import IdempotencyGuard
+    from .breaker import CircuitBreaker
+    from .validator import OutputValidator
+    from .score import ReliabilityScore
+    from .schema_registry import SchemaRegistry
+    
+    frameworks = detect_frameworks()
+    
+    config = {
+        "frameworks": frameworks,
+        "mode": "standalone" if not frameworks else "integrated",
+        "guard": IdempotencyGuard(),
+        "breaker": CircuitBreaker("auto-detect"),
+        "validator": OutputValidator(),
+        "score": ReliabilityScore(),
+        "registry": SchemaRegistry(),
+    }
+    
+    # Auto-init framework hooks
+    if "CrewAI" in frameworks:
+        try:
+            from .crewai import ARKCrewCallback
+            config["crewai_callback"] = ARKCrewCallback
+        except Exception:
+            pass
+    
+    if "LangChain" in frameworks:
+        try:
+            from .langchain import ARKCallbackHandler
+            config["langchain_handler"] = ARKCallbackHandler
+        except Exception:
+            pass
+    
+    return config