bc_get_drug_statistics

Instructions

Implementation Reference

• src/biocontext_kb/core/openfda/_count_drugs.py:56-90 (handler)

  Handler function for 'get_drug_statistics' tool. Fetches FDA drug statistics (top sponsors, dosage forms, routes, marketing statuses) from the openFDA Drugs@FDA API. Registered via @core_mcp.tool() decorator.

  @core_mcp.tool()
  def get_drug_statistics() -> dict:
      """Get general statistics about the FDA Drugs@FDA database. Includes top sponsors, dosage forms, routes, marketing status.
  
      Returns:
          dict: Top sponsors, dosage_forms, administration_routes, marketing_statuses with counts or error message.
      """
      statistics = {}
  
      try:
          # Get top sponsors
          base_url = "https://api.fda.gov/drug/drugsfda.json"
          sponsors_response = requests.get(base_url, params={"count": "sponsor_name", "limit": 10})  # type: ignore
          sponsors_response.raise_for_status()
          statistics["top_sponsors"] = sponsors_response.json()
  
          # Get dosage forms
          dosage_response = requests.get(base_url, params={"count": "products.dosage_form", "limit": 15})  # type: ignore
          dosage_response.raise_for_status()
          statistics["dosage_forms"] = dosage_response.json()
  
          # Get routes of administration
          routes_response = requests.get(base_url, params={"count": "products.route", "limit": 15})  # type: ignore
          routes_response.raise_for_status()
          statistics["administration_routes"] = routes_response.json()
  
          # Get marketing statuses
          status_response = requests.get(base_url, params={"count": "products.marketing_status", "limit": 10})  # type: ignore
          status_response.raise_for_status()
          statistics["marketing_statuses"] = status_response.json()
  
          return statistics
  
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch FDA drug statistics: {e!s}"}

• src/biocontext_kb/core/openfda/_count_drugs.py:56-57 (registration)

  Tool registration using the FastMCP decorator on the get_drug_statistics function. The core_mcp instance is defined in src/biocontext_kb/core/_server.py.

  @core_mcp.tool()
  def get_drug_statistics() -> dict:

• src/biocontext_kb/core/openfda/__init__.py:15-19 (registration)

  Exports get_drug_statistics in the package's __all__ list, and imports it from _count_drugs on line 6.

      "get_drug_statistics",
      "get_generic_equivalents",
      "search_drugs_by_therapeutic_class",
      "search_drugs_fda",
  ]

• src/biocontext_kb/core/_server.py:1-6 (helper)

  The core_mcp FastMCP server instance used to register tools via the @core_mcp.tool() decorator.

  from fastmcp import FastMCP
  
  core_mcp = FastMCP(  # type: ignore
      "BC",
      instructions="Provides access to biomedical knowledge bases.",
  )

• tests/core/test_openfda.py:69-80 (helper)

  Test for the get_drug_statistics tool, verifying it returns a dict with expected keys.

  async def test_get_drug_statistics():
      """Test the get_drug_statistics function."""
      async with Client(core_mcp) as client:
          result_text = await client.call_tool("get_drug_statistics", {})
          result = json.loads(result_text.content[0].text)
  
          assert isinstance(result, dict)
          # Should have multiple statistics sections
          if "error" not in result:
              assert any(
                  key in result for key in ["top_sponsors", "dosage_forms", "administration_routes", "marketing_statuses"]
              )