aurelian 0.3.2__py3-none-any.whl

aurelian/agents/goann/goann_agent.py

@@ -0,0 +1,90 @@
+"""
+Agent for reviewing GO standard annotations.
+"""
+from pydantic_ai import Agent, Tool, RunContext
+
+from aurelian.agents.goann.goann_config import GOAnnotationDependencies
+from aurelian.utils.documentation_manager import DocumentationManager
+from aurelian.agents.literature.literature_tools import (
+    lookup_pmid as literature_lookup_pmid,
+    search_literature_web,
+    retrieve_literature_page
+)
+from . import DOCUMENTS_DIR
+from .goann_tools import find_gene_annotations, fetch_document
+from ..uniprot import lookup_uniprot_entry
+
+SYSTEM = """
+You are a GO annotation reviewer specializing in reviewing GO standard annotations.
+
+Your primary responsibilities include:
+1. Evaluating GO annotations for accuracy based on evidence codes and supporting literature
+2. Identifying potential over-annotations based on phenotypes rather than direct involvement
+3. Reviewing annotations according to GO annotation guidelines
+4. Suggesting corrections or improvements to annotations
+
+You use the GO guidelines for proper annotation, you can use the `fetch_document` tool to retrieve the content of any of these documents.
+
+A gene should only be annotated to a process if its activity is an identifiable step in that process.
+
+When asked to evaluate or review existing annotations, be sure to:
+
+- check the papers used in annotation using `literature_lookup_pmid` to ensure the interpretation of the evidence is correct
+- look at textual information on the uniprot ID usingg `lookup_uniprot_entry` to ensure the annotation is consistent
+
+
+Your goal is to help maintain the quality and accuracy of the GO annotation database.
+"""
+
+# Define core tools for the agent
+core_tools = [
+    Tool(find_gene_annotations),
+    Tool(lookup_uniprot_entry),
+     Tool(literature_lookup_pmid,
+         description="""Lookup the text of a PubMed article by its PMID.
+
+                        Note that assertions in GO-CAMs may reference PMIDs, so this tool
+                        is useful for validating assertions. A common task is to align
+                        the text of a PMID with the text of an assertion, or extracting text
+                        snippets from the publication that support the assertion."""),
+    Tool(search_literature_web),
+    Tool(retrieve_literature_page),
+    Tool(fetch_document),
+]
+
+# Create the GO annotation review agent
+goann_agent = Agent(
+    model="anthropic:claude-3-7-sonnet-latest",
+    deps_type=GOAnnotationDependencies,
+    system_prompt=SYSTEM,
+    tools=core_tools,
+)
+
+
+def get_documents_for_prompt() -> str:
+    """
+    Get the documents for the system prompt.
+
+    Returns:
+        A string containing the list of available GO annotation best practice documents
+    """
+    dm = DocumentationManager(documents_dir=DOCUMENTS_DIR)
+    return dm.get_documents_for_prompt(extra_text=(
+        "\n\nYou can use the `fetch_document` tool to retrieve the content of any of these documents."
+        "\nWhen asked any question about GO annotation curation practice, be sure to ALWAYS"
+        " check the relevant document for the most up-to-date information.\n"
+    ))
+
+
+@goann_agent.system_prompt
+def add_documents_to_prompt(ctx: RunContext[GOAnnotationDependencies]) -> str:
+    """
+    Add available GO-CAM documents to the system prompt.
+    
+    Args:
+        ctx: The run context
+        
+    Returns:
+        A string containing the list of available GO-CAM documents
+    """
+    return get_documents_for_prompt()

aurelian/agents/goann/goann_config.py

@@ -0,0 +1,90 @@
+"""
+Configuration classes for the GO Annotation Review agent.
+"""
+from dataclasses import dataclass, field
+from typing import Dict, Any
+
+from bioservices import UniProt
+from oaklib import get_adapter
+from oaklib.implementations import AmiGOImplementation
+
+from aurelian.dependencies.workdir import HasWorkdir
+from aurelian.agents.uniprot.uniprot_tools import normalize_uniprot_id
+
+# Initialize UniProt service
+uniprot_service = UniProt(verbose=False)
+
+
+@dataclass
+class GOAnnotationDependencies(HasWorkdir):
+    """
+    Configuration for the GO Annotation Review agent.
+    
+    Args:
+        taxon: NCBI Taxonomy ID, defaults to human (9606)
+    """
+    taxon: str = field(default="9606")
+
+    # Options for the bioservices UniProt client
+    uniprot_client_options: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Initialize the config with default values."""
+        # HasWorkdir doesn't have a __post_init__ method, so we don't call super()
+        if self.uniprot_client_options is None or len(self.uniprot_client_options) == 0:
+            self.uniprot_client_options = {"verbose": False}
+
+    def get_uniprot_client(self) -> UniProt:
+        """Get a configured UniProt client."""
+        return UniProt(**self.uniprot_client_options)
+    
+    def get_amigo_adapter(self) -> AmiGOImplementation:
+        """
+        Get the AmiGO adapter for the specified taxon.
+        
+        Returns:
+            AmiGOImplementation: The OAK AmiGO adapter
+        """
+        return get_adapter(f"amigo:NCBITaxon:{self.taxon}")
+        
+    def get_gene_id(self, gene_term: str) -> str:
+        """
+        Normalize a gene identifier.
+        
+        Args:
+            gene_term: The gene identifier
+            
+        Returns:
+            str: The normalized gene identifier
+        """
+        return gene_term
+
+
+def normalize_pmid(pmid: str) -> str:
+    """
+    Normalize a PubMed ID to the format PMID:nnnnnnn.
+    
+    Args:
+        pmid: The PubMed ID
+        
+    Returns:
+        str: The normalized PubMed ID
+    """
+    if ":" in pmid:
+        pmid = pmid.split(":", 1)[1]
+    if not pmid.startswith("PMID:"):
+        pmid = f"PMID:{pmid}"
+    return pmid
+
+
+def get_config(taxon: str = "9606") -> GOAnnotationDependencies:
+    """
+    Get the GO Annotation Review configuration.
+    
+    Args:
+        taxon: NCBI Taxonomy ID, defaults to human (9606)
+        
+    Returns:
+        GOAnnotationDependencies: The GO Annotation dependencies
+    """
+    return GOAnnotationDependencies(taxon=taxon)

aurelian/agents/goann/goann_evals.py

@@ -0,0 +1,104 @@
+"""
+Evaluation module for the GO Annotation agent.
+
+This module implements evaluations for the GO Annotation agent using the pydantic-ai-evals framework.
+"""
+import asyncio
+import sys
+from typing import Optional, Any, Dict, Callable, Awaitable
+
+from aurelian.evaluators.model import MetadataDict, metadata
+from aurelian.evaluators.substring_evaluator import SubstringEvaluator
+from pydantic_evals import Case, Dataset
+from pydantic_evals.evaluators import LLMJudge
+
+from aurelian.agents.goann.goann_agent import goann_agent
+from aurelian.agents.goann.goann_config import GOAnnotationDependencies, get_config
+
+class GOAnnotationMetadata(Dict[str, Any]):
+    """Simple metadata dictionary for GO Annotation evaluations."""
+    pass
+
+# Define individual evaluation cases
+case1 = Case(
+    name="notch1_review",
+    inputs="Review GO annotations for human NOTCH1 (P46531)",
+    expected_output="transcription",  # Should mention transcription-related functions
+    metadata=metadata("medium", "protein_annotation_review")
+)
+
+case2 = Case(
+    name="tf_coregulator_difference",
+    inputs="Explain the difference between DNA-binding transcription factors and coregulators",
+    expected_output="bind DNA",  # Should mention DNA binding as key distinction
+    metadata=metadata("medium", "concept_explanation"),
+    evaluators=[
+        LLMJudge(
+            rubric="""
+            Answer should clearly explain:
+            1. DNA-binding TFs directly interact with DNA via specific domains
+            2. Coregulators modulate transcription without directly binding DNA
+            3. The different functional roles of each in gene expression
+            """,
+            include_input=True
+        )
+    ]
+)
+
+case3 = Case(
+    name="tf_annotation_guidelines",
+    inputs="What are the guidelines for annotating transcription factors?",
+    expected_output="evidence",  # Should mention evidence requirements
+    metadata=metadata("hard", "annotation_guideline_retrieval")
+)
+
+case4 = Case(
+    name="tf_annotation_check",
+    inputs="Check if P46531 is correctly annotated as a DNA-binding transcription factor",
+    expected_output="NOTCH",  # Should identify it as NOTCH1
+    metadata=metadata("hard", "annotation_accuracy_check")
+)
+
+case5 = Case(
+    name="pmid_annotation_quality",
+    inputs="Find GO annotations from PMID:12345678 and assess their quality",
+    expected_output="evidence code",  # Should mention evidence codes in assessment
+    metadata=metadata("medium", "literature_annotation_assessment")
+)
+
+case6 = Case(
+    name="evidence_code_reliability",
+    inputs="What evidence codes are most reliable for transcription factor annotations?",
+    expected_output="IDA",  # Should mention IDA (Inferred from Direct Assay)
+    metadata=metadata("easy", "evidence_code_assessment")
+)
+
+def create_eval_dataset() -> Dataset[str, str, MetadataDict]:
+    """
+    Create a dataset for evaluating the GO Annotation agent.
+    
+    Returns:
+        Dataset of GO Annotation evaluation cases with appropriate evaluators
+    """
+    # Collect all cases
+    cases = [case1, case2, case3, case4, case5, case6]
+    
+    # Dataset-level evaluators
+    evaluators = [
+        SubstringEvaluator(),
+        LLMJudge(
+            rubric="""
+            Evaluate the answer based on:
+            1. Accuracy in explaining GO annotation concepts and guidelines
+            2. Proper use of GO terminology and evidence codes
+            3. Correct assessment of annotation quality where relevant
+            4. Alignment with current GO Consortium best practices
+            """,
+            model="anthropic:claude-3-7-sonnet-latest"
+        )
+    ]
+    
+    return Dataset(
+        cases=cases,
+        evaluators=evaluators
+    )

aurelian/agents/goann/goann_gradio.py

@@ -0,0 +1,62 @@
+"""
+Gradio interface for the GO Annotation Review agent.
+"""
+from typing import List, Optional
+
+import gradio as gr
+
+from aurelian.agents.goann.goann_agent import goann_agent
+from aurelian.agents.goann.goann_config import GOAnnotationDependencies, get_config
+from aurelian.utils.async_utils import run_sync
+
+
+def chat(deps: Optional[GOAnnotationDependencies] = None, **kwargs):
+    """
+    Initialize a chat interface for the GO Annotation Review agent.
+    
+    Args:
+        deps: Optional dependencies configuration
+        **kwargs: Additional arguments to pass to the agent
+        
+    Returns:
+        A Gradio chat interface
+    """
+    if deps is None:
+        deps = get_config()
+
+    def get_info(query: str, history: List[str]) -> str:
+        print(f"QUERY: {query}")
+        print(f"HISTORY: {history}")
+        if history:
+            query += "## History"
+            for h in history:
+                query += f"\n{h}"
+        result = run_sync(lambda: goann_agent.run_sync(query, deps=deps, **kwargs))
+        return result.data
+
+    return gr.ChatInterface(
+        fn=get_info,
+        type="messages",
+        title="GO Annotation Review Assistant",
+        description="I can help review GO annotations, check annotation quality, and ensure compliance with GO guidelines.",
+        examples=[
+            ["Review GO annotations for human NOTCH1 (P46531)"],
+            ["Explain the difference between DNA-binding transcription factors and coregulators"],
+            ["What are the guidelines for annotating transcription factors?"],
+            ["Check if P46531 is correctly annotated as a DNA-binding transcription factor"],
+            ["Find GO annotations from PMID:12345678 and assess their quality"],
+            ["What evidence codes are most reliable for transcription factor annotations?"],
+        ],
+    )
+
+
+def launch_demo():
+    """
+    Launch the Gradio demo for the GO Annotation Review agent.
+    """
+    demo = chat()
+    demo.launch()
+
+
+if __name__ == "__main__":
+    launch_demo()

aurelian/agents/goann/goann_tools.py

@@ -0,0 +1,65 @@
+"""
+Tools for the GO Annotation Review agent.
+"""
+from typing import List, Dict, Optional
+
+from pydantic_ai import RunContext, ModelRetry
+
+from aurelian.agents.goann.goann_config import GOAnnotationDependencies
+from aurelian.utils.data_utils import obj_to_dict
+
+from . import DOCUMENTS_DIR
+from ...utils.documentation_manager import DocumentationManager
+
+document_manager = DocumentationManager(documents_dir=DOCUMENTS_DIR)
+
+async def find_gene_annotations(ctx: RunContext[GOAnnotationDependencies], gene_id: str) -> List[Dict]:
+    """
+    Find gene annotations for a given gene or gene product.
+    
+    Args:
+        ctx: The run context
+        gene_id: Gene or gene product IDs. This should be a prefixed ID, consistent with AmiGO
+        
+    Returns:
+        List[Dict]: List of gene annotations including their evidence codes
+    """
+    print(f"FIND GENE ANNOTATIONS: {gene_id}")
+    try:
+        adapter = ctx.deps.get_amigo_adapter()
+        normalized_gene_id = ctx.deps.get_gene_id(gene_id)
+        assocs = [obj_to_dict(a) for a in adapter.associations([normalized_gene_id])]
+        
+        if not assocs:
+            raise ModelRetry(f"No gene annotations found for {gene_id}. Try a different gene identifier.")
+            
+        return assocs
+    except Exception as e:
+        if "ModelRetry" in str(type(e)):
+            raise e
+        raise ModelRetry(f"Error finding gene annotations for {gene_id}: {str(e)}")
+
+
+async def fetch_document(
+        ctx: RunContext[GOAnnotationDependencies],
+        name: str,
+        format: str = "md"
+) -> str:
+    """
+    Lookup thedocument by name.
+
+    Args:
+        ctx: The run context
+        name: The document name (e.g. "How_to_annotate_TFs")
+        format: The format of the document (defaults to "md")
+
+    Returns:
+        The content of the document
+    """
+    print(f"FETCH DOCUMENT: {name}")
+    try:
+        return document_manager.fetch_document(name)
+    except KeyError:
+        raise ModelRetry(f"Document with name '{name}' not found. Please check the name and try again.")
+
+

aurelian/agents/gocam/__init__.py

@@ -0,0 +1,43 @@
+"""
+GOCAM agent module for working with Gene Ontology Causal Activity Models.
+"""
+from pathlib import Path
+
+THIS_DIR = Path(__file__).parent
+DOCUMENTS_DIR = THIS_DIR / "documents"
+
+# isort: skip_file
+from .gocam_agent import gocam_agent  # noqa: E402
+from .gocam_config import GOCAMDependencies, get_config  # noqa: E402
+from .gocam_gradio import chat  # noqa: E402
+from .gocam_tools import (  # noqa: E402
+    search_gocams,
+    lookup_gocam,
+    lookup_uniprot_entry,
+    all_documents,
+    fetch_document,
+    validate_gocam_model,
+)
+
+__all__ = [
+    # Constants
+    "THIS_DIR",
+    "DOCUMENTS_DIR",
+    
+    # Agent
+    "gocam_agent",
+    # Config
+    "GOCAMDependencies",
+    "get_config",
+    
+    # Tools
+    "search_gocams",
+    "lookup_gocam",
+    "lookup_uniprot_entry",
+    "all_documents",
+    "fetch_document",
+    "validate_gocam_model",
+    
+    # Gradio
+    "chat",
+]

aurelian/agents/gocam/documents/DNA-binding_transcription_factor_activity_annotation_guidelines.md

@@ -0,0 +1,100 @@
+Guidelines for DNA-binding transcription factor annotation in eukaryotes
+
+###
+
+# Pathway Editor
+
+### DNA-binding transcription factor activity - Single transcription target
+
+The activity unit for a eukaryotic DNA-binding transcription factor is:
+
+* **MF:** 'enables'a child of DNA binding transcription factor activity, RNA polymerase, II-specific ([GO:0000981](https://www.ebi.ac.uk/QuickGO/term/GO%3A0000981)):
+  + DNA-binding transcription activator activity, RNA polymerase, II-specific ([GO:0001228](https://www.ebi.ac.uk/QuickGO/term/GO%3A0001228))
+  + DNA-binding transcription repressor activity, RNA polymerase II-specific ([GO:0001227](https://www.ebi.ac.uk/QuickGO/term/GO%3A0001227))
+* **Context:**
+  + The relation between the DNA-binding transcription factor activity and the gene it regulates is 'has input'
+* **BP: '**part of' **regulation of the BP** in which the target participates (if known)**.**
+  + **CC:** 'occurs in' nucleus ([GO:0005634](https://www.ebi.ac.uk/QuickGO/term/GO%3A0005634))
+  + The causal relation between the transcription factor activity and the activity of its target gene is: ‘indirectly positively regulates’ or 'indirectly negatively regulates’, since there are many steps between the activation of transcription and the activity of the target protein, including the production of a messenger RNA that is translated into a protein, i. e the regulator does not directly interact with the protein it regulates.
+
+**Example single target:** [**FOXO3 regulation of G6PC1**](http://noctua.geneontology.org/workbench/noctua-visual-pathway-editor/?model_id=gomodel%3A645d887900001840)![](data:image/png;base64...)
+
+###
+
+###
+
+###
+
+### DNA-binding transcription factor activity - Multiple transcription targets
+
+In cases where transcription factor regulates multiple target genes, a separate activity unit is captured for each transcriptional target.
+
+**Example multiple targets:** [**FOXO3 regulation of G6PC1 and Pck1**](http://noctua.geneontology.org/workbench/noctua-visual-pathway-editor/?model_id=gomodel%3A645d887900001840)
+
+![](data:image/png;base64...)
+
+###
+
+### Nuclear receptors and ligand-activated transcription factors
+
+* Nuclear receptors are positively regulated by a ligand, usually a small molecule (ChEBI).
+* The activity unit for a nuclear receptor is:
+  + **MF**: nuclear receptor activity ([GO:0004879](https://www.ebi.ac.uk/QuickGO/GTerm?id=GO:0004879)) (a child of transcription factor activity)
+  + **Context:** the causal relation between the small molecule and the nuclear receptor is ‘is small activator of’.
+  + Other data are captured the same way as for [other transcription factors](#_fbcjfrmmj04i).
+
+**Example:** [**Model for nuclear receptor annotation**](http://noctua.geneontology.org/workbench/noctua-visual-pathway-editor/?model_id=gomodel%3A6482692800001263)
+
+![](data:image/png;base64...)
+
+##
+
+## Form Editor
+
+### DNA-binding transcription factor activity
+
+* **MF:** 'enables' a child of DNA binding transcription factor activity, RNA polymerase, II-specific ([GO:0000981](https://www.ebi.ac.uk/QuickGO/term/GO%3A0000981)):
+  + DNA-binding transcription activator activity, RNA polymerase, II-specific ([GO:0001228](https://www.ebi.ac.uk/QuickGO/term/GO%3A0001228))
+  + DNA-binding transcription repressor activity, RNA polymerase II-specific ([GO:0001227](https://www.ebi.ac.uk/QuickGO/term/GO%3A0001227))
+* **Context:**
+  + The relation between the DNA-binding transcription factor activity and the gene it regulates is 'has input'. A single input is captured per activity unit.
+* **regulation of transcription may be 'part of' a larger BP**, specifically, regulation of the BPin which the target participates (if known)**.**
+  + **CC:** 'occurs in' nucleus ([GO:0005634](https://www.ebi.ac.uk/QuickGO/term/GO%3A0005634))
+
+**Example DNA binding transcription factor activity:** [**FOXO3 regulation of G6PC1**](http://noctua.geneontology.org/workbench/noctua-form/?model_id=gomodel%3A645d887900001840)
+
+![](data:image/png;base64...)
+
+###
+
+### Nuclear receptors and ligand-activated transcription factors
+
+**Example:** [**Model for nuclear receptor annotation guidelines**](http://noctua.geneontology.org/workbench/noctua-form/?model_id=gomodel%3A6482692800001263)
+
+The annotations are the same as for DNA binding transcription factor activity, except using the more precise MF nuclear receptor activity ([GO:0004879](https://www.ebi.ac.uk/QuickGO/GTerm?id=GO:0004879)).
+
+![](data:image/png;base64...)
+
+#
+
+# Differences between GO-CAM and standard annotation of a DNA-binding transcription factor activity
+
+In standard annotation (captured with the Noctua Form or Protein2GO), relations between molecular functions are not captured, so there is no relation between the DNA binding transcription factor and the MF of its transcriptional target.
+
+For nuclear receptors, the relation between the small molecule activator and the transcription factor is not captured.
+
+# Open questions
+
+* FORM: For nuclear receptors, the relation between the small molecule activator and the transcription factor is not captured: can we add the relation in the Form?
+
+# Future features
+
+Chromosomal coordinates of the promoter/enhancer/loop anchor binding site of a DNA-binding transcription factor will be captured as 'has input'. For for the human genome, the syntax is: hg38\_chr6:12334566-12335555\* if we want to capture the chromosomal region
+
+\* https://eu.idtdna.com/pages/support/faqs/how-are-genomic-coordinates-defined
+
+# Review information
+
+Review date: 2023-07-20
+
+Reviewed by: Cristina Casals, Pascale Gaudet, Patrick Masson