Skip to content

README.md

Latest commit

 

History

History
183 lines (131 loc) · 4.36 KB

README.md

File metadata and controls

183 lines (131 loc) · 4.36 KB

Ledgix ALCV — Python SDK

PyPI Python 3.10+ License: MIT

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

pip install ledgix-python
# ledgix.yaml
# enforce:
#   - tool: "stripe_*"
#     policy_id: "financial-high-risk"
#   - tool: "*"
#     policy_id: "default"

import tools
import ledgix_python as ledgix

ledgix.configure(agent_id="payments-agent")
ledgix.auto_instrument(tools)

result = tools.stripe_refund(45, "Late package")
print(result)

auto_instrument() reads ledgix.yaml, ledgix.yml, or ledgix.json from the current working directory by default, wraps matching functions in place, and leaves unmatched functions alone.

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_JWT_ISSUER alcv-vault Expected A-JWT issuer
LEDGIX_JWT_AUDIENCE ledgix-sdk Expected A-JWT audience
LEDGIX_AGENT_ID default-agent Agent identifier

Or pass a VaultConfig directly:

from ledgix_python import LedgixClient, VaultConfig

config = VaultConfig(vault_url="https://vault.mycompany.com", vault_api_key="sk-...")
client = LedgixClient(config=config)

Manifest-driven auto-instrumentation

import tools
import ledgix_python as ledgix

ledgix.configure(agent_id="payments-agent")

# Auto-discover ledgix.yaml / ledgix.yml / ledgix.json from the CWD
wrapped = ledgix.auto_instrument(tools)

# Or pass an inline manifest
ledgix.auto_instrument(
    tools,
    manifest={"enforce": [{"tool": "stripe_*", "policy_id": "financial-high-risk"}]},
)

YAML manifests require pyyaml:

pip install ledgix-python[yaml]

Escape hatch

@ledgix.tool
def special_refund(amount: float):
    return ledgix.current_token()

@ledgix.tool(policy_id="override-policy")
def stripe_charge(amount: float):
    return ledgix.current_token()

Framework Adapters

LangChain

pip install ledgix-python[langchain]
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

pip install ledgix-python[llamaindex]
from ledgix_python.adapters.llamaindex import wrap_tool

guarded_tool = wrap_tool(client, my_function_tool, policy_id="refund-policy")

CrewAI

pip install ledgix-python[crewai]
from ledgix_python.adapters.crewai import LedgixCrewAITool

guarded_tool = LedgixCrewAITool.wrap(client, my_tool, policy_id="refund-policy")

Context Manager

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

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

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

python demo.py

License

MIT