nobulex 0.1.0__tar.gz

nobulex-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,93 @@
+# 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/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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)