Ona SDK

Introduction

The Ona SDK provides seamless integration with the Ona Energy AI Platform, enabling developers to build applications that interact with Asoba's energy management services. This SDK supports both JavaScript (Node.js & Browser) and Python, making it easy to integrate Ona into third-party applications.

Key Features

✔ Solar Energy Forecasting – Device, site, and customer-level predictions
✔ OODA Workflow – Asset management, fault detection, diagnostics, and maintenance scheduling
✔ Energy Policy Analysis – RAG-powered queries on energy regulations
✔ Edge Device Management – Discovery, registration, and capability detection
✔ Data Collection – Enphase, Huawei, and weather data integration
✔ ML Operations – Model training, interpolation, and data standardization
✔ Dual SDK Support – Use in both JavaScript and Python applications
✔ Comprehensive Error Handling – Detailed API responses and logging for debugging

---

SDKs

This repository contains two SDK implementations:

JavaScript SDK

Official JavaScript/TypeScript SDK for Node.js and browser environments.

📖 View JavaScript SDK Documentation →

Quick Start:

const { OnaSDK } = require('@asoba/ona-sdk');

const sdk = new OnaSDK({
  region: 'af-south-1',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
  }
});

// Get energy forecast
const forecast = await sdk.forecasting.getSiteForecast({
  site_id: 'Sibaya',
  forecast_hours: 24
});

Python SDK

Official Python SDK for server-side and data science applications.

📖 View Python SDK Documentation →

Quick Start:

from ona_platform import OnaClient

client = OnaClient()

# Get solar forecast
forecast = client.forecasting.get_site_forecast('Sibaya', hours=24)

# Run fault detection
detection = client.terminal.run_detection(
    customer_id='customer123',
    asset_id='asset456',
    lookback_hours=6
)

---

Installation

JavaScript SDK

npm install @asoba/ona-sdk

For detailed installation and setup instructions, see the JavaScript SDK Documentation.

Python SDK

pip install ona-platform

Or install from source:

cd python
pip install -e .

For detailed installation and setup instructions, see the Python SDK Documentation.

---

Configuration

Both SDKs support configuration via environment variables or constructor parameters.

Environment Variables

# AWS Configuration
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=af-south-1

# Service Endpoints (optional)
export ONA_FORECASTING_ENDPOINT=https://forecasting.api.asoba.co
export ONA_TERMINAL_ENDPOINT=https://terminal.api.asoba.co

See the individual SDK documentation for complete configuration options:

• JavaScript SDK Configuration
• Python SDK Configuration

---

Services

The Ona SDK provides access to the following platform services:

Forecasting API

Generate energy forecasts at device, site, or customer levels.

Terminal API (OODA Workflow)

Comprehensive API for Observe, Orient, Decide, Act workflow operations including:

• Asset management
• Fault detection
• AI diagnostics
• Maintenance scheduling
• Real-time monitoring

Energy Analyst (RAG)

AI-powered energy policy and regulatory compliance analysis.

Edge Device Registry

Manage distributed edge devices with automatic capability detection.

Data Collection

Integration with Enphase, Huawei, and weather data services.

ML Operations

Model training, interpolation, and data standardization services.

For detailed API documentation, see:

• JavaScript SDK API Reference
• Python SDK API Reference

---

Examples

Both SDKs include comprehensive examples:

JavaScript Examples

Located in javascript/examples/:

• basic-usage.js – Basic SDK initialization and usage
• forecasting-example.js – Energy forecasting examples
• terminal-api-example.js – OODA workflow examples
• edge-device-example.js – Edge device management examples

Python Examples

Located in python/examples/:

• forecasting_example.py – Solar forecasting
• terminal_ooda_example.py – OODA workflow
• energy_analyst_example.py – Energy policy queries
• edge_device_example.py – Edge device management
• complete_workflow_example.py – Multi-service workflow

---

Error Handling

Both SDKs provide comprehensive error handling with custom error classes:

JavaScript

const {
  OnaSDKError,
  APIError,
  ValidationError,
  AuthenticationError,
  TimeoutError
} = require('@asoba/ona-sdk');

Python

from ona_platform import (
    OnaError,
    ConfigurationError,
    ServiceUnavailableError,
    ValidationError,
    ResourceNotFoundError,
    TimeoutError
)

See the individual SDK documentation for detailed error handling examples.

---

Troubleshooting

403 Forbidden? Ensure your API key and AWS credentials are valid.
SignatureDoesNotMatch? Verify your AWS credentials and region settings.
Connection Timeout? Check your internet connection and retry.
Service Unavailable? Verify service endpoints are correct and accessible.

For more troubleshooting help, see:

• JavaScript SDK Documentation
• Python SDK Documentation

---

Support

For support, reach out to:

• Email: support@asoba.co
• GitHub Issues: https://github.com/AsobaCloud/platform/issues
• Documentation: https://docs.asoba.co

---

License

MIT License

---

Contributing

Contributions are welcome! Please see the individual SDK documentation for contribution guidelines:

• JavaScript SDK Contributing
• Python SDK Contributing