bylaw-python 0.4.0__py3-none-any.whl

bylaw_python/config.py

@@ -0,0 +1,95 @@
+# 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."""
+
+    jwt_issuer: str = "alcv-vault"
+    """Expected issuer for Vault A-JWTs."""
+
+    jwt_audience: str = "ledgix-sdk"
+    """Expected audience for Vault A-JWTs."""
+
+    agent_id: str = "default-agent"
+    """Identifier for the agent using this SDK instance."""
+
+    session_id: str = ""
+    """Optional session identifier for grouping related clearance requests."""
+
+    review_poll_interval: float = 2.0
+    """Polling interval in seconds while waiting for manual review."""
+
+    review_timeout: float = 900.0
+    """Maximum wait time in seconds for a pending manual review decision."""
+
+    review_mode: str = "block"
+    """How to handle pending manual reviews. ``"block"`` (default): poll until
+    a decision arrives or timeout expires. ``"detach"``: return a
+    :class:`~bylaw_python.PendingApproval` immediately so the caller can
+    resume later via :meth:`~bylaw_python.PendingApproval.wait_async`."""
+
+    max_retries: int = 3
+    """Number of retry attempts for transient failures (connection errors, 5xx responses)."""
+
+    retry_base_delay: float = 0.5
+    """Base delay in seconds for exponential backoff between retries (full jitter applied)."""
+
+    decision_cache_enabled: bool = False
+    """Enable the in-process decision cache.  Off by default — opt-in for safety.
+    When enabled, approved decisions are memoized; subsequent identical tool
+    calls skip the LLM judge and call /mint-token for a fresh A-JWT instead.
+    """
+
+    decision_cache_ttl_seconds: float = 60.0
+    """TTL (seconds) for cached decision envelopes."""
+
+    decision_cache_max_entries: int = 1000
+    """Maximum number of decision envelopes to keep in memory."""
+
+    principal_id: str | None = None
+    """Advisory OIDC ``sub`` of the human on whose behalf the agent acts.
+    Sent as ``human_principal`` in every clearance request.  Can be overridden
+    per-call via ``on_behalf_of`` argument.  Env: ``LEDGIX_PRINCIPAL_ID``."""
+
+    jwks_ttl_seconds: int = 300
+    """How long (seconds) the cached JWKS is considered fresh before a key-miss
+    triggers a refetch. Default 5 minutes matches the Vault's rotation cadence.
+    Env: ``LEDGIX_JWKS_TTL_SECONDS``."""
+
+    replay_cache_size: int = 10_000
+    """Maximum number of consumed A-JWT jtis held in the in-process replay
+    cache. When the limit is reached the oldest entries are evicted (LRU-TTL).
+    Env: ``LEDGIX_REPLAY_CACHE_SIZE``."""
+
+    max_token_lifetime_seconds: float = 330.0
+    """TTL for entries in the replay cache (seconds). Should be at least
+    ``VAULT_JWT_TTL + 30`` to cover clock skew. Default 330 = 5 min TTL + 30s.
+    Env: ``LEDGIX_MAX_TOKEN_LIFETIME_SECONDS``."""

bylaw_python/counterparty.py

@@ -0,0 +1,145 @@
+# Ledgix ALCV — Client-side counterparty hints
+#
+# Mirrors vault/internal/counterparty: best-effort extraction of the
+# destination provider/URI/account from a tool name + tool_args dict.
+# The Vault re-runs its own extractor chain, so this is a hint to
+# pre-populate the wire fields when the SDK has unambiguous signal.
+#
+# Caller-supplied destination_* always wins on both sides of the wire.
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlparse
+
+
+_PROVIDER_HOST_PREFIXES = ("www.", "api.", "api-")
+
+
+def _provider_from_host(host: str) -> str:
+    """Strip common gateway prefixes so regional subdomains group together.
+    Does not attempt eTLD+1 parsing — provider taxonomy is curated upstream."""
+    host = host.lower().split(":", 1)[0]
+    for prefix in _PROVIDER_HOST_PREFIXES:
+        if host.startswith(prefix):
+            return host[len(prefix):]
+    return host
+
+
+def _string_arg(tool_args: dict[str, Any], key: str) -> str:
+    value = tool_args.get(key)
+    return value if isinstance(value, str) else ""
+
+
+def _stripe(tool_name: str, tool_args: dict[str, Any]) -> dict[str, str] | None:
+    if "stripe" not in tool_name:
+        return None
+    out: dict[str, str] = {
+        "destination_uri": "https://api.stripe.com",
+        "destination_provider": "stripe",
+    }
+    api_key = _string_arg(tool_args, "api_key")
+    if api_key.startswith("sk_") and len(api_key) >= 12:
+        out["destination_account_ref"] = api_key[:12]
+    elif api_key.startswith("sk_"):
+        out["destination_account_ref"] = api_key
+    account = _string_arg(tool_args, "account")
+    if account:
+        out["destination_account_ref"] = account
+    return out
+
+
+def _twilio(tool_name: str, tool_args: dict[str, Any]) -> dict[str, str] | None:
+    if "twilio" not in tool_name:
+        return None
+    out: dict[str, str] = {
+        "destination_uri": "https://api.twilio.com",
+        "destination_provider": "twilio",
+    }
+    sid = _string_arg(tool_args, "account_sid")
+    if sid:
+        out["destination_account_ref"] = sid
+    return out
+
+
+def _slack(tool_name: str, tool_args: dict[str, Any]) -> dict[str, str] | None:
+    if "slack" not in tool_name:
+        return None
+    out: dict[str, str] = {
+        "destination_uri": "https://slack.com/api",
+        "destination_provider": "slack",
+    }
+    team = _string_arg(tool_args, "team_id") or _string_arg(tool_args, "workspace")
+    if team:
+        out["destination_account_ref"] = team
+    return out
+
+
+def _bedrock(tool_name: str, tool_args: dict[str, Any]) -> dict[str, str] | None:
+    if "bedrock" not in tool_name:
+        return None
+    out: dict[str, str] = {
+        "destination_uri": "https://bedrock-runtime.amazonaws.com",
+        "destination_provider": "aws-bedrock",
+    }
+    model_id = _string_arg(tool_args, "model_id") or _string_arg(tool_args, "model")
+    if model_id:
+        out["destination_account_ref"] = model_id
+    return out
+
+
+def _openai(tool_name: str, tool_args: dict[str, Any]) -> dict[str, str] | None:
+    if "openai" not in tool_name and "gpt" not in tool_name:
+        return None
+    out: dict[str, str] = {
+        "destination_uri": "https://api.openai.com",
+        "destination_provider": "openai",
+    }
+    org = _string_arg(tool_args, "organization") or _string_arg(tool_args, "org_id")
+    if org:
+        out["destination_account_ref"] = org
+    return out
+
+
+def _anthropic(tool_name: str, tool_args: dict[str, Any]) -> dict[str, str] | None:
+    if "anthropic" not in tool_name and "claude" not in tool_name:
+        return None
+    out: dict[str, str] = {
+        "destination_uri": "https://api.anthropic.com",
+        "destination_provider": "anthropic",
+    }
+    org = _string_arg(tool_args, "organization")
+    if org:
+        out["destination_account_ref"] = org
+    return out
+
+
+def _generic_http(tool_name: str, tool_args: dict[str, Any]) -> dict[str, str] | None:
+    for key in ("url", "endpoint", "uri", "host"):
+        raw = _string_arg(tool_args, key)
+        if not raw:
+            continue
+        parsed = urlparse(raw)
+        if not parsed.netloc:
+            continue
+        return {
+            "destination_uri": raw,
+            "destination_provider": _provider_from_host(parsed.netloc),
+        }
+    return None
+
+
+_EXTRACTORS = (_stripe, _twilio, _slack, _bedrock, _openai, _anthropic, _generic_http)
+
+
+def extract(tool_name: str, tool_args: dict[str, Any] | None) -> dict[str, str]:
+    """Return any inferred destination_* fields. Empty dict on no match."""
+    if not tool_name:
+        return {}
+    name_lower = tool_name.lower()
+    args = tool_args or {}
+    for ex in _EXTRACTORS:
+        result = ex(name_lower, args)
+        if result:
+            return result
+    return {}