faramesh-sdk 0.3.0__tar.gz

faramesh_sdk-0.3.0/LICENSE

@@ -0,0 +1,84 @@
+Elastic License 2.0
+
+Copyright (c) 2024 Faramesh Contributors
+
+This Elastic License 2.0 (the "License") sets forth the terms on which the
+software identified above ("Software") may be used. Any use of the Software
+other than as expressly set forth herein is prohibited.
+
+1. Grant of Rights
+
+   Subject to the terms of this License, you are granted a non-exclusive,
+   non-transferable, non-sublicensable, limited license to use, copy,
+   distribute, make available, and prepare derivative works of the Software,
+   in each case solely for your internal business purposes or for the purpose
+   of developing, testing, or running your applications and services.
+
+2. Restrictions
+
+   You may not:
+
+   (a) provide the Software to third parties as a managed, hosted, or
+       network-accessible service where the primary value of the service is
+       the Software itself;
+
+   (b) sell, offer for sale, or otherwise make the Software available as a
+       product or service that competes with the Software or any substantially
+       similar product or service offered by the licensor; or
+
+   (c) remove, obscure, or alter any copyright, trademark, or other
+       proprietary notices contained in the Software.
+
+3. Compliance with Laws
+
+   You must comply with all applicable laws and regulations, including export
+   control laws and regulations of the United States and other relevant
+   jurisdictions, in your use of the Software.
+
+4. No Trademark License
+
+   This License does not grant you any right in or to any trademarks, service
+   marks, or trade names of the licensor or its affiliates.
+
+5. Disclaimer of Warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, WHETHER
+   EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, INCLUDING WITHOUT LIMITATION ANY
+   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
+   NON-INFRINGEMENT. THE ENTIRE RISK ARISING OUT OF THE USE OR PERFORMANCE OF
+   THE SOFTWARE REMAINS WITH YOU.
+
+6. Limitation of Liability
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL THE
+   LICENSOR OR ITS AFFILIATES BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS OR
+   REVENUE, ARISING OUT OF OR IN CONNECTION WITH THIS LICENSE OR THE USE OR
+   INABILITY TO USE THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+   DAMAGES.
+
+7. Termination
+
+   This License is effective until terminated. Your rights under this License
+   will terminate automatically without notice if you fail to comply with any
+   term(s) of this License. Upon termination, you must cease all use of the
+   Software and destroy all copies in your possession or control.
+
+8. Third-Party Components
+
+   The Software may include or be distributed with third-party software
+   components that are separately licensed. Your use of such components is
+   subject to the terms and conditions of the applicable third-party licenses.
+
+9. Governing Law
+
+   This License shall be governed by and construed in accordance with the
+   laws of the State of California, without regard to its conflict of laws
+   principles.
+
+10. Entire Agreement
+
+   This License constitutes the entire agreement between you and the licensor
+   with respect to the Software and supersedes all prior or contemporaneous
+   understandings regarding such subject matter.
+

faramesh_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: faramesh-sdk
+Version: 0.3.0
+Summary: Faramesh Python SDK - Production-ready client for the Faramesh Execution Governor API
+Author: Faramesh Contributors
+License: Elastic License 2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Dynamic: license-file
+
+# Faramesh Python SDK
+
+Production-ready Python client for the Faramesh Execution Governor API.
+
+## Installation
+
+```bash
+pip install faramesh-sdk
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/faramesh/faramesh-python-sdk.git
+cd faramesh-python-sdk
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from faramesh import configure, submit_action, approve_action
+
+# Configure SDK (optional - defaults to http://127.0.0.1:8000)
+configure(
+    base_url="http://localhost:8000",
+    token="your-token",  # Optional, can also use FARAMESH_TOKEN env var
+)
+
+# Submit an action
+action = submit_action(
+    agent_id="my-agent",
+    tool="http",
+    operation="get",
+    params={"url": "https://example.com"}
+)
+
+print(f"Action {action.id} status: {action.status}")
+
+# If action requires approval
+if action.status == "pending_approval":
+    approved = approve_action(
+        action.id,
+        action.approval_token,
+        reason="Looks safe"
+    )
+    print(f"Action approved: {approved.status}")
+```
+
+## Features
+
+- **Simple API**: Easy-to-use functions for all API operations
+- **Batch Operations**: Submit multiple actions at once
+- **Submit and Wait**: Automatically wait for action completion
+- **Policy Building**: Build policies in Python code
+- **Deterministic Hashing**: Client-side request_hash computation
+- **Gate Endpoint**: Pre-check decisions without creating actions
+- **Replay Helpers**: Verify decision determinism
+- **Error Handling**: Typed exceptions for all error cases
+
+## Gate Endpoint & Deterministic Hashing
+
+The SDK provides helpers for deterministic decision verification:
+
+### Compute Request Hash Locally
+
+```python
+from faramesh import compute_request_hash
+
+payload = {
+    "agent_id": "my-agent",
+    "tool": "http",
+    "operation": "get",
+    "params": {"url": "https://example.com"},
+    "context": {}
+}
+
+# Compute hash locally (matches server's request_hash)
+hash_value = compute_request_hash(payload)
+print(f"Request hash: {hash_value}")
+```
+
+### Gate Decide (Decision Only)
+
+```python
+from faramesh import gate_decide
+
+# Get decision without creating an action
+decision = gate_decide(
+    agent_id="my-agent",
+    tool="http",
+    operation="get",
+    params={"url": "https://example.com"}
+)
+
+if decision.outcome == "EXECUTE":
+    print("Action would be allowed")
+elif decision.outcome == "HALT":
+    print(f"Action would be denied: {decision.reason_code}")
+else:  # ABSTAIN
+    print("Action requires approval")
+```
+
+### Execute If Allowed (Gated Execution)
+
+```python
+from faramesh import execute_if_allowed
+
+def my_executor(tool, operation, params, context):
+    # Your actual execution logic
+    return {"status": "done"}
+
+result = execute_if_allowed(
+    agent_id="my-agent",
+    tool="http",
+    operation="get",
+    params={"url": "https://example.com"},
+    executor=my_executor
+)
+
+if result["executed"]:
+    print("Action executed:", result["execution_result"])
+else:
+    print("Action blocked:", result["reason_code"])
+```
+
+### Replay Decision
+
+```python
+from faramesh import replay_decision
+
+# Verify decision is deterministic
+result = replay_decision(action_id="abc123")
+
+if result.success:
+    print("Decision replay passed!")
+else:
+    print("Mismatches:", result.mismatches)
+```
+
+## Documentation
+
+Full documentation is available at: https://github.com/faramesh/faramesh-docs
+
+See `docs/SDK-Python.md` for detailed API reference.
+
+## Repository
+
+**Source**: https://github.com/faramesh/faramesh-python-sdk
+
+## License
+
+Elastic License 2.0

faramesh_sdk-0.3.0/README.md

@@ -0,0 +1,153 @@
+# Faramesh Python SDK
+
+Production-ready Python client for the Faramesh Execution Governor API.
+
+## Installation
+
+```bash
+pip install faramesh-sdk
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/faramesh/faramesh-python-sdk.git
+cd faramesh-python-sdk
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from faramesh import configure, submit_action, approve_action
+
+# Configure SDK (optional - defaults to http://127.0.0.1:8000)
+configure(
+    base_url="http://localhost:8000",
+    token="your-token",  # Optional, can also use FARAMESH_TOKEN env var
+)
+
+# Submit an action
+action = submit_action(
+    agent_id="my-agent",
+    tool="http",
+    operation="get",
+    params={"url": "https://example.com"}
+)
+
+print(f"Action {action.id} status: {action.status}")
+
+# If action requires approval
+if action.status == "pending_approval":
+    approved = approve_action(
+        action.id,
+        action.approval_token,
+        reason="Looks safe"
+    )
+    print(f"Action approved: {approved.status}")
+```
+
+## Features
+
+- **Simple API**: Easy-to-use functions for all API operations
+- **Batch Operations**: Submit multiple actions at once
+- **Submit and Wait**: Automatically wait for action completion
+- **Policy Building**: Build policies in Python code
+- **Deterministic Hashing**: Client-side request_hash computation
+- **Gate Endpoint**: Pre-check decisions without creating actions
+- **Replay Helpers**: Verify decision determinism
+- **Error Handling**: Typed exceptions for all error cases
+
+## Gate Endpoint & Deterministic Hashing
+
+The SDK provides helpers for deterministic decision verification:
+
+### Compute Request Hash Locally
+
+```python
+from faramesh import compute_request_hash
+
+payload = {
+    "agent_id": "my-agent",
+    "tool": "http",
+    "operation": "get",
+    "params": {"url": "https://example.com"},
+    "context": {}
+}
+
+# Compute hash locally (matches server's request_hash)
+hash_value = compute_request_hash(payload)
+print(f"Request hash: {hash_value}")
+```
+
+### Gate Decide (Decision Only)
+
+```python
+from faramesh import gate_decide
+
+# Get decision without creating an action
+decision = gate_decide(
+    agent_id="my-agent",
+    tool="http",
+    operation="get",
+    params={"url": "https://example.com"}
+)
+
+if decision.outcome == "EXECUTE":
+    print("Action would be allowed")
+elif decision.outcome == "HALT":
+    print(f"Action would be denied: {decision.reason_code}")
+else:  # ABSTAIN
+    print("Action requires approval")
+```
+
+### Execute If Allowed (Gated Execution)
+
+```python
+from faramesh import execute_if_allowed
+
+def my_executor(tool, operation, params, context):
+    # Your actual execution logic
+    return {"status": "done"}
+
+result = execute_if_allowed(
+    agent_id="my-agent",
+    tool="http",
+    operation="get",
+    params={"url": "https://example.com"},
+    executor=my_executor
+)
+
+if result["executed"]:
+    print("Action executed:", result["execution_result"])
+else:
+    print("Action blocked:", result["reason_code"])
+```
+
+### Replay Decision
+
+```python
+from faramesh import replay_decision
+
+# Verify decision is deterministic
+result = replay_decision(action_id="abc123")
+
+if result.success:
+    print("Decision replay passed!")
+else:
+    print("Mismatches:", result.mismatches)
+```
+
+## Documentation
+
+Full documentation is available at: https://github.com/faramesh/faramesh-docs
+
+See `docs/SDK-Python.md` for detailed API reference.
+
+## Repository
+
+**Source**: https://github.com/faramesh/faramesh-python-sdk
+
+## License
+
+Elastic License 2.0

faramesh_sdk-0.3.0/faramesh/__init__.py

@@ -0,0 +1,178 @@
+"""Faramesh Python SDK - Production-ready client for the Faramesh Execution Governor API.
+
+Quick Start:
+    >>> from faramesh import configure, submit_action, approve_action
+    >>> configure(base_url="http://localhost:8000", token="dev-token")
+    >>> action = submit_action("my-agent", "http", "get", {"url": "https://example.com"})
+    >>> print(f"Action {action['id']} status: {action['status']}")
+"""
+
+from .client import (
+    # Configuration
+    configure,
+    ClientConfig,
+    
+    # Core functions
+    submit_action,
+    submit_actions,
+    submit_actions_bulk,
+    submit_and_wait,
+    block_until_approved,
+    get_action,
+    list_actions,
+    approve_action,
+    deny_action,
+    start_action,
+    replay_action,
+    wait_for_completion,
+    apply,
+    tail_events,
+    stream_events,
+    
+    # Convenience aliases
+    allow,
+    deny,
+    
+    # Exceptions
+    FarameshError,
+    FarameshAuthError,
+    FarameshNotFoundError,
+    FarameshPolicyError,
+    FarameshTimeoutError,
+    FarameshConnectionError,
+    FarameshValidationError,
+    FarameshServerError,
+    FarameshBatchError,
+    FarameshDeniedError,
+    
+    # Legacy class-based API (for backward compatibility)
+    ExecutionGovernorClient,
+    GovernorConfig,
+    GovernorError,
+    GovernorTimeoutError,
+    GovernorAuthError,
+    GovernorConnectionError,
+)
+
+# Import new modules
+from .governed_tool import governed_tool
+from .snapshot import ActionSnapshotStore, get_default_store
+from .policy_helpers import validate_policy_file, test_policy_against_action
+
+# Import canonicalization helpers
+from .canonicalization import (
+    canonicalize,
+    canonicalize_action_payload,
+    compute_request_hash,
+    compute_hash,
+    CanonicalizeError,
+)
+
+# Import gate helpers
+from .gate import (
+    gate_decide,
+    gate_decide_dict,
+    replay_decision,
+    verify_request_hash,
+    execute_if_allowed,
+    GateDecision,
+    ReplayResult,
+)
+
+# Import version
+from .client import __version__
+
+# Import policy models
+from .policy import (
+    Policy,
+    PolicyRule,
+    MatchCondition,
+    RiskRule,
+    RiskLevel,
+    create_policy,
+)
+
+__all__ = [
+    # Configuration
+    "configure",
+    "ClientConfig",
+    
+    # Core functions
+    "submit_action",
+    "submit_actions",
+    "submit_actions_bulk",
+    "submit_and_wait",
+    "block_until_approved",
+    "get_action",
+    "list_actions",
+    "approve_action",
+    "deny_action",
+    "start_action",
+    "replay_action",
+    "wait_for_completion",
+    "apply",
+    "tail_events",
+    "stream_events",
+    
+    # Convenience aliases
+    "allow",
+    "deny",
+    
+    # Policy models
+    "Policy",
+    "PolicyRule",
+    "MatchCondition",
+    "RiskRule",
+    "RiskLevel",
+    "create_policy",
+    
+    # Policy helpers
+    "validate_policy_file",
+    "test_policy_against_action",
+    
+    # Canonicalization helpers
+    "canonicalize",
+    "canonicalize_action_payload",
+    "compute_request_hash",
+    "compute_hash",
+    "CanonicalizeError",
+    
+    # Gate/Replay helpers
+    "gate_decide",
+    "gate_decide_dict",
+    "replay_decision",
+    "verify_request_hash",
+    "execute_if_allowed",
+    "GateDecision",
+    "ReplayResult",
+    
+    # Decorators
+    "governed_tool",
+    
+    # Utilities
+    "ActionSnapshotStore",
+    "get_default_store",
+    
+    # Exceptions
+    "FarameshError",
+    "FarameshAuthError",
+    "FarameshNotFoundError",
+    "FarameshPolicyError",
+    "FarameshTimeoutError",
+    "FarameshConnectionError",
+    "FarameshValidationError",
+    "FarameshServerError",
+    "FarameshBatchError",
+    "FarameshDeniedError",
+    
+    # Legacy API
+    "ExecutionGovernorClient",
+    "GovernorConfig",
+    "GovernorError",
+    "GovernorTimeoutError",
+    "GovernorAuthError",
+    "GovernorConnectionError",
+    
+    # Version
+    "__version__",
+]