Skip to content

Python Integration

This guide covers integrating SIX into Python applications using the requests library and the OpenAI client library.

Prerequisites

pip install requests
# Optional: for OpenAI client compatibility
pip install openai

Set your environment variables:

export SIX_API_KEY="your-api-key-here"
export SIX_ENDPOINT="https://six-sov.com"

Method 1: Using requests

The most direct approach. Full control over the request and response.

Basic Request

import os
import requests

SIX_API_KEY = os.environ["SIX_API_KEY"]
SIX_ENDPOINT = os.environ["SIX_ENDPOINT"]

response = requests.post(
    f"{SIX_ENDPOINT}/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {SIX_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "default",
        "messages": [
            {"role": "user", "content": "Summarize HIPAA Section 164.312"}
        ],
    }
)

response.raise_for_status()
data = response.json()

# AI response
content = data["choices"][0]["message"]["content"]
print(content)

# Cryptographic receipt
receipt = data["receipt"]
print(f"Receipt ID: {receipt['receipt_id']}")
print(f"Verified: {receipt['verified']}")

With Privacy Tier

response = requests.post(
    f"{SIX_ENDPOINT}/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {SIX_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "default",
        "messages": [
            {"role": "system", "content": "You are a compliance assistant."},
            {"role": "user", "content": "What are the key SOX 404 requirements?"}
        ],
        "privacy_tier": "sovereign",
    }
)

data = response.json()
assert data["receipt"]["routing"] == "sovereign"

Method 2: Using the OpenAI Client

If you already use the OpenAI Python client, switch to SIX with two lines:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SIX_API_KEY"],
    base_url=f"{os.environ['SIX_ENDPOINT']}/v1",
)

response = client.chat.completions.create(
    model="default",
    messages=[
        {"role": "user", "content": "Summarize HIPAA Section 164.312"}
    ],
)

print(response.choices[0].message.content)

Privacy Tier with OpenAI Client

Use extra_body to pass SIX-specific fields:

response = client.chat.completions.create(
    model="default",
    messages=[
        {"role": "user", "content": "What are the key SOX 404 requirements?"}
    ],
    extra_body={"privacy_tier": "sovereign"},
)

Receipt Access with OpenAI Client

The OpenAI client library may not directly expose the receipt field on the response object. Access it via the raw response or use the requests library for full receipt access.

Handling Receipts

Extracting and Storing Receipts

import json
from datetime import datetime

def make_inference(prompt, privacy_tier="standard"):
    """Make an inference and return both content and receipt."""
    response = requests.post(
        f"{SIX_ENDPOINT}/v1/chat/completions",
        headers={
            "Authorization": f"Bearer {SIX_API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "default",
            "messages": [{"role": "user", "content": prompt}],
            "privacy_tier": privacy_tier,
        }
    )
    response.raise_for_status()
    data = response.json()

    return {
        "content": data["choices"][0]["message"]["content"],
        "receipt": data["receipt"],
        "timestamp": datetime.utcnow().isoformat(),
    }


# Usage
result = make_inference(
    "Summarize HIPAA Section 164.312",
    privacy_tier="sovereign"
)

# Store receipt for audit trail
with open(f"receipts/{result['receipt']['receipt_id']}.json", "w") as f:
    json.dump(result["receipt"], f, indent=2)

Verifying Receipts

def verify_receipt(receipt_id):
    """Verify a receipt via the SIX API."""
    response = requests.get(
        f"{SIX_ENDPOINT}/v1/verify/{receipt_id}",
        headers={"Authorization": f"Bearer {SIX_API_KEY}"},
    )
    response.raise_for_status()
    result = response.json()

    return {
        "receipt_id": receipt_id,
        "status": result["status"],
        "integrity": result["attestation"]["integrity"],
        "settlement": result["attestation"]["settlement"],
        "verified_at": result["verified_at"],
    }


# Verify after inference
verification = verify_receipt(result["receipt"]["receipt_id"])
print(f"Status: {verification['status']}")
print(f"Integrity: {verification['integrity']}")

Batch Verification

import os
import glob

def verify_all_receipts(receipts_dir="receipts/"):
    """Verify all stored receipts and generate an audit report."""
    results = []

    for filepath in glob.glob(os.path.join(receipts_dir, "rcpt_*.json")):
        with open(filepath) as f:
            receipt = json.load(f)

        verification = verify_receipt(receipt["receipt_id"])
        results.append(verification)

    verified = [r for r in results if r["status"] == "verified"]
    failed = [r for r in results if r["status"] != "verified"]

    print(f"Total: {len(results)}")
    print(f"Verified: {len(verified)}")
    print(f"Failed: {len(failed)}")

    if failed:
        print("\nFailed receipts:")
        for r in failed:
            print(f"  {r['receipt_id']}: {r['status']}")

    return results

Error Handling

HTTP Errors

from requests.exceptions import HTTPError, ConnectionError, Timeout

def safe_inference(prompt, privacy_tier="standard", retries=3):
    """Make an inference with error handling and retries."""
    for attempt in range(retries):
        try:
            response = requests.post(
                f"{SIX_ENDPOINT}/v1/chat/completions",
                headers={
                    "Authorization": f"Bearer {SIX_API_KEY}",
                    "Content-Type": "application/json",
                },
                json={
                    "model": "default",
                    "messages": [{"role": "user", "content": prompt}],
                    "privacy_tier": privacy_tier,
                },
                timeout=30,
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", 5))
                print(f"Rate limited. Waiting {retry_after}s...")
                import time
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            return response.json()

        except ConnectionError:
            print(f"Connection failed (attempt {attempt + 1}/{retries})")
            if attempt == retries - 1:
                raise
        except Timeout:
            print(f"Request timed out (attempt {attempt + 1}/{retries})")
            if attempt == retries - 1:
                raise
        except HTTPError as e:
            if e.response.status_code >= 500:
                print(f"Server error (attempt {attempt + 1}/{retries})")
                if attempt == retries - 1:
                    raise
            else:
                # Client errors (4xx) should not be retried
                raise

    return None

API Error Responses

def handle_error(response):
    """Parse and handle SIX API error responses."""
    if response.status_code >= 400:
        error = response.json().get("error", {})
        error_type = error.get("type", "unknown")
        message = error.get("message", "No message provided")

        if error_type == "unauthorized":
            print("Check your API key.")
        elif error_type == "rate_limited":
            print(f"Rate limited: {message}")
        elif error_type == "bad_request":
            print(f"Invalid request: {message}")
        else:
            print(f"Error ({error_type}): {message}")

        return False
    return True

Complete Example

A full working example that makes an inference, stores the receipt, and verifies it:

import os
import json
import requests
from datetime import datetime

# Configuration
SIX_API_KEY = os.environ["SIX_API_KEY"]
SIX_ENDPOINT = os.environ["SIX_ENDPOINT"]
RECEIPTS_DIR = "receipts"

os.makedirs(RECEIPTS_DIR, exist_ok=True)


def main():
    # 1. Make inference
    print("Making inference...")
    response = requests.post(
        f"{SIX_ENDPOINT}/v1/chat/completions",
        headers={
            "Authorization": f"Bearer {SIX_API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "default",
            "messages": [
                {"role": "user", "content": "What are HIPAA technical safeguards?"}
            ],
            "privacy_tier": "sovereign",
        },
        timeout=30,
    )
    response.raise_for_status()
    data = response.json()

    # 2. Use the response
    content = data["choices"][0]["message"]["content"]
    print(f"Response: {content[:200]}...")

    # 3. Store the receipt
    receipt = data["receipt"]
    receipt_path = os.path.join(RECEIPTS_DIR, f"{receipt['receipt_id']}.json")
    with open(receipt_path, "w") as f:
        json.dump({
            "receipt": receipt,
            "prompt_summary": "HIPAA technical safeguards query",
            "stored_at": datetime.utcnow().isoformat(),
        }, f, indent=2)
    print(f"Receipt stored: {receipt_path}")

    # 4. Verify the receipt
    print("Verifying receipt...")
    verify_resp = requests.get(
        f"{SIX_ENDPOINT}/v1/verify/{receipt['receipt_id']}",
        headers={"Authorization": f"Bearer {SIX_API_KEY}"},
        timeout=10,
    )
    verify_resp.raise_for_status()
    result = verify_resp.json()

    print(f"Status: {result['status']}")
    print(f"Routing: {result['receipt']['routing']}")
    print(f"Integrity: {result['attestation']['integrity']}")
    print(f"Settlement: {result['attestation']['settlement']}")


if __name__ == "__main__":
    main()

Next Steps