# madmando/prism architecture

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

- Interactive diagram: https://gitdiagram.com/madmando/prism
- Repository: https://github.com/madmando/prism

## Overview

PRISM builds a typed epistemic graph over an existing vector corpus, then retrieves structured answers by combining vector-search seeds with graph spreading activation. The README also documents graph visualization, export, inspection, and a local interactive explorer. The sampled source confirms the main build/retrieval orchestration and explorer endpoints; links for unsampled CLI behavior and some adapter internals are limited to documented capabilities.

Main entry points: [`prism/prism.py`](https://github.com/madmando/prism/blob/main/prism/prism.py) (PRISM interface), [`prism/graph.py`](https://github.com/madmando/prism/blob/main/prism/graph.py) (Epistemic graph), [`prism/retriever.py`](https://github.com/madmando/prism/blob/main/prism/retriever.py) (Retrieval pipeline), [`prism/adapters`](https://github.com/madmando/prism/tree/main/prism/adapters) (Vector adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Graph building"]
  node_prism_api["PRISM interface<br/>[prism.py]"]
  node_build_cli["Build CLI<br/>[cli.py]"]
  node_pair_search["Candidate pairs<br/>[lancedb.py]"]
  node_epistemic_filter["Pair filter<br/>[filter.py]"]
  node_extractor["Edge extraction<br/>[extractor.py]"]
  node_llm_services["LLM services"]
end

subgraph group_retrieval["Structured retrieval"]
  node_retrieve_cli["Retrieval client<br/>[prism.py]"]
  node_retriever["Retrieval pipeline<br/>[retriever.py]"]
  node_activation["Spreading activation<br/>[activation.py]"]
  node_edge_semantics["Edge semantics<br/>[edges.py]"]
  node_epistemic_result["Structured result<br/>[result.py]"]
end

subgraph group_storage["Corpus and graph"]
  node_vector_adapters["Vector adapters"]
  node_vector_store[("Vector store")]
  node_embedding_provider["Embedding provider"]
  node_epistemic_graph["Epistemic graph<br/>[graph.py]"]
  node_graph_file["Graph file"]
end

subgraph group_tools["Explore and inspect"]
  node_explorer_server["Explorer API<br/>[server.py]"]
  node_explorer_ui["Explorer UI<br/>[index.html]"]
  node_graph_viz["Graph visualization<br/>[viz_cli.py]"]
  node_graph_export["Graph export<br/>[export_cli.py]"]
  node_graph_inspect["Graph inspection<br/>[inspect_cli.py]"]
end

node_developer(("Application developer"))

node_developer -->|"runs build"| node_build_cli
node_build_cli -->|"invokes build"| node_prism_api
node_developer -->|"calls API"| node_prism_api
node_prism_api -->|"connects"| node_vector_adapters
node_vector_adapters -->|"reads corpus"| node_vector_store
node_vector_adapters -.->|"embeds queries"| node_embedding_provider
node_prism_api -->|"requests pairs"| node_pair_search
node_pair_search -->|"searches neighbors"| node_vector_store
node_prism_api -->|"filters pairs"| node_epistemic_filter
node_epistemic_filter -->|"screens pairs"| node_llm_services
node_prism_api -->|"extracts edges"| node_extractor
node_extractor -->|"classifies relations"| node_llm_services
node_prism_api -->|"builds graph"| node_epistemic_graph
node_extractor -->|"adds edges"| node_epistemic_graph
node_prism_api -->|"saves or loads"| node_graph_file
node_epistemic_graph -->|"serializes"| node_graph_file
node_developer -->|"requests retrieval"| node_retrieve_cli
node_retrieve_cli -->|"delegates query"| node_retriever
node_retriever -->|"searches seeds"| node_vector_adapters
node_retriever -->|"propagates seeds"| node_activation
node_activation -->|"traverses edges"| node_epistemic_graph
node_retriever -->|"classifies valence"| node_edge_semantics
node_retriever -->|"structures buckets"| node_epistemic_result
node_developer -->|"uses explorer"| node_explorer_ui
node_explorer_ui -->|"requests graph or retrieval"| node_explorer_server
node_explorer_server -->|"serves graph"| node_epistemic_graph
node_explorer_server -->|"requests retrieval"| node_retrieve_cli
node_developer -->|"exports visualization"| node_graph_viz
node_graph_viz -->|"reads graph"| node_epistemic_graph
node_developer -->|"exports graph"| node_graph_export
node_graph_export -->|"reads graph"| node_epistemic_graph
node_developer -->|"inspects graph"| node_graph_inspect
node_graph_inspect -->|"reads graph"| node_epistemic_graph

click node_prism_api "https://github.com/madmando/prism/blob/main/prism/prism.py"
click node_build_cli "https://github.com/madmando/prism/blob/main/prism/cli.py"
click node_pair_search "https://github.com/madmando/prism/blob/main/prism/adapters/lancedb.py"
click node_epistemic_filter "https://github.com/madmando/prism/blob/main/prism/filter.py"
click node_extractor "https://github.com/madmando/prism/blob/main/prism/extractor.py"
click node_vector_adapters "https://github.com/madmando/prism/tree/main/prism/adapters"
click node_epistemic_graph "https://github.com/madmando/prism/blob/main/prism/graph.py"
click node_retrieve_cli "https://github.com/madmando/prism/blob/main/prism/prism.py"
click node_retriever "https://github.com/madmando/prism/blob/main/prism/retriever.py"
click node_activation "https://github.com/madmando/prism/blob/main/prism/activation.py"
click node_edge_semantics "https://github.com/madmando/prism/blob/main/prism/edges.py"
click node_epistemic_result "https://github.com/madmando/prism/blob/main/prism/result.py"
click node_explorer_server "https://github.com/madmando/prism/blob/main/prism/explorer/server.py"
click node_explorer_ui "https://github.com/madmando/prism/blob/main/prism/explorer/static/index.html"
click node_graph_viz "https://github.com/madmando/prism/blob/main/prism/viz_cli.py"
click node_graph_export "https://github.com/madmando/prism/blob/main/prism/export_cli.py"
click node_graph_inspect "https://github.com/madmando/prism/blob/main/prism/inspect_cli.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_prism_api,node_build_cli,node_pair_search,node_epistemic_filter,node_extractor,node_llm_services toneBlue
class node_retrieve_cli,node_retriever,node_activation,node_edge_semantics,node_epistemic_result toneAmber
class node_vector_adapters,node_vector_store,node_embedding_provider,node_epistemic_graph,node_graph_file toneMint
class node_explorer_server,node_explorer_ui,node_graph_viz,node_graph_export,node_graph_inspect toneRose
class node_developer toneIndigo
```

## Components

### Graph building

- [PRISM interface](https://github.com/madmando/prism/blob/main/prism/prism.py): `prism/prism.py`
- [Build CLI](https://github.com/madmando/prism/blob/main/prism/cli.py): `prism/cli.py`
- [Candidate pairs](https://github.com/madmando/prism/blob/main/prism/adapters/lancedb.py): `prism/adapters/lancedb.py`
- [Pair filter](https://github.com/madmando/prism/blob/main/prism/filter.py): `prism/filter.py`
- [Edge extraction](https://github.com/madmando/prism/blob/main/prism/extractor.py): `prism/extractor.py`
- **LLM services**

### Structured retrieval

- [Retrieval client](https://github.com/madmando/prism/blob/main/prism/prism.py): `prism/prism.py`
- [Retrieval pipeline](https://github.com/madmando/prism/blob/main/prism/retriever.py): `prism/retriever.py`
- [Spreading activation](https://github.com/madmando/prism/blob/main/prism/activation.py): `prism/activation.py`
- [Edge semantics](https://github.com/madmando/prism/blob/main/prism/edges.py): `prism/edges.py`
- [Structured result](https://github.com/madmando/prism/blob/main/prism/result.py): `prism/result.py`

### Corpus and graph

- [Vector adapters](https://github.com/madmando/prism/tree/main/prism/adapters): `prism/adapters`
- **Vector store**
- **Embedding provider**
- [Epistemic graph](https://github.com/madmando/prism/blob/main/prism/graph.py): `prism/graph.py`
- **Graph file**

### Explore and inspect

- [Explorer API](https://github.com/madmando/prism/blob/main/prism/explorer/server.py): `prism/explorer/server.py`
- [Explorer UI](https://github.com/madmando/prism/blob/main/prism/explorer/static/index.html): `prism/explorer/static/index.html`
- [Graph visualization](https://github.com/madmando/prism/blob/main/prism/viz_cli.py): `prism/viz_cli.py`
- [Graph export](https://github.com/madmando/prism/blob/main/prism/export_cli.py): `prism/export_cli.py`
- [Graph inspection](https://github.com/madmando/prism/blob/main/prism/inspect_cli.py): `prism/inspect_cli.py`

### Other components

- **Application developer**

## Connections

- Application developer → Build CLI: runs build
- Build CLI → PRISM interface: invokes build
- Application developer → PRISM interface: calls API
- PRISM interface → Vector adapters: connects
- Vector adapters → Vector store: reads corpus
- Vector adapters → Embedding provider: embeds queries
- PRISM interface → Candidate pairs: requests pairs
- Candidate pairs → Vector store: searches neighbors
- PRISM interface → Pair filter: filters pairs
- Pair filter → LLM services: screens pairs
- PRISM interface → Edge extraction: extracts edges
- Edge extraction → LLM services: classifies relations
- PRISM interface → Epistemic graph: builds graph
- Edge extraction → Epistemic graph: adds edges
- PRISM interface → Graph file: saves or loads
- Epistemic graph → Graph file: serializes
- Application developer → Retrieval client: requests retrieval
- Retrieval client → Retrieval pipeline: delegates query
- Retrieval pipeline → Vector adapters: searches seeds
- Retrieval pipeline → Spreading activation: propagates seeds
- Spreading activation → Epistemic graph: traverses edges
- Retrieval pipeline → Edge semantics: classifies valence
- Retrieval pipeline → Structured result: structures buckets
- Application developer → Explorer UI: uses explorer
- Explorer UI → Explorer API: requests graph or retrieval
- Explorer API → Epistemic graph: serves graph
- Explorer API → Retrieval client: requests retrieval
- Application developer → Graph visualization: exports visualization
- Graph visualization → Epistemic graph: reads graph
- Application developer → Graph export: exports graph
- Graph export → Epistemic graph: reads graph
- Application developer → Graph inspection: inspects graph
- Graph inspection → Epistemic graph: reads graph