aurelian 0.3.2__tar.gz

aurelian-0.3.2/LICENSE

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2025 Monarch Initiative
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

aurelian-0.3.2/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.3
+Name: aurelian
+Version: 0.3.2
+Summary: aurelian
+License: MIT
+Author: Author 1
+Author-email: author@org.org
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: bioservices
+Provides-Extra: chem
+Provides-Extra: gocam
+Provides-Extra: gradio
+Provides-Extra: linkml
+Provides-Extra: pdfminer
+Provides-Extra: rdkit
+Requires-Dist: bioservices (>=1.12.0) ; extra == "bioservices"
+Requires-Dist: bs4 (>=0.0.2)
+Requires-Dist: cairosvg (>=2.7.1,<3.0.0)
+Requires-Dist: click
+Requires-Dist: duckduckgo-search (>=7.3.2)
+Requires-Dist: gocam ; extra == "gocam"
+Requires-Dist: gradio (>=5.23.3,<6.0.0) ; extra == "gradio"
+Requires-Dist: importlib-metadata (>=8.2.0)
+Requires-Dist: linkml ; extra == "linkml"
+Requires-Dist: linkml-store[llm,mongodb] (>=0.2.4)
+Requires-Dist: logfire (>=3.5.3)
+Requires-Dist: markdownify (>=0.14.1)
+Requires-Dist: markitdown (>=0.0.1a4)
+Requires-Dist: mcp[cli] (>=1.3.0,<2.0.0)
+Requires-Dist: oaklib (>=0.6.19)
+Requires-Dist: pdfminer-six ; extra == "pdfminer"
+Requires-Dist: pydantic-ai (>=0.0.29)
+Requires-Dist: pypaperbot (>=1.4.1)
+Requires-Dist: pytest-asyncio (>=0.25.3,<0.26.0)
+Requires-Dist: rdkit ; extra == "rdkit" or extra == "chem"
+Requires-Dist: tabulate (>=0.9.0)
+Requires-Dist: undetected-chromedriver (>=3.5.5)
+Requires-Dist: wikipedia (>=1.4.0)
+Description-Content-Type: text/markdown
+
+
+# Aurelian: Agentic Universal Research Engine for Literature, Integration, Annotation, and Navigation
+
+| [Documentation](https://monarch-initiative.github.io/aurelian) |
+
+```
+aurelian --help
+```
+
+Most commands will start up a different AI agent.
+
+## Examples of use
+
+### TALISMAN
+
+gene set enrichment
+
+### Aria
+
+checking papers against checklists
+
+### GO-CAM agent
+
+This agent is for exploring, chatting with, and reviewing GO-CAMs
+
+Docs: [gocam_agent](https://monarch-initiative.github.io/aurelian/agents/gocam_agent/)
+
+It can be used to generate reviews according to guidelines for GO-CAMs:
+
+* [GO-CAM Reviews](https://cmungall.github.io/go-cam-reviews/)
+
+It can also generate SVGs, demonstrating innate knowledge of both the visual grammar of pathway diagrams and the semantics of the underlying biology.
+
+
+<img alt="img" src="https://cmungall.github.io/go-cam-reviews/figures/FIG-646ff70100005137-IL33_signaling_pathway__Human_.svg" />
+
+### GO-Ann agent
+
+This agent is for exploring, chatting with, and reviewing standard annotations
+
+
+Docs: [go_ann_agent](https://monarch-initiative.github.io/aurelian/agents/go_ann_agent/)
+
+Example review using TF guidelines:
+
+https://github.com/geneontology/go-annotation/issues/5743
+
+## Troubleshooting
+
+### Installing linkml-store
+
+Some agents require linkml-store pre-indexed. E.g. a mongodb with gocams for cam agent.
+Consult the [linkml-store documentation](https://linkml.io/linkml-store/) for more information.
+
+### Semantic search over ontologies
+
+If an agent requires ontology search it will use the semsql/OAK sqlite database.
+The first time querying it will use linkml-store to create an LLM index. Requires OAI key.
+This may be slow first iteration. Will be cached until your pystow cache regenerates.
+

aurelian-0.3.2/README.md

@@ -0,0 +1,59 @@
+
+# Aurelian: Agentic Universal Research Engine for Literature, Integration, Annotation, and Navigation
+
+| [Documentation](https://monarch-initiative.github.io/aurelian) |
+
+```
+aurelian --help
+```
+
+Most commands will start up a different AI agent.
+
+## Examples of use
+
+### TALISMAN
+
+gene set enrichment
+
+### Aria
+
+checking papers against checklists
+
+### GO-CAM agent
+
+This agent is for exploring, chatting with, and reviewing GO-CAMs
+
+Docs: [gocam_agent](https://monarch-initiative.github.io/aurelian/agents/gocam_agent/)
+
+It can be used to generate reviews according to guidelines for GO-CAMs:
+
+* [GO-CAM Reviews](https://cmungall.github.io/go-cam-reviews/)
+
+It can also generate SVGs, demonstrating innate knowledge of both the visual grammar of pathway diagrams and the semantics of the underlying biology.
+
+
+<img alt="img" src="https://cmungall.github.io/go-cam-reviews/figures/FIG-646ff70100005137-IL33_signaling_pathway__Human_.svg" />
+
+### GO-Ann agent
+
+This agent is for exploring, chatting with, and reviewing standard annotations
+
+
+Docs: [go_ann_agent](https://monarch-initiative.github.io/aurelian/agents/go_ann_agent/)
+
+Example review using TF guidelines:
+
+https://github.com/geneontology/go-annotation/issues/5743
+
+## Troubleshooting
+
+### Installing linkml-store
+
+Some agents require linkml-store pre-indexed. E.g. a mongodb with gocams for cam agent.
+Consult the [linkml-store documentation](https://linkml.io/linkml-store/) for more information.
+
+### Semantic search over ontologies
+
+If an agent requires ontology search it will use the semsql/OAK sqlite database.
+The first time querying it will use linkml-store to create an LLM index. Requires OAI key.
+This may be slow first iteration. Will be cached until your pystow cache regenerates.

aurelian-0.3.2/pyproject.toml

@@ -0,0 +1,130 @@
+[tool.poetry]
+name = "aurelian"
+version = "0.3.2"
+description = "aurelian"
+authors = ["Author 1 <author@org.org>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+click = "*"
+importlib-metadata = ">=8.2.0"
+oaklib = ">=0.6.19"
+tabulate = ">=0.9.0"
+linkml-store = {extras = ["llm", "mongodb"], version = ">=0.2.4"}
+rdkit = {optional=true, version="*"}
+gocam = {optional=true, version="*"}
+linkml = {optional=true, version="*"}
+gradio = "^5.23.3"
+pydantic-ai = ">=0.0.29"
+logfire = ">=3.5.3"
+bs4 = ">=0.0.2"
+duckduckgo-search = ">=7.3.2"
+markdownify = ">=0.14.1"
+wikipedia = ">=1.4.0"
+markitdown = ">=0.0.1a4"
+pypaperbot = ">=1.4.1"
+undetected-chromedriver = ">=3.5.5"
+bioservices = ">=1.12.0"
+pdfminer-six = {optional=true, version="*"}
+mcp = {extras = ["cli"], version = "^1.3.0"}
+pytest-asyncio = "^0.25.3"
+cairosvg = "^2.7.1"
+
+[tool.poetry.group.dev.dependencies]
+pytest = {version = ">=8.3.2"}
+pytest-reportlog = {version = "*"}
+pytest-metadata = {version = "*"}
+tox = {version = ">=4.16.0"}
+mypy = {version = "*"}
+types-PyYAML = {version = "*"}
+jupyter = {version = "*"}
+papermill = {version = "*"}
+nbdime = {version = "*"}
+nbformat = {version = "*"}
+pre-commit = {version = ">=3.3.3"}
+
+[tool.poetry.extras]
+rdkit = ["rdkit"]
+gocam = ["gocam"]
+gradio = ["gradio"]
+bioservices = ["bioservices"]
+linkml = ["linkml"]
+chem = ["rdkit"]
+pdfminer = ["pdfminer-six"]
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: marks tests as integration tests that might have external dependencies",
+    "flaky: marks tests that might occasionally fail due to external conditions",
+]
+
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+mkdocs = "*"
+mkdocs-material = "*"
+mkdocs-mermaid2-plugin = "*"
+mkdocs-gen-files = "*"
+mkdocs-literate-nav = "*"
+mknotebooks = ">=0.8.0"
+mkdocs-windmill = "*"
+mkdocs-click = "*"
+mkdocstrings = {extras = ["crystal", "python"], version = "*"}
+typer = ">=0.9.0"  # Required for mkdocs-click
+
+[tool.poetry.scripts]
+aurelian = "aurelian.cli:main"
+
+[tool.poetry-dynamic-versioning]
+enable = false
+vcs = "git"
+style = "pep440"
+
+[tool.black]
+line-length = 120
+target-version = ["py38", "py39", "py310"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+extend-ignore = [
+    "S101",  # Allow assert statements in tests
+    "D104",  # Ignore missing docstrings in __init__.py
+    "D417",  # Ignore missing argument descriptions in docstrings
+    "D401",  # Ignore enforcing imperative mood in docstrings
+    "D400", "D415",  # Ignore docstring punctuation enforcement
+    "D200",  # Ignore "one-line docstring should fit on one line"
+    "F821",  # Ignore undefined name errors (useful if missing imports)
+    "S113",  # Ignore "requests call without timeout" warnings
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101"]  # Ignore asserts only in test files
+
+fixable = ["ALL"]
+select = [
+    "B",  # bugbear
+    "D",  # pydocstyle
+    "E",  # pycodestyle errors
+    "F",  # Pyflakes
+    "I",  # isort
+    "S",  # flake8-bandit
+    "W",  # Warning
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.codespell]
+skip = "*.po,*.ts,.git,pyproject.toml"
+count = ""
+quiet-level = 3
+
+[build-system]
+requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning"]
+build-backend = "poetry_dynamic_versioning.backend"

aurelian-0.3.2/src/aurelian/__init__.py

@@ -0,0 +1,9 @@
+"""ubergraph-agent package."""
+
+import importlib_metadata
+
+try:
+    __version__ = importlib_metadata.version(__name__)
+except importlib_metadata.PackageNotFoundError:
+    # package is not installed
+    __version__ = "0.0.0"  # pragma: no cover

aurelian-0.3.2/src/aurelian/agents/amigo/__init__.py

@@ -0,0 +1,3 @@
+"""
+AmiGO agent module for interacting with GO KnowledgeBase via AmiGO solr endpoint.
+"""

aurelian-0.3.2/src/aurelian/agents/amigo/amigo_agent.py

@@ -0,0 +1,77 @@
+"""
+Agent for interacting with GO KnowledgeBase via AmiGO solr endpoint.
+"""
+from aurelian.agents.amigo.amigo_config import AmiGODependencies
+from aurelian.agents.amigo.amigo_tools import (
+    find_gene_associations,
+    find_gene_associations_for_pmid,
+    lookup_uniprot_entry,
+    uniprot_mapping
+)
+from aurelian.agents.literature.literature_tools import (
+    lookup_pmid as literature_lookup_pmid,
+    search_literature_web,
+    retrieve_literature_page
+)
+from pydantic_ai import Agent, Tool
+
+SYSTEM = """
+You are a biocurator that can answer questions using the Gene Ontology knowledge base via the AmiGO API.
+
+Do not assume the knowledge base is complete or always correct. Your job is to help curators find mistakes
+or missing information. A particular pervasive issue in GO is over-annotation based on phenotypes - a gene
+should only be annotated to a process if it is involved in that process, i.e., if the activity of the
+gene process is an identifiable step in the pathway.
+
+You can help with:
+- Finding gene associations for specific genes or gene products
+- Finding gene associations cited in specific publications by PMID
+- Looking up protein information via UniProt
+- Mapping UniProt accessions to other databases
+- Analyzing gene function and involvement in biological processes
+- Identifying potential over-annotations or missing annotations
+
+You can also use your general knowledge of genes and biological processes, and do additional searches
+when needed to provide context or verification.
+"""
+
+amigo_agent = Agent(
+    model="openai:gpt-4o",
+    deps_type=AmiGODependencies,
+    system_prompt=SYSTEM,
+    tools=[
+        Tool(find_gene_associations),
+        Tool(find_gene_associations_for_pmid),
+        Tool(lookup_uniprot_entry),
+        Tool(uniprot_mapping),
+        Tool(literature_lookup_pmid, name="lookup_pmid",
+             description="""Lookup the text of a PubMed article by its PMID.
+
+A PMID should be of the form "PMID:nnnnnnn" (no underscores).
+
+This is useful for retrieving the full text of papers referenced in GO annotations
+to verify the evidence for gene annotations or identify potential over-annotations.
+
+Args:
+    pmid: The PubMed ID to look up
+        
+Returns:
+    str: Full text if available, otherwise abstract"""),
+        Tool(search_literature_web, name="search_web",
+             description="""Search the web using a text query.
+    
+Args:
+    query: The search query
+        
+Returns:
+    str: Search results with summaries"""),
+        Tool(retrieve_literature_page, name="retrieve_web_page",
+             description="""Fetch the contents of a web page.
+    
+Args:
+    url: The URL to fetch
+        
+Returns:
+    str: The contents of the web page""")
+    ]
+)

aurelian-0.3.2/src/aurelian/agents/amigo/amigo_config.py

@@ -0,0 +1,85 @@
+"""
+Configuration classes for the AmiGO agent.
+"""
+from dataclasses import dataclass, field
+
+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 AmiGODependencies(HasWorkdir):
+    """
+    Configuration for the AmiGO agent.
+    
+    Args:
+        taxon: NCBI Taxonomy ID, defaults to human (9606)
+    """
+    taxon: str = field(default="9606")
+    
+    def get_uniprot_service(self) -> UniProt:
+        """
+        Get the UniProt service for protein lookups.
+        
+        Returns:
+            UniProt: The UniProt service
+        """
+        return uniprot_service
+    
+    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") -> AmiGODependencies:
+    """
+    Get the AmiGO configuration.
+    
+    Args:
+        taxon: NCBI Taxonomy ID, defaults to human (9606)
+        
+    Returns:
+        AmiGODependencies: The AmiGO dependencies
+    """
+    return AmiGODependencies(taxon=taxon)

aurelian-0.3.2/src/aurelian/agents/amigo/amigo_evals.py

@@ -0,0 +1,73 @@
+"""
+Evaluation module for the AmiGO agent.
+
+This module implements evaluations for the AmiGO 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 aurelian.agents.amigo.amigo_agent import amigo_agent
+from aurelian.agents.amigo.amigo_config import AmiGODependencies
+
+class AmiGOMetadata(Dict[str, Any]):
+    """Simple metadata dictionary for AmiGO evaluations."""
+    pass
+
+# Define individual evaluation cases
+case1 = Case(
+    name="uniprot_annotations",
+    inputs="What are some annotations for the protein UniProtKB:Q9UMS5",
+    expected_output="GO:",  # Should contain GO terms
+    metadata=metadata("medium", "annotation_retrieval")
+)
+
+case2 = Case(
+    name="paper_overannotation",
+    inputs="Check PMID:19661248 for over-annotation",
+    expected_output="annotation",  # Should evaluate the paper's annotations
+    metadata=metadata("hard", "literature_assessment")
+)
+
+case3 = Case(
+    name="pathway_genes",
+    inputs="What genes are involved in the ribosome biogenesis pathway?",
+    expected_output="ribosom",  # Should mention ribosome-related genes
+    metadata=metadata("medium", "pathway_analysis")
+)
+
+case4 = Case(
+    name="database_mapping",
+    inputs="Map UniProtKB:P04637 to KEGG database",
+    expected_output="KEGG",  # Should contain KEGG IDs
+    metadata=metadata("easy", "database_mapping")
+)
+
+case5 = Case(
+    name="dna_repair_genes",
+    inputs="Search for genes involved in DNA repair and show me their annotations",
+    expected_output="repair",  # Should mention DNA repair annotations
+    metadata=metadata("medium", "gene_function_search")
+)
+
+def create_eval_dataset() -> Dataset[str, str, MetadataDict]:
+    """
+    Create a dataset for evaluating the AmiGO agent.
+    
+    Returns:
+        Dataset of AmiGO evaluation cases with appropriate evaluators
+    """
+    # Collect all cases
+    cases = [case1, case2, case3, case4, case5]
+    
+    # Dataset-level evaluators
+    evaluators = [SubstringEvaluator()]
+    
+    return Dataset(
+        cases=cases,
+        evaluators=evaluators
+    )

aurelian-0.3.2/src/aurelian/agents/amigo/amigo_gradio.py

@@ -0,0 +1,52 @@
+"""
+Gradio UI for the AmiGO agent.
+"""
+from typing import List, Optional
+
+import gradio as gr
+
+from aurelian.agents.amigo.amigo_agent import amigo_agent
+from aurelian.agents.amigo.amigo_config import AmiGODependencies
+from aurelian.utils.async_utils import run_sync
+
+
+def chat(deps: Optional[AmiGODependencies] = None, taxon: Optional[str] = None, **kwargs):
+    """
+    Initialize a chat interface for the AmiGO agent.
+    
+    Args:
+        deps: Optional dependencies configuration
+        taxon: Optional NCBI Taxonomy ID, defaults to human (9606)
+        **kwargs: Additional arguments to pass to the agent
+        
+    Returns:
+        A Gradio chat interface
+    """
+    if deps is None:
+        deps = AmiGODependencies()
+        
+    if taxon:
+        deps.taxon = taxon
+
+    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: amigo_agent.run_sync(query, deps=deps, **kwargs))
+        return result.data
+
+    return gr.ChatInterface(
+        fn=get_info,
+        type="messages",
+        title="AmiGO AI Assistant",
+        examples=[
+            ["What are some annotations for the protein UniProtKB:Q9UMS5"],
+            ["Check PMID:19661248 for over-annotation"],
+            ["What genes are involved in the ribosome biogenesis pathway?"],
+            ["Map UniProtKB:P04637 to KEGG database"],
+            ["Search for genes involved in DNA repair and show me their annotations"]
+        ]
+    )