ledgix-python 0.1.0__py3-none-any.whl

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/adapters/__init__.py

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

ledgix_python/adapters/crewai.py

@@ -0,0 +1,95 @@
+# Ledgix ALCV — CrewAI Adapter
+# Wraps CrewAI tools with Vault clearance enforcement
+
+from __future__ import annotations
+
+from typing import Any, Type
+
+from pydantic import BaseModel
+
+from ..client import LedgixClient
+from ..exceptions import ClearanceDeniedError
+from ..models import ClearanceRequest
+
+try:
+    from crewai.tools import BaseTool as CrewAIBaseTool
+except ImportError as exc:
+    raise ImportError(
+        "CrewAI adapter requires crewai. "
+        "Install with: pip install ledgix-python[crewai]"
+    ) from exc
+
+
+class LedgixCrewAITool(CrewAIBaseTool):
+    """Wraps a CrewAI tool with Vault clearance enforcement.
+
+    Usage::
+
+        from crewai.tools import BaseTool
+        from ledgix_python.adapters.crewai import LedgixCrewAITool
+
+        class MyTool(BaseTool):
+            name = "search"
+            description = "Search the web"
+
+            def _run(self, query: str) -> str:
+                return f"Results for {query}"
+
+        guarded = LedgixCrewAITool.wrap(client, MyTool())
+    """
+
+    name: str = ""
+    description: str = ""
+    _inner_tool: CrewAIBaseTool
+    _client: LedgixClient
+    _policy_id: str | None
+
+    class Config:
+        arbitrary_types_allowed = True
+        underscore_attrs_are_private = True
+
+    def __init__(
+        self,
+        inner_tool: CrewAIBaseTool,
+        client: LedgixClient,
+        *,
+        policy_id: str | None = None,
+    ) -> None:
+        super().__init__(
+            name=f"ledgix_{inner_tool.name}",
+            description=inner_tool.description,
+        )
+        self._inner_tool = inner_tool
+        self._client = client
+        self._policy_id = policy_id
+
+    @classmethod
+    def wrap(
+        cls,
+        client: LedgixClient,
+        tool: CrewAIBaseTool,
+        *,
+        policy_id: str | None = None,
+    ) -> LedgixCrewAITool:
+        """Convenience factory to wrap a CrewAI tool."""
+        return cls(inner_tool=tool, client=client, policy_id=policy_id)
+
+    def _run(self, **kwargs: Any) -> Any:
+        ctx: dict[str, Any] = {}
+        if self._policy_id:
+            ctx["policy_id"] = self._policy_id
+
+        request = ClearanceRequest(
+            tool_name=self._inner_tool.name,
+            tool_args=kwargs,
+            agent_id=self._client.config.agent_id,
+            session_id=self._client.config.session_id,
+            context=ctx,
+        )
+
+        try:
+            self._client.request_clearance(request)
+        except ClearanceDeniedError as exc:
+            return f"BLOCKED: Vault denied this action — {exc.reason}"
+
+        return self._inner_tool._run(**kwargs)

ledgix_python/adapters/langchain.py

@@ -0,0 +1,156 @@
+# Ledgix ALCV — LangChain Adapter
+# Provides a callback handler and tool wrapper for LangChain integration
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..client import LedgixClient
+from ..exceptions import ClearanceDeniedError
+from ..models import ClearanceRequest
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+    from langchain_core.tools import BaseTool, ToolException
+except ImportError as exc:
+    raise ImportError(
+        "LangChain adapter requires langchain-core. "
+        "Install with: pip install ledgix-python[langchain]"
+    ) from exc
+
+
+class LedgixCallbackHandler(BaseCallbackHandler):
+    """LangChain callback handler that intercepts tool calls for Vault clearance.
+
+    Usage::
+
+        from ledgix_python.adapters.langchain import LedgixCallbackHandler
+
+        handler = LedgixCallbackHandler(client)
+        agent = create_agent(callbacks=[handler])
+    """
+
+    def __init__(self, client: LedgixClient, *, policy_id: str | None = None) -> None:
+        self.client = client
+        self.policy_id = policy_id
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any],
+        input_str: str,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        inputs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Intercept tool start and request Vault clearance."""
+        tool_name = serialized.get("name", "unknown_tool")
+        tool_args = inputs or {"input": input_str}
+
+        ctx: dict[str, Any] = {}
+        if self.policy_id:
+            ctx["policy_id"] = self.policy_id
+        if metadata:
+            ctx["langchain_metadata"] = metadata
+
+        request = ClearanceRequest(
+            tool_name=tool_name,
+            tool_args=tool_args,
+            agent_id=self.client.config.agent_id,
+            session_id=self.client.config.session_id,
+            context=ctx,
+        )
+
+        # This will raise ClearanceDeniedError if denied
+        self.client.request_clearance(request)
+
+
+class LedgixTool(BaseTool):
+    """Wraps an existing LangChain tool with Vault clearance enforcement.
+
+    Usage::
+
+        from langchain_community.tools import SomeTool
+        from ledgix_python.adapters.langchain import LedgixTool
+
+        guarded_tool = LedgixTool.wrap(client, SomeTool(), policy_id="refund-policy")
+    """
+
+    name: str = ""
+    description: str = ""
+    _inner_tool: BaseTool
+    _client: LedgixClient
+    _policy_id: str | None
+
+    class Config:
+        arbitrary_types_allowed = True
+        underscore_attrs_are_private = True
+
+    def __init__(
+        self,
+        inner_tool: BaseTool,
+        client: LedgixClient,
+        *,
+        policy_id: str | None = None,
+    ) -> None:
+        super().__init__(
+            name=f"ledgix_{inner_tool.name}",
+            description=inner_tool.description,
+        )
+        self._inner_tool = inner_tool
+        self._client = client
+        self._policy_id = policy_id
+
+    @classmethod
+    def wrap(
+        cls,
+        client: LedgixClient,
+        tool: BaseTool,
+        *,
+        policy_id: str | None = None,
+    ) -> LedgixTool:
+        """Convenience factory to wrap a tool."""
+        return cls(inner_tool=tool, client=client, policy_id=policy_id)
+
+    def _run(self, *args: Any, **kwargs: Any) -> Any:
+        ctx: dict[str, Any] = {}
+        if self._policy_id:
+            ctx["policy_id"] = self._policy_id
+
+        request = ClearanceRequest(
+            tool_name=self._inner_tool.name,
+            tool_args=kwargs or ({"input": args[0]} if args else {}),
+            agent_id=self._client.config.agent_id,
+            session_id=self._client.config.session_id,
+            context=ctx,
+        )
+
+        try:
+            self._client.request_clearance(request)
+        except ClearanceDeniedError as exc:
+            raise ToolException(f"Vault denied: {exc.reason}") from exc
+
+        return self._inner_tool._run(*args, **kwargs)
+
+    async def _arun(self, *args: Any, **kwargs: Any) -> Any:
+        ctx: dict[str, Any] = {}
+        if self._policy_id:
+            ctx["policy_id"] = self._policy_id
+
+        request = ClearanceRequest(
+            tool_name=self._inner_tool.name,
+            tool_args=kwargs or ({"input": args[0]} if args else {}),
+            agent_id=self._client.config.agent_id,
+            session_id=self._client.config.session_id,
+            context=ctx,
+        )
+
+        try:
+            await self._client.arequest_clearance(request)
+        except ClearanceDeniedError as exc:
+            raise ToolException(f"Vault denied: {exc.reason}") from exc
+
+        return await self._inner_tool._arun(*args, **kwargs)

ledgix_python/adapters/llamaindex.py

@@ -0,0 +1,85 @@
+# Ledgix ALCV — LlamaIndex Adapter
+# Wraps LlamaIndex tools with Vault clearance enforcement
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..client import LedgixClient
+from ..exceptions import ClearanceDeniedError
+from ..models import ClearanceRequest
+
+try:
+    from llama_index.core.tools import FunctionTool, ToolMetadata, ToolOutput
+except ImportError as exc:
+    raise ImportError(
+        "LlamaIndex adapter requires llama-index-core. "
+        "Install with: pip install ledgix-python[llamaindex]"
+    ) from exc
+
+
+class LedgixToolWrapper:
+    """Wraps a LlamaIndex tool with Vault clearance enforcement.
+
+    Usage::
+
+        from llama_index.core.tools import FunctionTool
+        from ledgix_python.adapters.llamaindex import LedgixToolWrapper
+
+        def my_tool(query: str) -> str:
+            return f"Result for {query}"
+
+        tool = FunctionTool.from_defaults(fn=my_tool, name="search")
+        guarded = LedgixToolWrapper(client, tool)
+
+        # Use guarded.tool in your LlamaIndex agent
+    """
+
+    def __init__(
+        self,
+        client: LedgixClient,
+        tool: FunctionTool,
+        *,
+        policy_id: str | None = None,
+    ) -> None:
+        self._client = client
+        self._inner_tool = tool
+        self._policy_id = policy_id
+
+        # Create the wrapped tool
+        self.tool = FunctionTool.from_defaults(
+            fn=self._guarded_call,
+            name=f"ledgix_{tool.metadata.name}",
+            description=tool.metadata.description or "",
+        )
+
+    def _guarded_call(self, **kwargs: Any) -> Any:
+        """Wrapper that requests clearance before calling the inner tool."""
+        ctx: dict[str, Any] = {}
+        if self._policy_id:
+            ctx["policy_id"] = self._policy_id
+
+        request = ClearanceRequest(
+            tool_name=self._inner_tool.metadata.name,
+            tool_args=kwargs,
+            agent_id=self._client.config.agent_id,
+            session_id=self._client.config.session_id,
+            context=ctx,
+        )
+
+        self._client.request_clearance(request)
+        return self._inner_tool.call(**kwargs)
+
+
+def wrap_tool(
+    client: LedgixClient,
+    tool: FunctionTool,
+    *,
+    policy_id: str | None = None,
+) -> FunctionTool:
+    """Convenience function to wrap a LlamaIndex tool.
+
+    Returns the guarded FunctionTool ready for use in an agent.
+    """
+    wrapper = LedgixToolWrapper(client, tool, policy_id=policy_id)
+    return wrapper.tool

ledgix_python/client.py

@@ -0,0 +1,314 @@
+# Ledgix ALCV — Client
+# Sync + async HTTP client for Vault communication and A-JWT verification
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import jwt
+
+from .config import VaultConfig
+from .exceptions import (
+    ClearanceDeniedError,
+    PolicyRegistrationError,
+    TokenVerificationError,
+    VaultConnectionError,
+)
+from .models import (
+    ClearanceRequest,
+    ClearanceResponse,
+    PolicyRegistration,
+    PolicyRegistrationResponse,
+)
+
+
+class LedgixClient:
+    """Sync + async client for the ALCV Vault.
+
+    Usage (sync)::
+
+        client = LedgixClient()
+        resp = client.request_clearance(ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45}))
+
+    Usage (async)::
+
+        client = LedgixClient()
+        resp = await client.arequest_clearance(ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45}))
+    """
+
+    def __init__(self, config: VaultConfig | None = None) -> None:
+        self.config = config or VaultConfig()
+        self._sync_client: httpx.Client | None = None
+        self._async_client: httpx.AsyncClient | None = None
+        self._jwks_cache: dict[str, Any] | None = None
+
+    # ------------------------------------------------------------------
+    # Internal HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if self.config.vault_api_key:
+            headers["X-Vault-API-Key"] = self.config.vault_api_key
+        return headers
+
+    def _get_sync_client(self) -> httpx.Client:
+        if self._sync_client is None or self._sync_client.is_closed:
+            self._sync_client = httpx.Client(
+                base_url=self.config.vault_url,
+                headers=self._headers(),
+                timeout=self.config.vault_timeout,
+            )
+        return self._sync_client
+
+    def _get_async_client(self) -> httpx.AsyncClient:
+        if self._async_client is None or self._async_client.is_closed:
+            self._async_client = httpx.AsyncClient(
+                base_url=self.config.vault_url,
+                headers=self._headers(),
+                timeout=self.config.vault_timeout,
+            )
+        return self._async_client
+
+    # ------------------------------------------------------------------
+    # Clearance — sync
+    # ------------------------------------------------------------------
+
+    def request_clearance(self, request: ClearanceRequest) -> ClearanceResponse:
+        """Send a clearance request to the Vault (sync).
+
+        Raises:
+            ClearanceDeniedError: If the Vault denies the request.
+            VaultConnectionError: If the Vault is unreachable.
+        """
+        try:
+            response = self._get_sync_client().post(
+                "/request-clearance",
+                content=request.model_dump_json(),
+            )
+            response.raise_for_status()
+        except httpx.ConnectError as exc:
+            raise VaultConnectionError(str(exc)) from exc
+        except httpx.HTTPStatusError as exc:
+            raise VaultConnectionError(
+                f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
+            ) from exc
+
+        clearance = ClearanceResponse.model_validate(response.json())
+
+        if not clearance.approved:
+            raise ClearanceDeniedError(
+                reason=clearance.reason,
+                request_id=clearance.request_id,
+            )
+
+        if self.config.verify_jwt and clearance.token:
+            self.verify_token(clearance.token)
+
+        return clearance
+
+    # ------------------------------------------------------------------
+    # Clearance — async
+    # ------------------------------------------------------------------
+
+    async def arequest_clearance(self, request: ClearanceRequest) -> ClearanceResponse:
+        """Send a clearance request to the Vault (async).
+
+        Raises:
+            ClearanceDeniedError: If the Vault denies the request.
+            VaultConnectionError: If the Vault is unreachable.
+        """
+        try:
+            response = await self._get_async_client().post(
+                "/request-clearance",
+                content=request.model_dump_json(),
+            )
+            response.raise_for_status()
+        except httpx.ConnectError as exc:
+            raise VaultConnectionError(str(exc)) from exc
+        except httpx.HTTPStatusError as exc:
+            raise VaultConnectionError(
+                f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
+            ) from exc
+
+        clearance = ClearanceResponse.model_validate(response.json())
+
+        if not clearance.approved:
+            raise ClearanceDeniedError(
+                reason=clearance.reason,
+                request_id=clearance.request_id,
+            )
+
+        if self.config.verify_jwt and clearance.token:
+            await self.averify_token(clearance.token)
+
+        return clearance
+
+    # ------------------------------------------------------------------
+    # Policy registration
+    # ------------------------------------------------------------------
+
+    def register_policy(self, policy: PolicyRegistration) -> PolicyRegistrationResponse:
+        """Register a policy with the Vault (sync)."""
+        try:
+            response = self._get_sync_client().post(
+                "/register-policy",
+                content=policy.model_dump_json(),
+            )
+            response.raise_for_status()
+        except httpx.ConnectError as exc:
+            raise VaultConnectionError(str(exc)) from exc
+        except httpx.HTTPStatusError as exc:
+            raise PolicyRegistrationError(
+                f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
+            ) from exc
+
+        return PolicyRegistrationResponse.model_validate(response.json())
+
+    async def aregister_policy(self, policy: PolicyRegistration) -> PolicyRegistrationResponse:
+        """Register a policy with the Vault (async)."""
+        try:
+            response = await self._get_async_client().post(
+                "/register-policy",
+                content=policy.model_dump_json(),
+            )
+            response.raise_for_status()
+        except httpx.ConnectError as exc:
+            raise VaultConnectionError(str(exc)) from exc
+        except httpx.HTTPStatusError as exc:
+            raise PolicyRegistrationError(
+                f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
+            ) from exc
+
+        return PolicyRegistrationResponse.model_validate(response.json())
+
+    # ------------------------------------------------------------------
+    # JWKS + A-JWT verification
+    # ------------------------------------------------------------------
+
+    def fetch_jwks(self) -> dict[str, Any]:
+        """Fetch the Vault's JWKS (JSON Web Key Set) for token verification (sync)."""
+        try:
+            response = self._get_sync_client().get("/.well-known/jwks.json")
+            response.raise_for_status()
+        except httpx.ConnectError as exc:
+            raise VaultConnectionError(str(exc)) from exc
+        except httpx.HTTPStatusError as exc:
+            raise VaultConnectionError(
+                f"Failed to fetch JWKS: HTTP {exc.response.status_code}"
+            ) from exc
+
+        self._jwks_cache = response.json()
+        return self._jwks_cache
+
+    async def afetch_jwks(self) -> dict[str, Any]:
+        """Fetch the Vault's JWKS for token verification (async)."""
+        try:
+            response = await self._get_async_client().get("/.well-known/jwks.json")
+            response.raise_for_status()
+        except httpx.ConnectError as exc:
+            raise VaultConnectionError(str(exc)) from exc
+        except httpx.HTTPStatusError as exc:
+            raise VaultConnectionError(
+                f"Failed to fetch JWKS: HTTP {exc.response.status_code}"
+            ) from exc
+
+        self._jwks_cache = response.json()
+        return self._jwks_cache
+
+    def verify_token(self, token: str) -> dict[str, Any]:
+        """Verify an A-JWT using the Vault's public key (sync).
+
+        Returns the decoded token payload on success.
+
+        Raises:
+            TokenVerificationError: If the token is invalid, expired, or
+                the JWKS cannot be fetched.
+        """
+        return self._verify_token_internal(token, sync=True)
+
+    async def averify_token(self, token: str) -> dict[str, Any]:
+        """Verify an A-JWT using the Vault's public key (async)."""
+        return self._verify_token_internal(token, sync=False)
+
+    def _verify_token_internal(self, token: str, sync: bool = True) -> dict[str, Any]:
+        """Shared verification logic.
+
+        Note: For async callers this is still synchronous internally
+        because PyJWT is sync. The async variant pre-fetches JWKS
+        asynchronously before calling this.
+        """
+        if self._jwks_cache is None:
+            if sync:
+                self.fetch_jwks()
+            else:
+                # In async context, caller must have pre-fetched JWKS.
+                # Fall back to sync fetch if cache is empty.
+                self.fetch_jwks()
+
+        if not self._jwks_cache:
+            raise TokenVerificationError("No JWKS available from Vault")
+
+        try:
+            # Extract the first key from the JWKS
+            jwks = self._jwks_cache
+            if "keys" not in jwks or not jwks["keys"]:
+                raise TokenVerificationError("JWKS contains no keys")
+
+            # Build a PyJWT key from the JWK
+            key_data = jwks["keys"][0]
+            public_key = jwt.algorithms.OKPAlgorithm.from_jwk(json.dumps(key_data))
+
+            decoded = jwt.decode(
+                token,
+                public_key,
+                algorithms=["EdDSA"],
+                options={"verify_exp": True},
+            )
+            return decoded
+
+        except jwt.ExpiredSignatureError as exc:
+            raise TokenVerificationError("A-JWT has expired") from exc
+        except jwt.InvalidTokenError as exc:
+            raise TokenVerificationError(f"Invalid A-JWT: {exc}") from exc
+        except Exception as exc:
+            raise TokenVerificationError(f"Token verification failed: {exc}") from exc
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying HTTP clients."""
+        if self._sync_client and not self._sync_client.is_closed:
+            self._sync_client.close()
+        if self._async_client and not self._async_client.is_closed:
+            # Can't await in sync context; schedule close if event loop exists
+            import asyncio
+
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(self._async_client.aclose())
+            except RuntimeError:
+                pass  # No running loop; client will be GC'd
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP clients (async)."""
+        if self._sync_client and not self._sync_client.is_closed:
+            self._sync_client.close()
+        if self._async_client and not self._async_client.is_closed:
+            await self._async_client.aclose()
+
+    def __enter__(self) -> LedgixClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    async def __aenter__(self) -> LedgixClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()

ledgix_python/config.py

@@ -0,0 +1,39 @@
+# Ledgix ALCV — Configuration
+# Environment-driven configuration via pydantic-settings
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class VaultConfig(BaseSettings):
+    """Configuration for connecting to the ALCV Vault.
+
+    Values are loaded from environment variables prefixed with ``LEDGIX_``,
+    e.g. ``LEDGIX_VAULT_URL``, or can be passed directly to the constructor.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="LEDGIX_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    vault_url: str = "http://localhost:8000"
+    """Base URL of the ALCV Vault server."""
+
+    vault_api_key: str = ""
+    """API key sent as ``X-Vault-API-Key`` header for Shim→Vault auth."""
+
+    vault_timeout: float = 30.0
+    """HTTP request timeout in seconds."""
+
+    verify_jwt: bool = True
+    """Whether to verify A-JWTs returned by the Vault using its JWKS endpoint."""
+
+    agent_id: str = "default-agent"
+    """Identifier for the agent using this SDK instance."""
+
+    session_id: str = ""
+    """Optional session identifier for grouping related clearance requests."""

ledgix_python/enforce.py

@@ -0,0 +1,164 @@
+# Ledgix ALCV — Enforcement Layer
+# Decorator and context manager for intercepting tool calls
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+from typing import Any, Callable, TypeVar
+
+from .client import LedgixClient
+from .exceptions import ClearanceDeniedError
+from .models import ClearanceRequest, ClearanceResponse
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class VaultContext:
+    """Context manager that requests clearance before executing a block.
+
+    Sync usage::
+
+        with VaultContext(client, "stripe_refund", {"amount": 45}) as ctx:
+            # ctx.clearance contains the ClearanceResponse
+            execute_refund(ctx.clearance.token)
+
+    Async usage::
+
+        async with VaultContext(client, "stripe_refund", {"amount": 45}) as ctx:
+            execute_refund(ctx.clearance.token)
+    """
+
+    def __init__(
+        self,
+        client: LedgixClient,
+        tool_name: str,
+        tool_args: dict[str, Any] | None = None,
+        *,
+        context: dict[str, Any] | None = None,
+        policy_id: str | None = None,
+    ) -> None:
+        self.client = client
+        self.tool_name = tool_name
+        self.tool_args = tool_args or {}
+        self.context = context or {}
+        self.policy_id = policy_id
+        self.clearance: ClearanceResponse | None = None
+
+    def _build_request(self) -> ClearanceRequest:
+        ctx = {**self.context}
+        if self.policy_id:
+            ctx["policy_id"] = self.policy_id
+        return ClearanceRequest(
+            tool_name=self.tool_name,
+            tool_args=self.tool_args,
+            agent_id=self.client.config.agent_id,
+            session_id=self.client.config.session_id,
+            context=ctx,
+        )
+
+    # Sync context manager
+    def __enter__(self) -> VaultContext:
+        request = self._build_request()
+        self.clearance = self.client.request_clearance(request)
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        pass
+
+    # Async context manager
+    async def __aenter__(self) -> VaultContext:
+        request = self._build_request()
+        self.clearance = await self.client.arequest_clearance(request)
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        pass
+
+
+def vault_enforce(
+    client: LedgixClient,
+    *,
+    tool_name: str | None = None,
+    policy_id: str | None = None,
+    context: dict[str, Any] | None = None,
+) -> Callable[[F], F]:
+    """Decorator that enforces Vault clearance before a function executes.
+
+    Works with both sync and async functions automatically.
+
+    Usage::
+
+        @vault_enforce(client, tool_name="stripe_refund")
+        def process_refund(amount: float, reason: str):
+            # This only runs if the Vault approves
+            stripe.refund(amount=amount, reason=reason)
+
+        @vault_enforce(client, tool_name="stripe_refund")
+        async def async_process_refund(amount: float, reason: str):
+            await stripe.refund(amount=amount, reason=reason)
+
+    The decorated function receives an injected ``_clearance`` keyword
+    argument containing the ``ClearanceResponse`` (with the A-JWT token).
+    """
+
+    def decorator(func: F) -> F:
+        resolved_name = tool_name or func.__name__
+
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                request = ClearanceRequest(
+                    tool_name=resolved_name,
+                    tool_args=_extract_tool_args(func, args, kwargs),
+                    agent_id=client.config.agent_id,
+                    session_id=client.config.session_id,
+                    context={**(context or {}), **({"policy_id": policy_id} if policy_id else {})},
+                )
+                clearance = await client.arequest_clearance(request)
+                kwargs["_clearance"] = clearance
+                return await func(*args, **kwargs)
+
+            return async_wrapper  # type: ignore[return-value]
+
+        else:
+
+            @functools.wraps(func)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                request = ClearanceRequest(
+                    tool_name=resolved_name,
+                    tool_args=_extract_tool_args(func, args, kwargs),
+                    agent_id=client.config.agent_id,
+                    session_id=client.config.session_id,
+                    context={**(context or {}), **({"policy_id": policy_id} if policy_id else {})},
+                )
+                clearance = client.request_clearance(request)
+                kwargs["_clearance"] = clearance
+                return func(*args, **kwargs)
+
+            return sync_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def _extract_tool_args(
+    func: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> dict[str, Any]:
+    """Best-effort extraction of function arguments as a dict for the clearance request."""
+    try:
+        sig = inspect.signature(func)
+        bound = sig.bind_partial(*args, **kwargs)
+        bound.apply_defaults()
+        # Filter out internal kwargs
+        return {
+            k: v
+            for k, v in bound.arguments.items()
+            if not k.startswith("_") and k != "self"
+        }
+    except Exception:
+        # Fallback: just return kwargs
+        return {k: v for k, v in kwargs.items() if not k.startswith("_")}

ledgix_python/exceptions.py

@@ -0,0 +1,44 @@
+# Ledgix ALCV — Exceptions
+# All custom exceptions for the SDK
+
+from __future__ import annotations
+
+
+class LedgixError(Exception):
+    """Base exception for all Ledgix SDK errors."""
+    pass
+
+
+class ClearanceDeniedError(LedgixError):
+    """Raised when the Vault denies a tool-call clearance request.
+
+    Attributes:
+        reason: Human-readable denial reason from the Vault.
+        request_id: The Vault's unique ID for this clearance request.
+    """
+
+    def __init__(self, reason: str, request_id: str | None = None) -> None:
+        self.reason = reason
+        self.request_id = request_id
+        super().__init__(f"Clearance denied: {reason}")
+
+
+class VaultConnectionError(LedgixError):
+    """Raised when the SDK cannot reach the Vault server."""
+
+    def __init__(self, message: str = "Unable to connect to the Vault server") -> None:
+        super().__init__(message)
+
+
+class TokenVerificationError(LedgixError):
+    """Raised when A-JWT verification fails (bad signature, expired, etc.)."""
+
+    def __init__(self, message: str = "Token verification failed") -> None:
+        super().__init__(message)
+
+
+class PolicyRegistrationError(LedgixError):
+    """Raised when a policy registration request fails."""
+
+    def __init__(self, message: str = "Policy registration failed") -> None:
+        super().__init__(message)

ledgix_python/models.py

@@ -0,0 +1,56 @@
+# Ledgix ALCV — Data Models
+# Pydantic models for Vault API request/response payloads
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ClearanceRequest(BaseModel):
+    """Payload sent to the Vault's ``/request-clearance`` endpoint."""
+
+    tool_name: str = Field(..., description="Name of the tool the agent wants to invoke")
+    tool_args: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arguments the agent will pass to the tool",
+    )
+    agent_id: str = Field(default="default-agent", description="Identifier for the calling agent")
+    session_id: str = Field(default="", description="Session grouping identifier")
+    context: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional context for the Vault's policy judge (e.g. conversation history)",
+    )
+
+
+class ClearanceResponse(BaseModel):
+    """Response from the Vault's ``/request-clearance`` endpoint."""
+
+    approved: bool = Field(..., description="Whether the tool call was approved")
+    token: str | None = Field(default=None, description="Signed A-JWT if approved, None if denied")
+    reason: str = Field(default="", description="Human-readable explanation of the decision")
+    request_id: str = Field(default="", description="Vault-assigned unique ID for this request")
+
+
+class PolicyRegistration(BaseModel):
+    """Payload for registering a policy with the Vault."""
+
+    policy_id: str = Field(..., description="Unique identifier for the policy")
+    description: str = Field(default="", description="Human-readable description of the policy")
+    rules: list[str] = Field(
+        default_factory=list,
+        description="List of plain-English rules (e.g. 'Refunds must not exceed $100')",
+    )
+    tools: list[str] = Field(
+        default_factory=list,
+        description="Tool names this policy applies to (empty = all tools)",
+    )
+
+
+class PolicyRegistrationResponse(BaseModel):
+    """Response from the Vault's ``/register-policy`` endpoint."""
+
+    policy_id: str = Field(..., description="Confirmed policy ID")
+    status: str = Field(default="registered", description="Registration status")
+    message: str = Field(default="", description="Additional information")

ledgix_python-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+ledgix_python/__init__.py,sha256=ljYh7w1vbtixarFcR7gThL4Zxi48nzytEKq_v87WtQU,1277
+ledgix_python/client.py,sha256=P4NJc7cTBmgf-r863uxA-OJcKFhcOnuvtzL1UjwF79k,11682
+ledgix_python/config.py,sha256=RrAJ9ilbDio_jLp4EsbBUFOvEFSx9k302wqA1hO39Fk,1186
+ledgix_python/enforce.py,sha256=PaYE9WkgujU02NWAcoK6HnH7mf-2Gy3chezgZoMlbrw,5434
+ledgix_python/exceptions.py,sha256=dhE-qyBctTpyY6omi82UMeLss-iIlrlHaM5qBzFrsv0,1338
+ledgix_python/models.py,sha256=0SSQX2mNx2GF0SVwkVUgFdIRHjSaaDb2-tdCQ2nr2gM,2273
+ledgix_python/adapters/__init__.py,sha256=qI-boxRb6Qgy7SkC3cTt1rXEH7geZzzV7ynNje-W6iQ,37
+ledgix_python/adapters/crewai.py,sha256=9kgxq_38RM6JWI540e7_MaZtpO8o-zdwT9Xkijq-KJw,2598
+ledgix_python/adapters/langchain.py,sha256=Wqb8kkgIwjHmxvsD79FTo9riYs8bGwV5wN9MoMDEkHk,4767
+ledgix_python/adapters/llamaindex.py,sha256=ffJ8Y8ge_x4BjD8ezm7ZEnJDpcbiVIx11InhCiJadSY,2467
+ledgix_python-0.1.0.dist-info/METADATA,sha256=s8sjMsBtzLd7bQ4l6hHoj-g1MdIA-azBvR2Mum0Io-k,5202
+ledgix_python-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ledgix_python-0.1.0.dist-info/RECORD,,

ledgix_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any