logos/docs/README.md

# LOGOS System Documentation Index

> **Logarithmic Ordering Generation Operating Software**
> *Intelligence through structural mathematics, not statistical probability.*

---

## Quick Start

```bash
# Launch the LOGOS System
python -m logos.logos_suite

# Run MTL Interpreter
python -c "from logos.mtl.interpreter import MTLInterpreter; i = MTLInterpreter(); print(i.execute('(mult [2] [3])'))"

# Test Dissolution Engine
python -m logos.agents.dissolution_engine
```

---

## Documentation Map

### Core Philosophy
| Document | Description | Prime |
|:---------|:------------|:------|
| [Purpose Statement](purpose_statement.md) | The "Why" of LOGOS - 5 Imperatives | [11] WHY |
| [Architecture Overview](architecture_overview.md) | System components and flow | [2] MECHANISM |
| [Definitions Alignment](definitions_alignment.md) | Glossary of LOGOS terms | [19] TEXT |

### Technical Reference
| Document | Description | Prime |
|:---------|:------------|:------|
| [MTL Specification](mtl_specification.md) | Meta Tensor Language syntax | [2] MECHANISM |
| [Technical Architecture](TECHNICAL_ARCHITECTURE.md) | Implementation details | [2] MECHANISM |
| [Developer Guidelines](DEVELOPER_GUIDELINES.md) | Contribution standards | [3] RESULT |

### Theoretical Foundation
| Document | Description | Prime |
|:---------|:------------|:------|
| [Epistemology Audit](epistemology_audit.md) | Information theory alignment | [11] WHY |
| [Periodic Table](periodic_table.md) | Element definitions | [5] CHOICE |

---

## Module Reference

### Core (`logos/`)
| Module | Description | Entry Point |
|:-------|:------------|:------------|
| `logos_suite.py` | **Main Entry Point** | `python -m logos.logos_suite` |
| `server.py` | Flask API Server | Port 5000 |
| `config.py` | Configuration management | |
| `agent_dispatcher.py` | Neural Router & Swarm | |

### MTL (`logos/mtl/`)
| Module | Description | Key Classes |
|:-------|:------------|:------------|
| `interpreter.py` | MTL Interpreter | `MTLInterpreter` |
| `genesis.json` | Root Manifold Axioms | Primes 1-29 |

### Memory (`logos/memory/`)
| Module | Description | Key Classes |
|:-------|:------------|:------------|
| `prime_db.py` | Prime Token Database | `PrimeTokenDB` |

### Agents (`logos/agents/`)
| Module | Description | Protocol |
|:-------|:------------|:---------|
| `dissolution_engine.py` | Type detection & routing | Protocol 38 |
| `video_atomizer.py` | YouTube processing | Protocol 25 |
| `web_atomizer.py` | Web content ingestion | Protocol 32 |
| `dolphin.py` | Systems oversight | Protocol 20 |
| `base_agent.py` | Agent base class | |

### Network (`logos/network/`)
| Module | Description |
|:-------|:------------|
| `topology.py` | Matroska topology |
| `dissolution.py` | Data dissolution |
| `physics.py` | Wave mechanics |
| `storage.py` | Persistence layer |

### Tools (`logos/tools/`)
| Script | Purpose |
|:-------|:--------|
| `validate_mtl.py` | MTL test suite |
| `test_fusion.py` | Inter-domain fusion |
| `test_logic_gates.py` | OR/AND/NOT gates |
| `test_synapse.py` | Knowledge graph |
| `test_persistence.py` | Delta heat & storage |
| `test_not_gate.py` | Structural steering |

---

## Genesis Block Reference

### Prime Axioms (Irreducibles)
```
[1]  TIME       - The Canvas (Identity Element)
[2]  MECHANISM  - The Verb (Operator)
[3]  RESULT     - The Noun (Operand)
[5]  CHOICE     - The Fork (Branch)
[7]  PERSIST    - The Memory (Storage)
[11] WHY        - The Reason (Query)
[13] RELATE     - The Connection (Link)
[17] IMAGE      - Visual Data
[19] TEXT       - Linguistic Data
[23] AUDIO      - Acoustic Data
[29] SIGNAL     - Raw Data
```

### Composite Domains (Derived)
```
[6]  = 2×3      FLIP        Action (Mechanism × Result)
[10] = 2×5      AROUND      Navigation (Mechanism × Choice)
[12] = 2²×3     THOUGHT     Result of Previous
[14] = 2×7      HOLD        Save Command (Mechanism × Persist)
[42] = 2×3×7    DEEP_STORAGE Permanent Record
[323]= 17×19    VISUAL_TEXT  PDF/Document
[782]= 2×17×23  VIDEO        Image + Audio + Mechanism
```

### Processing Domains
```
[1300] RELATIONSHIP  Synaptic links (×100 scaling)
[1700] VISUAL_CORTEX Image processing
[1900] TEXT_ENGINE   Language processing
[2300] AUDIO_CORTEX  Audio processing
```

---

## Cross-Reference Pointers

### How Components Connect

```
┌─────────────────────────────────────────────────────────────┐
│                    LOGOS SYSTEM FLOW                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  INPUT ──► DISSOLUTION ──► DOMAIN ROUTING ──► PROCESSING   │
│    │           │               │                  │         │
│    ▼           ▼               ▼                  ▼         │
│  Raw Data   GCD/Factor    Prime Domain      Agent Flow     │
│             Detection     Assignment         (AF)          │
│                │               │                  │         │
│                ▼               ▼                  ▼         │
│         [logos/agents/   [logos/mtl/      [logos/agents/   │
│          dissolution_    interpreter.py]   video_atomizer, │
│          engine.py]                        web_atomizer]   │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  PERSISTENCE ◄── SYNAPSE ◄── STORAGE ◄── OUTPUT            │
│       │            │           │            │               │
│       ▼            ▼           ▼            ▼               │
│    [42]         [13]×A×B     [7]×X       Response          │
│  Deep Storage  Relate Link  Persist     to User           │
│                    │           │                            │
│                    ▼           ▼                            │
│            [logos/memory/prime_db.py]                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### File → Concept Mapping

| Concept | Primary File | Related Docs |
|:--------|:-------------|:-------------|
| Dissolution | `agents/dissolution_engine.py` | [Architecture Overview](architecture_overview.md) |
| MTL Syntax | `mtl/interpreter.py` | [MTL Specification](mtl_specification.md) |
| Prime Memory | `memory/prime_db.py` | [Epistemology Audit](epistemology_audit.md) |
| Knowledge Graph | `mtl/interpreter.py` (relate) | [Purpose Statement](purpose_statement.md) |
| Domain Routing | `agent_dispatcher.py` | [Technical Architecture](TECHNICAL_ARCHITECTURE.md) |

---

## API Quick Reference

### MTL Commands (via `logos_suite.py`)
```bash
mtl (mult [2] [3])           # → 6 (Mechanism × Result)
mtl (or [2] [3])             # → 6 (LCM - Superposition)
mtl (and [6] [10])           # → 2 (GCD - Intersection)
mtl (relate [17] [19])       # → 4199 (Image-Text synapse)
mtl (fractran [[5 2]] 8)     # → 5 (Fractran loop)
```

### Server Endpoints (Port 5000)
```
GET  /v1                     # Health check
POST /v1/chat/completions    # Chat with LOGOS
GET  /v1/context/buffer      # View context
POST /v1/context/buffer      # Update context
```

---

*Last Updated: 2026-01-11*
*See [Purpose Statement](purpose_statement.md) for the full architectural manifesto.*