agentveil 0.2.0__tar.gz

agentveil-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Veil Protocol Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentveil-0.2.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: agentveil
+Version: 0.2.0
+Summary: Python SDK for Agent Veil Protocol — reputation and identity for AI agents
+Author: Agent Veil Protocol
+License: MIT
+Project-URL: Homepage, https://agentveil.dev
+Project-URL: Documentation, https://agentveil.dev/docs
+Project-URL: Repository, https://github.com/creatorrmode-lead/avp
+Keywords: ai,agents,reputation,did,identity,a2a
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: base58>=2.1.0
+Dynamic: license-file

agentveil-0.2.0/README.md

@@ -0,0 +1,158 @@
+# avp-sdk
+
+Python SDK for **Agent Veil Protocol** — the trust and identity layer for AI agents.
+
+**PyPI**: [avp-sdk](https://pypi.org/project/agentveil/) | **API**: [agentveil.dev](https://agentveil.dev) | **Docs**: [Swagger](https://agentveil.dev/docs) | **Explorer**: [Live Dashboard](https://agentveil.dev/#explorer)
+
+---
+
+## Install
+
+```bash
+pip install agentveil
+```
+
+## Quick Start — One Line, Zero Config
+
+```python
+from agentveil import avp_tracked
+
+@avp_tracked("https://agentveil.dev", name="reviewer", to_did="did:key:z6Mk...")
+def review_code(pr_url: str) -> str:
+    # Your logic here — no AVP code needed
+    return analysis
+
+# Success → automatic positive attestation
+# Exception → automatic negative attestation with evidence hash
+# First call → auto-registers agent + publishes card
+# Unfair rating? Auto-dispute with evidence
+```
+
+Works with sync and async functions, any framework.
+
+<details>
+<summary>Manual control (advanced)</summary>
+
+```python
+from agentveil import AVPAgent
+
+agent = AVPAgent.create("https://agentveil.dev", name="MyAgent")
+agent.register(display_name="Code Reviewer")
+agent.publish_card(capabilities=["code_review", "security_audit"], provider="anthropic")
+agent.attest("did:key:z6Mk...", outcome="positive", weight=0.9)
+rep = agent.get_reputation("did:key:z6Mk...")
+print(f"Score: {rep['score']}, Confidence: {rep['confidence']}")
+```
+</details>
+
+## Features
+
+- **Zero-Config Decorator** — `@avp_tracked()` — auto-register, auto-attest, auto-protect. One line.
+- **DID Identity** — W3C `did:key` (Ed25519). One key = one portable agent identity.
+- **Reputation** — EigenTrust algorithm with Bayesian confidence. Sybil-resistant.
+- **Attestations** — Signed peer-to-peer ratings with cryptographic proof. Negative ratings require evidence.
+- **Dispute Protection** — Contest unfair negative ratings. Arbitrator-resolved, evidence-based.
+- **Agent Cards** — Publish capabilities, find agents by skill. Machine-readable discovery.
+- **Verification** — 4 trust tiers (DID, Email, GitHub, Biometric). Higher tier = more weight.
+- **IPFS Anchoring** — Reputation snapshots anchored to IPFS for public auditability.
+
+## API Overview
+
+### @avp_tracked Decorator
+
+```python
+from agentveil import avp_tracked
+
+# Basic — auto-register + auto-attest on success/failure
+@avp_tracked("https://agentveil.dev", name="my_agent", to_did="did:key:z6Mk...")
+def do_work(task: str) -> str:
+    return result
+
+# With capabilities and custom weight
+@avp_tracked("https://agentveil.dev", name="auditor", to_did="did:key:z6Mk...",
+             capabilities=["security_audit"], weight=0.9)
+async def audit(code: str) -> str:
+    return await run_audit(code)
+```
+
+Parameters:
+- `base_url` — AVP server URL
+- `name` — Agent name (used for key storage)
+- `to_did` — DID of agent to rate (skip to disable attestation)
+- `capabilities` — Agent capabilities for card (defaults to function name)
+- `weight` — Attestation weight 0.0-1.0 (default 0.8)
+
+### Registration (manual)
+
+```python
+agent = AVPAgent.create(base_url, name="my_agent")
+agent.register(display_name="My Agent")
+```
+
+Keys are saved to `~/.avp/agents/{name}.json` (chmod 0600). Load later with:
+
+```python
+agent = AVPAgent.load(base_url, name="my_agent")
+```
+
+### Agent Cards (Discovery)
+
+```python
+agent.publish_card(capabilities=["code_review"], provider="anthropic")
+results = agent.search_agents(capability="code_review", min_reputation=0.5)
+```
+
+### Attestations
+
+```python
+agent.attest(
+    to_did="did:key:z6Mk...",
+    outcome="positive",    # positive / negative / neutral
+    weight=0.9,            # 0.0 - 1.0
+    context="task_completion",
+    evidence_hash="sha256_of_interaction_log",
+)
+```
+
+### Reputation
+
+```python
+rep = agent.get_reputation("did:key:z6Mk...")
+# {"score": 0.85, "confidence": 0.72, "interpretation": "good"}
+```
+
+## Authentication
+
+All write operations are signed with Ed25519:
+
+```
+Authorization: AVP-Sig did="did:key:z6Mk...",ts="1710864000",nonce="random",sig="hex..."
+```
+
+Signature covers: `{method}:{path}:{timestamp}:{nonce}:{body_sha256}`
+
+The SDK handles signing automatically.
+
+## Error Handling
+
+```python
+from agentveil import AVPAgent, AVPAuthError, AVPRateLimitError, AVPNotFoundError
+
+try:
+    agent.attest(did, outcome="positive")
+except AVPAuthError:
+    print("Signature invalid or agent not verified")
+except AVPRateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except AVPNotFoundError:
+    print("Agent not found")
+```
+
+## Examples
+
+- [`examples/quickstart.py`](examples/quickstart.py) — Register, publish card, check reputation
+- [`examples/two_agents.py`](examples/two_agents.py) — Full A2A interaction with attestations
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

agentveil-0.2.0/agentveil/__init__.py

@@ -0,0 +1,38 @@
+"""
+AVP SDK — Python client for Agent Veil Protocol.
+
+Usage:
+    from agentveil import AVPAgent
+
+    agent = AVPAgent.create("https://avp.example.com", name="MyAgent")
+    agent.register()
+    agent.publish_card(capabilities=["code_review", "testing"], provider="anthropic")
+
+    rep = agent.get_reputation(other_agent_did)
+    agent.attest(other_agent_did, outcome="positive", weight=0.9)
+"""
+
+from agentveil.agent import AVPAgent
+from agentveil.tracked import avp_tracked, clear_agent_cache
+from agentveil.exceptions import (
+    AVPError,
+    AVPAuthError,
+    AVPNotFoundError,
+    AVPRateLimitError,
+    AVPInsufficientFundsError,
+    AVPValidationError,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AVPAgent",
+    "avp_tracked",
+    "clear_agent_cache",
+    "AVPError",
+    "AVPAuthError",
+    "AVPNotFoundError",
+    "AVPRateLimitError",
+    "AVPInsufficientFundsError",
+    "AVPValidationError",
+]

agentveil-0.2.0/agentveil/agent.py

@@ -0,0 +1,473 @@
+"""
+AVPAgent — main SDK class for interacting with Agent Veil Protocol.
+
+Handles key management, authentication, registration, attestations,
+reputation queries, payments, and escrow.
+
+Usage:
+    agent = AVPAgent.create("https://avp.example.com", name="MyAgent")
+    agent.register()
+
+    agent.attest("did:key:z6Mk...", outcome="positive", weight=0.8)
+    rep = agent.get_reputation("did:key:z6Mk...")
+"""
+
+import json
+import os
+import logging
+from pathlib import Path
+from typing import Optional
+
+import httpx
+from nacl.signing import SigningKey, VerifyKey
+
+from agentveil.auth import build_auth_header
+from agentveil.exceptions import (
+    AVPError,
+    AVPAuthError,
+    AVPNotFoundError,
+    AVPRateLimitError,
+    AVPInsufficientFundsError,
+    AVPValidationError,
+    AVPServerError,
+)
+
+log = logging.getLogger("agentveil")
+
+# Default storage for agent keys
+AGENTS_DIR = os.path.expanduser("~/.avp/agents")
+
+# Multicodec prefix for Ed25519 public key
+ED25519_MULTICODEC = bytes([0xED, 0x01])
+
+
+def _public_key_to_did(public_key: bytes) -> str:
+    """Convert Ed25519 public key to did:key."""
+    import base58
+    multicodec_key = ED25519_MULTICODEC + public_key
+    encoded = base58.b58encode(multicodec_key).decode("ascii")
+    return f"did:key:z{encoded}"
+
+
+class AVPAgent:
+    """
+    AI agent identity on Agent Veil Protocol.
+
+    Manages Ed25519 keys, signs requests, and provides methods
+    for all AVP operations: registration, attestation, reputation,
+    payments, and escrow.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        private_key: bytes,
+        name: str = "agent",
+        timeout: float = 15.0,
+    ):
+        """
+        Initialize agent with existing private key.
+        Use AVPAgent.create() or AVPAgent.load() instead of calling directly.
+        """
+        self._base_url = base_url.rstrip("/")
+        self._private_key = private_key
+        self._name = name
+        self._timeout = timeout
+
+        # Derive public key and DID
+        signing_key = SigningKey(private_key)
+        self._public_key = bytes(signing_key.verify_key)
+        self._did = _public_key_to_did(self._public_key)
+        self._is_registered = False
+        self._is_verified = False
+
+    # === Factory methods ===
+
+    @classmethod
+    def create(cls, base_url: str, name: str = "agent", save: bool = True) -> "AVPAgent":
+        """
+        Create a new agent with fresh Ed25519 keys.
+
+        Args:
+            base_url: AVP server URL (e.g. "https://avp.example.com")
+            name: Agent name (used for local key storage)
+            save: Save keys to ~/.avp/agents/{name}.json
+        """
+        signing_key = SigningKey.generate()
+        private_key = bytes(signing_key)
+        agent = cls(base_url, private_key, name=name)
+        if save:
+            agent.save()
+        log.info(f"Created new agent: {agent.did[:40]}...")
+        return agent
+
+    @classmethod
+    def load(cls, base_url: str, name: str = "agent") -> "AVPAgent":
+        """
+        Load agent from saved keys.
+
+        Args:
+            base_url: AVP server URL
+            name: Agent name (matches saved file)
+
+        Raises:
+            FileNotFoundError: If no saved agent with this name
+        """
+        path = os.path.join(AGENTS_DIR, f"{name}.json")
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"No saved agent '{name}' at {path}")
+
+        with open(path) as f:
+            data = json.load(f)
+
+        private_key = bytes.fromhex(data["private_key_hex"])
+        agent = cls(base_url, private_key, name=name)
+        agent._is_registered = data.get("registered", False)
+        agent._is_verified = data.get("verified", False)
+        log.info(f"Loaded agent: {agent.did[:40]}...")
+        return agent
+
+    @classmethod
+    def from_private_key(cls, base_url: str, private_key_hex: str, name: str = "agent") -> "AVPAgent":
+        """Create agent from hex-encoded private key."""
+        return cls(base_url, bytes.fromhex(private_key_hex), name=name)
+
+    # === Properties ===
+
+    @property
+    def did(self) -> str:
+        """Agent's DID (did:key:z6Mk...)."""
+        return self._did
+
+    @property
+    def public_key_hex(self) -> str:
+        """Agent's public key as hex string."""
+        return self._public_key.hex()
+
+    @property
+    def is_registered(self) -> bool:
+        return self._is_registered
+
+    @property
+    def is_verified(self) -> bool:
+        return self._is_verified
+
+    # === Key management ===
+
+    def save(self) -> str:
+        """Save agent keys to disk. Returns file path."""
+        os.makedirs(AGENTS_DIR, exist_ok=True)
+        path = os.path.join(AGENTS_DIR, f"{self._name}.json")
+        with open(path, "w") as f:
+            json.dump({
+                "name": self._name,
+                "did": self._did,
+                "public_key_hex": self._public_key.hex(),
+                "private_key_hex": self._private_key.hex(),
+                "registered": self._is_registered,
+                "verified": self._is_verified,
+                "base_url": self._base_url,
+            }, f, indent=2)
+        os.chmod(path, 0o600)  # Owner read/write only
+        return path
+
+    # === HTTP helpers ===
+
+    def _auth_headers(self, method: str, path: str, body: bytes = b"") -> dict:
+        """Build authenticated headers for a request."""
+        return build_auth_header(self._private_key, self._did, method, path, body)
+
+    def _handle_response(self, response: httpx.Response) -> dict:
+        """Parse response and raise appropriate exceptions."""
+        if response.status_code == 200:
+            return response.json()
+
+        try:
+            detail = response.json().get("detail", response.text)
+        except Exception:
+            detail = response.text
+
+        if response.status_code == 401:
+            raise AVPAuthError(f"Authentication failed: {detail}", 401, detail)
+        elif response.status_code == 403:
+            raise AVPAuthError(f"Forbidden: {detail}", 403, detail)
+        elif response.status_code == 404:
+            raise AVPNotFoundError(f"Not found: {detail}", 404, detail)
+        elif response.status_code == 409:
+            raise AVPValidationError(f"Conflict: {detail}", 409, detail)
+        elif response.status_code == 429:
+            raise AVPRateLimitError(f"Rate limited: {detail}")
+        elif response.status_code == 400:
+            if "Insufficient" in str(detail):
+                raise AVPInsufficientFundsError(f"Insufficient funds: {detail}", 400, detail)
+            raise AVPValidationError(f"Validation error: {detail}", 400, detail)
+        elif response.status_code >= 500:
+            raise AVPServerError(f"Server error: {detail}", response.status_code, detail)
+        else:
+            raise AVPError(f"Unexpected error ({response.status_code}): {detail}", response.status_code, detail)
+
+    # === Registration ===
+
+    def register(self, display_name: Optional[str] = None) -> dict:
+        """
+        Register agent on AVP and verify key ownership.
+        Does both steps (register + verify) in one call.
+
+        Args:
+            display_name: Optional human-readable name
+
+        Returns:
+            dict with 'did' and 'agnet_address'
+        """
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            # Step 1: Register
+            r = c.post("/v1/agents/register", json={
+                "public_key_hex": self.public_key_hex,
+                "display_name": display_name or self._name,
+            })
+            data = self._handle_response(r)
+            challenge = data["challenge"]
+
+            # Step 2: Sign challenge and verify
+            signing_key = SigningKey(self._private_key)
+            signed = signing_key.sign(challenge.encode())
+            sig_hex = signed.signature.hex()
+
+            r = c.post("/v1/agents/verify", json={
+                "did": self._did,
+                "challenge": challenge,
+                "signature_hex": sig_hex,
+            })
+            self._handle_response(r)
+
+        self._is_registered = True
+        self._is_verified = True
+        self.save()
+        log.info(f"Registered and verified: {self._did[:40]}...")
+        return data
+
+    # === Agent Cards ===
+
+    def publish_card(
+        self,
+        capabilities: list[str],
+        provider: Optional[str] = None,
+        endpoint_url: Optional[str] = None,
+    ) -> dict:
+        """
+        Publish or update agent's capability card.
+
+        Args:
+            capabilities: List of capabilities (e.g. ["code_review", "testing"])
+            provider: LLM provider (e.g. "anthropic", "openai")
+            endpoint_url: URL where this agent can be reached
+        """
+        body_data = {"capabilities": capabilities}
+        if provider:
+            body_data["provider"] = provider
+        if endpoint_url:
+            body_data["endpoint_url"] = endpoint_url
+
+        body = json.dumps(body_data).encode()
+        headers = self._auth_headers("POST", "/v1/cards", body)
+
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            r = c.post("/v1/cards", content=body, headers=headers)
+            return self._handle_response(r)
+
+    def search_agents(
+        self,
+        capability: Optional[str] = None,
+        provider: Optional[str] = None,
+        min_reputation: Optional[float] = None,
+        limit: int = 20,
+    ) -> list[dict]:
+        """Search for agents by capability, provider, or minimum reputation."""
+        params = {"limit": limit}
+        if capability:
+            params["capability"] = capability
+        if provider:
+            params["provider"] = provider
+        if min_reputation is not None:
+            params["min_reputation"] = min_reputation
+
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            r = c.get("/v1/cards", params=params)
+            return self._handle_response(r)
+
+    # === Attestations ===
+
+    def attest(
+        self,
+        to_did: str,
+        outcome: str = "positive",
+        weight: float = 1.0,
+        context: Optional[str] = None,
+        evidence_hash: Optional[str] = None,
+    ) -> dict:
+        """
+        Submit an attestation about another agent.
+
+        Args:
+            to_did: DID of agent being rated
+            outcome: "positive", "negative", or "neutral"
+            weight: Confidence weight (0.0 to 1.0)
+            context: Interaction type (e.g. "task_completion")
+            evidence_hash: SHA256 of interaction log
+
+        Returns:
+            Attestation details
+        """
+        if outcome not in ("positive", "negative", "neutral"):
+            raise AVPValidationError(f"Invalid outcome: {outcome}. Must be positive/negative/neutral")
+        if not 0.0 <= weight <= 1.0:
+            raise AVPValidationError(f"Weight must be 0.0-1.0, got {weight}")
+
+        # Build and sign attestation payload
+        attest_payload = json.dumps({
+            "to": to_did,
+            "outcome": outcome,
+            "weight": weight,
+            "context": context or "",
+            "evidence_hash": evidence_hash or "",
+        }, sort_keys=True, separators=(",", ":")).encode()
+
+        signing_key = SigningKey(self._private_key)
+        signed = signing_key.sign(attest_payload)
+        sig_hex = signed.signature.hex()
+
+        body_data = {
+            "to_agent_did": to_did,
+            "outcome": outcome,
+            "weight": weight,
+            "signature": sig_hex,
+        }
+        if context:
+            body_data["context"] = context
+        if evidence_hash:
+            body_data["evidence_hash"] = evidence_hash
+
+        body = json.dumps(body_data).encode()
+        headers = self._auth_headers("POST", "/v1/attestations", body)
+
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            r = c.post("/v1/attestations", content=body, headers=headers)
+            return self._handle_response(r)
+
+    # === Reputation ===
+
+    def get_reputation(self, did: Optional[str] = None) -> dict:
+        """
+        Get reputation score for an agent.
+
+        Args:
+            did: Agent DID (defaults to self)
+
+        Returns:
+            dict with score, confidence, interpretation
+        """
+        target = did or self._did
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            r = c.get(f"/v1/reputation/{target}")
+            return self._handle_response(r)
+
+    def get_agent_info(self, did: Optional[str] = None) -> dict:
+        """Get public info about an agent."""
+        target = did or self._did
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            r = c.get(f"/v1/agents/{target}")
+            return self._handle_response(r)
+
+    # === Payments ===
+
+    def get_balance(self, did: Optional[str] = None) -> dict:
+        """Get agent's balance (internal + Agnet)."""
+        target = did or self._did
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            r = c.get(f"/v1/payments/balance/{target}")
+            return self._handle_response(r)
+
+    def transfer(self, to_did: str, amount_nagn: int, memo: Optional[str] = None) -> dict:
+        """
+        Transfer funds to another agent.
+
+        Args:
+            to_did: Recipient DID
+            amount_nagn: Amount in nAGN (1 AGN = 1,000,000 nAGN)
+            memo: Optional memo
+        """
+        body_data = {"to_agent_did": to_did, "amount_nagn": amount_nagn}
+        if memo:
+            body_data["memo"] = memo
+
+        body = json.dumps(body_data).encode()
+        headers = self._auth_headers("POST", "/v1/payments/transfer", body)
+
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            r = c.post("/v1/payments/transfer", content=body, headers=headers)
+            return self._handle_response(r)
+
+    # === Escrow ===
+
+    def create_escrow(
+        self,
+        payee_did: str,
+        amount_nagn: int,
+        ttl_hours: int = 24,
+        memo: Optional[str] = None,
+    ) -> dict:
+        """
+        Create an escrow — hold funds until interaction completes.
+
+        Args:
+            payee_did: Agent who will receive funds on success
+            amount_nagn: Amount to hold
+            ttl_hours: Hours before auto-refund (1-168)
+            memo: Optional memo
+        """
+        body_data = {
+            "payee_did": payee_did,
+            "amount_nagn": amount_nagn,
+            "ttl_hours": ttl_hours,
+        }
+        if memo:
+            body_data["memo"] = memo
+
+        body = json.dumps(body_data).encode()
+        headers = self._auth_headers("POST", "/v1/payments/escrow", body)
+
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            r = c.post("/v1/payments/escrow", content=body, headers=headers)
+            return self._handle_response(r)
+
+    def release_escrow(self, escrow_id: str) -> dict:
+        """Release escrow — send funds to payee. Only payee can call this."""
+        body_data = {"escrow_id": escrow_id, "action": "release"}
+        body = json.dumps(body_data).encode()
+        headers = self._auth_headers("POST", "/v1/payments/escrow/resolve", body)
+
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            r = c.post("/v1/payments/escrow/resolve", content=body, headers=headers)
+            return self._handle_response(r)
+
+    def refund_escrow(self, escrow_id: str) -> dict:
+        """Refund escrow — return funds to payer. Only payer can call this."""
+        body_data = {"escrow_id": escrow_id, "action": "refund"}
+        body = json.dumps(body_data).encode()
+        headers = self._auth_headers("POST", "/v1/payments/escrow/resolve", body)
+
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            r = c.post("/v1/payments/escrow/resolve", content=body, headers=headers)
+            return self._handle_response(r)
+
+    # === Utility ===
+
+    def health(self) -> dict:
+        """Check AVP server health."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
+            r = c.get("/v1/health")
+            return self._handle_response(r)
+
+    def __repr__(self) -> str:
+        status = "verified" if self._is_verified else ("registered" if self._is_registered else "new")
+        return f"AVPAgent(name={self._name}, did={self._did[:35]}..., status={status})"

agentveil-0.2.0/agentveil/auth.py

@@ -0,0 +1,45 @@
+"""
+AVP authentication helpers.
+Builds signed Authorization headers for API requests.
+"""
+
+import hashlib
+import secrets
+import time
+
+from nacl.signing import SigningKey
+
+
+def build_auth_header(
+    private_key: bytes,
+    did: str,
+    method: str,
+    path: str,
+    body: bytes = b"",
+) -> dict[str, str]:
+    """
+    Build AVP-Sig Authorization header.
+
+    Signs: {method}:{path}:{timestamp}:{nonce}:{body_sha256}
+    Returns dict with Authorization header ready for httpx.
+
+    Args:
+        private_key: Ed25519 private key (32 bytes)
+        did: Agent's DID (did:key:z6Mk...)
+        method: HTTP method (GET, POST, etc.)
+        path: URL path (/v1/attestations)
+        body: Request body bytes
+    """
+    ts = int(time.time())
+    nonce = secrets.token_hex(16)
+    body_hash = hashlib.sha256(body).hexdigest()
+
+    message = f"{method}:{path}:{ts}:{nonce}:{body_hash}"
+    signing_key = SigningKey(private_key)
+    signed = signing_key.sign(message.encode())
+    sig_hex = signed.signature.hex()
+
+    return {
+        "Authorization": f'AVP-Sig did="{did}",ts="{ts}",nonce="{nonce}",sig="{sig_hex}"',
+        "Content-Type": "application/json",
+    }

agentveil-0.2.0/agentveil/exceptions.py

@@ -0,0 +1,44 @@
+"""AVP SDK exceptions — clear, actionable error messages."""
+
+
+class AVPError(Exception):
+    """Base exception for all AVP SDK errors."""
+
+    def __init__(self, message: str, status_code: int = 0, detail: str = ""):
+        self.message = message
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(message)
+
+
+class AVPAuthError(AVPError):
+    """Authentication failed — invalid signature, expired timestamp, or nonce reuse."""
+    pass
+
+
+class AVPNotFoundError(AVPError):
+    """Resource not found — agent, card, escrow, etc."""
+    pass
+
+
+class AVPRateLimitError(AVPError):
+    """Rate limit exceeded — wait and retry."""
+
+    def __init__(self, message: str = "Rate limit exceeded", retry_after: int = 60):
+        self.retry_after = retry_after
+        super().__init__(message, status_code=429)
+
+
+class AVPInsufficientFundsError(AVPError):
+    """Not enough balance for the operation."""
+    pass
+
+
+class AVPValidationError(AVPError):
+    """Invalid input data."""
+    pass
+
+
+class AVPServerError(AVPError):
+    """Server-side error — retry later."""
+    pass

agentveil-0.2.0/agentveil/tracked.py

@@ -0,0 +1,227 @@
+"""
+Universal @avp_tracked decorator — one line = full AVP integration.
+
+Usage:
+    from agentveil import avp_tracked
+
+    @avp_tracked("https://agentveil.dev", name="my_agent", capabilities=["code_review"])
+    def review_code(pr_url: str) -> str:
+        # Your logic here
+        return analysis
+
+    # That's it. The decorator handles:
+    # - Auto-registration on first call
+    # - Positive attestation on success
+    # - Negative attestation with evidence on failure
+    # - Agent card publishing with capabilities
+
+Works with sync and async functions, any framework.
+"""
+
+import asyncio
+import functools
+import hashlib
+import inspect
+import logging
+import traceback
+from typing import Optional
+
+from agentveil.agent import AVPAgent
+from agentveil.exceptions import AVPError
+
+log = logging.getLogger("agentveil.tracked")
+
+# Cache of initialized agents (by name) to avoid re-registration
+_agent_cache: dict[str, AVPAgent] = {}
+
+
+def _get_or_create_agent(
+    base_url: str,
+    name: str,
+    capabilities: list[str],
+    provider: Optional[str],
+) -> AVPAgent:
+    """Get cached agent or create+register a new one."""
+    if name in _agent_cache:
+        return _agent_cache[name]
+
+    # Try loading existing agent
+    try:
+        agent = AVPAgent.load(base_url, name=name)
+        if agent.is_verified:
+            _agent_cache[name] = agent
+            log.info(f"Loaded existing agent: {name}")
+            return agent
+    except FileNotFoundError:
+        pass
+
+    # Create and register new agent
+    agent = AVPAgent.create(base_url, name=name, save=True)
+    try:
+        agent.register(display_name=name)
+        log.info(f"Auto-registered agent: {name} ({agent.did[:40]}...)")
+    except AVPError as e:
+        # Already registered (409) — load state and continue
+        if e.status_code == 409:
+            log.info(f"Agent already registered: {name}")
+            agent._is_registered = True
+            agent._is_verified = True
+            agent.save()
+        else:
+            log.warning(f"Registration failed: {e}")
+            raise
+
+    # Publish capabilities card
+    if capabilities:
+        try:
+            agent.publish_card(capabilities=capabilities, provider=provider)
+            log.info(f"Published card: {capabilities}")
+        except AVPError as e:
+            log.warning(f"Card publish failed (non-fatal): {e}")
+
+    _agent_cache[name] = agent
+    return agent
+
+
+def _make_evidence_hash(exc: Exception) -> str:
+    """Create SHA256 hash of exception traceback for evidence."""
+    tb = traceback.format_exception(type(exc), exc, exc.__traceback__)
+    tb_text = "".join(tb)
+    return hashlib.sha256(tb_text.encode()).hexdigest()
+
+
+def _derive_context(func_name: str) -> str:
+    """Derive attestation context from function name."""
+    # Sanitize: only alphanumeric, underscore, hyphen, dot (AVP context rules)
+    clean = "".join(c if c.isalnum() or c in ("_", "-", ".") else "_" for c in func_name)
+    return clean[:100]
+
+
+def avp_tracked(
+    base_url: str,
+    *,
+    name: str = "agent",
+    to_did: Optional[str] = None,
+    capabilities: Optional[list[str]] = None,
+    provider: Optional[str] = None,
+    weight: float = 0.8,
+    attest_self: bool = False,
+):
+    """
+    Decorator that integrates any function with Agent Veil Protocol.
+
+    On first call: auto-registers agent (if not registered).
+    On success: submits positive attestation.
+    On exception: submits negative attestation with stack trace hash as evidence.
+
+    Args:
+        base_url: AVP server URL (e.g. "https://agentveil.dev")
+        name: Agent name (used for key storage and display)
+        to_did: DID of agent to attest (required unless attest_self=True)
+        capabilities: Agent capabilities for card (defaults to [function_name])
+        provider: LLM provider for card (e.g. "anthropic")
+        weight: Attestation weight 0.0-1.0 (default 0.8)
+        attest_self: If True and to_did is None, skip attestation (no self-attest)
+
+    Usage:
+        @avp_tracked("https://agentveil.dev", name="reviewer", to_did="did:key:z6Mk...")
+        def review_code(code: str) -> str:
+            return "LGTM"
+
+        @avp_tracked("https://agentveil.dev", name="reviewer", capabilities=["code_review"])
+        async def review_code(code: str) -> str:
+            return "LGTM"
+    """
+
+    def decorator(func):
+        func_name = func.__name__
+        caps = capabilities if capabilities is not None else [func_name]
+        context = _derive_context(func_name)
+
+        if inspect.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                agent = _get_or_create_agent(base_url, name, caps, provider)
+                target_did = to_did
+
+                try:
+                    result = await func(*args, **kwargs)
+
+                    # Positive attestation on success
+                    if target_did:
+                        try:
+                            agent.attest(
+                                to_did=target_did,
+                                outcome="positive",
+                                weight=weight,
+                                context=context,
+                            )
+                        except AVPError as e:
+                            log.warning(f"Positive attestation failed (non-fatal): {e}")
+
+                    return result
+
+                except Exception as exc:
+                    # Negative attestation on failure
+                    if target_did:
+                        evidence = _make_evidence_hash(exc)
+                        try:
+                            agent.attest(
+                                to_did=target_did,
+                                outcome="negative",
+                                weight=weight,
+                                context=context,
+                                evidence_hash=evidence,
+                            )
+                        except AVPError as e:
+                            log.warning(f"Negative attestation failed (non-fatal): {e}")
+                    raise
+
+            return async_wrapper
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                agent = _get_or_create_agent(base_url, name, caps, provider)
+                target_did = to_did
+
+                try:
+                    result = func(*args, **kwargs)
+
+                    # Positive attestation on success
+                    if target_did:
+                        try:
+                            agent.attest(
+                                to_did=target_did,
+                                outcome="positive",
+                                weight=weight,
+                                context=context,
+                            )
+                        except AVPError as e:
+                            log.warning(f"Positive attestation failed (non-fatal): {e}")
+
+                    return result
+
+                except Exception as exc:
+                    # Negative attestation on failure
+                    if target_did:
+                        evidence = _make_evidence_hash(exc)
+                        try:
+                            agent.attest(
+                                to_did=target_did,
+                                outcome="negative",
+                                weight=weight,
+                                context=context,
+                                evidence_hash=evidence,
+                            )
+                        except AVPError as e:
+                            log.warning(f"Negative attestation failed (non-fatal): {e}")
+                    raise
+
+            return sync_wrapper
+
+    return decorator
+
+
+def clear_agent_cache():
+    """Clear the cached agents. Useful for testing."""
+    _agent_cache.clear()

agentveil-0.2.0/agentveil.egg-info/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: agentveil
+Version: 0.2.0
+Summary: Python SDK for Agent Veil Protocol — reputation and identity for AI agents
+Author: Agent Veil Protocol
+License: MIT
+Project-URL: Homepage, https://agentveil.dev
+Project-URL: Documentation, https://agentveil.dev/docs
+Project-URL: Repository, https://github.com/creatorrmode-lead/avp
+Keywords: ai,agents,reputation,did,identity,a2a
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: base58>=2.1.0
+Dynamic: license-file

agentveil-0.2.0/agentveil.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+agentveil/__init__.py
+agentveil/agent.py
+agentveil/auth.py
+agentveil/exceptions.py
+agentveil/tracked.py
+agentveil.egg-info/PKG-INFO
+agentveil.egg-info/SOURCES.txt
+agentveil.egg-info/dependency_links.txt
+agentveil.egg-info/requires.txt
+agentveil.egg-info/top_level.txt

agentveil-0.2.0/agentveil.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agentveil-0.2.0/agentveil.egg-info/requires.txt

@@ -0,0 +1,3 @@
+httpx>=0.27.0
+pynacl>=1.5.0
+base58>=2.1.0

agentveil-0.2.0/agentveil.egg-info/top_level.txt

@@ -0,0 +1 @@
+agentveil

agentveil-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "agentveil"
+version = "0.2.0"
+description = "Python SDK for Agent Veil Protocol — reputation and identity for AI agents"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Agent Veil Protocol"}]
+keywords = ["ai", "agents", "reputation", "did", "identity", "a2a"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+    "httpx>=0.27.0",
+    "pynacl>=1.5.0",
+    "base58>=2.1.0",
+]
+
+[project.urls]
+Homepage = "https://agentveil.dev"
+Documentation = "https://agentveil.dev/docs"
+Repository = "https://github.com/creatorrmode-lead/avp"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["agentveil*"]

agentveil-0.2.0/setup.cfg

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