This document is the mission brief for Spec Kitty.
Mission name:
- Frumpy NumPy-compatible array engine
Suggested mission slug:
frumpy-numpy-compatible-array-engine
Mission type:
software-dev
Frumpy is a Fortran 2018 NumPy-compatible array engine.
The project should implement NumPy-shaped ndarray behavior in readable modern Fortran. The goal is not to imitate Python syntax. The goal is to provide the same array semantics NumPy users rely on: shape behavior, dtype handling, broadcasting, views, copies, strides, reductions, indexing, and linear algebra.
Frumpy should make the point that modern numerical infrastructure can be fast, explicit, humane, and easy to follow.
Spec Kitty should treat these files as authoritative:
- README.md: project identity and current scope.
- STYLE_GUIDE.md: Fortran coding rules and ndarray semantics.
- PROJECT_PLAN.md: phased implementation roadmap.
- AGENTS.md: contributor and agent operating rules.
The active scope is NumPy only.
Frumpy owns:
- NumPy-compatible ndarray semantics.
- Shape, stride, dtype, memory, view, and copy behavior.
- NumPy-compatible creation and manipulation functions.
- Elementwise arithmetic.
- Reductions and axis behavior.
- Indexing, sorting, searching, and selection as phased work.
- CPU reference kernels.
- BLAS/LAPACK-backed dense linear algebra.
- A stable C ABI and eventual Python package surface.
- NumPy differential tests for every supported public behavior.
Do not include these in the current mission scope:
- Torch compatibility.
- Autograd.
- Neural-network modules.
- Training loops.
- Diffusers support.
- Safetensors or model loading.
- Tokenizers.
- GPU runtime design.
- A complete SciPy replacement.
Future projects may use Frumpy. They do not belong inside this mission.
Give Spec Kitty the full Frumpy NumPy replacement as one long-horizon mission. Do not split the vision into many independent missions yet.
The mission should decompose the work into phased, dependency-aware work packages. Work packages should be small enough to implement and review, but they should preserve the long-range project architecture.
The expected phase structure is:
- Toolchain and test harness.
- Core descriptor and metadata.
- Constructors and basic data movement.
- Broadcasting and elementwise kernels.
- Reductions and axis semantics.
- Views, reshape, transpose, and slicing.
- Dtype system and promotion.
- Indexing, sorting, searching, and selection.
- Linear algebra, random, and numerical utilities.
- C ABI, Python package, and differential testing.
- Performance and completeness.
Every generated spec, plan, and WP should preserve these themes:
- NumPy is the oracle for public behavior.
- Fortran code should be explicit, readable, and strongly typed.
- Shape, stride, offset, ownership, and contiguity invariants must be preserved.
- Public APIs use NumPy-facing semantics, including 0-based axes.
- Internal Fortran helpers may use 1-based dimensions, but names must make the conversion explicit.
- Hidden copies are bugs unless the API promises a copy.
- Tests should prove Fortran invariants and NumPy compatibility.
- Fast paths are allowed only after correct strided fallbacks exist.
- Library code should use status-based error handling, not casual
error stop.
The first satisfying end-to-end slice should be:
a = zeros([2, 3])
b = full([3], 2.0)
c = a + b
d = reshape(c, [3, 2])
e = sum(d, axis0=1)
Fortran should execute the slice. NumPy differential tests should verify the result for the supported subset.
A reviewer should reject generated artifacts or implementation WPs when:
- The scope drifts beyond NumPy.
- ndarray metadata is vague.
- dtype promotion is hand-waved.
- view/copy behavior is not explicit.
- tests do not compare against NumPy where public behavior is involved.
- Fortran style rules from
STYLE_GUIDE.mdare ignored. - work packages are too large to review confidently.
The mission is allowed to be large. The work packages are not allowed to be foggy.