feat: enrich outputs and docs; add topology backends, adapter, and CLI flags

- Implement Rips/Alpha persistence via GUDHI with field_to_point_cloud adapter
- Guard TDA feature extraction against NaN/Inf; add topology backend to stage results
- Add attractor classification/characterization and expose types in outputs
- Extend dashboard with topology summary and attractor type chart
- Add mneme.data.quality, mneme.data.parallel, mneme.utils.monitoring, results_generator
- CLI: add topology and attractor flags; mneme info shows backend and PySR status
- Docs: update README (examples and flags), API_DESIGN, DATA_PIPELINE, PROJECT_STRUCTURE, TESTING_STRATEGY
- Packaging: setup.py align to Python 3.12

Author: bshepp

CLAUDE.md

@@ -66,7 +66,7 @@ python -c "import numpy as np; import pandas as pd; import matplotlib.pyplot as
 
 - Package imports cleanly on Python 3.12
 - CI: lint passes; mypy runs non-blocking; docs deploy to `gh-pages`
-- `create_bioelectric_pipeline()` stub available; minimal model placeholders added
+- `create_bioelectric_pipeline()` implemented with lightweight defaults; minimal model placeholders remain
 
 ## Contributor Guidance
 

README.md

@@ -8,11 +8,11 @@ Mneme seeks to uncover attractor states, regulatory logic, and latent architectu
 
 ## Key Features
 
-- **Field Reconstruction**: Information Field Theory implementations for continuous field interpolation
-- **Topology Analysis**: Persistent homology for identifying stable structures
-- **Attractor Detection**: Methods for finding and characterizing dynamical attractors
-- **Symbolic Regression**: Discovery of mathematical rules governing field behavior
-- **Latent Space Analysis**: Autoencoders for dimensionality reduction and pattern discovery
+- **Field Reconstruction (MVP-ready)**: Basic IFT and GP reconstruction APIs; identity fallback when sparse observations are not provided
+- **Topology Analysis (MVP-ready)**: Cubical persistence via GUDHI when installed; simple fallback otherwise
+- **Attractor Detection (experimental)**: Recurrence-based detector usable on temporal data; Lyapunov and clustering detectors are stubs with NotImplemented methods
+- **Symbolic Regression (placeholder)**: PySR is installed optionally; shipped `SymbolicRegressor` is a placeholder. Integrations are roadmap
+- **Latent Space Analysis (placeholder)**: `FieldAutoencoder` class is a minimal placeholder; not a production model
 
 ## Installation
 
@@ -52,14 +52,51 @@ from mneme.data import generators
 generator = generators.SyntheticFieldGenerator(seed=42)
 field = generator.generate_dynamic(shape=(64, 64), timesteps=10, parameters={'noise_level': 0.1})
 
-# Create analysis pipeline
+# Create analysis pipeline (lightweight defaults)
 pipe = pipeline.create_bioelectric_pipeline()
 results = pipe.run({'field': field})
 
 # Access results
 print("Pipeline executed successfully!")
 ```
 
+### CLI usage
+
+Run analysis on a saved array and choose a topology backend:
+
+```bash
+# Topology backend options: cubical (default), rips, alpha
+mneme analyze data/synthetic/test_small.npz \
+  --pipeline bioelectric \
+  --topology-backend rips \
+  -o results
+```
+
+Run analysis with clustering-based attractor detection (example):
+
+```bash
+mneme analyze data/synthetic/test_small.npz \
+  --pipeline bioelectric \
+  --attractor-method clustering \
+  --attractor-threshold 0.2 \
+  --attractor-min-samples 20 \
+  -o results_clustering
+```
+
+#### Attractor CLI flags
+
+| Flag | Description |
+|------|-------------|
+| --attractor-method {none,recurrence,lyapunov,clustering} | Choose attractor detector (use none to disable) |
+| --attractor-threshold FLOAT | Detection threshold (method-specific) |
+| --attractor-min-persistence FLOAT | Recurrence: minimum persistence fraction |
+| --attractor-embedding-dim INT | Recurrence/Clustering: embedding dimension for 1D series |
+| --attractor-time-delay INT | Recurrence/Clustering: time delay for embedding |
+| --attractor-n-neighbors INT | Lyapunov: number of neighbors |
+| --attractor-evolution-time INT | Lyapunov: evolution time steps |
+| --attractor-min-samples INT | Clustering: minimum samples per cluster |
+| --attractor-clustering-method {dbscan,kmeans} | Clustering: algorithm selection |
+
 ## Project Structure (MVP)
 
 ```
@@ -76,11 +113,16 @@ See [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md) for detailed structur
 
 ## Documentation
 
-- [Project Structure](docs/PROJECT_STRUCTURE.md) - Code organization and architecture
-- [Development Setup](docs/DEVELOPMENT_SETUP.md) - Environment setup and dependencies
-- [API Design](docs/API_DESIGN.md) - Module interfaces and usage
-- [Data Pipeline](docs/DATA_PIPELINE.md) - Data processing workflows
-- [Testing Strategy](docs/TESTING_STRATEGY.md) - Testing approach and guidelines
+- [Project Structure](docs/PROJECT_STRUCTURE.md) — Code organization and architecture
+- [Development Setup](docs/DEVELOPMENT_SETUP.md) — Environment setup and dependencies
+- [API Design](docs/API_DESIGN.md) — Module interfaces and usage
+- [Data Pipeline](docs/DATA_PIPELINE.md) — MVP note: several sections are illustrative/roadmap and not yet implemented (quality, features, parallel, monitoring, recovery)
+- [Testing Strategy](docs/TESTING_STRATEGY.md) — Current suite is a smoke test; more tests are roadmap
+
+### Capabilities vs Roadmap
+
+- MVP capabilities: importable package, CLI (`mneme info`, `mneme analyze`), lightweight preprocessing, identity or basic reconstruction, cubical persistence (with GUDHI), simple recurrence attractor detection on temporal inputs, plotting utilities
+- Roadmap (not fully implemented): rich loaders/quality/feature extractors; Lyapunov/clustering attractors; real autoencoders; symbolic regression integration; parallel/distributed pipeline; monitoring/recovery utilities
 - [Contributing](CONTRIBUTING.md) - How to contribute
 
 ## Roadmap

docs/API_DESIGN.md

@@ -10,6 +10,8 @@ The Mneme API follows these principles:
 
 ## Module APIs
 
+> MVP note: Some classes shown below (e.g., rich attractor characterization, full models) are placeholders or partially implemented. Methods explicitly marked with `NotImplementedError` are roadmap.
+
 ### 1. Field Theory Module (`mneme.core.field_theory`) — MVP
 
 ```python
@@ -77,6 +79,18 @@ class AttractorDetector:
 
     def characterize(self, attractor: Attractor) -> Dict[str, Any]:
         """Compute attractor properties (dimension, stability, basin)."""
+
+### 2b. Point-cloud topology backends — MVP
+
+```python
+from mneme.core.topology import RipsComplex, AlphaComplex, field_to_point_cloud
+
+# Convert 2D field to point cloud and run Rips
+pc = field_to_point_cloud(field2d, method='peaks', percentile=95.0)
+tda = RipsComplex(max_dimension=1)
+diagrams = tda.compute_persistence(pc)
+features = tda.extract_features(diagrams)
+```
 ```
 
 ### 3. Models Module (`mneme.models`) — placeholders

docs/DATA_PIPELINE.md

@@ -1,5 +1,7 @@
 # Mneme Data Pipeline Documentation
 
+> Accuracy note (MVP): Several sections below (quality module, feature extractor, parallel pipeline, monitoring, recovery) are illustrative/roadmap and not yet implemented in `src/`. Where code references non-existent modules, treat them as examples for future work.
+
 ## Overview
 
 The Mneme data pipeline handles the flow of data from raw bioelectric measurements and synthetic generation through preprocessing, analysis, and final results. The pipeline is designed to be modular, reproducible, and scalable.
@@ -84,7 +86,7 @@ for experiment in loader:
     metadata = experiment.metadata
 ```
 
-### Stage 2: Quality Control
+### Stage 2: Quality Control (roadmap)
 
 ```python
 from mneme.data import quality
@@ -143,7 +145,7 @@ processed = preprocessor.fit_transform(voltage_field)
    - Bicubic interpolation for upsampling
    - Gaussian process interpolation for missing data
 
-### Stage 4: Feature Extraction
+### Stage 4: Feature Extraction (roadmap)
 
 ```python
 from mneme.analysis import features
@@ -171,19 +173,25 @@ reconstructor = field_theory.FieldReconstructor(method='ift')
 continuous_field = reconstructor.fit_reconstruct(processed_field)
 
 # 2. Topology analysis
+# Cubical for 2D fields (default), or use Rips/Alpha with adapter
 tda = topology.PersistentHomology()
 persistence_diagrams = tda.compute_persistence(continuous_field)
 
+# Point-cloud backends
+pc = topology.field_to_point_cloud(continuous_field, method='peaks', percentile=95.0)
+rips = topology.RipsComplex(max_dimension=1)
+rips_diagrams = rips.compute_persistence(pc)
+
 # 3. Latent space embedding
 autoencoder = autoencoders.FieldAutoencoder(latent_dim=32)
 latent_representation = autoencoder.encode(continuous_field)
 
-# 4. Attractor detection
-detector = topology.AttractorDetector()
+# 4. Attractor detection (recurrence default; lyapunov/clustering also available)
+detector = topology.AttractorDetector(method='recurrence')
 attractors = detector.detect(latent_trajectory)
 ```
 
-### Stage 6: Results Generation
+### Stage 6: Results Generation (roadmap)
 
 ```python
 from mneme.analysis import results
@@ -285,15 +293,15 @@ results = pipe.run_batch(
 )
 ```
 
-## Parallel Processing
+## Parallel Processing (MVP)
 
 ```python
 from mneme.data import parallel
 
 # Parallel pipeline for large datasets
 parallel_pipeline = parallel.ParallelPipeline(
     pipeline=pipe,
-    backend='multiprocessing',  # or 'dask', 'ray'
+    backend='multiprocessing',  # MVP
     n_workers=8
 )
 
@@ -334,7 +342,7 @@ field_cache = cache.FieldCache(max_size="10GB")
 field_cache.put("exp_001", processed_field)
 ```
 
-## Monitoring and Logging
+## Monitoring and Logging (MVP)
 
 ```python
 from mneme.utils import monitoring
@@ -348,10 +356,10 @@ with monitor.track_stage("preprocessing"):
 
 # Get performance metrics
 metrics = monitor.get_metrics()
-print(f"Preprocessing took: {metrics['preprocessing']['duration']}s")
+print(f"Preprocessing durations: {metrics['stage_durations_s']}")
 ```
 
-## Error Handling and Recovery
+## Error Handling and Recovery (roadmap)
 
 ```python
 from mneme.data import recovery

docs/PROJECT_STRUCTURE.md

@@ -36,6 +36,7 @@ mneme/
 │   │   │   ├── __init__.py
 │   │   │   ├── pipeline.py        # Main analysis pipeline
 │   │   │   ├── visualization.py   # Plotting and visualization
+│   │   │   ├── features.py        # Basic field feature extraction (MVP)
 │   │   │   └── metrics.py         # Evaluation metrics
 │   │   │
 │   │   └── utils/             # Utilities
@@ -100,12 +101,15 @@ mneme/
 - **bioelectric.py**: Specialized handlers for bioelectric imaging data
 
 ### Analysis Modules (`src/mneme/analysis/`)
-- **pipeline.py**: Orchestrates the complete analysis workflow
-- **visualization.py**: Publication-quality plotting and interactive visualizations
-- **metrics.py**: Coherence metrics, validation measures, and evaluation tools
+- **pipeline.py**: Orchestrates the analysis workflow (MVP-ready)
+- **visualization.py**: Plotting utilities (MVP-ready)
+- **features.py**: Basic feature extractor (MVP-ready)
+- **metrics.py**: Evaluation utilities (minimal)
 
 ## Development Workflow
 
+> Note: Some items referenced in `docs/DATA_PIPELINE.md` (e.g., `quality`, `features`, `parallel`, `monitoring`) are roadmap and not yet implemented.
+
 1. **Feature Development**: Create feature branches from `main`
 2. **Testing**: Write tests alongside new features
 3. **Documentation**: Update relevant docs with changes

docs/TESTING_STRATEGY.md

@@ -1,5 +1,7 @@
 # Mneme Testing Strategy
 
+> MVP note: Current repository includes a smoke test for imports. The sections below describe the intended testing strategy as the project grows.
+
 ## Testing Philosophy
 
 The Mneme project employs comprehensive testing to ensure:

results/analysis_results.hdf5

@@ -34,14 +34,12 @@
         "Topic :: Scientific/Engineering :: Physics",
         "License :: OSI Approved :: MIT License",
         "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.8",
-        "Programming Language :: Python :: 3.9",
-        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.12",
         "Operating System :: OS Independent",
     ],
     package_dir={"": "src"},
     packages=find_packages(where="src"),
-    python_requires=">=3.8",
+    python_requires=">=3.12",
     install_requires=requirements,
     extras_require={
         "dev": dev_requirements,