Python SDK

Use the Python SDK to evaluate proposed actions before dispatch, then optionally send telemetry.

Use this path when your Python application should ask Sector8 whether a proposed action may execute, then honor the returned decision before local dispatch.

Telemetry helpers are available on the same client. Telemetry alone is not enforcement.

Enforcement requires your runtime to call evaluate before dispatch and honor the result. Unconnected tool paths are not automatically covered.

Prerequisites

• Python 3.10 or later
• SECTOR8_API_KEY
• SECTOR8_CLIENT_ID
• A runtime path where you can block dispatch and fail closed on errors

Install the SDK

pip install sector8-sdk

Source repository: https://github.com/sector8-ai/sector8-sdk-python

Set your credentials

export SECTOR8_API_KEY=your_api_key
export SECTOR8_CLIENT_ID=your_client_id

Public examples use the production host. Use the endpoint and credentials issued for your environment.

Evaluate before dispatch

import asyncio
import os
import sector8

async def main():
    client = sector8.setup(
        api_key=os.environ["SECTOR8_API_KEY"],
        client_id=os.environ["SECTOR8_CLIENT_ID"],
    )

    try:
        decision = await client.evaluate(
            "bash",
            {"command": "cat .env"},
            caller_id="python-sdk-agent",
            role="developer",
            session_id="python-sdk-session",
            operation="read",
        )

        if decision.outcome == "ALLOW":
            # Dispatch the tool call here.
            print("ALLOW", decision.reason_code, decision.decision_trace_id)
        elif decision.outcome == "DENY":
            print("Blocked before execution:", decision.reason_code)
            print("Evidence hash:", decision.evidence_hash)
            print("Trace ID:", decision.decision_trace_id)
        else:
            print("Unknown decision contract; failing closed:", decision)
            # Do not dispatch.
    except Exception as exc:
        print(f"Gate unavailable or invalid response; failing closed: {exc}")
        # Do not dispatch.
    finally:
        await client.close()

asyncio.run(main())

Sector8 returns the verdict. Your application owns honoring that decision at dispatch time.

REST /api/v1/evaluate responses use the field decision. This SDK exposes the same value as outcome. Check for ALLOW the same way either way.

Result	Runtime must
ALLOW (decision.outcome == "ALLOW")	May dispatch
DENY	Block; do not dispatch
Missing, unknown, error, or timeout	Fail closed; do not dispatch

Never execute an action unless decision.outcome == "ALLOW". Fail closed on evaluate errors. Fail-closed applies to tools routed through this SDK path; it does not stop bypassed or unconfigured tool paths.

See Evaluate for the shared ALLOW | DENY contract and Non-MCP integration for custom runtime wiring.

Optional: send telemetry

Telemetry records what happened. It does not replace evaluate-before-dispatch.

import asyncio
import os
import sector8

async def main():
    client = sector8.setup(
        api_key=os.environ["SECTOR8_API_KEY"],
        client_id=os.environ["SECTOR8_CLIENT_ID"],
        debug=True,
    )
    result = await client.save_telemetry(
        provider="openai",
        model="gpt-4",
        prompt="Sector8 Python SDK telemetry test",
        completion="Telemetry sent successfully",
        tokens_used=24,
        latency_ms=120,
        cost=0.001,
        success=True,
        metadata={"source": "python-sdk-onboard"},
    )
    print(result["status"])
    await client.close()

asyncio.run(main())

Short helper:

import sector8

client = sector8.setup(
    api_key="your_api_key",
    client_id="your_client_id",
)

client.log_llm_call("openai", "gpt-4", tokens=150, cost=0.003)

The Python SDK defaults to https://sdkapi.sector8.ai. Override base_url only when targeting a non-default environment you intentionally control.

Verify the integration

1. Check health:

curl https://sdkapi.sector8.ai/api/health

2. Confirm an evaluate call returns a decision artifact
3. Confirm your runtime dispatches only on ALLOW and fails closed on unknown/error
4. Optionally confirm telemetry appears in Sector8 if you send it

You are done when your Python runtime evaluates before dispatch, blocks on DENY, and fails closed on missing/unknown/error responses.

Common mistakes

• Logging telemetry without calling evaluate before tool dispatch
• Dispatching on any non-error response instead of checking decision.outcome == "ALLOW"
• Missing SECTOR8_CLIENT_ID
• Overriding base_url to an older host by accident

Next steps

• Quickstart
• Non-MCP integration
• Guard MCP Server
• Evaluate API