add_protein_complex

Instructions

# 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"
)

Implementation Reference

• src/noctua_mcp/mcp_server.py:439-566 (handler)

  The MCP tool handler for 'add_protein_complex'. Decorated with @mcp.tool(), it accepts model_id, components list (with entity_id, label, evidence_type, reference), and assign_var. It converts component dicts to ProteinComplexComponent Pydantic models, calls client.add_protein_complex(), and returns the response with complex_id and component_count.

  @mcp.tool()
  async def add_protein_complex(
      model_id: str,
      components: List[Dict[str, Any]],
      assign_var: str = "complex1"
  ) -> Dict[str, Any]:
      """
      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
      """
      client = get_client()
  
      # Convert component dicts to Pydantic models
      try:
          pydantic_components = [ProteinComplexComponent(**comp) for comp in components]
      except Exception as e:
          return {
              "success": False,
              "error": "Invalid component structure",
              "reason": str(e),
              "hint": "Each component must have 'entity_id' field. Optional: 'label', 'evidence_type', 'reference'"
          }
  
      # Call the new add_protein_complex method
      resp = client.add_protein_complex(
          model_id,
          pydantic_components,
          assign_var=assign_var
      )
  
      if resp.validation_failed:
          return {
              "success": False,
              "error": "Validation failed",
              "reason": resp.validation_reason,
              "rolled_back": True,
              "component_count": len(components)
          }
  
      if resp.error:
          return {
              "success": False,
              "error": resp.error,
              "model_id": model_id
          }
  
      # Get the complex ID from model_vars or from the individuals list
      complex_id = assign_var
      if resp.model_vars and assign_var in resp.model_vars:
          complex_id = resp.model_vars[assign_var]
      elif resp.individuals and len(resp.individuals) > 0:
          # Find the complex individual (it should be the first one created in this operation)
          # The complex is created first, then components are added
          for ind in resp.individuals:
              # Check if it's a protein-containing complex
              if hasattr(ind, 'type') and any('GO:0032991' in str(t.id) if hasattr(t, 'id') else False for t in ind.type):
                  complex_id = ind.id
                  break
  
      return {
          "success": True,
          "complex_id": complex_id,
          "component_count": len(components),
          "assign_var": assign_var
      }

• src/noctua_mcp/mcp_server.py:25-25 (schema)

  Import of ProteinComplexComponent from noctua.models, used as the Pydantic schema for validating component dicts in add_protein_complex.

  from noctua.models import ProteinComplexComponent, EntitySetMember

• src/noctua_mcp/mcp_server.py:439-440 (registration)

  The @mcp.tool() decorator on line 439 registers 'add_protein_complex' as an MCP tool with FastMCP.

  @mcp.tool()
  async def add_protein_complex(

• src/noctua_mcp/mcp_server.py:516-530 (helper)

  Conversion of component dictionaries to ProteinComplexComponent Pydantic models for validation before passing to the client.

      pydantic_components = [ProteinComplexComponent(**comp) for comp in components]
  except Exception as e:
      return {
          "success": False,
          "error": "Invalid component structure",
          "reason": str(e),
          "hint": "Each component must have 'entity_id' field. Optional: 'label', 'evidence_type', 'reference'"
      }
  
  # Call the new add_protein_complex method
  resp = client.add_protein_complex(
      model_id,
      pydantic_components,
      assign_var=assign_var
  )