site-calc-investment 1.2.0__tar.gz

site_calc_investment-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.10', '3.11', '3.12']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v2
+
+    - name: Install dependencies
+      run: |
+        uv venv
+        uv pip install -e ".[dev]"
+
+    - name: Lint with ruff
+      run: |
+        uv run ruff check .
+
+    - name: Check formatting with ruff
+      run: |
+        uv run ruff format --check .
+
+    - name: Type check with mypy
+      run: |
+        uv run mypy site_calc_investment/
+
+    - name: Run tests with pytest
+      run: |
+        uv run pytest tests/ --cov=site_calc_investment --cov-report=xml --cov-report=term
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install build dependencies
+      run: |
+        pip install build
+
+    - name: Build package
+      run: |
+        python -m build
+
+    - name: Check distribution
+      run: |
+        pip install twine
+        twine check dist/*

site_calc_investment-1.2.0/.github/workflows/publish.yml

@@ -0,0 +1,107 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Publish target'
+        required: true
+        default: 'testpypi'
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install build dependencies
+      run: pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check distribution
+      run: twine check dist/*
+
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v2
+
+    - name: Install dependencies
+      run: |
+        uv venv
+        uv pip install -e ".[dev]"
+
+    - name: Run tests
+      run: uv run pytest tests/ -v -m "not production"
+
+  publish-testpypi:
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi'
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/site-calc-investment/
+    permissions:
+      id-token: write
+
+    steps:
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+    - name: Publish to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        verbose: true
+
+  publish-pypi:
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'pypi')
+    environment:
+      name: pypi
+      url: https://pypi.org/project/site-calc-investment/
+    permissions:
+      id-token: write
+
+    steps:
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        verbose: true

site_calc_investment-1.2.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Distribution
+*.whl

site_calc_investment-1.2.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to the Site-Calc Investment Client will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2026-02-03
+
+### Changed
+- **Repository URLs**: Updated package metadata to point to official GitHub repository
+- **CI/CD**: Added automatic PyPI publishing workflow on release tags
+
+### Fixed
+- Minor documentation improvements and URL corrections
+
+---
+
+## [1.1.0] - 2026-02-01
+
+### Added
+- **SOC Anchoring**: New optional fields `soc_anchor_interval_hours` and `soc_anchor_target`
+  in `BatteryProperties` for improved long-term battery optimization
+- **Version Validation**: Client automatically checks server version compatibility and warns
+  if MAJOR.MINOR versions don't match
+- **Timeout Control**: Jobs can now specify custom timeout limits
+
+### Changed
+- **Default Solver**: Changed from CBC to HiGHS for 30-40% faster optimization times
+- Results are identical; no code changes required
+
+### Notes
+- All v1.0.x client code continues to work without modification
+- SOC anchoring is opt-in via new optional fields
+- Version warnings are informational only and don't affect functionality
+
+---
+
+## [1.0.0] - 2024-12-15
+
+### Added
+- Initial release of Site-Calc Investment Client
+- Complete Pydantic V2 models for investment planning requests and responses
+- 10 device types: Battery, CHP, HeatAccumulator, Photovoltaic, ElectricityDemand, HeatDemand, ElectricityImport, ElectricityExport, GasImport, HeatExport
+- API client with automatic retry logic and exponential backoff
+- Financial analysis functions: NPV, IRR (Newton-Raphson), payback period
+- Scenario comparison utilities for evaluating multiple investment options
+- Support for 10-year hourly optimization (up to 100,000 intervals)
+- Comprehensive test suite with 120 tests and 93% coverage
+- Three complete examples demonstrating capacity planning, scenario comparison, and financial analysis
+
+### Features
+- **Investment-Specific**: Designed exclusively for long-term capacity planning and ROI analysis
+- **No Ancillary Services**: Investment client does not support ANS optimization (reserved for operational client)
+- **1-Hour Resolution Only**: Optimized for multi-year planning horizons
+- **Automatic Binary Relaxation**: CHP binary constraints automatically relaxed for tractability
+- **Financial Metrics**: Built-in NPV, IRR, and payback period calculations
+- **Type-Safe**: Full type hints with Pydantic V2 validation
+- **Well-Tested**: 120 tests covering all major functionality with mocked HTTP responses
+
+### Notes
+- Requires API key with `inv_` prefix
+- Maximum 100,000 intervals (~11 years at 1-hour resolution)
+- Default timeout: 3600 seconds (1 hour)
+- Python 3.10+ required

site_calc_investment-1.2.0/CONTRIBUTING.md

@@ -0,0 +1,213 @@
+# Contributing to Site-Calc Investment Client
+
+Thank you for considering contributing to the Site-Calc Investment Client! This document provides guidelines for contributing to the project.
+
+## Development Setup
+
+### Prerequisites
+- Python 3.10 or higher
+- `uv` package manager (recommended) or `pip`
+
+### Setup Steps
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/site-calc/investment-client.git
+   cd investment-client
+   ```
+
+2. **Create virtual environment**
+   ```bash
+   uv venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+3. **Install dependencies**
+   ```bash
+   uv pip install -e ".[dev]"
+   ```
+
+## Development Workflow
+
+### Running Tests
+
+Run all tests:
+```bash
+pytest tests/
+```
+
+Run with coverage:
+```bash
+pytest tests/ --cov=site_calc_investment --cov-report=html
+```
+
+Run specific test file:
+```bash
+pytest tests/test_financial_analysis.py -v
+```
+
+### Code Style
+
+We use `ruff` for linting and formatting:
+
+```bash
+# Check for issues
+ruff check .
+
+# Auto-fix issues
+ruff check --fix .
+
+# Format code
+ruff format .
+```
+
+### Type Checking
+
+We use `mypy` for static type checking:
+
+```bash
+mypy site_calc_investment/
+```
+
+## Code Standards
+
+### Style Guidelines
+- **Line length**: 120 characters maximum
+- **Type hints**: Required for all functions and methods
+- **Docstrings**: Use reStructuredText format (PEP 257)
+- **Imports**: Organized with `ruff` (stdlib, third-party, local)
+
+### Testing Requirements
+- All new features must include tests
+- Maintain or improve code coverage (currently 93%)
+- Use pytest fixtures for common test data
+- Mock HTTP requests (no real API calls in tests)
+
+### Commit Messages
+Follow conventional commits format:
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation changes
+- `test:` Test additions or changes
+- `refactor:` Code refactoring
+- `chore:` Maintenance tasks
+
+Example:
+```
+feat: Add support for wind turbine devices
+
+- Add WindTurbine device model
+- Add generation profile validation
+- Add tests for wind turbine
+```
+
+## Test-Driven Development (TDD)
+
+We follow TDD methodology:
+
+1. **Write tests first** - Define the interface and expected behavior
+2. **Implement code** - Make tests pass
+3. **Refactor** - Improve code quality while keeping tests green
+
+Example workflow:
+```python
+# 1. Write test (tests/test_new_feature.py)
+def test_wind_turbine_creation():
+    turbine = WindTurbine(
+        name="WT1",
+        properties=WindTurbineProperties(capacity=5.0)
+    )
+    assert turbine.name == "WT1"
+
+# 2. Run test (should fail)
+pytest tests/test_new_feature.py::test_wind_turbine_creation
+
+# 3. Implement feature (site_calc_investment/models/devices.py)
+class WindTurbine(BaseModel):
+    name: str
+    properties: WindTurbineProperties
+
+# 4. Run test again (should pass)
+pytest tests/test_new_feature.py::test_wind_turbine_creation
+```
+
+## Pull Request Process
+
+1. **Create a branch**
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+2. **Make your changes**
+   - Follow TDD workflow
+   - Add/update tests
+   - Update documentation if needed
+
+3. **Run quality checks**
+   ```bash
+   ruff check --fix .
+   ruff format .
+   mypy site_calc_investment/
+   pytest tests/
+   ```
+
+4. **Commit your changes**
+   ```bash
+   git add .
+   git commit -m "feat: Add your feature description"
+   ```
+
+5. **Push and create PR**
+   ```bash
+   git push origin feat/your-feature-name
+   ```
+
+6. **PR Checklist**
+   - [ ] Tests pass locally
+   - [ ] Code coverage maintained or improved
+   - [ ] Type hints added for all new code
+   - [ ] Docstrings added for public functions/classes
+   - [ ] CHANGELOG.md updated
+   - [ ] No breaking changes (or clearly documented)
+
+## Project Structure
+
+```
+client-investment/
+├── site_calc_investment/       # Main package
+│   ├── models/                 # Pydantic models
+│   │   ├── common.py          # TimeSpan, Resolution, Location
+│   │   ├── devices.py         # Device models
+│   │   ├── requests.py        # Request models
+│   │   └── responses.py       # Response models
+│   ├── api/                   # API client
+│   │   └── client.py          # InvestmentClient
+│   ├── analysis/              # Financial analysis
+│   │   ├── financial.py       # NPV, IRR, payback
+│   │   └── comparison.py      # Scenario comparison
+│   └── exceptions.py          # Custom exceptions
+├── tests/                     # Test suite
+│   ├── conftest.py           # Pytest fixtures
+│   ├── test_*.py             # Test modules
+├── examples/                  # Usage examples
+└── docs/                      # Documentation (if added)
+```
+
+## Adding New Device Types
+
+If adding a new device type:
+
+1. **Define model** in `site_calc_investment/models/devices.py`
+2. **Add tests** in `tests/test_device_models.py`
+3. **Update examples** if relevant
+4. **Update CHANGELOG.md**
+
+## Questions or Issues?
+
+- **Bug reports**: Open an issue with reproduction steps
+- **Feature requests**: Open an issue describing the use case
+- **Questions**: Check README.md first, then open a discussion
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

site_calc_investment-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Site-Calc Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.