spacetime-os

Sentinel OS Python SDK -- maritime threat intelligence, vessel tracking, and critical infrastructure security.

Installation

pip install spacetime-os

Or install from source:

git clone https://github.com/spacetime-io/spacetime-os.git
cd spacetime-os/packages/python-sdk
pip install -e .

Quick Start (async)

import asyncio
from spacetime_os import SentinelClient, EventCreate

async def main():
    async with SentinelClient(api_key="sk-...") as client:
        # Submit an AIS position event
        event = EventCreate(
            type="ais_position",
            source="ais-receiver-north",
            data={"mmsi": "211234567", "lat": 59.33, "lon": 18.07, "sog": 12.4},
        )
        result = await client.submit_event(event)
        print(f"Event accepted: {result.event_id}")

        # List recent incidents
        incidents = await client.list_incidents(severity="critical")
        for inc in incidents:
            print(f"[{inc.severity}] {inc.title}")

        # Search vessels
        vessels = await client.search_vessels("NORD STREAM")
        for v in vessels:
            print(f"{v.name} (MMSI: {v.mmsi}, Flag: {v.flag})")

asyncio.run(main())

Quick Start (sync)

Every async method has a _sync counterpart for scripts and notebooks:

from spacetime_os import SentinelClient

client = SentinelClient(api_key="sk-...")

# Get vessel risk assessment
risk = client.get_vessel_risk_sync("211234567")
print(f"Risk: {risk.risk_level} (score: {risk.score})")

# Resolve an incident
client.resolve_incident_sync("inc-abc123", note="False alarm confirmed")

client.close_sync()

API Coverage

Error Handling

from spacetime_os import SentinelClient, AuthError, RateLimitError, NotFoundError

client = SentinelClient(api_key="sk-...")

try:
    vessel = await client.get_vessel("999999999")
except AuthError:
    print("Invalid API key")
except NotFoundError:
    print("Vessel not found")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")

Configuration

client = SentinelClient(
    api_key="sk-...",
    base_url="https://oceanapi.ainative.studio/api/v1",  # default
    timeout=30.0,       # HTTP timeout in seconds
    max_retries=3,      # retries on 429/502/503 with exponential backoff
)

License

MIT -- SpaceTime Industries