Nolano Python SDK

v1.0.0

Simple and intuitive Python SDK for the Nolano API. Built for developers who want fast integration with powerful time series forecasting capabilities.

Install from PyPI View on GitHub

Active maintenance

Latest release

## Installation Install the SDK using pip: ```bash theme={null} pip install nolano ``` Or install directly from GitHub: ```bash theme={null} pip install git+https://github.com/tejasvaidhyadev/nolano.git ``` ## Quick Start ### Initialize the Client ```python theme={null} from nolano import Nolano client = Nolano(api_key="your-api-key-here") ``` ### Basic Usage ```python theme={null} from nolano import Nolano import pandas as pd # Initialize the client client = Nolano(api_key="your_api_key_here") # Or set environment variable: NOLANO_API_KEY=your_api_key_here client = Nolano() # Verify API key (recommended) verification = client.verify_api_key() if not verification['valid']: print(f"API key issue: {verification['message']}") exit(1) print("✅ API key verified successfully!") # Prepare your time series data df = pd.DataFrame({ 'date': pd.date_range(start='2023-01-01', periods=100, freq='D'), 'sales': [100, 102, 98, 105, 110, 108, 115, 120, 125, 130, 128, 135, 140, 145, 150, 155, 160, 165, 170, 175, 180, 185, 190, 195, 200, 205, 210, 215, 220, 225, 230, 235, 240, 245, 250, 255, 260, 265, 270, 275, 280, 285, 290, 295, 300, 305, 310, 315, 320, 325, 330, 335, 340, 345, 350, 355, 360, 365, 370, 375, 380, 385, 390, 395, 400, 405, 410, 415, 420, 425, 430, 435, 440, 445, 450, 455, 460, 465, 470, 475, 480, 485, 490, 495, 500, 505, 510, 515, 520, 525, 530, 535, 540, 545, 550, 555, 560, 565, 570, 575] }) # Generate forecast forecast = client.forecast( dataset=df, target_col='sales', timestamp_col='date', forecast_horizon=30, data_frequency='Daily' ) print(f"Forecast: {forecast.median}") print(f"Lower bound: {forecast.lower_bound}") print(f"Upper bound: {forecast.upper_bound}") ``` ## API Reference ### Constructor Parameters ```python theme={null} class Nolano: def __init__( self, api_key: str = None, model_id: str = "forecast-model-1" ): """ Initialize the Nolano client. Args: api_key: Your Nolano API key (optional if NOLANO_API_KEY env var is set) model_id: Default model to use for forecasting """ ``` ### Forecast Method ```python theme={null} def forecast( self, dataset: pd.DataFrame, target_col: str, timestamp_col: str, forecast_horizon: int, data_frequency: str = "Daily", forecast_frequency: str = None, confidence: float = 0.95, model_id: str = None ) -> NolanoForecast: """ Generate time series forecasts from a pandas DataFrame. Args: dataset: pandas DataFrame with time series data target_col: Column name containing values to forecast timestamp_col: Column name containing timestamps forecast_horizon: Number of periods to forecast data_frequency: Data frequency (Daily, Hourly, Weekly, etc.) forecast_frequency: Forecast frequency (optional, defaults to data_frequency) confidence: Confidence level for prediction intervals model_id: Model to use (optional, uses default) Returns: NolanoForecast object with prediction data """ ``` ## Error Handling The SDK provides helpful error messages for common issues: ```python theme={null} # Verify API key before making requests try: result = client.verify_api_key() if not result['valid']: print(f"API key verification failed: {result['message']}") # Handle invalid API key case exit(1) print("API key verified successfully!") # Proceed with forecasting forecast = client.forecast( dataset=df, target_col='sales', timestamp_col='date', forecast_horizon=30, data_frequency='Daily' ) except ValueError as e: print(f"Parameter error: {e}") except KeyError as e: print(f"Column not found: {e}") except Exception as e: print(f"API error: {e}") ``` ## Advanced Examples ### Using Different Models ```python theme={null} # List available models models = client.list_models() for model in models: print(model) # Use a specific model forecast = client.forecast( dataset=df, target_col='sales', timestamp_col='date', forecast_horizon=30, data_frequency='Daily', model_id='forecast-model-2' # Use alternative model ) ``` ### Data Validation ```python theme={null} # Validate your data before forecasting validation = client.validate_data( dataset=df, target_col='sales', timestamp_col='date' ) if validation['valid']: print("Data is valid!") print(f"Stats: {validation['stats']}") else: print("Data issues found:") for warning in validation['warnings']: print(f"- {warning}") ``` ### Working with Forecast Results ```python theme={null} # Access forecast data forecast.forecast_timestamps # List of forecast timestamp strings forecast.median # List of median forecast values forecast.lower_bound # List of lower confidence bound values forecast.upper_bound # List of upper confidence bound values # Convert to DataFrame df = forecast.to_dataframe() # Evaluate forecast accuracy actual_values = [105, 110, 108, 115, 120] # Actual values for forecast period metrics = forecast.evaluate(actual_values) print(f"MAE: {metrics['mae']:.2f}") print(f"WAPE: {metrics['wape']:.2f}%") ``` ## Supported Frequencies The Nolano API supports the following time series frequencies: * `Seconds` - Second-level data * `Minutes` - Minute-level data * `Hours` - Hourly data * `Daily` - Daily data * `Weekly` - Weekly data * `Monthly` - Monthly data * `Quarterly` - Quarterly data * `Yearly` - Annual data ## Environment Variables For production applications, use environment variables: ```python theme={null} import os # Set your API key export NOLANO_API_KEY=your_api_key_here # In your code client = Nolano() # Will automatically use NOLANO_API_KEY environment variable ``` ## Examples Check out the examples directory in the [GitHub repository](https://github.com/tejasvaidhyadev/nolano) for complete usage examples: * `examples/verify_api_key.py` - Quick API key verification script * `examples/nolano_example.py` - Comprehensive usage examples with API verification * `examples/nolano-forecasting-example.ipynb` - Jupyter notebook tutorial ### Quick API Key Test To quickly verify your API key is working: ```python theme={null} from nolano import Nolano client = Nolano() result = client.verify_api_key() if result['valid']: print("✅ API key is valid!") else: print(f"❌ Issue: {result['message']}") ``` ## Next Steps * Visit the [GitHub repository](https://github.com/tejasvaidhyadev/nolano) for the latest updates and examples * Explore the [API Reference](/api-reference/introduction) for detailed endpoint documentation * Get support by opening an issue on [GitHub](https://github.com/tejasvaidhyadev/nolano/issues) or contacting [hello@nolano.ai](mailto:hello@nolano.ai)