Metadata-Version: 2.4
Name: sector8-sdk
Version: 1.0.2
Summary: Python SDK for Sector8 AI telemetry, alerts, and MCP guard installation
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,telemetry,mcp,monitoring,guardrails
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
Requires-Dist: pydantic>=2.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: asyncio-mqtt>=0.11.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-sdk>=1.20.0
Requires-Dist: opentelemetry-instrumentation<1.0.0,>=0.52b0
Requires-Dist: wrapt>=1.14.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: cryptography>=3.4.0
Requires-Dist: tenacity>=8.0.0
Requires-Dist: requests>=2.28.0
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: 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 sending AI telemetry and security events to Sector8.

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:
- send telemetry for LLM calls to Sector8
- emit threat alerts and incident logs from your application
- install the Sector8 MCP guard helper into a local project

This package is intentionally simple. The paid wedge is the live guard and decision service, not a large client-side framework.

## Installation

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

Optional extras:

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

## 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.

### Verify a new customer connection

```powershell
$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" # required for deliberate staging use
sector8-verify
```

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 |
