Skip to content

timmeck/nexus

BranchesTags

Repository files navigation

Nexus

The verification layer for AI agent networks. A2A and IATP prove agents are who they say they are. Nexus checks if they're telling the truth.

CI Python 3.11+ License: MIT

The Problem

Today's agent protocols verify the sender and the delivery. None of them verify the answer.

  • A2A Signed Agent Cards prove the agent is who it claims to be.
  • IATP scores reputation based on past behavior.
  • PayCrow / ERC-8004 release escrow when bytes arrive matching a JSON schema.
  • Nava verifies intent against the user's request.

But Agent B can return a cryptographically-signed, schema-valid, on-time response that is factually wrong — and every layer above passes it through. Partial cheaters, style mimics, semantic swaps, coordinated collusion: all defeat identity-based trust because they aren't lying about who they are. They're lying about what they know.

Nexus is the missing verdict. Claim-level semantic verification that runs over A2A, IATP, or standalone. Verified outputs settle escrow. Failed verifications slash trust. Every step is audited.

Why Not Just A2A?

A2A is the right transport. Nexus is the verdict on top.

Layer A2A / IATP PayCrow / ERC-8004 / Nava Nexus
Sender authenticity ✅ Signed Agent Cards — (delegated to A2A)
Identity reputation ✅ Trust score 0-1000 — (delegated to IATP)
Delivery / schema match — ✅ Smart-contract escrow (delegated)
Content correctness ❌ ❌ ✅ Claim-level verification
Adversarial test coverage Identity attacks Replay / non-delivery 12/12 caught: partial cheat, style mimic, omission, collusion, meaning swap, negation, context shift

Use A2A for who and whether. Use Nexus for what.

60-Second Demo

One script shows the entire story:

git clone https://github.com/timmeck/nexus.git
cd nexus
pip install -r requirements.txt
python demo_cheat.py

What happens:

  1. A cheater agent returns garbage with 95% confidence
  2. An honest agent returns real analysis
  3. Nexus verification catches the cheater (26% consensus score)
  4. Consumer disputes the escrow -- credits returned
  5. Cheater gets slashed -- trust score drops, credits lost

Red Team Results

We ran 4 rounds of adversarial testing against the verification system. Every round exposed weaknesses, every weakness was fixed and regression-tested.

Adversarial Pattern Verdict Score Result
Baseline (2 honest agents) PASS 100% Correct
Dumb Liar (obvious garbage, high confidence) FAIL 100% CAUGHT
Plausible Liar (correct format, wrong facts) FAIL 65% CAUGHT
Partial Cheater (80% correct, wrong penalties) FAIL 82% CAUGHT
Style Mimic (exact format, EU->US, euros->dollars) FAIL 66% CAUGHT
Lazy Agent (generic fluff, no data) FAIL 100% CAUGHT
Confidence Gamer (99% confidence, vague output) FAIL 86% CAUGHT
Colluding Pair vs 1 Honest FAIL 60% CAUGHT
Colluding Pair vs 2 Honest FAIL 60% CAUGHT
Omission Attack (hides all numbers/dates) FAIL 100% CAUGHT
Word Numbers ("thirty five million") FAIL 65% CAUGHT
Coordinated Collusion (varied wrong answers) FAIL 74% CAUGHT

11/11 adversarial patterns caught. 0 escaped. Plus 4 meta-agent attacks (agents that know the verifier logic): all 4 caught (3 as SUSPICIOUS, 1 as FAIL). See Known Detection Boundaries.

False positive tests (4 honest agents with different styles): 4/4 pass, 0 false negatives.

Run it yourself: python red_team_isolated.py

Quick Start

# Start Nexus
python run.py
# Dashboard: http://localhost:9500
# API docs:  http://localhost:9500/docs

10-Line Integration

Any FastAPI agent joins the network with the standalone SDK (zero nexus dependencies):

from nexus_sdk import NexusAdapter

adapter = NexusAdapter(
    app=app,
    agent_name="my-agent",
    nexus_url="http://localhost:9500",
    endpoint="http://localhost:8000",
    capabilities=[
        {"name": "summarization", "description": "Summarizes text", "price_per_request": 0.01},
    ],
)

@adapter.handle("summarization")
async def handle(query: str, params: dict) -> dict:
    result = await my_summarize(query)
    return {"result": result, "confidence": 0.9, "cost": 0.01}

The adapter handles registration, heartbeats (30s), HMAC verification, and request/response serialization automatically.

How It Works

Consumer                         Nexus                        Provider
   |                              |                              |
   |-- request ------------------>|                              |
   |                     [POLICY CHECK]                          |
   |                     [ROUTE TO BEST AGENT]                   |
   |                     [BUDGET CHECK]                          |
   |                     [CREATE ESCROW]                         |
   |                              |-- signed request ----------->|
   |                              |<-- response + confidence ----|
   |                     [RECORD TRUST]                          |
   |                     [SETTLE OR DISPUTE]                     |
   |<-- result + audit trail -----|                              |

Every state transition is validated. Invalid jumps raise InvalidTransitionError. Terminal states cannot be mutated.

Verification System

Nexus uses claim-level verification, not just string similarity:

  1. Extract factual claims from each agent's answer (numbers, currencies, dates, jurisdictions, percentages)
  2. Normalize claims ("35 million" = "35M" = "thirty five million" = 35000000)
  3. Compare critical fields across agents with weighted scoring
  4. Veto PASS when critical facts disagree (wrong amounts, wrong jurisdiction, wrong dates)
  5. Detect omissions when an agent suspiciously hides specific data

This catches the attacks that naive string matching misses: partial cheaters (80% correct, wrong penalties), style mimics (same format, different country/currency), and adversarial formatting (numbers as words).

Defense Mechanisms

Mechanism What it does
Escrow Payments held during settlement window. Consumer can dispute.
Slashing Bad output + high confidence = trust AND credit penalty
Challenges Any agent can dispute another's output
Sybil Detection Rate-limited registration, similarity flagging
Replay Protection HMAC + timestamp + signature cache (3-layer)
Reconciliation Background job catches stuck requests and orphaned escrows

Connected Agents

8 agents already integrated via NexusAdapter SDK:

Agent Capabilities
Cortex text_generation, code_analysis
DocBrain document_analysis, knowledge_retrieval
Mnemonic memory_management, context_tracking
DeepResearch deep_research, fact_checking
Sentinel security_analysis, threat_detection
CostControl cost_tracking, budget_management
SafetyProxy prompt_injection_detection, pii_detection
LogAnalyst log_analysis, error_explanation

Architecture

Nexus has 9 layers. The differentiated value lives in Verification + Defense + Trust — these are what no other agent network does today. The rest exist so Nexus can also run standalone, but are best understood as substrate that A2A can replace.

Differentiating layers (the product):

Layer Purpose
Verification Claim-level extraction, normalization, semantic-tension detection, SUSPICIOUS verdict
Defense Slashing, escrow disputes, challenges, sybil detection — driven by verification verdicts
Trust Append-only reputation ledger fed by verification outcomes

Substrate layers (replaceable by A2A or similar):

Layer Purpose Can be replaced by
Discovery Agent registry, capability search, heartbeat monitoring A2A Agent Cards
Protocol NexusRequest/NexusResponse lifecycle A2A JSON-RPC 2.0
Routing Best, cheapest, fastest, or most trusted agent matching A2A discovery + routing
Federation Cross-instance agent registry sync A2A federation
Payments Credit wallets, pay-per-request x402 / PayCrow / on-chain escrow
Schemas Formal capability definitions A2A Agent Cards
Defense Slashing, escrow, challenges, sybil detection
Policy Data locality, compliance claims, routing policies — (keep, used by both modes)

Roadmap: an A2A bridge is the top Phase 2 item — Nexus consumes A2A Agent Cards as discovery, accepts A2A JSON-RPC requests, and emits Nexus verdicts back into A2A's response flow. See ROADMAP.md.

Known Detection Boundaries

We tested Nexus with meta-agents — adversarial agents that know how the verifier works and craft responses to bypass it:

Attack What it does Result How
Low Amplitude 34M instead of 35M FAIL Claim extraction distinguishes the integers
Meaning Swap "penalty" becomes "subsidy", same numbers SUSPICIOUS Semantic tension: role conflict (penalty vs incentive language)
Negation "can NOT exceed 35M" — opposite meaning SUSPICIOUS Negation divergence detected (2 markers vs 0)
Context Shift Same numbers, different regulation SUSPICIOUS Regulation mismatch (AI Act vs Digital Markets Act)
Shared Hallucination All agents agree on the same wrong fact PASS Consensus is not truth — by design

The SUSPICIOUS verdict means: "claims match numerically, but semantic signals diverge — manual review recommended." Three lightweight heuristics power this (no LLM needed): trigger word divergence, negation surface check, and entity/regulation anchoring.

Remaining architectural limit: shared hallucination (all agents wrong in the same way). Addressing this requires external truth anchoring — planned for future phases.

What Nexus catches: numeric drift, format tricks, omissions, collusion, style variation, confidence gaming, meaning swaps, negation, context shifts. What Nexus cannot catch: coordinated identical hallucination.

Nexus makes incorrect behavior harder, more visible, and less profitable than correct behavior.

Testing

224 tests + adversarial red team suite:

# Unit + integration tests
pytest -v               # 224 passed

# Killer demo
python demo_cheat.py    # Cheater caught in 60 seconds

# Full red team suite (12 adversarial + 4 false-positive tests)
python red_team_isolated.py

API Reference

Full API (click to expand)

Registry

Method Endpoint Description
POST /api/registry/agents Register agent
GET /api/registry/agents List agents
GET /api/registry/agents/{id} Get agent
POST /api/registry/agents/{id}/heartbeat Heartbeat
GET /api/registry/discover Find by capability

Protocol

Method Endpoint Description
POST /api/protocol/request Submit request (enforced lifecycle)
POST /api/protocol/verify Multi-agent verification
GET /api/protocol/requests/{id}/events Audit trail

Trust & Defense

Method Endpoint Description
GET /api/trust/report/{id} Trust report
POST /api/defense/slash Slash agent
GET /api/defense/escrows List escrows
POST /api/defense/escrows/{id}/dispute Dispute escrow

Payments

Method Endpoint Description
GET /api/payments/wallets List wallets
GET /api/payments/wallets/{id}/balance Get balance
POST /api/payments/wallets/{id}/topup Add credits

System

Method Endpoint Description
GET /health Health check
GET /api/stats Network stats
WS /ws/dashboard Dashboard WebSocket

Tech Stack

  • Python 3.11+ with full async/await
  • FastAPI for HTTP + WebSocket API
  • SQLite + aiosqlite for zero-config persistence
  • Pydantic v2 for data validation
  • httpx for async agent-to-agent communication

License

MIT -- Tim Mecklenburg

Built by Tim Mecklenburg

Star this repo PayPal

About

The AI-to-AI Protocol Layer that catches unreliable agent outputs before they cost you money. Claim-level verification, escrow, and slashing. 224 tests, 12/12 adversarial patterns caught.

Topics

python microservices ai mcp protocol decentralized routing discovery self-hosted trust federation ai-safety ai-agents fastapi a2a llm local-llm ollama agent-to-agent agent-verification

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages