# ahb-sjsu/agi-hpc architecture

> Architecture diagram of the GitHub repository ahb-sjsu/agi-hpc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahb-sjsu/agi-hpc
- Repository: https://github.com/ahb-sjsu/agi-hpc

## Overview

Atlas AI is a distributed cognitive architecture: user requests enter its server, are routed through an ensemble of cloud and local reasoning voices over NATS, and produce responses informed by memory and safety checks. Separate branches support Council deliberation, Erebus learning, Primer tutoring, and dream consolidation. The README documents these capabilities and the shared bus; the source excerpts are mostly from vendored libraries, so implementation-level links among Atlas subsystems are not verified here.

Main entry points: [`atlas-rag-server.py`](https://github.com/ahb-sjsu/agi-hpc/blob/main/atlas-rag-server.py) (Atlas request server), [`src/agi`](https://github.com/ahb-sjsu/agi-hpc/tree/main/src/agi) (vMOE ensemble), [`src/agi/memory`](https://github.com/ahb-sjsu/agi-hpc/tree/main/src/agi/memory) (Memory services), [`src/agi/primer/service.py`](https://github.com/ahb-sjsu/agi-hpc/blob/main/src/agi/primer/service.py) (Primer tutor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Request and routing"]
  node_server["Atlas request server"]
  node_router["Adaptive routing<br/>[adaptive_router.py]"]
end

subgraph group_cognition["Cognitive capabilities"]
  node_ensemble["vMOE ensemble"]
  node_frontier["Frontier models"]
  node_local["Local specialists"]
  node_council["Divine Council"]
  node_safety["ErisML safety<br/>[service.py]"]
  node_erebus["Erebus learning"]
  node_primer["Primer tutor<br/>[service.py]"]
  node_dream["Dream consolidation<br/>[nats_service.py]"]
  node_burst["GPU burst workers"]
end

subgraph group_workspace["Shared workspace"]
  node_nats["NATS JetStream"]
end

subgraph group_knowledge["Memory and learning"]
  node_memory["Memory services"]
  node_postgres[("PostgreSQL + pgvector")]
  node_ukg[("Knowledge graph<br/>[nats_service.py]")]
  node_wiki[("Sensei wiki")]
end

node_user(("User"))

node_user -->|"submits request"| node_server
node_server -.->|"routes request"| node_router
node_router -->|"invokes vMOE"| node_ensemble
node_ensemble -->|"fans out"| node_frontier
node_ensemble -->|"fans out"| node_local
node_ensemble -->|"publishes turns"| node_nats
node_nats -->|"dispatches messages"| node_ensemble
node_frontier -->|"joins via leaf"| node_nats
node_local -->|"subscribes"| node_nats
node_server -.->|"handles decisions"| node_council
node_council -->|"deliberates on"| node_nats
node_server -.->|"handles policy gates"| node_safety
node_server -.->|"handles puzzles"| node_erebus
node_erebus -->|"requests tutoring"| node_primer
node_primer -->|"teaching cycle"| node_nats
node_primer -->|"publishes verified notes"| node_wiki
node_server -.->|"supports consolidation"| node_dream
node_dream -->|"uses shared fabric"| node_nats
node_memory -->|"subscribes and publishes"| node_nats
node_memory -->|"reads and writes"| node_postgres
node_memory -->|"tracks taught and unanswered"| node_ukg
node_server -.->|"returns result"| node_user
node_nats -->|"dispatches workload"| node_burst

click node_server "https://github.com/ahb-sjsu/agi-hpc/blob/main/atlas-rag-server.py"
click node_router "https://github.com/ahb-sjsu/agi-hpc/blob/main/src/agi/metacognition/adaptive_router.py"
click node_ensemble "https://github.com/ahb-sjsu/agi-hpc/tree/main/src/agi"
click node_council "https://github.com/ahb-sjsu/agi-hpc/tree/main/src/agi/reasoning"
click node_safety "https://github.com/ahb-sjsu/agi-hpc/blob/main/src/agi/safety/erisml/service.py"
click node_erebus "https://github.com/ahb-sjsu/agi-hpc/tree/main/src/agi/autonomous"
click node_primer "https://github.com/ahb-sjsu/agi-hpc/blob/main/src/agi/primer/service.py"
click node_dream "https://github.com/ahb-sjsu/agi-hpc/blob/main/src/agi/dreaming/nats_service.py"
click node_memory "https://github.com/ahb-sjsu/agi-hpc/tree/main/src/agi/memory"
click node_ukg "https://github.com/ahb-sjsu/agi-hpc/blob/main/src/agi/memory/nats_service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_router,node_user toneBlue
class node_ensemble,node_frontier,node_local,node_council,node_safety,node_erebus,node_primer,node_dream,node_burst toneAmber
class node_nats toneMint
class node_memory,node_postgres,node_ukg,node_wiki toneRose
```

## Components

### Request and routing

- [Atlas request server](https://github.com/ahb-sjsu/agi-hpc/blob/main/atlas-rag-server.py): `atlas-rag-server.py`
- [Adaptive routing](https://github.com/ahb-sjsu/agi-hpc/blob/main/src/agi/metacognition/adaptive_router.py): `src/agi/metacognition/adaptive_router.py`

### Cognitive capabilities

- [vMOE ensemble](https://github.com/ahb-sjsu/agi-hpc/tree/main/src/agi): `src/agi`
- **Frontier models**
- **Local specialists**
- [Divine Council](https://github.com/ahb-sjsu/agi-hpc/tree/main/src/agi/reasoning): `src/agi/reasoning`
- [ErisML safety](https://github.com/ahb-sjsu/agi-hpc/blob/main/src/agi/safety/erisml/service.py): `src/agi/safety/erisml/service.py`
- [Erebus learning](https://github.com/ahb-sjsu/agi-hpc/tree/main/src/agi/autonomous): `src/agi/autonomous`
- [Primer tutor](https://github.com/ahb-sjsu/agi-hpc/blob/main/src/agi/primer/service.py): `src/agi/primer/service.py`
- [Dream consolidation](https://github.com/ahb-sjsu/agi-hpc/blob/main/src/agi/dreaming/nats_service.py): `src/agi/dreaming/nats_service.py`
- **GPU burst workers**

### Shared workspace

- **NATS JetStream**

### Memory and learning

- [Memory services](https://github.com/ahb-sjsu/agi-hpc/tree/main/src/agi/memory): `src/agi/memory`
- **PostgreSQL + pgvector**
- [Knowledge graph](https://github.com/ahb-sjsu/agi-hpc/blob/main/src/agi/memory/nats_service.py): `src/agi/memory/nats_service.py`
- **Sensei wiki**

### Other components

- **User**

## Connections

- User → Atlas request server: submits request
- Atlas request server → Adaptive routing: routes request (evidence: `atlas-rag-server.py`)
- Adaptive routing → vMOE ensemble: invokes vMOE
- vMOE ensemble → Frontier models: fans out
- vMOE ensemble → Local specialists: fans out
- vMOE ensemble → NATS JetStream: publishes turns
- NATS JetStream → vMOE ensemble: dispatches messages
- Frontier models → NATS JetStream: joins via leaf
- Local specialists → NATS JetStream: subscribes
- Atlas request server → Divine Council: handles decisions (evidence: `atlas-rag-server.py`)
- Divine Council → NATS JetStream: deliberates on
- Atlas request server → ErisML safety: handles policy gates
- Atlas request server → Erebus learning: handles puzzles
- Erebus learning → Primer tutor: requests tutoring
- Primer tutor → NATS JetStream: teaching cycle
- Primer tutor → Sensei wiki: publishes verified notes
- Atlas request server → Dream consolidation: supports consolidation
- Dream consolidation → NATS JetStream: uses shared fabric
- Memory services → NATS JetStream: subscribes and publishes
- Memory services → PostgreSQL + pgvector: reads and writes
- Memory services → Knowledge graph: tracks taught and unanswered (evidence: `src/agi/memory/nats_service.py`)
- Atlas request server → User: returns result
- NATS JetStream → GPU burst workers: dispatches workload