How kacemmathlouthi/vcell-demo works
Project type and purpose
• This is a lightweight full‑stack demo application built with Streamlit that exposes a natural‑language chatbot for querying and visualizing BioModels from the VCell BioModel Database.
• It relies on two external services:
• A Groq‑powered LLaMA 3.3 LLM (via utils/llm_helper.py) for parameter extraction and summarization
• The VCell Public API (via vcelldb/vcell_api.py) for fetching real biological model data
File structure
Top‑level:
• app.py – The Streamlit entry point and orchestrator of UI, user input, and module calls
• requirements.txt, .env/.streamlit/config.toml – Dependencies and deployment configuration
Utility layer (utils/):
• llm_helper.py – Wrapper around the Groq API for LLM calls
• params_extraction.py – Logic for turning free‑text prompts into structured query parameters
Domain/data layer (vcelldb/):
• vcell_api.py – HTTP client that retrieves models, SBML/VCML files, reaction network data
• params_model.py – Pydantic schemas for the request parameters and API responses
Key architectural patterns and principles
• “Separation of Concerns”: UI (app.py) vs. LLM logic vs. API client vs. data modeling vs. visualization
• “Adapter/Wrapper” pattern for external dependencies (Groq API and VCell API)
• Use of Pydantic for schema validation and type safety
Main components
A. Frontend/UI
• Streamlit App (app.py)
• Receives user input
B. Backend modules (internal services)
1. Parameter Extraction Service (utils/params_extraction.py)
2. LLM Service Adapter (utils/llm_helper.py)
3. VCell API Client (vcelldb/vcell_api.py)
4. Data Models (vcelldb/params_model.py)
C. External Services
• Groq LLaMA API (LLM)
• VCell Public API
D. Configuration
• Environment (.env) for API keys
• Streamlit config (.streamlit/config.toml)
Relationships and data flow
1. User → Streamlit UI: submits a natural language query
2. UI → Parameter Extraction: passes query text to params_extraction
3. Parameter Extraction → LLM Adapter: sends prompt to Groq API
4. LLM Adapter → LLM Service: retrieves structured query parameters
5. UI/Controller → VCell API Client: invokes HTTP calls with extracted parameters
6. VCell API → VCell API Client → Data Models: responses are validated via Pydantic
8. Summarization (via LLM Adapter) → Human‑readable answer