GitHub - scutum-defense/scutum-python-sdk: Official Python SDK for the Scutum Command Platform — sync and async clients with Pydantic v2 models

 ____            _
/ ___|  ___ _   _| |_ _   _ _ __ ___
\___ \ / __| | | | __| | | | '_ ` _ \
 ___) | (__| |_| | |_| |_| | | | | | |
|____/ \___|\__,_|\__|\__,_|_| |_| |_|

@scutum/python-sdk

Official Python SDK for the Scutum Command Platform -- typed, validated, production-ready bindings for sovereign defense infrastructure operators.

Scutum is the command-and-control operating system for critical infrastructure protection across the Gulf region. This SDK provides Python developers with first-class access to the Scutum API for incident management, threat response orchestration, asset monitoring, and auditable decision pipelines.

Installation

pip install scutum-sdk

Requirements

Python 3.10 or higher
httpx >= 0.27
Pydantic >= 2.0

From source (development)

git clone https://github.com/ScutumDefense/scutum-python-sdk.git
cd scutum-python-sdk
pip install -e ".[dev]"

Quick Start

import os
from scutum_sdk import ScutumClient

with ScutumClient(
    base_url=os.environ["SCUTUM_ENDPOINT"],
    api_key=os.environ["SCUTUM_API_KEY"],
    region="abudhabi",
) as client:
    # Check platform health
    health = client.health()
    print(f"Platform status: {health}")

    # Get the active incident
    incident = client.get_current_incident()
    print(f"Incident: {incident.title} (severity={incident.severity.value})")

    # Retrieve ranked recommended actions
    recommendations = client.get_recommendations()
    for rec in recommendations:
        print(f"  #{rec.rank}: {rec.label} (confidence: {rec.confidence})")

    # Approve a recommended action
    client.approve_action(action_id=recommendations[0].id)

    # Retrieve the audit trail
    audit = client.get_audit_trail()
    for record in audit:
        print(f"  {record.timestamp} | {record.actor} | {record.action}")

All responses are deserialized into strongly-typed Pydantic models. Invalid data from the API will raise pydantic.ValidationError immediately, ensuring you never silently propagate malformed state.

Async Client

For high-throughput applications, event loops, or integration with async frameworks (FastAPI, Starlette), use AsyncScutumClient:

import asyncio
import os
from scutum_sdk.async_client import AsyncScutumClient

async def main() -> None:
    async with AsyncScutumClient(
        base_url=os.environ["SCUTUM_ENDPOINT"],
        api_key=os.environ["SCUTUM_API_KEY"],
    ) as client:
        health = await client.health()
        print(f"Platform: {health}")

        incident = await client.get_current_incident()
        print(f"Incident: {incident.title} ({incident.severity.value})")

        recommendations = await client.get_recommendations()
        for rec in recommendations:
            print(f"  #{rec.rank}: {rec.label}")

asyncio.run(main())

The async client shares the same method signatures as the sync client. Every method returns an awaitable with identical return types.

API Reference

ScutumClient

The synchronous HTTP client for the Scutum Command Platform.

from scutum_sdk import ScutumClient

Constructor

Parameter	Type	Default	Description
`base_url`	`str`	--	Base URL of the Scutum API (e.g. `https://api.scutum.defense`)
`api_key`	`str \| None`	`None`	Bearer token for API authentication
`region`	`str \| None`	`None`	Deployment region identifier (e.g. `abudhabi`)
`timeout`	`float`	`30.0`	Request timeout in seconds

Methods

Method	Return Type	Description
`health()`	`dict[str, Any]`	Check platform health and connectivity
`get_current_incident()`	`Incident`	Retrieve the currently active incident
`get_recommendations()`	`list[RecommendedAction]`	Get ranked list of recommended actions for the active incident
`approve_action(action_id)`	`dict[str, Any]`	Approve a recommended action by ID
`get_audit_trail()`	`list[AuditRecord]`	Retrieve the full audit trail for the active session
`get_assets()`	`list[Asset]`	List all monitored assets and their current status
`close()`	`None`	Close the underlying HTTP connection pool

AsyncScutumClient

The asynchronous HTTP client. Shares the same constructor parameters and method signatures as ScutumClient, with all methods returning awaitables.

from scutum_sdk.async_client import AsyncScutumClient

Method	Return Type	Description
`health()`	`Coroutine[..., dict[str, Any]]`	Check platform health
`get_current_incident()`	`Coroutine[..., Incident]`	Get active incident
`get_recommendations()`	`Coroutine[..., list[RecommendedAction]]`	Get ranked actions
`approve_action(action_id)`	`Coroutine[..., dict[str, Any]]`	Approve a recommended action
`get_audit_trail()`	`Coroutine[..., list[AuditRecord]]`	Get audit trail
`get_assets()`	`Coroutine[..., list[Asset]]`	List monitored assets
`close()`	`Coroutine[..., None]`	Close connection pool

Domain Models

All models use Pydantic v2 with strict validation, camelCase aliasing (for API compatibility), and full type annotations.

Incident

Represents a detected security incident on the command platform.

Field	Type	Description
`id`	`str`	Unique incident identifier
`title`	`str`	Human-readable incident title
`severity`	`Severity`	Severity level: `critical`, `high`, `medium`, `low`
`confidence`	`float`	AI confidence score, constrained to `[0.0, 1.0]`
`affected_asset_ids`	`list[str]`	IDs of assets affected by this incident
`status`	`IncidentStatus`	Current status: `open`, `under_review`, `resolved`, `dismissed`
`description`	`str \| None`	Optional detailed description

RecommendedAction

A ranked action recommended by the Scutum decision engine.

Field	Type	Description
`id`	`str`	Unique action identifier
`label`	`str`	Human-readable action label
`rank`	`int`	Priority rank (1 = highest), must be >= 1
`rationale`	`str`	Explanation of why this action is recommended
`confidence`	`float`	Confidence score for this recommendation `[0.0, 1.0]`

AuditRecord

An immutable record in the decision audit trail.

Field	Type	Description
`id`	`str`	Unique audit record identifier
`incident_id`	`str \| None`	Associated incident ID (if applicable)
`actor`	`str`	Identity of the actor (operator or system)
`action`	`str`	Description of the action taken
`timestamp`	`str`	ISO 8601 timestamp
`policy_label`	`str \| None`	Governance policy label (e.g. `human-approval-required`)

Asset

A monitored asset within the defense perimeter.

Field	Type	Description
`id`	`str`	Unique asset identifier
`type`	`str`	Asset type (e.g. `fuel_zone`, `radar`, `gate`)
`name`	`str`	Human-readable asset name
`status`	`AssetStatus`	Current status: `normal`, `warning`, `critical`, `offline`

SensorReading

A time-series reading from a connected sensor.

Field	Type	Description
`id`	`str`	Unique reading identifier
`asset_id`	`str`	ID of the asset this sensor belongs to
`type`	`str`	Sensor type (e.g. `temperature`, `motion`)
`value`	`float`	Sensor reading value
`unit`	`str`	Unit of measurement
`timestamp`	`str`	ISO 8601 timestamp

Enumerations

Enum	Values
`Severity`	`critical`, `high`, `medium`, `low`
`IncidentStatus`	`open`, `under_review`, `resolved`, `dismissed`
`AssetStatus`	`normal`, `warning`, `critical`, `offline`

Type Safety

This SDK is built with full type safety as a first-class concern:

PEP 561 compliant: The py.typed marker file is included, enabling downstream consumers to benefit from type checking automatically.
mypy strict mode: The entire SDK passes mypy --strict with zero errors. All function signatures, return types, and model fields are fully annotated.
Pydantic v2 validation: Every API response is parsed through Pydantic models with constrained fields (e.g., confidence is bounded to [0.0, 1.0], rank must be >= 1). Invalid data raises ValidationError immediately.
camelCase aliasing: Models accept both snake_case (Pythonic) and camelCase (API wire format) field names via Pydantic's alias_generator, so affectedAssetIds and affected_asset_ids both work.

from scutum_sdk.models import Incident, Severity

# Type checkers understand the full shape:
incident: Incident = client.get_current_incident()
severity: Severity = incident.severity  # Severity enum, not str
confidence: float = incident.confidence  # float, bounded [0, 1]
assets: list[str] = incident.affected_asset_ids  # list[str]

Architecture

                    +-------------------+
                    |  Your Application |
                    +--------+----------+
                             |
                    +--------v----------+
                    |   ScutumClient    |
                    |  (sync or async)  |
                    +--------+----------+
                             |
                    +--------v----------+
                    |      httpx        |
                    |  HTTP/1.1, HTTP/2 |
                    |  Connection Pool  |
                    +--------+----------+
                             |
                    +--------v----------+
                    |    Scutum API     |
                    |  (REST / JSON)    |
                    +--------+----------+
                             |
                    +--------v----------+
                    |  JSON Response    |
                    +--------+----------+
                             |
                    +--------v----------+
                    |   Pydantic v2     |
                    |   Validation &    |
                    |   Deserialization  |
                    +--------+----------+
                             |
                    +--------v----------+
                    |   Typed Models    |
                    |  (Incident, etc.) |
                    +-------------------+

Key design decisions:

httpx over requests: httpx provides both sync and async clients from a single library, supports HTTP/2, and has superior connection pooling.
Pydantic v2 over dataclasses: Pydantic provides runtime validation, serialization, and JSON Schema generation. v2 is built on Rust (pydantic-core) for significant performance gains.
Context manager pattern: Both clients implement __enter__/__exit__ (sync) and __aenter__/__aexit__ (async) to ensure connection pools are properly cleaned up.

Error Handling

The SDK uses standard Python exceptions with clear semantics:

import httpx
from pydantic import ValidationError
from scutum_sdk import ScutumClient

with ScutumClient(base_url="https://api.scutum.defense", api_key="...") as client:
    try:
        incident = client.get_current_incident()
    except httpx.HTTPStatusError as e:
        # Server returned 4xx or 5xx
        print(f"API error: {e.response.status_code} - {e.response.text}")
    except httpx.ConnectError:
        # Network connectivity issue
        print("Cannot reach Scutum API")
    except httpx.TimeoutException:
        # Request timed out
        print("Request timed out")
    except ValidationError as e:
        # Response did not match expected schema
        print(f"Invalid response data: {e}")

Exception	When
`httpx.HTTPStatusError`	API returns non-2xx status code
`httpx.ConnectError`	Cannot establish TCP connection
`httpx.TimeoutException`	Request exceeds configured timeout
`pydantic.ValidationError`	Response JSON does not match model schema

All httpx exceptions inherit from httpx.HTTPError, so you can catch that base class for broad error handling.

Configuration

Environment Variables

Variable	Description	Example
`SCUTUM_ENDPOINT`	Base URL of the Scutum API	`https://api.scutum.defense`
`SCUTUM_API_KEY`	Bearer token for authentication	`sk-live-...`
`SCUTUM_REGION`	Deployment region	`abudhabi`
`SCUTUM_TIMEOUT`	Request timeout in seconds	`30`

Constructor Parameters

client = ScutumClient(
    base_url="https://api.scutum.defense",  # Required
    api_key="sk-live-...",                   # Optional: sets Authorization header
    region="abudhabi",                       # Optional: deployment region
    timeout=60.0,                            # Optional: request timeout (default: 30s)
)

If api_key is provided, it is sent as a Bearer token in the Authorization header on every request. If omitted, requests are sent without authentication (useful for local development against mock servers).

Testing

The SDK is tested across multiple Python versions using pytest.

# Run full test suite
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=scutum_sdk --cov-report=term-missing

# Type checking
mypy scutum_sdk/

# Linting
ruff check .

Multi-version testing

The CI pipeline tests against Python 3.10, 3.11, and 3.12 on every pull request and push to main. See .github/workflows/ci.yml for the full matrix configuration.

Writing tests

Tests are organized by module:

tests/
  test_models.py    # Domain model validation and serialization
  test_client.py    # Client initialization, headers, context managers

Contributing

Development Setup

git clone https://github.com/ScutumDefense/scutum-python-sdk.git
cd scutum-python-sdk
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Development Workflow

Create a feature branch from main
Make your changes with full type annotations

Ensure all checks pass:

ruff check .
mypy scutum_sdk/
pytest tests/ -v

Open a pull request against main

Code Style

Formatter: Ruff (configured in pyproject.toml)
Linter: Ruff with strict rules
Type checker: mypy in strict mode
Docstrings: Google style
Line length: 120 characters

Pull Request Requirements

All CI checks must pass (lint, type check, tests across 3.10/3.11/3.12)
New public API methods require tests
New models require validation tests
CODEOWNERS approval required for models.py changes

Security

Reporting Vulnerabilities

If you discover a security vulnerability, please report it responsibly:

Email: security@scutumdefense.com
Do not open a public GitHub issue for security vulnerabilities

Security Measures

CodeQL analysis runs on every PR and push to main
TruffleHog scans for leaked secrets on every commit
Dependency auditing via scheduled security workflows (weekly)
No secrets in code: API keys are passed via constructor or environment variables, never hardcoded
HTTPS enforced: The SDK does not downgrade connections

Supply Chain

Minimal dependency footprint: only httpx and pydantic
All dependencies are pinned to major versions in pyproject.toml
No native extensions or C dependencies beyond pydantic-core (Rust)

Roadmap

Planned

v0.2.0 -- Streaming support for real-time sensor data via WebSocket
v0.3.0 -- Retry policies with exponential backoff and circuit breaker
v0.4.0 -- Batch operations for multi-incident workflows
v1.0.0 -- Stable API, full OpenAPI spec alignment

Future SDKs

Language	Repository	Status
Python	`scutum-python-sdk` (this)	Active
Go	`scutum-go-sdk`	Planned
Rust	`scutum-rust-sdk`	Under evaluation

Integration Targets

FastAPI middleware for Scutum-backed auth
Airflow operators for scheduled threat sweeps
Terraform provider for infrastructure-as-code asset management

License

This project is licensed under the Apache License 2.0. See LICENSE for the full text.

Copyright 2026 Scutum Defense

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Built by Scutum Defense -- Sovereign infrastructure protection for the Gulf region.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
examples		examples
scutum_sdk		scutum_sdk
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODEOWNERS		CODEOWNERS
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Table of Contents

Installation

Requirements

From source (development)

Quick Start

Async Client

API Reference

ScutumClient

Constructor

Methods

AsyncScutumClient

Domain Models

Incident

RecommendedAction

AuditRecord

Asset

SensorReading

Enumerations

Type Safety

Architecture

Error Handling

Configuration

Environment Variables

Constructor Parameters

Testing

Multi-version testing

Writing tests

Development Setup

Development Workflow

Code Style

Pull Request Requirements

Reporting Vulnerabilities

Security Measures

Supply Chain

Planned

Future SDKs

Integration Targets

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages