Metadata-Version: 2.4
Name: spacetime-os
Version: 1.0.0
Summary: Sentinel OS Python SDK — maritime threat intelligence, vessel tracking, and critical infrastructure security
Project-URL: Homepage, https://github.com/spacetime-io/spacetime-os
Project-URL: Documentation, https://docs.spacetime.io/sdk/python
Author-email: SpaceTime Industries <support@spacetime.io>
License-Expression: MIT
Keywords: ais,critical-infrastructure,dark-vessels,geospatial,maritime,satellite,security,sentinel,spacetime,threat-detection,threat-intelligence,vessel-tracking
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# spacetime-os

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

## Installation

```bash
pip install spacetime-os
```

Or install from source:

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

## Quick Start (async)

```python
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:

```python
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

| Domain              | Methods                                                          |
|---------------------|------------------------------------------------------------------|
| Events              | `submit_event`, `submit_event_batch`, `list_events`              |
| Incidents           | `list_incidents`, `get_incident`, `acknowledge_incident`, `escalate_incident`, `resolve_incident` |
| Threat Intelligence | `query_threats`, `get_risk_assessment`, `get_vessel_activity`, `get_cable_risk` |
| Vessels             | `get_vessel`, `search_vessels`, `get_vessel_risk`                |
| Assets              | `list_assets`                                                    |
| Sensors             | `list_sensors`, `register_sensor`                                |

## Error Handling

```python
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

```python
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
