Skip to main content

Python SDK Installation

The ASCEND Python SDK provides a simple interface for integrating AI governance into your Python applications.

Source of Truth: This documentation is based on the actual implementation in /ow-ai-backend/integration-examples/python_sdk_example.py (lines 1-622)

Requirements​

  • Python 3.8 or higher
  • pip package manager

Installation​

Prerequisites​

Install the required dependencies:

pip install requests python-dotenv

SDK Integration​

The ASCEND SDK is currently distributed as source code. You have two options:

Option 1: Copy the SDK Classes (Recommended)

Copy the following classes from /integration-examples/python_sdk_example.py into your project:

  • OWKAIClient (lines 105-310)
  • AuthorizedAgent (lines 328-458)
  • AgentAction (lines 74-102)
  • ActionType (lines 55-62)
  • DecisionStatus (lines 65-72)

Option 2: Import from Integration Examples

import sys
sys.path.append('/path/to/ow-ai-backend/integration-examples')
from python_sdk_example import OWKAIClient, AuthorizedAgent, AgentAction

Environment Variables​

Create a .env file in your project root:

# API Configuration
OWKAI_API_URL=https://pilot.owkai.app
OWKAI_API_KEY=owkai_live_your_api_key_here
OWKAI_ORG_SLUG=your-organization-slug

Environment Variable Reference​

VariableRequiredDefaultDescription
OWKAI_API_URLNohttps://pilot.owkai.appAPI endpoint URL
OWKAI_API_KEYYes-Your organization's API key
OWKAI_ORG_SLUGNo-Organization identifier

Verify Installation​

Create a test script test_connection.py:

from python_sdk_example import OWKAIClient
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Initialize client
client = OWKAIClient()

# Test connection
status = client.test_connection()
print(f"Connection Status: {status['status']}")

if status['status'] == 'connected':
    print(f"API Version: {status['api_version']}")
    print(f"Server Time: {status['server_time']}")
else:
    print(f"Error: {status.get('error')}")

Run the test:

python test_connection.py

Expected output:

Connection Status: connected
API Version: 2.0
Server Time: 2025-12-04T10:30:00

Quick Start​

from python_sdk_example import OWKAIClient, AgentAction, ActionType

# Initialize client
client = OWKAIClient()

# Submit an agent action
action = AgentAction(
    agent_id="customer-service-agent",
    agent_name="Customer Service AI",
    action_type=ActionType.DATA_ACCESS.value,
    resource="customer_database",
    resource_id="CUST-12345",
    action_details={
        "operation": "read",
        "fields": ["name", "email", "balance"]
    },
    context={
        "user_request": "Show customer profile",
        "session_id": "sess_abc123"
    },
    risk_indicators={
        "pii_involved": True,
        "financial_data": True,
        "data_sensitivity": "medium"
    }
)

# Submit for authorization
response = client.submit_action(action)

print(f"Action ID: {response['action_id']}")
print(f"Status: {response['status']}")
print(f"Decision: {response.get('decision', 'pending')}")

Logging Configuration​

The SDK uses Python's built-in logging module:

import logging

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Enable debug mode
client = OWKAIClient(debug=True)

Docker Installation​

FROM python:3.11-slim

# Install dependencies
RUN pip install --no-cache-dir requests python-dotenv

# Copy SDK files
COPY integration-examples/python_sdk_example.py /app/
COPY your_application.py /app/

WORKDIR /app

CMD ["python", "your_application.py"]

Security Standards​

The ASCEND SDK implements enterprise security standards:

  • SOC 2 Type II Compliant - Multi-tenant data isolation
  • PCI-DSS 8.3 - API key authentication with Bearer tokens
  • HIPAA 164.312 - Audit trails for all actions
  • NIST 800-63B - Secure authentication mechanisms

API Authentication​

The SDK supports two authentication headers (per SEC-033 implementation, lines 142-148):

# Both headers are sent automatically
headers = {
    "X-API-Key": self.api_key,           # SEC-033 support
    "Authorization": f"Bearer {self.api_key}",
    "Content-Type": "application/json",
    "User-Agent": "OWKAIClient/2.0 Python"
}

Troubleshooting​

Missing API Key​

ValueError: API key is required. Set OWKAI_API_KEY environment variable.

Solution: Create a .env file or set the environment variable:

export OWKAI_API_KEY=owkai_live_your_key

Connection Errors​

# Test with custom timeout
client = OWKAIClient(timeout=60)  # 60 seconds
status = client.test_connection()

SSL Certificate Errors​

# Update certificates
pip install --upgrade certifi

Import Errors​

# Verify Python version
import sys
print(f"Python version: {sys.version}")

# Verify dependencies
import requests
import dotenv
print("Dependencies installed successfully")

Next Steps​

Source Code Reference​

The complete SDK implementation is available in:

/ow-ai-backend/integration-examples/python_sdk_example.py

Key classes and their line numbers:

  • ActionType enum: lines 55-62
  • DecisionStatus enum: lines 65-72
  • AgentAction dataclass: lines 74-102
  • OWKAIClient class: lines 105-326
  • AuthorizedAgent class: lines 328-458
  • Example usage: lines 465-621