# aminshahsaheb/fanus-living-seal architecture

> Architecture diagram of the GitHub repository aminshahsaheb/fanus-living-seal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aminshahsaheb/fanus-living-seal
- Repository: https://github.com/aminshahsaheb/fanus-living-seal

## Overview

Fānus is an epistemic AI runtime: its main interaction loop records user input, searches a knowledge gateway, generates a response, stores that response, and applies cognitive and guardian checks before returning it. The repository also documents a memory pipeline, research and growth capabilities, runtime safety and evolution, and a separate verification/audit capability. Edges are limited to relationships visible in the excerpts or SOURCE INDEX; documented but unsampled subsystems are shown without guessed call paths.

Main entry points: [`fanus/main.py`](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/main.py) (Fanus System), [`fanus/memory/pipeline.py`](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/pipeline.py) (Memory Pipeline), [`fanus/audit/audit_engine.py`](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/audit/audit_engine.py) (Audit Engine), [`fanus/cognitive/guardian_pipeline.py`](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/guardian_pipeline.py) (Guardian Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction Runtime"]
  node_main["Fanus System<br/>[main.py]"]
  node_loop["Runtime Loop<br/>[loop.py]"]
  node_llm["Groq Adapter<br/>[groq_adapter.py]"]
  node_identity["System Identity<br/>[identity.py]"]
end

subgraph group_knowledge["Knowledge and Memory"]
  node_gateway["Knowledge Gateway"]
  node_memory_pipeline["Memory Pipeline<br/>[pipeline.py]"]
  node_evidence["Evidence Engine<br/>[evidence_engine.py]"]
  node_beliefs["Belief Layer<br/>[belief_layer.py]"]
  node_ledger[("Memory Ledger<br/>[ledger.py]")]
  node_knowledge_graph[("Knowledge Graph<br/>[knowledge_graph.py]")]
  node_persistence[("Memory Persistence<br/>[persistence.py]")]
end

subgraph group_cognition["Cognitive Governance"]
  node_orchestrator["Cognitive Orchestrator<br/>[orchestrator.py]"]
  node_guardians["Guardian Pipeline"]
  node_policy["Policy Engine<br/>[policy_engine.py]"]
  node_hayrat["Hayrat Judge<br/>[hayrat_judge.py]"]
  node_fi_detector["Flattery Detection<br/>[fi_detector.py]"]
  node_negar["Negar Detection<br/>[negar_detector.py]"]
  node_isp["Identity Safeguards<br/>[isp_controller.py]"]
  node_growth["Cognitive Growth"]
end

subgraph group_runtime["Runtime Evolution"]
  node_runtime_safety["Runtime Safety"]
  node_observer["Runtime Observer"]
  node_evolution["Evolution Engine"]
end

subgraph group_verification["Verification"]
  node_audit_api["Audit Engine<br/>[audit_engine.py]"]
  node_api["Verify API<br/>[server.py]"]
end

node_user(("User"))

node_user -->|"submits input"| node_main
node_main -->|"stores input and response"| node_memory_pipeline
node_main -->|"searches knowledge"| node_gateway
node_main -->|"ticks runtime"| node_loop
node_main -->|"loads identity prompt"| node_identity
node_main -->|"generates response"| node_llm
node_main -->|"processes exchange"| node_orchestrator
node_main -->|"checks response"| node_guardians
node_main -->|"evaluates signals"| node_policy
node_main -->|"checks identity risk"| node_isp
node_main -->|"revises response"| node_hayrat
node_memory_pipeline -->|"evaluates evidence"| node_evidence
node_memory_pipeline -->|"records belief"| node_beliefs
node_memory_pipeline -->|"records entry"| node_ledger
node_memory_pipeline -->|"adds entity"| node_knowledge_graph
node_memory_pipeline -->|"restores and saves"| node_persistence
node_guardians -->|"runs detection"| node_fi_detector
node_guardians -->|"runs detection"| node_negar
node_guardians -->|"runs judgment"| node_hayrat
node_audit_api -->|"evaluates claims"| node_evidence
node_audit_api -->|"updates beliefs"| node_beliefs
node_audit_api -->|"judges uncertainty"| node_hayrat
node_audit_api -->|"evaluates signals"| node_policy
node_api -.->|"offers verification"| node_audit_api
node_gateway -.->|"retrieves sources"| node_user

click node_main "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/main.py"
click node_loop "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/runtime/loop.py"
click node_llm "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/adapters/groq_adapter.py"
click node_identity "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/core/identity.py"
click node_gateway "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/adapters/knowledge_gateway.py"
click node_memory_pipeline "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/pipeline.py"
click node_evidence "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/evidence_engine.py"
click node_beliefs "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/belief_layer.py"
click node_ledger "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/ledger.py"
click node_knowledge_graph "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/knowledge_graph.py"
click node_persistence "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/persistence.py"
click node_orchestrator "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/orchestrator.py"
click node_guardians "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/guardian_pipeline.py"
click node_policy "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/policy_engine.py"
click node_hayrat "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/hayrat_judge.py"
click node_fi_detector "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/fi_detector.py"
click node_negar "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/negar_detector.py"
click node_isp "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/isp_controller.py"
click node_growth "https://github.com/aminshahsaheb/fanus-living-seal/tree/main/fanus/cognitive"
click node_runtime_safety "https://github.com/aminshahsaheb/fanus-living-seal/tree/main/fanus/runtime/safety"
click node_observer "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/runtime/observer/runtime_observer.py"
click node_evolution "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/evolution/evolution_engine.py"
click node_audit_api "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/audit/audit_engine.py"
click node_api "https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/api/server.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_main,node_loop,node_llm,node_identity,node_user toneBlue
class node_gateway,node_memory_pipeline,node_evidence,node_beliefs,node_ledger,node_knowledge_graph,node_persistence toneAmber
class node_orchestrator,node_guardians,node_policy,node_hayrat,node_fi_detector,node_negar,node_isp,node_growth toneMint
class node_runtime_safety,node_observer,node_evolution toneRose
class node_audit_api,node_api toneIndigo
```

## Components

### Interaction Runtime

- [Fanus System](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/main.py): `fanus/main.py`
- [Runtime Loop](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/runtime/loop.py): `fanus/runtime/loop.py`
- [Groq Adapter](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/adapters/groq_adapter.py): `fanus/adapters/groq_adapter.py`
- [System Identity](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/core/identity.py): `fanus/core/identity.py`

### Knowledge and Memory

- [Knowledge Gateway](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/adapters/knowledge_gateway.py): `fanus/adapters/knowledge_gateway.py`
- [Memory Pipeline](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/pipeline.py): `fanus/memory/pipeline.py`
- [Evidence Engine](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/evidence_engine.py): `fanus/memory/evidence_engine.py`
- [Belief Layer](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/belief_layer.py): `fanus/memory/belief_layer.py`
- [Memory Ledger](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/ledger.py): `fanus/memory/ledger.py`
- [Knowledge Graph](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/knowledge_graph.py): `fanus/memory/knowledge_graph.py`
- [Memory Persistence](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/memory/persistence.py): `fanus/memory/persistence.py`

### Cognitive Governance

- [Cognitive Orchestrator](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/orchestrator.py): `fanus/cognitive/orchestrator.py`
- [Guardian Pipeline](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/guardian_pipeline.py): `fanus/cognitive/guardian_pipeline.py`
- [Policy Engine](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/policy_engine.py): `fanus/cognitive/policy_engine.py`
- [Hayrat Judge](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/hayrat_judge.py): `fanus/cognitive/hayrat_judge.py`
- [Flattery Detection](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/fi_detector.py): `fanus/cognitive/fi_detector.py`
- [Negar Detection](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/negar_detector.py): `fanus/cognitive/negar_detector.py`
- [Identity Safeguards](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/cognitive/isp_controller.py): `fanus/cognitive/isp_controller.py`
- [Cognitive Growth](https://github.com/aminshahsaheb/fanus-living-seal/tree/main/fanus/cognitive): `fanus/cognitive`

### Runtime Evolution

- [Runtime Safety](https://github.com/aminshahsaheb/fanus-living-seal/tree/main/fanus/runtime/safety): `fanus/runtime/safety`
- [Runtime Observer](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/runtime/observer/runtime_observer.py): `fanus/runtime/observer/runtime_observer.py`
- [Evolution Engine](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/evolution/evolution_engine.py): `fanus/evolution/evolution_engine.py`

### Verification

- [Audit Engine](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/audit/audit_engine.py): `fanus/audit/audit_engine.py`
- [Verify API](https://github.com/aminshahsaheb/fanus-living-seal/blob/main/fanus/api/server.py): `fanus/api/server.py`

### Other components

- **User**

## Connections

- User → Fanus System: submits input (evidence: `fanus/main.py`)
- Fanus System → Memory Pipeline: stores input and response (evidence: `fanus/main.py`)
- Fanus System → Knowledge Gateway: searches knowledge (evidence: `fanus/main.py`)
- Fanus System → Runtime Loop: ticks runtime (evidence: `fanus/main.py`)
- Fanus System → System Identity: loads identity prompt (evidence: `fanus/main.py`)
- Fanus System → Groq Adapter: generates response (evidence: `fanus/main.py`)
- Fanus System → Cognitive Orchestrator: processes exchange (evidence: `fanus/main.py`)
- Fanus System → Guardian Pipeline: checks response (evidence: `fanus/main.py`)
- Fanus System → Policy Engine: evaluates signals (evidence: `fanus/main.py`)
- Fanus System → Identity Safeguards: checks identity risk (evidence: `fanus/main.py`)
- Fanus System → Hayrat Judge: revises response (evidence: `fanus/main.py`)
- Memory Pipeline → Evidence Engine: evaluates evidence (evidence: `fanus/memory/pipeline.py`)
- Memory Pipeline → Belief Layer: records belief (evidence: `fanus/memory/pipeline.py`)
- Memory Pipeline → Memory Ledger: records entry (evidence: `fanus/memory/pipeline.py`)
- Memory Pipeline → Knowledge Graph: adds entity (evidence: `fanus/memory/pipeline.py`)
- Memory Pipeline → Memory Persistence: restores and saves (evidence: `fanus/memory/pipeline.py`)
- Guardian Pipeline → Flattery Detection: runs detection (evidence: `fanus/cognitive/guardian_pipeline.py`)
- Guardian Pipeline → Negar Detection: runs detection (evidence: `fanus/cognitive/guardian_pipeline.py`)
- Guardian Pipeline → Hayrat Judge: runs judgment (evidence: `fanus/cognitive/guardian_pipeline.py`)
- Audit Engine → Evidence Engine: evaluates claims (evidence: `fanus/audit/audit_engine.py`)
- Audit Engine → Belief Layer: updates beliefs (evidence: `fanus/audit/audit_engine.py`)
- Audit Engine → Hayrat Judge: judges uncertainty (evidence: `fanus/audit/audit_engine.py`)
- Audit Engine → Policy Engine: evaluates signals (evidence: `fanus/audit/audit_engine.py`)
- Verify API → Audit Engine: offers verification
- Knowledge Gateway → User: retrieves sources
