aiagents4pharma 1.44.0__py3-none-any.whl → 1.45.1__py3-none-any.whl

aiagents4pharma/talk2scholars/agents/zotero_agent.py

@@ -5,22 +5,23 @@ Agent for interacting with Zotero with human-in-the-loop features
 """
 
 import logging
-from typing import Any, Dict
-import hydra
+from typing import Any
 
+import hydra
 from langchain_core.language_models.chat_models import BaseChatModel
-from langgraph.graph import START, StateGraph
-from langgraph.prebuilt import create_react_agent, ToolNode
 from langgraph.checkpoint.memory import MemorySaver
+from langgraph.graph import START, StateGraph
+from langgraph.prebuilt import ToolNode, create_react_agent
+
 from ..state.state_talk2scholars import Talk2Scholars
-from ..tools.zotero.zotero_read import zotero_read
-from ..tools.zotero.zotero_review import zotero_review
-from ..tools.zotero.zotero_write import zotero_write
 from ..tools.s2.display_dataframe import display_dataframe
 from ..tools.s2.query_dataframe import query_dataframe
 from ..tools.s2.retrieve_semantic_scholar_paper_id import (
     retrieve_semantic_scholar_paper_id,
 )
+from ..tools.zotero.zotero_read import zotero_read
+from ..tools.zotero.zotero_review import zotero_review
+from ..tools.zotero.zotero_write import zotero_write
 
 # Initialize logger
 logging.basicConfig(level=logging.INFO)
@@ -49,7 +50,7 @@ def get_app(uniq_id, llm_model: BaseChatModel):
         >>> result = app.invoke(initial_state)
     """
 
-    def zotero_agent_node(state: Talk2Scholars) -> Dict[str, Any]:
+    def zotero_agent_node(state: Talk2Scholars) -> dict[str, Any]:
         """
         Processes the user query and retrieves relevant research papers from Zotero.
 
@@ -68,9 +69,7 @@ def get_app(uniq_id, llm_model: BaseChatModel):
             >>> result = zotero_agent_node(current_state)
             >>> papers = result.get("papers", [])
         """
-        logger.log(
-            logging.INFO, "Creating Agent_Zotero node with thread_id %s", uniq_id
-        )
+        logger.log(logging.INFO, "Creating Agent_Zotero node with thread_id %s", uniq_id)
         result = model.invoke(state, {"configurable": {"thread_id": uniq_id}})
 
         return result

aiagents4pharma/talk2scholars/configs/__init__.py

@@ -2,8 +2,6 @@
 This package contains configuration settings and prompts used by various AI agents
 """
 
-from . import agents
-from . import tools
-from . import app
+from . import agents, app, tools
 
 __all__ = ["agents", "tools", "app"]

aiagents4pharma/talk2scholars/configs/agents/talk2scholars/__init__.py

@@ -2,9 +2,6 @@
 Import all the modules in the package
 """
 
-from . import s2_agent
-from . import main_agent
-from . import pdf_agent
-from . import zotero_agent
+from . import main_agent, pdf_agent, s2_agent, zotero_agent
 
 __all__ = ["s2_agent", "main_agent", "pdf_agent", "zotero_agent"]

aiagents4pharma/talk2scholars/configs/agents/talk2scholars/main_agent/default.yaml

@@ -26,7 +26,7 @@ system_prompt: |
 
   **IMPORTANT – Q&A Disambiguation (Pause Before Acting):**
   - When the user asks a question like “Tell me more about X”, “What does the first article say?”, or similar:
-    1) **Pause and ask**:  
+    1) **Pause and ask**:
        “Do you want me to answer using the **PDF content** (full text), or using the **last displayed table** (metadata only)?”
        - Accept synonyms: *PDF, full text, paper text* → **PDF content**.
        - Accept synonyms: *last displayed table, table above, results table, search results* → **metadata/table**.

aiagents4pharma/talk2scholars/configs/agents/talk2scholars/pdf_agent/default.yaml

@@ -2,7 +2,7 @@ _target_: agents.pdf_agent.get_app
 pdf_agent: |
   You are the **PDF Agent**.
 
-  **Primary Role:**  
+  **Primary Role:**
   Perform question-and-answer tasks on the **full text** of papers, articles, or PDFs that are already available
   (downloaded locally, uploaded by the user, or stored in the user's Zotero library).
 

aiagents4pharma/talk2scholars/configs/agents/talk2scholars/s2_agent/default.yaml

@@ -2,12 +2,12 @@ _target_: agents.s2_agent.get_app
 s2_agent: |
   You are the **S2 Agent**.
 
-  **Primary Role:**  
-  - Search for academic papers.  
-  - Provide recommendations **only when explicitly requested** by the user.  
+  **Primary Role:**
+  - Search for academic papers.
+  - Provide recommendations **only when explicitly requested** by the user.
   - Display results using the `display_dataframe` tool.
 
-  **Additional Capability – Metadata Queries:**  
+  **Additional Capability – Metadata Queries:**
   - You can query the last displayed results table using the `query_dataframe` tool to filter, sort, or extract metadata (including paper IDs).
   - Use this tool only for **metadata-level** questions (not full PDF content).
 
@@ -22,10 +22,10 @@ s2_agent: |
        END
        ---
     3) Do **not** call any other S2 tools (e.g., `retrieve_semantic_scholar_paper_id`, `get_single_paper_recommendations`, `get_multi_paper_recommendations`) in this mode.
-    4) If no last displayed table exists, reply:  
-       `IDS: NONE`  
-       `SOURCE: none (no results table available)`  
-       `END`  
+    4) If no last displayed table exists, reply:
+       `IDS: NONE`
+       `SOURCE: none (no results table available)`
+       `END`
        and stop.
 
   **Tool-Selection Policy (default mode):**

aiagents4pharma/talk2scholars/configs/agents/talk2scholars/zotero_agent/default.yaml

@@ -2,18 +2,18 @@ _target_: agents.zotero_agent.get_app
 zotero_agent: |
   You are the **Zotero Agent**.
 
-  **Primary Role:**  
-  - Read from the user's Zotero library (list items, retrieve metadata, check existing entries).  
-  - Write to the user's Zotero library (save new papers, update existing records) — only with explicit user approval.  
+  **Primary Role:**
+  - Read from the user's Zotero library (list items, retrieve metadata, check existing entries).
+  - Write to the user's Zotero library (save new papers, update existing records) — only with explicit user approval.
   - Display Zotero query results using "display_dataframe" tool.
 
-  **Rules & Boundaries:**  
+  **Rules & Boundaries:**
   - Never save papers to Zotero without **explicit human approval**. If approval is denied, do not retry unless the user changes their decision.
   - Do not search for papers on the web — that is the `s2_agent`’s role.
   - Do not perform PDF content analysis — that is the `pdf_agent`’s role.
   - Do not download PDFs directly — that is the `paper_download_agent`’s role.
 
-  **Examples:**  
-  - “Show me all papers I saved last month.”  
-  - “Check if I already have this paper in Zotero.”  
+  **Examples:**
+  - “Show me all papers I saved last month.”
+  - “Check if I already have this paper in Zotero.”
   - “Save this paper to Zotero” → Ask for explicit approval before saving.

aiagents4pharma/talk2scholars/configs/tools/__init__.py

@@ -2,12 +2,14 @@
 Import all the modules in the package
 """
 
-from . import search
-from . import single_paper_recommendation
-from . import multi_paper_recommendation
-from . import question_and_answer
-from . import zotero_read
-from . import zotero_write
+from . import (
+    multi_paper_recommendation,
+    question_and_answer,
+    search,
+    single_paper_recommendation,
+    zotero_read,
+    zotero_write,
+)
 
 __all__ = [
     "search",

aiagents4pharma/talk2scholars/docker-compose/cpu/.env.example

@@ -0,0 +1,21 @@
+# .env.example (DO NOT put actual API keys here, read the README.md)
+
+# OPENAI API KEY
+OPENAI_API_KEY=your_openai_api_key_here
+
+# LangSmith API KEY
+LANGCHAIN_TRACING_V2=true
+LANGCHAIN_API_KEY=your_langchain_api_key_heres
+
+# NVIDIA API KEY
+NVIDIA_API_KEY=your_nvidia_api_key_here
+
+# ZOTERO API KEY
+ZOTERO_API_KEY=your_zotero_api_key_here
+ZOTERO_USER_ID=your_zotero_user_id_here
+
+# Set environment variables for data loader
+MILVUS_HOST=milvus-standalone
+MILVUS_PORT=19530
+MILVUS_DB_NAME=pdf_rag_db
+MILVUS_COLLECTION_NAME=pdf_rag_documents

aiagents4pharma/talk2scholars/docker-compose/cpu/docker-compose.yml

@@ -0,0 +1,90 @@
+version: "1.0.0"
+
+services:
+  # talk2scholars
+  talk2scholars:
+    container_name: talk2scholars
+    image: vpatientengine/talk2scholars:latest
+    platform: linux/amd64
+    ports:
+      - "8501:8501"
+    environment:
+      - MILVUS_HOST=milvus-standalone
+      - MILVUS_PORT=19530
+    env_file:
+      - .env
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8501/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+    depends_on:
+      milvus-standalone:
+        condition: service_healthy
+
+  # Milvus Dependencies
+  etcd:
+    container_name: milvus-etcd
+    image: quay.io/coreos/etcd:v3.5.18
+    environment:
+      - ETCD_AUTO_COMPACTION_MODE=revision
+      - ETCD_AUTO_COMPACTION_RETENTION=1000
+      - ETCD_QUOTA_BACKEND_BYTES=4294967296
+      - ETCD_SNAPSHOT_COUNT=50000
+    volumes:
+      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd
+    command: etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
+    healthcheck:
+      test: ["CMD", "etcdctl", "endpoint", "health"]
+      interval: 30s
+      timeout: 20s
+      retries: 3
+
+  minio:
+    container_name: milvus-minio
+    image: minio/minio:RELEASE.2024-05-28T17-19-04Z
+    environment:
+      MINIO_ACCESS_KEY: minioadmin
+      MINIO_SECRET_KEY: minioadmin
+    ports:
+      - "9001:9001"
+      - "9000:9000"
+    volumes:
+      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data
+    command: minio server /minio_data --console-address ":9001"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      interval: 30s
+      timeout: 20s
+      retries: 3
+
+  # Milvus Vector Database (CPU-only)
+  milvus-standalone:
+    container_name: milvus-standalone
+    image: milvusdb/milvus:v2.5.14
+    command: ["milvus", "run", "standalone"]
+    security_opt:
+      - seccomp:unconfined
+    environment:
+      MINIO_REGION: us-east-1
+      ETCD_ENDPOINTS: etcd:2379
+      MINIO_ADDRESS: minio:9000
+    volumes:
+      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus
+    ports:
+      - "19530:19530"
+      - "9091:9091"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
+      interval: 30s
+      start_period: 90s
+      timeout: 20s
+      retries: 3
+    depends_on:
+      - "etcd"
+      - "minio"
+
+networks:
+  milvus:
+    name: milvus

aiagents4pharma/talk2scholars/docker-compose/gpu/.env.example

@@ -0,0 +1,21 @@
+# .env.example (DO NOT put actual API keys here, read the README.md)
+
+# OPENAI API KEY
+OPENAI_API_KEY=your_openai_api_key_here
+
+# LangSmith API KEY
+LANGCHAIN_TRACING_V2=true
+LANGCHAIN_API_KEY=your_langchain_api_key_heres
+
+# NVIDIA API KEY
+NVIDIA_API_KEY=your_nvidia_api_key_here
+
+# ZOTERO API KEY
+ZOTERO_API_KEY=your_zotero_api_key_here
+ZOTERO_USER_ID=your_zotero_user_id_here
+
+# Set environment variables for data loader
+MILVUS_HOST=milvus-standalone
+MILVUS_PORT=19530
+MILVUS_DB_NAME=pdf_rag_db
+MILVUS_COLLECTION_NAME=pdf_rag_documents

aiagents4pharma/talk2scholars/docker-compose/gpu/docker-compose.yml

@@ -0,0 +1,105 @@
+version: "1.0.0"
+
+services:
+  # talk2scholars
+  talk2scholars:
+    container_name: talk2scholars
+    image: vpatientengine/talk2scholars:latest
+    platform: linux/amd64
+    ports:
+      - "8501:8501"
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              capabilities: ["gpu"]
+              device_ids: ["0"]
+    environment:
+      - MILVUS_HOST=milvus-standalone
+      - MILVUS_PORT=19530
+    env_file:
+      - .env
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8501/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+    depends_on:
+      milvus-standalone:
+        condition: service_healthy
+
+  # Milvus Dependencies
+  etcd:
+    container_name: milvus-etcd
+    image: quay.io/coreos/etcd:v3.5.18
+    environment:
+      - ETCD_AUTO_COMPACTION_MODE=revision
+      - ETCD_AUTO_COMPACTION_RETENTION=1000
+      - ETCD_QUOTA_BACKEND_BYTES=4294967296
+      - ETCD_SNAPSHOT_COUNT=50000
+    volumes:
+      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd
+    command: etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
+    healthcheck:
+      test: ["CMD", "etcdctl", "endpoint", "health"]
+      interval: 30s
+      timeout: 20s
+      retries: 3
+
+  minio:
+    container_name: milvus-minio
+    image: minio/minio:RELEASE.2023-03-20T20-16-18Z
+    environment:
+      MINIO_ACCESS_KEY: minioadmin
+      MINIO_SECRET_KEY: minioadmin
+    ports:
+      - "9001:9001"
+      - "9000:9000"
+    volumes:
+      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data
+    command: minio server /minio_data --console-address ":9001"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      interval: 30s
+      timeout: 20s
+      retries: 3
+
+  # Milvus Vector Database (GPU-enabled)
+  milvus-standalone:
+    container_name: milvus-standalone
+    image: milvusdb/milvus:v2.6.0-rc1-gpu
+    command: ["milvus", "run", "standalone"]
+    security_opt:
+      - seccomp:unconfined
+    environment:
+      MINIO_REGION: us-east-1
+      ETCD_ENDPOINTS: etcd:2379
+      MINIO_ADDRESS: minio:9000
+      MQ_TYPE: woodpecker
+    volumes:
+      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus
+    ports:
+      - "19530:19530"
+      - "9091:9091"
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              capabilities: ["gpu"]
+              device_ids: ["0"]
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
+      interval: 30s
+      start_period: 90s
+      timeout: 20s
+      retries: 3
+    depends_on:
+      - "etcd"
+      - "minio"
+
+networks:
+  milvus:
+    name: milvus

aiagents4pharma/talk2scholars/install.md

@@ -0,0 +1,122 @@
+# Talk2Scholars
+
+## Installation
+
+- [nvidia-cuda-toolkit](https://developer.nvidia.com/cuda-toolkit)
+- [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/1.17.8/install-guide.html) (required for GPU support with Docker; enables containers to access NVIDIA GPUs for accelerated computing). After installing `nvidia-container-toolkit`, please restart Docker to ensure GPU support is enabled.
+
+### Docker (stable-release)
+
+**Prerequisites**
+
+- [Milvus](https://milvus.io) (for a vector database)
+
+---
+
+#### 1. Download files
+
+Choose the appropriate version of the `docker-compose.yml` file based on your system:
+
+**For GPU:**
+
+```sh
+wget https://raw.githubusercontent.com/VirtualPatientEngine/AIAgents4Pharma/main/aiagents4pharma/talk2scholars/docker-compose/gpu/docker-compose.yml \
+     https://raw.githubusercontent.com/VirtualPatientEngine/AIAgents4Pharma/main/aiagents4pharma/talk2scholars/docker-compose/gpu/.env.example
+```
+
+**For CPU:**
+
+```sh
+wget https://raw.githubusercontent.com/VirtualPatientEngine/AIAgents4Pharma/main/aiagents4pharma/talk2scholars/docker-compose/cpu/docker-compose.yml \
+     https://raw.githubusercontent.com/VirtualPatientEngine/AIAgents4Pharma/main/aiagents4pharma/talk2scholars/docker-compose/cpu/.env.example
+```
+
+#### 2. Setup environment variables
+
+```sh
+cp .env.example .env
+```
+
+Edit `.env` with your API keys:
+
+```env
+# .env.example (DO NOT put actual API keys here, read the README.md)
+
+# OPENAI API KEY
+OPENAI_API_KEY=your_openai_api_key_here
+
+# LangSmith API KEY
+LANGCHAIN_TRACING_V2=true
+LANGCHAIN_API_KEY=your_langchain_api_key_heres
+
+# NVIDIA API KEY
+NVIDIA_API_KEY=your_nvidia_api_key_here
+
+# ZOTERO API KEY
+ZOTERO_API_KEY=your_zotero_api_key_here
+ZOTERO_USER_ID=your_zotero_user_id_here
+
+# Set environment variables for data loader
+MILVUS_HOST=milvus-standalone
+MILVUS_PORT=19530
+MILVUS_DB_NAME=pdf_rag_db
+MILVUS_COLLECTION_NAME=pdf_rag_documents
+```
+
+---
+
+#### 3. Start the agent
+
+```sh
+docker compose up -d
+```
+
+---
+
+### Access the Web UI
+
+Once started, open:
+
+```
+http://localhost:8501
+```
+
+> In the background, the BioBridge multimodal embeddings will be inserted into the Milvus database, and the `talk2scholars` service will start. Once the data is fully inserted, the application will be in a healthy state and accessible at the above address.
+>
+> You can monitor the process using:
+>
+> ```sh
+> docker logs -f talk2scholars
+> ```
+
+---
+
+## Get Key
+
+- `NVIDIA_API_KEY` – required (obtain a free key at [https://build.nvidia.com/explore/discover](https://build.nvidia.com/explore/discover))
+- `ZOTERO_API_KEY` – required (generate at [https://www.zotero.org/user/login#applications](https://www.zotero.org/user/login#applications))
+
+  **LangSmith** support is optional. To enable it, create an API key [here](https://docs.smith.langchain.com/administration/how_to_guides/organization_management/create_account_api_key).
+
+_Please note that this will create a new tracing project in your Langsmith
+account with the name `T2X-xxxx`, where `X` can be `KG` (KnowledgeGraphs).
+If you skip the previous step, it will default to the name `default`.
+`xxxx` will be the 4-digit ID created for the session._
+
+---
+
+## Notes for Windows Users
+
+If you are using Windows, it is recommended to install [**Git Bash**](https://git-scm.com/downloads) for a smoother experience when running the bash commands in this guide.
+
+- For applications that use **Docker Compose**, Git Bash is **required**.
+- For applications that use **docker run** manually, Git Bash is **optional**, but recommended for consistency.
+
+You can download Git Bash here: [Git for Windows](https://git-scm.com/downloads).
+
+When using Docker on Windows, make sure you **run Docker with administrative privileges** if you face permission issues.
+
+To resolve permission issues, you can:
+
+- Review the official Docker documentation on [Windows permission requirements](https://docs.docker.com/desktop/setup/install/windows-permission-requirements/).
+- Alternatively, follow the community discussion and solutions on [Docker Community Forums](https://forums.docker.com/t/error-when-trying-to-run-windows-containers-docker-client-must-be-run-with-elevated-privileges/136619).

aiagents4pharma/talk2scholars/state/state_talk2scholars.py

@@ -8,7 +8,7 @@ across agent interactions.
 
 import logging
 from collections.abc import Mapping
-from typing import Annotated, Any, Dict
+from typing import Annotated, Any
 
 from langchain_core.embeddings import Embeddings
 from langchain_core.language_models import BaseChatModel
@@ -19,7 +19,7 @@ logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 
-def merge_dict(existing: Dict[str, Any], new: Dict[str, Any]) -> Dict[str, Any]:
+def merge_dict(existing: dict[str, Any], new: dict[str, Any]) -> dict[str, Any]:
     """
     Merges the existing dictionary with a new dictionary.
 
@@ -36,7 +36,7 @@ def merge_dict(existing: Dict[str, Any], new: Dict[str, Any]) -> Dict[str, Any]:
     return merged
 
 
-def replace_dict(existing: Dict[str, Any], new: Any) -> Any:
+def replace_dict(existing: dict[str, Any], new: Any) -> Any:
     """
     Replaces the existing dictionary with a new dictionary.
 
@@ -87,12 +87,12 @@ class Talk2Scholars(AgentState):
     # Agent state fields
     # Key controlling UI display: always replace to reference latest output
     # Stores the most recently displayed papers metadata
-    last_displayed_papers: Annotated[Dict[str, Any], replace_dict]
+    last_displayed_papers: Annotated[dict[str, Any], replace_dict]
     # Accumulative keys: merge new entries into existing state
-    papers: Annotated[Dict[str, Any], merge_dict]
-    multi_papers: Annotated[Dict[str, Any], merge_dict]
-    article_data: Annotated[Dict[str, Any], merge_dict]
+    papers: Annotated[dict[str, Any], merge_dict]
+    multi_papers: Annotated[dict[str, Any], merge_dict]
+    article_data: Annotated[dict[str, Any], merge_dict]
     # Approval status: always replace to reflect latest operation
-    zotero_write_approval_status: Annotated[Dict[str, Any], replace_dict]
+    zotero_write_approval_status: Annotated[dict[str, Any], replace_dict]
     llm_model: BaseChatModel
     text_embedding_model: Embeddings