Add an entity set to a GO-CAM model with validated members.

Creates an entity set (CHEBI:33695 "information biomacromolecule" by default) representing functionally interchangeable entities. Links members using RO:0019003 (has substitutable entity) relation. The operation is atomic - either all members are added successfully or the entire operation is rolled back.

Args: model_id: The GO-CAM model identifier members: List of member dictionaries with keys: - entity_id (required): Entity ID (e.g., "UniProtKB:P12345") - label (optional): Member label for validation - evidence_type (optional): ECO code (e.g., "ECO:0000353") - reference (optional): Source reference (e.g., "PMID:12345678") assign_var: Variable name for the set (default: "set1")

Returns: Barista API response with set ID and member IDs

Examples: # Create a set of functionally equivalent kinases add_entity_set( "gomodel:12345", [ {"entity_id": "UniProtKB:P31749", "label": "AKT1"}, {"entity_id": "UniProtKB:P31751", "label": "AKT2"}, {"entity_id": "UniProtKB:Q9Y243", "label": "AKT3"} ], assign_var="akt_isoforms" )

# Create set with evidence
add_entity_set(
    "gomodel:12345",
    [
        {
            "entity_id": "UniProtKB:P04637",
            "label": "TP53",
            "evidence_type": "ECO:0000314",
            "reference": "PMID:87654321"
        },
        {
            "entity_id": "UniProtKB:P04049",
            "label": "RAF1",
            "evidence_type": "ECO:0000314",
            "reference": "PMID:87654321"
        }
    ],
)

Notes: - All members must have entity_id specified - Label validation prevents ID hallucination - Evidence and references are optional but recommended - Uses RO:0019003 (has substitutable entity) to link members - Atomic operation with automatic rollback on failure - Entity sets represent functionally interchangeable entities

Add evidence to an existing fact in a GO-CAM model.

Args: model_id: The GO-CAM model identifier subject_id: Subject of the fact object_id: Object of the fact predicate_id: Predicate of the fact eco_id: Evidence code (e.g., "ECO:0000353") sources: List of source references (e.g., ["PMID:12345"]) with_from: Optional list of with/from references

Returns: Barista API response

Examples: # Add experimental evidence from a paper add_evidence_to_fact( "gomodel:12345", "mf1", "gp1", "RO:0002333", "ECO:0000353", # physical interaction evidence ["PMID:12345678"] )

# Add multiple sources
add_evidence_to_fact(
    "gomodel:12345", "mf1", "gp1", "RO:0002333",
    "ECO:0000314",  # direct assay evidence
    ["PMID:12345678", "PMID:87654321", "doi:10.1234/example"]
)

# Add evidence with with/from (e.g., for IPI)
add_evidence_to_fact(
    "gomodel:12345", "mf1", "gp1", "RO:0002333",
    "ECO:0000353",  # IPI
    ["PMID:12345678"],  
    ["UniProtKB:Q9Y6K9", "UniProtKB:P38398"]  # interacting partners
)

# Common evidence codes:
# ECO:0000314 - direct assay evidence
# ECO:0000353 - physical interaction evidence (IPI)
# ECO:0000315 - mutant phenotype evidence (IMP)
# ECO:0000316 - genetic interaction evidence (IGI)
# ECO:0000318 - biological aspect of ancestor evidence (IBA)
# ECO:0000269 - experimental evidence

Add a fact (edge/relation) between two individuals in a model.

Args: model_id: The GO-CAM model identifier subject_id: Subject individual ID or variable object_id: Object individual ID or variable predicate_id: Relation predicate (e.g., "RO:0002333" for enabled_by)

Returns: Barista API response

Examples: # Connect molecular function to gene product (enabled_by) add_fact("gomodel:12345", "mf1", "gp1", "RO:0002333")

# Connect molecular function to cellular component (occurs_in)
add_fact("gomodel:12345", "mf1", "cc1", "BFO:0000066")

# Connect molecular function to biological process (part_of)
add_fact("gomodel:12345", "mf1", "bp1", "BFO:0000050")

# Add causal relationship between activities
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002411")  # causally upstream of
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002629")  # directly positively regulates
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002630")  # directly negatively regulates
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002413")  # provides input for

# Add regulates relationships
add_fact("gomodel:12345", "mf1", "bp1", "RO:0002211")  # regulates
add_fact("gomodel:12345", "mf1", "bp1", "RO:0002213")  # positively regulates
add_fact("gomodel:12345", "mf1", "bp1", "RO:0002212")  # negatively regulates

# Add indirect regulation relationships
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002407")  # indirectly positively regulates
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002409")  # indirectly negatively regulates

# Add causal relationships with effects
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002304")  # causally upstream of, positive effect
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002305")  # causally upstream of, negative effect

# Add small molecule regulation relationships
add_fact("gomodel:12345", "sm1", "mf1", "RO:0012005")  # is small molecule activator of
add_fact("gomodel:12345", "sm1", "mf1", "RO:0012006")  # is small molecule inhibitor of

# Use with existing individual IDs from model
add_fact("gomodel:12345", "gomodel:12345/abc123", "gomodel:12345/def456", "RO:0002333")

Add an individual (instance) of a class to a GO-CAM model with label validation.

This tool requires providing the expected label for the class to prevent accidental use of wrong IDs (e.g., GO:0003924 vs GO:0003925). The operation will automatically rollback if the created individual doesn't match the expected label.

Args: model_id: The GO-CAM model identifier (e.g., "gomodel:12345") class_curie: The class to instantiate (e.g., "GO:0003674") class_label: The expected rdfs:label of the class (e.g., "molecular_function") assign_var: Variable name for referencing in the same batch

Returns: Barista API response with message-type and signal fields. If validation fails, includes rolled_back=true and validation error.

Examples: # Add a molecular function activity with validation add_individual("gomodel:12345", "GO:0004672", "protein kinase activity", "mf1")

# Add a protein/gene product with validation
add_individual("gomodel:12345", "UniProtKB:P38398", "BRCA1", "gp1")

# Add a cellular component with validation
add_individual("gomodel:12345", "GO:0005737", "cytoplasm", "cc1")

# Add a biological process with validation
add_individual("gomodel:12345", "GO:0016055", "Wnt signaling pathway", "bp1")

# Add an evidence instance with validation
add_individual("gomodel:12345", "ECO:0000353", "physical interaction evidence", "ev1")

# Variables like "mf1", "gp1" can be referenced in subsequent
# add_fact calls within the same batch operation

Notes: - The label acts as a checksum to prevent ID hallucination - If the label doesn't match, the operation is automatically rolled back - This prevents corrupt models from incorrect IDs

Add a protein complex to a GO-CAM model with validated components.

Creates a protein-containing complex (GO:0032991 by default) and links all components using BFO:0000051 (has part) relation. The operation is atomic - either all components are added successfully or the entire operation is rolled back.

Args: model_id: The GO-CAM model identifier components: List of component dictionaries with keys: - entity_id (required): Protein/gene product ID (e.g., "UniProtKB:P12345") - label (optional): Component label for validation - evidence_type (optional): ECO code (e.g., "ECO:0000353") - reference (optional): Source reference (e.g., "PMID:12345678") assign_var: Variable name for the complex (default: "complex1")

Returns: Barista API response with complex ID and component IDs

Examples: # Create a simple dimer complex add_protein_complex( "gomodel:12345", [ {"entity_id": "UniProtKB:P04637", "label": "TP53"}, {"entity_id": "UniProtKB:P04637", "label": "TP53"} ], )

# Create complex with evidence
add_protein_complex(
    "gomodel:12345",
    [
        {
            "entity_id": "UniProtKB:P68400",
            "label": "CSNK1A1",
            "evidence_type": "ECO:0000353",
            "reference": "PMID:12345678"
        },
        {
            "entity_id": "UniProtKB:P49841",
            "label": "GSK3B",
            "evidence_type": "ECO:0000353",
            "reference": "PMID:12345678"
        }
    ],
    assign_var="destruction_complex"
)

# Create a complex with specific assignment variable
add_protein_complex(
    "gomodel:12345",
    [
        {"entity_id": "UniProtKB:P62191", "label": "PSMC1"},
        {"entity_id": "UniProtKB:P62195", "label": "PSMC5"}
    ],
    assign_var="proteasome"
)

Notes: - All components must have entity_id specified - Label validation prevents ID hallucination - Evidence and references are optional but recommended - Uses BFO:0000051 (has part) to link components - Atomic operation with automatic rollback on failure

Configure the Barista authentication token.

Args: token: The Barista authentication token

Returns: Success status

Create a new empty GO-CAM model.

Args: title: Optional title for the model

Returns: Barista API response containing the new model ID and editor URLs

Examples:

• create_model("RAS-RAF signaling pathway")

Notes: - The returned model_id can be used with other tools like add_individual - Models are created in "development" state by default - To add taxon information, use add_individual after creating the model

Get all GO annotations (evidence) for a specific bioentity.

Args: bioentity_id: The bioentity ID (e.g., "UniProtKB:P12345") go_terms: Comma-separated GO terms to filter (includes child terms) evidence_types: Comma-separated evidence codes to filter (e.g., "IDA,IPI") aspect: GO aspect filter - "C", "F", or "P" limit: Maximum number of results (default: 100)

Returns: Dictionary containing: - bioentity_id: The queried bioentity - annotations: List of annotation results - summary: Count by aspect and evidence type

Examples: # Get all annotations for a protein get_annotations_for_bioentity("UniProtKB:P53762")

# Get only experimental evidence
get_annotations_for_bioentity(
    "UniProtKB:P53762",
    evidence_types="IDA,IPI,IMP"
)

# Get annotations for specific GO terms
get_annotations_for_bioentity(
    "UniProtKB:P53762",
    go_terms="GO:0005634,GO:0005737"
)

# Get only molecular function annotations
get_annotations_for_bioentity(
    "UniProtKB:P53762",
    aspect="F"
)

Fetch specific GO-CAM guideline content.

Args: guideline_name: Name of guideline file (without .md extension). Use list_guidelines() to see available options.

Returns: Dictionary with guideline content or error message

Examples: # Get a specific guideline content = get_guideline_content("E3_ubiquitin_ligases")

# Get transcription factor guidelines
content = get_guideline_content("DNA-binding_transcription_factor_activity_annotation_guidelines")

Retrieve the full JSON representation of a GO-CAM model.

Args: model_id: The GO-CAM model identifier

Returns: Full model data including individuals and facts

Examples: # Get a production model model = get_model("gomodel:5fce9b7300001215") # Returns complete model with: # - data.id: model ID # - data.individuals: list of all individuals # - data.facts: list of all relationships # - data.annotations: model-level annotations

# Extract specific information
model = get_model("gomodel:12345")
individuals = model["data"]["individuals"]
facts = model["data"]["facts"]

# Find all molecular functions
mfs = [i for i in individuals
       if any("GO:0003674" in str(e.id) for e in i.type if hasattr(e, 'id'))]

# Find all enabled_by relationships (facts are Pydantic objects)
enabled_by = [f for f in facts if f.property == "RO:0002333"]

# Check model state
state = model["data"].get("state")

Get the currently bound variables for a GO-CAM model.

Returns a mapping of variable names to their actual individual IDs. This is useful for understanding what variables are available in the current model context, especially after batch operations.

Args: model_id: The GO-CAM model identifier

Returns: Dictionary with variable mappings and model information

Examples: # Get variables after creating individuals vars = get_model_variables("gomodel:12345") # Returns: # { # "model_id": "gomodel:12345", # "variables": { # "mf1": "gomodel:12345/68dee4d300000481", # "gp1": "gomodel:12345/68dee4d300000482", # "cc1": "gomodel:12345/68dee4d300000483" # }, # "individual_count": 3 # }

# Use the variables in subsequent operations
vars = get_model_variables("gomodel:12345")
mf_id = vars["variables"]["mf1"]
add_fact("gomodel:12345", mf_id, vars["variables"]["gp1"], "RO:0002333")

Notes: - Variables are only valid within the same batch operation - This tool helps identify actual IDs for cross-batch operations - If the model has no tracked variables, returns empty dict

List all available GO-CAM guideline documents.

Returns a list of available guideline names that can be accessed using the get_guideline_content tool.

Returns: Dictionary with 'guidelines' key containing list of available guidelines

Examples: # List all available guidelines result = list_guidelines() for guide in result['guidelines']: print(guide)

Get a summary of a GO-CAM model including counts and key information.

Args: model_id: The GO-CAM model identifier

Returns: Summary with individual count, fact count, and predicate distribution

Examples: # Get summary of a model result = model_summary("gomodel:5fce9b7300001215") # Returns: # { # "model_id": "gomodel:5fce9b7300001215", # "state": "production", # "individual_count": 42, # "fact_count": 67, # "predicate_distribution": { # "RO:0002333": 15, # enabled_by (note: not in vetted list) # "RO:0002411": 8, # causally upstream of # "BFO:0000066": 12, # occurs_in # "BFO:0000050": 5 # part_of # } # }

# Check if a model is empty
result = model_summary("gomodel:new_empty_model")
if result["individual_count"] == 0:
    print("Model is empty")

# Analyze model complexity
result = model_summary("gomodel:12345")
causal_edges = result["predicate_distribution"].get("RO:0002411", 0)
causal_edges += result["predicate_distribution"].get("RO:0002413", 0)  # provides input for
causal_edges += result["predicate_distribution"].get("RO:0002629", 0)  # directly positively regulates
causal_edges += result["predicate_distribution"].get("RO:0002630", 0)  # directly negatively regulates
print(f"Model has {causal_edges} causal relationships")

Remove a fact from a GO-CAM model.

You must specify the exact triple (subject, predicate, object) to remove.

Args: model_id: The GO-CAM model identifier subject_id: Subject of the fact object_id: Object of the fact predicate_id: Predicate of the fact

Returns: Barista API response

Examples: # Remove an enabled_by relationship remove_fact( "gomodel:12345", "gomodel:12345/mf_123", "gomodel:12345/gp_456", "RO:0002333" )

# Remove a causal relationship
remove_fact(
    "gomodel:12345",
    "gomodel:12345/activity1",
    "gomodel:12345/activity2",
    "RO:0002413"  # provides input for
)

# Remove occurs_in relationship
remove_fact(
    "gomodel:12345",
    "gomodel:12345/mf_123",
    "gomodel:12345/cc_789",
    "BFO:0000066"  # occurs_in
)

# Remove using variable references (within same batch)
remove_fact("gomodel:12345", "mf1", "gp1", "RO:0002333")

Remove an individual from a GO-CAM model.

Note: This will also remove all facts (edges) connected to this individual.

Args: model_id: The GO-CAM model identifier individual_id: The individual to remove

Returns: Barista API response

Examples: # Remove using a variable reference (within same batch) remove_individual("gomodel:12345", "mf1")

# Remove using full individual ID
remove_individual("gomodel:12345", "gomodel:12345/5fce9b7300001215")

# Remove an evidence individual
remove_individual("gomodel:12345", "gomodel:12345/evidence_123")

# Clean up after testing
for ind_id in ["test1", "test2", "test3"]:
    remove_individual("gomodel:12345", ind_id)

Search for GO annotations (evidence) with filtering.

Args: bioentity: Specific bioentity ID to filter by (e.g., "UniProtKB:P12345") go_term: Specific GO term ID to filter by (e.g., "GO:0008150") evidence_types: Comma-separated evidence codes (e.g., "IDA,IPI,IMP") taxon: Organism filter - accepts numeric (9606) or full ID (NCBITaxon:9606) aspect: GO aspect filter - "C" (cellular component), "F" (molecular function), or "P" (biological process) assigned_by: Annotation source filter (e.g., "GOC", "UniProtKB", "MGI") limit: Maximum number of results (default: 10, max: 1000)

Returns: Dictionary containing: - annotations: List of annotation results with evidence details - total: Number of results returned

Examples: # Find all evidence for a specific protein search_annotations(bioentity="UniProtKB:P53762")

# Find proteins with experimental evidence for a GO term
search_annotations(go_term="GO:0005634", evidence_types="IDA,IPI")

# Find human proteins in nucleus with experimental evidence
search_annotations(
    go_term="GO:0005634",
    taxon="9606",
    evidence_types="IDA,IPI,IMP",
    aspect="C"
)

# Find all UniProt annotations for apoptosis
search_annotations(
    go_term="GO:0006915",
    assigned_by="UniProtKB"
)

Search for bioentities (genes/proteins) using Gene Ontology data.

Searches across gene and protein names/labels with optional taxonomic filtering. Provides access to comprehensive bioentity information from GOlr.

Args: text: Text search across names and labels (e.g., "insulin", "kinase") taxon: Organism filter - accepts NCBI Taxon ID with or without prefix (e.g., "9606", "NCBITaxon:9606" for human) bioentity_type: Type filter (e.g., "protein", "gene") source: Source database filter (e.g., "UniProtKB", "MGI", "RGD") limit: Maximum number of results to return (default: 10) offset: Starting offset for pagination (default: 0)

Returns: Dictionary containing search results with bioentity information

Examples: # Search for human insulin proteins results = search_bioentities( text="insulin", taxon="9606", bioentity_type="protein" )

# Find mouse kinases from MGI
results = search_bioentities(
    text="kinase",
    taxon="NCBITaxon:10090",
    source="MGI",
    limit=20
)

# Search for any human genes/proteins
results = search_bioentities(
    taxon="9606",
    limit=50
)

# Find specific protein types
results = search_bioentities(
    text="receptor",
    bioentity_type="protein",
    limit=25
)

# Search across all organisms
results = search_bioentities(text="p53")

# Pagination example
page1 = search_bioentities(text="kinase", limit=10, offset=0)
page2 = search_bioentities(text="kinase", limit=10, offset=10)

# Common organisms:
# Human: "9606" or "NCBITaxon:9606"
# Mouse: "10090" or "NCBITaxon:10090"
# Rat: "10116" or "NCBITaxon:10116"
# Fly: "7227" or "NCBITaxon:7227"
# Worm: "6239" or "NCBITaxon:6239"
# Yeast: "559292" or "NCBITaxon:559292"

Notes: - Results include ID, name, type, organism, and source information - Text search covers both short names/symbols and full descriptions - Taxon IDs automatically handle NCBITaxon: prefix normalization - Use pagination for large result sets - Sources include UniProtKB, MGI, RGD, ZFIN, SGD, and others

Search for GO-CAM models based on various criteria.

Allows searching models by title, state, contributor, group, publication, or gene product. Returns a list of matching models with their metadata.

Args: title: Search for models containing this text in their title state: Filter by model state (production, development, internal_test) contributor: Filter by contributor ORCID (e.g., 'https://orcid.org/0000-0002-6601-2165') group: Filter by group/provider (e.g., 'http://www.wormbase.org') pmid: Filter by PubMed ID (e.g., 'PMID:12345678') gene_product: Filter by gene product (e.g., 'UniProtKB:Q9BRQ8', 'MGI:MGI:97490') limit: Maximum number of results to return (default: 50) offset: Offset for pagination (default: 0)

Returns: Dictionary containing search results with model metadata

Examples: # Search for all production models results = search_models(state="production")

# Find models containing "Wnt signaling" in title
results = search_models(title="Wnt signaling")

# Find models for a specific gene product
results = search_models(gene_product="UniProtKB:P38398")

# Find models from a specific paper
results = search_models(pmid="PMID:30194302")

# Find models by a specific contributor
results = search_models(
    contributor="https://orcid.org/0000-0002-6601-2165"
)

# Combine filters
results = search_models(
    state="production",
    title="kinase",
    limit=10
)

# Pagination example
page1 = search_models(limit=50, offset=0)
page2 = search_models(limit=50, offset=50)

# Find models from specific research group
results = search_models(group="http://www.wormbase.org")

# Search for development models with specific gene
results = search_models(
    state="development",
    gene_product="MGI:MGI:97490"
)

Notes: - Results include model ID, title, state, contributors, and dates - Use pagination (offset/limit) for large result sets - Filters can be combined for more specific searches - Gene products can be from various databases (UniProt, MGI, RGD, etc.)