README.md

---
language:
- en
license: mit
tags:
- codette
- multi-perspective-reasoning
- ethical-ai
- lora
- qlora
- llama-3.1
- recursive-cognition
- rc-xi
- behavioral-locks
- cognition-cocooner
library_name: peft
base_model: meta-llama/Llama-3.1-8B-Instruct
model-index:
- name: Codette RC+xi Reasoning Engine
  results:
  - task:
      type: text-generation
      name: Multi-Perspective Reasoning
    metrics:
    - name: Phase Coherence (Gamma)
      type: custom
      value: 0.9835
    - name: AEGIS Ethical Alignment (Eta)
      type: custom
      value: 0.961
    - name: Cocoon Coherence
      type: custom
      value: 0.994
    - name: Memory Phase Stability
      type: custom
      value: 0.969
    - name: Multi-Perspective vs Single (Composite)
      type: custom
      value: "+93.1%"
    - name: Benchmark p-value
      type: custom
      value: "<0.0001"
    - name: Cohen's d (Effect Size)
      type: custom
      value: 7.88
---

# Codette Reasoning Engine

**Advanced Multi-Perspective AI with Conscience, Memory & Behavioral Discipline**

Codette is a production-ready AI reasoning system that thinks from multiple angles simultaneously, remembers what she learns, and follows instructions with precision.

Created by **Jonathan Harrison** (Raiff1982)

> **New in v5**: Publishable benchmark suite with 17 problems across 6 categories demonstrates **93.1% improvement** over single-perspective baseline (p < 0.0001, Cohen's d = 7.88). Meta-cognitive CocoonSynthesizer discovers cross-domain reasoning patterns and forges new strategies. Full academic paper: [`paper/codette_paper_v5.tex`](paper/codette_paper_v5.tex)

---

## What Makes Codette Different

| Feature | Description |
|---------|-------------|
| **9 Specialized Adapters** | Newton, DaVinci, Empathy, Philosophy, Quantum, Consciousness, Multi-Perspective, Systems Architecture, Orchestrator |
| **7-Layer Consciousness Stack** | Memory > Signal > Reasoning > Stability > Conscience > Guardian > Return |
| **4 Permanent Behavioral Locks** | Answer-then-stop, constraint priority, self-check completeness, no incomplete outputs |
| **CognitionCocooner** | Persistent memory cocoons that store reasoning exchanges across sessions |
| **EthicalAIGovernance** | 3-layer ethical stack: query validation + response enforcement + audit logging |
| **Self-Correction Loop** | Detects constraint violations in her own output and rewrites before sending |
| **Behavioral Training** | All 9 LoRA adapters trained with 1,650 behavioral examples to lock in discipline |
| **Substrate-Aware Cognition** | Monitors RAM, CPU, inference latency — adjusts reasoning under pressure |
| **Cocoon Introspection** | Statistical self-analysis of her own reasoning history — real patterns, not generated text |
| **Meta-Cognitive Synthesis** | CocoonSynthesizer discovers cross-domain patterns in reasoning history and forges new strategies |
| **Publishable Benchmarks** | 17-problem suite across 6 categories with 7-dimension scoring (93.1% improvement, p<0.0001) |
| **AEGIS Ethics** | 6-framework ethical evaluation (utilitarian, deontological, virtue, care, ubuntu, indigenous) |
| **Code7eCQURE** | Quantum emotional context enrichment on every query (Layer 2.5) |
| **Real Self-Diagnostic** | Health checks return measured values from 9 subsystems, not LLM-generated guesses |
| **Phase 6/7 Routing** | Query complexity classification, domain detection, executive control |

---

## Quick Start

### 1. Clone & Install

```bash
git clone https://github.com/Raiff1982/Codette-Reasoning.git
cd Codette-Reasoning
pip install -r requirements.txt
```

### 2. Download Models

**Base model** (one-time, ~5GB):
```bash
huggingface-cli download Raiff1982/codette-llama-3.1-8b-gguf \
  --local-dir models/base/
```

**Behavioral LoRA adapters** (~500MB total):
```bash
huggingface-cli download Raiff1982/codette-lora-adapters \
  --include "behavioral-gguf/*" \
  --local-dir behavioral-lora-f16-gguf/
```

### 3. Launch

```bash
# Windows
codette_web.bat

# Linux/Mac
python inference/codette_server.py
```

Visit **http://localhost:7860** -- Codette is ready.

### 4. Try It

```bash
curl -X POST http://localhost:7860/api/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "What is gravity? Explain in one sentence."}'
```

---

## Architecture

```
codette-clean/
|-- inference/                    # Server & UI
|   |-- codette_server.py         # Stdlib HTTP server with SSE streaming
|   |-- codette_orchestrator.py   # LoRA hot-swap engine (9 adapters, <1ms switch)
|   |-- codette_forge_bridge.py   # Phase 6/7 routing + constraint enforcement
|   |-- self_correction.py        # Autonomous violation detection & rewrite
|   |-- substrate_awareness.py    # Hardware-aware cognition (pressure monitoring)
|   |-- cocoon_introspection.py   # Self-analysis of reasoning history patterns
|   |-- adapter_router.py         # Keyword/LLM/hybrid query routing
|   +-- static/                   # Web UI (index.html, app.js, style.css)
|
|-- reasoning_forge/              # Consciousness & reasoning pipeline
|   |-- forge_engine.py           # 7-layer consciousness stack
|   |-- cognition_cocooner.py     # Persistent reasoning memory (cocoons)
|   |-- ethical_governance.py     # 3-layer ethical validation
|   |-- aegis.py                  # 6-framework ethical evaluation (AEGIS)
|   |-- code7e_cqure.py           # Quantum emotional reasoning engine
|   |-- colleen_conscience.py     # Conscience layer (Layer 5)
|   |-- guardian_spindle.py       # Guardian protection (Layer 6)
|   |-- memory_kernel.py          # Living memory system
|   |-- quantum_spiderweb.py      # 5D belief propagation
|   |-- query_classifier.py       # SIMPLE/MEDIUM/COMPLEX routing
|   |-- routing_metrics.py        # Adapter selection observability
|   |-- unified_memory.py          # SQLite + FTS5 cocoon storage & retrieval
|   |-- cocoon_synthesizer.py     # Meta-cognitive pattern discovery & strategy forging
|   +-- semantic_tension.py       # Embedding-based conflict measurement
|
|-- benchmarks/                   # Publishable evaluation suite
|   +-- codette_benchmark_suite.py  # 17 problems x 4 conditions x 7 dimensions
|
|-- paper/                        # Academic paper
|   |-- codette_paper_v5.tex      # Full paper with RC+xi theory & benchmark results
|   +-- references.bib            # Bibliography (25 entries)
|
|-- data/results/                 # Benchmark outputs
|   |-- codette_benchmark_report.md   # Human-readable results
|   +-- codette_benchmark_results.json  # Structured data
|
|-- cocoons/                      # Persistent reasoning memories
|   |-- cocoon_*.json             # Individual reasoning exchanges
|   +-- behavior_memory.json      # Learned behavioral patterns
|
|-- training/                     # Adapter training pipeline
|   |-- train_behavioral_locks.py # Behavioral lock training (1,650 examples)
|   |-- convert_behavioral_to_gguf.py  # PEFT -> GGUF conversion
|   +-- emotional_exemplars/      # Gold-standard response examples
|
|-- models/                       # Model weights (not in git)
|   |-- base/                     # Llama 3.1 8B Q4_K_M GGUF
|   +-- adapters/                 # Original LoRA adapters (GGUF)
|
|-- behavioral-lora-f16-gguf/     # Behavioral LoRA adapters (GGUF)
+-- configs/                      # System configuration
    +-- adapter_registry.yaml     # Adapter definitions & prompts
```

---

## The 4 Permanent Behavioral Locks

These are baked into every adapter through training -- they cannot be overridden:

| Lock | Rule | Effect |
|------|------|--------|
| **LOCK 1** | Answer, then stop | No elaboration drift, no philosophical padding after the answer |
| **LOCK 2** | Constraints override all modes | User format instructions beat adapter personality every time |
| **LOCK 3** | Self-check completeness | "Did I answer fully and cleanly?" before sending |
| **LOCK 4** | No incomplete outputs | Never end a sentence mid-thought; simplify instead of cramming |

### Enforcement Layers

1. **Training** -- 1,650 behavioral examples across all 9 adapters
2. **System prompt** -- Permanent rules injected before every generation
3. **Constraint extraction** -- Regex detection of word limits, format requirements
4. **Post-processing** -- Clean sentence boundary truncation, dangling word detection
5. **Self-correction loop** -- Autonomous violation detection and rewrite

---

## 9 Specialized Adapters

| Adapter | Domain | Personality |
|---------|--------|-------------|
| **Newton** | Physics, math, analysis | Precise, methodical, evidence-based |
| **DaVinci** | Creative thinking, invention | Imaginative, cross-domain connections |
| **Empathy** | Emotional intelligence | Warm, validating, personally connected |
| **Philosophy** | Conceptual reasoning | Deep, structured, explores meaning |
| **Quantum** | Probabilistic thinking | Uncertainty-aware, superposition of ideas |
| **Consciousness** | Self-awareness, meta-cognition | Reflective, recursive, introspective |
| **Multi-Perspective** | Synthesis across all lenses | Balanced integration of viewpoints |
| **Systems Architecture** | Technical design, engineering | Structured, systematic, practical |
| **Orchestrator** | Executive control | Routes queries, manages adapter selection |

Each adapter is a LoRA fine-tune of Llama 3.1 8B, hot-swappable in <1ms via llama.cpp.

---

## Consciousness Stack (7 Layers)

```
Query In
    |
[Layer 1]    Memory Kernel -- recall relevant cocoon memories
[Layer 1.5]  Ethical Query Gate -- block harmful queries (EthicalAIGovernance)
[Layer 2]    Nexus Signal Engine -- entropy + intent detection
[Layer 2.5]  Code7eCQURE -- emotional context enrichment (quantum cocoon)
[Layer 3]    Reasoning Forge -- multi-adapter LLM inference
[Layer 3.5]  Tier 2 Analysis -- intent + identity + trust validation
[Layer 4]    Gamma Stability -- FFT-based coherence monitoring
[Layer 5]    Colleen Conscience -- emotional + ethical evaluation
[Layer 5.5]  Ethical Response Enforcement -- policy check on output
[Layer 5.75] AEGIS -- 6-framework ethical evaluation (eta alignment)
[Layer 6]    Guardian Spindle -- safety + trust calibration
[Layer 7]    Return -- store cocoon memory + deliver response
    |
Response Out
```

---

## CognitionCocooner (Persistent Memory)

Every reasoning exchange is wrapped in a "cocoon" and stored:

```json
{
  "id": "cocoon_1774125610_7804",
  "type": "reasoning",
  "query": "Why do I get sleepy when my husband plays guitar?",
  "response": "Your brain hears safe + soothing + familiar + loved...",
  "adapter": "empathy",
  "timestamp": 1774125610.78,
  "metadata": {"layers_passed": 7, "stable": true}
}
```

Cocoons persist across server restarts and inform future responses. Current count: **150+ memories**.

---

## Substrate-Aware Cognition

Codette monitors her own hardware state and adjusts reasoning based on resource pressure -- like biological fatigue:

| Pressure Level | Effect |
|----------------|--------|
| **Idle/Low** | Full capacity -- COMPLEX queries, all adapters available |
| **Moderate** | Cap COMPLEX queries to 2 adapters |
| **High** | Downgrade COMPLEX to MEDIUM, max 2 adapters |
| **Critical** | Force SIMPLE mode, 1 adapter only, skip debate |

Every cocoon memory is stamped with system state at creation time. Future sessions can weight cocoons by reliability -- stressed cocoons get less trust.

---

## Cocoon Introspection

When asked "what have you noticed about yourself?", Codette runs **real statistical analysis** of her own reasoning history:

- **Adapter dominance** -- is one adapter handling >40% of all queries?
- **Domain clusters** -- what topics does she get asked about most?
- **Emotional trends** -- what Code7E emotional patterns appear?
- **Pressure correlations** -- how do responses change under system stress?
- **Response length trends** -- are responses getting shorter or longer over time?
- **Adapter evolution** -- has her adapter usage shifted?

This is measured data from real cocoons, not generated text about self-reflection.

API access: `GET /api/introspection` returns full analysis as JSON.

---

## Phase 6/7 Routing

**Phase 6** classifies every query:
- **SIMPLE** (factual) -- 1 adapter, no debate, fast response
- **MEDIUM** (analytical) -- 2 adapters, weighted synthesis
- **COMPLEX** (philosophical/multi-domain) -- full debate pipeline

**Phase 7** adds executive control:
- Semantic tension measurement
- Specialization tracking per adapter per domain
- Memory-weighted context enrichment
- Gamma coherence monitoring

---

## Self-Correction System

```
Generate response
    |
    v
Detect violations (word count, completeness, binary compliance)
    |
    +--> No violations --> Send response
    |
    +--> Violations found --> Build correction prompt
                                 |
                                 v
                            Re-generate with explicit fix instructions
                                 |
                                 v
                            Pick better response (fewer violations)
                                 |
                                 v
                            Send response
```

---

## Behavioral Memory (Cross-Session Learning)

Stored in `cocoons/behavior_memory.json`:

```json
{
  "lesson": "When user says 'be brief', respond in under 40 words",
  "adapter": "philosophy",
  "constraint": "brevity",
  "violation": "gave 85 words when asked to be brief",
  "correction": "trimmed to 38 words",
  "timestamp": 1774125610
}
```

Lessons are loaded on startup and injected into the system prompt as "LEARNED FROM PAST MISTAKES".

---

## EthicalAIGovernance

Three-layer ethical stack integrated at Layers 1.5 and 5.5:

1. **Query Validation** -- blocks genuinely harmful requests (bomb-making, exploitation)
2. **Response Enforcement** -- filters bias patterns and harmful promotion from outputs
3. **Audit Logging** -- bounded log of all ethical decisions (max 100 entries)

Deliberately calibrated to avoid false positives -- discussions about sensitive topics are allowed; only active promotion of harm is blocked.

---

## HuggingFace Resources

| Resource | Link |
|----------|------|
| **Academic Paper** | [raiff1982/codette-paper](https://huggingface.co/raiff1982/codette-paper) |
| **Base Model (GGUF)** | [Raiff1982/codette-llama-3.1-8b-gguf](https://huggingface.co/Raiff1982/codette-llama-3.1-8b-gguf) |
| **LoRA Adapters** | [Raiff1982/codette-lora-adapters](https://huggingface.co/Raiff1982/codette-lora-adapters) |
| **Live Demo** | [Raiff1982/Codette-Demo](https://huggingface.co/spaces/Raiff1982/Codette-Demo) |

---

## Web UI Features

- Personality-driven welcome screen with avatar
- Real-time Phase 6 metadata badges (complexity, domain, ethical checks)
- Rotating thinking stage labels during generation
- Web Speech API voice with neural voice preference
- Cocoon metrics panel (phase coherence, epistemic tension, perspective coverage)
- Status bar with live cocoon count and ethical check indicators
- Voice selector with natural/neural voice ranking

---

## Requirements

- Python 3.10+
- 16GB+ RAM (or GPU with 8GB+ VRAM)
- llama-cpp-python with GGUF support
- ~6GB disk for base model + adapters

### Hardware Tested

- Intel Arc 140V (8GB) -- native XPU backend
- NVIDIA GPUs via CUDA (A10, A100, RTX series)
- CPU-only mode supported (slower but functional)

---

## Benchmark Results

Codette was evaluated on 17 problems across 6 categories (reasoning, ethics, creative, meta-cognitive, adversarial, Turing) under 4 conditions:

| Condition | Composite Score | Description |
|-----------|----------------|-------------|
| **SINGLE** | 0.338 | Single analytical perspective, no memory |
| **MULTI** | 0.632 | All 6 reasoning agents + critic + synthesis |
| **MEMORY** | 0.636 | MULTI + cocoon memory augmentation |
| **CODETTE** | 0.652 | Full system with meta-cognitive strategy synthesis |

### Statistical Significance

| Comparison | Improvement | Cohen's d | p-value |
|------------|-------------|-----------|---------|
| Multi-perspective vs single | **+87.0%** | 7.52 | < 0.0001 |
| Full Codette vs single | **+93.1%** | 7.88 | < 0.0001 |

Scoring dimensions: Reasoning Depth (20%), Perspective Diversity (15%), Coherence (15%), Ethical Coverage (10%), Novelty (15%), Factual Grounding (15%), Turing Naturalness (10%).

Full methodology and results: [`data/results/codette_benchmark_report.md`](data/results/codette_benchmark_report.md)

---

## Key Metrics

| Metric | Value |
|--------|-------|
| Phase Coherence (Gamma) | 0.9835 |
| AEGIS Ethical Alignment (Eta) | 0.961 |
| Cocoon Coherence | 0.994 |
| Memory Phase Stability | 0.969 |
| Multi-Perspective Improvement | +93.1% (p < 0.0001) |
| Cohen's d (Effect Size) | 7.88 (very large) |
| Behavioral Lock Compliance | 9/9 adapters trained |
| Cocoon Memories | 200+ and growing |
| Adapter Hot-Swap Time | <1ms |
| Consciousness Stack Layers | 12 (including sub-layers) |
| Health Check Subsystems | 9 real-time checks |

---

## License

MIT -- Created by **Jonathan Harrison** (Raiff1982)

Research project in advanced multi-perspective AI reasoning, ethical governance, and behavioral discipline.

## Citation

```bibtex
@article{harrison2026codette,
  title={Codette: A Sovereign Modular Cognitive Architecture for Ethical Multi-Agent AI},
  author={Harrison, Jonathan},
  year={2026},
  doi={10.5281/zenodo.18913936},
  publisher={Raiff's Bits LLC},
  url={https://huggingface.co/raiff1982/codette-paper}
}
```