Metadata-Version: 2.4
Name: maya-metrics-nll
Version: 1.0.0
Summary: Affective neuromorphic evaluation library for SNN continual learning
Author-email: Venkatesh Swaminathan <founder@nexuslearninglabs.in>
License: MIT
Project-URL: Homepage, https://github.com/venky2099/maya-metrics
Project-URL: Bug Tracker, https://github.com/venky2099/maya-metrics/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.9.0
Requires-Dist: pandas>=1.5.0
Provides-Extra: dashboard
Requires-Dist: flask>=3.0.0; extra == "dashboard"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# maya-metrics: Affective Neuromorphic Evaluation

<div align="center">

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19553205.svg)](https://doi.org/10.5281/zenodo.19553205)
[![Series](https://img.shields.io/badge/Maya%20Research%20Series-Companion%20Library-9d7cff?style=flat-square)](https://venky2099.github.io/)
[![Status](https://img.shields.io/badge/Status-Active%20✦-00d4aa?style=flat-square)](https://venky2099.github.io/)
[![ORCID](https://img.shields.io/badge/ORCID-0000--0002--3315--7907-a6ce39?style=flat-square&logo=orcid)](https://orcid.org/0000-0002-3315-7907)
[![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?style=flat-square&logo=python)](https://python.org)
[![Tests](https://img.shields.io/badge/Tests-16%2F16%20passing-00d4aa?style=flat-square)](https://github.com/venky2099/maya-metrics)
[![Hardware](https://img.shields.io/badge/Hardware-RTX%204060%208GB-76b900?style=flat-square)](https://github.com/venky2099/maya-metrics)

**Venkatesh Swaminathan** · Nexus Learning Labs, Bengaluru, India · M.Sc. DS&AI, BITS Pilani

[📄 Paper](https://doi.org/10.5281/zenodo.19553205) · [🎛️ Interactive Dashboard](https://venky2099.github.io/maya-metrics/docs/maya_metrics_dashboard.html) · [❓ FAQ](https://venky2099.github.io/maya-metrics/docs/maya_metrics_faq.html) · [🌐 Research Hub](https://venky2099.github.io/)

</div>

---

## What is this?

**maya-metrics** is the companion evaluation library to the [Maya Research Series](https://venky2099.github.io/) — the first open-source Python library for evaluating **internal affective and neuromodulatory dynamics** in neuromorphic spiking neural networks (SNNs) engaged in class-incremental continual learning (CIL).

The Maya Research Series (P1–P9, Maya-mPCI, Maya-LLM) implemented all fourteen dimensions of the Advaita Vedantic *Antahkarana* as independently falsifiable computational mechanisms. This library gives the community the tools to measure those mechanisms in any future architecture.

> *"cl-metrics measures what happened. maya-metrics measures how it felt."*

Validated against 11 published preprints, two substrates (SNN + LLM), one embodied PiCar-X deployment. 16/16 unit tests pass in 1.56 seconds.

---

## The One-Paragraph Summary

maya-metrics accepts a Maya batch log CSV and returns standardised measurements of every affective dimension: whether Bhaya quiesced under replay (the Quiescence Law), whether Buddhi followed its sigmoid to R²=1.0000 (S-curve determinism), whether Vairagya grew monotonically (Pearson r=0.9228), whether Karma drove pruning while Vairagya moderated it (D★: partial_r=−0.808), whether the mPCI delta survives depth-matched decoupling (Δ=−0.0427, threshold=0.0214), and whether the network's Structural Age Index classifies it as infant, maturing, or adult (P9 Condition D: SAI=0.824, Maturing). Six modules, one dependency (numpy), stateless pure functions that accept a CSV and return metric dictionaries. No framework coupling. No training loop.

---

## Key Results — P9 Canonical Run (Condition D · seed=42 · Split-CIFAR-100 · 10 tasks)

| Metric | Result | Expected | Status |
|--------|--------|----------|--------|
| Bhaya Quiescence Law | replay_max = **0.000000**, rate = 100% | 0.000 under replay | ✅ CONFIRMED |
| Buddhi S-curve R² | **1.0000** · ceiling task 1 | > 0.95 | ✅ CONFIRMED |
| Vairagya Pearson r | **0.9228** (monotonic) | Positive growth | ✅ CONFIRMED |
| D★ partial_r | **−0.808** (Karma-controlled) | < −0.5 | ✅ CONFIRMED |
| Karma monotonic | r = **0.9997** · DECAY = 0.002315 | Monotonic | ✅ CONFIRMED |
| Shunyata pruned | **84.3%** monotonic | Monotonic growth | ✅ CONFIRMED |
| mPCI delta | **−0.0427**, threshold = 0.0214 | > 2× std | ✅ CONFIRMED |
| Depth-matched decoupler | **2/3 seeds** below baseline | Honest per-seed | ~ PARTIAL |
| Structural Age Index | **0.824** — Maturing (transition T5) | SAI ∈ [0,1] | ✅ CONFIRMED |
| Cross-substrate DTW | **0.200** < 0.300 threshold | Buddhi invariant | ✅ CONFIRMED |
| Unit tests | **16/16 passing** in 1.56s | All green | ✅ CONFIRMED |

---

## Two Series Constants — Confirmed Across All 11 Papers

### 🔹 Bhaya Quiescence Law

> **Bhaya = 0.000 under replay from Task 1 onwards — every paper, every ablation condition, every seed. Eleven consecutive confirmations.**

```python
am = AffectiveMetrics(df)
result = am.bhaya_quiescence_score()
# → {"law_confirmed": True, "replay_max": 0.000000, "quiescence_rate": 1.0}
```

Bhaya is now a programmatic unit test. If it fires non-zero under replay, `pytest` fails — real-time catastrophic forgetting monitor for any deployed Maya system.

### 🔹 Buddhi S-Curve Determinism

> **Identical 0.750 → 1.000 sigmoid trajectory P4–P9, all ablation conditions, all seeds, SNN and LLM substrates. DTW_norm(SNN↔LLM) = 0.200 < 0.300.**

```python
result = am.buddhi_scurve_fit()
# → {"r_squared": 1.0000, "deterministic": True, "ceiling_task": 1}
```

`S = 1 / (1 + exp(−3.0 × (task − 1.0)))` — the pattern belongs to experience accumulation, not to the substrate.

---

## The Depth-Matched Decoupler (Honest)

Seeds 42 (−0.016) and 7 (−0.029) confirm: affective mPCI is below the depth-matched SGD baseline. **Seed 123's baseline (0.252) was unusually low**, placing the affective model above it (+0.014). This is not a mechanism failure — it reflects seed-level variance in the baseline. The correct aggregate metric is −0.0489 (multi-seed), significant at 2.05× criterion.

maya-metrics reports this honestly per-seed. The depth-matched decoupler is the methodological contribution: it isolates genuine affective complexity from training-depth weight-hardening. No prior tool does this.

---

## The 14 Antahkarana Dimensions

| Dimension | Sanskrit | Paper | Mechanism | Biological Ground |
|-----------|----------|-------|-----------|-------------------|
| **Bhaya** | भय | P1 | Pain-driven hyper-plasticity | Nociceptive metaplasticity |
| **Vairagya** | वैराग्य | P1/P3 | Per-synapse earned protection | Heterosynaptic LTD |
| **Shraddha** | श्रद्धा | P2 | Affective arbitration trust | — |
| **Spanda** | स्पन्द | P2 | OS-level vibrational activation | — |
| **Buddhi** | बुद्धि | P4 | Discriminative S-curve gate | Experience accumulation |
| **Smriti** | स्मृति | P4 | Episodic memory / replay buffer | Hippocampal consolidation |
| **Ahamkara** | अहंकार | P4 | Class-boundary identity | — |
| **Viveka** | विवेक | P5 | Cross-task consistency scoring | GANE neuromodulation |
| **Chitta** | चित्त | P6 | Retrograde gradient gate | Endocannabinoid signalling |
| **Samskara** | संस्कार | P6 | Per-synapse implicit memory trace | Synaptic tagging |
| **Moha** | मोह | P6 | Attachment/release at task boundary | — |
| **Manas** | मनस् | P7 | Oscillatory LIF threshold gate | Thalamo-cortical rhythm |
| **Karma** | कर्म | P8 | Second-order plasticity history | Microglial C1q/C3 |
| **Prana** | प्राण | P9 | Metabolic plasticity budget | Astrocyte-Neuron Lactate Shuttle |

> **The Atma boundary is held explicitly throughout.** This series instantiates the Antahkarana — the instrument. It does not claim the Atma — the witness. Each Maya instance is original, never a replicate.

---

## Architecture

```
maya_metrics/
├── __init__.py              # KARMA_DECAY_RATE = 0.002315 (ORCID magic number)
├── affective.py             # AffectiveMetrics: bhaya_quiescence_score, buddhi_scurve_fit,
│                            #   vairagya_saturation_fraction, karma_accumulation_profile,
│                            #   prana_depletion_profile, chitta_retrograde_rate,
│                            #   manas_oscillatory_efficacy
├── cross_dimensional.py     # CrossDimensional: vairagya_karma_interaction (D★),
│                            #   homeostatic_cascade_score, shunyata_pruning_profile
├── complexity.py            # ComplexityMetrics: phase_delta_summary,
│                            #   depth_matched_decoupler, perturbation_scale_robustness,
│                            #   shuffle_control
├── maturation.py            # MaturationIndex: structural_age, plasticity_transition_rate,
│                            #   senescence_score
├── cross_substrate.py       # CrossSubstrate: buddhi_substrate_invariance (DTW),
│                            #   bhaya_domain_firing
├── cl_corrector.py          # CLCorrector: AA, BWT, FWT (zero-shot + acceleration),
│                            #   intransigence (oracle-enforced), forgetting_measure
└── validator.py             # Pre-computation schema validation
tests/
├── test_affective.py        # 6 tests: Bhaya Law, Buddhi S-curve, Vairagya, Karma, Prana
├── test_complexity.py       # 4 tests: mPCI phase delta, decoupler, scale, shuffle
└── test_cl_corrector.py     # 6 tests: AA, BWT, FWT, Intransigence oracle enforcement
run_dashboard.py             # Flask validation dashboard (localhost:5000)
bootstrap_maya_metrics.py    # Writes complete repo from scratch
```

### Bhaya Quiescence Monitor

```python
# Real-time catastrophic forgetting monitor
am = AffectiveMetrics(df)
bq = am.bhaya_quiescence_score()
if not bq["law_confirmed"]:
    print(f"REPLAY BUFFER FAILURE — Bhaya fired on tasks {bq['violation_tasks']}")
```

---

## Hyperparameter Configuration

| Parameter | Value | Description |
|-----------|-------|-------------|
| `KARMA_DECAY_RATE` | **0.002315** | **ORCID magic number** (0000-0002-3315-7907) |
| `PRANA_COST_RATE` | **0.002315** | **ORCID magic number** |
| `VAIRAGYA_DECAY_RATE` | **0.002315** | **ORCID magic number** |
| Bhaya quiescence tolerance | 1e-4 | Confirmed zero threshold |
| Buddhi S-curve R² threshold | 0.95 | Series constant confirmation |
| Vairagya masking threshold | 0.3 | Maya P3+ canonical |
| D★ partial_r threshold | −0.5 | P8 empirical calibration |
| Cross-substrate DTW threshold | 0.300 | Buddhi invariance criterion |
| SAI Adult threshold | 0.90 | Developmental mapping |
| mPCI significance criterion | 2× std Phase 1 | Maya-mPCI calibration |

**Dashboard R key resets all interactive controls to these canonical values instantly.**

---

## How to Run

### Prerequisites

```
Python 3.9+
numpy >= 1.21.0
scipy >= 1.9.0
pandas >= 1.5.0
flask >= 3.0.0   # dashboard only
pytest >= 7.0.0  # tests only
```

```bash
git clone https://github.com/venky2099/maya-metrics
cd maya-metrics
pip install numpy scipy pandas flask pytest
```

### Run tests

```bash
python -m pytest tests/ -v
```

Expected:
```
tests/test_affective.py::test_bhaya_quiescence_law PASSED
tests/test_affective.py::test_buddhi_scurve_fit PASSED
...
16 passed in 1.56s
```

### Validate against your data

```python
import pandas as pd
from maya_metrics import AffectiveMetrics, CrossDimensional, ComplexityMetrics

df = pd.read_csv("your_run_batches.csv")
am = AffectiveMetrics(df)
print(am.summary())
```

### Live validation dashboard

```bash
python run_dashboard.py \
  --prana  path/to/ablation_D_canonical_batches.csv \
  --mpci   path/to/mpci_summary.csv \
  --ctrl   path/to/mpci_controls_summary.csv \
  --llm    path/to/llm_batches.csv
# Opens http://127.0.0.1:5000 automatically
```

Expected terminal output:
```
[maya-metrics] Running validation suite...
[maya-metrics] Validation complete.
  Bhaya Quiescence Law : CONFIRMED ✓
  Buddhi S-curve       : CONFIRMED ✓
[maya-metrics] Dashboard → http://127.0.0.1:5000
 * Canary: MayaNexusVS2026NLL_Bengaluru_Narasimha
```

---

## IP Protection Stack

1. **White-text watermark** — ORCID + DOI + timestamp embedded in every document before PDF export; includes `LakshmiNarasimha_NLL_2026`
2. **ORCID magic number** — `0.002315` in `KARMA_DECAY_RATE`, `VAIRAGYA_DECAY_RATE`, `PRANA_COST_RATE`
3. **LSB steganographic signature** — every matplotlib figure signed via `sign_paper.py`; payload includes `LakshmiNarasimha_NLL_2026`
4. **Canary string** — `MayaNexusVS2026NLL_Bengaluru_Narasimha` logged at the start of every experiment run

---

## Limitations (Honest)

- **Validation corpus is Maya-specific.** Column mapping API for arbitrary schemas is planned. Researchers with different affective dimension names must map their columns to the expected schema.
- **Depth-matched decoupler: 2/3 seeds.** Seed 123 baseline variance. Multi-seed aggregate (−0.0489) is the correct aggregate metric.
- **Cross-substrate Pearson r is negative (−0.341).** Reflects different sequence lengths (10 tasks vs 8 domains). DTW is the correct metric for unequal-length sequences; Pearson r is displayed for transparency.
- **No hardware-in-the-loop energy.** Spike rate proxy used; actual watt-hours require hardware-specific profiling (pynvml, Loihi SDK).
- **Wetware not supported.** FinalSpark Neuroplatform and biological coprocessors produce continuous analog signals. Extension is a future direction.

---

## Maya Research Series — Complete

| Paper | Title | Key Result | DOI | GitHub | Dashboard |
|-------|-------|------------|-----|--------|-----------|
| P1 | Nociceptive Metaplasticity | Bhaya introduced | [DOI](https://doi.org/10.5281/zenodo.19151563) | — | — |
| P2 | Maya-OS | OS arbitration | [DOI](https://doi.org/10.5281/zenodo.19160123) | [Maya-OS](https://github.com/venky2099/Maya-OS) | — |
| P3 | Maya-CL | AA=62.38% TIL | [DOI](https://doi.org/10.5281/zenodo.19201769) | [Maya-CL](https://github.com/venky2099/Maya-CL) | — |
| P4 | Maya-Smriti | AA=31.84% · Buddhi | [DOI](https://doi.org/10.5281/zenodo.19228975) | [Maya-Smriti](https://github.com/venky2099/Maya-Smriti) | — |
| P5 | Maya-Viveka | AA=16.03% CIFAR-100 | [DOI](https://doi.org/10.5281/zenodo.19279002) | [Maya-Viveka](https://github.com/venky2099/Maya-Viveka) | — |
| P6 | Maya-Chitta | AA=14.42% · retrograde | [DOI](https://doi.org/10.5281/zenodo.19337041) | [Maya-Chitta](https://github.com/venky2099/Maya-Chitta) | [Dashboard](https://venky2099.github.io/Maya-Chitta/maya_chitta_dashboard_v2.html) |
| P7 | Maya-Manas | Best BWT · AA=15.19% | [DOI](https://doi.org/10.5281/zenodo.19363006) | [Maya-Manas](https://github.com/venky2099/Maya-Manas) | [Dashboard](https://venky2099.github.io/Maya-Manas/maya_manas_dashboard.html) |
| P8 | Maya-Shunyata | D★ · AA=10.39% · 59% pruned | [DOI](https://doi.org/10.5281/zenodo.19397010) | [Maya-Shunyata](https://github.com/venky2099/Maya-Shunyata) | [Dashboard](https://venky2099.github.io/Maya-Shunyata/docs/maya_shunyata_dashboard.html) |
| P9 | Maya-Prana | Full Antahkarana · AA=12.72% | [DOI](https://doi.org/10.5281/zenodo.19451174) | [Maya-Prana](https://github.com/venky2099/Maya-Prana) | [Dashboard](https://venky2099.github.io/Maya-Prana/docs/maya_prana_dashboard.html) |
| mPCI | Maya-mPCI | Δ=−0.0489 · 2.05× | [DOI](https://doi.org/10.5281/zenodo.19482794) | [Maya-mPCI](https://github.com/venky2099/Maya-mPCI) | [Dashboard](https://venky2099.github.io/Maya-mPCI/docs/maya_mpci_dashboard.html) |
| LLM | Maya-LLM | Buddhi cross-substrate · BWT=1.11 | [DOI](https://doi.org/10.5281/zenodo.19522348) | [Maya-LLM](https://github.com/venky2099/Maya-LLM) | [Dashboard](https://venky2099.github.io/Maya-LLM/maya_llm_dashboard.html) |
| Tool | cl-metrics | CIL evaluation library | [DOI](https://doi.org/10.5281/zenodo.19388144) | [cl-metrics](https://github.com/venky2099/cl-metrics) | [FAQ](https://venky2099.github.io/cl-metrics/faq.html) |
| **★** | **maya-metrics** | **Affective evaluation library** | [**DOI**](https://doi.org/10.5281/zenodo.19553205) | [**maya-metrics**](https://github.com/venky2099/maya-metrics) | [**Dashboard**](https://venky2099.github.io/maya-metrics/docs/maya_metrics_dashboard.html) |

---

## Citation

```bibtex
@software{swaminathan2026mayametrics,
  title     = {maya-metrics: A Stateless Python Library for
               Affective Neuromorphic Evaluation},
  author    = {Swaminathan, Venkatesh},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.19553205},
  url       = {https://doi.org/10.5281/zenodo.19553205}
}
```

### Cite the Full Series

| Paper | BibTeX key | DOI |
|-------|------------|-----|
| P1 | `swaminathan2026nociceptive` | [10.5281/zenodo.19151563](https://doi.org/10.5281/zenodo.19151563) |
| P2 | `swaminathan2026mayaos` | [10.5281/zenodo.19160123](https://doi.org/10.5281/zenodo.19160123) |
| P3 | `swaminathan2026mayacl` | [10.5281/zenodo.19201769](https://doi.org/10.5281/zenodo.19201769) |
| P4 | `swaminathan2026smriti` | [10.5281/zenodo.19228975](https://doi.org/10.5281/zenodo.19228975) |
| P5 | `swaminathan2026viveka` | [10.5281/zenodo.19279002](https://doi.org/10.5281/zenodo.19279002) |
| P6 | `swaminathan2026chitta` | [10.5281/zenodo.19337041](https://doi.org/10.5281/zenodo.19337041) |
| P7 | `swaminathan2026manas` | [10.5281/zenodo.19363006](https://doi.org/10.5281/zenodo.19363006) |
| P8 | `swaminathan2026shunyata` | [10.5281/zenodo.19397010](https://doi.org/10.5281/zenodo.19397010) |
| P9 | `swaminathan2026mayaprana` | [10.5281/zenodo.19451174](https://doi.org/10.5281/zenodo.19451174) |
| mPCI | `swaminathan2026mpci` | [10.5281/zenodo.19482794](https://doi.org/10.5281/zenodo.19482794) |
| LLM | `swaminathan2026mayallm` | [10.5281/zenodo.19522348](https://doi.org/10.5281/zenodo.19522348) |
| cl-metrics | `swaminathan2026clmetrics` | [10.5281/zenodo.19388144](https://doi.org/10.5281/zenodo.19388144) |

---

## About

**Venkatesh Swaminathan** is an independent AI researcher and founder of Nexus Learning Labs, Bengaluru (UDYAM-KR-02-0122422). M.Sc. Data Science and Artificial Intelligence, BITS Pilani (expected December 2027). ORCID: [0000-0002-3315-7907](https://orcid.org/0000-0002-3315-7907).

The Maya Research Series was built independently, on personal hardware (NVIDIA RTX 4060 8GB), without institutional funding. Eleven papers. One robot. One complete Antahkarana. This library gives the community the tools to measure it.

**If your lab works on neuromorphic systems, continual learning, LLM fine-tuning, or consciousness research — I am interested in talking.**

[venkateshswaminathaniyer@gmail.com](mailto:venkateshswaminathaniyer@gmail.com) · [LinkedIn](https://linkedin.com/in/vensimlee) · [GitHub](https://github.com/venky2099) · [Research Hub](https://venky2099.github.io/)

---

<div align="center">

*Nexus Learning Labs, Bengaluru · 2026*

`MayaNexusVS2026NLL_Bengaluru_Narasimha`

**cl-metrics measures what happened. maya-metrics measures how it felt.**

</div>
