vehk-axle 1.0.0
Official Python SDK for Vehk Axle Fleet Management & Predictive Maintenance Platform
License: MIT
Requires Python: >=3.8
Keywords: vehk, fleet-management, predictive-maintenance, iot, ml, api, sdk

# Vehk Axle Python SDK

Official Python SDK for the Vehk Axle Fleet Management & 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
```

## Quick Start

```python
from vehk_axle import VehkClient

# Initialize the client with your API key
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']}")

# 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-01-13T10: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}")
```

### 🔮 Predictions

Get AI-powered predictions for vehicle health:

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

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

# Check maintenance needs
if prediction.needs_maintenance:
    for alert in prediction.maintenance_alerts:
        print(f"⚠️ {alert.type}: {alert.description}")

# Get recommendations
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

List and manage your fleet:

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

## Error Handling

The SDK provides detailed exceptions for different error scenarios:

```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. Please 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}")
```

## Configuration

### Custom Base URL

For staging or private deployments:

```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,        # Request timeout in seconds
    retries=5,         # Number of retries
    retry_delay=2.0    # Delay between retries
)
```

### Context Manager

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

## Health Check

```python
# Check if API is healthy (no auth required)
health = client.health_check()
print(f"Status: {health['status']}")
```

## 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 (it's only shown 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.