Python SDK - Faramesh Documentation

Installation

Install Faramesh from source

cd fara-core
pip install -e .

Basic Usage

Create a client and submit an action in just a few lines

from faracore.sdk import ExecutionGovernorClient

client = ExecutionGovernorClient("http://127.0.0.1:8000")

action = client.submit_action(
    tool="http",
    operation="get",
    params={"url": "https://example.com"},
    context={"agent_id": "custbot"}
)

print(action["status"], action["decision"])

Programmatic Configuration

Configure the client with custom settings

from faracore.sdk import ExecutionGovernorClient, GovernorConfig

config = GovernorConfig(
    base_url="http://localhost:8000",
    agent_id="my-agent",
    timeout=10.0,
    auth_token="your-token",
    max_retries=3
)

client = ExecutionGovernorClient(config)

Submitting Actions

The submit_action method sends an action for evaluation:

response = client.submit_action(
    tool="shell",
    operation="run",
    params={"cmd": "ls -la"},
    context={"agent_id": "test-agent"}
)

# Response includes:
# - id: Action ID
# - status: Current status (pending_decision, pending_approval, allowed, etc.)
# - decision: Policy decision (allow, deny, require_approval)
# - reason: Policy reason
# - approval_token: Token for approval (if require_approval)

Getting Action Status

Check the status of an action:

action = client.get_action(action_id)
print(f"Status: {action['status']}")
print(f"Decision: {action['decision']}")

Listing Actions

Query actions with filters:

# List all actions
actions = client.list_actions()

# Filter by status
actions = client.list_actions(status="pending_approval")

# Filter by agent
actions = client.list_actions(agent_id="my-agent")

# Filter by tool
actions = client.list_actions(tool="shell")

Error Handling

The SDK provides custom exceptions for robust error handling

from faracore.sdk import (
    ExecutionGovernorClient,
    GovernorError,
    GovernorTimeoutError,
    GovernorAuthError,
    GovernorConnectionError
)

try:
    action = client.submit_action(...)
except GovernorAuthError as e:
    print(f"Authentication failed: {e}")
except GovernorTimeoutError as e:
    print(f"Request timed out: {e}")
except GovernorConnectionError as e:
    print(f"Connection failed: {e}")
except GovernorError as e:
    print(f"Error: {e}")

Complete Example

A full working example showing the complete workflow

from faracore.sdk import ExecutionGovernorClient

# Initialize client
client = ExecutionGovernorClient("http://127.0.0.1:8000")

# Submit an action
response = client.submit_action(
    tool="shell",
    operation="run",
    params={"cmd": "echo 'Hello FaraCore'"},
    context={"agent_id": "test-agent"}
)

print(f"Action ID: {response['id']}")
print(f"Status: {response['status']}")

# If approval is required, wait for approval
if response['status'] == 'pending_approval':
    print("Action requires approval. Waiting...")
    # In production, you might poll or use SSE to wait for approval
    
# Check final status
action = client.get_action(response['id'])
print(f"Final status: {action['status']}")

# Close the client
client.close()

Python SDK Reference