1 line
42 KiB
JSON
1 line
42 KiB
JSON
{"repo": "antoninovaccarella/clinical-chat", "files": {"README.md": {"d3306e5c99e79053490a1c8897dbddb2c56ec474": {"t": 1785746501.1852403, "n": 8226, "h": "66df280a7fe3d33d", "c": "# ClinAgent\n\nClinAgent is a web application for exploring clinical and biomedical questions through a conversational interface. It combines a Flask web UI, multiple selectable LLM backends, a LangGraph workflow, and domain-specific tools for ClinicalTrials.gov and PubMed.\n\nThe project is designed for research and prototyping workflows where clinicians, biomedical researchers, and developers need a shared interface to ask questions, inspect clinical trial information, and compare model behavior.\n\n## What The Application Does\n\nClinAgent can help with tasks such as:\n\n- exploring clinical trials related to diseases, drugs, devices, or interventions;\n- retrieving protocol details, outcomes, and available trial results;\n- using different LLM providers from the same UI;\n- optionally consulting PubMed when trial data alone is not enough.\n\nThe application is not a medical device and does not replace clinical judgment, literature review, or methodological validation. Generated answers must always be checked against the original sources.\n\n## Important Safety Notes\n\n- Do not submit personal data, patient-identifiable information, or sensitive health data.\n- Requests are sent to external LLM providers.\n- Answers may contain errors, omissions, or incomplete reasoning.\n- The files in [`db/`](db) are temporary working files, not a validated clinical database.\n\n## How It Works\n\nAt a high level, the request flow is:\n\n1. A user enters a question in the web UI.\n2. The browser sends a `POST /chat` request to the Flask backend.\n3. Flask validates the payload and forwards it to the chatbot workflow.\n4. LangGraph runs a ReAct-style agent backed by the selected LLM.\n5. The agent decides whether to:\n - answer directly;\n - retrieve trial data from ClinicalTrials.gov;\n - inspect the local CSV cache with Python and Pandas;\n - use PubMed for medical literature support.\n6. The final answer is returned as JSON and rendered in the chat UI.\n\nThe main pieces of the system are:\n\n- [`main.py`](main.py): application entry point;\n- [`app/__init__.py`](app/__init__.py): Flask app factory;\n- [`app/client/routes.py`](app/client/routes.py): HTTP endpoints, including `/chat`;\n- [`app/client/chatbot.py`](app/client/chatbot.py): chatbot wrapper around the workflow;\n- [`app/rag_agent/workflow.py`](app/rag_agent/workflow.py): LangGraph orchestration;\n- [`app/rag_agent/react_agent.py`](app/rag_agent/react_agent.py): ReAct agent and tool selection rules;\n- [`app/rag_agent/clinical_tool/`](app/rag_agent/clinical_tool): ClinicalTrials.gov integration and local dataset utilities;\n- [`app/templates/index.html`](app/templates/index.html) and [`app/static/style.css`](app/static/style.css): web UI.\n\n## Runtime Behavior\n\nClinAgent maintains two temporary files under [`db/`](db):\n\n- `ClinicalTrialsDB.csv`\n- `ClinicalTrialsDB.json`\n\nThese files are cleared automatically every time the application starts, both locally and in Docker. This means each new app startup begins with a fresh working session.\n\n## Supported Models\n\nThe UI currently exposes these model options:\n\n- `gemini` -> `gemini-3-flash-preview`\n- `deepseek-v3` -> `deepseek-chat`\n- `deepseek-r1` -> `deepseek-reasoner`\n\nAn API key can be supplied in either of these ways:\n\n- directly in the web UI;\n- through environment variables.\n\nThe main environment variable mappings used by the code are:\n\n- `GEMINI_API` or `GEMINI_API_2` for Gemini;\n- `DEEPSEEK_API_KEY` for DeepSeek V3 and DeepSeek R1.\n\n## Requirements\n\nFor Docker execution:\n\n- Docker\n- Docker Compose\n\nFor local execution:\n\n- Python 3.11 recommended\n- `venv`\n- internet access\n- at least one valid API key for a supported model\n\nPython 3.11 is the recommended local version because it matches the base image used in the [`Dockerfile`](Dockerfile). Local installs also work on Python 3.12 and 3.13 because [`requirements.txt`](requirements.txt) selects compatible `pandas` and `numpy` builds for newer interpreters.\n\n## Environment Variables\n\nThe repository includes an example file:\n\n```bash\ncp .env.example .env\n```\n\nThe most important variables are:\n\n- `FLASK_HOST`: host bound by the Flask process;\n- `FLASK_PORT`: port used by Flask inside the Python process;\n- `HOST_PORT`: host port published by Docker Compose;\n- `SECRET_KEY`: Flask secret key;\n- `GEMINI_API`, `DEEPSEEK_API_KEY`: model API keys;\n- `CSV_PATH`, `JSON_PATH`: paths for the temporary trial files.\n\nThe default template is:\n\n```env\n# Flask\nFLASK_HOST=0.0.0.0\nFLASK_PORT=7860\nHOST_PORT=5000\nFLASK_DEBUG=false\nSECRET_KEY=dev-secret-key\n\n# Data sources\nCLINICAL_API=https://clinicaltrials.gov/api/v2/\nCSV_PATH=./db/ClinicalTrialsDB.csv\nJSON_PATH=./db/ClinicalTrialsDB.json\n\n# LLM providers\nGEMINI_API=\nGEMINI_API_2=\nGEMINI_API_3=\nDEEPSEEK_API_KEY=\n\n# Reserved for future integrations\nMISTRAL_AI_API=\nGROQ_API_KEY=\nOPEN_ROUTER_API_KEY=\n```\n\nImportant note for local execution: `python main.py` does not automatically load `.env`, so you must export the variables in your shell first if you want to rely on them locally.\n\n## Running With Docker\n\nDocker is the easiest way to start the project with a reproducible environment.\n\n### 1. Verify Docker\n\n```bash\ndocker --version\ndocker compose version\n```\n\n### 2. Create the environment file\n\n```bash\ncp .env.example .env\n```\n\nFill in at least one API key if you want the backend to work immediately. If needed, you can still enter a key manually in the web UI.\n\n### 3. Start the web application\n\n```bash\ndocker compose up --build web\n```\n\nBy default:\n\n- Flask runs on port `7860` inside the container;\n- Docker publishes it on host port `5000`.\n\nOpen:\n\n```text\nhttp://127.0.0.1:5000\n```\n\n### 4. Stop the containers\n\n```bash\ndocker compose down\n```\n\n### 5. Change the exposed host port\n\nIf port `5000` is already in use:\n\n```bash\nHOST_PORT=5001 docker compose up --build web\n```\n\nThen open:\n\n```text\nhttp://127.0.0.1:5001\n```\n\n### 6. View logs\n\n```bash\ndocker compose logs -f web\n```\n\n## Running Locally Without Docker\n\nThis mode is useful for development, debugging, and source-level inspection.\n\n### 1. Create a virtual environment\n\nRecommended:\n\n```bash\npython3.11 -m venv .venv\n```\n\nIf `python3.11` is not available but `python3` already points to Python 3.11, 3.12, or 3.13:\n\n```bash\npython3 -m venv .venv\n```\n\n### 2. Activate the virtual environment\n\n```bash\nsource .venv/bin/activate\n```\n\n### 3. Install dependencies\n\n```bash\npython -m pip install --upgrade pip\npython -m pip install -r requirements.txt\n```\n\n### 4. Create `.env`\n\n```bash\ncp .env.example .env\n```\n\n### 5. Export the environment variables\n\nBecause the app does not auto-load `.env` outside Docker, export it before starting Flask:\n\n```bash\nset -a\nsource .env\nset +a\n```\n\nIf you do not want to export `.env`, you can also set variables manually in your shell.\n\n### 6. Start the application\n\n```bash\npython main.py\n```\n\nBy default the local server listens on:\n\n```text\nhttp://127.0.0.1:7860\n```\n\nIf `FLASK_PORT` is set to a different value, use that port instead.\n\n## HTTP API\n\nThe main backend endpoint is:\n\n```text\nPOST /chat\n```\n\nExample request:\n\n```bash\ncurl -X POST http://127.0.0.1:7860/chat \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"question\": \"What are the main outcomes of trials on pembrolizumab in lung cancer?\",\n \"model\": \"gemini\",\n \"api_key\": \"YOUR_API_KEY\"\n }'\n```\n\nExample response shape:\n\n```json\n{\n \"response\": \"...\"\n}\n```\n\n## Project Structure\n\n```text\nclinagent/\n├── app/\n│ ├── client/ # Flask routes and chatbot wrapper\n│ ├── large_language_models/ # Model connectors\n│ ├── rag_agent/ # LangGraph workflow and tools\n│ ├── static/ # CSS and static assets\n│ └── templates/ # HTML templates\n├── db/ # Temporary ClinicalTrials working files\n├── Dockerfile\n├── docker-compose.yml\n├── main.py\n├── requirements.txt\n└── README.md\n```\n\n## Notes For Contributors\n\n- The web UI is rendered by Flask and enhanced with client-side JavaScript.\n- ClinicalTrials.gov data is downloaded on demand and written to local working files in [`db/`](db).\n- Those working files are reset at every application startup.\n- If you run locally, remember that `.env` is not auto-loaded by the app."}, "d4b8754758d26c53c6ee171ef3c4c7b9d4a540df": {"t": 1785764990.0587254, "n": 9024, "h": "308dd3ad67317a54", "c": "# ClinAgent\n\nClinAgent is a web application for exploring clinical and biomedical questions through a conversational interface. It combines a Flask web UI, multiple selectable LLM backends, a LangGraph workflow, and domain-specific tools for ClinicalTrials.gov and PubMed.\n\nThe project is designed for research and prototyping workflows where clinicians, biomedical researchers, and developers need a shared interface to ask questions, inspect clinical trial information, and compare model behavior.\n\n## What The Application Does\n\nClinAgent can help with tasks such as:\n\n- exploring clinical trials related to diseases, drugs, devices, or interventions;\n- retrieving protocol details, outcomes, and available trial results;\n- using different LLM providers from the same UI;\n- optionally consulting PubMed when trial data alone is not enough.\n\nThe application is not a medical device and does not replace clinical judgment, literature review, or methodological validation. Generated answers must always be checked against the original sources.\n\n## Important Safety Notes\n\n- Do not submit personal data, patient-identifiable information, or sensitive health data.\n- Requests are sent to external LLM providers.\n- Answers may contain errors, omissions, or incomplete reasoning.\n- The files in [`db/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/db) are temporary working files, not a validated clinical database.\n\n## How It Works\n\nAt a high level, the request flow is:\n\n1. A user enters a question in the web UI.\n2. The browser sends a `POST /chat` request to the Flask backend.\n3. Flask validates the payload and forwards it to the chatbot workflow.\n4. LangGraph runs a ReAct-style agent backed by the selected LLM.\n5. The agent decides whether to:\n - answer directly;\n - retrieve trial data from ClinicalTrials.gov;\n - inspect the local CSV cache with Python and Pandas;\n - use PubMed for medical literature support.\n6. The final answer is returned as JSON and rendered in the chat UI.\n\nThe main pieces of the system are:\n\n- [`main.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/main.py): application entry point;\n- [`app/__init__.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/__init__.py): Flask app factory;\n- [`app/client/routes.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/client/routes.py): HTTP endpoints, including `/chat`;\n- [`app/client/chatbot.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/client/chatbot.py): chatbot wrapper around the workflow;\n- [`app/rag_agent/workflow.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/rag_agent/workflow.py): LangGraph orchestration;\n- [`app/rag_agent/react_agent.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/rag_agent/react_agent.py): ReAct agent and tool selection rules;\n- [`app/rag_agent/clinical_tool/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/rag_agent/clinical_tool): ClinicalTrials.gov integration and local dataset utilities;\n- [`app/templates/index.html`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/templates/index.html) and [`app/static/style.css`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/static/style.css): web UI.\n\n## Runtime Behavior\n\nClinAgent maintains two temporary files under [`db/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/db):\n\n- `ClinicalTrialsDB.csv`\n- `ClinicalTrialsDB.json`\n\nThese files are cleared automatically every time the application starts, both locally and in Docker. This means each new app startup begins with a fresh working session.\n\n## Supported Models\n\nThe UI currently exposes these model options:\n\n- `gemini` -> `gemini-3-flash-preview`\n- `deepseek-v3` -> `deepseek-chat`\n- `deepseek-r1` -> `deepseek-reasoner`\n\nAn API key can be supplied in either of these ways:\n\n- directly in the web UI;\n- through environment variables.\n\nThe main environment variable mappings used by the code are:\n\n- `GEMINI_API` or `GEMINI_API_2` for Gemini;\n- `DEEPSEEK_API_KEY` for DeepSeek V3 and DeepSeek R1.\n\n## Requirements\n\nFor Docker execution:\n\n- Docker\n- Docker Compose\n\nFor local execution:\n\n- Python 3.11 recommended\n- `venv`\n- internet access\n- at least one valid API key for a supported model\n\nPython 3.11 is the recommended local version because it matches the base image used in the [`Dockerfile`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/Dockerfile). Local installs also work on Python 3.12 and 3.13 because [`requirements.txt`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/requirements.txt) selects compatible `pandas` and `numpy` builds for newer interpreters.\n\n## Environment Variables\n\nThe repository includes an example file:\n\n```bash\ncp .env.example .env\n```\n\nThe most important variables are:\n\n- `FLASK_HOST`: host bound by the Flask process;\n- `FLASK_PORT`: port used by Flask inside the Python process;\n- `HOST_PORT`: host port published by Docker Compose;\n- `SECRET_KEY`: Flask secret key;\n- `GEMINI_API`, `DEEPSEEK_API_KEY`: model API keys;\n- `CSV_PATH`, `JSON_PATH`: paths for the temporary trial files.\n\nThe default template is:\n\n```env\n# Flask\nFLASK_HOST=0.0.0.0\nFLASK_PORT=7860\nHOST_PORT=5000\nFLASK_DEBUG=false\nSECRET_KEY=dev-secret-key\n\n# Data sources\nCLINICAL_API=https://clinicaltrials.gov/api/v2/\nCSV_PATH=./db/ClinicalTrialsDB.csv\nJSON_PATH=./db/ClinicalTrialsDB.json\n\n# LLM providers\nGEMINI_API=\nGEMINI_API_2=\nGEMINI_API_3=\nDEEPSEEK_API_KEY=\n\n# Reserved for future integrations\nMISTRAL_AI_API=\nGROQ_API_KEY=\nOPEN_ROUTER_API_KEY=\n```\n\nImportant note for local execution: `python main.py` does not automatically load `.env`, so you must export the variables in your shell first if you want to rely on them locally.\n\n## Running With Docker\n\nDocker is the easiest way to start the project with a reproducible environment.\n\n### 1. Verify Docker\n\n```bash\ndocker --version\ndocker compose version\n```\n\n### 2. Create the environment file\n\n```bash\ncp .env.example .env\n```\n\nFill in at least one API key if you want the backend to work immediately. If needed, you can still enter a key manually in the web UI.\n\n### 3. Start the web application\n\n```bash\ndocker compose up --build web\n```\n\nBy default:\n\n- Flask runs on port `7860` inside the container;\n- Docker publishes it on host port `5000`.\n\nOpen:\n\n```text\nhttp://127.0.0.1:5000\n```\n\n### 4. Stop the containers\n\n```bash\ndocker compose down\n```\n\n### 5. Change the exposed host port\n\nIf port `5000` is already in use:\n\n```bash\nHOST_PORT=5001 docker compose up --build web\n```\n\nThen open:\n\n```text\nhttp://127.0.0.1:5001\n```\n\n### 6. View logs\n\n```bash\ndocker compose logs -f web\n```\n\n## Running Locally Without Docker\n\nThis mode is useful for development, debugging, and source-level inspection.\n\n### 1. Create a virtual environment\n\nRecommended:\n\n```bash\npython3.11 -m venv .venv\n```\n\nIf `python3.11` is not available but `python3` already points to Python 3.11, 3.12, or 3.13:\n\n```bash\npython3 -m venv .venv\n```\n\n### 2. Activate the virtual environment\n\n```bash\nsource .venv/bin/activate\n```\n\n### 3. Install dependencies\n\n```bash\npython -m pip install --upgrade pip\npython -m pip install -r requirements.txt\n```\n\n### 4. Create `.env`\n\n```bash\ncp .env.example .env\n```\n\n### 5. Export the environment variables\n\nBecause the app does not auto-load `.env` outside Docker, export it before starting Flask:\n\n```bash\nset -a\nsource .env\nset +a\n```\n\nIf you do not want to export `.env`, you can also set variables manually in your shell.\n\n### 6. Start the application\n\n```bash\npython main.py\n```\n\nBy default the local server listens on:\n\n```text\nhttp://127.0.0.1:7860\n```\n\nIf `FLASK_PORT` is set to a different value, use that port instead.\n\n## HTTP API\n\nThe main backend endpoint is:\n\n```text\nPOST /chat\n```\n\nExample request:\n\n```bash\ncurl -X POST http://127.0.0.1:7860/chat \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"question\": \"What are the main outcomes of trials on pembrolizumab in lung cancer?\",\n \"model\": \"gemini\",\n \"api_key\": \"YOUR_API_KEY\"\n }'\n```\n\nExample response shape:\n\n```json\n{\n \"response\": \"...\"\n}\n```\n\n## Project Structure\n\n```text\nclinagent/\n├── app/\n│ ├── client/ # Flask routes and chatbot wrapper\n│ ├── large_language_models/ # Model connectors\n│ ├── rag_agent/ # LangGraph workflow and tools\n│ ├── static/ # CSS and static assets\n│ └── templates/ # HTML templates\n├── db/ # Temporary ClinicalTrials working files\n├── Dockerfile\n├── docker-compose.yml\n├── main.py\n├── requirements.txt\n└── README.md\n```\n\n## Notes For Contributors\n\n- The web UI is rendered by Flask and enhanced with client-side JavaScript.\n- ClinicalTrials.gov data is downloaded on demand and written to local working files in [`db/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/db).\n- Those working files are reset at every application startup.\n- If you run locally, remember that `.env` is not auto-loaded by the app."}, "0888b85d2f6eae25519d96f4d698a8abf028618d": {"t": 1785764991.5100348, "n": 9166, "h": "01eb76644d013671", "c": "# ClinAgent\n\nClinAgent is a web application for exploring clinical and biomedical questions through a conversational interface. It combines a Flask web UI, multiple selectable LLM backends, a LangGraph workflow, and domain-specific tools for ClinicalTrials.gov and PubMed.\n\nThe project is designed for research and prototyping workflows where clinicians, biomedical researchers, and developers need a shared interface to ask questions, inspect clinical trial information, and compare model behavior.\n\n## What The Application Does\n\nClinAgent can help with tasks such as:\n\n- exploring clinical trials related to diseases, drugs, devices, or interventions;\n- retrieving protocol details, outcomes, and available trial results;\n- using different LLM providers from the same UI;\n- optionally consulting PubMed when trial data alone is not enough.\n\nThe application is not a medical device and does not replace clinical judgment, literature review, or methodological validation. Generated answers must always be checked against the original sources.\n\n## Important Safety Notes\n\n- Do not submit personal data, patient-identifiable information, or sensitive health data.\n- Requests are sent to external LLM providers.\n- Answers may contain errors, omissions, or incomplete reasoning.\n- The files in [`db/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/db) are temporary working files, not a validated clinical database.\n\n## How It Works\n\nAt a high level, the request flow is:\n\n1. A user enters a question in the web UI.\n2. The browser sends a `POST /chat` request to the Flask backend.\n3. Flask validates the payload and forwards it to the chatbot workflow.\n4. LangGraph runs a ReAct-style agent backed by the selected LLM.\n5. The agent decides whether to:\n - answer directly;\n - retrieve trial data from ClinicalTrials.gov;\n - inspect the local CSV cache with Python and Pandas;\n - use PubMed for medical literature support.\n6. The final answer is returned as JSON and rendered in the chat UI.\n\nThe main pieces of the system are:\n\n- [`main.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/main.py): application entry point;\n- [`app/__init__.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/__init__.py): Flask app factory;\n- [`app/client/routes.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/client/routes.py): HTTP endpoints, including `/chat`;\n- [`app/client/chatbot.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/client/chatbot.py): chatbot wrapper around the workflow;\n- [`app/rag_agent/workflow.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/rag_agent/workflow.py): LangGraph orchestration;\n- [`app/rag_agent/react_agent.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/rag_agent/react_agent.py): ReAct agent and tool selection rules;\n- [`app/rag_agent/clinical_tool/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/rag_agent/clinical_tool): ClinicalTrials.gov integration and local dataset utilities;\n- [`app/templates/index.html`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/templates/index.html) and [`app/static/style.css`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/static/style.css): web UI.\n\n## Runtime Behavior\n\nClinAgent maintains two temporary files under [`db/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/db):\n\n- `ClinicalTrialsDB.csv`\n- `ClinicalTrialsDB.json`\n\nThese files are cleared automatically every time the application starts, both locally and in Docker. This means each new app startup begins with a fresh working session.\n\n## Supported Models\n\nThe UI currently exposes these model options:\n\n- `gemini` -> `gemini-3-flash-preview`\n- `deepseek-v3` -> `deepseek-chat`\n- `deepseek-r1` -> `deepseek-reasoner`\n\nAn API key can be supplied in either of these ways:\n\n- directly in the web UI;\n- through environment variables.\n\nThe main environment variable mappings used by the code are:\n\n- `GEMINI_API` or `GEMINI_API_2` for Gemini;\n- `DEEPSEEK_API_KEY` for DeepSeek V3 and DeepSeek R1.\n\n## Requirements\n\nFor Docker execution:\n\n- Docker\n- Docker Compose\n\nFor local execution:\n\n- Python 3.11 recommended\n- `venv`\n- internet access\n- at least one valid API key for a supported model\n\nPython 3.11 is the recommended local version because it matches the base image used in the [`Dockerfile`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/Dockerfile). Local installs also work on Python 3.12 and 3.13 because [`requirements.txt`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/requirements.txt) selects compatible `pandas` and `numpy` builds for newer interpreters.\n\n## Environment Variables\n\nThe repository includes an example file:\n\n```bash\ncp .env.example .env\n```\n\nThe most important variables are:\n\n- `FLASK_HOST`: host bound by the Flask process;\n- `FLASK_PORT`: port used by Flask inside the Python process;\n- `HOST_PORT`: host port published by Docker Compose;\n- `SECRET_KEY`: Flask secret key;\n- `GEMINI_API`, `DEEPSEEK_API_KEY`: model API keys;\n- `CSV_PATH`, `JSON_PATH`: paths for the temporary trial files.\n\nThe default template is:\n\n```env\n# Flask\nFLASK_HOST=0.0.0.0\nFLASK_PORT=7860\nHOST_PORT=5000\nFLASK_DEBUG=false\nSECRET_KEY=dev-secret-key\n\n# Data sources\nCLINICAL_API=https://clinicaltrials.gov/api/v2/\nCSV_PATH=./db/ClinicalTrialsDB.csv\nJSON_PATH=./db/ClinicalTrialsDB.json\n\n# LLM providers\nGEMINI_API=\nGEMINI_API_2=\nGEMINI_API_3=\nDEEPSEEK_API_KEY=\n\n# Reserved for future integrations\nMISTRAL_AI_API=\nGROQ_API_KEY=\nOPEN_ROUTER_API_KEY=\n```\n\nImportant note for local execution: `python main.py` does not automatically load `.env`, so you must export the variables in your shell first if you want to rely on them locally.\n\n## Running With Docker\n\nDocker is the easiest way to start the project with a reproducible environment.\n\n### 1. Verify Docker\n\n```bash\ndocker --version\ndocker compose version\n```\n\n### 2. Create the environment file\n\n```bash\ncp .env.example .env\n```\n\nFill in at least one API key if you want the backend to work immediately. If needed, you can still enter a key manually in the web UI.\n\n### 3. Start the web application\n\n```bash\ndocker compose up --build web\n```\n\nBy default:\n\n- Flask runs on port `7860` inside the container;\n- Docker publishes it on host port `5000`.\n\nOpen:\n\n```text\nhttp://127.0.0.1:5000\n```\n\n### 4. Stop the containers\n\n```bash\ndocker compose down\n```\n\n### 5. Change the exposed host port\n\nIf port `5000` is already in use:\n\n```bash\nHOST_PORT=5001 docker compose up --build web\n```\n\nThen open:\n\n```text\nhttp://127.0.0.1:5001\n```\n\n### 6. View logs\n\n```bash\ndocker compose logs -f web\n```\n\n## Running Locally Without Docker\n\nThis mode is useful for development, debugging, and source-level inspection.\n\n### 1. Create a virtual environment\n\nRecommended:\n\n```bash\npython3.11 -m venv .venv\n```\n\nIf `python3.11` is not available but `python3` already points to Python 3.11, 3.12, or 3.13:\n\n```bash\npython3 -m venv .venv\n```\n\n### 2. Activate the virtual environment\n\n```bash\nsource .venv/bin/activate\n```\n\n### 3. Install dependencies\n\n```bash\npython -m pip install --upgrade pip\npython -m pip install -r requirements.txt\n```\n\n### 4. Create `.env`\n\n```bash\ncp .env.example .env\n```\n\n### 5. Export the environment variables\n\nBecause the app does not auto-load `.env` outside Docker, export it before starting Flask:\n\n```bash\nset -a\nsource .env\nset +a\n```\n\nIf you do not want to export `.env`, you can also set variables manually in your shell.\n\n### 6. Start the application\n\n```bash\npython main.py\n```\n\nBy default the local server listens on:\n\n```text\nhttp://127.0.0.1:7860\n```\n\nIf `FLASK_PORT` is set to a different value, use that port instead.\n\n## HTTP API\n\nThe main backend endpoint is:\n\n```text\nPOST /chat\n```\n\nExample request:\n\n```bash\ncurl -X POST http://127.0.0.1:7860/chat \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"question\": \"What are the main outcomes of trials on pembrolizumab in lung cancer?\",\n \"model\": \"gemini\",\n \"api_key\": \"YOUR_API_KEY\"\n }'\n```\n\nExample response shape:\n\n```json\n{\n \"response\": \"...\"\n}\n```\n\n## Project Structure\n\n```text\nclinagent/\n├── app/\n│ ├── client/ # Flask routes and chatbot wrapper\n│ ├── large_language_models/ # Model connectors\n│ ├── rag_agent/ # LangGraph workflow and tools\n│ ├── static/ # CSS and static assets\n│ └── templates/ # HTML templates\n├── db/ # Temporary ClinicalTrials working files\n├── Dockerfile\n├── docker-compose.yml\n├── main.py\n├── requirements.txt\n└── README.md\n```\n\n## Notes For Contributors\n\n- The web UI is rendered by Flask and enhanced with client-side JavaScript.\n- ClinicalTrials.gov data is downloaded on demand and written to local working files in [`db/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/db).\n- Those working files are reset at every application startup.\n- If you run locally, remember that `.env` is not auto-loaded by the app.\n\n## License\n\nNo license file is currently included in the repository. Add one if you plan to distribute or publish the project more broadly.\n"}, "8b256006351ab33d184104f125cf88ddfe3b488d": {"t": 1785764992.7931569, "n": 10597, "h": "6a9300f8461d5f9e", "c": "# Clinical Chat\n\nClinical Chat is a web application for exploring clinical and biomedical questions through a conversational interface. It combines a Flask web UI, multiple selectable LLM backends, a LangGraph workflow, and domain-specific tools for ClinicalTrials.gov and PubMed.\n\nThe project is designed for research and prototyping workflows where clinicians, biomedical researchers, and developers need a shared interface to ask questions, inspect clinical trial information, and compare model behavior.\n\n## What The Application Does\n\nClinical Chat can help with tasks such as:\n\n- exploring clinical trials related to diseases, drugs, devices, or interventions;\n- retrieving protocol details, outcomes, and available trial results;\n- using different LLM providers from the same UI;\n- optionally consulting PubMed when trial data alone is not enough;\n- exposing the same backend to an optional Telegram bot.\n\nThe application is not a medical device and does not replace clinical judgment, literature review, or methodological validation. Generated answers must always be checked against the original sources.\n\n## Important Safety Notes\n\n- Do not submit personal data, patient-identifiable information, or sensitive health data.\n- Requests are sent to external LLM providers.\n- Answers may contain errors, omissions, or incomplete reasoning.\n- The files in [`db/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/db) are temporary working files, not a validated clinical database.\n\n## How It Works\n\nAt a high level, the request flow is:\n\n1. A user enters a question in the web UI.\n2. The browser sends a `POST /chat` request to the Flask backend.\n3. Flask validates the payload and forwards it to the chatbot workflow.\n4. LangGraph runs a ReAct-style agent backed by the selected LLM.\n5. The agent decides whether to:\n - answer directly;\n - retrieve trial data from ClinicalTrials.gov;\n - inspect the local CSV cache with Python and Pandas;\n - use PubMed for medical literature support.\n6. The final answer is returned as JSON and rendered in the chat UI.\n\nThe main pieces of the system are:\n\n- [`main.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/main.py): application entry point;\n- [`app/__init__.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/__init__.py): Flask app factory;\n- [`app/client/routes.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/client/routes.py): HTTP endpoints, including `/chat`;\n- [`app/client/chatbot.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/client/chatbot.py): chatbot wrapper around the workflow;\n- [`app/rag_agent/workflow.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/rag_agent/workflow.py): LangGraph orchestration;\n- [`app/rag_agent/react_agent.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/rag_agent/react_agent.py): ReAct agent and tool selection rules;\n- [`app/rag_agent/clinical_tool/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/rag_agent/clinical_tool): ClinicalTrials.gov integration and local dataset utilities;\n- [`app/templates/index.html`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/templates/index.html) and [`app/static/style.css`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/app/static/style.css): web UI.\n\n## Runtime Behavior\n\nClinical Chat maintains two temporary files under [`db/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/db):\n\n- `ClinicalTrialsDB.csv`\n- `ClinicalTrialsDB.json`\n\nThese files are cleared automatically every time the application starts, both locally and in Docker. This means each new app startup begins with a fresh working session.\n\n## Supported Models\n\nThe UI currently exposes these model options:\n\n- `gemini` -> `gemini-3-flash-preview`\n- `chatgpt` -> `gpt-4o-mini` through a ChatOpenAI-compatible client\n- `deepseek-v3` -> `deepseek-chat`\n- `deepseek-r1` -> `deepseek-reasoner`\n\nAn API key can be supplied in either of these ways:\n\n- directly in the web UI;\n- through environment variables.\n\nThe main environment variable mappings used by the code are:\n\n- `GEMINI_API` or `GEMINI_API_2` for Gemini;\n- `DEEPSEEK_API_KEY` for DeepSeek V3 and DeepSeek R1;\n- `DEEPBRICKS_API_KEY` for the default `chatgpt` setup;\n- `OPENAI_API_BASE` if you want the `chatgpt` option to use a custom OpenAI-compatible endpoint.\n\n## Requirements\n\nFor Docker execution:\n\n- Docker\n- Docker Compose\n\nFor local execution:\n\n- Python 3.11 recommended\n- `venv`\n- internet access\n- at least one valid API key for a supported model\n\nPython 3.11 is the recommended local version because it matches the base image used in the [`Dockerfile`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/Dockerfile). Local installs also work on Python 3.12 and 3.13 because [`requirements.txt`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/requirements.txt) selects compatible `pandas` and `numpy` builds for newer interpreters.\n\n## Environment Variables\n\nThe repository includes an example file:\n\n```bash\ncp .env.example .env\n```\n\nThe most important variables are:\n\n- `FLASK_HOST`: host bound by the Flask process;\n- `FLASK_PORT`: port used by Flask inside the Python process;\n- `HOST_PORT`: host port published by Docker Compose;\n- `SECRET_KEY`: Flask secret key;\n- `GEMINI_API`, `DEEPSEEK_API_KEY`, `DEEPBRICKS_API_KEY`: model API keys;\n- `TELEGRAM_API_KEY`: only required for the optional Telegram bot;\n- `CSV_PATH`, `JSON_PATH`: paths for the temporary trial files.\n\nThe default template is:\n\n```env\n# Flask\nFLASK_HOST=0.0.0.0\nFLASK_PORT=7860\nHOST_PORT=5000\nFLASK_DEBUG=false\nSECRET_KEY=dev-secret-key\n\n# Data sources\nCLINICAL_API=https://clinicaltrials.gov/api/v2/\nCSV_PATH=./db/ClinicalTrialsDB.csv\nJSON_PATH=./db/ClinicalTrialsDB.json\n\n# LLM providers\nGEMINI_API=\nGEMINI_API_2=\nGEMINI_API_3=\nDEEPSEEK_API_KEY=\nDEEPBRICKS_API_KEY=\nOPENAI_API_BASE=\n\n# Reserved for future integrations\nMISTRAL_AI_API=\nGROQ_API_KEY=\nOPEN_ROUTER_API_KEY=\n\n# Optional Telegram bot\nTELEGRAM_API_KEY=\n```\n\nImportant note for local execution: `python main.py` does not automatically load `.env`, so you must export the variables in your shell first if you want to rely on them locally.\n\n## Running With Docker\n\nDocker is the easiest way to start the project with a reproducible environment.\n\n### 1. Verify Docker\n\n```bash\ndocker --version\ndocker compose version\n```\n\n### 2. Create the environment file\n\n```bash\ncp .env.example .env\n```\n\nFill in at least one API key if you want the backend to work immediately. If needed, you can still enter a key manually in the web UI.\n\n### 3. Start the web application\n\n```bash\ndocker compose up --build web\n```\n\nBy default:\n\n- Flask runs on port `7860` inside the container;\n- Docker publishes it on host port `5000`.\n\nOpen:\n\n```text\nhttp://127.0.0.1:5000\n```\n\n### 4. Stop the containers\n\n```bash\ndocker compose down\n```\n\n### 5. Change the exposed host port\n\nIf port `5000` is already in use:\n\n```bash\nHOST_PORT=5001 docker compose up --build web\n```\n\nThen open:\n\n```text\nhttp://127.0.0.1:5001\n```\n\n### 6. View logs\n\n```bash\ndocker compose logs -f web\n```\n\n### 7. Start the optional Telegram bot\n\n```bash\ndocker compose --profile telegram up --build\n```\n\nThis starts:\n\n- `web`\n- `telegram`\n\nThe Telegram service requires `TELEGRAM_API_KEY` in `.env`.\n\n## Running Locally Without Docker\n\nThis mode is useful for development, debugging, and source-level inspection.\n\n### 1. Create a virtual environment\n\nRecommended:\n\n```bash\npython3.11 -m venv .venv\n```\n\nIf `python3.11` is not available but `python3` already points to Python 3.11, 3.12, or 3.13:\n\n```bash\npython3 -m venv .venv\n```\n\n### 2. Activate the virtual environment\n\n```bash\nsource .venv/bin/activate\n```\n\n### 3. Install dependencies\n\n```bash\npython -m pip install --upgrade pip\npython -m pip install -r requirements.txt\n```\n\n### 4. Create `.env`\n\n```bash\ncp .env.example .env\n```\n\n### 5. Export the environment variables\n\nBecause the app does not auto-load `.env` outside Docker, export it before starting Flask:\n\n```bash\nset -a\nsource .env\nset +a\n```\n\nIf you do not want to export `.env`, you can also set variables manually in your shell.\n\n### 6. Start the application\n\n```bash\npython main.py\n```\n\nBy default the local server listens on:\n\n```text\nhttp://127.0.0.1:7860\n```\n\nIf `FLASK_PORT` is set to a different value, use that port instead.\n\n## Optional Telegram Bot\n\nThe repository also contains [`main_telegram_bot.py`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/main_telegram_bot.py), which forwards Telegram messages to the same Flask `/chat` endpoint.\n\nTypical uses:\n\n- demoing the same assistant outside the browser;\n- running a lightweight chat bridge without changing backend logic.\n\nFor Docker, use the `telegram` profile shown above.\n\nFor a local run, make sure:\n\n- the Flask app is already running;\n- `TELEGRAM_API_KEY` is exported;\n- `CHATBOT_ENDPOINT` points to the Flask `/chat` URL if you are not using the default.\n\nExample local start:\n\n```bash\nset -a\nsource .env\nset +a\nexport CHATBOT_ENDPOINT=http://127.0.0.1:7860/chat\npython main_telegram_bot.py\n```\n\n## HTTP API\n\nThe main backend endpoint is:\n\n```text\nPOST /chat\n```\n\nExample request:\n\n```bash\ncurl -X POST http://127.0.0.1:7860/chat \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"question\": \"What are the main outcomes of trials on pembrolizumab in lung cancer?\",\n \"model\": \"gemini\",\n \"api_key\": \"YOUR_API_KEY\"\n }'\n```\n\nExample response shape:\n\n```json\n{\n \"response\": \"...\"\n}\n```\n\n## Project Structure\n\n```text\nclinical-chat/\n├── app/\n│ ├── client/ # Flask routes and chatbot wrapper\n│ ├── large_language_models/ # Model connectors\n│ ├── rag_agent/ # LangGraph workflow and tools\n│ ├── static/ # CSS and static assets\n│ └── templates/ # HTML templates\n├── db/ # Temporary ClinicalTrials working files\n├── Dockerfile\n├── docker-compose.yml\n├── main.py\n├── main_telegram_bot.py\n├── requirements.txt\n└── README.md\n```\n\n## Notes For Contributors\n\n- The web UI is rendered by Flask and enhanced with client-side JavaScript.\n- ClinicalTrials.gov data is downloaded on demand and written to local working files in [`db/`](/Users/antoninovaccarella/Documents/GitHub/clinical-chat/db).\n- Those working files are reset at every application startup.\n- If you run locally, remember that `.env` is not auto-loaded by the app.\n\n## License\n\nNo license file is currently included in the repository. Add one if you plan to distribute or publish the project more broadly.\n"}}, "docker-compose.yml": {"d3306e5c99e79053490a1c8897dbddb2c56ec474": {"t": 1785746980.3082209, "n": 801, "h": "0ad593aa6ea5cea2", "c": "services:\n web:\n build:\n context: .\n ports:\n - \"${HOST_PORT:-5000}:7860\"\n environment:\n FLASK_HOST: 0.0.0.0\n FLASK_PORT: ${FLASK_PORT:-7860}\n FLASK_DEBUG: ${FLASK_DEBUG:-false}\n SECRET_KEY: ${SECRET_KEY:-dev-secret-key}\n CLINICAL_API: ${CLINICAL_API:-https://clinicaltrials.gov/api/v2/}\n CSV_PATH: ${CSV_PATH:-/app/db/ClinicalTrialsDB.csv}\n JSON_PATH: ${JSON_PATH:-/app/db/ClinicalTrialsDB.json}\n GEMINI_API: ${GEMINI_API:-}\n GEMINI_API_2: ${GEMINI_API_2:-}\n GEMINI_API_3: ${GEMINI_API_3:-}\n MISTRAL_AI_API: ${MISTRAL_AI_API:-}\n GROQ_API_KEY: ${GROQ_API_KEY:-}\n OPEN_ROUTER_API_KEY: ${OPEN_ROUTER_API_KEY:-}\n DEEPSEEK_API_KEY: ${DEEPSEEK_API_KEY:-}\n volumes:\n - ./db:/app/db\n restart: unless-stopped\n"}, "0888b85d2f6eae25519d96f4d698a8abf028618d": {"t": 1785764988.8427002, "n": 801, "h": "0ad593aa6ea5cea2", "c": "services:\n web:\n build:\n context: .\n ports:\n - \"${HOST_PORT:-5000}:7860\"\n environment:\n FLASK_HOST: 0.0.0.0\n FLASK_PORT: ${FLASK_PORT:-7860}\n FLASK_DEBUG: ${FLASK_DEBUG:-false}\n SECRET_KEY: ${SECRET_KEY:-dev-secret-key}\n CLINICAL_API: ${CLINICAL_API:-https://clinicaltrials.gov/api/v2/}\n CSV_PATH: ${CSV_PATH:-/app/db/ClinicalTrialsDB.csv}\n JSON_PATH: ${JSON_PATH:-/app/db/ClinicalTrialsDB.json}\n GEMINI_API: ${GEMINI_API:-}\n GEMINI_API_2: ${GEMINI_API_2:-}\n GEMINI_API_3: ${GEMINI_API_3:-}\n MISTRAL_AI_API: ${MISTRAL_AI_API:-}\n GROQ_API_KEY: ${GROQ_API_KEY:-}\n OPEN_ROUTER_API_KEY: ${OPEN_ROUTER_API_KEY:-}\n DEEPSEEK_API_KEY: ${DEEPSEEK_API_KEY:-}\n volumes:\n - ./db:/app/db\n restart: unless-stopped\n"}, "8b256006351ab33d184104f125cf88ddfe3b488d": {"t": 1785764990.4779675, "n": 1195, "h": "7aa7bea2cb584947", "c": "services:\n web:\n build:\n context: .\n ports:\n - \"${HOST_PORT:-5000}:7860\"\n environment:\n FLASK_HOST: 0.0.0.0\n FLASK_PORT: ${FLASK_PORT:-7860}\n FLASK_DEBUG: ${FLASK_DEBUG:-false}\n SECRET_KEY: ${SECRET_KEY:-dev-secret-key}\n CLINICAL_API: ${CLINICAL_API:-https://clinicaltrials.gov/api/v2/}\n CSV_PATH: ${CSV_PATH:-/app/db/ClinicalTrialsDB.csv}\n JSON_PATH: ${JSON_PATH:-/app/db/ClinicalTrialsDB.json}\n GEMINI_API: ${GEMINI_API:-}\n GEMINI_API_2: ${GEMINI_API_2:-}\n GEMINI_API_3: ${GEMINI_API_3:-}\n MISTRAL_AI_API: ${MISTRAL_AI_API:-}\n GROQ_API_KEY: ${GROQ_API_KEY:-}\n OPEN_ROUTER_API_KEY: ${OPEN_ROUTER_API_KEY:-}\n DEEPSEEK_API_KEY: ${DEEPSEEK_API_KEY:-}\n DEEPBRICKS_API_KEY: ${DEEPBRICKS_API_KEY:-}\n TELEGRAM_API_KEY: ${TELEGRAM_API_KEY:-}\n volumes:\n - ./db:/app/db\n restart: unless-stopped\n\n telegram:\n build:\n context: .\n command: python main_telegram_bot.py\n environment:\n TELEGRAM_API_KEY: ${TELEGRAM_API_KEY:-}\n CHATBOT_ENDPOINT: ${CHATBOT_ENDPOINT:-http://web:7860/chat}\n depends_on:\n - web\n profiles:\n - telegram\n restart: unless-stopped\n"}}}} |