# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.3.1] - 2026-01-27

### Fixed

- **Pipeline duration tracking** - Fixed `KeyError: 'duration_seconds'` crash at end of pipeline run
  - Added timing to `BaselinePipeline.run()` method
  - Returns `duration_seconds` in result dict as expected by `run_pipeline.py`

### Changed

- feat: add Docker infrastructure for ghcr.io publishing (#8)
- eval: v_0003 - Recall 0.8105 (-0.0234) (#7)
- perf: optimize BurstDetector edge lookup with O(1) set check (#6)
- refactor: remove NetworkX entirely - pure Rust + cuGraph architecture (#5)
- **BurstDetector chain detection now uses Rust backend** - Route chain burst detection through petgraph + rayon for parallel processing
  - Added `find_chain_bursts()` to Rust backend (`lib.rs`) with parallel time window processing
  - `_detect_chain_bursts()` now uses Rust when available, falls back to optimized Python
  - Python fallback samples windows (every 100th) and limits exploration depth to avoid O(n²) blowup
  - Expected 50-100x speedup for large transaction datasets

## [0.2.4] - 2026-01-24

### Changed

- **Python version requirement** - Lowered minimum Python version from 3.13 to 3.12 for RAPIDS/cuGraph GPU acceleration compatibility

### Added

- **LLM Self-Improvement Evaluation Framework** - New `eval/` module for iterative code evolution
  - `FlowValidator` - Pattern validation by tracing flows in transfers (ported from subnet)
  - `EvalScorer` - Balanced scoring: 50% recall + 25% novelty + 25% performance
  - `EvalRunner` - Pipeline execution with pre-build hooks (Rust, bash scripts)
  - `MetricsStorage` - JSON metrics + parquet history tracking
  - `scripts/run_eval.py` - LLM-friendly CLI for iteration management
  - `LLM_INSTRUCTIONS.md` - Comprehensive usage guide for Docker and CLI
- `StructuralPatternAnalyzer.analyze_with_timing()` - Per-detector timing instrumentation
- Test dataset `data/input/torus/2025-12-10/256/` with 143,924 ground truth patterns

## [0.2.3] - 2026-01-08

### Fixed

- **Pattern Flow Validation Fixes** - Fixed `Gate 2` validation failures by preserving address order in pattern output
  - `MotifDetector`: Removed `sorted()` from `addresses_involved` to ensure center address is always at index 0 (required by validator)
  - `CycleDetector`: Now returns ordered `cycle` instead of `sorted_cycle` in `addresses_involved` to pass sequential flow validation
  - `LayeringDetector`: Now returns ordered `path` instead of `sorted_path` in `addresses_involved` to pass sequential flow validation
  - Detectors still use sorted addresses for deterministic pattern hashing/deduplication, but return structurally meaningful order

## [0.2.2] - 2026-01-06

### Fixed

- **ParquetAdapter Burst Detection Support** - Added missing `read_transfer_timestamps()` method to ParquetAdapter
  - Fixes `AttributeError` when running pattern detection with Parquet data sources
  - Enables temporal burst pattern detection in tournament/testing mode
  - Maintains parity with ClickHouseAdapter timestamp data extraction
  - Reuses cached transfer DataFrame for efficient timestamp extraction

### Added

- `ParquetAdapter.read_transfer_timestamps()` - Extract timestamp data for burst detection from Parquet files
- `InputAdapter.read_transfer_timestamps()` protocol definition - Enforces consistent interface across adapters

## [0.2.1] - 2026-01-05

### Changed

- **BREAKING**: `ParquetAdapter.read_money_flows()` now requires `money_flows.parquet`
  - File is required - raises `ValueError` if not found (no fallback)
  - Raises `ValueError` if no money flows in time range (consistent with other adapters)
  - Enables dormant detection with preserved `first_seen_timestamp` from production data
  - Added `_money_flows_df` cache and `clear_cache()` update

## [0.2.0] - 2025-12-26

### Changed

- **BREAKING**: `MoneyFlow` dataclass expanded from 4 to 15 fields - now includes edge-level temporal context, reciprocity metrics, and behavioral patterns from `core_money_flows_view`
  - Added: `first_seen_timestamp`, `last_seen_timestamp`, `active_days`, `avg_tx_size_usd`
  - Added: `unique_assets`, `dominant_asset`, `hourly_pattern[24]`, `weekly_pattern[7]`
  - Added: `reciprocity_ratio`, `is_bidirectional`
- **BREAKING**: `ClickHouseAdapter.read_money_flows()` now queries `core_money_flows_view` instead of re-aggregating `core_transfers`
  - Returns lifetime aggregates for edges active in time window (semantic change)
  - 5x faster query performance via pre-computed materialized view
- **BREAKING**: `BurstDetector.detect()` signature now requires `timestamp_data` parameter
  - Burst detection uses dedicated transfer timestamp query for precision
  - Other pattern detectors unaffected (use MV graph)

### Added

- `ClickHouseAdapter.read_transfer_timestamps()` - Targeted query for burst detection temporal analysis
- `AddressFeatureAnalyzer._compute_edge_features()` - 7 new relationship-context features:
  - `avg_relationship_age_days`, `max_relationship_age_days` - Relationship maturity metrics
  - `bidirectional_relationship_ratio`, `avg_edge_reciprocity` - Reciprocity analysis
  - `multi_asset_edge_ratio` - Asset diversity across relationships
  - `edge_hourly_entropy`, `edge_weekly_entropy` - Temporal pattern diversity
- **Schema**: 7 new columns in `analyzers_features` table leveraging MV edge data

### Performance

- Overall pipeline speedup: ~5x (MV eliminates 4 of 5 transfer table scans)
- Feature computation: Behavioral/temporal features now use pre-aggregated edge arrays
- Graph building: 13 edge attributes from MV vs 2 from re-aggregation

## [0.1.3] - 2025-12-10

### Changed

- **BREAKING**: `ClickHouseAdapter.delete_partition()` has been removed and replaced with two separate methods:
  - `delete_features_partition(window_days, processing_date)` - Deletes only from `analyzers_features` table
  - `delete_patterns_partition(window_days, processing_date)` - Deletes only from `analyzers_patterns_*` tables
  - This prevents unintended data loss when running feature computation and pattern detection sequentially

## [0.1.1] - 2025-12-10

### Fixed

- **Zero USD Price Handling** - Fixed multiple ZeroDivisionError crashes when processing networks with missing USD price data
  - `NetworkDetector._detect_smurfing()`: Added fallback to tx_count as weight when USD values are zero
  - `AddressFeatureAnalyzer._compute_flow_features()`: Added total_volume > 0 check for concentration_ratio
  - `AddressFeatureAnalyzer._compute_pagerank()`: Fallback to unweighted PageRank when graph has zero weights
  - `AddressFeatureAnalyzer._compute_closeness_centrality()`: Fallback to hop-based distance when weights are zero
  - `AddressFeatureAnalyzer._compute_clustering_coefficient()`: Fallback to unweighted clustering when weights are zero
  - `AddressFeatureAnalyzer._compute_community_detection()`: Fallback to tx_count as weight for Leiden algorithm
  - `MotifDetector._calculate_time_concentration()`: Added protection against floating-point edge cases

## [0.1.0] - 2025-12-08

### Added

- Initial release of `chainswarm-analyzers-baseline`
- **I/O Adapters**
  - `ParquetAdapter` for file-based I/O (tournament testing)
  - `ClickHouseAdapter` for database I/O (production)
- **Feature Computation**
  - `AddressFeatureAnalyzer` with 70+ features per address
  - Volume, statistical, flow, graph, behavioral, and label-based features
- **Pattern Detection**
  - `CycleDetector` - Circular transaction patterns
  - `LayeringDetector` - Long transaction chains
  - `NetworkDetector` - Smurfing network patterns
  - `ProximityDetector` - Distance to risky addresses
  - `MotifDetector` - Fan-in/fan-out patterns
  - `BurstDetector` - Temporal burst patterns
  - `ThresholdDetector` - Threshold evasion patterns
- **Pipeline**
  - `BaselineAnalyzersPipeline` orchestrator
  - `create_pipeline()` factory function
- **Configuration**
  - `SettingsLoader` for network-specific settings
  - JSON-based configuration with inheritance
- **Protocols**
  - `InputAdapter`, `OutputAdapter`, `DataAdapter` interfaces
  - `FeatureAnalyzer`, `PatternAnalyzer` protocols
  - Data models: `Transfer`, `AddressFeatures`, `PatternDetection`
- **CLI Scripts**
  - `run-pipeline` - Full pipeline execution
  - `run-features` - Feature computation only
  - `run-patterns` - Pattern detection only
