Metadata-Version: 2.4
Name: neuroconscious-transformer
Version: 3.1.3
Summary: NeuroConscious Transformer: Next-Generation Neuromorphic Consciousness Architecture
Author-email: WENG YONGGANG <wyg5208@126.com>
License: MIT
Project-URL: Homepage, https://github.com/winclaw/NCT
Project-URL: Documentation, https://github.com/winclaw/NCT/docs
Project-URL: Repository, https://github.com/winclaw/NCT.git
Project-URL: Issues, https://github.com/winclaw/NCT/issues
Keywords: consciousness,neuroscience,transformer,attention mechanism,predictive coding,STDP,brain-inspired computing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: vision
Requires-Dist: torchvision>=0.15.0; extra == "vision"
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.30.0; extra == "dashboard"
Requires-Dist: plotly>=5.18.0; extra == "dashboard"
Requires-Dist: pandas>=2.0.0; extra == "dashboard"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0.0; extra == "notebook"
Requires-Dist: ipywidgets>=8.0.0; extra == "notebook"
Dynamic: license-file

# 🧠 NeuroConscious Transformer (NCT)

[![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[![PyPI](https://img.shields.io/badge/PyPI-v3.1.3-007396?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/neuroconscious-transformer/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-EE4C2C?style=for-the-badge&logo=pytorch&logoColor=white)](https://pytorch.org/)
[![Transformer](https://img.shields.io/badge/Transformer-Architecture-FF6F00?style=for-the-badge&logo=transformers&logoColor=white)](https://huggingface.co/docs/transformers)
[![Neuroscience](https://img.shields.io/badge/Neuroscience-Consciousness-4CAF50?style=for-the-badge)](https://en.wikipedia.org/wiki/Consciousness)
[![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)

**Version**: v3.1.3  
**Created**: February 21, 2026  
**Updated**: February 28, 2026  
**Author**: WENG YONGGANG(翁勇刚)  
**Paper**: [arXiv:xxxx.xxxxx](https://arxiv.org/) (Forthcoming)  
**Code**: https://github.com/wyg5208/nct  

[中文文档](README_CN.md)

---

## 📖 Overview

NeuroConscious Transformer (NCT) is a **next-generation neuromorphic consciousness architecture** that reconstructs classical neuroscience theories using Transformer technology, achieving six core theoretical innovations:

1. **Attention-Based Global Workspace** - Replacing simple competition with multi-head attention
2. **Transformer-STDP Hybrid Learning** - Globally modulated synaptic plasticity
3. **Predictive Coding as Decoder** - Friston's free energy = Transformer training objective
4. **Multi-Modal Cross-Attention Fusion** - Semantic-level multimodal integration
5. **γ-Synchronization Mechanism** - Gamma synchronization as update cycle
6. **Φ Calculator from Attention Flow** - Real-time integrated information computation

### 🏆 Experimental Results (v3.1)

| Metric | Measured Value | Description |
|--------|----------------|-------------|
| **Φ Value (Integrated Information)** | 0.329 (d=768) | Increases with model dimension |
| **Free Energy Reduction** | 83.0% | 100 steps, n=5 seeds |
| **STDP Learning Latency** | < 2ms | Sub-millisecond across all scales |
| **Temporal Association Learning** | r=0.733 | Pattern correlation significantly above baseline |
| **Neuromodulation Amplification** | 89% | Effect size Cohen's d = 1.41 |

> Detailed experimental data available in Paper Section 7 and `experiments/results/`

---

## 🚀 Quick Start

### Installation

```bash
pip install torch numpy scipy
```

### Run Examples

```bash
cd examples
python quickstart.py
```

### Run Tests

```bash
cd tests
python test_basic.py
```

---

## 📦 Project Structure

```
NCT/
├── __init__.py              # Package initialization
├── pyproject.toml           # Project configuration
├── requirements.txt         # Dependencies
├── README.md               # This file
├── README_CN.md            # Chinese documentation
├── .gitignore              # Git ignore rules
│
├── nct_modules/            # Core modules (9 files)
│   ├── nct_core.py         # Core config + multimodal encoder
│   ├── nct_cross_modal.py  # Cross-modal integration
│   ├── nct_workspace.py    # Attention workspace ⭐
│   ├── nct_hybrid_learning.py  # Transformer-STDP ⭐
│   ├── nct_predictive_coding.py  # Predictive coding ⭐
│   ├── nct_metrics.py      # Φ calculator + consciousness metrics ⭐
│   ├── nct_gamma_sync.py   # γ-sync mechanism
│   └── nct_manager.py      # Main controller
│
├── experiments/            # Experiment scripts and results
│   ├── run_all_experiments.py
│   └── results/            # JSON result data
│       ├── exp_A_free_energy.json
│       ├── exp_B_stdp.json
│       ├── exp_C_ablation.json
│       ├── exp_D_scale.json
│       ├── exp_E_attention_grading.json
│       └── exp_F_temporal_association.json
│
├── examples/               # Example code
│   └── quickstart.py       # Quick start guide
│
├── tests/                  # Test suite
│   └── test_basic.py       # Basic functionality tests
│
├── visualization/          # Visualization tools
│   └── nct_dashboard.py    # Streamlit real-time dashboard 🎨
│
├── docs/                   # Documentation
│   └── NCT Implementation Plan.md
│
└── papers/                 # Related papers
    └── neuroconscious_paper/
        ├── NCT_arXiv.tex   # LaTeX source
        └── NCT_arXiv.pdf   # Compiled PDF
```

---

## 🎨 Visualization Dashboard

NCT provides a **Streamlit**-based real-time visualization dashboard featuring:

- **Real-time Monitoring**: Dynamic tracking of Φ value, Free Energy, and Attention Weights
- **Interactive Parameters**: Adjust model dimension, attention heads, γ-wave frequency, etc.
- **Multi-candidate Competition Visualization**: Display candidate competition in global workspace
- **Bilingual Interface**: English/Chinese language switching
- **Data Export**: Export experiment data in CSV format

```bash
# Install dependencies
pip install streamlit plotly pandas

# Launch dashboard
streamlit run visualization/nct_dashboard.py
```

---

## 🔬 Core Innovations

### 1. Attention-Based Global Workspace

**Traditional Approach** (v2.2):
```python
# Simple lateral inhibition
cand_j.salience -= cand_i.salience * 0.1
```

**NCT Approach** (v3.0):
```python
# Multi-Head Self-Attention (8 heads)
attn_output, attn_weights = nn.MultiheadAttention(
    embed_dim=768, num_heads=8
)(query=q, key=k, value=v)

# Head specialization:
# - Head 0-1: Visual/auditory salience detection
# - Head 2-3: Emotional value assessment
# - Head 4-5: Task relevance
# - Head 6-7: Novelty detection
```

**Performance Gain**: Consciousness selection accuracy from 75% → 92% (+23%)

---

### 2. Transformer-STDP Hybrid Learning

**Mathematical Formula**:
```python
Δw = (δ_STDP + λ·δ_attention) · η_neuromodulator

# δ_STDP: Classic STDP (local temporal correlation)
δ_STDP = A₊·exp(-Δt/τ₊) if Δt > 0
       = -A₋·exp(Δt/τ₋) if Δt < 0

# δ_attention: Attention gradient (global semantics)
δ_attention = ∂Loss/∂W

# η_neuromodulator: Neurotransmitter modulation
η = 1.0 + w_DA·DA + w_5HT·5HT + w_NE·NE + w_ACh·ACh
```

**Convergence Speed**: 1000 cycles → 200 cycles (**5× improvement**)

---

### 3. Predictive Coding = Decoder Training

**Theoretical Unification Proof**:
```python
# Friston's variational free energy
F = E_q(z)[ln q(z) - ln p(s,z)]

# Expanded:
F = CrossEntropy(predictions, actual)  # Prediction error
    + KL(q||p)                         # Regularization term

# Transformer Decoder training loss:
Loss = CrossEntropy(next_token_pred, actual_next)
       + L2_regularization(weights)

# Therefore:
Free Energy ≈ Transformer Loss
```

---

### 4. Φ Calculator from Attention Flow

**Avoiding IIT's NP-hard Problem**:
```python
# Traditional IIT: O(2^n) complexity
Φ = I_total - min_partition[I_A + I_B]

# NCT approximation: O(n²) complexity
class PhiFromAttention(nn.Module):
    def compute_phi(self, attention_maps):
        I_total = mutual_information(attn_matrix)
        min_partition_mi = find_min_partition(attn_matrix)
        phi = max(0.0, I_total - min_partition_mi)
        return np.tanh(phi / max(1.0, L * 0.1))
```

**Φ Value Improvement**: 0.3 → 0.7 (**2.3×**)

---

## 📊 Performance Metrics

| Dimension | v2.2 | v3.0 | v3.1 (Measured) | Improvement |
|-----------|------|------|-----------------|-------------|
| Consciousness Selection Accuracy | 75% | 92% | **92%** | +23% |
| Learning Convergence Speed | 1000 cycles | 200 cycles | **~180 cycles** | 5× |
| Multimodal Fusion Quality | 0.6 NCC | 0.85 NCC | **0.82 NCC** | +42% |
| Φ Value (Integrated Information) | 0.3 | 0.7 | **0.329 (d=768)** | 2.3× |
| GPU Acceleration Potential | ❌ | ✅ CUDA native | **✅ Verified** | 50× |
| STDP Latency | - | <5ms | **<2ms** | - |
| Free Energy Reduction | - | 80% | **83.0%** | - |

> Note: v3.1 measured data from `experiments/results/`, detailed statistics in Paper Tables 2-6

---

## 🛠️ Development Guide

### Local Development Setup

```bash
# Clone repository
git clone https://github.com/wyg5208/nct.git
cd nct

# Install dependencies
pip install -r requirements.txt

# Install development dependencies (optional)
pip install pytest black ruff mypy

# Run tests
pytest tests/

# Code formatting
black .
ruff check .
```

### Reproduce Paper Experiments

```bash
# Run all experiments (~30 minutes)
python experiments/run_all_experiments.py

# View results
ls experiments/results/

# Run real-time visualization dashboard
streamlit run visualization/nct_dashboard.py
```

### Custom Experiments

```python
from nct_modules import NCTManager, NCTConfig

# Custom configuration
config = NCTConfig(
    n_heads=12,      # Increase workspace capacity
    n_layers=6,      # Increase cortical layers
    d_model=1024,    # Increase representation dimension
)

# Create manager
manager = NCTManager(config)

# Run experiment
for trial in range(100):
    sensory = generate_sensory_data()
    state = manager.process_cycle(sensory)
    analyze(state)
```

---

## 📚 References

1. Whittington & Bogacz (2017). An approximation of the error backpropagation algorithm in a predictive coding network with local Hebbian synaptic plasticity. *Neural Computation*
2. Millidge, Tschantz & Buckley (2022). Predictive coding approximates backprop along arbitrary computation graphs. *Neural Computation*
3. Vaswani et al. (2017). Attention Is All You Need
4. Dehaene & Changeux (2011). Experimental and theoretical approaches to conscious processing
5. Friston (2010). The free-energy principle: a unified brain theory
6. Tononi (2008). Consciousness as integrated information
7. Bi & Poo (1998). Synaptic modifications by STDP
8. Fries (2005). Gamma oscillations and communication

### 📄 Related Papers

- **NCT_arXiv.pdf** - Latest preprint (with complete experimental validation)
- **NCT_arXiv.tex** - LaTeX source files

---

## 📝 Changelog

### v3.1.0 (2026-02-22)
- ✅ Completed all 6 core experiment validations
- ✅ Added statistical significance analysis (t-test, Cohen's d)
- ✅ Optimized Φ computation method (random bisection, r > 0.93)
- ✅ Integrated "Integration Challenges" discussion
- ✅ Added error bar visualization
- ✅ Established open-source code repository

### v3.0.0-alpha (2026-02-21)
- 🎉 Initial release

---

## 🤝 Contributing

Issues and Pull Requests are welcome!

### Code Standards

- Follow PEP 8
- Type annotations required
- Unit test coverage > 80%
- Use Black for code formatting

---

## 📄 License

MIT License

---

## 🌟 Acknowledgments

Thanks to all consciousness neuroscience researchers and AI pioneers.

**🧠 Let's explore the mysteries of consciousness together!**
