Metadata-Version: 2.4
Name: veroq-agentmesh
Version: 0.2.0
Summary: VeroQ Shield adapter for OpenAI Agents SDK + Agent Governance Toolkit — output guardrails, trust scoring, content verification
Project-URL: Homepage, https://github.com/veroq-ai/veroq-agentmesh
Project-URL: Repository, https://github.com/veroq-ai/veroq-agentmesh
Project-URL: Documentation, https://docs.veroq.ai
Project-URL: Issues, https://github.com/veroq-ai/veroq-agentmesh/issues
Author-email: VeroQ <team@veroq.ai>
License: MIT
License-File: LICENSE
Keywords: agentmesh,agents,content-quality,governance,hallucination,openai-agents,shield,trust,verification,veroq
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: veroq>=2.2.0
Provides-Extra: agents
Requires-Dist: openai-agents>=0.1.0; extra == 'agents'
Provides-Extra: dev
Requires-Dist: openai-agents>=0.1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# veroq-agentmesh

VeroQ Shield adapter for the [Agent Governance Toolkit](https://github.com/microsoft/agent-governance-toolkit). Feeds claim-level verification into AgentMesh content governance and trust evaluation.

Two integration points:
- **ShieldEvaluator** — Runs VeroQ Shield on agent output and maps results to AgentMesh content quality dimensions (accuracy, completeness, consistency). Generates audit entries with verification receipts.
- **ShieldActionGuard** — Gates actions based on output verification. An agent's trust score is adjusted by Shield confidence before the allow/deny decision.

## Install

```bash
pip install veroq-agentmesh
```

## Quick Start

```python
from veroq_agentmesh import ShieldEvaluator, ShieldActionGuard

# 1. Evaluate agent output
evaluator = ShieldEvaluator(api_key="vq_...")
report = evaluator.evaluate(
    "NVIDIA reported $22B in Q4 revenue",
    agent_id="did:mesh:researcher",
    content_id="response-001",
)

print(report.trust_score)       # 0.73
print(report.passed)            # False (contradiction found)
print(report.scores)            # {'accuracy': 0.73, 'completeness': 1.0, 'consistency': 0.67}
print(report.audit_entries)     # per-claim receipts

# 2. Feed into policy evaluation context (0-1000 scale)
ctx = report.to_policy_context()
# {'trust_score': 730, 'claims_contradicted': 1, 'receipt_ids': ['r1', 'r2', 'r3'], ...}

# 3. Gate actions with verification
guard = ShieldActionGuard(
    min_trust_score=500,
    sensitive_actions={"publish": 800},
    shield_evaluator=evaluator,
)

result = guard.check_with_verification(
    agent_did="did:mesh:writer",
    agent_trust_score=900,
    action="publish",
    output_text="NVIDIA reported $22B in Q4 revenue",
)
# effective_score = 900 * 0.73 = 657 < 800 -> denied
```

## How It Maps

| Shield Output | AgentMesh Dimension | Description |
|---|---|---|
| `trust_score` (0-1) | `accuracy` | Overall factual accuracy of the output |
| verifiable / total claims | `completeness` | Fraction of claims that could be checked |
| 1 - contradicted / total | `consistency` | Absence of contradictions |
| Per-claim receipts | Audit trail entries | Cryptographic proof of each verification |
| `trust_score * 1000` | Policy context `trust_score` | 0-1000 scale for PolicyEvaluator |

## With ContentQualityEvaluator

```python
from agent_os.content_governance import (
    ContentQualityEvaluator, ContentQualityRule,
    ContentDimension, QualityGate,
)
from veroq_agentmesh import ShieldEvaluator

# Configure quality gates
quality_eval = ContentQualityEvaluator()
quality_eval.add_rule(ContentQualityRule(
    name="min-accuracy",
    dimension=ContentDimension.ACCURACY,
    threshold=0.8,
    gate=QualityGate.FAIL,
))
quality_eval.add_rule(ContentQualityRule(
    name="min-consistency",
    dimension=ContentDimension.CONSISTENCY,
    threshold=0.9,
    gate=QualityGate.WARN,
))

# Run Shield and map to quality dimensions
shield_eval = ShieldEvaluator(api_key="vq_...")
scores = shield_eval.evaluate_to_quality_scores(agent_output)
dim_scores = {ContentDimension(k): v for k, v in scores.items()}

report = quality_eval.evaluate("agent-1", "resp-1", dim_scores)
print(report.passed)    # True/False
print(report.warnings)  # consistency warnings
print(report.failures)  # accuracy failures
```

## Trust Adjustment Formula

When using `ShieldActionGuard.check_with_verification()`:

```
effective_score = base_trust_score * shield_trust_score
```

An agent with trust 800 that produces output with 0.5 accuracy gets an effective score of 400 — below most thresholds. This means even a highly trusted agent gets gated if its output can't be verified.

## Components

| Component | Purpose |
|---|---|
| `ShieldEvaluator` | Runs Shield verification and maps to quality dimensions |
| `ShieldActionGuard` | Trust-gated actions with optional output verification |
| `ShieldContentReport` | Aggregated quality report with policy context conversion |
| `ShieldAuditEntry` | Per-claim verification receipt for audit trail |

## Links

- [VeroQ Shield](https://docs.veroq.ai) — `pip install veroq`
- [Agent Governance Toolkit](https://github.com/microsoft/agent-governance-toolkit)
- [Integration template](https://github.com/microsoft/agent-governance-toolkit/tree/main/packages/agentmesh-integrations/template-agentmesh)

## License

MIT
