Q-SPARC integrates an LLM-powered conversational interface with a semantic indexing and retrieval pipeline,
To clarify the model used in the implementation, Q-SPARC supports both local and cloud-hosted LLMs. In the hackathon prototype, we used Qwen2.5-72B as the default LLM, while GPT-4 and lighter-weight open-source models were also compatible in testing. This flexibility ensures adaptability across computational environments.
The tool is built on a modular architecture that separates query understanding, data retrieval, and visualization. This separation facilitates maintenance, scalability, and integration with other SPARC resources. To improve responsiveness, token and document flows are separated, asynchronous processing is applied, and local embedding caching minimizes repeated inference—together accelerating sequential queries without compromising reproducibility.
Q-SPARC is implemented as a modular pipeline composed of multiple interconnected components, shown in
Interface: The process begins when the user enters a prompt into the input box on the web interface and clicks the submit button. The interface is designed to display three possible outputs: (1) a natural language text response, (2) a structured table, and (3) an optional Flatmap-based anatomical diagram. Query Understanding (LLM): The submitted query is processed by a local or server-hosted Large Language Model (LLM) responsible for interpreting the question and generating an internal search representation. First Retrieval (Embedding): The interpreted query is vectorized and matched against a local database of SCKAN knowledge using semantic embeddings. This first retrieval stage selects an initial set of candidate knowledge chunks. Second Retrieval (Reranking): The candidate chunks are reranked based on relevance, using additional scoring methods to ensure that the most relevant items are prioritized for the next stage. Reader (LLM): The top-ranked chunks are passed to a second LLM (Reader) which synthesizes the final answer, combining retrieved knowledge with reasoning capabilities. The Reader can produce both free-text explanations and structured outputs. Structured Output Formats: The system supports JSON, CSV, and TTL formats, ensuring that responses are interoperable with other tools and data pipelines. Visualization Adapter (Flatmap): When applicable, anatomical context is provided via Flatmap visualization, allowing users to see spatial relationships between structures described in the answer. Local Server and Data Flow: All processing can be run locally. Token flow and document flow, as shown in
Overview of the Q-SPARC interactive chatbot framework integrating SPARC SCKAN connectivity with flatmap-based visualization. The system combines natural language input, knowledge graph querying and anatomical flatmap rendering to enable interactive exploration of neural connectivity.
Q-SPARC can be run locally or deployed on a server. The system requires Python 3.x and the dependencies listed in the accompanying requirements file. A containerized configuration is provided for reproducibility.
A typical workflow involves:
Starting the backend service to handle data retrieval and processing. Launching the frontend interface in a browser. Entering a natural-language query, for example, “What are the input sources of the heart?”. Viewing the outputs, which may include: a narrative text summary; a structured results table; an optional Flatmap anatomical visualization.
The software is accompanied by a complete tutorial set that guides the user from installation through to advanced use. The tutorials cover:
Installing dependencies and setting up the Python environment. Starting the backend and frontend components. Understanding the two-stage retrieval process. Generating and interpreting Flatmap visualizations.
All source code, documentation, and example data are distributed under an open-source license. The modular design allows adaptation for integration with other SPARC tools and datasets.