Metadata-Version: 2.4
Name: vehk-axle
Version: 2.0.0
Summary: Official Python SDK for Vehk Axle Fleet Management, GPS Tracking & Predictive Maintenance Platform
Author-email: Vehk Engineering Team <support@vehk.in>
License: MIT
Project-URL: Homepage, https://vehk.in
Project-URL: Documentation, https://docs.vehk.in/sdk/python
Project-URL: Repository, https://github.com/vehk-axle/python-sdk
Project-URL: Issues, https://github.com/vehk-axle/python-sdk/issues
Keywords: vehk,fleet-management,predictive-maintenance,iot,ml,api,sdk,gps-tracking,telematics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: types-requests>=2.28.0; extra == "dev"
Provides-Extra: async
Requires-Dist: aiohttp>=3.8.0; extra == "async"

# Vehk Axle Python SDK

Official Python SDK for the Vehk Axle Fleet Management, GPS Tracking & Predictive Maintenance Platform.

[![PyPI version](https://badge.fury.io/py/vehk-axle.svg)](https://badge.fury.io/py/vehk-axle)
[![Python Version](https://img.shields.io/pypi/pyversions/vehk-axle.svg)](https://pypi.org/project/vehk-axle/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install vehk-axle
```

## What's New in v2.0.0

- **GPS Tracking API** - Send and retrieve real-time device location data
- **Device Management API** - List devices and get fleet-wide locations
- **Scoped Permissions** - Granular API key scopes (`telemetry:write`, `tracking:read`, etc.)
- **Enforced Rate Limits** - Per-key sliding window rate limiting (default 60 req/min)
- **New Models** - `TrackingData` and `DeviceLocation` dataclasses

## Quick Start

```python
from vehk_axle import VehkClient

client = VehkClient(api_key="vehk_your_api_key_here")

# Send telemetry data
response = client.telemetry.send(
    vehicle_id="VH-001",
    sensor_data={
        "speed": 65,
        "rpm": 2500,
        "coolant_temp": 92,
        "fuel_level": 45,
        "battery_voltage": 12.6
    }
)
print(f"Telemetry sent: {response['telemetry_id']}")

# Send GPS tracking data from a device
client.tracking.send(
    device_id="dev-abc123",
    latitude=12.9716,
    longitude=77.5946,
    speed=45.2,
    ignition=True
)

# Get ML prediction
prediction = client.predict(
    vehicle_id="VH-001",
    sensor_data={"speed": 65, "rpm": 2500, "coolant_temp": 92}
)
print(f"Health Score: {prediction.health_score}%")
print(f"Status: {prediction.health_status.value}")
print(f"Critical: {prediction.is_critical}")
```

## Features

### Telemetry Ingestion

Send real-time sensor data from your vehicles:

```python
# Single telemetry point
client.telemetry.send(
    vehicle_id="VH-001",
    sensor_data={"speed": 65, "rpm": 2500},
    timestamp="2026-03-26T10:00:00Z",
    location={"lat": 12.97, "lng": 77.59}
)

# Batch telemetry (up to 100 at a time)
batch_result = client.telemetry.send_batch([
    {"vehicle_id": "VH-001", "sensor_data": {"speed": 65}},
    {"vehicle_id": "VH-002", "sensor_data": {"speed": 70}},
    {"vehicle_id": "VH-003", "sensor_data": {"speed": 55}},
])
print(f"Processed: {batch_result.records_processed}")
```

### GPS Tracking (v2.0)

Send and retrieve GPS tracking data from configured devices:

```python
# Send a single tracking data point
client.tracking.send(
    device_id="dev-abc123",
    latitude=12.9716,
    longitude=77.5946,
    speed=45.2,
    heading=180,
    ignition=True,
    event="periodic"
)

# Batch tracking (up to 100 at a time)
client.tracking.send_batch([
    {"device_id": "dev-1", "latitude": 12.97, "longitude": 77.59, "speed": 45},
    {"device_id": "dev-2", "latitude": 13.01, "longitude": 77.61, "speed": 30},
])

# Get all device locations (real-time fleet map)
locations = client.tracking.locations()
for loc in locations:
    print(f"{loc['device_id']}: {loc['latitude']}, {loc['longitude']}")

# Get a single device location
loc = client.tracking.location("dev-abc123")
print(f"Speed: {loc['speed']} km/h, Ignition: {loc['ignition']}")
```

### Device Management (v2.0)

List and query devices registered to your tenant:

```python
# List all devices
devices = client.devices.list()
for d in devices:
    print(f"{d['device_id']}: {d.get('status', 'unknown')}")

# Filter by status
active = client.devices.list(status="active")
```

### Predictions

Get AI-powered predictions for vehicle health:

```python
prediction = client.predictions.get(
    vehicle_id="VH-001",
    sensor_data={"speed": 65, "rpm": 2500, "coolant_temp": 92}
)

print(f"Health Score: {prediction.health_score}")
print(f"Risk Level: {prediction.risk_level.value}")

if prediction.needs_maintenance:
    for alert in prediction.maintenance_alerts:
        print(f"  {alert.type}: {alert.description}")

for rec in prediction.recommendations:
    print(f"  {rec}")

# List recent predictions
recent = client.predictions.list(vehicle_id="VH-001", limit=10)
for p in recent:
    print(f"{p.vehicle_id}: {p.health_score}%")
```

### Vehicle Management

```python
vehicles = client.vehicles.list()
for vehicle in vehicles:
    print(f"{vehicle.vehicle_id}: Health {vehicle.health_score}%")
```

## Error Handling

```python
from vehk_axle import (
    VehkClient,
    VehkAuthenticationError,
    VehkRateLimitError,
    VehkConnectionError,
    VehkAPIError,
)

try:
    client = VehkClient(api_key="vehk_your_key")
    prediction = client.predict("VH-001", {"speed": 65})

except VehkAuthenticationError:
    print("Invalid API key. Check your credentials.")

except VehkRateLimitError as e:
    print(f"Rate limit hit. Retry after {e.retry_after} seconds.")

except VehkConnectionError:
    print("Could not connect to Vehk API. Check your network.")

except VehkAPIError as e:
    print(f"API error [{e.status_code}]: {e.message}")
```

## API Scopes (v2.0)

API keys now enforce granular permission scopes:

| Scope | Description |
|-------|-------------|
| `telemetry:write` | Send telemetry data |
| `telemetry:read` | Read telemetry history |
| `tracking:write` | Send GPS tracking data |
| `tracking:read` | Read device locations |
| `devices:read` | List devices |
| `predict` | Request ML predictions |
| `vehicles:read` | List vehicles |

## Configuration

### Custom Base URL

```python
client = VehkClient(
    api_key="vehk_your_key",
    base_url="https://api-staging.vehk.in"
)
```

### Timeout & Retries

```python
client = VehkClient(
    api_key="vehk_your_key",
    timeout=60,
    retries=5,
    retry_delay=2.0
)
```

### Context Manager

```python
with VehkClient(api_key="vehk_your_key") as client:
    prediction = client.predict("VH-001", {"speed": 65})
```

## Health Check

```python
health = client.health_check()
print(f"Status: {health['status']}")
print(f"Version: {health['version']}")
```

## Supported Sensor Fields

| Field | Description | Unit |
|-------|-------------|------|
| `speed` | Vehicle speed | km/h |
| `rpm` | Engine RPM | RPM |
| `coolant_temp` | Coolant temperature | °C |
| `fuel_level` | Fuel level | % |
| `battery_voltage` | Battery voltage | V |
| `oil_pressure` | Oil pressure | PSI |
| `throttle` | Throttle position | % |
| `intake_air_temp` | Intake air temperature | °C |
| `ambient_temp` | Ambient temperature | °C |
| `odometer` | Odometer reading | km |

## Requirements

- Python 3.8+
- `requests` library

## Getting Your API Key

1. Log in to [Vehk Dashboard](https://vehk-frontend.bravedune-34ccdec3.centralindia.azurecontainerapps.io)
2. Go to **Settings > API Keys**
3. Click **"Generate New Key"**
4. Copy the key (shown only once)

## Support

- [Documentation](https://docs.vehk.in/sdk/python)
- Email: support@vehk.in
- [Discord Community](https://discord.gg/vehk)

## License

MIT License - see [LICENSE](LICENSE) for details.
