{"id":26856721,"url":"https://github.com/ebodshojaei/sentinel","last_synced_at":"2026-05-13T07:02:54.558Z","repository":{"id":285018475,"uuid":"956817053","full_name":"EbodShojaei/sentinel","owner":"EbodShojaei","description":"Sentinel is an AI agent that retrieves PubMed publications using phi3.5 with phidata to generate and run a MeSH search on NCBI Entrez.","archived":false,"fork":false,"pushed_at":"2025-04-29T23:08:42.000Z","size":32,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-29T23:29:53.549Z","etag":null,"topics":["biopython","dotenv","entrez","ncbi","ollama","pandas","phi3","phidata","pubmed","python","sqlalchemy","xlsx"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EbodShojaei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-28T23:06:59.000Z","updated_at":"2025-04-29T23:08:44.000Z","dependencies_parsed_at":"2025-04-29T23:25:00.929Z","dependency_job_id":"4b1d13be-04c2-46fe-bef9-799d06931c1c","html_url":"https://github.com/EbodShojaei/sentinel","commit_stats":null,"previous_names":["ebodshojaei/sentinel_ai","ebodshojaei/sentinel"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/EbodShojaei/sentinel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EbodShojaei%2Fsentinel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EbodShojaei%2Fsentinel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EbodShojaei%2Fsentinel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EbodShojaei%2Fsentinel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EbodShojaei","download_url":"https://codeload.github.com/EbodShojaei/sentinel/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EbodShojaei%2Fsentinel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278486278,"owners_count":25994941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["biopython","dotenv","entrez","ncbi","ollama","pandas","phi3","phidata","pubmed","python","sqlalchemy","xlsx"],"created_at":"2025-03-31T00:23:22.245Z","updated_at":"2025-10-05T16:53:21.395Z","avatar_url":"https://github.com/EbodShojaei.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sentinel | Terminal-Based AI Agent for PubMed Search\n\nThis application is a terminal-based AI agent that:\n\n- Accepts a natural language search query from the user.\n- Uses a local phi3.5 model (via Ollama and phidata) to generate a research purpose and a detailed MeSH search strategy.\n- Executes the search on PubMed using a free API (via Entrez from Biopython).\n- Retrieves the top 250 relevant articles, sorted by relevance and publication year.\n- Stores the search results and metadata in a relational SQL database.\n- Allows the user to export the search results and metadata to an Excel file with two tabs.\n\nWatch the demo (as of version 1.0.3): [Video](https://youtu.be/MO7oLftEFaY?si=zbub_zpP1GBzms8R)\n\n## File Structure\n\n```plaintext\nsentinel/\n├── src/\n│   ├── __init__.py\n│   ├── agent.py\n│   ├── config.py\n│   ├── menu.py\n│   └── utils/\n│       ├── __init__.py\n│       ├── xlsx_export.py\n│       ├── database.py\n│       ├── extract_values.py\n│       └── pubmed_search.py\n├── tests/\n│   ├── __init__.py\n│   └── test_pubmed_search.py\n├── main.py\n├── requirements.txt\n└── setup.sh\n```\n\n## Requirements\n\nThe application uses the following Python packages:\n\n- phidata\n- ollama\n- sqlalchemy\n- requests\n- biopython\n- openpyxl\n- pandas\n- python-dotenv\n\nSetup virtual Python environment and install all dependencies with:\n\n```bash\n./setup.sh\n```\n\n## Configuration\n\nCreate a `.env` file (make a copy of `.env.example`) in the project root with your configuration. For example:\n\n```dotenv\n# .env file\nENTREZ_EMAIL=your.email@example.com\nPUBMED_API_KEY=your_pubmed_api_key\nMODEL_ID=phi3.5\n```\n\n## Usage\n\nRun the application from the terminal **with provided arguments**:\n\n```bash\npython main.py --query \"efficacy of placebo injections in knee osteoarthritis patients between 2000 and 2025\" --export\n```\n\n- If `--query` is not provided, you will be prompted to enter it interactively.\n- Optionally specify `--min_year` and `--max_year` for the publication date range (defaults to the last 5 years).\n- The `--export` flag will export the results to an Excel file (`output.xlsx`).\n\nAlternatively, run the application **without any arguments** to open the menu and choose between running a new search, or exporting prior search results:\n\n```bash\npython main.py\nUsing PubMed API key for enhanced rate limits.\n\n[Sentinel]: Welcome to Sentinel, how can I assist you today?\n\nMenu:\n1. Run new PubMed search\n2. View history and export results\n3. Quit\nEnter your choice: 1\n[Sentinel]: Enter your search query or 'r' to return: r\n[Sentinel]: Returning to menu.\n\nMenu:\n1. Run new PubMed search\n2. View history and export results\n3. Quit\nEnter your choice: 2\n[1] Research Purpose: To assess whether placebo injections have significant efficacy compared to standard treatments or no intervention at all, on symptom relief for knee osteoarthritis patients within a controlled clinical study setting., Date Range: 2000-2025\n[2] Research Purpose: To assess the efficacy of placebo injections as a therapeutic intervention for alleviating pain symptoms among knee osteoarthritis patients., Date Range: 2000-2025\n\n[Sentinel]: Would you like to export any of these? Enter number or 'r' to return: r\n[Sentinel]: Returning to menu.\n\nMenu:\n1. Run new PubMed search\n2. View history and export results\n3. Quit\nEnter your choice: 3\n\n[Sentinel]: Goodbye!\n```\n\n## Example Output\n\nSee the below example for running a custom query:\n\n```bash\npython main.py\nUsing PubMed API key for enhanced rate limits.\nEnter your search query: efficacy of placebo injections in knee osteoarthritis patients\nNo date range found in the query. Using default values: 2020 to 2025\nResearch Purpose: To investigate the efficacy and impacts of placebo injections on pain management and joint function outcomes among patients diagnosed with knee osteoarthritis undergoing randomized controlled trials.\nMeSH Search Strategy: (placebo OR therapeutic injections) AND knee osteoarthritis AND (pain relief OR improved joint function) AND randomized AND control trial\nFound 96 PubMed IDs\nRetrieved 96 search results\nData stored successfully in the database.\n```\n\nWith custom non-default date in query:\n\n```bash\npython main.py\nUsing PubMed API key for enhanced rate limits.\nEnter your search query: efficacy of placebo injections in knee osteoarthritis patients between 2000 and 2025\nExtracted date range from query: 2000 to 2025\nResearch Purpose: (placebo) versus active interventions in reducing pain and improving joint function for knee osteoarthritis patients undergoing clinical studies.\nMeSH Search Strategy: (placebo OR sham treatment) AND knee osteoarthritis patients] AND ([pain reduction OR improved joint function])\nFound 250 PubMed IDs\nRetrieved 249 search results\nData stored successfully in the database.\n```\n\nWith wider outcome criteria (wider scope of efficacy outcomes e.g., pain relief):\n\n```bash\npython main.py --export\nUsing PubMed API key for enhanced rate limits.\nEnter your search query: efficacy of placebo injections in knee osteoarthritis patients\nNo date range found in the query. Using default values: 2020 to 2025\nResearch Purpose: To evaluate the therapeutic effectiveness and potential benefits on patient-reported pain levels in knee osteoarthritis patients receiving placebo injections as compared to a control group not undergoing any intervention or those treated with standard pharmacological therapies.\nMeSH Search Strategy: (Pain OR pain) AND (\"Knee Osteoarthritis\" OR Knees OR arthrosis OR osteophytes) AND Placebo And Effectiveness NOT Drug Or Medication\nFound 250 PubMed IDs\nRetrieved 250 search results\nData stored successfully in the database.\nData exported successfully to output.xlsx\n```\n\nIf search fails to return any entries, the ai tries again:\n\n```bash\npython main.py --query \"efficacy of placebo injections in knee osteoarthritis patients between 2000 and 2025\" --export\nUsing PubMed API key for enhanced rate limits.\nExtracted date range from query: 2000 to 2025\nResearch Purpose: The purpose of this study is to assess whether placebo injections provide therapeutic benefits or improvement in knee function among patients aged between 65-74 suffering from osteoarthritis.\nMeSH Search Strategy: (no time zone provided) Reasoning Steps for Boolean Search Query Formulation To assess studies on placebo injections' efficacy, focusing specifically on knee osteoarthritis patients aged between 65 to 74 years old without considering date ranges or using compound terms. The boolean search query constructed should combine relevant keywords related to the intervention (placebo/sham treatment), outcome measures of interest such as 'knee pain' and 'reduced mobility', along with population-specific criteria:\nFound 0 PubMed IDs\nRetrieved 0 search results\nNo results found. Retries: 3\nResearch Purpose: To investigate the impact and effectiveness of placebo injections specifically as pain management or therapeutic intervention for knee osteoarthritis patients, with a focus on treatment outcomes.\nMeSH Search Strategy: (osteoarthritis OR joint disease) AND knees AND (pain relief OR analgesic OR therapeutic treatment OR intervention therapy) AND placebo injection\nFound 250 PubMed IDs\nRetrieved 249 search results after retry.\nData stored successfully in the database.\nData exported successfully to output.xlsx\n```\n\n## License\n\nThis project is released under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febodshojaei%2Fsentinel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Febodshojaei%2Fsentinel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febodshojaei%2Fsentinel/lists"}