forecastfactor-publisher 1.0.0__tar.gz

forecastfactor_publisher-1.0.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.2
+Name: forecastfactor_publisher
+Version: 1.0.0
+Summary: A library for publishing forecast data to an API
+Author: Ricardo Teixeira
+Author-email: ricardo.teixeira@obiio.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Requires-Dist: requests
+Requires-Dist: pandas
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

forecastfactor_publisher-1.0.0/README.md

@@ -0,0 +1,299 @@
+# Forecast Factor Publisher
+
+A Python library for publishing forecast data to the Forecast Factor API. This package provides a simple interface to upload time series data, forecasts, and associated metadata to the forecast ingestion service.
+
+## Features
+
+- Upload raw time series data with metadata
+- Publish forecast data with confidence bounds
+- Include model information and performance metrics
+- Support for turning points analysis
+- Comprehensive error handling and validation
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install forecastfactor-publisher
+```
+
+### From Source
+
+```bash
+git clone <repository-url>
+cd forecastfactor_publisher
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+from forecastfactor_publisher import forecastfactor_publish
+
+# Prepare your data
+raw_data = pd.DataFrame({
+    'date': ['2023-01-01', '2023-01-02'],
+    'value': [100, 110]
+})
+
+forecast_data = pd.DataFrame({
+    'date': ['2023-02-01', '2023-02-02'],
+    'value': [120, 130]
+})
+
+forecast_bounds = pd.DataFrame({
+    'date': ['2023-02-01', '2023-02-02'],
+    'lb95': [115, 125],
+    'ub95': [125, 135]
+})
+
+forecast_residuals = pd.DataFrame({
+    'date': ['2023-01-01', '2023-01-02'],
+    'value': [0.1, -0.2]
+})
+
+# Define metadata
+turning_points = {
+    "2023-01-15": ["peak", "trough"],
+    "2023-02-01": ["peak"]
+}
+
+metadata = {
+    "source": "internal_data",
+    "description": "Monthly sales forecast"
+}
+
+model_inputs = {
+    "algorithm": "ARIMA",
+    "mae": "0.15",
+    "rmse": "0.23"
+}
+
+model_info = {
+    "parameters": ["p=1", "d=1", "q=1"],
+    "features": ["lag_1", "trend"]
+}
+
+# Optionally, you can specify a custom API endpoint:
+# result = forecastfactor_publish(..., base_url="https://your-custom-api-endpoint")
+
+# Publish to API
+result = forecastfactor_publish(
+    api_key="your_api_key_here",
+    group_name="sales_forecasts",
+    series_name="monthly_sales",
+    model_name="arima_111",
+    transformation_name="none",
+    data_frequency="monthly",
+    raw_data=raw_data,
+    forecast_data=forecast_data,
+    forecast_bounds=forecast_bounds,
+    forecast_residuals=forecast_residuals,
+    turning_points=turning_points,
+    metadata=metadata,
+    model_inputs=model_inputs,
+    model_info=model_info
+)
+
+print(result)
+```
+
+## API Reference
+
+### `forecastfactor_publish()`
+
+Posts time series data and metadata to the Forecast Factor API.
+
+#### Parameters
+
+- **api_key** (str): API key for authentication
+- **group_name** (str): The name of the group the series belongs to
+- **series_name** (str): The name of the series
+- **model_name** (str): The name of the model
+- **transformation_name** (str): The transformation applied to the original dataset (e.g., 'none', 'log')
+- **data_frequency** (str): The series data frequency (monthly, weekly, daily, etc.)
+- **raw_data** (pd.DataFrame): DataFrame with columns ['date', 'value']
+- **forecast_data** (pd.DataFrame): DataFrame with columns ['date', 'value']
+- **forecast_bounds** (pd.DataFrame): DataFrame with columns ['date', 'lb95', ..., 'ub95']
+- **forecast_residuals** (pd.DataFrame): DataFrame with columns ['date', 'value']
+- **turning_points** (Dict): Dictionary where keys are timestamps, values are lists of turning points
+- **metadata** (Dict): Additional metadata characterizing the series
+- **model_inputs** (Dict): Information about the forecasting model and performance metrics
+- **model_info** (Dict): Dictionary where keys are model parameters, values are lists of values
+- - **base_url** (str, optional): Override the default API endpoint URL. Defaults to the official endpoint.
+
+#### Returns
+
+- **Dict**: Response from the API with status and message
+
+## Development
+
+### Prerequisites
+
+- Python 3.7 or higher
+- pip
+- twine (for publishing)
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd forecastfactor_publisher
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+pip install -e .
+```
+
+## Publishing New Versions
+
+### Step 1: Update Version Number
+
+Before publishing a new version, you must update the version number in `setup.py`:
+
+```python
+# In setup.py, line 5
+version="0.1.9",  # Increment this version number
+```
+
+**Version Numbering Convention:**
+- **Major.Minor.Patch** (e.g., 1.2.3)
+- **Major**: Breaking changes
+- **Minor**: New features, backward compatible
+- **Patch**: Bug fixes, backward compatible
+
+### Step 2: Update Changelog (Optional but Recommended)
+
+Create or update a `CHANGELOG.md` file to document changes:
+
+```markdown
+# Changelog
+
+## [0.1.9] - 2024-01-15
+### Added
+- New feature X
+- Enhanced error handling
+
+### Fixed
+- Bug fix Y
+
+## [0.1.8] - 2024-01-01
+### Added
+- Initial release
+```
+
+### Step 3: Commit Changes
+
+```bash
+git add .
+git commit -m "Bump version to 0.1.9"
+git tag v0.1.9
+git push origin main
+git push origin v0.1.9
+```
+
+### Step 4: Build and Publish
+
+Use the provided release script:
+
+```bash
+# Make sure you're in the project root directory
+./release.sh
+```
+
+Or manually:
+
+```bash
+# Clean old builds
+rm -rf build dist *.egg-info
+
+# Create new build
+python3 setup.py sdist bdist_wheel
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+### Step 5: Verify Publication
+
+Check that your package is available on PyPI:
+
+```bash
+pip install --upgrade forecastfactor-publisher
+```
+
+## Configuration
+
+### PyPI Credentials
+
+Before publishing, ensure you have PyPI credentials configured:
+
+```bash
+# Create ~/.pypirc file
+[distutils]
+index-servers =
+    pypi
+
+[pypi]
+repository = https://upload.pypi.org/legacy/
+username = your_username
+password = your_password
+```
+
+Or use environment variables:
+
+```bash
+export TWINE_USERNAME=your_username
+export TWINE_PASSWORD=your_password
+```
+
+## Testing
+
+### Local Testing
+
+```bash
+# Install in development mode
+pip install -e .
+
+# Test the package
+python -c "from forecastfactor_publisher import forecastfactor_publish; print('Package imported successfully')"
+```
+
+### Test PyPI (Optional)
+
+For testing before publishing to production PyPI:
+
+```bash
+# Upload to test PyPI first
+twine upload --repository testpypi dist/*
+
+# Install from test PyPI
+pip install --index-url https://test.pypi.org/simple/ forecastfactor-publisher
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Version Already Exists**: If you get an error about the version already existing, increment the version number in `setup.py`.
+
+2. **Authentication Failed**: Ensure your PyPI credentials are correct in `~/.pypirc` or environment variables.
+
+3. **Build Errors**: Make sure all dependencies are installed and the package structure is correct.
+
+4. **Import Errors**: Verify that `__init__.py` files are present in all directories.
+
+### Getting Help
+
+If you encounter issues:
+
+1. Check the [PyPI documentation](https://packaging.python.org/)
+2. Verify your package structure matches Python packaging standards
+3. Test locally before publishing

forecastfactor_publisher-1.0.0/forecastfactor_publisher/__init__.py

@@ -0,0 +1 @@
+from .publisher import forecastfactor_publish

forecastfactor_publisher-1.0.0/forecastfactor_publisher/publisher.py

@@ -0,0 +1,80 @@
+import requests
+import pandas as pd
+from typing import Dict, Optional
+
+def forecastfactor_publish(
+    api_key: str,
+    group_name: str,
+    series_name: str,
+    model_name: str,
+    transformation_name: str,
+    data_frequency: str,
+    raw_data: pd.DataFrame,
+    forecast_data: pd.DataFrame,
+    forecast_bounds: pd.DataFrame,
+    forecast_residuals: pd.DataFrame,
+    turning_points: Dict[str, list],
+    metadata: Dict[str, str],
+    model_inputs: Dict[str, str],
+    model_info: Dict[str, list],
+    base_url: Optional[str] = None,
+):
+    """
+    Posts time series data, metadata to an API.
+ 
+    Parameters:
+        api_key (str): API key for authentication.
+        group_name (str): The name of the group the series belongs to.
+        series_name (str): The name of the series.
+        model_name (str): The name of the model.
+        transformation_name (str): The name of the transformation of the original dataset to feed the model (e.g., 'none', 'log', etc.).
+        data_frequency (str): The series data frequency (monthly, weekly, daily, etc.).
+        raw_data (pd.DataFrame): DataFrame of raw time series data with columns ['date', 'value'].
+        forecast_data (pd.DataFrame): DataFrame of forecast bounds with columns ['date', 'value'].
+        forecast_bounds (pd.DataFrame): DataFrame of forecast data with columns ['date', 'lb95', ..., 'up95'].
+        forecast_residuals (pd.DataFrame): DataFrame of forecast data with columns ['date', 'value'].
+        turning_points (Dict): Dictionary where keys are timestamps, and values are lists of turning points.
+        metadata (Dict): Additional metadata characterizing the series and input parameters.
+        model_inputs (Dict): Information about the forecasting model, including performance metrics.
+        model_info (Dict): Dictionary where keys are model parameters, and values are lists of multiple values.
+        base_url (str, optional): Override the default API endpoint URL. Defaults to None (uses the official endpoint).
+ 
+    Returns:
+        Dict: Response from the API.
+    """
+    # Validate turning_points format
+    if not isinstance(turning_points, dict) or not all(isinstance(v, list) for v in turning_points.values()):
+        return {"status": "error", "message": "Invalid format: 'turningPoints' should be a dictionary with lists as values."}
+
+    # Validate model_info format
+    if not isinstance(model_info, dict) or not all(isinstance(v, list) for v in model_info.values()):
+        return {"status": "error", "message": "Invalid format: 'modelInfo' should be a dictionary with lists as values."}
+
+    payload = {
+        "groupName": group_name,
+        "seriesName": series_name,
+        "modelName": model_name,
+        "transformationName": transformation_name,
+        "dataFrequency": data_frequency,
+        "rawData": raw_data.to_dict(orient="records"),
+        "forecastData": forecast_data.to_dict(orient="records"),
+        "forecastBounds": forecast_bounds.to_dict(orient="records"),
+        "forecastResiduals": forecast_residuals.to_dict(orient="records"),
+        "turningPoints": turning_points,
+        "metadata": metadata,
+        "modelInfo": model_info,
+        "modelInputs": model_inputs,
+    }
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json"
+    }
+
+    try:
+        url = base_url or "https://vu-forecast-ingestor.ricardofmteixeira.workers.dev"
+        response = requests.post(url, json=payload, headers=headers)
+        response.raise_for_status()  # Raise HTTPError for bad responses (4xx, 5xx)
+        return {"status": "success", "message": "Forecast data successfully uploaded."}
+    except requests.exceptions.RequestException as e:
+        return {"status": "error", "message": f"Request failed: {str(e)}"}

forecastfactor_publisher-1.0.0/forecastfactor_publisher.egg-info/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.2
+Name: forecastfactor_publisher
+Version: 1.0.0
+Summary: A library for publishing forecast data to an API
+Author: Ricardo Teixeira
+Author-email: ricardo.teixeira@obiio.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Requires-Dist: requests
+Requires-Dist: pandas
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

forecastfactor_publisher-1.0.0/forecastfactor_publisher.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+setup.py
+forecastfactor_publisher/__init__.py
+forecastfactor_publisher/publisher.py
+forecastfactor_publisher.egg-info/PKG-INFO
+forecastfactor_publisher.egg-info/SOURCES.txt
+forecastfactor_publisher.egg-info/dependency_links.txt
+forecastfactor_publisher.egg-info/requires.txt
+forecastfactor_publisher.egg-info/top_level.txt

forecastfactor_publisher-1.0.0/forecastfactor_publisher.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

forecastfactor_publisher-1.0.0/forecastfactor_publisher.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests
+pandas

forecastfactor_publisher-1.0.0/forecastfactor_publisher.egg-info/top_level.txt

@@ -0,0 +1 @@
+forecastfactor_publisher

forecastfactor_publisher-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

forecastfactor_publisher-1.0.0/setup.py

@@ -0,0 +1,20 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="forecastfactor_publisher",
+    version="1.0.0",
+    description="A library for publishing forecast data to an API",
+    author="Ricardo Teixeira",
+    author_email="ricardo.teixeira@obiio.com",
+    packages=find_packages(include=["forecastfactor_publisher*"]),
+    install_requires=[
+        "requests",
+        "pandas",
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.7",
+)