Rust + PyO3 function skill (eo-processor)

Use this skill when you need to add or change a Rust implementation that is exposed to Python. The goal is: correct math + stable API + high performance + predictable behavior.

Activation checklist (before you code)

1. •Identify the public Python name of the function (e.g., ndvi) and confirm whether this is:
   • •a new function, or
   • •a behavior change, or
   • •a bug fix (no API change).
2. •Find existing patterns in:
   • •src/ for Rust/PyO3 style
   • •python/eo_processor/ for exports/docstrings
   • •python/eo_processor/__init__.pyi for typing
   • •tests/ for numerical expectations.
3. •Define expected behavior for:
   • •shape mismatches
   • •division by zero / near-zero denominators
   • •NaN/Inf handling
   • •dtype support and output dtype.

If anything is ambiguous, decide based on existing functions in this repo (stay consistent).

Design rules (repo conventions)

1) Keep the core pure

• •Rust compute kernels should be pure functions: no file I/O, no network access, no global state.
• •Deterministic results for deterministic inputs.

2) Validate shapes early, fail clearly

• •If the function expects aligned shapes, check and raise a Python-friendly error.
• •Do not silently broadcast unless the repo already does that everywhere.

3) Numerical stability is not optional

• •For normalized differences and ratios, guard denominators with a small epsilon.
• •Use a consistent epsilon strategy across similar functions.
• •Make NaN behavior explicit (propagate vs sanitize) and match existing functions.

4) Avoid unnecessary allocations

• •Prefer single-pass loops where possible.
• •Avoid creating multiple temporaries for large rasters.
• •If using ndarray operations, be mindful of intermediate allocations.

5) Don’t introduce unsafe without a compelling reason

• •If you think you need unsafe, stop and provide:
  • •justification (benchmark evidence),
  • •a safety argument,
  • •tests that would catch UB-like symptoms.

Implementation workflow (step-by-step)

Step A: Specify the API contract

Write down:

• •signature at Python level (args, defaults, return)
• •expected input shapes and dtypes
• •output dtype
• •error behavior & messages

Example contract for a normalized difference:

• •Inputs: a, b float arrays (1D or 2D depending on existing patterns)
• •Output: float array same shape
• •Math: (a - b) / (a + b + EPS)
• •Errors: shape mismatch -> ValueError (or the project’s standard)

Step B: Implement Rust function with PyO3 glue

Typical structure:

1. •Accept Python token and PyReadonlyArray* inputs.
2. •Convert to ndarray::ArrayView* using .as_array().
3. •Validate shape compatibility.
4. •Allocate output (or create new array) and fill it.
5. •Return PyArray* via into_pyarray(py) (or existing conventions).

Prefer returning a new array rather than mutating inputs.

Step C: Register with the module

• •Ensure the #[pyfunction] is added to the module in the #[pymodule] initializer.
• •Keep ordering, naming, and grouping consistent with neighboring functions.

Step D: Maintain Python surface coherence

Whenever you add/rename a Rust-exposed function, you almost always need to update:

• •python/eo_processor/__init__.py (exports and __all__)
• •python/eo_processor/__init__.pyi (typing stub)
• •docs (README.md at minimum; docs/ if used by the repo)
• •tests (tests/)

If the change is internal-only, do not export it publicly.

Error handling guidance (PyO3)

• •Prefer returning PyResult<T>.
• •Use Pythonic errors; typical choices:
  • •ValueError for invalid shapes/values
  • •TypeError for wrong types (rare if signature enforces arrays)
• •Error messages should be:
  • •actionable
  • •short
  • •consistent across functions.

Performance guidance

What to optimize first

1. •Avoid extra allocations / temporaries.
2. •Ensure tight loops with minimal branching in the inner loop.
3. •Use contiguous iteration patterns when possible.

When to benchmark

Benchmark if:

• •you’re adding a new kernel, or
• •you changed the inner loop, or
• •you changed dtype handling.

Don’t claim speedups without before/after numbers and array sizes.

Testing expectations (what to add)

Add tests that cover:

1. •Correctness: known inputs with known outputs (small arrays).
2. •Stability: near-zero denominators; ensure outputs are finite if expected.
3. •Shape behavior: mismatch raises the correct error.
4. •NaN behavior: if inputs contain NaN, outcome matches contract.
5. •Dtype behavior: float32/float64 if supported by project conventions.

For numerical comparisons:

• •use tolerances appropriate for float64/float32
• •avoid exact equality for floats unless intentionally exact.

Documentation expectations

For a new EO index function, document:

• •the formula
• •what each band represents
• •recommended input scaling (e.g., reflectance 0–1 vs scaled ints)
• •typical output range and interpretation

Keep docs short in README.md and move deeper material to docs/ if present.

“Done” checklist (must be true before you stop)

• • Rust function implemented with correct math and shape checks
• • Function is registered in the PyO3 module
• • Python exports updated (if public)
• • Typing stubs updated (if public)
• • Tests added/updated and pass
• • Docs updated (if public)
• • Lint/format gates pass for Rust (+ Python if touched)
• • No unnecessary new dependencies

Common pitfalls (avoid these)

• •Returning wrong shape due to accidental broadcast or flattening
• •Implicit dtype casts causing precision loss
• •Division by zero producing noisy Inf/NaN without being documented
• •Adding a Rust function but forgetting Python __init__.py / __init__.pyi
• •Performance regressions from extra temporaries
• •Changing behavior without updating tests and docs

Local references (repo)

• •Engineering rules & checklists: AGENTS.md
• •User docs and API overview: README.md, QUICKSTART.md
• •Existing workflows/examples: WORKFLOWS.md, examples/
• •Rust crate entrypoints and module registration: src/
• •Python exports/stubs: python/eo_processor/
• •Tests: tests/