xproof 0.2.0__tar.gz → 0.2.2__tar.gz

xproof-0.2.2/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: xproof
+Version: 0.2.2
+Summary: Python SDK for xProof — blockchain-anchored proof-of-existence for AI agents on MultiversX
+Author-email: xProof <contact@xproof.app>
+License-Expression: MIT
+Project-URL: Homepage, https://xproof.app
+Project-URL: Repository, https://github.com/jasonxkensei/xproof
+Project-URL: Documentation, https://xproof.app/docs
+Project-URL: Issues, https://github.com/jasonxkensei/xproof/issues
+Project-URL: Changelog, https://github.com/jasonxkensei/xproof/releases
+Keywords: blockchain,multiversx,proof-of-existence,certification,sha256,ai-agents,accountability,audit-trail,web3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: responses>=0.20.0; extra == "dev"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.13.0; extra == "llamaindex"
+Provides-Extra: autogen
+Requires-Dist: pyautogen>=0.2.0; extra == "autogen"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.0.3; extra == "openai-agents"
+Provides-Extra: deerflow
+Dynamic: license-file
+
+# xproof
+
+On-chain decision provenance for autonomous agents. **WHY before acting. WHAT after.** Timestamps written by the chain, not your agent.
+
+```bash
+pip install xproof
+```
+
+---
+
+## 3 steps. 30 seconds.
+
+### Step 1 — Register (no wallet, no payment)
+
+```bash
+curl -X POST https://xproof.app/api/agent/register \
+  -H "Content-Type: application/json" \
+  -d '{"agent_name": "my-agent"}'
+```
+
+```json
+{ "api_key": "pm_...", "trial": { "remaining": 10 } }
+```
+
+### Step 2 — Anchor WHY before acting
+
+Hash your reasoning and certify it *before* your agent executes.
+
+```bash
+curl -X POST https://xproof.app/api/proof \
+  -H "Authorization: Bearer pm_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "file_hash": "<sha256_of_reasoning>",
+    "file_name": "reasoning.json",
+    "author": "my-agent",
+    "metadata": { "action_type": "decision" }
+  }'
+```
+
+```json
+{ "id": "why-proof-uuid", "transaction_hash": "0x..." }
+```
+
+### Step 3 — Anchor WHAT after acting
+
+Hash your output and link it to the WHY proof.
+
+```bash
+curl -X POST https://xproof.app/api/proof \
+  -H "Authorization: Bearer pm_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "file_hash": "<sha256_of_output>",
+    "file_name": "output.json",
+    "author": "my-agent",
+    "metadata": { "action_type": "execution", "why_proof_id": "why-proof-uuid" }
+  }'
+```
+
+```json
+{ "id": "what-proof-uuid", "transaction_hash": "0x..." }
+```
+
+When something goes wrong, you don't guess. You verify.
+
+---
+
+## Python SDK
+
+```python
+from xproof import XProofClient, hash_string
+
+# Register — zero-friction, no wallet, no payment
+client = XProofClient.register("my-agent")
+# 10 free certs, API key stored automatically
+
+# Step 2: Anchor WHY before acting
+why = client.certify_hash(
+    file_hash=hash_string('{"action": "summarize", "model": "gpt-4"}'),
+    file_name="reasoning.json",
+    author="my-agent",
+    metadata={"action_type": "decision"},
+)
+
+# Step 3: Anchor WHAT after acting
+what = client.certify_hash(
+    file_hash=hash_string(execution_output),
+    file_name="output.json",
+    author="my-agent",
+    metadata={"action_type": "execution", "why_proof_id": why.id},
+)
+
+print(what.transaction_url)  # MultiversX explorer link
+```
+
+Or use an existing API key:
+
+```python
+client = XProofClient(api_key="pm_your_api_key")
+```
+
+---
+
+## Framework Integrations
+
+### LangChain
+
+```python
+from xproof.integrations.langchain import XProofCallbackHandler
+
+handler = XProofCallbackHandler(api_key="pm_...")
+llm = ChatOpenAI(callbacks=[handler])
+```
+
+### CrewAI
+
+```python
+from xproof.integrations.crewai import XProofListener
+
+listener = XProofListener(api_key="pm_...")
+```
+
+### AutoGen
+
+```python
+from xproof.integrations.autogen import XProofHook
+
+hook = XProofHook(api_key="pm_...")
+agent.register_hook("process_last_received_message", hook.on_message)
+```
+
+### LlamaIndex
+
+```python
+from xproof.integrations.llamaindex import XProofCallbackHandler
+from llama_index.core import Settings
+from llama_index.core.callbacks import CallbackManager
+
+Settings.callback_manager = CallbackManager([XProofCallbackHandler(api_key="pm_...")])
+```
+
+---
+
+## 4W Framework (WHO / WHAT / WHEN / WHY)
+
+Full accountability metadata on every certification:
+
+```python
+from xproof import XProofClient, hash_bytes
+
+client = XProofClient(api_key="pm_your_key")
+
+action_data = b'{"action": "generate_report", "model": "gpt-4"}'
+action_hash = hash_bytes(action_data)
+
+cert = client.certify_hash(
+    file_hash=action_hash,
+    file_name="agent-action.json",
+    author="research-agent",
+    who="erd1abc...or-agent-id",
+    what=action_hash,
+    when="2026-03-20T12:00:00Z",
+    why=hash_bytes(b"Summarize Q1 earnings report"),
+    metadata={"model": "gpt-4", "session_id": "sess-123"},
+)
+```
+
+## Batch Certification
+
+Certify up to 50 files in a single API call:
+
+```python
+results = client.batch_certify([
+    {"file_hash": "abc123...", "file_name": "file1.pdf", "author": "my-agent"},
+    {"file_hash": "def456...", "file_name": "file2.pdf"},
+])
+
+print(results.summary.total)    # 2
+print(results.summary.created)  # 2
+```
+
+## Certify a Local File
+
+```python
+# Auto-hashes with SHA-256
+cert = client.certify("path/to/report.pdf", author="my-agent")
+print(cert.id)
+print(cert.transaction_url)
+```
+
+## Verify a Proof
+
+```python
+# By proof ID
+proof = client.verify("certification-uuid")
+print(proof.file_name, proof.blockchain_status)
+
+# By file hash
+proof = client.verify_hash("e3b0c442...")
+```
+
+## Pricing
+
+```python
+pricing = client.get_pricing()
+print(pricing.price_usd)  # e.g. 0.05
+```
+
+## API Reference
+
+### `XProofClient(api_key=None, base_url="https://xproof.app", timeout=30)`
+
+| Parameter  | Type  | Default                |
+|------------|-------|------------------------|
+| `api_key`  | `str` | `None`                 |
+| `base_url` | `str` | `"https://xproof.app"` |
+| `timeout`  | `int` | `30` (seconds)         |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `XProofClient.register(agent_name)` | Register agent, get trial key |
+| `certify(path, author, file_name?, **fourW)` | Certify file (hashes locally) |
+| `certify_hash(file_hash, file_name, author, **fourW)` | Certify by pre-computed hash |
+| `batch_certify(files)` | Batch certify (up to 50) |
+| `verify(proof_id)` | Look up by proof ID |
+| `verify_hash(file_hash)` | Look up by file hash |
+| `get_pricing()` | Get current pricing |
+
+## Links
+
+- [xproof.app](https://xproof.app) — dashboard & docs
+- [npm SDK](https://www.npmjs.com/package/@xproof/xproof) — `npm install @xproof/xproof`
+- [Examples](https://github.com/jasonxkensei/xproof-examples) — LangChain, CrewAI, AutoGen, LlamaIndex
+
+## License
+
+MIT

xproof-0.2.2/README.md

@@ -0,0 +1,240 @@
+# xproof
+
+On-chain decision provenance for autonomous agents. **WHY before acting. WHAT after.** Timestamps written by the chain, not your agent.
+
+```bash
+pip install xproof
+```
+
+---
+
+## 3 steps. 30 seconds.
+
+### Step 1 — Register (no wallet, no payment)
+
+```bash
+curl -X POST https://xproof.app/api/agent/register \
+  -H "Content-Type: application/json" \
+  -d '{"agent_name": "my-agent"}'
+```
+
+```json
+{ "api_key": "pm_...", "trial": { "remaining": 10 } }
+```
+
+### Step 2 — Anchor WHY before acting
+
+Hash your reasoning and certify it *before* your agent executes.
+
+```bash
+curl -X POST https://xproof.app/api/proof \
+  -H "Authorization: Bearer pm_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "file_hash": "<sha256_of_reasoning>",
+    "file_name": "reasoning.json",
+    "author": "my-agent",
+    "metadata": { "action_type": "decision" }
+  }'
+```
+
+```json
+{ "id": "why-proof-uuid", "transaction_hash": "0x..." }
+```
+
+### Step 3 — Anchor WHAT after acting
+
+Hash your output and link it to the WHY proof.
+
+```bash
+curl -X POST https://xproof.app/api/proof \
+  -H "Authorization: Bearer pm_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "file_hash": "<sha256_of_output>",
+    "file_name": "output.json",
+    "author": "my-agent",
+    "metadata": { "action_type": "execution", "why_proof_id": "why-proof-uuid" }
+  }'
+```
+
+```json
+{ "id": "what-proof-uuid", "transaction_hash": "0x..." }
+```
+
+When something goes wrong, you don't guess. You verify.
+
+---
+
+## Python SDK
+
+```python
+from xproof import XProofClient, hash_string
+
+# Register — zero-friction, no wallet, no payment
+client = XProofClient.register("my-agent")
+# 10 free certs, API key stored automatically
+
+# Step 2: Anchor WHY before acting
+why = client.certify_hash(
+    file_hash=hash_string('{"action": "summarize", "model": "gpt-4"}'),
+    file_name="reasoning.json",
+    author="my-agent",
+    metadata={"action_type": "decision"},
+)
+
+# Step 3: Anchor WHAT after acting
+what = client.certify_hash(
+    file_hash=hash_string(execution_output),
+    file_name="output.json",
+    author="my-agent",
+    metadata={"action_type": "execution", "why_proof_id": why.id},
+)
+
+print(what.transaction_url)  # MultiversX explorer link
+```
+
+Or use an existing API key:
+
+```python
+client = XProofClient(api_key="pm_your_api_key")
+```
+
+---
+
+## Framework Integrations
+
+### LangChain
+
+```python
+from xproof.integrations.langchain import XProofCallbackHandler
+
+handler = XProofCallbackHandler(api_key="pm_...")
+llm = ChatOpenAI(callbacks=[handler])
+```
+
+### CrewAI
+
+```python
+from xproof.integrations.crewai import XProofListener
+
+listener = XProofListener(api_key="pm_...")
+```
+
+### AutoGen
+
+```python
+from xproof.integrations.autogen import XProofHook
+
+hook = XProofHook(api_key="pm_...")
+agent.register_hook("process_last_received_message", hook.on_message)
+```
+
+### LlamaIndex
+
+```python
+from xproof.integrations.llamaindex import XProofCallbackHandler
+from llama_index.core import Settings
+from llama_index.core.callbacks import CallbackManager
+
+Settings.callback_manager = CallbackManager([XProofCallbackHandler(api_key="pm_...")])
+```
+
+---
+
+## 4W Framework (WHO / WHAT / WHEN / WHY)
+
+Full accountability metadata on every certification:
+
+```python
+from xproof import XProofClient, hash_bytes
+
+client = XProofClient(api_key="pm_your_key")
+
+action_data = b'{"action": "generate_report", "model": "gpt-4"}'
+action_hash = hash_bytes(action_data)
+
+cert = client.certify_hash(
+    file_hash=action_hash,
+    file_name="agent-action.json",
+    author="research-agent",
+    who="erd1abc...or-agent-id",
+    what=action_hash,
+    when="2026-03-20T12:00:00Z",
+    why=hash_bytes(b"Summarize Q1 earnings report"),
+    metadata={"model": "gpt-4", "session_id": "sess-123"},
+)
+```
+
+## Batch Certification
+
+Certify up to 50 files in a single API call:
+
+```python
+results = client.batch_certify([
+    {"file_hash": "abc123...", "file_name": "file1.pdf", "author": "my-agent"},
+    {"file_hash": "def456...", "file_name": "file2.pdf"},
+])
+
+print(results.summary.total)    # 2
+print(results.summary.created)  # 2
+```
+
+## Certify a Local File
+
+```python
+# Auto-hashes with SHA-256
+cert = client.certify("path/to/report.pdf", author="my-agent")
+print(cert.id)
+print(cert.transaction_url)
+```
+
+## Verify a Proof
+
+```python
+# By proof ID
+proof = client.verify("certification-uuid")
+print(proof.file_name, proof.blockchain_status)
+
+# By file hash
+proof = client.verify_hash("e3b0c442...")
+```
+
+## Pricing
+
+```python
+pricing = client.get_pricing()
+print(pricing.price_usd)  # e.g. 0.05
+```
+
+## API Reference
+
+### `XProofClient(api_key=None, base_url="https://xproof.app", timeout=30)`
+
+| Parameter  | Type  | Default                |
+|------------|-------|------------------------|
+| `api_key`  | `str` | `None`                 |
+| `base_url` | `str` | `"https://xproof.app"` |
+| `timeout`  | `int` | `30` (seconds)         |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `XProofClient.register(agent_name)` | Register agent, get trial key |
+| `certify(path, author, file_name?, **fourW)` | Certify file (hashes locally) |
+| `certify_hash(file_hash, file_name, author, **fourW)` | Certify by pre-computed hash |
+| `batch_certify(files)` | Batch certify (up to 50) |
+| `verify(proof_id)` | Look up by proof ID |
+| `verify_hash(file_hash)` | Look up by file hash |
+| `get_pricing()` | Get current pricing |
+
+## Links
+
+- [xproof.app](https://xproof.app) — dashboard & docs
+- [npm SDK](https://www.npmjs.com/package/@xproof/xproof) — `npm install @xproof/xproof`
+- [Examples](https://github.com/jasonxkensei/xproof-examples) — LangChain, CrewAI, AutoGen, LlamaIndex
+
+## License
+
+MIT

{xproof-0.2.0 → xproof-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xproof"
-version = "0.2.0"
+version = "0.2.2"
 description = "Python SDK for xProof — blockchain-anchored proof-of-existence for AI agents on MultiversX"
 readme = "README.md"
 license = "MIT"

{xproof-0.2.0 → xproof-0.2.2}/xproof/__init__.py

@@ -21,7 +21,7 @@ from .models import (
 )
 from .utils import hash_bytes, hash_file
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 __all__ = [
     "XProofClient",

{xproof-0.2.0 → xproof-0.2.2}/xproof/client.py

@@ -281,6 +281,103 @@ class XProofClient:
         data = self._request("POST", "/api/proof", json=payload)
         return Certification.from_dict(data)
 
+    VALID_THRESHOLD_STAGES = ("initial", "partial", "pre-commitment", "final")
+
+    def certify_with_confidence(
+        self,
+        file_hash: str,
+        file_name: str,
+        author: str,
+        confidence_level: float,
+        threshold_stage: str,
+        decision_id: str,
+        *,
+        who: Optional[str] = None,
+        what: Optional[str] = None,
+        when: Optional[str] = None,
+        why: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Certification:
+        """Certify a file hash with confidence-level anchoring.
+
+        Creates a forensic trail by anchoring proofs at different confidence
+        thresholds, linked by a shared ``decision_id``. An agent trading at
+        60%, 80%, then final creates an immutable trail that distinguishes
+        real reasoning from post-hoc reconstruction.
+
+        Args:
+            file_hash: 64-character lowercase hex SHA-256 digest.
+            file_name: Original file name.
+            author: Author / owner name.
+            confidence_level: Confidence between 0.0 and 1.0.
+            threshold_stage: One of ``initial``, ``partial``,
+                ``pre-commitment``, ``final``.
+            decision_id: Shared identifier linking all proofs in the
+                same decision chain.
+            who: 4W -- agent identity.
+            what: 4W -- action hash or description.
+            when: 4W -- ISO-8601 timestamp.
+            why: 4W -- instruction or reason.
+            metadata: Extra key-value metadata stored alongside the proof.
+
+        Returns:
+            A :class:`Certification` with the on-chain proof details.
+
+        Raises:
+            ValueError: If confidence_level or threshold_stage is invalid.
+        """
+        if not self.api_key:
+            raise ValueError("api_key is required — call register() or pass an api_key")
+        if not 0.0 <= confidence_level <= 1.0:
+            raise ValueError("confidence_level must be between 0.0 and 1.0")
+        if threshold_stage not in self.VALID_THRESHOLD_STAGES:
+            raise ValueError(
+                f"threshold_stage must be one of: {', '.join(self.VALID_THRESHOLD_STAGES)}"
+            )
+        if not decision_id or not decision_id.strip():
+            raise ValueError("decision_id is required")
+
+        proof_metadata: Dict[str, Any] = dict(metadata) if metadata else {}
+        proof_metadata["confidence_level"] = confidence_level
+        proof_metadata["threshold_stage"] = threshold_stage
+        proof_metadata["decision_id"] = decision_id
+        if who is not None:
+            proof_metadata["who"] = who
+        if what is not None:
+            proof_metadata["what"] = what
+        if when is not None:
+            proof_metadata["when"] = when
+        if why is not None:
+            proof_metadata["why"] = why
+
+        payload: Dict[str, Any] = {
+            "filename": file_name,
+            "file_hash": file_hash,
+            "author_name": author,
+            "metadata": proof_metadata,
+        }
+        data = self._request("POST", "/api/proof", json=payload)
+        return Certification.from_dict(data)
+
+    def get_confidence_trail(self, decision_id: str) -> Dict[str, Any]:
+        """Retrieve the full confidence trail for a decision chain.
+
+        Args:
+            decision_id: The shared identifier linking proofs in the chain.
+
+        Returns:
+            A dictionary with ``decision_id``, ``total_anchors``,
+            ``current_confidence``, ``current_stage``, ``is_finalized``,
+            and ``stages`` (list of anchor details sorted by confidence).
+        """
+        from urllib.parse import quote
+        data = self._request(
+            "GET",
+            f"/api/confidence-trail/{quote(decision_id, safe='')}",
+            auth_required=False,
+        )
+        return data
+
     def batch_certify(
         self,
         files: List[Dict[str, Any]],