nct

KO | EN

gitlite — search

#python #android #javascript #machine-learning #php #tensorflow #swift #hacktoberfest #java #go #tdd #docker

★ 90 Open GitHub ↗

🧠 NeuroConscious Transformer (NCT) - A next-generation neuromorphic consciousness architecture integrating Transformer with Global Workspace Theory, Predictive Coding, and IIT. | 下一代神经形态意识架构，融合Transformer与全局工作空间、预测编码、整合信息理论。

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🧠 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.2.1-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)](https://raw.githubusercontent.com/wyg5208/nct/main/LICENSE)

**Version**: v3.2.1  
**Created**: February 21, 2026  
**Updated**: April 18, 2026  
**Author**: NCT LAB Team

[中文文档](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
│
├── MCS-NCT框架理论/         # MCS multi-constraint satisfaction framework
│   ├── mcs_solver.py       # MCS core solver
│   └── mcs_nct_integration.py  # NCT integration
│
├── cats_nct/               # CATS-NCT concept abstraction variant
│   ├── core/               # Core modules
│   └── manager.py          # CATS-NCT manager
│
├── 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
│   ├── 教育领域数据集实验论文/  # Education domain experiment papers
│   ├── 教育领域数据集实验结果/  # Education experiment results
│   └── 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×**)

---

## 🔄 Framework Variants & Extensions

### MCS (Multi-Constraint Satisfaction) Framework

MCS reframes consciousness modeling as a **multi-constraint optimization problem**: instead of asking "what is consciousness?", it asks "what constraints must a system satisfy to be conscious?" This operational approach enables quantitative measurement of consciousness levels.

**Core Formulation**:
```
C(t) = argmin_S [ Σᵢ wᵢ·Vᵢ(S,t) ]    # Optimal conscious state
Consciousness Level = 1/(1+J)          # J = weighted constraint violation
```

| Constraint | Definition | Theoretical Basis |
|-----------|-----------|------------------|
| C1 Sensory Consistency | Multi-modal input spatiotemporal alignment | GWT Global Broadcast |
| C2 Temporal Continuity | Current state predictable from history | Predictive Coding + Free Energy |
| C3 Self-Consistency | No contradictions in belief system | Thagard's Coherence Theory |
| C4 Action Feasibility | Intentions mappable to executable plans | Embodied Cognition |
| C5 Social Interpretability | Experiences communicable to others | Vygotsky's Social Origin |
| C6 Integrated Information (Φ) | System Φ exceeds threshold | IIT |

**Key Results**: DAiSEE dataset 5-fold CV **R²=0.164** (121% improvement over NCT Φ baseline)

📁 Core files: `MCS-NCT框架理论/mcs_solver.py`, `mcs_nct_integration.py`  
📄 Paper: *Submitted to IEEE Transactions on Affective Computing*

---

### CATS-NCT (Concept Abstraction & Task Solving)

CATS-NCT fuses **Concept Abstraction (CA) dual-module architecture** with NCT's neuroscience-grounded mechanisms. It extends consciousness modeling from perceptual to **conceptual consciousness**—stable, communicable mental representations.

| Dimension | NCT (Original) | CATS-NCT |
|-----------|----------------|----------|
| Focus | Consciousness generation | Concept formation & communication |
| Representation | Perceptual consciousness | Conceptual consciousness (stable) |
| Integration | Attention-based GWS | CA + TS dual modules |
| Learning | Transformer-STDP | Concept abstraction + STDP |
| Interpretability | Attention maps | Concept prototypes + gating visualization |
| Knowledge Transfer | Not supported | Concept space alignment |

📁 Core files: `cats_nct/core/`, `cats_nct/manager.py`  
🚧 Status: *Under active development*

---

## 🎓 Education Domain Research

### Research Evolution (V1→V4)

**Research Question**: Can NCT architecture effectively monitor cognitive states in educational settings?

| Version | Focus | Key Finding |
|---------|-------|-------------|
| V1 | Concept validation | Framework operational, but Φ non-significant (p>0.05) |
| V2 | Deep learning enhancement | FER +16.84%, but Φ still non-significant (p=0.549) |
| V3 | Systematic diagnosis | **Breakthrough**: EEGNet features make Φ significant (p=0.0003) |
| V4 | Paper & validation | Full ablation study, PCA optimization (p=0.00005, d=0.586) |

### Key Breakthrough

The critical discovery: **Φ (integrated information) becomes a valid cognitive state marker when computed from deep learning (EEGNet) features** rather than traditional spectral features. This bridges IIT theory with practical educational applications.

| Feature Type | Φ Significance | Cohen's d |
|-------------|---------------|-----------|
| Traditional (Welch PSD) | p>0.05 (non-significant) | - |
| EEGNet features | **p=0.0003** | **0.524 (medium)** |
| PCA-reduced (50-dim) | **p=0.00005** | **0.586** |

- **EEGNet classification**: F1=0.62 (vs SVM baseline F1=0.39)
- **Datasets**: MEMA (EEG), DAiSEE (Video), FER2013, EdNet
- 📄 Paper: *Submitted to IEEE Transactions on Affective Computing*

---

## 📊 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/somebody2026-peer/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

---

## 📄 Publications

| Paper | Venue | Status |
|-------|-------|--------|
| MCS: Multi-Constraint Satisfaction Framework for Consciousness Modeling | IEEE Trans. Affective Computing | Under Review |
| Deep Learning Features Enable IIT (Φ) for Cognitive State Monitoring in Education | IEEE Trans. Affective Computing | Under Review |

---

## 📝 Changelog

### v3.2.1 (2026-04-18)
- ✅ Fixed Φ computation mathematical defect: replaced single-sample outer product (rank=1) with batch covariance estimation
- ✅ Added eigenvalue entropy and energy concentration as auxiliary Φ metrics
- ✅ Fixed PredictiveHierarchy GPU device mismatch error (causal mask now supports device parameter)
- ✅ Enhanced Experiment 9: 12 perturbation levels (was 5), 1000 samples (was 200)
- ✅ Added 5 control groups: Gaussian noise, Shuffle features, Random classifier, Frozen intermediate, Temperature scaling
- ✅ H4a hypothesis fully passed: all perturbations significantly reduce Φ (p<0.01, r=-0.78~-0.93)
- ⚠️ **Breaking change**: All experiments using `PhiFromAttention` will produce different results

### v3.2.0 (2026-03-20)
- ✅ Added MCS (Multi-Constraint Satisfaction) consciousness modeling framework
- ✅ Education V4 experiments: EEGNet features enable Φ discrimination (p=0.0003, d=0.524)
- ✅ Two papers submitted to IEEE Transactions on Affective Computing
- ✅ Project restructuring: cleaned root directory, organized scripts
- ✅ Unified version numbers across all config files
- ✅ Fixed GitHub URLs in pyproject.toml
- ✅ Enhanced .gitignore for security (.env) and organization (/temp/)

### 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!**

nct

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README