ledgix-python 0.1.0__tar.gz

ledgix_python-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Env files
+.env
+.env.local

ledgix_python-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: ledgix-python
+Version: 0.1.0
+Summary: Agent-agnostic compliance shim for SOX 404 policy enforcement via the ALCV Vault
+Project-URL: Homepage, https://github.com/ledgix-dev/python-sdk
+Project-URL: Documentation, https://docs.ledgix.dev
+Project-URL: Repository, https://github.com/ledgix-dev/python-sdk
+Author-email: Ledgix <team@ledgix.dev>
+License: MIT
+Keywords: agents,ai,compliance,security,sox404,vault
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
+Description-Content-Type: text/markdown
+
+# Ledgix ALCV — Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/ledgix-python)](https://pypi.org/project/ledgix-python/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Agent-agnostic compliance shim for SOX 404 policy enforcement. Intercepts AI agent tool calls, validates them against your policies via the ALCV Vault, and ensures only approved actions receive a cryptographically signed A-JWT (Agentic JSON Web Token).
+
+## Quick Start
+
+```bash
+pip install ledgix-python
+```
+
+```python
+from ledgix_python import LedgixClient, vault_enforce
+
+client = LedgixClient()  # Reads LEDGIX_VAULT_URL, LEDGIX_VAULT_API_KEY from env
+
+@vault_enforce(client, tool_name="stripe_refund")
+def process_refund(amount: float, reason: str, **kwargs):
+    token = kwargs["_clearance"].token  # Signed A-JWT
+    return stripe.refund(amount=amount, metadata={"vault_token": token})
+```
+
+**That's it.** Three lines to SOX 404-compliant tool calls.
+
+## Configuration
+
+Set environment variables (prefix: `LEDGIX_`):
+
+| Variable | Default | Description |
+|---|---|---|
+| `LEDGIX_VAULT_URL` | `http://localhost:8000` | Vault server URL |
+| `LEDGIX_VAULT_API_KEY` | `""` | API key for Vault auth |
+| `LEDGIX_VAULT_TIMEOUT` | `30.0` | Request timeout (seconds) |
+| `LEDGIX_VERIFY_JWT` | `true` | Verify A-JWT signatures |
+| `LEDGIX_AGENT_ID` | `default-agent` | Agent identifier |
+
+Or pass a `VaultConfig` directly:
+
+```python
+from ledgix_python import LedgixClient, VaultConfig
+
+config = VaultConfig(vault_url="https://vault.mycompany.com", vault_api_key="sk-...")
+client = LedgixClient(config=config)
+```
+
+## Framework Adapters
+
+### LangChain
+
+```bash
+pip install ledgix-python[langchain]
+```
+
+```python
+from ledgix_python.adapters.langchain import LedgixCallbackHandler, LedgixTool
+
+# Option 1: Callback handler (intercepts ALL tool calls)
+handler = LedgixCallbackHandler(client)
+agent = create_agent(callbacks=[handler])
+
+# Option 2: Wrap individual tools
+guarded_tool = LedgixTool.wrap(client, my_tool, policy_id="refund-policy")
+```
+
+### LlamaIndex
+
+```bash
+pip install ledgix-python[llamaindex]
+```
+
+```python
+from ledgix_python.adapters.llamaindex import wrap_tool
+
+guarded_tool = wrap_tool(client, my_function_tool, policy_id="refund-policy")
+```
+
+### CrewAI
+
+```bash
+pip install ledgix-python[crewai]
+```
+
+```python
+from ledgix_python.adapters.crewai import LedgixCrewAITool
+
+guarded_tool = LedgixCrewAITool.wrap(client, my_tool, policy_id="refund-policy")
+```
+
+## Context Manager
+
+```python
+from ledgix_python import VaultContext
+
+with VaultContext(client, "stripe_refund", {"amount": 45}) as ctx:
+    print(ctx.clearance.token)  # Use the A-JWT
+
+# Async
+async with VaultContext(client, "stripe_refund", {"amount": 45}) as ctx:
+    print(ctx.clearance.token)
+```
+
+## Error Handling
+
+```python
+from ledgix_python import ClearanceDeniedError, VaultConnectionError, TokenVerificationError
+
+try:
+    result = process_refund(amount=5000, reason="...")
+except ClearanceDeniedError as e:
+    print(f"Blocked: {e.reason} (request: {e.request_id})")
+except VaultConnectionError:
+    print("Cannot reach Vault — fail-closed")
+except TokenVerificationError:
+    print("A-JWT signature invalid")
+```
+
+## Development
+
+```bash
+git clone https://github.com/ledgix-dev/python-sdk.git
+cd python-sdk
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest tests/ -v --cov
+```
+
+## Demo
+
+```bash
+python demo.py
+```
+
+## License
+
+MIT

ledgix_python-0.1.0/README.md

@@ -0,0 +1,138 @@
+# Ledgix ALCV — Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/ledgix-python)](https://pypi.org/project/ledgix-python/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Agent-agnostic compliance shim for SOX 404 policy enforcement. Intercepts AI agent tool calls, validates them against your policies via the ALCV Vault, and ensures only approved actions receive a cryptographically signed A-JWT (Agentic JSON Web Token).
+
+## Quick Start
+
+```bash
+pip install ledgix-python
+```
+
+```python
+from ledgix_python import LedgixClient, vault_enforce
+
+client = LedgixClient()  # Reads LEDGIX_VAULT_URL, LEDGIX_VAULT_API_KEY from env
+
+@vault_enforce(client, tool_name="stripe_refund")
+def process_refund(amount: float, reason: str, **kwargs):
+    token = kwargs["_clearance"].token  # Signed A-JWT
+    return stripe.refund(amount=amount, metadata={"vault_token": token})
+```
+
+**That's it.** Three lines to SOX 404-compliant tool calls.
+
+## Configuration
+
+Set environment variables (prefix: `LEDGIX_`):
+
+| Variable | Default | Description |
+|---|---|---|
+| `LEDGIX_VAULT_URL` | `http://localhost:8000` | Vault server URL |
+| `LEDGIX_VAULT_API_KEY` | `""` | API key for Vault auth |
+| `LEDGIX_VAULT_TIMEOUT` | `30.0` | Request timeout (seconds) |
+| `LEDGIX_VERIFY_JWT` | `true` | Verify A-JWT signatures |
+| `LEDGIX_AGENT_ID` | `default-agent` | Agent identifier |
+
+Or pass a `VaultConfig` directly:
+
+```python
+from ledgix_python import LedgixClient, VaultConfig
+
+config = VaultConfig(vault_url="https://vault.mycompany.com", vault_api_key="sk-...")
+client = LedgixClient(config=config)
+```
+
+## Framework Adapters
+
+### LangChain
+
+```bash
+pip install ledgix-python[langchain]
+```
+
+```python
+from ledgix_python.adapters.langchain import LedgixCallbackHandler, LedgixTool
+
+# Option 1: Callback handler (intercepts ALL tool calls)
+handler = LedgixCallbackHandler(client)
+agent = create_agent(callbacks=[handler])
+
+# Option 2: Wrap individual tools
+guarded_tool = LedgixTool.wrap(client, my_tool, policy_id="refund-policy")
+```
+
+### LlamaIndex
+
+```bash
+pip install ledgix-python[llamaindex]
+```
+
+```python
+from ledgix_python.adapters.llamaindex import wrap_tool
+
+guarded_tool = wrap_tool(client, my_function_tool, policy_id="refund-policy")
+```
+
+### CrewAI
+
+```bash
+pip install ledgix-python[crewai]
+```
+
+```python
+from ledgix_python.adapters.crewai import LedgixCrewAITool
+
+guarded_tool = LedgixCrewAITool.wrap(client, my_tool, policy_id="refund-policy")
+```
+
+## Context Manager
+
+```python
+from ledgix_python import VaultContext
+
+with VaultContext(client, "stripe_refund", {"amount": 45}) as ctx:
+    print(ctx.clearance.token)  # Use the A-JWT
+
+# Async
+async with VaultContext(client, "stripe_refund", {"amount": 45}) as ctx:
+    print(ctx.clearance.token)
+```
+
+## Error Handling
+
+```python
+from ledgix_python import ClearanceDeniedError, VaultConnectionError, TokenVerificationError
+
+try:
+    result = process_refund(amount=5000, reason="...")
+except ClearanceDeniedError as e:
+    print(f"Blocked: {e.reason} (request: {e.request_id})")
+except VaultConnectionError:
+    print("Cannot reach Vault — fail-closed")
+except TokenVerificationError:
+    print("A-JWT signature invalid")
+```
+
+## Development
+
+```bash
+git clone https://github.com/ledgix-dev/python-sdk.git
+cd python-sdk
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest tests/ -v --cov
+```
+
+## Demo
+
+```bash
+python demo.py
+```
+
+## License
+
+MIT

ledgix_python-0.1.0/demo.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""Ledgix ALCV SDK — Demo Script
+
+Simulates the "Good Agent" vs "Rogue Agent" scenario from the
+ALCV Vault technical specification.
+
+This demo runs without a real Vault server by using a lightweight
+mock. Set LEDGIX_VAULT_URL to point to a real Vault to test live.
+
+Usage:
+    python demo.py
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from datetime import datetime, timedelta, timezone
+
+import jwt
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from ledgix_python import (
+    ClearanceDeniedError,
+    LedgixClient,
+    VaultConfig,
+    vault_enforce,
+)
+
+# ──────────────────────────────────────────────────────────────────────
+# Mock Vault (only used when no live Vault is configured)
+# ──────────────────────────────────────────────────────────────────────
+
+# Generate a demo Ed25519 key pair for A-JWT signing
+_DEMO_PRIVATE_KEY = Ed25519PrivateKey.generate()
+_DEMO_PUBLIC_KEY = _DEMO_PRIVATE_KEY.public_key()
+
+REFUND_POLICY = {
+    "policy_id": "refund-policy-001",
+    "description": "Customer refund policy for shipping delays",
+    "rules": [
+        "Refunds are allowed up to $100 for shipping delays",
+        "Refund recipient must be the original customer",
+        "Agent must provide a valid order ID",
+    ],
+}
+
+
+def _mock_clearance_decision(tool_name: str, tool_args: dict) -> dict:
+    """Simulates the Vault's policy judge decision."""
+    amount = tool_args.get("amount", 0)
+    recipient = tool_args.get("recipient", "customer")
+
+    approved = amount <= 100 and recipient != "agent_personal_account"
+
+    if approved:
+        # Sign a demo A-JWT
+        payload = {
+            "sub": "clearance",
+            "tool": tool_name,
+            "amount": amount,
+            "iat": datetime.now(timezone.utc),
+            "exp": datetime.now(timezone.utc) + timedelta(minutes=5),
+            "request_id": f"demo-{int(time.time())}",
+        }
+        token = jwt.encode(payload, _DEMO_PRIVATE_KEY, algorithm="EdDSA")
+        return {
+            "approved": True,
+            "token": token,
+            "reason": "Policy check passed — refund within limits",
+            "request_id": payload["request_id"],
+        }
+    else:
+        reason = []
+        if amount > 100:
+            reason.append(f"Amount ${amount} exceeds $100 limit")
+        if recipient == "agent_personal_account":
+            reason.append("Recipient is not the original customer")
+        return {
+            "approved": False,
+            "token": None,
+            "reason": "; ".join(reason),
+            "request_id": f"demo-{int(time.time())}",
+        }
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Simulated Stripe Tool
+# ──────────────────────────────────────────────────────────────────────
+
+
+def stripe_refund(amount: float, reason: str, order_id: str, recipient: str = "customer", **kwargs) -> str:
+    """Simulates a Stripe refund API call."""
+    clearance = kwargs.get("_clearance")
+    token_preview = clearance.token[:40] + "..." if clearance and clearance.token else "N/A"
+    return (
+        f"✅ REFUND PROCESSED\n"
+        f"   Amount:  ${amount:.2f}\n"
+        f"   Reason:  {reason}\n"
+        f"   Order:   {order_id}\n"
+        f"   A-JWT:   {token_preview}"
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Demo Runner
+# ──────────────────────────────────────────────────────────────────────
+
+
+def run_demo():
+    """Run the Good Agent / Rogue Agent demo."""
+
+    print("=" * 64)
+    print("  LEDGIX ALCV — SDK Demo")
+    print("  Policy: \"Refunds ≤ $100 for shipping delays only\"")
+    print("=" * 64)
+
+    # Create a client with JWT verification disabled for demo
+    # (the mock doesn't serve a real JWKS endpoint)
+    config = VaultConfig(
+        vault_url="http://localhost:9999",  # Won't be called in demo mode
+        verify_jwt=False,
+        agent_id="demo-agent",
+    )
+    client = LedgixClient(config=config)
+
+    # ── Scenario A: Good Agent ─────────────────────────────────────
+    print("\n" + "─" * 64)
+    print("  SCENARIO A: Good Agent")
+    print("  Agent requests $45 refund for a late package")
+    print("─" * 64 + "\n")
+
+    tool_args_good = {
+        "amount": 45.00,
+        "reason": "Package arrived 5 days late",
+        "order_id": "ORD-2026-1234",
+        "recipient": "customer",
+    }
+
+    decision = _mock_clearance_decision("stripe_refund", tool_args_good)
+    print(f"  Vault decision: {'✅ APPROVED' if decision['approved'] else '❌ DENIED'}")
+    print(f"  Reason: {decision['reason']}")
+
+    if decision["approved"]:
+        # Simulate what the decorator would do
+        from ledgix_python.models import ClearanceResponse
+
+        clearance = ClearanceResponse(**decision)
+        result = stripe_refund(**tool_args_good, _clearance=clearance)
+        print(f"\n{result}")
+
+    # ── Scenario B: Rogue Agent ────────────────────────────────────
+    print("\n" + "─" * 64)
+    print("  SCENARIO B: Rogue Agent")
+    print("  Agent (prompt-injected) tries $5,000 refund to own account")
+    print("─" * 64 + "\n")
+
+    tool_args_rogue = {
+        "amount": 5000.00,
+        "reason": "Customer requested full refund",
+        "order_id": "ORD-2026-9999",
+        "recipient": "agent_personal_account",
+    }
+
+    decision = _mock_clearance_decision("stripe_refund", tool_args_rogue)
+    print(f"  Vault decision: {'✅ APPROVED' if decision['approved'] else '❌ DENIED'}")
+    print(f"  Reason: {decision['reason']}")
+
+    if not decision["approved"]:
+        print("\n  🛡️  Tool call BLOCKED — no A-JWT issued")
+        print("  The Stripe tool would refuse execution without a valid token.")
+
+    # ── Summary ────────────────────────────────────────────────────
+    print("\n" + "=" * 64)
+    print("  Demo complete!")
+    print("  The ALCV Vault SDK intercepted both tool calls.")
+    print("  • Good agent: Approved and received a signed A-JWT")
+    print("  • Rogue agent: Denied — policy violation detected")
+    print("=" * 64)
+
+
+if __name__ == "__main__":
+    run_demo()

ledgix_python-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ledgix-python"
+version = "0.1.0"
+description = "Agent-agnostic compliance shim for SOX 404 policy enforcement via the ALCV Vault"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Ledgix", email = "team@ledgix.dev" }]
+keywords = ["ai", "agents", "compliance", "sox404", "vault", "security"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "PyJWT[crypto]>=2.8.0",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.1.0"]
+llamaindex = ["llama-index-core>=0.10.0"]
+crewai = ["crewai>=0.1.0"]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.0.0",
+    "respx>=0.21.0",
+    "build>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ledgix-dev/python-sdk"
+Documentation = "https://docs.ledgix.dev"
+Repository = "https://github.com/ledgix-dev/python-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ledgix_python"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["ledgix_python"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 80

ledgix_python-0.1.0/requirements.txt

@@ -0,0 +1,17 @@
+httpx>=0.25.0
+pydantic>=2.0.0
+pydantic-settings>=2.0.0
+PyJWT[crypto]>=2.8.0
+
+# Optional Adapters
+# langchain-core>=0.1.0
+# llama-index-core>=0.10.0
+# crewai>=0.1.0
+
+# Build and Dev Tools
+build>=1.0.0
+twine>=5.0.0
+pytest>=7.0.0
+pytest-asyncio>=0.23.0
+pytest-cov>=4.0.0
+respx>=0.21.0

ledgix_python-0.1.0/src/ledgix_python/__init__.py

@@ -0,0 +1,53 @@
+# Ledgix ALCV — Python SDK
+# Agent-agnostic compliance shim for SOX 404 policy enforcement
+#
+# Usage:
+#   from ledgix_python import LedgixClient, vault_enforce, VaultConfig
+#
+#   client = LedgixClient()
+#
+#   @vault_enforce(client, tool_name="stripe_refund")
+#   def process_refund(amount: float, reason: str, **kwargs):
+#       token = kwargs.get("_clearance").token
+#       ...
+
+"""Ledgix ALCV — agent-agnostic compliance shim for SOX 404 enforcement."""
+
+from .client import LedgixClient
+from .config import VaultConfig
+from .enforce import VaultContext, vault_enforce
+from .exceptions import (
+    ClearanceDeniedError,
+    PolicyRegistrationError,
+    LedgixError,
+    TokenVerificationError,
+    VaultConnectionError,
+)
+from .models import (
+    ClearanceRequest,
+    ClearanceResponse,
+    PolicyRegistration,
+    PolicyRegistrationResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core
+    "LedgixClient",
+    "VaultConfig",
+    # Enforcement
+    "vault_enforce",
+    "VaultContext",
+    # Models
+    "ClearanceRequest",
+    "ClearanceResponse",
+    "PolicyRegistration",
+    "PolicyRegistrationResponse",
+    # Exceptions
+    "LedgixError",
+    "ClearanceDeniedError",
+    "VaultConnectionError",
+    "TokenVerificationError",
+    "PolicyRegistrationError",
+]

ledgix_python-0.1.0/src/ledgix_python/adapters/__init__.py

@@ -0,0 +1 @@
+# Ledgix ALCV — Framework Adapters