release: bump version and update changelog for v0.2.0

Author: RobLe3

CHANGELOG.md

@@ -7,7 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Added - Phase 2 Performance Optimizations
+## [0.2.0] - 2025-12-21
+
+This release delivers significant performance improvements, usability enhancements, and infrastructure upgrades while maintaining stdlib-only purity and exact contract compliance.
+
+### Contract Compliance
+- **Meissel-Lehmer π(x) backend**: ENABLE_LEHMER_PI now enabled by default
+  - Sublinear O(x^(2/3)) prime counting for large x
+  - Exact Legendre formula implementation with memoization
+  - Dedicated lehmer.py module with comprehensive tests
+- **Forecast refinement levels**: Extended support for refinement_level parameter
+  - Level 2: Higher-order PNT terms for <0.2% error at n=10^8
+  - Level 3: Implemented and tested for ultra-precise forecasting
+  - Maintains backward compatibility (Level 1 default)
+
+### Performance
 - **Log caching**: LRU cache (maxsize=2048) for log_n() and log_log_n() functions
   - 25-35% reduction in simulation time for N≥10^6
   - Cache hit rate >95% in typical workloads
@@ -16,28 +30,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Maintains determinism: same seed yields identical sequence
   - 12 new tests validating equivalence and memory efficiency
 - **Dynamic β annealing**: Added `anneal_tau` parameter to simulate()
-  - Formula: β_eff(n) = beta * (1 - exp(-n / anneal_tau)) * (beta_decay)^n
   - Reduces early transient variance, improves convergence stability
   - 14 new tests validating annealing behavior
 - **CDF gap sampling**: Replaced random.choices() with CDF + binary search
-  - Performance improvement: O(k) → O(log k) per sample
+  - Performance improvement: O(k) → O(log k) per sample (~7-8× faster)
   - Maintains exact probability distribution semantics
   - 17 new tests validating sampling correctness
 
+### Usability
+- **Command-line interface**: Added `python -m lulzprime` CLI
+  - Commands: resolve, pi, simulate
+  - Support for --seed, --anneal-tau, --generator flags
+  - Streaming output for low-memory workflows
+- **JSON export**: New simulation export functionality
+  - simulation_to_json() and simulation_to_json_string() helpers
+  - CLI --json flag for exporting results to file
+  - Includes metadata (n_steps, seed, anneal_tau, timestamps)
+
+### Infrastructure
+- **GitHub Actions CI**: Automated testing on push/PR
+  - Matrix testing: Python 3.10, 3.11
+  - Runs full test suite (258 passing tests)
+  - Mypy type checking integrated into workflow
+- **mypy strict type checking**: Comprehensive type annotations
+  - Enabled strict mode (disallow_untyped_defs, warn_return_any)
+  - Fixed 17 typing errors across 5 modules
+  - Python 3.10+ type hints throughout codebase
+
 ### Changed
 - simulate() signature now includes: as_generator (bool), anneal_tau (float | None)
 - Gap sampling implementation: bisect-based for O(log k) performance
-- Total tests: 169 → 225 (56 new tests)
+- Total tests: 169 → 258 (89 new tests)
+- ENABLE_LEHMER_PI default changed from False to True
 
-### Performance
+### Performance Metrics
 - Simulations: 20-60% faster overall
 - Memory: 75% reduction with generator mode (180 MB → 45 MB for N=10^6)
 - Gap sampling: ~7-8× faster per sample for typical distributions
+- Forecast accuracy: <0.2% error at n=10^8 with refinement_level=2
 
 ### Notes
-- All optimizations maintain stdlib-only purity (no external dependencies)
-- Phase 2 (Performance) complete, Phase 3 (Usability) starting
-- Tier C statistical contracts maintained throughout
+- All features maintain stdlib-only purity (no external dependencies)
+- Backward compatible: All v0.1.2 code runs unchanged on v0.2.0
+- Phase 2 (Performance), Phase 3 (Usability), Phase 4 (Infrastructure) complete
 
 ## [0.1.2] - 2025-12-20
 

README.md

@@ -41,21 +41,21 @@ LULZprime is a Python library for efficient prime number resolution using analyt
 
 See `docs/PAPER_ALIGNMENT_STATUS.md` for complete performance analysis and validation results.
 
-### Enable Meissel Backend
+### Meissel-Lehmer Backend
 
-The Meissel-Lehmer backend provides O(x^(2/3)) sublinear complexity for large indices. It's opt-in by default:
+The Meissel-Lehmer backend provides O(x^(2/3)) sublinear complexity for large indices. **Enabled by default in v0.2.0.**
 
 ```python
-# In your code, before using lulzprime
-import lulzprime.config as config
-config.ENABLE_LEHMER_PI = True  # Enable Meissel backend
-
-# Now use lulzprime normally
+# Enabled automatically - no configuration needed
 import lulzprime
 result = lulzprime.resolve(500_000)  # Fast with Meissel backend
+
+# Optional: Disable if needed for backward compatibility
+import lulzprime.config as config
+config.ENABLE_LEHMER_PI = False  # Revert to segmented sieve
 ```
 
-**Why opt-in?** Extensive validation complete (169/169 tests pass), but defaults preserve backward compatibility. Enablement is safe and reversible (one-line change).
+**Default change:** v0.2.0 enables ENABLE_LEHMER_PI=True by default. Extensive validation complete (258 tests pass). Safe and reversible.
 
 **Rollback:** Simply set `ENABLE_LEHMER_PI = False` to revert to segmented sieve.
 
@@ -238,7 +238,7 @@ This reframes primes from a brute-force enumeration problem into a navigable spa
 
 ## Maintenance Status
 
-**Current Status:** Completed reference implementation (v0.1.2)
+**Current Status:** Completed reference implementation (v0.2.0)
 
 LULZprime is a **finished artifact**. The implementation has achieved full paper alignment and is production-ready for indices up to 500k.
 
@@ -254,7 +254,7 @@ LULZprime is a **finished artifact**. The implementation has achieved full paper
 - API will not change (backward compatibility preserved)
 - No new features planned (scope is deliberately limited)
 - All 258 tests continue to pass
-- Defaults remain unchanged (ENABLE_LEHMER_PI = False)
+- Meissel-Lehmer backend enabled by default (ENABLE_LEHMER_PI = True)
 
 **Future work (out of scope):**
 - C/Rust port for paper-exceedance performance (10-50× gains possible)
@@ -341,7 +341,7 @@ https://roblemumin.com/library.html
 
 ---
 
-**Status**: v0.1.2 (v0.2.0 in development) - Full paper alignment achieved ✓
+**Status**: v0.2.0 - Full paper alignment achieved ✓
 
 **Test Coverage**: 258 passing (225 core + 15 CLI + 18 JSON export)
 **Validation**: resolve(500k) measured at 73.044s with Meissel backend

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lulzprime"
-version = "0.1.2"
+version = "0.2.0"
 description = "Prime resolution and navigation library based on OMPC"
 readme = "README.md"
 requires-python = ">=3.10"

src/lulzprime/__init__.py

@@ -20,7 +20,7 @@
 - between_many(ranges) -> list[list[int]]: Batch range queries
 """
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 
 # Public API exports
 from .batch import between_many, resolve_many

tests/test_json_export.py

@@ -47,7 +47,7 @@ def test_simulation_to_json_basic(self):
 
         # Check meta
         assert json_data["meta"]["library"] == "lulzprime"
-        assert json_data["meta"]["version"] == "0.1.2"
+        assert json_data["meta"]["version"] == "0.2.0"
         assert json_data["meta"]["timestamp"] is None
 
     def test_json_serializable(self):