bylaw-python 0.4.0__py3-none-any.whl

bylaw_python/__init__.py

@@ -0,0 +1,114 @@
+# Ledgix ALCV — Python SDK
+# Agent-agnostic compliance shim for SOX 404 policy enforcement
+#
+# Recommended usage:
+#   import bylaw_python as ledgix
+#
+#   ledgix.configure(agent_id="finance-agent")
+#
+#   import tools
+#
+#   ledgix.configure(agent_id="finance-agent")
+#   ledgix.auto_instrument(tools)
+#
+# Explicit API (advanced):
+#   from bylaw_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,
+    auto_instrument,
+    configure,
+    current_clearance,
+    current_token,
+    enforce,
+    tool,
+    vault_enforce,
+)
+from .manifest import Manifest, ManifestRule, load_manifest
+from .exceptions import (
+    ClearanceDeniedError,
+    ManualReviewTimeoutError,
+    PolicyRegistrationError,
+    LedgixError,
+    QueueSaturatedError,
+    ReplayDetectedError,
+    ReviewPendingError,
+    TokenVerificationError,
+    VaultConnectionError,
+)
+from .pending import PendingApproval
+from .webhook import verify_webhook
+from .models import (
+    ClearanceRequest,
+    ClearanceResponse,
+    ConsistencyProof,
+    InclusionProof,
+    LedgerCheckpoint,
+    LedgerEntry,
+    LedgerKeyVersion,
+    LedgerManifest,
+    LedgerProofBundle,
+    LedgerVerificationResult,
+    PolicyRegistration,
+    PolicyRegistrationResponse,
+)
+
+__version__ = "0.4.0"
+
+__all__ = [
+    # Core
+    "LedgixClient",
+    "VaultConfig",
+    # Low-code API
+    "configure",
+    "enforce",
+    "current_clearance",
+    "current_token",
+    # Manifest / auto-instrumentation
+    "auto_instrument",
+    "tool",
+    "load_manifest",
+    "Manifest",
+    "ManifestRule",
+    # Explicit API
+    "vault_enforce",
+    "VaultContext",
+    # Detach-mode / async approvals
+    "PendingApproval",
+    # Webhook verification
+    "verify_webhook",
+    # Models
+    "ClearanceRequest",
+    "ClearanceResponse",
+    "ConsistencyProof",
+    "InclusionProof",
+    "LedgerCheckpoint",
+    "LedgerEntry",
+    "LedgerKeyVersion",
+    "LedgerManifest",
+    "LedgerProofBundle",
+    "LedgerVerificationResult",
+    "PolicyRegistration",
+    "PolicyRegistrationResponse",
+    # Exceptions
+    "LedgixError",
+    "ClearanceDeniedError",
+    "ManualReviewTimeoutError",
+    "QueueSaturatedError",
+    "ReviewPendingError",
+    "VaultConnectionError",
+    "TokenVerificationError",
+    "ReplayDetectedError",
+    "PolicyRegistrationError",
+]

bylaw_python/adapters/__init__.py

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

bylaw_python/adapters/_core.py

@@ -0,0 +1,58 @@
+# Ledgix ALCV — Adapter Core Helpers
+# Shared scaffolding used by the LangChain, LlamaIndex, and CrewAI adapters.
+# Framework-specific glue (callback handlers, sync vs async, error-translation
+# policy) stays per-adapter — only the genuinely identical pieces live here.
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..client import LedgixClient
+from ..enforce import _get_default_client
+from ..models import ClearanceRequest
+
+
+def resolve_client(client: LedgixClient | None) -> LedgixClient:
+    """Return the explicit client or fall back to the module-level default
+    configured via :func:`bylaw_python.configure`.
+    """
+    if client is not None:
+        return client
+    return _get_default_client()
+
+
+def build_clearance_request(
+    *,
+    tool_name: str,
+    tool_args: dict[str, Any],
+    client: LedgixClient,
+    policy_id: str | None = None,
+    extra_context: dict[str, Any] | None = None,
+    data_categories: list[str] | None = None,
+    purpose: str | None = None,
+    processing_register_ref: str | None = None,
+    dataset_ref: str | None = None,
+) -> ClearanceRequest:
+    """Build a ClearanceRequest with adapter-agnostic defaults pulled from
+    ``client.config``. ``policy_id``, when set, is merged into ``context``
+    after ``extra_context`` so it always wins for that key.
+
+    Phase 2/6 fields (``data_categories``, ``purpose``,
+    ``processing_register_ref``, ``dataset_ref``) are forwarded as top-level
+    fields so the Vault's processing-register / dataset-lineage validators
+    can match them.
+    """
+    ctx: dict[str, Any] = dict(extra_context or {})
+    if policy_id:
+        ctx["policy_id"] = policy_id
+    return ClearanceRequest(
+        tool_name=tool_name,
+        tool_args=tool_args,
+        agent_id=client.config.agent_id,
+        session_id=client.config.session_id,
+        context=ctx,
+        data_categories=data_categories,
+        purpose=purpose,
+        processing_register_ref=processing_register_ref,
+        dataset_ref=dataset_ref,
+    )

bylaw_python/adapters/crewai.py

@@ -0,0 +1,99 @@
+# 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 ._core import build_clearance_request, resolve_client
+
+try:
+    from crewai.tools import BaseTool as CrewAIBaseTool
+except ImportError as exc:
+    raise ImportError(
+        "CrewAI adapter requires crewai. "
+        "Install with: pip install bylaw-python[crewai]"
+    ) from exc
+
+
+class LedgixCrewAITool(CrewAIBaseTool):
+    """Wraps a CrewAI tool with Vault clearance enforcement.
+
+    Usage with explicit client::
+
+        from crewai.tools import BaseTool
+        from bylaw_python.adapters.crewai import LedgixCrewAITool
+
+        guarded = LedgixCrewAITool.wrap(client, MyTool())
+
+    Usage after :func:`bylaw_python.configure`::
+
+        guarded = LedgixCrewAITool.wrap(MyTool())
+    """
+
+    name: str = ""
+    description: str = ""
+    _inner_tool: CrewAIBaseTool
+    _client: LedgixClient | None
+    _policy_id: str | None
+
+    class Config:
+        arbitrary_types_allowed = True
+        underscore_attrs_are_private = True
+
+    def __init__(
+        self,
+        inner_tool: CrewAIBaseTool,
+        client: LedgixClient | None = None,
+        *,
+        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
+
+    def _resolve_client(self) -> LedgixClient:
+        return resolve_client(self._client)
+
+    @classmethod
+    def wrap(
+        cls,
+        client_or_tool: LedgixClient | CrewAIBaseTool,
+        tool: CrewAIBaseTool | None = None,
+        *,
+        policy_id: str | None = None,
+    ) -> LedgixCrewAITool:
+        """Convenience factory to wrap a CrewAI tool.
+
+        Supports two call signatures:
+
+        - ``LedgixCrewAITool.wrap(client, tool, policy_id=...)`` — explicit client
+        - ``LedgixCrewAITool.wrap(tool, policy_id=...)`` — uses global client from :func:`bylaw_python.configure`
+        """
+        if isinstance(client_or_tool, LedgixClient):
+            return cls(inner_tool=tool, client=client_or_tool, policy_id=policy_id)  # type: ignore[arg-type]
+        return cls(inner_tool=client_or_tool, client=None, policy_id=policy_id)
+
+    def _run(self, **kwargs: Any) -> Any:
+        client = self._resolve_client()
+        request = build_clearance_request(
+            tool_name=self._inner_tool.name,
+            tool_args=kwargs,
+            client=client,
+            policy_id=self._policy_id,
+        )
+
+        try:
+            client.request_clearance(request)
+        except ClearanceDeniedError as exc:
+            return f"BLOCKED: Vault denied this action — {exc.reason}"
+
+        return self._inner_tool._run(**kwargs)

bylaw_python/adapters/langchain.py

@@ -0,0 +1,167 @@
+# 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 ._core import build_clearance_request, resolve_client
+
+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 bylaw-python[langchain]"
+    ) from exc
+
+
+class LedgixCallbackHandler(BaseCallbackHandler):
+    """LangChain callback handler that intercepts tool calls for Vault clearance.
+
+    Usage::
+
+        from bylaw_python.adapters.langchain import LedgixCallbackHandler
+
+        handler = LedgixCallbackHandler(client)
+        agent = create_agent(callbacks=[handler])
+
+    If :func:`bylaw_python.configure` has been called, *client* may be omitted::
+
+        handler = LedgixCallbackHandler()
+    """
+
+    def __init__(self, client: LedgixClient | None = None, *, policy_id: str | None = None) -> None:
+        self._client = client
+        self.policy_id = policy_id
+
+    @property
+    def client(self) -> LedgixClient:
+        return resolve_client(self._client)
+
+    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}
+
+        extra_context = {"langchain_metadata": metadata} if metadata else None
+        request = build_clearance_request(
+            tool_name=tool_name,
+            tool_args=tool_args,
+            client=self.client,
+            policy_id=self.policy_id,
+            extra_context=extra_context,
+        )
+
+        # This will raise ClearanceDeniedError if denied
+        self.client.request_clearance(request)
+
+
+class LedgixTool(BaseTool):
+    """Wraps an existing LangChain tool with Vault clearance enforcement.
+
+    Usage with explicit client::
+
+        from langchain_community.tools import SomeTool
+        from bylaw_python.adapters.langchain import LedgixTool
+
+        guarded_tool = LedgixTool.wrap(client, SomeTool(), policy_id="refund-policy")
+
+    Usage after :func:`bylaw_python.configure`::
+
+        guarded_tool = LedgixTool.wrap(SomeTool(), policy_id="refund-policy")
+    """
+
+    name: str = ""
+    description: str = ""
+    _inner_tool: BaseTool
+    _client: LedgixClient | None
+    _policy_id: str | None
+
+    class Config:
+        arbitrary_types_allowed = True
+        underscore_attrs_are_private = True
+
+    def __init__(
+        self,
+        inner_tool: BaseTool,
+        client: LedgixClient | None = None,
+        *,
+        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
+
+    def _resolve_client(self) -> LedgixClient:
+        return resolve_client(self._client)
+
+    @classmethod
+    def wrap(
+        cls,
+        client_or_tool: LedgixClient | BaseTool,
+        tool: BaseTool | None = None,
+        *,
+        policy_id: str | None = None,
+    ) -> LedgixTool:
+        """Convenience factory to wrap a tool.
+
+        Supports two call signatures:
+
+        - ``LedgixTool.wrap(client, tool, policy_id=...)`` — explicit client
+        - ``LedgixTool.wrap(tool, policy_id=...)`` — uses global client from :func:`bylaw_python.configure`
+        """
+        if isinstance(client_or_tool, LedgixClient):
+            return cls(inner_tool=tool, client=client_or_tool, policy_id=policy_id)  # type: ignore[arg-type]
+        # client_or_tool is actually the tool; no explicit client
+        return cls(inner_tool=client_or_tool, client=None, policy_id=policy_id)
+
+    def _run(self, *args: Any, **kwargs: Any) -> Any:
+        client = self._resolve_client()
+        request = build_clearance_request(
+            tool_name=self._inner_tool.name,
+            tool_args=kwargs or ({"input": args[0]} if args else {}),
+            client=client,
+            policy_id=self._policy_id,
+        )
+
+        try:
+            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:
+        client = self._resolve_client()
+        request = build_clearance_request(
+            tool_name=self._inner_tool.name,
+            tool_args=kwargs or ({"input": args[0]} if args else {}),
+            client=client,
+            policy_id=self._policy_id,
+        )
+
+        try:
+            await 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)

bylaw_python/adapters/llamaindex.py

@@ -0,0 +1,90 @@
+# Ledgix ALCV — LlamaIndex Adapter
+# Wraps LlamaIndex tools with Vault clearance enforcement
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..client import LedgixClient
+from ._core import build_clearance_request, resolve_client
+
+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 bylaw-python[llamaindex]"
+    ) from exc
+
+
+class LedgixToolWrapper:
+    """Wraps a LlamaIndex tool with Vault clearance enforcement.
+
+    Usage with explicit client::
+
+        from llama_index.core.tools import FunctionTool
+        from bylaw_python.adapters.llamaindex import LedgixToolWrapper
+
+        tool = FunctionTool.from_defaults(fn=my_tool, name="search")
+        guarded = LedgixToolWrapper(client, tool)
+
+    Usage after :func:`bylaw_python.configure`::
+
+        guarded = LedgixToolWrapper(tool=tool)
+    """
+
+    def __init__(
+        self,
+        client: LedgixClient | None = None,
+        tool: FunctionTool | None = None,
+        *,
+        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}",  # type: ignore[union-attr]
+            description=tool.metadata.description or "",  # type: ignore[union-attr]
+        )
+
+    def _resolve_client(self) -> LedgixClient:
+        return resolve_client(self._client)
+
+    def _guarded_call(self, **kwargs: Any) -> Any:
+        """Wrapper that requests clearance before calling the inner tool."""
+        client = self._resolve_client()
+        request = build_clearance_request(
+            tool_name=self._inner_tool.metadata.name,  # type: ignore[union-attr]
+            tool_args=kwargs,
+            client=client,
+            policy_id=self._policy_id,
+        )
+
+        client.request_clearance(request)
+        return self._inner_tool.call(**kwargs)  # type: ignore[union-attr]
+
+
+def wrap_tool(
+    client_or_tool: LedgixClient | FunctionTool,
+    tool: FunctionTool | None = None,
+    *,
+    policy_id: str | None = None,
+) -> FunctionTool:
+    """Wrap a LlamaIndex tool with Vault clearance enforcement.
+
+    Returns the guarded FunctionTool ready for use in an agent.
+
+    Supports two call signatures:
+
+    - ``wrap_tool(client, tool, policy_id=...)`` — explicit client
+    - ``wrap_tool(tool, policy_id=...)`` — uses global client from :func:`bylaw_python.configure`
+    """
+    if isinstance(client_or_tool, LedgixClient):
+        wrapper = LedgixToolWrapper(client_or_tool, tool, policy_id=policy_id)
+    else:
+        wrapper = LedgixToolWrapper(None, client_or_tool, policy_id=policy_id)
+    return wrapper.tool