# salt-nlp/sparkme architecture

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

- Interactive diagram: https://gitdiagram.com/salt-nlp/sparkme
- Repository: https://github.com/salt-nlp/sparkme

## Overview

SparkMe is a multi-agent system for semi-structured, multi-turn interviews. Its principal workflow accepts an interviewee’s text or optional speech input, runs an interview session in which an interviewer asks questions and planning and agenda components guide topic exploration and note-taking, then stores session state and logs. The README also documents a web interface with authentication and session management. The graph focuses on the primary `src` implementation, not the separate baselines or evaluation tooling. Some wiring is supported only by the SOURCE INDEX or README, so unsampled relationships are omitted or marked unverified.

Main entry points: [`src/interview_session/interview_session.py`](https://github.com/salt-nlp/sparkme/blob/main/src/interview_session/interview_session.py) (Interview session), [`src/agents/agenda_manager/agenda_manager.py`](https://github.com/salt-nlp/sparkme/blob/main/src/agents/agenda_manager/agenda_manager.py) (Agenda manager), [`src/content/session_agenda/session_agenda.py`](https://github.com/salt-nlp/sparkme/blob/main/src/content/session_agenda/session_agenda.py) (Session agenda), [`src/interview_session/user/user.py`](https://github.com/salt-nlp/sparkme/blob/main/src/interview_session/user/user.py) (User participant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces and session"]
  node_terminal["Terminal interface<br/>[main.py]"]
  node_web["Web interface<br/>[main_flask.py]"]
  node_session["Interview session"]
  node_messages["Session messages<br/>[session_models.py]"]
  node_participant["User participant<br/>[user.py]"]
end

subgraph group_agents["Interview agents"]
  node_interviewer["Interviewer<br/>[interviewer.py]"]
  node_agenda_agent["Agenda manager<br/>[agenda_manager.py]"]
  node_planner["Exploration planner"]
  node_agent_base["Agent framework<br/>[base_agent.py]"]
end

subgraph group_domain["Interview domain"]
  node_agenda[("Session agenda<br/>[session_agenda.py]")]
  node_topic_manager["Topic manager"]
  node_question_bank[("Question bank")]
  node_question["Question records<br/>[question.py]"]
  node_memory_bank[("Session memory")]
  node_memory["Memory records<br/>[memory.py]"]
end

subgraph group_runtime["Runtime services"]
  node_embeddings["Embedding service"]
  node_llm["Model engine<br/>[engines.py]"]
  node_speech["Speech input<br/>[speech_to_text.py]"]
  node_logs[("Session logs<br/>[session_logger.py]")]
end

node_interviewee(("Interviewee"))

node_interviewee -->|"starts interview"| node_terminal
node_terminal -->|"starts session"| node_session
node_interviewee -->|"uses web interview"| node_web
node_web -->|"uses session"| node_session
node_session -->|"creates participant"| node_participant
node_participant -->|"adds response"| node_session
node_session -->|"sets up agent"| node_interviewer
node_session -.->|"sets up agent"| node_agenda_agent
node_session -.->|"sets up agent"| node_planner
node_session -->|"loads agenda"| node_agenda
node_session -->|"sets up memory"| node_memory_bank
node_session -->|"sets up bank"| node_question_bank
node_session -->|"uses message model"| node_messages
node_interviewer -->|"inherits from"| node_agent_base
node_agenda_agent -->|"inherits from"| node_agent_base
node_agent_base -->|"invokes engine"| node_llm
node_agenda_agent -->|"adds questions"| node_agenda
node_agenda_agent -.->|"uses memories"| node_memory
node_agenda -->|"manages topics"| node_topic_manager
node_agenda -->|"records questions"| node_question
node_topic_manager -->|"uses questions"| node_question
node_question_bank -->|"stores questions"| node_question
node_memory_bank -->|"stores memories"| node_memory
node_memory_bank -->|"embeds for search"| node_embeddings
node_question_bank -->|"embeds for search"| node_embeddings
node_participant -->|"transcribes voice"| node_speech
node_session -.->|"logs session"| node_logs

click node_terminal "https://github.com/salt-nlp/sparkme/blob/main/src/main.py"
click node_web "https://github.com/salt-nlp/sparkme/blob/main/src/main_flask.py"
click node_session "https://github.com/salt-nlp/sparkme/blob/main/src/interview_session/interview_session.py"
click node_messages "https://github.com/salt-nlp/sparkme/blob/main/src/interview_session/session_models.py"
click node_participant "https://github.com/salt-nlp/sparkme/blob/main/src/interview_session/user/user.py"
click node_interviewer "https://github.com/salt-nlp/sparkme/blob/main/src/agents/interviewer/interviewer.py"
click node_agenda_agent "https://github.com/salt-nlp/sparkme/blob/main/src/agents/agenda_manager/agenda_manager.py"
click node_planner "https://github.com/salt-nlp/sparkme/blob/main/src/agents/exploration_planner/exploration_planner.py"
click node_agent_base "https://github.com/salt-nlp/sparkme/blob/main/src/agents/base_agent.py"
click node_agenda "https://github.com/salt-nlp/sparkme/blob/main/src/content/session_agenda/session_agenda.py"
click node_topic_manager "https://github.com/salt-nlp/sparkme/blob/main/src/content/session_agenda/interview_topic_manager.py"
click node_question_bank "https://github.com/salt-nlp/sparkme/blob/main/src/content/question_bank/question_bank_vector_db.py"
click node_question "https://github.com/salt-nlp/sparkme/blob/main/src/content/question_bank/question.py"
click node_memory_bank "https://github.com/salt-nlp/sparkme/blob/main/src/content/memory_bank/memory_bank_vector_db.py"
click node_memory "https://github.com/salt-nlp/sparkme/blob/main/src/content/memory_bank/memory.py"
click node_embeddings "https://github.com/salt-nlp/sparkme/blob/main/src/content/embeddings/embedding_service.py"
click node_llm "https://github.com/salt-nlp/sparkme/blob/main/src/utils/llm/engines.py"
click node_speech "https://github.com/salt-nlp/sparkme/blob/main/src/utils/speech/speech_to_text.py"
click node_logs "https://github.com/salt-nlp/sparkme/blob/main/src/utils/logger/session_logger.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_terminal,node_web,node_session,node_messages,node_participant,node_interviewee toneBlue
class node_interviewer,node_agenda_agent,node_planner,node_agent_base toneAmber
class node_agenda,node_topic_manager,node_question_bank,node_question,node_memory_bank,node_memory toneMint
class node_embeddings,node_llm,node_speech,node_logs toneRose
```

## Components

### Interfaces and session

- [Terminal interface](https://github.com/salt-nlp/sparkme/blob/main/src/main.py): `src/main.py`
- [Web interface](https://github.com/salt-nlp/sparkme/blob/main/src/main_flask.py): `src/main_flask.py`
- [Interview session](https://github.com/salt-nlp/sparkme/blob/main/src/interview_session/interview_session.py): `src/interview_session/interview_session.py`
- [Session messages](https://github.com/salt-nlp/sparkme/blob/main/src/interview_session/session_models.py): `src/interview_session/session_models.py`
- [User participant](https://github.com/salt-nlp/sparkme/blob/main/src/interview_session/user/user.py): `src/interview_session/user/user.py`

### Interview agents

- [Interviewer](https://github.com/salt-nlp/sparkme/blob/main/src/agents/interviewer/interviewer.py): `src/agents/interviewer/interviewer.py`
- [Agenda manager](https://github.com/salt-nlp/sparkme/blob/main/src/agents/agenda_manager/agenda_manager.py): `src/agents/agenda_manager/agenda_manager.py`
- [Exploration planner](https://github.com/salt-nlp/sparkme/blob/main/src/agents/exploration_planner/exploration_planner.py): `src/agents/exploration_planner/exploration_planner.py`
- [Agent framework](https://github.com/salt-nlp/sparkme/blob/main/src/agents/base_agent.py): `src/agents/base_agent.py`

### Interview domain

- [Session agenda](https://github.com/salt-nlp/sparkme/blob/main/src/content/session_agenda/session_agenda.py): `src/content/session_agenda/session_agenda.py`
- [Topic manager](https://github.com/salt-nlp/sparkme/blob/main/src/content/session_agenda/interview_topic_manager.py): `src/content/session_agenda/interview_topic_manager.py`
- [Question bank](https://github.com/salt-nlp/sparkme/blob/main/src/content/question_bank/question_bank_vector_db.py): `src/content/question_bank/question_bank_vector_db.py`
- [Question records](https://github.com/salt-nlp/sparkme/blob/main/src/content/question_bank/question.py): `src/content/question_bank/question.py`
- [Session memory](https://github.com/salt-nlp/sparkme/blob/main/src/content/memory_bank/memory_bank_vector_db.py): `src/content/memory_bank/memory_bank_vector_db.py`
- [Memory records](https://github.com/salt-nlp/sparkme/blob/main/src/content/memory_bank/memory.py): `src/content/memory_bank/memory.py`

### Runtime services

- [Embedding service](https://github.com/salt-nlp/sparkme/blob/main/src/content/embeddings/embedding_service.py): `src/content/embeddings/embedding_service.py`
- [Model engine](https://github.com/salt-nlp/sparkme/blob/main/src/utils/llm/engines.py): `src/utils/llm/engines.py`
- [Speech input](https://github.com/salt-nlp/sparkme/blob/main/src/utils/speech/speech_to_text.py): `src/utils/speech/speech_to_text.py`
- [Session logs](https://github.com/salt-nlp/sparkme/blob/main/src/utils/logger/session_logger.py): `src/utils/logger/session_logger.py`

### Other components

- **Interviewee**

## Connections

- Interviewee → Terminal interface: starts interview (evidence: `README.md`)
- Terminal interface → Interview session: starts session (evidence: `src/main.py`)
- Interviewee → Web interface: uses web interview (evidence: `README.md`)
- Web interface → Interview session: uses session (evidence: `src/main_flask.py`)
- Interview session → User participant: creates participant (evidence: `src/interview_session/interview_session.py`)
- User participant → Interview session: adds response (evidence: `src/interview_session/user/user.py`)
- Interview session → Interviewer: sets up agent (evidence: `src/interview_session/interview_session.py`)
- Interview session → Agenda manager: sets up agent (evidence: `src/interview_session/interview_session.py`)
- Interview session → Exploration planner: sets up agent (evidence: `src/interview_session/interview_session.py`)
- Interview session → Session agenda: loads agenda (evidence: `src/interview_session/interview_session.py`)
- Interview session → Session memory: sets up memory (evidence: `src/interview_session/interview_session.py`)
- Interview session → Question bank: sets up bank (evidence: `src/interview_session/interview_session.py`)
- Interview session → Session messages: uses message model (evidence: `src/interview_session/interview_session.py`)
- Interviewer → Agent framework: inherits from (evidence: `src/agents/interviewer/interviewer.py`)
- Agenda manager → Agent framework: inherits from (evidence: `src/agents/agenda_manager/agenda_manager.py`)
- Agent framework → Model engine: invokes engine (evidence: `src/agents/base_agent.py`)
- Agenda manager → Session agenda: adds questions (evidence: `src/agents/agenda_manager/agenda_manager.py`)
- Agenda manager → Memory records: uses memories (evidence: `src/agents/agenda_manager/agenda_manager.py`)
- Session agenda → Topic manager: manages topics (evidence: `src/content/session_agenda/session_agenda.py`)
- Session agenda → Question records: records questions (evidence: `src/content/session_agenda/session_agenda.py`)
- Topic manager → Question records: uses questions (evidence: `src/content/session_agenda/interview_topic_manager.py`)
- Question bank → Question records: stores questions (evidence: `src/content/question_bank/question_bank_vector_db.py`)
- Session memory → Memory records: stores memories (evidence: `src/content/memory_bank/memory_bank_vector_db.py`)
- Session memory → Embedding service: embeds for search (evidence: `src/content/memory_bank/memory_bank_vector_db.py`)
- Question bank → Embedding service: embeds for search (evidence: `src/content/question_bank/question_bank_vector_db.py`)
- User participant → Speech input: transcribes voice (evidence: `src/interview_session/user/user.py`)
- Interview session → Session logs: logs session (evidence: `src/interview_session/interview_session.py`)