nobulex 0.1.0__py3-none-any.whl

nobulex/__init__.py

@@ -0,0 +1,30 @@
+"""
+Nobulex - Trust Capital for AI Agents
+
+Tamper-proof receipts for everything your AI agent does.
+Credit scores for machines.
+
+Usage:
+    from nobulex import Agent, Receipt
+
+    # Create an agent identity
+    agent = Agent("my-agent")
+
+    # Generate a receipt for any action
+    receipt = agent.act("send_email", scope="user@example.com")
+
+    # Verify any receipt
+    assert receipt.verify()
+
+    # Get trust score
+    print(agent.trust_score)
+"""
+
+from nobulex.agent import Agent
+from nobulex.receipt import Receipt
+from nobulex.trust import TrustLedger
+from nobulex.crypto import KeyPair
+from nobulex.decorator import track
+
+__version__ = "0.1.0"
+__all__ = ["Agent", "Receipt", "TrustLedger", "KeyPair", "track"]

nobulex/__main__.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""
+Nobulex CLI - Verify receipts from the command line.
+
+Usage:
+    python -m nobulex verify receipt.json
+    python -m nobulex demo
+    python -m nobulex keygen
+"""
+
+import sys
+import json
+from nobulex import Agent, Receipt, KeyPair
+from nobulex.chain import ReceiptChain
+
+
+def cmd_demo():
+    """Run a quick demo showing receipt generation and verification."""
+    print("nobulex demo")
+    print("=" * 40)
+    agent = Agent("demo-agent")
+    r1 = agent.act("send_email", scope="user@example.com")
+    r2 = agent.act("api_call", scope="stripe.com")
+    r3 = agent.deny("delete_db", scope="production")
+    print(f"generated 3 receipts")
+    print(f"  allow: {r1.action_ref[:24]}... verified={r1.verify()}")
+    print(f"  allow: {r2.action_ref[:24]}... verified={r2.verify()}")
+    print(f"  deny:  {r3.action_ref[:24]}... verified={r3.verify()}")
+    print(f"trust score: {agent.trust_score}")
+    print(f"\ntamper test:")
+    r1.scope = "TAMPERED"
+    print(f"  modified receipt verified={r1.verify()} (tamper detected)")
+
+
+def cmd_verify(filepath):
+    """Verify a receipt JSON file."""
+    try:
+        with open(filepath) as f:
+            data = json.load(f)
+        receipt = Receipt.from_dict(data)
+        ok = receipt.verify()
+        print(f"receipt: {filepath}")
+        print(f"  agent:  {receipt.agent_id}")
+        print(f"  action: {receipt.action_type}")
+        print(f"  scope:  {receipt.scope}")
+        print(f"  verdict: {receipt.verdict}")
+        print(f"  action_ref: {receipt.action_ref[:32]}...")
+        print(f"  verified: {ok}")
+        sys.exit(0 if ok else 1)
+    except Exception as e:
+        print(f"error: {e}")
+        sys.exit(1)
+
+
+def cmd_keygen():
+    """Generate a new Ed25519 key pair."""
+    keys = KeyPair()
+    print(f"public_key: {keys.public_hex}")
+    print("(private key held in memory only)")
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("usage: python -m nobulex [demo|verify|keygen]")
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+    if cmd == "demo":
+        cmd_demo()
+    elif cmd == "verify" and len(sys.argv) >= 3:
+        cmd_verify(sys.argv[2])
+    elif cmd == "keygen":
+        cmd_keygen()
+    else:
+        print(f"unknown command: {cmd}")
+        print("usage: python -m nobulex [demo|verify|keygen]")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

nobulex/agent.py

@@ -0,0 +1,90 @@
+"""Agent identity and receipt management for Nobulex."""
+
+import time
+from typing import List, Optional
+
+from nobulex.crypto import KeyPair
+from nobulex.receipt import Receipt
+from nobulex.trust import TrustLedger
+
+
+class Agent:
+    """
+    An AI agent with a cryptographic identity and trust history.
+
+    Usage:
+        agent = Agent("my-agent")
+        receipt = agent.act("send_email", scope="user@example.com")
+        assert receipt.verify()
+        print(agent.trust_score)
+    """
+
+    def __init__(self, agent_id: str, keys: Optional[KeyPair] = None):
+        self.agent_id = agent_id
+        self.keys = keys or KeyPair()
+        self._ledger = TrustLedger()
+        self._receipts: List[Receipt] = []
+
+    @property
+    def public_key(self) -> str:
+        return self.keys.public_hex
+
+    @property
+    def trust_score(self) -> float:
+        return self._ledger.score(self.agent_id)
+
+    @property
+    def receipts(self) -> List[Receipt]:
+        return list(self._receipts)
+
+    def act(
+        self,
+        action_type: str,
+        scope: str,
+        verdict: str = "ALLOW",
+        metadata: Optional[dict] = None,
+    ) -> Receipt:
+        """
+        Record an agent action and generate a signed receipt.
+
+        Args:
+            action_type: What the agent did (e.g., "send_email")
+            scope: What resource was acted on
+            verdict: "ALLOW" or "DENY"
+            metadata: Optional extra data
+
+        Returns:
+            A signed, verifiable Receipt
+        """
+        receipt = Receipt.create(
+            agent_id=self.agent_id,
+            action_type=action_type,
+            scope=scope,
+            keys=self.keys,
+            verdict=verdict,
+            metadata=metadata,
+        )
+        self._receipts.append(receipt)
+        self._ledger.record(receipt)
+        return receipt
+
+    def deny(
+        self, action_type: str, scope: str, metadata: Optional[dict] = None
+    ) -> Receipt:
+        """Record a denied action. Proves the system caught a violation."""
+        return self.act(action_type, scope, verdict="DENY", metadata=metadata)
+
+    def verify_receipt(self, receipt: Receipt) -> bool:
+        """Verify a receipt was signed by this agent."""
+        return (
+            receipt.verify()
+            and receipt.signer_public_key == self.public_key
+        )
+
+    def __repr__(self) -> str:
+        n = len(self._receipts)
+        return (
+            f"Agent(id={self.agent_id!r}, "
+            f"receipts={n}, "
+            f"trust_score={self.trust_score:.2f})"
+        )

nobulex/chain.py

@@ -0,0 +1,156 @@
+"""Receipt chain for tamper-evident audit trails.
+
+Links receipts together with hash pointers so tampering
+with any single receipt breaks the entire chain.
+
+    from nobulex.chain import ReceiptChain
+
+    chain = ReceiptChain(agent_id="my-agent")
+    chain.append("send_email", scope="user@example.com")
+    chain.append("api_call", scope="stripe.com")
+    
+    assert chain.verify()  # Verify entire chain
+    
+    # Export the audit trail
+    chain.export("audit-trail.json")
+"""
+
+import json
+from typing import List, Optional
+from nobulex.agent import Agent
+from nobulex.receipt import Receipt
+from nobulex.crypto import sha256_hex, jcs_canonicalize
+
+
+class ReceiptChain:
+    """
+    A hash-linked chain of receipts.
+    Tampering with any receipt breaks the chain.
+    """
+
+    def __init__(self, agent_id: str = "chain-agent"):
+        self.agent = Agent(agent_id)
+        self._chain: List[dict] = []
+
+    @property
+    def length(self) -> int:
+        return len(self._chain)
+
+    @property
+    def head_hash(self) -> Optional[str]:
+        if not self._chain:
+            return None
+        return self._chain[-1]["chain_hash"]
+
+    def append(
+        self,
+        action_type: str,
+        scope: str,
+        verdict: str = "ALLOW",
+        metadata: Optional[dict] = None,
+    ) -> Receipt:
+        """Add an action to the chain."""
+        if verdict == "ALLOW":
+            receipt = self.agent.act(action_type, scope=scope, metadata=metadata)
+        else:
+            receipt = self.agent.deny(action_type, scope=scope, metadata=metadata)
+
+        # Compute chain hash: SHA-256(prev_hash + receipt.action_ref)
+        prev_hash = self.head_hash or "0" * 64
+        chain_input = prev_hash + receipt.action_ref
+        chain_hash = sha256_hex(chain_input)
+
+        self._chain.append({
+            "index": len(self._chain),
+            "receipt": receipt,
+            "prev_hash": prev_hash,
+            "chain_hash": chain_hash,
+        })
+        return receipt
+
+    def verify(self) -> bool:
+        """Verify the entire chain is intact."""
+        if not self._chain:
+            return True
+
+        for i, entry in enumerate(self._chain):
+            # Verify receipt signature
+            if not entry["receipt"].verify():
+                return False
+
+            # Verify chain hash
+            prev = self._chain[i - 1]["chain_hash"] if i > 0 else "0" * 64
+            expected = sha256_hex(prev + entry["receipt"].action_ref)
+            if entry["chain_hash"] != expected:
+                return False
+
+        return True
+
+    def export(self, filepath: str) -> None:
+        """Export the chain as a JSON audit trail."""
+        data = {
+            "agent_id": self.agent.agent_id,
+            "chain_length": len(self._chain),
+            "head_hash": self.head_hash,
+            "verified": self.verify(),
+            "entries": [
+                {
+                    "index": e["index"],
+                    "action_type": e["receipt"].action_type,
+                    "scope": e["receipt"].scope,
+                    "verdict": e["receipt"].verdict,
+                    "action_ref": e["receipt"].action_ref,
+                    "timestamp_ms": e["receipt"].timestamp_ms,
+                    "prev_hash": e["prev_hash"],
+                    "chain_hash": e["chain_hash"],
+                }
+                for e in self._chain
+            ],
+        }
+        with open(filepath, "w") as f:
+            json.dump(data, f, indent=2)
+
+    def __repr__(self) -> str:
+        v = "verified" if self.verify() else "BROKEN"
+        return f"ReceiptChain(agent={self.agent.agent_id!r}, length={self.length}, status={v})"
+
+
+def verify_audit_trail(filepath: str) -> dict:
+    """Verify an exported audit trail JSON file.
+    
+    Checks hash chain integrity (prev_hash linkage).
+    Returns a verification report.
+    """
+    import json
+    import hashlib
+    
+    with open(filepath) as f:
+        data = json.load(f)
+    
+    entries = data.get("entries", [])
+    results = []
+    all_valid = True
+    prev = "0" * 64
+    
+    for entry in entries:
+        # Verify chain linkage
+        chain_ok = entry.get("prev_hash") == prev
+        if not chain_ok:
+            all_valid = False
+        
+        results.append({
+            "index": entry.get("index", len(results)),
+            "action_type": entry.get("action_type", ""),
+            "verdict": entry.get("verdict", ""),
+            "action_ref": entry.get("action_ref", "")[:32] + "...",
+            "chain_valid": chain_ok,
+        })
+        prev = entry.get("chain_hash", "")
+    
+    return {
+        "file": filepath,
+        "total_receipts": len(results),
+        "chain_intact": all_valid,
+        "head_hash": data.get("head_hash", ""),
+        "receipts": results,
+    }

nobulex/crewai.py

@@ -0,0 +1,93 @@
+"""CrewAI integration for Nobulex receipts.
+
+Add tamper-proof receipts to any CrewAI crew:
+
+    from nobulex.crewai import NobuCrewTracker
+    tracker = NobuCrewTracker("my-crew")
+    
+    # Track agent actions
+    tracker.on_task_start(agent_name="researcher", task="find data")
+    tracker.on_task_complete(agent_name="researcher", task="find data", result="found 10 results")
+    tracker.on_task_fail(agent_name="writer", task="write report", error="timeout")
+    
+    print(tracker.trust_scores)  # Per-agent trust scores
+"""
+
+from typing import Dict, List, Optional
+from nobulex.agent import Agent
+from nobulex.receipt import Receipt
+from nobulex.trust import TrustLedger
+
+
+class NobuCrewTracker:
+    """Track trust across a crew of AI agents."""
+
+    def __init__(self, crew_id: str = "crewai-crew"):
+        self.crew_id = crew_id
+        self._agents: Dict[str, Agent] = {}
+        self._all_receipts: List[Receipt] = []
+
+    def _get_agent(self, agent_name: str) -> Agent:
+        if agent_name not in self._agents:
+            agent_id = f"{self.crew_id}:{agent_name}"
+            self._agents[agent_name] = Agent(agent_id)
+        return self._agents[agent_name]
+
+    def on_task_start(
+        self, agent_name: str, task: str, metadata: Optional[dict] = None
+    ) -> Receipt:
+        agent = self._get_agent(agent_name)
+        receipt = agent.act(
+            action_type=f"task:{task}",
+            scope=f"crew:{self.crew_id}",
+            metadata=metadata or {},
+        )
+        self._all_receipts.append(receipt)
+        return receipt
+
+    def on_task_complete(
+        self, agent_name: str, task: str, result: str = "", metadata: Optional[dict] = None
+    ) -> Receipt:
+        agent = self._get_agent(agent_name)
+        meta = metadata or {}
+        meta["result_preview"] = result[:200]
+        receipt = agent.act(
+            action_type=f"complete:{task}",
+            scope=f"crew:{self.crew_id}",
+            metadata=meta,
+        )
+        self._all_receipts.append(receipt)
+        return receipt
+
+    def on_task_fail(
+        self, agent_name: str, task: str, error: str = "", metadata: Optional[dict] = None
+    ) -> Receipt:
+        agent = self._get_agent(agent_name)
+        meta = metadata or {}
+        meta["error"] = error[:200]
+        receipt = agent.deny(
+            action_type=f"fail:{task}",
+            scope=f"crew:{self.crew_id}",
+            metadata=meta,
+        )
+        self._all_receipts.append(receipt)
+        return receipt
+
+    @property
+    def trust_scores(self) -> Dict[str, float]:
+        return {name: a.trust_score for name, a in self._agents.items()}
+
+    @property
+    def receipts(self) -> List[Receipt]:
+        return list(self._all_receipts)
+
+    @property
+    def agent_names(self) -> List[str]:
+        return list(self._agents.keys())
+
+    def summary(self) -> str:
+        lines = [f"Crew: {self.crew_id}", f"Agents: {len(self._agents)}", f"Total receipts: {len(self._all_receipts)}", ""]
+        for name, agent in self._agents.items():
+            n = len(agent.receipts)
+            lines.append(f"  {name}: {n} receipts, trust={agent.trust_score:.1f}")
+        return "\n".join(lines)

nobulex/crypto.py

@@ -0,0 +1,86 @@
+"""Cryptographic primitives for Nobulex receipts."""
+
+import hashlib
+import json
+from typing import Optional
+
+import rfc8785
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives import serialization
+
+
+class KeyPair:
+    """Ed25519 key pair for signing and verifying receipts."""
+
+    def __init__(self, private_key: Optional[Ed25519PrivateKey] = None):
+        if private_key is None:
+            private_key = Ed25519PrivateKey.generate()
+        self._private = private_key
+        self._public = private_key.public_key()
+
+    @property
+    def public_bytes(self) -> bytes:
+        return self._public.public_bytes(
+            serialization.Encoding.Raw,
+            serialization.PublicFormat.Raw,
+        )
+
+    @property
+    def public_hex(self) -> str:
+        return self.public_bytes.hex()
+
+    def sign(self, data: bytes) -> bytes:
+        return self._private.sign(data)
+
+    def sign_hex(self, data: bytes) -> str:
+        return self.sign(data).hex()
+
+    @staticmethod
+    def verify_signature(
+        public_bytes: bytes, signature: bytes, data: bytes
+    ) -> bool:
+        try:
+            pub = Ed25519PublicKey.from_public_bytes(public_bytes)
+            pub.verify(signature, data)
+            return True
+        except Exception:
+            return False
+
+    @classmethod
+    def from_seed(cls, seed: bytes) -> "KeyPair":
+        """Create a key pair from a 32-byte seed (deterministic)."""
+        private_key = Ed25519PrivateKey.from_private_bytes(seed)
+        return cls(private_key)
+
+
+def jcs_canonicalize(obj: dict) -> str:
+    """
+    JSON Canonicalization Scheme (RFC 8785).
+    Uses the rfc8785 package for strict conformance.
+    """
+    return rfc8785.dumps(obj).decode("utf-8")
+
+
+def sha256_hex(data: str) -> str:
+    """SHA-256 hash of a string, returned as lowercase hex."""
+    return hashlib.sha256(data.encode("utf-8")).hexdigest()
+
+
+def compute_action_ref(
+    agent_id: str, action_type: str, scope: str, timestamp_ms: int
+) -> str:
+    """
+    Compute the action_ref hash from receipt preimage fields.
+    action_ref = SHA-256(JCS({agent_id, action_type, scope, timestamp_ms}))
+    """
+    preimage = {
+        "agent_id": agent_id,
+        "action_type": action_type,
+        "scope": scope,
+        "timestamp_ms": timestamp_ms,
+    }
+    canonical = jcs_canonicalize(preimage)
+    return sha256_hex(canonical)

nobulex/decorator.py

@@ -0,0 +1,105 @@
+"""Universal decorator for adding receipts to any function.
+
+Works with any Python function, any framework, any agent:
+
+    from nobulex.decorator import track
+
+    @track(agent_id="my-agent")
+    def send_email(to, subject, body):
+        # your code here
+        return "sent"
+
+    # Every call now generates a tamper-proof receipt
+    result = send_email("user@example.com", "Hello", "World")
+    
+    # Access receipts
+    print(send_email.receipts)
+    print(send_email.trust_score)
+"""
+
+import functools
+from typing import Optional, Callable, Any
+from nobulex.agent import Agent
+from nobulex.receipt import Receipt
+
+
+def track(
+    agent_id: str = "tracked-agent",
+    action_type: Optional[str] = None,
+) -> Callable:
+    """
+    Decorator that generates a receipt for every function call.
+
+    Args:
+        agent_id: Identifier for the agent
+        action_type: Override action name (defaults to function name)
+
+    The decorated function gains these attributes:
+        .receipts: List of all receipts
+        .trust_score: Current Trust Capital score
+        .agent: The underlying Agent object
+        .last_receipt: Most recent receipt
+
+    Usage:
+        @track("my-bot")
+        def process_order(order_id):
+            return do_something(order_id)
+
+        result = process_order("ORD-123")
+        print(process_order.last_receipt)  # Receipt(...)
+        print(process_order.trust_score)   # 13.86
+    """
+    agent = Agent(agent_id)
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            action = action_type or func.__name__
+            scope = f"args:{str(args)[:100]}"
+
+            try:
+                result = func(*args, **kwargs)
+                receipt = agent.act(action, scope=scope)
+                wrapper.last_receipt = receipt
+                return result
+            except Exception as e:
+                receipt = agent.deny(
+                    action, scope=f"error:{str(e)[:100]}"
+                )
+                wrapper.last_receipt = receipt
+                raise
+
+        wrapper.agent = agent
+        wrapper.receipts = agent.receipts
+        wrapper.trust_score = property(lambda self: agent.trust_score)
+
+        # Make trust_score accessible as attribute
+        class TrackedFunc:
+            def __call__(self, *args, **kwargs):
+                return wrapper(*args, **kwargs)
+
+            @property
+            def receipts(self):
+                return agent.receipts
+
+            @property
+            def trust_score(self):
+                return agent.trust_score
+
+            @property
+            def agent(self):
+                return agent
+
+            @property
+            def last_receipt(self):
+                return getattr(wrapper, 'last_receipt', None)
+
+            def __getattr__(self, name):
+                return getattr(func, name)
+
+        tracked = TrackedFunc()
+        tracked.__name__ = func.__name__
+        tracked.__doc__ = func.__doc__
+        return tracked
+
+    return decorator

nobulex/langchain.py

@@ -0,0 +1,113 @@
+"""LangChain middleware for Nobulex receipts.
+
+Add tamper-proof receipts to any LangChain agent in 2 lines:
+
+    from nobulex.integrations.langchain import NobuReceipts
+    agent = NobuReceipts.wrap(your_agent, agent_id="my-agent")
+
+Every tool call now generates a cryptographic receipt.
+"""
+
+from typing import Any, Dict, List, Optional, Callable
+from nobulex.agent import Agent
+from nobulex.receipt import Receipt
+
+
+class NobuReceipts:
+    """
+    LangChain callback handler that generates receipts
+    for every tool call an agent makes.
+
+    Usage:
+        from langchain.agents import create_tool_calling_agent
+        from nobulex.integrations.langchain import NobuReceipts
+
+        tracker = NobuReceipts(agent_id="my-agent")
+
+        # Option 1: Use as a callback
+        agent.invoke(input, config={"callbacks": [tracker]})
+
+        # Option 2: Wrap the agent
+        wrapped = NobuReceipts.wrap(agent, "my-agent")
+        wrapped.invoke(input)
+
+        # Get receipts
+        print(tracker.receipts)
+        print(tracker.trust_score)
+    """
+
+    def __init__(self, agent_id: str = "langchain-agent"):
+        self.agent = Agent(agent_id)
+        self._pending: Dict[str, dict] = {}
+
+    @property
+    def receipts(self) -> List[Receipt]:
+        return self.agent.receipts
+
+    @property
+    def trust_score(self) -> float:
+        return self.agent.trust_score
+
+    def on_tool_start(
+        self, tool_name: str, tool_input: Any, **kwargs
+    ) -> Receipt:
+        """Generate a receipt when a tool call starts."""
+        scope = str(tool_input)[:200]  # Truncate long inputs
+        receipt = self.agent.act(
+            action_type=f"tool:{tool_name}",
+            scope=scope,
+        )
+        return receipt
+
+    def on_tool_error(
+        self, tool_name: str, error: str, **kwargs
+    ) -> Receipt:
+        """Generate a DENY receipt when a tool call fails."""
+        receipt = self.agent.deny(
+            action_type=f"tool:{tool_name}",
+            scope=f"error:{error[:200]}",
+        )
+        return receipt
+
+    @classmethod
+    def wrap(cls, runnable: Any, agent_id: str = "langchain-agent"):
+        """
+        Wrap any LangChain runnable with receipt tracking.
+
+        Returns a wrapper that generates receipts for every
+        tool call while passing through all other behavior.
+        """
+        tracker = cls(agent_id=agent_id)
+
+        class ReceiptWrapper:
+            def __init__(self, inner, tracker):
+                self._inner = inner
+                self.tracker = tracker
+
+            def invoke(self, input: Any, **kwargs) -> Any:
+                result = self._inner.invoke(input, **kwargs)
+                # Generate receipt for the invocation
+                action = "invoke"
+                scope = str(input)[:200]
+                self.tracker.agent.act(action, scope=scope)
+                return result
+
+            async def ainvoke(self, input: Any, **kwargs) -> Any:
+                result = await self._inner.ainvoke(input, **kwargs)
+                action = "ainvoke"
+                scope = str(input)[:200]
+                self.tracker.agent.act(action, scope=scope)
+                return result
+
+            @property
+            def receipts(self):
+                return self.tracker.receipts
+
+            @property
+            def trust_score(self):
+                return self.tracker.trust_score
+
+            def __getattr__(self, name):
+                return getattr(self._inner, name)
+
+        return ReceiptWrapper(runnable, tracker)

nobulex/receipt.py

@@ -0,0 +1,162 @@
+"""Receipt generation and verification for Nobulex."""
+
+import time
+from dataclasses import dataclass, field, asdict
+from typing import Optional, Literal
+
+from nobulex.crypto import (
+    KeyPair,
+    jcs_canonicalize,
+    sha256_hex,
+    compute_action_ref,
+)
+
+
+@dataclass
+class Receipt:
+    """
+    A tamper-proof cryptographic receipt for an AI agent action.
+    
+    Every receipt proves:
+    - WHO acted (agent_id)
+    - WHAT they did (action_type)  
+    - ON WHAT (scope)
+    - WHEN (timestamp_ms)
+    - WHETHER it was allowed (verdict)
+    - WHO verified it (signer)
+    """
+
+    agent_id: str
+    action_type: str
+    scope: str
+    timestamp_ms: int
+    verdict: Literal["ALLOW", "DENY"] = "ALLOW"
+    action_ref: str = ""
+    signature: str = ""
+    signer_public_key: str = ""
+    version: str = "nobulex-receipt-v0.1"
+    policy_version: str = ""
+    attempt_id: str = ""
+    metadata: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        """Convert receipt to dictionary (excludes empty fields)."""
+        d = asdict(self)
+        return {k: v for k, v in d.items() if v != "" and v != {}}
+
+    def to_canonical(self) -> str:
+        """JCS-canonical JSON representation (for hashing/signing)."""
+        signable = {
+            "agent_id": self.agent_id,
+            "action_type": self.action_type,
+            "scope": self.scope,
+            "timestamp_ms": self.timestamp_ms,
+            "verdict": self.verdict,
+            "action_ref": self.action_ref,
+            "version": self.version,
+        }
+        if self.policy_version:
+            signable["policy_version"] = self.policy_version
+        if self.attempt_id:
+            signable["attempt_id"] = self.attempt_id
+        if self.metadata:
+            signable["metadata"] = self.metadata
+        return jcs_canonicalize(signable)
+
+    def verify(self) -> bool:
+        """Verify the receipt's cryptographic signature."""
+        if not self.signature or not self.signer_public_key:
+            return False
+        try:
+            canonical = self.to_canonical()
+            return KeyPair.verify_signature(
+                bytes.fromhex(self.signer_public_key),
+                bytes.fromhex(self.signature),
+                canonical.encode("utf-8"),
+            )
+        except Exception:
+            return False
+
+    def to_json(self) -> str:
+        """Serialize receipt to JSON string."""
+        import json
+        return json.dumps(self.to_dict(), indent=2)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Receipt":
+        """Create a Receipt from a dictionary."""
+        return cls(
+            agent_id=data["agent_id"],
+            action_type=data["action_type"],
+            scope=data["scope"],
+            timestamp_ms=data["timestamp_ms"],
+            verdict=data.get("verdict", "ALLOW"),
+            action_ref=data.get("action_ref", ""),
+            signature=data.get("signature", ""),
+            signer_public_key=data.get("signer_public_key", ""),
+            version=data.get("version", "nobulex-receipt-v0.1"),
+            policy_version=data.get("policy_version", ""),
+            attempt_id=data.get("attempt_id", ""),
+            metadata=data.get("metadata", {}),
+        )
+
+    @classmethod
+    def create(
+        cls,
+        agent_id: str,
+        action_type: str,
+        scope: str,
+        keys: KeyPair,
+        verdict: str = "ALLOW",
+        timestamp_ms: Optional[int] = None,
+        metadata: Optional[dict] = None,
+        policy_version: str = "",
+        attempt_id: str = "",
+    ) -> "Receipt":
+        """
+        Create and sign a new receipt.
+
+        Args:
+            agent_id: The agent's identifier
+            action_type: What the agent did (e.g., "send_email", "api_call")
+            scope: What resource was acted on
+            keys: KeyPair used to sign the receipt
+            verdict: "ALLOW" or "DENY"
+            timestamp_ms: Unix epoch milliseconds (auto-generated if omitted)
+            metadata: Optional additional data
+
+        Returns:
+            A signed Receipt
+        """
+        if timestamp_ms is None:
+            timestamp_ms = int(time.time() * 1000)
+
+        action_ref = compute_action_ref(
+            agent_id, action_type, scope, timestamp_ms
+        )
+
+        receipt = cls(
+            agent_id=agent_id,
+            action_type=action_type,
+            scope=scope,
+            timestamp_ms=timestamp_ms,
+            verdict=verdict,
+            action_ref=action_ref,
+            signer_public_key=keys.public_hex,
+            policy_version=policy_version,
+            attempt_id=attempt_id,
+            metadata=metadata or {},
+        )
+
+        canonical = receipt.to_canonical()
+        receipt.signature = keys.sign_hex(canonical.encode("utf-8"))
+        return receipt
+
+    def __repr__(self) -> str:
+        status = "verified" if self.verify() else "unverified"
+        return (
+            f"Receipt(agent={self.agent_id!r}, "
+            f"action={self.action_type!r}, "
+            f"verdict={self.verdict}, "
+            f"status={status})"
+        )

nobulex/trust.py

@@ -0,0 +1,68 @@
+"""Trust Capital scoring for Nobulex agents."""
+
+from collections import defaultdict
+from typing import Dict, List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from nobulex.receipt import Receipt
+
+
+class TrustLedger:
+    """
+    Computes Trust Capital scores from receipt history.
+
+    Trust Capital is the credit score for machines.
+    It's earned through verified behavior, not granted.
+    You can copy the code, but you can't copy the score.
+
+    Scoring rules:
+    - Each ALLOW receipt adds trust (+1.0)
+    - Each DENY receipt proves the system caught a
+      violation, slight trust boost (+0.2)
+    - Score decays over time without new receipts
+    - Score is bounded [0.0, 100.0]
+    """
+
+    def __init__(self):
+        self._receipts: Dict[str, list] = defaultdict(list)
+
+    def record(self, receipt: "Receipt") -> None:
+        """Record a receipt in the ledger."""
+        self._receipts[receipt.agent_id].append(receipt)
+
+    def score(self, agent_id: str) -> float:
+        """
+        Compute Trust Capital score for an agent.
+
+        Returns a score between 0.0 and 100.0.
+        """
+        receipts = self._receipts.get(agent_id, [])
+        if not receipts:
+            return 0.0
+
+        raw = 0.0
+        for r in receipts:
+            if r.verdict == "ALLOW":
+                raw += 1.0
+            elif r.verdict == "DENY":
+                raw += 0.2  # Caught violation = slight trust
+
+        # Logarithmic scaling: diminishing returns
+        import math
+        scaled = 20.0 * math.log1p(raw)
+
+        return min(100.0, round(scaled, 2))
+
+    def history(self, agent_id: str) -> List["Receipt"]:
+        """Get all receipts for an agent."""
+        return list(self._receipts.get(agent_id, []))
+
+    def agent_count(self) -> int:
+        """Number of agents tracked."""
+        return len(self._receipts)
+
+    def receipt_count(self, agent_id: str = "") -> int:
+        """Total receipts, or receipts for a specific agent."""
+        if agent_id:
+            return len(self._receipts.get(agent_id, []))
+        return sum(len(r) for r in self._receipts.values())

nobulex-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: nobulex
+Version: 0.1.0
+Summary: Trust Capital for AI agents. Tamper-proof receipts for everything your AI agent does.
+Author-email: Arian Gogani <nobulex.dev@gmail.com>
+License: MIT
+Project-URL: Homepage, https://nobulex.com
+Project-URL: Repository, https://github.com/arian-gogani/nobulex
+Project-URL: Documentation, https://nobulex.com/docs
+Keywords: ai,agents,trust,accountability,receipts,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0
+Requires-Dist: rfc8785>=0.1.2
+
+# nobulex
+
+**Trust Capital for AI agents. Tamper-proof receipts for everything your AI agent does.**
+
+Credit scores exist for people. They don't exist for machines. Until now.
+
+## Install
+
+```bash
+pip install nobulex
+```
+
+## Quick Start (5 minutes)
+
+```python
+from nobulex import Agent
+
+# Create an agent with a cryptographic identity
+agent = Agent("my-agent")
+
+# Every action generates a signed receipt
+receipt = agent.act("send_email", scope="user@example.com")
+
+# Receipts are cryptographically verifiable
+assert receipt.verify()  # Ed25519 signature check
+print(receipt.action_ref)  # SHA-256 hash of the action
+
+# Trust Capital builds with every verified action
+print(agent.trust_score)  # 13.86
+
+# Denied actions prove the system caught violations
+agent.deny("delete_database", scope="production")
+print(agent.trust_score)  # 15.22
+```
+
+## What is this?
+
+Every time an AI agent does something, Nobulex generates a **cryptographic receipt**:
+
+- **WHO** acted (agent_id)
+- **WHAT** they did (action_type)
+- **ON WHAT** (scope)
+- **WHEN** (timestamp_ms)
+- **WHETHER** it was allowed (verdict)
+- **PROOF** it happened (Ed25519 signature + SHA-256 hash)
+
+Receipts are tamper-proof. You can't edit them after the fact. You can't fake them. An independent verifier can check any receipt without trusting the agent.
+
+Over time, receipts build into **Trust Capital** — a portable trust score that follows the agent across deployments. You can copy an agent's code, but you can't copy its credit score. The copy starts at zero.
+
+## Use Cases
+
+- **Audit trails**: Prove what your agent did to regulators (EU AI Act Article 12)
+- **Agent-to-agent trust**: Agents verify each other's track records before collaborating
+- **Compliance**: Tamper-evident records for financial, healthcare, and legal agents
+- **Accountability**: When something goes wrong, receipts prove what happened
+
+## API
+
+### Agent
+
+```python
+from nobulex import Agent
+
+agent = Agent("my-agent")          # Create agent identity
+receipt = agent.act("tool_call",   # Record an action
+                    scope="api.stripe.com")
+agent.deny("unauthorized_action",  # Record a caught violation
+           scope="admin_panel")
+print(agent.trust_score)           # Get Trust Capital score
+print(agent.receipts)              # Get all receipts
+```
+
+### Receipt
+
+```python
+from nobulex import Receipt, KeyPair
+
+keys = KeyPair()
+receipt = Receipt.create(
+    agent_id="agent-1",
+    action_type="send_email",
+    scope="user@example.com",
+    keys=keys,
+)
+assert receipt.verify()            # Verify signature
+print(receipt.action_ref)          # Content-addressable hash
+print(receipt.to_json())           # JSON serialization
+```
+
+## License
+
+MIT — Arian Gogani (@nobulexlabs)

nobulex-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+nobulex/__init__.py,sha256=80yrzy0_bmpS1mClYfsxaRAzpzUJappMrVAMA9rUdfM,719
+nobulex/__main__.py,sha256=JuqAQ-y3xh7CR-LQ4VxstaLPq-I4C_oG4YABzriavks,2357
+nobulex/agent.py,sha256=Wy6Y6zFb355-yzlw5kMdaKovGQAzIaERJbgYdFTP9Y8,2545
+nobulex/chain.py,sha256=aQAn4PhyAkhblTvrxvTxbzaEX7PW3S_q-A99quHoDmc,4773
+nobulex/crewai.py,sha256=T5erdPb9B8EoMNqLlJ6WnYHaCrVecrkZCXk8nYNlCuE,3173
+nobulex/crypto.py,sha256=JUmASxF5ASVJclGsAqQofRVMB5WB87KylXlgJS89lmk,2451
+nobulex/decorator.py,sha256=kIN6hAEe4XNGtWMTFugKXHSyxglwOKLWoEq1MVmtDoo,3041
+nobulex/langchain.py,sha256=Zyj1CaIGp9tKO9XS0KQgQXdp_Q--dE3aDMCbCQbxXtM,3514
+nobulex/receipt.py,sha256=IgQ_pRkxUVjjeevRFYSCzGc9RsVomLVfOXJ3UWrT_Pc,5079
+nobulex/trust.py,sha256=dhCX3MN1qtosX6i7pCvNdLpo5245-ZyGdi6oOmIPDIs,2091
+nobulex-0.1.0.dist-info/METADATA,sha256=H5dYlwTW9umQ4GQIWUd8mmFz--qtrNOAJ4jYZAavo0c,3789
+nobulex-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+nobulex-0.1.0.dist-info/top_level.txt,sha256=rdY9aOxWT0d-wwdxsuJ9YqK3jm8n3c85N47m7NC2K3U,8
+nobulex-0.1.0.dist-info/RECORD,,

nobulex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nobulex-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nobulex