bylaw-python 0.4.0__tar.gz

bylaw_python-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+      - run: pip install -r requirements.txt && pip install -e ".[yaml]"
+      - run: pytest

bylaw_python-0.4.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

bylaw_python-0.4.0/.shipsafeignore

@@ -0,0 +1,45 @@
+# Ship Safe ignore rules for python-sdk
+# Published as ledgix-python on PyPI. Agent-agnostic SDK shim.
+
+# --- Test fixtures ---
+
+# Test files use dummy API key loaded from env var with test fallback.
+Generic API Key Assignment
+
+# Test assertions use == for values, not secrets.
+TIMING_ATTACK_COMPARISON
+
+# --- CLI (ledgix init / status / teardown) ---
+
+# CLI commands invoke docker-compose and subprocess.run for local dev
+# orchestration. These are user-invoked commands, not LLM-driven actions.
+AGENT_OUTPUT_TO_ACTION
+
+# Recursive invocation flag is a Pydantic data field, not agent behavior.
+AGENT_RECURSIVE_INVOCATION
+
+# --- Docker-compose defaults ---
+
+# cli.py embeds docker-compose templates with localhost Postgres URLs
+# and dev-only default passwords for local development.
+Database URL with Credentials
+SSRF_INTERNAL_IP
+Password Assignment
+
+# --- Dependencies ---
+
+# httpx>=0.25.0 is a standard PyPI version specifier, not a git/URL dep.
+GIT_PYTHON_DEP
+
+# --- JWT ---
+
+# jwt.decode with a key argument verifies the signature. The scanner
+# flags the call as "verification disabled" but it is not.
+JWT_VERIFY_DISABLED
+
+# --- Git history ---
+# No real secrets were ever committed; placeholder values only.
+GIT_HISTORY_SECRET
+
+# --- General ---
+MCP_SHADOW_CONFIG

bylaw_python-0.4.0/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to `bylaw-python` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0]
+
+### Breaking changes — categorical confidence buckets
+
+This release replaces the legacy decimal `confidence: float` field with five
+categorical buckets (`extra_high | high | medium | low | none`), and splits
+the overloaded `approved=True + confidence=0.00` "needs human review"
+sentinel into an explicit `decision_status` field
+(`approved | denied | approved_pending_review`). See
+[`docs/MIGRATION_0.4.md`](docs/MIGRATION_0.4.md) for the migration guide.
+
+> Note: the wire format change is breaking, but the SemVer bump is 0.3.1 →
+> 0.4.0 (still in 0.x.0). The 0.x line is pre-1.0 and minor bumps are
+> allowed to carry breaking changes per SemVer §4. Customers pinning
+> `^0.3` will NOT auto-upgrade; they must explicitly bump to `^0.4`
+> after reading the migration guide.
+
+#### `ClearanceResponse` — fields removed
+- `approved: bool`
+- `confidence: float`
+- `minimum_confidence_score: float`
+
+#### `ClearanceResponse` — fields added
+- `decision_status: Literal["approved", "denied", "approved_pending_review"]`
+- `confidence_bucket: Literal["extra_high", "high", "medium", "low", "none"]`
+- `minimum_confidence_bucket: Literal[...]` (same five values)
+- `is_approved` property — convenience boolean for the common
+  "may the agent proceed?" check, returns `True` for both `approved` and
+  `approved_pending_review`.
+
+#### `LedgerEntry`
+- `confidence_bucket` and `decision_status` added (populated for
+  canonical_version=2 events).
+- Legacy `confidence: float` and `approved: bool` retained on the model so
+  canonical_version=1 hash verification of historical rows still works.
+
+#### Why this changed
+The previous design overloaded `confidence=0.00` to mean both "extreme low
+confidence" (deny path) and "needs human review" (gated approval). Customer
+code doing `if response.confidence < threshold: reject` would accidentally
+reject the very review-pending decisions the platform was trying to surface.
+The bucket migration retires the cents-level decimal precision the model
+couldn't reliably produce and gives review-pending its own dedicated state.
+
+#### Migration in one line
+- Old: `if response.approved and response.confidence >= 0.8: ...`
+- New: `if response.decision_status == "approved": ...`
+  (or `if response.is_approved: ...` if you also want to treat
+  `approved_pending_review` as "may proceed eventually").
+
+## [0.3.1]
+
+### Added
+- `ClearanceRequest.data_categories`, `purpose`, and
+  `processing_register_ref` — Phase 2 GDPR Article 30 processing-register
+  matching. When set, the Vault's pre-LLM validator chain checks for an
+  active register that covers the (data_categories ⊇ requested,
+  purpose ∈ register.purposes, recipient ∈ register.recipients) tuple.
+  Unmatched requests deny with `reason_code='processing_no_register_match'`.
+- `ClearanceRequest.dataset_ref` — Phase 6 dataset lineage. Logical
+  reference (filename, S3 path, table name, etc.) for the production
+  data this action reads/writes. Auto-derived dataset sheets group on
+  this field for row counts, schema fingerprints, and consent-basis
+  breakdowns.
+- All four fields are also surfaced as kwargs on `enforce()`, `tool()`,
+  `vault_enforce()`, and `VaultContext` so the high-level decorator API
+  can populate them without dropping to `LedgixClient.request_clearance`.
+- `/mint-token` cache-replay forwards the new fields alongside the 0.3.0
+  destination set.
+
+### Compatibility
+- Backwards-compatible. All four fields are optional. Vault ignores
+  unknown wire fields prior to the matching schema migration; older SDKs
+  continue to work against the new Vault.
+
+## [0.3.0]
+
+### Added
+- `ClearanceRequest.destination_uri`, `destination_provider`, and
+  `destination_account_ref` — typed counterparty attribution that replaces
+  per-tool guessing in downstream policy checks. All three fields are
+  optional; existing callers are unaffected.
+- `bylaw_python.counterparty.extract()` — best-effort SDK-side hint that
+  fills the new fields when the caller doesn't supply them. Recognizes
+  Stripe (`api_key` prefix → 12-char account ref), Twilio (`account_sid`),
+  Slack (`team_id` / `workspace`), AWS Bedrock (`model_id`), OpenAI
+  (`organization`), Anthropic (`organization`), and a generic URL-host
+  fallback. The Vault re-runs its own extractor chain server-side, so
+  this is a hint — caller-supplied values always win.
+- `/mint-token` cache-replay path forwards the destination fields so
+  re-minted A-JWTs share attribution with the original decision.
+
+### Compatibility
+- Backwards-compatible against Vault 0.x (Vault ignores unknown wire
+  fields prior to the matching schema migration). Older SDKs continue
+  to work against the new Vault — destination columns are simply NULL
+  on those rows.
+
+## [0.2.1]
+- Honor `Retry-After` on 429 from Vault backpressure.
+
+## [0.2.0]
+- Idempotency-Key on POSTs, JWKS async lock, adapter dedup.
+- Security: JWKS kid matching, jti replay detection.
+- HITL: `PendingApproval`, `review_mode="detach"`, `verify_webhook`.

bylaw_python-0.4.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: bylaw-python
+Version: 0.4.0
+Summary: Agent-agnostic compliance shim for SOX 404 policy enforcement via the ALCV Vault
+Project-URL: Homepage, https://github.com/bylaw-dev/python-sdk
+Project-URL: Documentation, https://docs.bylaw.dev
+Project-URL: Repository, https://github.com/bylaw-dev/python-sdk
+Author-email: Bylaw <team@bylaw.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: cachetools>=5.3.0
+Requires-Dist: click>=8.1.0
+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'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# Ledgix ALCV — Python SDK
+
+[![PyPI](https://img.shields.io/badge/pypi-v0.1.13-blue)](https://pypi.org/project/bylaw-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 bylaw-python
+```
+
+```python
+# ledgix.yaml
+# enforce:
+#   - tool: "stripe_*"
+#     policy_id: "financial-high-risk"
+#   - tool: "*"
+#     policy_id: "default"
+
+import tools
+import bylaw_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:
+
+```python
+from bylaw_python import LedgixClient, VaultConfig
+
+config = VaultConfig(vault_url="https://vault.mycompany.com", vault_api_key="sk-...")
+client = LedgixClient(config=config)
+```
+
+## Manifest-driven auto-instrumentation
+
+```python
+import tools
+import bylaw_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`:
+
+```bash
+pip install bylaw-python[yaml]
+```
+
+### Escape hatch
+
+```python
+@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
+
+```bash
+pip install bylaw-python[langchain]
+```
+
+```python
+from bylaw_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 bylaw-python[llamaindex]
+```
+
+```python
+from bylaw_python.adapters.llamaindex import wrap_tool
+
+guarded_tool = wrap_tool(client, my_function_tool, policy_id="refund-policy")
+```
+
+### CrewAI
+
+```bash
+pip install bylaw-python[crewai]
+```
+
+```python
+from bylaw_python.adapters.crewai import LedgixCrewAITool
+
+guarded_tool = LedgixCrewAITool.wrap(client, my_tool, policy_id="refund-policy")
+```
+
+## Context Manager
+
+```python
+from bylaw_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 bylaw_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

bylaw_python-0.4.0/README.md

@@ -0,0 +1,183 @@
+# Ledgix ALCV — Python SDK
+
+[![PyPI](https://img.shields.io/badge/pypi-v0.1.13-blue)](https://pypi.org/project/bylaw-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 bylaw-python
+```
+
+```python
+# ledgix.yaml
+# enforce:
+#   - tool: "stripe_*"
+#     policy_id: "financial-high-risk"
+#   - tool: "*"
+#     policy_id: "default"
+
+import tools
+import bylaw_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:
+
+```python
+from bylaw_python import LedgixClient, VaultConfig
+
+config = VaultConfig(vault_url="https://vault.mycompany.com", vault_api_key="sk-...")
+client = LedgixClient(config=config)
+```
+
+## Manifest-driven auto-instrumentation
+
+```python
+import tools
+import bylaw_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`:
+
+```bash
+pip install bylaw-python[yaml]
+```
+
+### Escape hatch
+
+```python
+@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
+
+```bash
+pip install bylaw-python[langchain]
+```
+
+```python
+from bylaw_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 bylaw-python[llamaindex]
+```
+
+```python
+from bylaw_python.adapters.llamaindex import wrap_tool
+
+guarded_tool = wrap_tool(client, my_function_tool, policy_id="refund-policy")
+```
+
+### CrewAI
+
+```bash
+pip install bylaw-python[crewai]
+```
+
+```python
+from bylaw_python.adapters.crewai import LedgixCrewAITool
+
+guarded_tool = LedgixCrewAITool.wrap(client, my_tool, policy_id="refund-policy")
+```
+
+## Context Manager
+
+```python
+from bylaw_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 bylaw_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