eo-processor 0.4.0__tar.gz

eo_processor-0.4.0/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: bnjam
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

eo_processor-0.4.0/.github/copilot-instructions.md

@@ -0,0 +1,322 @@
+# GitHub Copilot / AI Agent Instructions
+
+This document defines how AI code assistants (e.g., GitHub Copilot, autonomous agents) should behave when generating, modifying, or proposing code in the `eo-processor` repository. It complements `AGENTS.md` and focuses on inline assistance, code completion, and automated changes.
+
+---
+
+## 1. Scope of Assistance
+
+AI assistance MAY:
+- Suggest Rust functions implementing EO spectral indices and numeric transforms
+- Provide Python integration layers (imports, type stubs, tests)
+- Improve performance in pure Rust (keeping safety)
+- Add unit tests and benchmarks (lightweight)
+- Refactor for clarity without breaking public APIs
+- Maintain or regenerate `coverage-badge.svg` via existing script logic
+- Propose documentation updates (README, QUICKSTART)
+- Add missing type hints, docstrings, or comments
+
+AI assistance MUST NOT:
+- Introduce external services, network calls, or file I/O into the core computational path
+- Add unchecked dependencies without justification
+- Use `unsafe` Rust blocks (unless explicitly approved and documented)
+- Commit partial implementations (functions without tests or exports)
+- Generate large boilerplate unrelated to repository goals
+- Fabricate data, benchmarks, or security claims
+
+---
+
+## 2. Repository Structure Awareness
+
+Key areas for code suggestions:
+- `src/` – Rust source (PyO3 module functions)
+- `python/eo_processor/` – Python package exports and type stubs
+- `tests/` – Python tests (add test_*.py files here)
+- `scripts/` – Utility scripts (badge generation, etc.)
+- `pyproject.toml` – Metadata, versioning, dependencies
+- `tox.ini` – Test environments, coverage configuration
+
+Do not invent directories. Use existing patterns (e.g., 1D, 2D variants where appropriate).
+
+---
+
+## 3. Coding Conventions
+
+Rust:
+- Format with `cargo fmt`
+- Zero clippy warnings (`cargo clippy -- -D warnings`)
+- Prefer slice/array operations over explicit loops where clear
+- Avoid `unwrap()`—use explicit error handling or safe assumptions
+- Enforce shape matching before arithmetic when combining arrays
+
+Python:
+- Export new functions in `__init__.py`
+- Add type stubs in `__init__.pyi`
+- Keep tests deterministic (no random seeds unless specified)
+- Use NumPy array assertions (`np.allclose`, `np.isfinite`)
+- Prefer descriptive test names (`test_<function>_<case>`)
+
+Documentation:
+- Add formulas for new spectral indices
+- Include minimal runnable examples
+- Maintain consistency with existing README function lists
+
+---
+
+## 4. Performance Guidance
+
+When suggesting optimizations:
+- Preserve numerical correctness (tolerance ≤ 1e-9)
+- Prefer vectorized ndarray operations in Rust
+- Avoid micro-optimizations that reduce readability unless >20% speed gain
+- Suggest benchmarking snippets only if relevant
+
+Benchmarks must be realistic (large arrays, e.g., 5000 x 5000).
+
+---
+
+## 5. Safe Rust Patterns
+
+DO:
+- Use `ndarray` arithmetic operations
+- Validate shapes early
+- Use small constants like `1e-10` for numeric stability
+
+DON'T:
+- Introduce `unsafe`
+- Allocate excessively in tight loops
+- Return inconsistent array dimensions
+- Silently swallow errors
+
+---
+
+## 6. Adding New Functionality (Checklist)
+
+For each new function:
+1. Implement in Rust (`src/lib.rs`)
+2. Register with `#[pyfunction]` and add to `#[pymodule]`
+3. Export in `python/eo_processor/__init__.py`
+4. Add type stub in `python/eo_processor/__init__.pyi`
+5. Create test file in `tests/`
+6. Update README function list and examples
+7. Run full pre-commit checklist (Section 8)
+8. Consider version bump (patch/minor/major)
+
+---
+
+## 7. Versioning Rules (SemVer)
+
+- Patch: Bug fixes / internal refactors
+- Minor: New functions (backward-compatible)
+- Major: Breaking changes (signature changes, removals)
+
+AI agents should tag suggestions that require version bumps.
+
+---
+
+## 8. Pre-Commit / Pre-Push Checklist (MANDATORY)
+
+Before generating or validating a commit, ensure:
+- [ ] Rust code formatted (`cargo fmt`)
+- [ ] No clippy warnings
+- [ ] `cargo check --lib` succeeds (or `cargo test` if tests exist)
+- [ ] Python style/lint: ruff passes
+- [ ] `mypy python/eo_processor` has no new errors
+- [ ] Tests pass (`tox` or individual env)
+- [ ] Coverage updated if logic changed (`tox -e coverage`)
+- [ ] Badge regenerated if coverage changed:
+      `python scripts/generate_coverage_badge.py coverage.xml coverage-badge.svg`
+- [ ] README / docs updated for public API changes
+- [ ] Version updated if needed
+- [ ] No secrets or unintended large binaries staged
+- [ ] Commit message follows convention (Section 9)
+- [ ] Performance impact evaluated (if relevant)
+
+If any step fails, DO NOT propose commit.
+
+---
+
+## 9. Commit Message Pattern
+
+Format:
+```
+<type>(scope): concise summary
+
+Optional body explaining rationale, benchmarks, or docs
+Refs: issue numbers, benchmarks, links
+```
+
+Types:
+- feat
+- fix
+- perf
+- docs
+- test
+- chore
+- build
+- ci
+
+Example:
+```
+feat(indices): add Enhanced Vegetation Index (EVI)
+
+Implements EVI with 1D/2D variants. Adds tests and docs.
+Benchmarked at 1.28x speed vs NumPy baseline.
+Refs: #45
+```
+
+---
+
+## 10. When NOT to Suggest Code
+
+AI agents should refrain if:
+- Required context (file content) is missing
+- Task involves strategic redesign (defer to human proposal)
+- Operation would introduce external network access
+- Performance trade-offs cannot be reasonably estimated
+- Security posture could be affected (e.g., unsafe / dynamic execution)
+
+Instead, propose clarification questions or planning steps.
+
+---
+
+## 11. Testing Guidance
+
+Minimal test template:
+```python
+def test_new_index_basic():
+    import numpy as np
+    from eo_processor import new_index
+    a = np.array([0.6, 0.7, 0.8])
+    b = np.array([0.2, 0.3, 0.4])
+    out = new_index(a, b)
+    assert out.shape == a.shape
+    assert np.isfinite(out).all()
+```
+
+Edge case tests:
+- Zeros / near-zero denominators
+- Matching shape enforcement
+- Large arrays performance (sanity only; avoid huge runtime)
+
+---
+
+## 12. Coverage Badge Regeneration
+
+Trigger conditions:
+- Python code modified
+- Tests added/removed
+- Coverage threshold changes
+
+Sequence:
+1. `tox -e coverage`
+2. Confirm `coverage.xml` exists
+3. Run script
+4. Verify SVG text alignment locally
+5. Stage updated badge
+
+---
+
+## 13. Documentation Updates
+
+For new features:
+- Add function signature to README
+- Add usage snippet
+- Provide formula
+- Mention typical EO use-case
+- Optional: scientific reference (if standard index)
+
+---
+
+## 14. Performance Claim Template
+
+If suggesting optimization:
+```
+Benchmark:
+Array size: 5000 x 5000
+Old: 1.42s
+New: 1.05s
+Speedup: 1.35x
+
+Methodology:
+Single run, warm cache discarded
+Python timing via time.time()
+```
+
+---
+
+## 15. Do / Don’t Summary
+
+DO:
+- Maintain parity between Rust and Python exports
+- Use explicit naming (`index_1d`, `index_2d`)
+- Keep code minimal and safe
+- Suggest incremental changes
+
+DON’T:
+- Combine unrelated changes in one diff
+- Introduce unstable dependencies
+- Modify unrelated files casually
+- Reduce test coverage
+
+---
+
+## 16. Rollback Strategy (If Committed Mistake Detected)
+
+1. Reset local changes: `git reset --hard HEAD~1` (if safe)
+2. Revert remote commit: create a `revert:` commit
+3. Re-run full checklist
+4. Open issue documenting root cause if systemic
+
+---
+
+## 17. Example Rust Function Pattern (Reusable)
+
+```rust
+#[pyfunction]
+fn example_index<'py>(
+    py: Python<'py>,
+    a: PyReadonlyArray2<f64>,
+    b: PyReadonlyArray2<f64>,
+) -> PyResult<&'py PyArray2<f64>> {
+    let a_arr = a.as_array();
+    let b_arr = b.as_array();
+    assert_eq!(a_arr.shape(), b_arr.shape(), "Input arrays must have matching shapes");
+    let numerator = &a_arr - &b_arr;
+    let denominator = &a_arr + &b_arr + 1e-10;
+    let out = numerator / denominator;
+    Ok(out.into_pyarray(py))
+}
+```
+
+---
+
+## 18. Red Flags (Require Human Review)
+
+- Proposal to add GPU or distributed code paths
+- Changes to module initialization signature
+- Introduction of concurrency primitives (threads / async)
+- Large memory allocations (> several GB)
+- Breaking API removals
+
+---
+
+## 19. Optional Extensions (Future Suggestions)
+
+Agents may propose (but not implement without approval):
+- Additional indices: EVI, SAVI, NBR, GCI
+- Sliding window operations
+- Batch spectral composite builder
+- Multi-threaded internal tiling (must justify)
+
+---
+
+## 20. Final Rule
+
+If uncertain about spec or impact → STOP and generate a structured clarification prompt rather than guessing.
+
+Quality > speed. Safety > novelty.
+
+---
+
+End of GitHub Copilot / AI Agent Instructions.

eo_processor-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,98 @@
+name: CI
+
+# --- TRIGGER: Runs on Pull Requests ---
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+  RUN_BENCHMARKS: false
+
+jobs:
+  test:
+    name: Tests via tox (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # Needed for coverage badge/artifacts
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # --- SETUP ---
+      - name: Install Rust toolchain
+        # Required for the 'clippy' environment and maturin builds
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv and tools
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install tox and plugins
+        # Install tox and the tox-gh-actions plugin into the base environment
+        run: uv pip install --system tox tox-gh-actions
+
+      # --- LINT & CLIPPY STEPS (Run once on 3.11) ---
+      # Running static checks only on one version to save time
+      - name: 🔎 Run Lint (tox -e lint)
+        if: matrix.python-version == '3.11'
+        run: tox -e lint
+
+      - name: 🔎 Run Rust Checks (tox -e clippy)
+        if: matrix.python-version == '3.11'
+        run: tox -e clippy
+
+      # --- CORE TESTS STEP (Run on both 3.11 and 3.12) ---
+      - name: 🧪 Run Tests (tox -e py${{ matrix.python-version }})
+        id: tests_step
+        # Runs 'maturin develop' and 'pytest -q'
+        run: tox -e py${{ matrix.python-version }}
+
+      # --- COVERAGE & BADGE STEPS (Run once on 3.12) ---
+      - name: 📊 Run Coverage Threshold Check
+        if: matrix.python-version == '3.12'
+        id: coverage_step
+        # This assumes the tox 'coverage' environment produces a coverage.xml file in the repository root.
+        run: |
+          set -euo pipefail
+          tox -e coverage
+          python scripts/generate_coverage_badge.py coverage.xml coverage-badge.svg || echo "Badge generation skipped"
+
+      - name: 🚀 Run Example Scripts (Smoke Tests)
+        if: matrix.python-version == '3.12'
+        run: |
+          set -e
+          echo "Running smoke-test examples..."
+          uv run python examples/basic_usage.py
+          uv run python examples/temporal_operations.py
+          uv run python examples/spatial_distances.py
+          # Optional dependencies may not be installed in minimal CI; tolerate failure.
+          uv run python examples/xarray_dask_usage.py || echo "xarray/dask example skipped (optional deps missing)"
+          uv run python examples/map_blocks.py || echo "map_blocks example skipped (optional deps missing)"
+
+      - name: 🏁 Benchmark (Optional)
+        if: matrix.python-version == '3.12' && env.RUN_BENCHMARKS == 'true'
+        run: |
+          set -e
+          echo "Running benchmark suite (with NumPy baseline comparisons)..."
+          uv run python scripts/benchmark.py --group all --height 1024 --width 1024 --time 8 --points-a 500 --points-b 500 --point-dim 8 --loops 2 --warmups 1 --compare-numpy --json-out benchmark-results.json --quiet
+          echo "Benchmark JSON generated: benchmark-results.json"
+      - name: 📦 Upload Benchmark Artifact
+        if: matrix.python-version == '3.12' && env.RUN_BENCHMARKS == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: benchmark-results.json
+          if-no-files-found: warn
+          retention-days: 7

eo_processor-0.4.0/.github/workflows/jules-autofix.yml

@@ -0,0 +1,130 @@
+name: 🤖 Jules Autofix
+
+# This workflow runs only when the main CI workflow completes and fails on a pull_request
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.workflow_run.head_sha }}
+  cancel-in-progress: true
+
+jobs:
+  jules_autofix:
+    name: Run Jules Fix Session
+    # Use a faster, lighter runner since it's mostly Python scripting
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write # Needed to comment on the PR
+      contents: read # Needed to checkout code
+      actions: read # Needed to list/download artifacts
+
+    # Only run if the CI failed AND it was triggered by a pull request
+    if: |
+      github.event.workflow_run.conclusion == 'failure' &&
+      github.event.workflow_run.event == 'pull_request'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # Use the commit SHA from the failed run to ensure context is correct
+          ref: ${{ github.event.workflow_run.head_sha }}
+
+      - name: Get PR Number and Author
+        id: get_pr
+        uses: actions/github-script@v6
+        with:
+          script: |
+            // Find the PR associated with the commit SHA from the failed workflow run
+            const { data: pullRequest } = await github.rest.pulls.list({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              head: context.repo.owner + ':' + context.event.workflow_run.head_branch,
+            });
+            if (pullRequest.length === 0) {
+              core.info('Could not find corresponding pull request. Skipping.');
+              return;
+            }
+            core.setOutput('pr_number', pullRequest[0].number);
+            core.setOutput('pr_author', pullRequest[0].user.login);
+            core.setOutput('pr_repo', pullRequest[0].base.repo.full_name);
+
+      - name: Check if Author is "bnjam" (or other approved user)
+        # This conditional check ensures the script only runs for approved users, matching the original logic
+        if: ${{ steps.get_pr.outputs.pr_author != 'bnjam' }}
+        run: |
+          echo "Skipping Jules session. PR author is not 'bnjam'."
+          exit 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # --- Download Artifacts from failed run ---
+      - name: 📥 Find and Download Failure Context
+        uses: actions/github-script@v6
+        id: download_artifact
+        with:
+          script: |
+            const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: context.event.workflow_run.id,
+            });
+
+            // Find the artifact uploaded by the failing test job (e.g., failure-context-3.12)
+            const matchArtifact = artifacts.data.artifacts.find(artifact =>
+              artifact.name.startsWith('failure-context-')
+            );
+
+            if (matchArtifact) {
+              const download = await github.rest.actions.downloadArtifact({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                artifact_id: matchArtifact.id,
+                archive_format: 'zip',
+              });
+
+              const fs = require('fs');
+              const unzip = require('unzip-stream');
+
+              // This downloads the zip, extracts it, and makes the error message available
+              fs.writeFileSync('failure-context.zip', Buffer.from(download.data));
+              fs.mkdirSync('failure-context');
+              const readStream = fs.createReadStream('failure-context.zip');
+              const extractStream = unzip.Extract({ path: 'failure-context' });
+
+              await new Promise((resolve, reject) => {
+                  extractStream.on('close', resolve);
+                  extractStream.on('error', reject);
+                  readStream.pipe(extractStream);
+              });
+
+              console.log('Successfully downloaded and extracted failure context.');
+            } else {
+              core.setFailed('Could not find failure-context artifact. Aborting autofix attempt.');
+            }
+
+      - name: Install dependencies for API interaction
+        run: pip install requests # Need 'requests' to talk to the Jules API
+
+      - name: 💬 Run Jules Session Manager
+        env:
+          JULES_API_KEY: ${{ secrets.JULES_API_KEY }}
+          REPO_NAME: ${{ steps.get_pr.outputs.pr_repo }}
+          PR_NUMBER: ${{ steps.get_pr.outputs.pr_number }}
+          BRANCH_NAME: ${{ github.event.workflow_run.head_branch }}
+          ERROR_MESSAGE: ""
+        run: |
+          # Load the error message from the downloaded artifact
+          if [ -f failure-context/error_message.txt ]; then
+            export ERROR_MESSAGE=$(cat failure-context/error_message.txt)
+          else
+            export ERROR_MESSAGE="CI failed, but the specific error message artifact was missing."
+          fi
+
+          # Execute the Python script that interacts with the fixing system
+          python ./scripts/jules_session_manager.py