Metadata-Version: 2.4
Name: sector8-sdk
Version: 1.0.3
Summary: Pre-execution policy evaluation SDK for Sector8 AI agents and tools
Author-email: Sector8 Team <support@sector8.ai>
Maintainer-email: Sector8 Team <support@sector8.ai>
License-Expression: MIT
Project-URL: Homepage, https://sector8.ai
Project-URL: Documentation, https://sdkapi.sector8.ai/api/health
Project-URL: Repository, https://github.com/sector8-ai/sector8-sdk-python
Project-URL: Bug Tracker, https://github.com/sector8-ai/sector8-sdk-python/issues
Project-URL: Source Code, https://github.com/sector8-ai/sector8-sdk-python
Project-URL: Security Policy, https://github.com/sector8-ai/sector8-sdk-python/security/policy
Keywords: ai,security,llm,policy,execution,guardrails,mcp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8.0
Provides-Extra: full
Requires-Dist: pydantic>=2.0.0; extra == "full"
Requires-Dist: click>=8.0.0; extra == "full"
Requires-Dist: rich>=13.0.0; extra == "full"
Requires-Dist: asyncio-mqtt>=0.11.0; extra == "full"
Requires-Dist: python-dotenv>=1.0.0; extra == "full"
Requires-Dist: typing-extensions>=4.0.0; extra == "full"
Requires-Dist: opentelemetry-api>=1.20.0; extra == "full"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "full"
Requires-Dist: opentelemetry-instrumentation<1.0.0,>=0.52b0; extra == "full"
Requires-Dist: wrapt>=1.14.0; extra == "full"
Requires-Dist: keyring>=25.0.0; extra == "full"
Requires-Dist: cryptography>=3.4.0; extra == "full"
Requires-Dist: tenacity>=8.0.0; extra == "full"
Requires-Dist: requests>=2.28.0; extra == "full"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.7.0; extra == "anthropic"
Provides-Extra: google
Requires-Dist: google-generativeai>=0.3.0; extra == "google"
Provides-Extra: azure
Requires-Dist: openai>=1.0.0; extra == "azure"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-instrumentation<1.0.0,>=0.52b0; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "otel"
Provides-Extra: prometheus
Requires-Dist: prometheus-client>=0.17.0; extra == "prometheus"
Provides-Extra: datadog
Requires-Dist: datadog>=0.44.0; extra == "datadog"
Provides-Extra: ml
Requires-Dist: pandas>=1.5.0; extra == "ml"
Requires-Dist: numpy>=1.24.0; extra == "ml"
Requires-Dist: scikit-learn>=1.3.0; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
Requires-Dist: myst-parser>=1.0.0; extra == "docs"
Provides-Extra: all
Requires-Dist: pydantic>=2.0.0; extra == "all"
Requires-Dist: click>=8.0.0; extra == "all"
Requires-Dist: rich>=13.0.0; extra == "all"
Requires-Dist: asyncio-mqtt>=0.11.0; extra == "all"
Requires-Dist: python-dotenv>=1.0.0; extra == "all"
Requires-Dist: typing-extensions>=4.0.0; extra == "all"
Requires-Dist: opentelemetry-api>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-instrumentation<1.0.0,>=0.52b0; extra == "all"
Requires-Dist: wrapt>=1.14.0; extra == "all"
Requires-Dist: keyring>=25.0.0; extra == "all"
Requires-Dist: cryptography>=3.4.0; extra == "all"
Requires-Dist: tenacity>=8.0.0; extra == "all"
Requires-Dist: requests>=2.28.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.7.0; extra == "all"
Requires-Dist: google-generativeai>=0.3.0; extra == "all"
Requires-Dist: opentelemetry-api>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-instrumentation<1.0.0,>=0.52b0; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "all"
Requires-Dist: prometheus-client>=0.17.0; extra == "all"
Requires-Dist: datadog>=0.44.0; extra == "all"
Requires-Dist: pandas>=1.5.0; extra == "all"
Requires-Dist: numpy>=1.24.0; extra == "all"
Requires-Dist: scikit-learn>=1.3.0; extra == "all"
Dynamic: license-file

# Sector8 SDK

[![PyPI version](https://badge.fury.io/py/sector8-sdk.svg)](https://badge.fury.io/py/sector8-sdk)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Python SDK for evaluating proposed AI-agent and tool actions with Sector8
before execution.

Sector8 is an execution-boundary security platform for AI systems. The production Guard Module is live at `https://sdkapi.sector8.ai`.

## What this package is for

Use `sector8-sdk` when you want to:
- evaluate an action before your application executes it
- verify a new customer runtime key and decision contract
- retain canonical ALLOW or DENY decision artifacts for audit
- optionally use legacy telemetry, alert, and MCP guard helpers

The default installation is intentionally slim and contains the evaluate and
onboarding path. The paid wedge is the live Gate and decision service, not a
large client-side framework.

## Installation

```bash
pip install sector8-sdk
```

Use the exact PyPI package name `sector8-sdk`, not `sector8` or `sdk`.

Install the optional legacy telemetry and observability dependencies only when
needed:

```bash
pip install sector8-sdk[full]
pip install sector8-sdk[openai]
pip install sector8-sdk[anthropic]
pip install sector8-sdk[google]
pip install sector8-sdk[all]
```

## Verify a new customer connection

Run `sector8-verify --help` before using a customer key. For reproducible
customer onboarding, pin the approved SDK version in your own requirements.

```powershell
pip install sector8-sdk
$env:SECTOR8_API_KEY = "<one-time-reveal-runtime-key>"
$env:SECTOR8_CLIENT_ID = "<client-id>"
$env:SECTOR8_ENDPOINT = "https://stgsdkapi.sector8.ai" # omit for production
$env:SECTOR8_UNSAFE_ENDPOINT = "true" # staging only
sector8-verify
```

The staging endpoint requires explicit unsafe-endpoint opt-in because the SDK
allows only the production host by default. Remove both endpoint variables for
production.

## Quick start

Set your credentials:

```bash
export SECTOR8_API_KEY="your-api-key"
export SECTOR8_CLIENT_ID="your-client-id"
```

Send telemetry:

```python
import sector8

client = sector8.setup(
    api_key="your-api-key",
    client_id="your-client-id",
)

client.log_llm_call(
    provider="openai",
    model="gpt-4o",
    tokens=150,
    cost=0.003,
    latency_ms=800,
    prompt="Summarize this contract.",
    completion="Here is the summary...",
)
```

Protect an action before execution:

```python
decision = await client.evaluate(
    "bash",
    {"command": "git status"},
    caller_id="developer-1",
    role="developer",
    session_id="customer-onboarding-1",
)

if decision.allowed:
    run_the_action()
else:
    audit_log(decision.reason_code, decision.decision_trace_id)
```

A policy `DENY` is returned as a normal decision artifact. Authentication,
scope, validation, transport, and malformed-response failures raise SDK errors.
Never execute an action unless `decision.allowed` is `True`.

You can also call the async methods directly:

```python
import asyncio
import sector8


async def main() -> None:
    client = sector8.setup(api_key="your-api-key", client_id="your-client-id")
    await client.save_telemetry(
        provider="openai",
        model="gpt-4o",
        prompt="Classify this email",
        completion="Likely phishing",
        tokens_used=240,
        latency_ms=620,
        cost=0.0048,
        success=True,
        metadata={"route": "inbound-mail"},
    )
    await client.close()


asyncio.run(main())
```

## Threat alerts and incidents

```python
import sector8

client = sector8.setup(api_key="your-api-key", client_id="your-client-id")
client.alert_threat("prompt_injection", severity="High", description="Jailbreak attempt detected")
client.log_incident("Sensitive file request denied", severity="high", classification="policy_deny")
```

## MCP guard helper

This package also ships a small CLI for installing the Sector8 guard MCP entry into a project:

```bash
sector8-guard install
sector8-guard version
```

The installer writes `.claude/settings.json` entries that point at the repo-local MCP stdio server and pass through:
- `SECTOR8_API_KEY`
- `SECTOR8_CLIENT_ID`

## Runtime endpoints used by this SDK

- Production API: `https://sdkapi.sector8.ai`
- Telemetry ingest: `POST /api/v1/telemetry`
- Threat alerts: `POST /api/v1/threat-alerts`
- Incident logs: `POST /api/v1/incident-logs`

## Secure host configuration

The SDK uses `https://sdkapi.sector8.ai` by default and treats `endpoint` as
the preferred configuration field. The legacy `base_url` alias is still
accepted for compatibility.

- plain HTTP is rejected by default
- arbitrary remote hosts other than `sdkapi.sector8.ai` are rejected by default
- endpoint values with `/api/...` paths, query strings, or fragments are rejected by default
- local or mock testing requires explicit opt-in

```python
client = sector8.setup(
    api_key="your-api-key",
    endpoint="http://localhost:9876",
    unsafe_endpoint=True,
)
```

Use `unsafe_endpoint=True` only for deliberate local or test use. The older
`allow_unsafe_base_url=True` option remains available as a compatibility alias.

## Links

- Homepage: `https://sector8.ai`
- Production API: `https://sdkapi.sector8.ai`
- Dashboard: `https://app.sector8.ai`
- Repository: `https://github.com/sector8-ai/sector8-sdk-python`

## Development notes

This package targets Python 3.8+ and is published as `sector8-sdk` on PyPI.

The verifier submits safe simulated actions only. It confirms one `ALLOW`, one
`DENY`, and the canonical decision artifact fields without printing credentials
or request payloads.

Never use production credentials with staging, local, or other unsafe
endpoints. Never share a one-time reveal key. A successful run prints one ALLOW
trace, one DENY trace, and `Staging onboarding smoke passed`.

| Exit | Meaning |
| --- | --- |
| `0` | Verification passed |
| `2` | Missing or invalid configuration |
| `3` | Endpoint/network unavailable |
| `4` | Malformed or unexpected decision contract |
| `5` | Authentication failed or key lacks scope |
