bioguider 0.2.3__py3-none-any.whl

bioguider/agents/identification_task.py

@@ -0,0 +1,220 @@
+
+import os
+import json
+import logging
+from enum import Enum
+from typing import Callable
+from pydantic import BaseModel, Field
+from langchain_openai.chat_models.base import BaseChatOpenAI
+from langchain.tools import Tool
+from langgraph.graph import StateGraph, START, END
+
+from bioguider.utils.constants import PrimaryLanguageEnum, ProjectTypeEnum
+from bioguider.utils.file_utils import get_file_type
+from bioguider.agents.agent_tools import (
+    read_file_tool, 
+    read_directory_tool, 
+    summarize_file_tool,
+)
+from bioguider.agents.agent_utils import (
+    read_directory,
+)
+from bioguider.agents.identification_execute_step import IdentificationExecuteStep
+from bioguider.agents.identification_observe_step import IdentificationObserveStep
+from bioguider.agents.identification_plan_step import IdentificationPlanStep
+from bioguider.agents.identification_task_utils import IdentificationWorkflowState
+from bioguider.agents.peo_common_step import PEOCommonStep
+from bioguider.agents.prompt_utils import (
+    IDENTIFICATION_GOAL_PROJECT_TYPE, 
+    IDENTIFICATION_GOAL_PRIMARY_LANGUAGE,
+    IDENTIFICATION_GOAL_META_DATA,
+)
+from bioguider.agents.python_ast_repl_tool import CustomPythonAstREPLTool
+from bioguider.agents.agent_task import AgentTask
+from bioguider.database.summarized_file_db import SummarizedFilesDb
+
+logger = logging.getLogger(__name__)
+
+META_DATA_FINAL_ANSWER_EXAMPLE = '{{"name": "repo name", ...}}'
+PROJECT_TYPE_FINAL_ANSWER_EXAMPLE = '{{"project_type": "project type"}}'
+PRIMARY_LANGUAGE_FINAL_ANSWER_EXAMPLE = '{{"primary_language": "primary language"}}'
+
+class IdentificationPlanResult(BaseModel):
+    """ Identification Plan Result """
+    actions: list[dict] = Field(description="a list of action dictionary, e.g. [{'name': 'read_file', 'input': 'README.md'}, ...]")
+
+IdentificationPlanResultJsonSchema = {
+    "title": "identification_plan_result",
+    "description": "plan result",
+    "type": "object",
+    "properties": {
+        "actions": {
+            "type": "array",
+            "description": """a list of action dictionary, e.g. [{'name': 'read_file', 'input': 'README.md'}, ...]""",
+            "title": "Actions",
+            "items": {"type": "object"}
+        },
+    },
+    "required": ["actions"],
+}
+
+class IdentificationTask(AgentTask):
+    def __init__(
+        self, 
+        llm: BaseChatOpenAI,
+        step_callback: Callable | None=None,
+    ):
+        super().__init__(llm=llm, step_callback=step_callback)
+        self.repo_path: str | None = None
+        self.gitignore_path: str | None = None
+        self.repo_structure: str | None = None
+        self.tools = []
+        self.custom_tools = []
+        self.steps: list[PEOCommonStep] = []
+
+    def _initialize(self):        
+        if not os.path.exists(self.repo_path):
+            raise ValueError(f"Repository path {self.repo_path} does not exist.")
+        files = read_directory(self.repo_path, os.path.join(self.repo_path, ".gitignore"))
+        file_pairs = [(f, get_file_type(os.path.join(self.repo_path, f)).value) for f in files]
+        self.repo_structure = ""
+        for f, f_type in file_pairs:
+            self.repo_structure += f"{f} - {f_type}\n"
+
+        self.tools = [
+            summarize_file_tool(
+                llm=self.llm, 
+                repo_path=self.repo_path, 
+                output_callback=self._print_step,
+                db=self.summary_file_db,
+            ),
+            read_directory_tool(repo_path=self.repo_path, gitignore_path=self.gitignore_path),
+            read_file_tool(repo_path=self.repo_path),
+        ]
+        self.custom_tools = [Tool(
+            name=tool.__class__.__name__,
+            func=tool.run,
+            description=tool.__class__.__doc__,
+        ) for tool in self.tools]
+        self.custom_tools.append(CustomPythonAstREPLTool())
+        self.steps = [
+            IdentificationPlanStep(
+                llm=self.llm,
+                repo_path=self.repo_path,
+                repo_structure=self.repo_structure,
+                gitignore_path=self.gitignore_path,
+                custom_tools=self.custom_tools,
+            ),
+            IdentificationExecuteStep(
+                llm=self.llm,
+                repo_path=self.repo_path,
+                repo_structure=self.repo_structure,
+                gitignore_path=self.gitignore_path,
+                custom_tools=self.custom_tools,
+            ),
+            IdentificationObserveStep(
+                llm=self.llm,
+                repo_path=self.repo_path,
+                repo_structure=self.repo_structure,
+                gitignore_path=self.gitignore_path,
+                custom_tools=self.custom_tools,
+            )
+        ]
+        
+    
+    def _compile(
+        self, 
+        repo_path: str,
+        gitignore_path: str,
+        **kwargs,
+    ):
+        self.repo_path = repo_path
+        self.gitignore_path = gitignore_path
+        self._initialize()
+                
+        def check_observation_step(state: IdentificationWorkflowState):
+            if "final_answer" in state and state["final_answer"] is not None:
+                return END
+            return "plan_step"
+        
+        graph = StateGraph(IdentificationWorkflowState)
+        graph.add_node("plan_step", self.steps[0].execute)
+        graph.add_node("execute_step", self.steps[1].execute)
+        graph.add_node("observe_step", self.steps[2].execute)
+        graph.add_edge(START, "plan_step")
+        graph.add_edge("plan_step", "execute_step")
+        graph.add_edge("execute_step", "observe_step")
+        graph.add_conditional_edges("observe_step", check_observation_step, {"plan_step", END})
+
+        self.graph = graph.compile()
+        
+    def identify_project_type(self):
+        s = self._go_graph({
+            "goal": IDENTIFICATION_GOAL_PROJECT_TYPE,
+            "final_answer_example": PROJECT_TYPE_FINAL_ANSWER_EXAMPLE,
+        })
+        proj_type = s["final_answer"] if "final_answer" in s else "unknown type"
+        return self._parse_project_type(proj_type)
+    
+    def identify_primary_language(self):
+        s = self._go_graph({
+            "goal": IDENTIFICATION_GOAL_PRIMARY_LANGUAGE,
+            "final_answer_example": PRIMARY_LANGUAGE_FINAL_ANSWER_EXAMPLE,
+        })
+        language = s["final_answer"] if "final_answer" in s else "unknown type"
+        return self._parse_primary_language(language)
+    
+    def identify_meta_data(self):
+        s = self._go_graph({
+            "goal": IDENTIFICATION_GOAL_META_DATA,
+            "final_answer_example": META_DATA_FINAL_ANSWER_EXAMPLE,
+        })
+        meta_data = s["final_answer"] if "final_answer" in s else "unknown type"
+        return self._parse_meta_data(meta_data)
+        
+    
+    def _parse_project_type(self, proj_type_obj: str) -> ProjectTypeEnum:
+        try:
+            json_obj = json.loads(proj_type_obj)
+            proj_type = json_obj["project_type"]
+        except Exception as e:
+            logger.error(e)
+            return ProjectTypeEnum.unknown
+        proj_type = proj_type.strip()
+        if proj_type == "application":
+            return ProjectTypeEnum.application
+        elif proj_type == "package":
+            return ProjectTypeEnum.package
+        elif proj_type == "pipeline":
+            return ProjectTypeEnum.pipeline
+        else:
+            return ProjectTypeEnum.unknown
+        
+    def _parse_primary_language(self, language_obj: str) -> PrimaryLanguageEnum:
+        try:
+            json_obj = json.loads(language_obj)
+            language = json_obj["primary_language"]
+        except Exception as e:
+            logger.error(e)
+            return PrimaryLanguageEnum.unknown
+        language = language.strip()
+        if language == "python":
+            return PrimaryLanguageEnum.python
+        elif language == "R":
+            return PrimaryLanguageEnum.R
+        else:
+            return PrimaryLanguageEnum.unknown
+        
+    def _parse_meta_data(self, meta_data_obj: str) -> dict:
+        try:
+            json_obj = json.loads(meta_data_obj)
+            meta_data = json_obj
+            return meta_data
+        except Exception as e:
+            logger.error(e)
+            return {
+                "name": "unknown",
+                "description": "unknown",
+                "license": "unknown",
+                "owner": "unknown",
+            }

bioguider/agents/identification_task_utils.py

@@ -0,0 +1,18 @@
+
+
+from typing import Callable, TypedDict, Optional
+from langchain_openai.chat_models.base import BaseChatOpenAI
+
+class IdentificationWorkflowState(TypedDict):
+    llm: BaseChatOpenAI
+    step_output_callback: Optional[Callable]
+    goal: str
+
+    plan_actions: Optional[str]
+    plan_reasoning: Optional[str]
+    intermediate_steps: Optional[list[str]]
+    final_answer: Optional[str]
+    final_answer_example: Optional[str]
+    step_output: Optional[str]
+    step_analysis: Optional[str]
+    step_thoughts: Optional[str]

bioguider/agents/peo_common_step.py

@@ -0,0 +1,64 @@
+
+
+from typing import Optional
+from langchain_openai.chat_models.base import BaseChatOpenAI
+from pydantic import BaseModel, Field
+from bioguider.agents.common_step import CommonState, CommonStep
+
+class PEOWorkflowState(CommonState):
+    intermediate_steps: Optional[str]
+    step_output: Optional[str]
+    step_analysis: Optional[str]
+    step_thoughts: Optional[str]
+    plan_actions: Optional[list[dict]]
+
+class PEOCommonStep(CommonStep):
+    """
+    This class is a placeholder for common step functionality in the PEO agent.
+    It is currently empty and can be extended in the future.
+    """
+    def __init__(self, llm: BaseChatOpenAI):
+        super().__init__()
+        self.llm = llm
+
+    def _build_intermediate_steps(self, state: PEOWorkflowState):
+        """
+        Build intermediate steps for the PEO workflow.
+        """
+        intermediate_steps = ""
+        # previous steps
+        if "intermediate_steps" in state:
+            for i in range(len(state['intermediate_steps'])):
+                step = state['intermediate_steps'][i].replace("{", "(").replace("}", ")")
+                intermediate_steps += step + "\n"
+        # current step
+        if "step_output" in state and state["step_output"] is not None:
+            step_content = state["step_output"]
+            step_content = step_content.replace("{", "(").replace("}", ")")
+            intermediate_steps += step_content
+        return intermediate_steps
+    
+    def _build_intermediate_analysis_and_thoughts(self, state: PEOWorkflowState):
+        intermediate_analysis = "N/A" if "step_analysis" not in state or \
+            state["step_analysis"] is None \
+            else state["step_analysis"]
+        intermediate_analysis = intermediate_analysis.replace("{", "(").replace("}", ")")
+        intermediate_thoughts = "N/A" if "step_thoughts" not in state or \
+            state["step_thoughts"] is None \
+            else state["step_thoughts"]
+        intermediate_thoughts = intermediate_thoughts.replace("{", "(").replace("}", ")")
+        return intermediate_analysis, intermediate_thoughts
+
+    @staticmethod
+    def _reset_step_state(state):
+        # move step_output to intermediate steps
+        if "intermediate_steps" not in state or state["intermediate_steps"] is None:
+            state["intermediate_steps"] = []
+        intermediate_steps = state["intermediate_steps"]
+        if "step_output" in state and state["step_output"] is not None:
+            intermediate_steps.append(state["step_output"])
+        state["intermediate_steps"] = intermediate_steps
+
+        state["step_analysis"] = None
+        state["step_thoughts"] = None
+        state["step_output"] = None

bioguider/agents/prompt_utils.py

@@ -0,0 +1,190 @@
+from enum import Enum
+from langchain_core.prompts import ChatPromptTemplate
+
+USER_INSTRUCTION = """Do not give the final result immediately. First, explain your reasoning process step by step, then provide the answer."""
+
+EVALUATION_ITEMS = [
+    ("1. Clarity & Readability", 20),
+    ("2. Completeness", 20), 
+    ("3. Organization & Navigation", 10),
+    ("4. Examples & Tutorials", 10), 
+    ("5. Maintainability & Updates", 15), 
+    ("6. Accessibility & Formatting", 15), 
+]
+
+EVALUATION_SYSTEM_PROMPT = ChatPromptTemplate.from_template("""Please act as both a **biomedical researcher** and an **experienced software developer** to evaluate the documentation quality of a GitHub repository using the evaluation criteria below.
+
+### **Evaluation Criteria (Total: 100 points)**
+
+1. **Clarity & Readability (20 points)** - Is the documentation written in a clear, concise, and easy-to-understand manner?
+2. **Completeness (20 points)** - Does the documentation cover all essential information needed for understanding, usage, and further development?
+3. **Organization & Navigation (10 points)** - Is the structure logical and easy to navigate? Are key sections easy to find?
+4. **Examples & Tutorials (10 points)** - Are there sufficient examples or tutorials to help users get started and understand core functionality?
+5. **Maintainability & Updates (15 points)** - Does the documentation reflect ongoing maintenance and version history (e.g., changelogs, version tags)?
+6. **Accessibility & Formatting (15 points)** - Is the documentation well-formatted and easy to read (e.g., Markdown formatting, appropriate use of code blocks, headers, etc.)?
+### **Repository Structure Overview**  
+_(f = file, d = directory)_
+```
+{repository_structure}
+```""")
+
+EVALUATION_ITEM_PROMPT = ChatPromptTemplate.from_template("""Here are the content of files or directories in the repository that you need to take into account:
+{files_or_directories}
+
+### **Instructions**
+
+Let's begin by evaluating **Criterion {evaluation_item}*.
+
+- If the information provided is **sufficient**, please proceed with your evaluation using the following format:
+```
+{evaluation_item} ({score_point} points)  
+    a. Score: [score out of {score_point}]  
+    b. Reason: [brief explanation justifying the score]  
+```
+- If the information provided is **insufficient**, do **not** attempt to evaluate. Instead, list the specific files or directories for which you need more detail, using the format below:
+```
+[files/directories needed for evaluation]
+```""")
+
+
+## goal: identify project type
+IDENTIFICATION_GOAL_PROJECT_TYPE = """Identify the following key attribute of the repository:
+  **project type**: The primary functional type of the project.  
+    Options and their definitions:  
+    - **package**: A reusable Python or R library intended to be imported by other software.  
+    - **application**: A standalone Python or R program that can be directly executed by users.  
+    - **pipeline**: A biomedical data processing workflow that integrates multiple tools or steps.
+    - **unknown type**: Use this only if the type cannot be determined reliably from available information.
+  **Notes**:
+    1. The project can be identified as one of the above project type.
+    2. The project may server as multiple project types, like package & pipeline, standalone application & package,
+      However, you need to investigate closely to find out the primary project type.
+    3. Do **not** rely heavily on directories like 'benchmark/' or 'tests/' when determining the project type, as they are often auxiliary."""
+
+## goal: identify primary language
+IDENTIFICATION_GOAL_PRIMARY_LANGUAGE = """Identify the following key attribute of the repository:
+  **primary language**: The primary language of the project.  
+    Options and their definitions:  
+    - **python**: Python language
+    - **R**: R language
+    - **unknown type**: Use this only if the type cannot be determined reliably from available information.
+  **Notes**:
+    The project can be identified as one of the above primary language."""
+
+## goal: identify meta data: repo name, owner, description, license
+IDENTIFICATION_GOAL_META_DATA = """Identify the following meta data of the repository:
+  **name**: The repository name.
+  **owner**: The repository user or orgnization.
+  **description**: The description of the repository.
+  **license**: The license of the repository, like 'MIT', 'Apache 2.0' or 'unknown'.
+
+**Notes**: If the above meta data can't be identified, please return 'unknown' or 'N/A'.
+"""
+
+COT_USER_INSTRUCTION = "Do not give the answer immediately. First, explain your reasoning process step by step, then provide the answer."
+
+class CollectionGoalItemEnum(Enum):
+    UserGuide = "User Guide"
+    Tutorial = "Tutorials & Vignettes"
+    DockerGeneration = "Docker Generation"
+    Installation = "Installation"
+    License = "License"
+    Contributing = "Contributing"
+
+
+
+COLLECTION_GOAL = """Your goal is to collect the names of all files that are relevant to **{goal_item}**.  
+**Note:**
+ - You only need to collect the **file names**, not their contents."""
+
+COLLECTION_PROMPTS = {
+    "UserGuide": {
+        "goal_item": "User Guide",
+        "related_file_description": """A document qualifies as a **User Guide** if it includes **at least one** of the following elements.
+If **any one** of these is present, the document should be classified as a User Guide — full coverage is **not required**:
+ - Overview: A brief introduction to the software, its purpose, and its intended audience.
+ - Installation Instructions: Step-by-step setup procedures.
+ - Input/Output Specifications: Detailed information on the data the software accepts and produces.
+ - Configuration Options: Descriptions of settings and parameters that can be adjusted.
+ - Function/Interface Listings: Comprehensive lists of available functions or interfaces, including their descriptions, parameters, and return values.
+ - Mathematical Equations/Numerical Methods: Embedded documentation explaining the underlying mathematical concepts or algorithms.
+ - Developer Guidance: Instructions on how to extend the software or contribute to its development.
+ **Do not** classify the document as a User Guide if it primarily serves as a Tutorial or Example. Such documents typically include:
+ - Sample Datasets: Example data used to illustrate functionality.
+ - Narrative Explanations: Story-like descriptions guiding the user through examples.
+ - Code Walkthroughs: Detailed explanations of code snippets in a tutorial format.
+**Do not** classify the document as a User Guide if it is souce code or a script (*.py, *.R) that is not intended for end-user interaction.
+ - You can include directory names if all files in the directory are relevant to the goal item.""",
+    },
+    "Tutorial": {
+        "goal_item": "Tutorials & Vignettes",
+        "related_file_description": """
+**Tutorials and Vignettes** are instructional documents or interactive notebooks that provide step-by-step guidance on using a software package or library. They typically include:
+ - Code Examples: Practical code snippets demonstrating how to use the software's features and functions.
+ - Explanatory Text: Clear explanations accompanying the code examples to help users understand the concepts and techniques being presented.​
+ - Visualizations: Graphical representations of data or results to enhance understanding.
+ - Interactive Elements: Features that allow users to experiment with the code in real-time, such as Jupyter notebooks or R Markdown files.​
+ - Use Cases: Real-world applications or scenarios where the software can be applied effectively.
+ - You can include directory names if all files in the directory are relevant to the goal item.
+""",
+    },
+    "DockerGeneration": {
+        "goal_item": "Generating a Dockerfile for reproducibility testing",
+        
+        "related_file_description": """A document qualifies **Dockerfile Generation** related if it includes **at least one** of the following elements.
+If **any one** of these is present, the document should be classified as a Dockerfile — full coverage is **not required**:
+ - Existing Docker Configuration
+   * Files like `Dockerfile`, `docker-compose.yml`, or any Docker-related build scripts.
+ - Installation & Environment Setup
+   * Files used to define or install dependencies.
+     * Examples: `README.md` `requirements.txt`, `environment.yml`, `setup.py`, `install.R`, `DESCRIPTION`, `pyproject.toml`, etc.
+ - Build/Runtime Scripts
+   * Shell or batch scripts used for setup, building, or launching the application.
+     * Examples: `install.sh`, `build.sh`, `run.sh`, etc.
+ - Minimal Code Examples or Get-Started Files
+   * Files that demonstrate a minimal working example of the software (e.g., for testing or reproducing results).
+     * Examples: `example.py`, `main.py`, `demo.R`, `notebooks/get_started.ipynb`, etc.
+     * These should be runnable with minimal configuration.""",
+        
+        "important_instructions": """- Only include minimal code examples that demonstrate basic functionality.
+If multiple example files are found, select only the simplest and most lightweight one that is sufficient to verify the repository works.
+ - Give priority to analyzing files whose names include **"install"** or **"Dockerfile"**, as these are most likely to be useful for generating our Dockerfile
+ - The total number of collected files should **not exceed 5**.
+ - Make sure to include **only one code example**, selecting the most minimal and representative one.
+"""
+    },
+    "Installation": {
+        "goal_item": "Installation Instructions",
+        "related_file_description": """A document qualifies as **Installation Instructions** if it includes **at least one** of the following elements.
+If **any one** of these is present, the document should be classified as Installation Instructions — full coverage is **not required**:
+ - Step-by-step setup procedures for the software.
+ - Prerequisites or dependencies that need to be installed before using the software.
+ - Configuration steps required to get the software running.
+ - Troubleshooting tips related to installation issues.
+ - You can include directory names if all files in the directory are relevant to the goal item.""",
+        "important_instructions": """- Give priority to analyzing README file that contain installation instructions and the files whose names include **"install"** or **"setup"**.
+- If multiple files are found, select the most comprehensive one that covers the installation process.
+- The total number of collected files should **not exceed 3**.
+- Make sure to include **only one installation instruction file**, selecting the most comprehensive and representative one.
+"""
+    },
+    "License": {
+        "goal_item": "License Information",
+        "related_file_description": """A document qualifies as **License Information** if it includes **at least one** of the following elements.
+If **any one** of these is present, the document should be classified as License Information — full coverage is **not required**:
+ - A file named `LICENSE`, `LICENSE.txt`, or similar that explicitly states the software's license.
+ - A section in the README or documentation that describes the licensing terms.
+ - Any file that contains legal information regarding the use, distribution, or modification of the software.
+ - You can include directory names if all files in the directory are relevant to the goal item.""",
+    },
+    "Contributing": {
+        "goal_item": "Contributing Guidelines",
+        "related_file_description": """A document qualifies as **Contributing Guidelines** if it includes **at least one** of the following elements.
+If **any one** of these is present, the document should be classified as Contributing Guidelines — full coverage is **not required**:
+ - A file named `CONTRIBUTING.md`, `CONTRIBUTING.rst`, or similar that provides guidelines for contributing to the project.
+ - A section in the README or documentation that outlines how to contribute, report issues, or submit pull requests.
+ - Any file that contains instructions for developers on how to contribute to the project, including coding standards, testing procedures, and submission processes.
+ - You can include directory names if all files in the directory are relevant to the goal item.""",
+    },
+}
+

bioguider/agents/python_ast_repl_tool.py

@@ -0,0 +1,69 @@
+
+from pydantic import PrivateAttr
+import re
+import io
+import contextlib
+import logging
+from langchain_experimental.tools.python.tool import PythonAstREPLTool
+
+class CustomPythonAstREPLTool(PythonAstREPLTool):
+    """
+    Custom Python REPL tool that executes Python code and captures output.
+    This tool is designed to be used in a LangChain agent for executing Python code
+    and capturing the output, including any print statements.
+    """
+    __name__ = "Custom_Python_AST_REPL"
+    _exec_globals: dict = PrivateAttr()
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._exec_globals = {}
+        self._exec_globals.update(__builtins__)
+
+    def _set_globals(self, table_dict=None):
+        self._exec_globals = {}
+        self._exec_globals.update(__builtins__)
+
+        if table_dict is not None:
+            self._exec_globals.update(table_dict)
+
+    def _run(self, query: str, run_manager=None):  
+        print("================================== code here ==============================")
+        print(query)
+        print("===========================================================================")
+        code_match = re.search(r"```(.*?)```", query, re.DOTALL)
+        if code_match:
+            # Extract code within backticks
+            code = code_match.group(1)
+        else:
+            code = query
+        code = code.strip()
+        if code.startswith("python"):
+            code = code[len("python"):].lstrip()
+        
+        if code.endswith("Observation"):
+            code = code[:-len("Observation")].rstrip()
+        
+        code_lines = code.strip().split('\n')
+        code = '\n'.join(code_lines[:-1])   # avoid printing the last line twice
+        last_line = code_lines[-1]
+        
+        output_capture = io.StringIO()
+        with contextlib.redirect_stdout(output_capture), contextlib.redirect_stderr(output_capture):
+            logging.getLogger().handlers[0].stream = output_capture
+            try:
+                exec(code, self._exec_globals)
+                try:
+                    result = eval(last_line, self._exec_globals)
+                    if result is not None:
+                        print(result, file=output_capture)
+                except:
+                    pass
+            except Exception as e:
+                return str(e)
+        
+        # Retrieve the output and return it
+        output = output_capture.getvalue()
+        return output if output else "Execution completed without output."
+
+
+