Merge pull request #8 from quantbai/dev

Dev

Author: quantbai

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,54 @@
+name: Bug Report
+description: Report incorrect behavior or numerical errors
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Describe the bug. Include expected vs actual behavior.
+      placeholder: |
+        ts_mean([1, 2, 3], window=2) returns [None, None, 2.5]
+        Expected: [None, 1.5, 2.5]
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproducible Example
+      render: python
+      placeholder: |
+        from elvers import load, ts_mean
+
+        panel = load()
+        result = ts_mean(panel["close"], 5)
+        print(result.df)
+    validations:
+      required: true
+
+  - type: dropdown
+    id: numerical
+    attributes:
+      label: Does this affect numerical output?
+      options:
+        - "Yes -- incorrect numerical values"
+        - "No -- crash, wrong type, or other non-numerical issue"
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: "Paste the output of: python -c \"import elvers; elvers.show_versions()\""
+      render: text
+      placeholder: |
+        --------Elvers---------
+        Elvers:              0.3.0
+        Polars:              1.37.0
+        Python:              3.12.0
+        Platform:            Linux-6.1.0-x86_64
+        Architecture:        x86_64
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question
+    url: https://github.com/quantbai/elvers/discussions/new?category=q-a
+    about: Ask a question or start a discussion.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,26 @@
+name: Feature Request
+description: Suggest an improvement or new capability
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Use Case
+      description: What problem does this solve?
+      placeholder: |
+        Computing returns requires verbose composition every time:
+        divide(ts_delta(close, 1), ts_delay(close, 1))
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed_api
+    attributes:
+      label: Proposed API
+      description: Show how it should work.
+      render: python
+      placeholder: |
+        from elvers import returns
+        ret = returns(close, window=1)
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/new_operator.yml

@@ -0,0 +1,50 @@
+name: New Operator
+description: Propose a new operator
+labels: ["new operator"]
+body:
+  - type: input
+    id: name
+    attributes:
+      label: Operator Name
+      description: "Naming: ts_ for time-series, group_ for group ops, no prefix for cross-sectional."
+      placeholder: "ts_entropy"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: module
+    attributes:
+      label: Module
+      options:
+        - "timeseries -- per-symbol rolling window"
+        - "cross_sectional -- across symbols per timestamp"
+        - "neutralization -- group operations"
+        - "math -- element-wise transforms"
+        - "base -- arithmetic and structural"
+    validations:
+      required: true
+
+  - type: textarea
+    id: definition
+    attributes:
+      label: Definition and Use Case
+      description: Mathematical formula and why this operator is useful.
+      placeholder: |
+        H(X) = -sum(p_i * log(p_i))
+        Measures randomness in a rolling window. Low entropy often precedes breakouts.
+    validations:
+      required: true
+
+  - type: textarea
+    id: example
+    attributes:
+      label: Example
+      description: Input and expected output.
+      render: python
+      placeholder: |
+        from elvers import load
+        panel = load()
+        result = ts_entropy(panel["close"], window=3)
+        print(result.df.head())
+    validations:
+      required: false

.github/pull_request_template.md

@@ -5,13 +5,35 @@
 - [ ] Bug fix (corrects incorrect behavior)
 - [ ] New feature (new operator or functionality)
 - [ ] Refactor (no behavior change)
-- [ ] Numerical change (alters factor computation results) [BREAKING]
+- [ ] Documentation only
+- [ ] Numerical change (alters factor computation results) **[BREAKING]**
 
 ## Numerical Impact
-<!-- If this changes numerical output, provide before/after factor statistics -->
+<!-- If this changes numerical output, provide before/after comparison: -->
+<!-- Before: ts_example([1,2,3], window=2) -> [None, 1.5, 2.5] -->
+<!-- After:  ts_example([1,2,3], window=2) -> [None, 1.0, 2.0] -->
 <!-- If no numerical impact, write "No numerical impact" -->
 
 ## Testing
 - [ ] Added or updated tests
 - [ ] All tests pass (`pytest tests/ -v`)
 - [ ] Lint passes (`ruff check elvers/`)
+- [ ] Type check passes (`pyright elvers/`)
+
+## New Operator Checklist
+<!-- Delete this section if not adding a new operator -->
+- [ ] Operator added to `ops/__init__.py` imports and `__all__`
+- [ ] Docstring includes: description, parameters, return type, null behavior, warmup
+- [ ] Divisions handle zero denominators (exact zero check or Inf → null via Factor)
+- [ ] No Python loops in computation (Polars expressions only)
+- [ ] Uses `ddof=0` for std/variance (population statistics)
+- [ ] Uses `min_samples=window` for rolling operations
+- [ ] Tests cover: basic correctness, null handling, edge cases
+- [ ] `OPERATORS.md` updated with the new operator
+
+## Reviewer Notes
+<!-- For reviewers: -->
+<!-- 1. Manually verify at least one expected value from the tests -->
+<!-- 2. Check division-by-zero handling (exact zero check or Inf->null via Factor) -->
+<!-- 3. Confirm no implicit Inf-to-null reliance -->
+<!-- 4. For numerical changes: verify the before/after comparison above -->

.github/workflows/ci.yml

@@ -19,4 +19,5 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - run: pip install -e ".[dev]"
       - run: ruff check elvers/
+      - run: pyright elvers/
       - run: pytest tests/ -v

.gitignore

@@ -28,3 +28,6 @@ venv/
 *.swo
 .DS_Store
 .claude/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

CHANGELOG.md

@@ -5,7 +5,27 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 Numerical changes are marked with [NUMERICAL].
 
-## [Unreleased]
+## [0.4.0] - 2026-03-26
+
+### Added
+- `show_versions()` for environment diagnostics in bug reports
+- Pyright static type checking in CI pipeline
+- Community templates: issue templates (bug, feature, new operator), CODE_OF_CONDUCT, SECURITY
+- CONTRIBUTING.md with workflow, numerical invariants, and design rationale
+- Timestamp type validation in loader (must be pl.Date or pl.Datetime)
+- `_check_intervals()` warns about irregular timestamp spacing
+- `Panel.gc()` to drop intermediate columns
+- `Panel.select()` to export specific factors
+
+### Changed
+- **Column-based Factor architecture.** Factor stores a column name + Panel reference instead of a full DataFrame. Eliminates all hash joins (24 removed), reduces memory by ~60% per Factor, ~2x faster on large panels. All data lives in Panel._df.
+- [NUMERICAL] Removed arbitrary `1e-10` zero guards across all operators. Pure divisions (divide, inverse) now produce Inf → null via Panel._add_col. Statistical and regression operators use exact zero checks for degenerate cases (constant series).
+- Replaced interval-based panel skeleton with union-based skeleton (no frequency inference)
+- Restructured documentation: CLAUDE.md (AI memo), CONTRIBUTING.md (human guide), no duplication
+- Removed `interval` parameter from `load()`
+- Restructured into 12-step pipeline: core/, ops/, data/, universe/, analysis/, synthesis/, portfolio/, backtest/, risk/, execution/, monitor/
+- Panel moved from io/ to core/. Loader moved from io/ to data/. Sample data moved to data/sample/
+- Column-level memoization: _add_col skips computation if column already exists
 
 ## [0.3.0] - 2026-03-24
 
@@ -16,22 +36,22 @@ Numerical changes are marked with [NUMERICAL].
 
 ### Changed
 - OPERATORS.md rewritten as pure operator reference manual (signatures, behavior, edge cases)
-- Design rationale moved to CLAUDE.md Section 4.1 (developer-facing)
+- Design rationale moved to CONTRIBUTING.md (Numerical Invariants section)
 - Fixed incorrect signatures in docs: `trade_when`, `scale`, `bucket`
 - Fixed README example code to use only columns present in sample data
 
 ## [0.2.0] - 2026-03-23
 
 ### Added
-- CLAUDE.md development standards (12 sections covering full workflow)
+- CLAUDE.md development memo (architecture map, conduct rules, known limitations)
 - CI pipeline (GitHub Actions, pytest across Python 3.10-3.13)
 - Automated release pipeline (tag-triggered PyPI publish + GitHub Release)
 - Pre-commit hooks (ruff lint + format, pytest)
 - PR template with numerical impact checklist
 - Dev dependencies (pytest, ruff, pre-commit)
 - `elvers/ops/_dev.py` for experimental operators
 - `elvers/ops/_validation.py` input validation helpers
-- `load()` now accepts `interval` parameter for sub-daily data (e.g., "1h", "5m")
+- `load()` supports any time frequency; panel skeleton built from timestamps present in data
 - Factor constructor validates required columns [timestamp, symbol, factor]
 - Tests for `divide()`, `reverse()`, `ts_product` (negative/zero), `ts_regression` (lag>0)
 
@@ -42,7 +62,7 @@ Numerical changes are marked with [NUMERICAL].
 - [NUMERICAL] `inverse()`: no zero protection; now returns null where abs(x) < 1e-10
 - `ts_regression` rettype=7 (MSE): implicit Inf-to-null on window=2; now has explicit guard
 - `ts_count_nans`: used min_samples=1 unlike all other ts_* operators; aligned to min_samples=window
-- `_balance()`: hardcoded daily frequency; now accepts interval parameter
+- `_balance()`: replaced generated-range skeleton with union-based skeleton (no frequency inference)
 
 ### Changed
 - DEV operators (hump, ts_arg_max, ts_arg_min) moved from public API to `_dev.py`