> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rotastellar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Official Python SDK for the RotaStellar API

# Python SDK

The official Python SDK for RotaStellar, providing full access to Planning, Intelligence, and Runtime APIs.

<Info>
  **Status:** Early Access — [Request API key](https://rotastellar.com/developers)
</Info>

## Installation

```bash theme={null}
pip install rotastellar
```

### Requirements

* Python 3.9+
* httpx (for HTTP requests)

### Optional Dependencies

```bash theme={null}
# For async support
pip install rotastellar[async]

# For data analysis utilities
pip install rotastellar[pandas]

# All optional dependencies
pip install rotastellar[all]
```

## Quick Start

```python theme={null}
from rotastellar import RotaStellarClient

# Initialize client
client = RotaStellarClient(api_key="rs_your_api_key")

# Or use environment variable
# export ROTASTELLAR_API_KEY=rs_your_api_key
client = RotaStellarClient()

# Track a satellite
iss = client.get_satellite("25544")
print(f"ISS: {iss.position.latitude}, {iss.position.longitude}")
```

## Client Configuration

```python theme={null}
from rotastellar import RotaStellarClient

client = RotaStellarClient(
    api_key="rs_...",
    base_url="https://api.rotastellar.com/v1",  # Default
    timeout=30.0,     # Request timeout in seconds
    max_retries=3,    # Retry failed requests
    debug=False       # Enable debug logging
)
```

## Intelligence API

### Get Satellite

```python theme={null}
# Get satellite by NORAD ID
sat = client.get_satellite("25544")  # ISS
print(f"Name: {sat.name}")
print(f"Position: {sat.position.latitude}, {sat.position.longitude}")
print(f"Altitude: {sat.position.altitude_km} km")

# Get position only
pos = client.get_satellite_position("25544")
print(f"Position: {pos.latitude}, {pos.longitude} at {pos.altitude_km} km")
```

### List Satellites

```python theme={null}
# List satellites with filters
satellites = client.list_satellites(
    constellation="Starlink",
    limit=100
)

for sat in satellites:
    print(f"{sat.name}: {sat.norad_id}")

# Filter by operator
spacex_sats = client.list_satellites(operator="SpaceX", limit=50)
```

### Conjunction Analysis

```python theme={null}
from rotastellar.types import TimeRange

# Get conjunction risks for a satellite
conjunctions = client.list_conjunctions(
    satellite_id="25544",
    threshold_km=5.0,
    limit=10
)

for conj in conjunctions:
    print(f"TCA: {conj['tca']}")
    print(f"Miss distance: {conj['miss_distance_km']:.3f} km")
    print(f"Probability: {conj['collision_probability']:.2e}")
```

### Pattern Detection

```python theme={null}
# Detect maneuvers and anomalies
patterns = client.list_patterns(
    satellite_id="44832",  # COSMOS-2542
    lookback_days=30
)

for pattern in patterns:
    print(f"{pattern['type']}: {pattern['description']}")
    print(f"Confidence: {pattern['confidence']:.1%}")
```

### Trajectory Prediction

```python theme={null}
from datetime import datetime, timedelta

# Get predicted trajectory (start/end are ISO 8601 strings)
trajectory = client.get_trajectory(
    satellite_id="25544",
    start=datetime.utcnow().isoformat(),
    end=(datetime.utcnow() + timedelta(hours=2)).isoformat(),
    interval_sec=60
)

for point in trajectory:
    print(f"{point['timestamp']}: {point['lat']:.2f}, {point['lon']:.2f}")
```

## Planning API

### Feasibility Analysis

```python theme={null}
# Analyze if orbital compute is viable for your workload
result = client.analyze_feasibility(
    workload_type="inference",
    compute_tflops=10,
    data_gb=1.5,
    latency_requirement_ms=100,
    orbit_altitude_km=550
)

print(f"Feasible: {result['feasible']}")
print(f"Recommendation: {result['recommendation']}")
```

### Thermal Simulation

```python theme={null}
# Model heat rejection in orbit
thermal = client.simulate_thermal(
    power_watts=500,
    orbit_altitude_km=550,
    radiator_area_m2=2.0,
    duration_hours=24
)

print(f"Max temp: {thermal['max_temperature_c']}°C")
print(f"Min temp: {thermal['min_temperature_c']}°C")
```

### Latency Simulation

```python theme={null}
from rotastellar.types import Position

# Model end-to-end latency
source = Position(latitude=37.7749, longitude=-122.4194)  # San Francisco
dest = Position(latitude=51.5074, longitude=-0.1278)      # London

latency = client.simulate_latency(
    source=source,
    destination=dest,
    orbit_altitude_km=550,
    relay_count=2
)

print(f"Total latency: {latency['total_latency_ms']:.1f} ms")
```

## Runtime API (Coming Q2 2026)

```python theme={null}
# Submit inference job to orbital compute
job = client.submit_job(
    model="llama-70b",
    prompt="...",
    constraints={
        "latency_sla_ms": 200,
        "energy_budget_wh": 0.5
    }
)

# Get result
result = client.get_job_result(job['id'], timeout=30)
print(result['text'])
```

## Async Client

For high-performance async applications:

```python theme={null}
import asyncio
from rotastellar import AsyncRotaStellarClient

async def main():
    client = AsyncRotaStellarClient(api_key="rs_...")

    # Async satellite tracking
    iss = await client.get_satellite("25544")
    print(f"ISS: {iss.position.latitude}, {iss.position.longitude}")

    # Concurrent requests
    satellites = ["25544", "43013", "20580"]
    tasks = [client.get_satellite(s) for s in satellites]
    results = await asyncio.gather(*tasks)

    for sat in results:
        print(f"{sat.name}: {sat.position.altitude_km} km")

asyncio.run(main())
```

## Pagination

Handle large result sets with the `PaginatedResponse` class:

```python theme={null}
from rotastellar import PaginatedResponse

# Manual pagination
page = client.list_satellites(constellation="Starlink", limit=100)

print(f"Page has {len(page.items)} items, has_more={page.has_more}")

for sat in page.items:
    print(sat.name)

if page.has_more:
    next_page = page.next_page()

# Automatic iteration (auto-fetches next pages)
for sat in client.list_satellites(constellation="Starlink"):
    print(sat.name)

# Async auto-pagination
async for sat in async_client.list_satellites(constellation="Starlink"):
    print(sat.name)
```

### PaginatedResponse Properties

| Property   | Type          | Description                |
| ---------- | ------------- | -------------------------- |
| `items`    | `List[T]`     | Current page of items      |
| `has_more` | `bool`        | Whether more pages exist   |
| `total`    | `int \| None` | Total count (if available) |
| `limit`    | `int`         | Page size                  |
| `offset`   | `int`         | Current offset             |

## Distributed Compute API (Coming Q1 2026)

The `rotastellar-distributed` package enables Earth-space AI coordination:

```bash theme={null}
pip install rotastellar-distributed
```

### Federated Learning

```python theme={null}
from rotastellar_distributed import FederatedClient, CompressionConfig, CompressionMethod

# Configure gradient compression (100x reduction)
compression = CompressionConfig(
    method=CompressionMethod.TOP_K_QUANTIZED,
    k_ratio=0.01,
    quantization_bits=8,
    error_feedback=True
)

# Initialize client on orbital node
client = FederatedClient(
    node_id="orbital-3",
    compression=compression,
    node_type="orbital"
)

# Compute and compress gradients for transmission
gradients = client.compute_gradients(model_params, local_data)
compressed = client.compress(gradients)
```

<Info>
  See the [Distributed Compute documentation](/distributed/overview) for full API reference.
</Info>

## Error Handling

```python theme={null}
from rotastellar import RotaStellarClient
from rotastellar.errors import (
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
    APIError
)

client = RotaStellarClient(api_key="rs_...")

try:
    sat = client.get_satellite("INVALID-ID")
except NotFoundError:
    print("Satellite not found")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except APIError as e:
    print(f"API error: {e.message}")
```

## Type Hints

The SDK includes full type annotations for IDE support:

```python theme={null}
from rotastellar import RotaStellarClient
from rotastellar.types import Position, Orbit, Satellite

client = RotaStellarClient(api_key="rs_...")

sat: Satellite = client.get_satellite("25544")
pos: Position = sat.position
orbit: Orbit = sat.orbit

# IDE will provide autocomplete for all fields
print(pos.latitude)              # float
print(pos.longitude)             # float
print(pos.altitude_km)           # float
print(orbit.orbital_period_minutes)  # float
```

## Logging

Enable debug logging:

```python theme={null}
import logging

logging.basicConfig(level=logging.DEBUG)

# Or configure specific logger
logger = logging.getLogger("rotastellar")
logger.setLevel(logging.DEBUG)
```

## Source Code

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/rotastellar/rotastellar-python">
    View source, report issues, and contribute.
  </Card>

  <Card title="PyPI Package" icon="python" href="https://pypi.org/project/rotastellar/">
    Package page and version history.
  </Card>
</CardGroup>