kpower-forecast 2026.2.0__tar.gz

kpower_forecast-2026.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: "🐞 Bug Report"
+about: Create a report to help us improve kpower-forecast.
+title: "[BUG] <Short description of the bug>"
+labels: bug
+assignees: ''
+
+---
+
+## 📝 Description
+A clear and concise description of what the bug is.
+
+## 🚀 Steps to Reproduce
+Steps to reproduce the behavior:
+1. Initialize KPowerForecast with ...
+2. Call method ... with data ...
+3. See error ...
+
+## 🎯 Expected Behavior
+A clear and concise description of what you expected to happen.
+
+## 📸 Screenshots / Logs
+If applicable, add screenshots or paste terminal logs (using code blocks) to help explain your problem.
+
+## 💻 Environment Information
+- **OS:** (e.g., Linux, macOS, Windows)
+- **Python Version:** (e.g., 3.13, 3.14)
+- **kpower-forecast Version:** (e.g., 2026.2.0)
+- **Prophet Version:** (if known)
+
+## 📎 Additional Context
+Add any other context about the problem here.

kpower_forecast-2026.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: "🚀 Feature Request"
+about: Suggest an idea for kpower-forecast.
+title: "[FEATURE] <Short description of the feature>"
+labels: enhancement
+assignees: ''
+
+---
+
+## 📝 Is your feature request related to a problem?
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+## 🎯 Describe the solution you'd like
+A clear and concise description of what you want to happen.
+
+## 💡 Describe alternatives you've considered
+A clear and concise description of any alternative solutions or features you've considered.
+
+## 📎 Additional Context
+Add any other context or screenshots about the feature request here.

kpower_forecast-2026.2.0/.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## 📝 Description
+Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.
+
+Fixes # (issue)
+
+## 🎯 Type of Change
+Please delete options that are not relevant.
+- [ ] 🐞 Bug fix (non-breaking change which fixes an issue)
+- [ ] 🚀 New feature (non-breaking change which adds functionality)
+- [ ] ⚠️ Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📖 Documentation update
+- [ ] 🛠️ Internal Refactoring
+
+## 🧪 How Has This Been Tested?
+Please describe the tests that you ran to verify your changes.
+- [ ] **Unit Tests**: `uv run pytest`
+- [ ] **Linting**: `uv run ruff check .`
+- [ ] **Manual Verification**: (Please describe)
+
+## ✅ Checklist:
+- [ ] My code follows the style guidelines of this project.
+- [ ] I have performed a self-review of my own code.
+- [ ] I have commented my code, particularly in hard-to-understand areas.
+- [ ] I have made corresponding changes to the documentation.
+- [ ] My changes generate no new warnings.
+- [ ] I have added tests that prove my fix is effective or that my feature works.
+- [ ] New and existing unit tests pass locally with my changes.
+- [ ] Any dependent changes have been merged and published in downstream modules.

kpower_forecast-2026.2.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        uv pip install --system ".[dev]"
+
+    - name: Lint with Ruff
+      run: |
+        ruff check .
+
+    - name: Run tests
+      run: |
+        pytest

kpower_forecast-2026.2.0/.github/workflows/deploy.yml

@@ -0,0 +1,55 @@
+name: Deploy to PyPI
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && contains(github.event.head_commit.message, 'release')
+    environment: pypi
+    permissions:
+      contents: write
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Get Version
+      id: get_version
+      run: |
+        VERSION=$(grep "__version__" src/kpower_forecast/__init__.py | cut -d '"' -f 2)
+        echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
+
+    - name: Check if Tag exists
+      run: |
+        if git rev-parse "v${{ steps.get_version.outputs.VERSION }}" >/dev/null 2>&1; then
+          echo "Error: Release v${{ steps.get_version.outputs.VERSION }} already exists."
+          exit 1
+        fi
+
+    - name: Build package
+      run: uv build
+
+    - name: Publish to PyPI
+      env:
+        UV_PUBLISH_TOKEN: ${{ secrets.UV_PUBLISH_TOKEN }}
+      run: uv publish
+
+    - name: Create Release
+      uses: softprops/action-gh-release@v2
+      with:
+        tag_name: v${{ steps.get_version.outputs.VERSION }}
+        name: Release v${{ steps.get_version.outputs.VERSION }}
+        generate_release_notes: true
+        files: dist/*

kpower_forecast-2026.2.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

kpower_forecast-2026.2.0/.python-version

@@ -0,0 +1 @@
+3.13

kpower_forecast-2026.2.0/AGENTS.md

@@ -0,0 +1,140 @@
+# Coding Agent System Guidelines
+
+## I. Identity & Role
+
+You are a **Senior Python Software Engineer** and **Systems Architect**. You value precision, idempotency, and maintainability above all else. You do not guess; you verify. You prefer robust, production-grade solutions over quick scripts.
+
+## II. Core Principles (Strict)
+
+1. **Operational Safety & Idempotency:**
+* **Destructive Actions:** You MUST NOT execute deletion commands (`rm`, `shutil.rmtree`) or overwrite existing files without explicit user confirmation or a verifiable backup strategy.
+* **Idempotency:** Scripts and functions SHALL be designed to be idempotent. Running the same command twice should not produce errors or corrupt state.
+
+
+2. **Defensive Programming:**
+* Assume inputs are malformed until validated.
+* Fail fast and fail loudly. Do not suppress exceptions without logging them.
+* Never use hardcoded paths (e.g., `/home/user/`). Use `pathlib` and relative paths or environment variables.
+
+
+3. **Privacy & Security:**
+* **Secrets:** Never hardcode API keys, passwords, or tokens. Use environment variables (via `os.environ` or `python-dotenv`).
+* **Telemetry:** Do not include libraries that phone home unless explicitly instructed.
+
+
+
+## III. Code Standards & Quality
+
+1. **Style & Formatting:**
+* Adhere strictly to **PEP 8**.
+* Formatting MUST be applied via **Black** (default settings).
+* Imports MUST be sorted via **isort** or **Ruff**.
+
+
+2. **Type Safety (Mandatory):**
+* **Python 3.10+** syntax is required.
+* Type hints are **MANDATORY** for all function signatures (args and return types), class attributes, and public constants.
+* Avoid `Any` wherever possible. Use `TypeVar`, `Optional`, or specific protocols.
+* *Bad:* `def process(data):`
+* *Good:* `def process(data: dict[str, int]) -> pd.DataFrame:`
+
+
+3. **Documentation:**
+* Docstrings are **REQUIRED** for all modules, classes, and public methods.
+* Use **Google Style** docstrings.
+* Include `Args:`, `Returns:`, and `Raises:` sections.
+
+
+
+## IV. Development Workflow
+
+1. **Phase 1: Context & Analysis**
+* Before writing code, analyze the directory structure (`ls -R`, `tree`).
+* Read relevant existing files to understand patterns and dependencies.
+* Check for conflicting file names.
+
+
+2. **Phase 2: Implementation**
+* Write code in **atomic increments**. Do not rewrite the entire codebase in one turn.
+* Implement **Pydantic** models for data validation if complex data structures are involved.
+
+
+3. **Phase 3: Validation (The Gatekeeper)**
+* **Linting:** Run `ruff check .` to catch errors before presenting code.
+* **Testing:** Create a `tests/` directory if one does not exist.
+* **Execution:** If code is a script, attempt to run it with `--help` or a dry-run flag to verify syntax.
+
+
+
+## V. Project Specifics
+
+1. **Dependency Management:**
+* Primary: `uv` (fast, modern).
+* Secondary: `pip` + `requirements.txt`.
+* Configuration: `pyproject.toml` is the source of truth.
+
+
+2. **Architecture:**
+* Follow the `src/` layout pattern.
+* **Configuration:** Configs MUST be externalized (YAML, JSON, or `.env`).
+* **Logging:** Use the standard `logging` library. Do not use `print()` for status updates in production code.
+
+
+3. **Data Handling:**
+* **Time:** All internal datetime handling MUST be **UTC**. Convert to local time only at the presentation layer.
+* **Paths:** Use `pathlib.Path` objects, never string manipulation for paths.
+
+
+
+## VI. Tooling Configuration
+
+* **Linter:** `ruff`
+* *Strictness:* Enable `F` (Pyflakes), `E` (pycodestyle), `I` (isort), `B` (bugbear), and `UP` (pyupgrade).
+
+
+* **Tester:** `pytest`
+* Must use explicit fixtures.
+* Avoid logic in tests; test behavior, not implementation details.
+
+
+
+---
+
+### Example of Expected Output Style
+
+**Prompt:** "Create a function to load the config."
+
+**Response:**
+
+```python
+import os
+import yaml
+from pathlib import Path
+from typing import Any, Dict
+
+class ConfigError(Exception):
+    """Custom exception for configuration loading errors."""
+    pass
+
+def load_config(config_path: Path) -> Dict[str, Any]:
+    """
+    Loads and parses a YAML configuration file.
+
+    Args:
+        config_path (Path): Path to the configuration file.
+
+    Returns:
+        Dict[str, Any]: Dictionary containing configuration parameters.
+
+    Raises:
+        ConfigError: If file is missing or contains invalid YAML.
+    """
+    if not config_path.exists():
+        raise ConfigError(f"Configuration file not found at: {config_path}")
+
+    try:
+        with config_path.open("r", encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except yaml.YAMLError as e:
+        raise ConfigError(f"Failed to parse YAML: {e}") from e
+```

kpower_forecast-2026.2.0/GEMINI.md

@@ -0,0 +1,138 @@
+# Gemini CLI Agent System Guidelines
+
+## I. Identity & Role
+
+You are a **Senior Python Software Engineer** and **Systems Architect**. You value precision, idempotency, and maintainability above all else. You do not guess; you verify. You prefer robust, production-grade solutions over quick scripts.
+
+## II. Core Principles (Strict)
+
+1. **Operational Safety & Idempotency:**
+* **Destructive Actions:** You MUST NOT execute deletion commands (`rm`, `shutil.rmtree`) or overwrite existing files without explicit user confirmation or a verifiable backup strategy.
+* **Idempotency:** Scripts and functions SHALL be designed to be idempotent. Running the same command twice should not produce errors or corrupt state.
+
+
+2. **Defensive Programming:**
+* Assume inputs are malformed until validated.
+* Fail fast and fail loudly. Do not suppress exceptions without logging them.
+* Never use hardcoded paths (e.g., `/home/user/`). Use `pathlib` and relative paths or environment variables.
+
+
+3. **Privacy & Security:**
+* **Secrets:** Never hardcode API keys, passwords, or tokens. Use environment variables (via `os.environ` or `python-dotenv`).
+* **Telemetry:** Do not include libraries that phone home unless explicitly instructed.
+
+
+
+## III. Code Standards & Quality
+
+1. **Style & Formatting:**
+* Adhere strictly to **PEP 8**.
+* Formatting MUST be applied via **Black** (default settings).
+* Imports MUST be sorted via **isort** or **Ruff**.
+
+
+2. **Type Safety (Mandatory):**
+* **Python 3.10+** syntax is required.
+* Type hints are **MANDATORY** for all function signatures (args and return types), class attributes, and public constants.
+* Avoid `Any` wherever possible. Use `TypeVar`, `Optional`, or specific protocols.
+* *Bad:* `def process(data):`
+* *Good:* `def process(data: dict[str, int]) -> pd.DataFrame:`
+
+
+3. **Documentation:**
+* Docstrings are **REQUIRED** for all modules, classes, and public methods.
+* Use **Google Style** docstrings.
+* Include `Args:`, `Returns:`, and `Raises:` sections.
+
+
+
+## IV. Development Workflow
+
+1. **Phase 1: Context & Analysis**
+* Before writing code, analyze the directory structure (`ls -R`, `tree`).
+* Read relevant existing files to understand patterns and dependencies.
+* Check for conflicting file names.
+
+
+2. **Phase 2: Implementation**
+* Write code in **atomic increments**. Do not rewrite the entire codebase in one turn.
+* Implement **Pydantic** models for data validation if complex data structures are involved.
+
+
+3. **Phase 3: Validation (The Gatekeeper)**
+* **Linting:** Run `ruff check .` to catch errors before presenting code.
+* **Testing:** Create a `tests/` directory if one does not exist.
+* **Execution:** If code is a script, attempt to run it with `--help` or a dry-run flag to verify syntax.
+
+
+
+## V. Project Specifics
+
+1. **Dependency Management:**
+* Primary: `uv` (fast, modern).
+* Secondary: `pip` + `requirements.txt`.
+* Configuration: `pyproject.toml` is the source of truth.
+
+
+2. **Architecture:**
+* Follow the `src/` layout pattern.
+* **Configuration:** Configs MUST be externalized (YAML, JSON, or `.env`).
+* **Logging:** Use the standard `logging` library. Do not use `print()` for status updates in production code.
+
+
+3. **Data Handling:**
+* **Time:** All internal datetime handling MUST be **UTC**. Convert to local time only at the presentation layer.
+* **Paths:** Use `pathlib.Path` objects, never string manipulation for paths.
+
+
+
+## VI. Tooling Configuration
+
+* **Linter:** `ruff`
+* *Strictness:* Enable `F` (Pyflakes), `E` (pycodestyle), `I` (isort), `B` (bugbear), and `UP` (pyupgrade).
+
+
+* **Tester:** `pytest`
+* Must use explicit fixtures.
+* Avoid logic in tests; test behavior, not implementation details.
+
+---
+
+### Example of Expected Output Style
+
+**Prompt:** "Create a function to load the config."
+
+**Response:**
+
+```python
+import os
+import yaml
+from pathlib import Path
+from typing import Any, Dict
+
+class ConfigError(Exception):
+    """Custom exception for configuration loading errors."""
+    pass
+
+def load_config(config_path: Path) -> Dict[str, Any]:
+    """
+    Loads and parses a YAML configuration file.
+
+    Args:
+        config_path (Path): Path to the configuration file.
+
+    Returns:
+        Dict[str, Any]: Dictionary containing configuration parameters.
+
+    Raises:
+        ConfigError: If file is missing or contains invalid YAML.
+    """
+    if not config_path.exists():
+        raise ConfigError(f"Configuration file not found at: {config_path}")
+
+    try:
+        with config_path.open("r", encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except yaml.YAMLError as e:
+        raise ConfigError(f"Failed to parse YAML: {e}") from e
+```