# mims-harvard/tooluniverse architecture

> Architecture diagram of the GitHub repository mims-harvard/tooluniverse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mims-harvard/tooluniverse
- Repository: https://github.com/mims-harvard/tooluniverse

## Overview

##### Project Type and Purpose
- ToolUniverse is a Python library designed as a collection of biomedical tools. Its main purpose is to support Agentic AI (specifically the TxAgent project) by providing access to hundreds of biomedical tools and trusted data sources (such as FDA approvals, Open Targets, and Monarch Initiative data) that can be queried to perform complex therapeutic reasoning.
- It is a backend library (not a full-stack or UI-focused project) intended to be imported and used as a dependency that supplies biomedical knowledge and functionality via a unified API.

##### File Structure
- Top-Level Files: Files like LICENSE, README.md, pyproject.toml, and setup.cfg indicate it’s a packaged Python project ready for installation via Pypi.
- Source Code Location: Under the “src/tooluniverse” directory, you find the main modules.
- __init__.py: Primary entry point for the package.
- base_tool.py: Likely defines common functionality or interfaces for tools.
- execute_function.py, graphql_tool.py, openfda_tool.py, restful_tool.py: Each of these modules implements a specific type of tool with different modes of accessing external biomedical data (e.g., GraphQL-based, RESTful, OpenFDA-specific).
- utils.py: Contains utility functions, possibly for common operations or shared code between modules.
- Data Directory: The “src/tooluniverse/data” folder holds JSON files and a Python file that provide static datasets such as FDA drug labeling data, tools from Monarch, OpenTargets, and any “special_tools” that may have additional business logic. This data is a crucial component of the tool registry.

##### README for Additional Insights
- The README clearly explains how to install and use the project (from source or via Pypi).
- Usage examples illustrate two primary operations: loading all the tools and running a specific function call to a tool by its name.
- The ToolUniverse library serves as an abstraction layer, where a user (or another agent like TxAgent) can call methods to retrieve a list of tool names and descriptions, and then execute functions provided by these tools.

a. Main Components to Include:
- ToolUniverse API/Interface: The central interface exposing methods like load_tools(), refresh_tool_name_desc(), and run(query).
- Tool Registry: A component (backed by the “data” subdirectory) that stores detailed information about the 211 available biomedical tools.
- Tool Implementations: Individual modules (openfda_tool, restful_tool, graphql_tool, etc.) that provide specific functionality. Include base_tool as the common abstraction layer.
- Utility Module: Support operations, parsing, data handling implemented in utils.py.
- External Data Sources: Although the project itself contains static data files, conceptually these serve as trusted biomedical data sources.

b. Relationships and Interactions:
- The API layer of ToolUniverse interacts with the Tool Registry (data directory) to fetch tool definitions.
- The API uses the specific tool implementations (e.g., restful, graphql, openfda) to execute queries based on the input command.
- Utility functions support both tool execution and data operations.
- There is an outward dependency where TxAgent or a client application calls the ToolUniverse API, gets tool metadata, and requests actions via run(query).

c. Architectural Patterns and Design Principles:
- Modular Design: Clear separation of concerns by isolating tool definitions, execution logic, and data.
- Abstraction: The base_tool module provides an abstraction for inheriting common functionality across various biomedical tools.
- Extensibility: The structure supports the addition of new tools (new modules can be introduced with similar interface structures and registered through the data layer).
- Data-Driven Architecture: The presence of JSON and Python-prepared data indicates a data-centric approach to tool registration.

d. Technologies, Frameworks, or Libraries:
- Python-based packaging (setup.cfg, pyproject.toml) suggests the use of build tools like setuptools or poetry.
- The usage of JSON for storing tool metadata.
- Potential integration with external biomedical databases or APIs (OpenFDA, GraphQL, RESTful endpoints).

## Diagram (Mermaid)

```mermaid
flowchart TD
    TxAgent("TxAgent/Consumer"):::external
    API("ToolUniverse API"):::api
    Registry("Tool Registry (Tool Data Storage)"):::data
    Base("Base Tool Abstraction"):::abstract
    Rest("RESTful Tool Module"):::tool
    GraphQL("GraphQL Tool Module"):::tool
    OpenFDA("OpenFDA Tool Module"):::tool
    ExecFn("Execute Function Utility"):::utility
    Utils("Utility Functions Module"):::utility

    TxAgent -->|"calls_API"| API
    API -->|"load_tools"| Registry
    API -->|"dispatch_tool"| Base
    Base -->|"executes_REST"| Rest
    Base -->|"executes_GraphQL"| GraphQL
    Base -->|"executes_OpenFDA"| OpenFDA
    API -->|"run_query"| ExecFn
    API -->|"util_functions"| Utils

    click API "https://github.com/mims-harvard/tooluniverse/blob/main/src/tooluniverse/__init__.py"
    click Base "https://github.com/mims-harvard/tooluniverse/blob/main/src/tooluniverse/base_tool.py"
    click Rest "https://github.com/mims-harvard/tooluniverse/blob/main/src/tooluniverse/restful_tool.py"
    click GraphQL "https://github.com/mims-harvard/tooluniverse/blob/main/src/tooluniverse/graphql_tool.py"
    click OpenFDA "https://github.com/mims-harvard/tooluniverse/blob/main/src/tooluniverse/openfda_tool.py"
    click ExecFn "https://github.com/mims-harvard/tooluniverse/blob/main/src/tooluniverse/execute_function.py"
    click Utils "https://github.com/mims-harvard/tooluniverse/blob/main/src/tooluniverse/utils.py"
    click Registry "https://github.com/mims-harvard/tooluniverse/tree/main/src/tooluniverse/data"

    classDef external fill:#ffcccc,stroke:#d33,stroke-width:2px;
    classDef api fill:#ccf,stroke:#33f,stroke-width:2px;
    classDef data fill:#fcf,stroke:#f3f,stroke-width:2px;
    classDef abstract fill:#cfc,stroke:#3c3,stroke-width:2px;
    classDef tool fill:#ffc,stroke:#cc0,stroke-width:2px;
    classDef utility fill:#cff,stroke:#3cf,stroke-width:2px;
```
