skills/mims-harvard__tooluniverse
1
0
Fork 0
mirror of https://github.com/mims-harvard/ToolUniverse.git synced 2026-09-19 07:31:47 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: expand redirect map (15 more paper-cited legacy paths) (#211)

Browse Source 
* docs: expand redirect map with 15 additional legacy paths

Adds redirects for paths uncovered in a second-pass audit against
the live published site. Each destination verified to return HTTP 200
on https://zitniklab.hms.harvard.edu/ToolUniverse/.

New /tutorials/ → /guide/, /tools/, /expand_tooluniverse/ redirects:
- make_your_data_searchable, make_your_data_agent_searchable,
  build_search_and_share_datastores → guide/make_your_data_agent_searchable
- skills → guide/skills_showcase
- tool_finder → guide/finding_tools
- overview → guide/index
- remote_tools → tools/remote_tools
- mcp_integration → expand_tooluniverse/remote_tools/mcp_integration

Top-level legacy pages (404 at root, now redirected):
- getting_started → guide/python_guide
- deployment, contributing, changelog → about/<page>
- faq → help/faq

Local build confirms all 22 redirect stubs generate and that every
destination file exists in the build output.

* docs: fix broken sphinx-tabs, dead toctrees, orphan pages, missing image

Build now produces 0 warnings/errors of these structural categories
(down from ~280 such issues):

- Re-enable sphinx_tabs.tabs extension (3.5.0 supports Sphinx 9.x);
  fixes 7 broken "Unknown directive type tabs" errors that made
  help/faq.html and help/troubleshooting.html render incomplete.
- Drop 25+ dead toctree entries in api/modules.rst and
  api/tooluniverse.rst that referenced per-module pages never
  generated by sphinx-apidoc; modules.rst now points at the existing
  comprehensive tooluniverse autodoc page.
- Wire 16 orphan pages into the master toctree so they're reachable
  from the navigation, including tooluniverse_case_study,
  visualization_tutorial, expert_feedback, literature_search_web_ui,
  euhealth, logging, openrouter, streaming, vllm, wechat_community,
  simbad_tools, the guide/index landing page, and the full
  expand_tooluniverse sub-tree.
- Remove three stale ":doc:" links to old/{quickstart,installation,
  getting_started} from sitemap.rst (those directories are excluded
  from the build) and mark sitemap.rst as :orphan: since it's a
  parallel nav surface by design.
- Mark MCP_TASKS_GUIDE.md as orphan and exclude the internal
  DOCUMENTATION_STRUCTURE.md meta-doc from the build.
- Add the missing tools/remote/ui.jpg referenced by the remote
  expert_feedback page (previously: broken image).

* docs: eliminate all 49 structural Sphinx ERRORs (broken tables, directives, headings)

Round-3 build cleanup. Builds now finish with 0 structural ERRORs of any
category (previous: 49 ERRORs spread across 20 files). Total
warnings/errors dropped from 280 → 114; the remaining 114 are all in
Python source-file docstrings (out of scope for a docs PR).

Categories fixed:

**Malformed tables** (8 files)

  Replace ASCII grid tables with mis-aligned pipes and inline-markdown
  pipe tables (which RST mis-parses as substitution references) with
  ``list-table`` directives that render correctly across all themes:

  - guide/literature_search_tools_tutorial.rst (two tables)
  - guide/cache_system.rst (env-var table whose first column overflowed)
  - guide/clinical_guidelines_tools.rst
  - guide/make_your_data_agent_searchable.rst
  - expand_tooluniverse/contributing/index.rst
  - expand_tooluniverse/contributing/remote_tools.rst
  - expand_tooluniverse/reference/index.rst

**list-table indentation** (3 files)

  Option lines and list items were indented with 1 space (only valid for
  3-space) so Sphinx silently dropped them and reported "exactly one
  bullet list expected":

  - guide/finding_tools.rst
  - guide/http_api.rst
  - guide/tools.rst

**Code-block separators** (5 files, ~30 directives)

  Add the required blank line between an introductory paragraph and a
  following ``.. code-block::``. Without it, Sphinx treated the directive
  as a continuation of the paragraph and emitted "Unexpected indentation"
  for every line of the code:

  - guide/literature_search_tools_tutorial.rst
  - expand_tooluniverse/quick_start.rst
  - expand_tooluniverse/contributing/local_tools.rst
  - expand_tooluniverse/contributing/remote_tools.rst
  - guide/make_your_data_agent_searchable.rst

**Heading-style + indentation** (3 files)

  - guide/building_ai_scientists/mcp_name_shortening.rst — strip stray
    leading spaces from two section titles + downgrade unknown
    ``.. critical::`` to ``.. important::``
  - about/deployment.rst — remove rogue ``=========`` underline below
    numbered-list items that mis-led the parser into skipping heading
    levels
  - guide/make_your_data_agent_searchable.rst — extend four "title
    underline too short" underlines + convert four markdown ``` fences
    to RST literal blocks

**Misc directive / target fixes**

  - guide/python_guide.rst — replace nonexistent ``.. success::`` with
    a tip-styled ``.. admonition::``
  - guide/euhealth_tools_tutorial.rst — indent ``.. note::`` body so it
    is no longer an empty admonition
  - help/troubleshooting.rst — same fix + remove rogue ``=========``
    line that was being read as a section overline
  - tools/cellosaurus_tools.rst — wrap ``CVCL_`` in literal backticks
    so the trailing underscore stops triggering missing-target lookups
  - expand_tooluniverse/index.rst — promote two leading-space bullet
    lists to standalone lists so the indentation is correct
  - expand_tooluniverse/reference/architecture.rst — switch ``.. graphviz::``
    (extension not installed) to a plain ``.. code-block:: text``;
    the embedded content was Mermaid pseudo-code anyway
  - guide/tools.rst — strip leading space on a section title

* docs: clear all remaining content warnings (lists, headings, refs, grids)

Round-4 build cleanup. Builds now finish with 0 structural ERRORs and 0
content WARNINGs; the only remaining ~11 warnings are pre-existing autodoc
infrastructure noise (duplicate object index entries from autosummary, and
the ghost_tool / medrxiv_tool modules that genuinely fail to import) — none
are in hand-written documentation.

Fixes in this commit:

**sphinx-design grids** (python_guide.rst)

  Re-indent two ``.. grid::`` blocks whose first card + options used 1-space
  indentation (Sphinx silently dropped them → "parent of grid-item should be
  grid-row"). Also fix a ``.. button-ref::`` whose content was indented 1
  space, producing a broken ``:any:`` cross-reference, and point it at the
  absolute ``/api/modules``.

**Numbered/bulleted sub-lists** (tool_composition, literature_search ×2,
architecture, literature_search_web_ui, make_your_data, agentic_tools,
finding_tools, euhealth)

  Insert the required blank line before nested lists and re-indent 1-space
  sub-bullets to align under their parent list marker. Clears ~80
  "list ends without a blank line; unexpected unindent" warnings.

**Title underlines** (logging, tool_caller, loading_tools, tool_composition,
euhealth, make_your_data, contributing/local_tools, reference/index,
remote_tools/tutorial, troubleshooting + bulk pass)

  Extend underlines shorter than their title text; strip stray leading spaces
  from section titles that Sphinx read as block quotes.

**Stray markdown in RST** (make_your_data, local_tools)

  Convert leftover ``###`` headings and ``` ``` fences to proper RST
  directives; remove a rogue ``------`` separator that was being parsed as a
  section underline.

**Duplicate autosectionlabel** (make_your_data)

  Rename the second "How it works" heading to "How sharing works".

**uniprot_tools** (JSON + generated RST)

  Rephrase the ``min_length`` / ``max_length`` descriptions so the open-ended
  range syntax no longer contains a bare ``*`` that RST read as an unterminated
  emphasis marker. Fixed in the JSON source so it survives doc regeneration.
This commit is contained in:
Shanghua Gao
2026-05-30 22:34:05 -07:00
committed by GitHub
parent 03c1bb6e9a
commit 08246bcd4d
41 changed files with 794 additions and 635 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/MCP_TASKS_GUIDE.md
+4
View File
@@ -1,3 +1,7 @@
---
orphan: true
---
# MCP Tasks: Async Operations in ToolUniverse
**Status**: Production Ready
docs/about/deployment.rst
+2 -2
View File
@@ -27,7 +27,7 @@ The repository includes GitHub Actions workflow for automatic deployment to GitH
**Setup Steps:**
1. Enable GitHub Pages in repository settings:
==============================================
- Go to repository **Settings > Pages**
- Set source to **GitHub Actions**
@@ -61,7 +61,7 @@ Automated Setup
~~~~~~~~~~~~~~~
1. Connect repository to ReadTheDocs:
=====================================
- Visit https://readthedocs.org/
- Import repository
- Configure webhook (automatic)
docs/api/modules.rst
-60
View File
@@ -3,67 +3,7 @@ API Reference
This section provides the complete Python API reference for ToolUniverse.
Core Infrastructure
-------------------
.. toctree::
:maxdepth: 2
tooluniverse
tooluniverse.execute_function
Core Classes & Utilities
------------------------
.. toctree::
:maxdepth: 2
tooluniverse.base_tool
tooluniverse.core_tool
tooluniverse.exceptions
tooluniverse.tool_registry
tooluniverse.logging_config
tooluniverse.utils
tooluniverse.default_config
Important Tools
---------------
.. toctree::
:maxdepth: 2
tooluniverse.agentic_tool
tooluniverse.remote_tool
tooluniverse.compose_tool
Tool Finders
------------
.. toctree::
:maxdepth: 2
tooluniverse.tool_finder_embedding
tooluniverse.tool_finder_keyword
tooluniverse.tool_finder_llm
MCP Support
-----------
.. toctree::
:maxdepth: 2
tooluniverse.smcp
tooluniverse.smcp_server
tooluniverse.mcp_client_tool
tooluniverse.mcp_integration
tooluniverse.mcp_tool_registry
Embedding & Output Management
-----------------------------
.. toctree::
:maxdepth: 2
tooluniverse.embedding_database
tooluniverse.embedding_sync
tooluniverse.output_hook
docs/api/tooluniverse.rst
-13
View File
@@ -7,19 +7,6 @@ tooluniverse package
:show-inheritance:
:private-members:
Subpackages
-----------
.. toctree::
:maxdepth: 4
tooluniverse.cache
tooluniverse.compose_scripts
tooluniverse.data
tooluniverse.database_setup
tooluniverse.profile
tooluniverse.tools
Submodules
----------
docs/conf.py
+23 -3
View File
@@ -26,7 +26,7 @@ extensions = [
"sphinx.ext.autosectionlabel",
"myst_parser",
"sphinx_copybutton",
# "sphinx_tabs.tabs", # Temporarily disabled due to Sphinx 9.x compatibility issue
"sphinx_tabs.tabs",
"sphinx_design",
# "notfound.extension", # Temporarily disabled due to theme compatibility issue
"sphinx_reredirects",
@@ -34,9 +34,11 @@ extensions = [
# HTML redirects for paths that moved during a docs reshuffle.
# Old path → new path. The ToolUniverse paper and external blog posts cite
# /tutorials/<name>.html URLs from before the docs were reorganised under
# /guide/. Without these redirects, every cited URL 404s.
# legacy URLs from before the docs were reorganised. Without these redirects
# every cited URL 404s. Each entry was verified against the live site:
# the destination must already return HTTP 200.
redirects = {
# /tutorials/* → /guide/*
"tutorials/tooluniverse_case_study": "../guide/tooluniverse_case_study.html",
"tutorials/agentic_tools_tutorial": "../guide/agentic_tools_tutorial.html",
"tutorials/literature_search_tools_tutorial": "../guide/literature_search_tools_tutorial.html",
@@ -44,6 +46,21 @@ redirects = {
"tutorials/visualization_tutorial": "../guide/visualization_tutorial.html",
"tutorials/expert_feedback": "../guide/expert_feedback.html",
"tutorials/finding_tools": "../guide/finding_tools.html",
"tutorials/make_your_data_searchable": "../guide/make_your_data_agent_searchable.html",
"tutorials/make_your_data_agent_searchable": "../guide/make_your_data_agent_searchable.html",
"tutorials/build_search_and_share_datastores": "../guide/make_your_data_agent_searchable.html",
"tutorials/skills": "../guide/skills_showcase.html",
"tutorials/tool_finder": "../guide/finding_tools.html",
"tutorials/overview": "../guide/index.html",
# /tutorials/* → /tools/* and /expand_tooluniverse/*
"tutorials/remote_tools": "../tools/remote_tools.html",
"tutorials/mcp_integration": "../expand_tooluniverse/remote_tools/mcp_integration.html",
# Top-level pages whose content moved into /about/ or /help/
"getting_started": "guide/python_guide.html",
"deployment": "about/deployment.html",
"contributing": "about/contributing.html",
"changelog": "about/changelog.html",
"faq": "help/faq.html",
}
templates_path = ["_templates"]
@@ -59,6 +76,9 @@ exclude_patterns = [
"tutorials/overview.md",
"tutorials/optimization",
"guide/ODPHPtools_tutorial.md",
# Internal meta-docs describing the folder structure or task list.
# Not user-facing; kept in-tree as a developer reference only.
"DOCUMENTATION_STRUCTURE.md",
]
# -- Options for HTML output with Shibuya theme -----------------------------
docs/expand_tooluniverse/architecture.rst
+38 -29
View File
@@ -179,19 +179,22 @@ Core Components
**Engine & Registry**
- `execute_function.py`: Core `ToolUniverse` engine class responsible for:
- Reading tool configurations (local JSON, default configs) and building `all_tools`/`all_tool_dict`
- Mapping tool types to concrete classes (`tool_type_mappings`) and instantiation
- Tool execution routing (`run_tool`), validation, and result processing
- Handling MCP auto-loaders, temporary clients (with `mcp_integration.py`)
- Reading tool configurations (local JSON, default configs) and building `all_tools`/`all_tool_dict`
- Mapping tool types to concrete classes (`tool_type_mappings`) and instantiation
- Tool execution routing (`run_tool`), validation, and result processing
- Handling MCP auto-loaders, temporary clients (with `mcp_integration.py`)
- `base_tool.py`: `BaseTool` base class and exception types. Supports:
- Loading default configurations from `tooluniverse.data` package
- Parameter validation, required parameter extraction, function call validation
- Loading default configurations from `tooluniverse.data` package
- Parameter validation, required parameter extraction, function call validation
- `tool_registry.py`: Tool registration and discovery:
- `@register_tool` decorator for registering tool classes
- Lazy loading registry (on-demand module imports) and full discovery
- Smart matching of configuration JSON to modules and tool types
- `@register_tool` decorator for registering tool classes
- Lazy loading registry (on-demand module imports) and full discovery
- Smart matching of configuration JSON to modules and tool types
- `default_config.py`: Default tool configuration file list
- `logging_config.py`, `utils.py`: Logging setup and utility functions
@@ -220,39 +223,45 @@ Available tool classes (alphabetically organized):
**External Ecosystem & Extension Examples**
- `remote/`: External system integrations including:
- `expert_feedback/`: Human expert feedback system
- `expert_feedback_mcp/`: MCP-enabled expert feedback
- `boltz/`: Boltz protein folding integration
- `depmap_24q2/`: DepMap cancer dependency data integration
- `immune_compass/`: Immune system analysis tools
- `pinnacle/`: Pinnacle platform integration
- `transcriptformer/`: Transcriptformer model integration
- `uspto_downloader/`: USPTO patent downloader service
- `expert_feedback/`: Human expert feedback system
- `expert_feedback_mcp/`: MCP-enabled expert feedback
- `boltz/`: Boltz protein folding integration
- `depmap_24q2/`: DepMap cancer dependency data integration
- `immune_compass/`: Immune system analysis tools
- `pinnacle/`: Pinnacle platform integration
- `transcriptformer/`: Transcriptformer model integration
- `uspto_downloader/`: USPTO patent downloader service
Execution Flow (Configuration to Invocation)
---------------------------------------------
1. **Configuration Loading**
- Engine startup reads `default_tool_files` and `data/*.json` to build tool manifest
- Each JSON entry defines a tool instance: `name`, `type`, `description`, `parameter` (JSON Schema), endpoints, etc.
- Engine startup reads `default_tool_files` and `data/*.json` to build tool manifest
- Each JSON entry defines a tool instance: `name`, `type`, `description`, `parameter` (JSON Schema), endpoints, etc.
2. **Tool Registration & Mapping**
- `tool_registry.py` maintains "tool type → tool class" mappings
- Supports both full import discovery and lazy loading mappings (smart config-to-module matching)
- `tool_registry.py` maintains "tool type → tool class" mappings
- Supports both full import discovery and lazy loading mappings (smart config-to-module matching)
3. **Instantiation & Default Configuration**
- Based on `type`, finds corresponding class (e.g., `FDADrugLabelTool`)
- Merges `BaseTool` default configurations with entry-specific config
- Based on `type`, finds corresponding class (e.g., `FDADrugLabelTool`)
- Merges `BaseTool` default configurations with entry-specific config
4. **Execution & Validation**
- `ToolUniverse.tools.tool_name(**params)`:
- Locate instance by name → Parameter validation (required fields) → Call concrete implementation
- Unified error handling and return structure
- `ToolUniverse.tools.tool_name(**params)`:
- Locate instance by name → Parameter validation (required fields) → Call concrete implementation
- Unified error handling and return structure
5. **Composition/Discovery & Graphs**
- Use `compose_tool.py` or `compose_scripts/` for orchestration
- Leverage `tool_finder_*` (keyword/embedding/LLM) for tool retrieval
- Visualize tool relationships and call chains via scripts or `tool_graph_web_ui.py`
- Use `compose_tool.py` or `compose_scripts/` for orchestration
- Leverage `tool_finder_*` (keyword/embedding/LLM) for tool retrieval
- Visualize tool relationships and call chains via scripts or `tool_graph_web_ui.py`
MCP Integration
---------------
docs/expand_tooluniverse/contributing/index.rst
+22 -7
View File
@@ -6,13 +6,28 @@ Welcome! Choose the type of tool you want to contribute and follow the detailed
Choose Your Tool Type
---------------------
| Feature | Local Tools | Remote Tools |
|---------|-------------|--------------|
| **Runs** | In ToolUniverse process | Independent server |
| **Language** | Python only | Any language |
| **Setup** | Modify __init__.py in 4 locations | Deploy server publicly |
| **Testing** | Unit tests (>90% coverage) | Integration tests |
| **Best For** | API wrappers, data processing | Heavy computation, external services |
.. list-table::
:header-rows: 1
:widths: 20 40 40
* - Feature
- Local Tools
- Remote Tools
* - **Runs**
- In ToolUniverse process
- Independent server
* - **Language**
- Python only
- Any language
* - **Setup**
- Modify ``__init__.py`` in 4 locations
- Deploy server publicly
* - **Testing**
- Unit tests (>90% coverage)
- Integration tests
* - **Best For**
- API wrappers, data processing
- Heavy computation, external services
**Quick Decision Guide:**
docs/expand_tooluniverse/contributing/local_tools.rst
+3 -2
View File
@@ -134,7 +134,7 @@ Create or edit ``src/tooluniverse/data/xxx_tools.json``:
]
Step 5: No Modifications Needed in __init__.py!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
With the new automated discovery system, **you do NOT need to modify `src/tooluniverse/__init__.py`**.
@@ -180,6 +180,7 @@ Create tests in ``tests/unit/test_my_new_tool.py``:
assert result["result"] == ""
Run tests with coverage:
.. code-block:: bash
pytest tests/unit/test_my_new_tool.py --cov=tooluniverse --cov-report=html
@@ -222,7 +223,6 @@ Add comprehensive docstrings to your tool class:
>>> print(result["result"])
HELLO
"""
```
Step 9: Create Examples
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -321,6 +321,7 @@ Step 10: Submit Pull Request
git push origin feature/add-my-new-tool
**PR Template:**
.. code-block:: markdown
## Description
docs/expand_tooluniverse/contributing/remote_tools.rst
+32 -8
View File
@@ -65,6 +65,7 @@ Step 3: Create MCP Server
Create server directory: ``src/tooluniverse/remote/my_service/``
**Server Structure:**
.. code-block:: text
src/tooluniverse/remote/my_service/
@@ -76,6 +77,7 @@ Create server directory: ``src/tooluniverse/remote/my_service/``
└── docker-compose.yml # Optional: Docker setup
**Example server.py:**
.. code-block:: python
from fastapi import FastAPI
@@ -113,6 +115,7 @@ Create server directory: ``src/tooluniverse/remote/my_service/``
uvicorn.run(app, host="0.0.0.0", port=8000)
**requirements.txt:**
.. code-block:: text
fastapi>=0.100.0
@@ -182,6 +185,7 @@ Step 5: Deploy Server
- Document requirements and dependencies
**Example deployment documentation (README.md):**
.. code-block:: markdown
# My Service MCP Server
@@ -285,6 +289,7 @@ Create ``tests/integration/test_my_remote_tool.py``:
assert "my_remote_tool" in self.tu.all_tool_dict
Run tests:
.. code-block:: bash
pytest tests/integration/test_my_remote_tool.py -v
@@ -304,6 +309,7 @@ Step 8: Documentation
~~~~~~~~~~~~~~~~~~~~~
**Server Documentation (README.md):**
.. code-block:: markdown
# My Service
@@ -401,6 +407,7 @@ Step 10: Submit Pull Request
git push origin feature/add-my-remote-tool
**PR Template:**
.. code-block:: markdown
## Description
@@ -445,14 +452,31 @@ Step 10: Submit Pull Request
Key Differences from Local Tools
---------------------------------
| Aspect | Local Tools | Remote Tools |
|--------|-------------|--------------|
| **__init__.py** | Must modify 4 locations | No modification needed |
| **File Location** | ``src/tooluniverse/xxx_tool.py`` | ``src/tooluniverse/remote/xxx/`` |
| **Config Location** | ``data/xxx_tools.json`` | ``data/remote_tools/xxx_tools.json`` |
| **Server Deployment** | Not needed | Must provide public access |
| **Testing** | Unit tests | Integration tests (mock server) |
| **Dependencies** | Python only | Server + dependencies |
.. list-table::
:header-rows: 1
:widths: 22 39 39
* - Aspect
- Local Tools
- Remote Tools
* - **__init__.py**
- Must modify 4 locations
- No modification needed
* - **File Location**
- ``src/tooluniverse/xxx_tool.py``
- ``src/tooluniverse/remote/xxx/``
* - **Config Location**
- ``data/xxx_tools.json``
- ``data/remote_tools/xxx_tools.json``
* - **Server Deployment**
- Not needed
- Must provide public access
* - **Testing**
- Unit tests
- Integration tests (mock server)
* - **Dependencies**
- Python only
- Server + dependencies
Common Mistakes
----------------
docs/expand_tooluniverse/index.rst
+41 -22
View File
@@ -20,15 +20,17 @@ Quick Start
**I want to learn tool development systematically:**
→ Choose your path:
- **Local tools**: :doc:`local_tools/local_tools_tutorial` - Python classes for API wrappers, data processing
- **Async tools**: :doc:`async_tools_guide` - Long-running operations with automatic polling
- **Remote tools**: :doc:`remote_tools/tutorial` - MCP servers for microservices, heavy computation
- **Local tools**: :doc:`local_tools/local_tools_tutorial` - Python classes for API wrappers, data processing
- **Async tools**: :doc:`async_tools_guide` - Long-running operations with automatic polling
- **Remote tools**: :doc:`remote_tools/tutorial` - MCP servers for microservices, heavy computation
**I want to contribute tools to the community:**
→ Choose your tool type:
- **Local tools**: :doc:`contributing/local_tools` - Submit Python tools (requires modifying ``__init__.py``)
- **Remote tools**: :doc:`contributing/remote_tools` - Submit MCP servers (requires deployment)
- **Complete guide**: :doc:`contributing/index` - Full contribution guidelines with code examples
- **Local tools**: :doc:`contributing/local_tools` - Submit Python tools (requires modifying ``__init__.py``)
- **Remote tools**: :doc:`contributing/remote_tools` - Submit MCP servers (requires deployment)
- **Complete guide**: :doc:`contributing/index` - Full contribution guidelines with code examples
**I want to understand the differences:**
→ :doc:`reference/index` - Compare tool types and usage scenarios
@@ -75,29 +77,34 @@ Development Workflow
--------------------
1. **Plan Your Tool**
- Define functionality and requirements
- Choose between local or remote implementation
- Design API and parameter structure
- Define functionality and requirements
- Choose between local or remote implementation
- Design API and parameter structure
2. **Develop Your Tool**
- Implement core functionality
- Add proper error handling
- Write comprehensive tests
- Implement core functionality
- Add proper error handling
- Write comprehensive tests
3. **Document Your Tool**
- Create clear documentation
- Provide usage examples
- Document all parameters and outputs
- Create clear documentation
- Provide usage examples
- Document all parameters and outputs
4. **Test Thoroughly**
- Unit tests for all functionality
- Integration tests with ToolUniverse
- Test edge cases and error conditions
- Unit tests for all functionality
- Integration tests with ToolUniverse
- Test edge cases and error conditions
5. **Submit for Review** (if contributing)
- Follow contribution guidelines
- Create pull request
- Address review feedback
- Follow contribution guidelines
- Create pull request
- Address review feedback
Examples
--------
@@ -130,4 +137,16 @@ Ready to start? Choose your path:
* **Understanding**: Review the tool type comparison table in :doc:`contributing/index`
.. tip::
**Getting Started**: We recommend starting with the quick start tutorial to understand the basics, then choosing the appropriate detailed guide based on your needs. The community is here to help you succeed!
**Getting Started**: We recommend starting with the quick start tutorial to understand the basics, then choosing the appropriate detailed guide based on your needs. The community is here to help you succeed!
.. toctree::
:hidden:
:maxdepth: 2
quick_start
local_tools/index
remote_tools/index
contributing/index
reference/index
async_tools_guide
architecture
docs/expand_tooluniverse/quick_start.rst
+1
View File
@@ -114,6 +114,7 @@ Create ``main.py`` in the same directory:
python main.py
**Expected Output:**
.. code-block:: text
Text Processing Results:
docs/expand_tooluniverse/reference/architecture.rst
+4 -4
View File
@@ -10,19 +10,19 @@ ToolUniverse is built around a modular, registry-based architecture that support
**Core Components:**
.. graphviz::
.. code-block:: text
graph TD
A[ToolUniverse] --> B[Tool Registry]
A --> C[MCP Tool Registry]
A --> D[Tool Executor]
B --> E[Local Tools]
C --> F[Remote Tools]
E --> G[BaseTool Classes]
F --> H[MCP Servers]
D --> I[Parameter Validation]
D --> J[Error Handling]
D --> K[Result Processing]
docs/expand_tooluniverse/reference/index.rst
+26 -9
View File
@@ -24,14 +24,31 @@ Understanding the differences between local and remote tools helps you choose th
**Key Differences:**
| Aspect | Local Tools | Remote Tools |
|--------|-------------|--------------|
| **Performance** | High (no network overhead) | Lower (network latency) |
| **Development** | Simple Python classes | MCP servers or API wrappers |
| **Deployment** | Part of ToolUniverse | Independent servers |
| **Scalability** | Limited by process | Highly scalable |
| **Integration** | Full ToolUniverse access | Limited to MCP/API |
| **Contribution** | Requires ``__init__.py`` changes | No code changes needed |
.. list-table::
:header-rows: 1
:widths: 22 39 39
* - Aspect
- Local Tools
- Remote Tools
* - **Performance**
- High (no network overhead)
- Lower (network latency)
* - **Development**
- Simple Python classes
- MCP servers or API wrappers
* - **Deployment**
- Part of ToolUniverse
- Independent servers
* - **Scalability**
- Limited by process
- Highly scalable
* - **Integration**
- Full ToolUniverse access
- Limited to MCP/API
* - **Contribution**
- Requires ``__init__.py`` changes
- No code changes needed
**When to Use Local Tools:**
- Data processing and analysis
@@ -46,7 +63,7 @@ Understanding the differences between local and remote tools helps you choose th
- Tools in different programming languages
Architecture Details
-------------------
--------------------
**ToolUniverse Core Components:**
- **Tool Registry**: Manages tool discovery and registration
docs/expand_tooluniverse/remote_tools/tutorial.rst
+1 -1
View File
@@ -319,7 +319,7 @@ Complete working examples are available in the `examples/remote_tools/` director
cd examples/remote_tools
python create_remote_tool.py # In one terminal
python use_remote_tool.py # In another terminal
```
```````````````````````````````````````````````````
Next Steps
----------
docs/guide/agentic_tools_tutorial.rst
+3 -2
View File
@@ -187,8 +187,9 @@ Set up AI model settings:
- ``api_type``: "CHATGPT", "GEMINI", "OPENROUTER", or "VLLM"
- ``model_id``: Choose your model (see Step 2)
- For vLLM: Must match the model name loaded on your vLLM server
- Set ``VLLM_SERVER_URL`` environment variable when using vLLM
- For vLLM: Must match the model name loaded on your vLLM server
- Set ``VLLM_SERVER_URL`` environment variable when using vLLM
- ``temperature``: 0.0-2.0 (higher = more creative)
- ``return_json``: true for structured data, false for text
docs/guide/building_ai_scientists/mcp_name_shortening.rst
+7 -7
View File
@@ -83,8 +83,8 @@ Examples
When to Use This Feature
=========================
USE in These Scenarios
--------------------------
USE in These Scenarios
----------------------
MCP Integration (Automatic)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -147,8 +147,8 @@ External API Integration with Length Constraints
When NOT to Use This Feature
=============================
DO NOT USE in These Scenarios
---------------------------------
DO NOT USE in These Scenarios
-----------------------------
Direct Python API Usage (Default)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -439,7 +439,7 @@ For MCP Users
}
}
.. critical::
.. important::
Change the JSON key from ``"tooluniverse"`` to ``"tu"`` in your configuration!
For Python API Users
@@ -523,7 +523,7 @@ Key Takeaways
4. **Simple implementation** - 380 lines, well-tested
5. **Production ready** - All tests passing, validated with real tools
When to Use
When to Use
--------------
- **MCP integration** (automatic)
@@ -531,7 +531,7 @@ Key Takeaways
- **External systems with name length limits**
- **Testing and validation**
When NOT to Use
When NOT to Use
------------------
- **Direct Python API** (no constraints)
docs/guide/cache_system.rst
+36 -20
View File
@@ -105,19 +105,28 @@ Configuration
Use environment variables to tune cache behavior before creating a
``ToolUniverse`` instance:
=============================== ==============================================
Variable Description
=============================== ==============================================
``TOOLUNIVERSE_CACHE_ENABLED`` Turn caching on/off (``true`` by default)
``TOOLUNIVERSE_CACHE_PERSIST`` Enable SQLite persistence (``true`` by default)
``TOOLUNIVERSE_CACHE_PATH`` Full path to the SQLite file
``TOOLUNIVERSE_CACHE_DIR`` Directory for the SQLite file (default:
``~/.tooluniverse``) if ``CACHE_PATH`` unset
``TOOLUNIVERSE_CACHE_MEMORY_SIZE`` Max entries in the in-memory LRU (default 256)
``TOOLUNIVERSE_CACHE_DEFAULT_TTL`` Expiration in seconds (None disables TTL)
``TOOLUNIVERSE_CACHE_SINGLEFLIGHT`` Deduplicate concurrent misses (``true``)
``TOOLUNIVERSE_CACHE_ASYNC_PERSIST`` Write cache entries to SQLite on a background thread (``true``)
=============================== ==============================================
.. list-table::
:header-rows: 1
:widths: 40 60
* - Variable
- Description
* - ``TOOLUNIVERSE_CACHE_ENABLED``
- Turn caching on/off (``true`` by default)
* - ``TOOLUNIVERSE_CACHE_PERSIST``
- Enable SQLite persistence (``true`` by default)
* - ``TOOLUNIVERSE_CACHE_PATH``
- Full path to the SQLite file
* - ``TOOLUNIVERSE_CACHE_DIR``
- Directory for the SQLite file (default: ``~/.tooluniverse``) if ``CACHE_PATH`` unset
* - ``TOOLUNIVERSE_CACHE_MEMORY_SIZE``
- Max entries in the in-memory LRU (default 256)
* - ``TOOLUNIVERSE_CACHE_DEFAULT_TTL``
- Expiration in seconds (None disables TTL)
* - ``TOOLUNIVERSE_CACHE_SINGLEFLIGHT``
- Deduplicate concurrent misses (``true``)
* - ``TOOLUNIVERSE_CACHE_ASYNC_PERSIST``
- Write cache entries to SQLite on a background thread (``true``)
.. seealso::
:doc:`../reference/environment_variables` for complete environment variable reference including logging, LLM, and other configuration options.
@@ -198,11 +207,18 @@ Best Practices
* Call ``tu.clear_cache()`` in long-running services if you need a fresh start.
* For hands-on demos, run ``examples/cache_usage_example.py`` (basic walkthrough)
or ``examples/cache_stress_test.py`` (randomized load test with summary stats).
.. code-block:: json
{
"name": "SlowTool",
"type": "SlowTool",
"batch_max_concurrency": 2,
"parameter": {"type": "object", "properties": {}}
}
Per-tool Concurrency
--------------------
Set ``batch_max_concurrency`` in a tool config to cap how many concurrent
executions of that tool run during batch jobs:
.. code-block:: json
{
"name": "SlowTool",
"type": "SlowTool",
"batch_max_concurrency": 2,
"parameter": {"type": "object", "properties": {}}
}
docs/guide/clinical_guidelines_tools.rst
+25 -15
View File
@@ -50,21 +50,31 @@ Quick Start
Tool Comparison
---------------
+---------------------------+----------------------------------+---------------------------------------+
| Tool | Data Source | Features |
+===========================+==================================+=======================================+
| NICE_Clinical_Guidelines | UK NICE official website | Official UK guidelines with summaries |
+---------------------------+----------------------------------+---------------------------------------+
| WHO_Guidelines | WHO publications database | International health guidelines |
+---------------------------+----------------------------------+---------------------------------------+
| PubMed_Guidelines | NCBI PubMed database | Peer-reviewed with abstracts & PMIDs |
+---------------------------+----------------------------------+---------------------------------------+
| EuropePMC_Guidelines | Europe PMC database | European & international research |
+---------------------------+----------------------------------+---------------------------------------+
| TRIP_Database | TRIP evidence database | Evidence-based medicine focus |
+---------------------------+----------------------------------+---------------------------------------+
| OpenAlex_Guidelines | OpenAlex scholarly database | Comprehensive with citation counts |
+---------------------------+----------------------------------+---------------------------------------+
.. list-table::
:header-rows: 1
:widths: 30 30 40
* - Tool
- Data Source
- Features
* - ``NICE_Clinical_Guidelines``
- UK NICE official website
- Official UK guidelines with summaries
* - ``WHO_Guidelines``
- WHO publications database
- International health guidelines
* - ``PubMed_Guidelines``
- NCBI PubMed database
- Peer-reviewed with abstracts & PMIDs
* - ``EuropePMC_Guidelines``
- Europe PMC database
- European & international research
* - ``TRIP_Database``
- TRIP evidence database
- Evidence-based medicine focus
* - ``OpenAlex_Guidelines``
- OpenAlex scholarly database
- Comprehensive with citation counts
Usage Examples
--------------
docs/guide/euhealth_tools_tutorial.rst
+5 -5
View File
@@ -1,5 +1,5 @@
EUHealth tools: find and explore EU public-health datasets
=========================================================
==========================================================
Use these tools to:
@@ -116,7 +116,7 @@ You should see a few JSON results (uuid, title, landing_page, etc.).
(Inside the agent you’ll get nicely formatted results. This is just a quick check.)
**That's it!!**
---
---------------
Advanced:
---------
@@ -256,7 +256,7 @@ Common questions
If not, use the **Quick start** download or the **Build it yourself** step.
* **Why did embedding fall back to keyword?**
Either the Codex MCP config (above) isn't set, or your environment doesn't have Azure + text-embedding-3-small configured. Add the config block to `~/.codex/config.toml` and restart Codex to enable embedding search.
Either the Codex MCP config (above) isn't set, or your environment doesn't have Azure + text-embedding-3-small configured. Add the config block to `~/.codex/config.toml` and restart Codex to enable embedding search.
* **Where does my data upload now?**
When you run `tu-datastore sync-hf upload --collection euhealth`, ToolUniverse automatically detects your `HF_TOKEN` and uploads to **your own Hugging Face namespace** (`your_username/euhealth`).
@@ -276,5 +276,5 @@ If you later want the nitty-gritty (how we crawl, embed, index), see the develop
.. note::
Want to build or share your **own** searchable dataset or tool (like EUHealth)?
See: :doc:`make_your_data_agent_searchable` - the 3-minute guide to creating and publishing your own ToolUniverse datastore.
Want to build or share your **own** searchable dataset or tool (like EUHealth)?
See: :doc:`make_your_data_agent_searchable` - the 3-minute guide to creating and publishing your own ToolUniverse datastore.
docs/guide/finding_tools.rst
+23 -22
View File
@@ -30,25 +30,25 @@ Strategic Trade-offs
Each method offers different advantages:
.. list-table:: Tool Finder Comparison
:header-rows: 1
:widths: 20 25 25 25
:header-rows: 1
:widths: 20 25 25 25
* - Method
- Speed
- Semantic Understanding
- Resource Usage
* - **Keyword Search**
- Very Fast
- Basic
- Very Low
* - **LLM Search**
- Moderate
- Excellent
- High
* - **Embedding Search**
- Fast
- Good
- Moderate
* - Method
- Speed
- Semantic Understanding
- Resource Usage
* - **Keyword Search**
- Very Fast
- Basic
- Very Low
* - **LLM Search**
- Moderate
- Excellent
- High
* - **Embedding Search**
- Fast
- Good
- Moderate
When to Use Each Method
------------------------
@@ -80,10 +80,11 @@ How Keyword Search Works
Keyword search uses a sophisticated text processing pipeline:
1. **Query Processing**:
- Tokenization via regular expressions
- Removal of 45+ common English stop words
- Suffix-based stemming using 20 morphological rules
- Generation of n-grams (bigrams and trigrams)
- Tokenization via regular expressions
- Removal of 45+ common English stop words
- Suffix-based stemming using 20 morphological rules
- Generation of n-grams (bigrams and trigrams)
2. **Relevance Scoring**:
docs/guide/http_api.rst
+30 -30
View File
@@ -152,37 +152,37 @@ API Endpoints
The server exposes the following REST endpoints:
.. list-table:: API Endpoints Reference
:header-rows: 1
:widths: 20 10 40 30
:header-rows: 1
:widths: 20 10 40 30
* - Endpoint
- Method
- Purpose
- Client Usage
* - ``/health``
- GET
- Server health check
- ``client.health_check()``
* - ``/api/methods``
- GET
- List all ToolUniverse methods
- ``client.list_available_methods()``
* - ``/api/call``
- POST
- Call any ToolUniverse method
- ``client.method_name(**kwargs)``
* - ``/api/reset``
- POST
- Reset ToolUniverse instance
- ``client.reset_server(config)``
* - ``/docs``
- GET
- Interactive Swagger UI docs
- Open in browser
* - ``/redoc``
- GET
- Alternative ReDoc docs
- Open in browser
* - Endpoint
- Method
- Purpose
- Client Usage
* - ``/health``
- GET
- Server health check
- ``client.health_check()``
* - ``/api/methods``
- GET
- List all ToolUniverse methods
- ``client.list_available_methods()``
* - ``/api/call``
- POST
- Call any ToolUniverse method
- ``client.method_name(**kwargs)``
* - ``/api/reset``
- POST
- Reset ToolUniverse instance
- ``client.reset_server(config)``
* - ``/docs``
- GET
- Interactive Swagger UI docs
- Open in browser
* - ``/redoc``
- GET
- Alternative ReDoc docs
- Open in browser
**Key distinction:**
docs/guide/literature_search_tools_tutorial.rst
+158 -108
View File
@@ -32,56 +32,62 @@ ToolUniverse provides 15 powerful literature search tools that cover different a
Tool Overview Table
~~~~~~~~~~~~~~~~~~~
+------------------+------------------+------------------+------------------+
| Tool Name | Database | Best For | Key Features |
+==================+==================+==================+==================+
| ArXiv_search_ | ArXiv | Preprints | Physics, Math, |
| papers | | | CS, Biology |
+------------------+------------------+------------------+------------------+
| Crossref_search_ | Crossref | Scholarly | DOI metadata, |
| works | | Articles | Rich metadata, |
| | | | HTML cleaning |
+------------------+------------------+------------------+------------------+
| PubMed_search_ | PubMed | Medical/Life | Medical |
| articles | | Sciences | literature, |
| | | | MeSH keywords |
+------------------+------------------+------------------+------------------+
| SemanticScholar_ | Semantic Scholar | AI-powered | AI ranking, |
| search_papers | | Search | Citations, |
| | | | Rate limit |
| | | | handling |
+------------------+------------------+------------------+------------------+
| openalex_ | OpenAlex | Comprehensive | Open access, |
| literature_ | | Academic | Year filtering, |
| search | | Search | Abstract |
| | | | reconstruction |
+------------------+------------------+------------------+------------------+
| EuropePMC_ | Europe PMC | Biomedical | European |
| search_articles | | Literature | research, |
| | | | Core+Lite modes |
+------------------+------------------+------------------+------------------+
| DBLP_search_ | DBLP | Computer | CS bibliography, |
| publications | | Science | Conference |
| | | | papers |
+------------------+------------------+------------------+------------------+
| DOAJ_search_ | DOAJ | Open Access | Articles & |
| articles | | | Journals, |
| | | | HTML cleaning |
+------------------+------------------+------------------+------------------+
| BioRxiv_search_ | BioRxiv | Biology | Biology |
| preprints | | Preprints | preprints, |
| | | | Abstracts |
+------------------+------------------+------------------+------------------+
| MedRxiv_search_ | MedRxiv | Medical | Medical |
| preprints | | Preprints | preprints, |
| | | | Abstracts |
+------------------+------------------+------------------+------------------+
| HAL_search_ | HAL | French Research | French academic |
| archive | | Archive | papers |
+------------------+------------------+------------------+------------------+
| Unpaywall_ | Unpaywall | Open Access | OA status |
| check_oa_status | | Status | checking |
+------------------+------------------+------------------+------------------+
.. list-table::
:header-rows: 1
:widths: 28 18 22 32
* - Tool Name
- Database
- Best For
- Key Features
* - ``ArXiv_search_papers``
- ArXiv
- Preprints
- Physics, Math, CS, Biology
* - ``Crossref_search_works``
- Crossref
- Scholarly Articles
- DOI metadata, Rich metadata, HTML cleaning
* - ``PubMed_search_articles``
- PubMed
- Medical/Life Sciences
- Medical literature, MeSH keywords
* - ``SemanticScholar_search_papers``
- Semantic Scholar
- AI-powered Search
- AI ranking, Citations, Rate limit handling
* - ``openalex_literature_search``
- OpenAlex
- Comprehensive Academic Search
- Open access, Year filtering, Abstract reconstruction
* - ``EuropePMC_search_articles``
- Europe PMC
- Biomedical Literature
- European research, Core+Lite modes
* - ``DBLP_search_publications``
- DBLP
- Computer Science
- CS bibliography, Conference papers
* - ``DOAJ_search_articles``
- DOAJ
- Open Access
- Articles & Journals, HTML cleaning
* - ``BioRxiv_search_preprints``
- BioRxiv
- Biology Preprints
- Biology preprints, Abstracts
* - ``MedRxiv_search_preprints``
- MedRxiv
- Medical Preprints
- Medical preprints, Abstracts
* - ``HAL_search_archive``
- HAL
- French Research Archive
- French academic papers
* - ``Unpaywall_check_oa_status``
- Unpaywall
- Open Access Status
- OA status checking
Enhanced Features
------------------
@@ -152,7 +158,7 @@ First, let's initialize ToolUniverse and load the literature search tools:
print(f"- {tool}")
Basic Usage Pattern
------------------
-------------------
All literature search tools follow a similar usage pattern:
@@ -510,30 +516,35 @@ Best Practices
--------------
1. **Choose the Right Tool:**
- Use ArXiv for preprints in physics, math, CS
- Use PubMed for medical/life sciences
- Use Semantic Scholar for AI-powered ranking
- Use OpenAlex for comprehensive academic search
- Use ArXiv for preprints in physics, math, CS
- Use PubMed for medical/life sciences
- Use Semantic Scholar for AI-powered ranking
- Use OpenAlex for comprehensive academic search
2. **Optimize Your Queries:**
- Use specific, relevant keywords
- Combine terms with appropriate operators
- Use filters to narrow results
- Use specific, relevant keywords
- Combine terms with appropriate operators
- Use filters to narrow results
3. **Handle Rate Limits:**
- Some APIs have rate limits
- Implement delays between requests if needed
- Use error handling for 429 (Too Many Requests) errors
- Some APIs have rate limits
- Implement delays between requests if needed
- Use error handling for 429 (Too Many Requests) errors
4. **Process Results Efficiently:**
- Check result types before processing
- Extract only needed fields
- Implement pagination for large result sets
- Check result types before processing
- Extract only needed fields
- Implement pagination for large result sets
5. **Combine Multiple Sources:**
- Use different tools for comprehensive coverage
- Cross-reference results for validation
- Merge and deduplicate results
- Use different tools for comprehensive coverage
- Cross-reference results for validation
- Merge and deduplicate results
Complete Example
----------------
@@ -628,24 +639,28 @@ Troubleshooting
Common Issues and Solutions:
1. **API Rate Limits:**
- Some services have rate limits
- Implement delays between requests
- Use error handling for 429 errors
- Some services have rate limits
- Implement delays between requests
- Use error handling for 429 errors
2. **Missing Results:**
- Check query spelling and keywords
- Try different search terms
- Verify tool parameters
- Check query spelling and keywords
- Try different search terms
- Verify tool parameters
3. **Authentication Errors:**
- Some tools require API keys
- Check your .env file configuration
- Verify API key validity
- Some tools require API keys
- Check your .env file configuration
- Verify API key validity
4. **Network Issues:**
- Check internet connection
- Implement retry logic
- Handle timeout exceptions
- Check internet connection
- Implement retry logic
- Handle timeout exceptions
For more help, see the :doc:`troubleshooting guide <../help/troubleshooting>`.
@@ -657,40 +672,64 @@ Common Parameters
Most search tools accept these common parameters:
+------------------+------------------+------------------+------------------+
| Parameter | Type | Description | Example |
+==================+==================+==================+==================+
| query | string | Search terms | "machine |
| | | | learning" |
+------------------+------------------+------------------+------------------+
| limit | integer | Max results | 5 |
+------------------+------------------+------------------+------------------+
| max_results | integer | Max results | 5 |
| | | (alternative) | |
+------------------+------------------+------------------+------------------+
| sort_by | string | Sort order | "relevance" |
+------------------+------------------+------------------+------------------+
| sort_order | string | Sort direction | "descending" |
+------------------+------------------+------------------+------------------+
| filter | string | Result filters | "type:journal- |
| | | | article" |
+------------------+------------------+------------------+------------------+
| year_from | integer | Start year | 2020 |
+------------------+------------------+------------------+------------------+
| year_to | integer | End year | 2024 |
+------------------+------------------+------------------+------------------+
| open_access | boolean | Open access only | True |
+------------------+------------------+------------------+------------------+
| type | string | Content type | "articles" |
+------------------+------------------+------------------+------------------+
| email | string | Contact email | "user@example. |
| | | (required) | com" |
+------------------+------------------+------------------+------------------+
.. list-table::
:header-rows: 1
:widths: 20 15 35 30
* - Parameter
- Type
- Description
- Example
* - ``query``
- string
- Search terms
- ``"machine learning"``
* - ``limit``
- integer
- Max results
- ``5``
* - ``max_results``
- integer
- Max results (alternative)
- ``5``
* - ``sort_by``
- string
- Sort order
- ``"relevance"``
* - ``sort_order``
- string
- Sort direction
- ``"descending"``
* - ``filter``
- string
- Result filters
- ``"type:journal-article"``
* - ``year_from``
- integer
- Start year
- ``2020``
* - ``year_to``
- integer
- End year
- ``2024``
* - ``open_access``
- boolean
- Open access only
- ``True``
* - ``type``
- string
- Content type
- ``"articles"``
* - ``email``
- string
- Contact email (required)
- ``"user@example.com"``
Quick Usage Examples
~~~~~~~~~~~~~~~~~~~~
ArXiv Search:
.. code-block:: python
result = tu.run({
@@ -703,6 +742,7 @@ ArXiv Search:
})
Crossref Search:
.. code-block:: python
result = tu.run({
@@ -715,6 +755,7 @@ Crossref Search:
})
PubMed Search:
.. code-block:: python
result = tu.run({
@@ -726,6 +767,7 @@ PubMed Search:
})
Semantic Scholar Search:
.. code-block:: python
result = tu.run({
@@ -737,6 +779,7 @@ Semantic Scholar Search:
})
OpenAlex Search:
.. code-block:: python
result = tu.run({
@@ -750,6 +793,7 @@ OpenAlex Search:
})
Preprint Archives:
.. code-block:: python
# BioRxiv (Biology)
@@ -780,6 +824,7 @@ Preprint Archives:
})
Open Access Tools:
.. code-block:: python
# DOAJ Search
@@ -931,6 +976,7 @@ Optimized Tool Examples
Here are examples showing the enhanced features of the optimized tools:
**Europe PMC with Enhanced Data:**
.. code-block:: python
# Europe PMC now provides comprehensive metadata
@@ -954,6 +1000,7 @@ Here are examples showing the enhanced features of the optimized tools:
print(f"Data Quality: {paper.get('data_quality')}")
**OpenAlex with Abstract Reconstruction:**
.. code-block:: python
# OpenAlex now reconstructs abstracts from inverted index
@@ -975,6 +1022,7 @@ Here are examples showing the enhanced features of the optimized tools:
print(f"Keywords: {paper.get('keywords')}")
**Semantic Scholar with Rate Limit Handling:**
.. code-block:: python
# Semantic Scholar now handles rate limits gracefully
@@ -995,6 +1043,7 @@ Here are examples showing the enhanced features of the optimized tools:
print(f"Data Quality: {paper.get('data_quality')}")
**Crossref with HTML Cleaning:**
.. code-block:: python
# Crossref now cleans HTML tags from abstracts
@@ -1015,6 +1064,7 @@ Here are examples showing the enhanced features of the optimized tools:
print(f"Article Type: {paper.get('article_type')}")
**Data Quality Analysis:**
.. code-block:: python
def analyze_data_quality(results):
docs/guide/literature_search_web_ui_tutorial.rst
+27 -21
View File
@@ -30,11 +30,12 @@ Key Features
- **Unified Search Interface**: Search across ArXiv, PubMed, Crossref, Semantic Scholar, OpenAlex, DBLP, DOAJ, Europe PMC, HAL, MedRxiv, and Unpaywall
- **Smart Query Processing**: AI-powered query expansion to generate multiple search terms
- **Intelligent Analysis**: Comprehensive literature review generation with:
- Research overview and scope analysis
- Temporal analysis of research trends
- Thematic analysis of research areas
- Key contributions identification
- Research gaps and future directions
- Research overview and scope analysis
- Temporal analysis of research trends
- Thematic analysis of research areas
- Key contributions identification
- Research gaps and future directions
- **Paper Card Display**: Modern, responsive interface showing papers with source identification
- **Real-time Status**: Live updates on tool usage and search progress
@@ -91,9 +92,10 @@ Basic Search
1. **Enter your search query** in the search box
2. **Choose search options**:
- Enable "AI Query Split" to automatically expand your search terms
- Enable "AI Summary" to generate intelligent literature analysis
- Adjust the result limit (default: 10)
- Enable "AI Query Split" to automatically expand your search terms
- Enable "AI Summary" to generate intelligent literature analysis
- Adjust the result limit (default: 10)
3. **Click "Search Literature"** to start the search
Example searches:
@@ -365,25 +367,29 @@ Here's a complete example of using the Wide Research Web UI:
2. **Open your browser** and go to http://localhost:5001
3. **Perform a search**:
- Query: "deep learning computer vision"
- Enable AI Query Split:
- Enable AI Summary:
- Limit: 5
- Query: "deep learning computer vision"
- Enable AI Query Split:
- Enable AI Summary:
- Limit: 5
4. **Review the results**:
- Check the paper cards for relevant publications
- Read the intelligent summary for insights
- Note the research timeline and themes
- Check the paper cards for relevant publications
- Read the intelligent summary for insights
- Note the research timeline and themes
5. **Refine your search**:
- Try more specific terms: "object detection deep learning"
- Focus on recent papers: adjust date filters
- Explore related themes from the summary
- Try more specific terms: "object detection deep learning"
- Focus on recent papers: adjust date filters
- Explore related themes from the summary
6. **Export results**:
- Use the API to programmatically access results
- Save interesting papers for further reading
- Use the summary for your literature review
- Use the API to programmatically access results
- Save interesting papers for further reading
- Use the summary for your literature review
This tutorial provides a comprehensive guide to using the ToolUniverse Wide Research Web UI. The interface combines the power of multiple academic databases with intelligent analysis to provide a complete literature research solution.
docs/guide/loading_tools.rst
+1 -1
View File
@@ -1,5 +1,5 @@
Tool Loading Tutorial
==================
=====================
**Complete Tutorial to loading and managing tools in ToolUniverse**
docs/guide/logging.rst
+8 -8
View File
@@ -1,11 +1,11 @@
Logging Tutorial
=============
================
**Configure and use ToolUniverse's comprehensive logging system**
ToolUniverse provides a robust logging system to help you monitor tool execution, debug issues, and track research workflows.
Logging Overview
Logging Overview
-------------------
ToolUniverse uses Python's standard logging module with enhanced formatting and emoji indicators. The logging system provides:
@@ -15,7 +15,7 @@ ToolUniverse uses Python's standard logging module with enhanced formatting and
* **Emoji Indicators**: Visual cues for different message types
* **Flexible Configuration**: Environment variables, programmatic setup, and per-instance control
Log Levels Explained
Log Levels Explained
-----------------------
Understanding when to use each log level:
@@ -299,7 +299,7 @@ ToolUniverse provides convenience functions for quick logging:
error("Tool execution failed")
critical("System resources exhausted")
Common Logging Patterns
Common Logging Patterns
--------------------------
Research Workflow Logging
@@ -404,7 +404,7 @@ Batch Processing with Progress Tracking
logger.info(f"📊 Batch complete: {len(results)} successful, {len(errors)} failed")
return results, errors
Best Practices
Best Practices
-----------------
Choose Appropriate Log Levels
@@ -468,7 +468,7 @@ Include relevant details for debugging:
logger.debug(f"Full traceback:", exc_info=True) # Include stack trace in debug
raise
Troubleshooting Logging
Troubleshooting Logging
--------------------------
Common Issues and Solutions
@@ -518,7 +518,7 @@ Check Current Log Level
# Level numbers: DEBUG=10, INFO=20, PROGRESS=25, WARNING=30, ERROR=40, CRITICAL=50
Log Output Examples
Log Output Examples
---------------------
Here's what different log levels look like in practice:
@@ -533,7 +533,7 @@ Here's what different log levels look like in practice:
❌ ERROR: OpenTargets query failed: Connection timeout
🚨 CRITICAL: Failed to initialize tool registry
Next Steps
Next Steps
-------------
Now that you understand ToolUniverse logging:
docs/guide/make_your_data_agent_searchable.rst
+74 -66
View File
@@ -28,7 +28,7 @@ What you’ll do
---
1. Install
---------
----------
.. code-block:: bash
@@ -52,7 +52,8 @@ run the module directly:
python -m tooluniverse.database_setup.cli --help
### Available ``tu-datastore`` commands
Available ``tu-datastore`` commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: text
@@ -66,7 +67,7 @@ run the module directly:
---
2. Choose ONE embedding service
----------------------------
-------------------------------
Create a file named **.env** and paste one block below, then run ``source .env``.
@@ -107,7 +108,7 @@ Create a file named **.env** and paste one block below, then run ``source .env``
---
3. Build your agent-searchable collection from your raw data
----------------------------------------------------------
------------------------------------------------------------
All you need is either a **folder of text files** or a **JSON list of documents**.
@@ -117,15 +118,18 @@ All you need is either a **folder of text files** or a **JSON list of documents*
tu-datastore quickbuild --name cardiology_tutorial --from-folder ./cardiology_data
What goes in `./cardiology_data`:
What goes in ``./cardiology_data``:
* **Supported:** ``.txt`` and ``.md`` (your raw data files)
Each file in `./cardiology_data` automatically gets converted into a document with the following information:
* ``doc_key`` = relative file path (e.g., ``biology/mitochondria.md``)
* ``text`` = file contents
* Basic metadata (title, path, source) which is auto-filled
Each file in ``./cardiology_data`` automatically gets converted into a document with the following information:
* ``doc_key`` = relative file path (e.g., ``biology/mitochondria.md``)
* ``text`` = file contents
* Basic metadata (title, path, source) which is auto-filled
**Example:**
.. code-block:: text
cardiology_data/
@@ -192,13 +196,14 @@ Use this when you want explicit IDs and metadata.
]
Produces the same ``cardiology_tutorial.db`` and ``cardiology_tutorial.faiss`` artifacts as QuickBuild.
Note:
* **Required:** `doc_key` (unique per collection), `text`
* **Optional:** `metadata` (any JSON object), `text_hash` (string)
---
Note:
* **Required:** ``doc_key`` (unique per collection), ``text``
* **Optional:** ``metadata`` (any JSON object), ``text_hash`` (string)
4. Create the agent tool for your collection
-----------------------------------------
--------------------------------------------
Now the last step is to tell ToolUniverse how agents should search your dataset by creating a small **tool JSON**.
@@ -239,13 +244,9 @@ If you want your tool to load automatically in all ToolUniverse or Codex session
5. Install your tool for automatic discovery (recommended)
-----------------------------------------------------------
ToolUniverse automatically loads any tool placed in:
ToolUniverse automatically loads any tool placed in::
```
~/.tooluniverse/data/user_tools/
```
~/.tooluniverse/data/user_tools/
Install your tool with:
@@ -253,13 +254,9 @@ Install your tool with:
tu-datastore add-tool cardiology_expert_search.json
This copies your tool into the auto-load directory:
This copies your tool into the auto-load directory::
```
~/.tooluniverse/data/user_tools/cardiology_expert_search.json
```
~/.tooluniverse/data/user_tools/cardiology_expert_search.json
Optional arguments:
@@ -268,13 +265,9 @@ Optional arguments:
tu-datastore add-tool cardiology_expert_search.json --name cardiology_expert_search.json
tu-datastore add-tool cardiology_expert_search.json --overwrite # overwrites json file if exists
Once installed, **any ToolUniverse or Codex session** will immediately expose your tool:
Once installed, **any ToolUniverse or Codex session** will immediately expose your tool::
```
tu.tools.cardiology_expert_search(...)
```
tu.tools.cardiology_expert_search(...)
**You are done! ToolUniverse agents now have access to your data collection and associated tool to use in their work as an AI Scientist!**
@@ -283,10 +276,11 @@ How it works
* ToolUniverse has a built-in **search tool** (`EmbeddingCollectionSearchTool`) that queries the agent-searchable dataset you’ve built from your raw data. `
* Your JSON simply tells ToolUniverse **which collection** to open and **which search options it supports**:
- the user’s search text (``query``),
- search type (``method``: keyword/embedding/hybrid),
- number of results (``top_k``),
- You can optionally control the hybrid mix with alpha (``alpha``).
- the user’s search text (``query``),
- search type (``method``: keyword/embedding/hybrid),
- number of results (``top_k``),
- You can optionally control the hybrid mix with alpha (``alpha``).
ToolUniverse automatically resolves paths in ``<user_cache_dir>/embeddings/``.
* Agents can now call ``cardiology_expert_search`` immediately after loading your JSON — no local setup needed.
@@ -294,7 +288,7 @@ ToolUniverse automatically resolves paths in ``<user_cache_dir>/embeddings/``.
---
6. Share or back up via Hugging Face (optional)
--------------------------------------------
-----------------------------------------------
After making your agent-searchable dataset you can share it publicly. You can also download other's public agent-searchable datasets and their tools so that you can use the community's data and tools in your research!
@@ -336,8 +330,8 @@ Get your token from: https://huggingface.co/settings/tokens
All files download into your local cache at: ``<user_cache_dir>/embeddings/<collection>/``.
How it works
------------
How sharing works
-----------------
* Using the above commands, ToolUniverse syncs your local datastore, the `.db` and `.faiss` files (e.g. `<user_cache_dir>/embeddings/cardiology_tutorial.db` and `<user_cache_dir>/embeddings/cardiology_tutorial.faiss`) and associated JSON tools you create to search the associated `.db` and `.faiss` (e.g. `cardiology_expert_search.json`) directly with your **Hugging Face account**. This way others can download and use the exact same searchable dataset you built with ToolUniverse agents — complete with your embeddings and metadata.
@@ -378,11 +372,22 @@ Blends keyword and embedding scores. Documents must be relevant on BOTH dimensio
**Comparison:**
| Method | Strength | Use Case |
|--------|----------|----------|
| **Keyword** | Fast, exact | Technical queries with known terms |
| **Embedding** | Understands meaning | Natural language, conceptual queries |
| **Hybrid** | Both (agents use this) | Recommended for agents; combines precision + recall |
.. list-table::
:header-rows: 1
:widths: 20 35 45
* - Method
- Strength
- Use Case
* - **Keyword**
- Fast, exact
- Technical queries with known terms
* - **Embedding**
- Understands meaning
- Natural language, conceptual queries
* - **Hybrid**
- Both (agents use this)
- Recommended for agents; combines precision + recall
---
@@ -498,20 +503,22 @@ Mini FAQ
- **“No results”?** Try ``--method keyword`` or confirm the ``--collection`` name.
- **Where are my searchable datasets stored locally?** ``<user_cache_dir>/embeddings/``. Examples:
- macOS → ``~/Library/Caches/ToolUniverse``
- Linux → ``~/.cache/tooluniverse``
- Windows → ``%LOCALAPPDATA%\\ToolUniverse``
- **Where do my tools live?**
``~/.tooluniverse/data/user_tools/`` (auto-loaded)
- **Where does my data upload?** ``tu-datastore sync-hf upload`` targets your **own** HF account by default (based on your token).
- macOS → ``~/Library/Caches/ToolUniverse``
- Linux → ``~/.cache/tooluniverse``
- Windows → ``%LOCALAPPDATA%\\ToolUniverse``
- **What is the`EmbeddingCollectionSearchTool`?**
-`EmbeddingCollectionSearchTool` is a **real ToolUniverse tool** (registered in code). Check ``src/tooluniverse/database_setup/generic_embedding_search_tool.py`` for details.
- We don’t ship a pre-bound JSON for it because the collection name is yours.
- Use the example JSON under ``docs/tools/``, set ``"fields.collection"`` to your collection (e.g., ``"cardiology_tutorial"``), and load it
- If you prefer not to create a JSON, you can also instantiate the tool directly from Python and pass the collection name via ``fields``
- **Where do my tools live?**
``~/.tooluniverse/data/user_tools/`` (auto-loaded)
- **Where does my data upload?** ``tu-datastore sync-hf upload`` targets your **own** HF account by default (based on your token).
- **What is the** ``EmbeddingCollectionSearchTool`` **?**
- ``EmbeddingCollectionSearchTool`` is a **real ToolUniverse tool** (registered in code). Check ``src/tooluniverse/database_setup/generic_embedding_search_tool.py`` for details.
- We don’t ship a pre-bound JSON for it because the collection name is yours.
- Use the example JSON under ``docs/tools/``, set ``"fields.collection"`` to your collection (e.g., ``"cardiology_tutorial"``), and load it
- If you prefer not to create a JSON, you can also instantiate the tool directly from Python and pass the collection name via ``fields``
- **Can I upload my tool with the datastore?** Yes, pass one or more files via ``--tool-json`` during ``sync-hf upload``; they’re stored at the dataset root.
@@ -520,9 +527,10 @@ Mini FAQ
- **Is upload private by default?** Yes auto upload **private** datasets unless you opt out (CLI: ``--no-private``; tool: set ``"private": false``).
- **Do I have to pass --db to search/build?**
- No — both commands write and read from your cache automatically.
- Use `--db` only if you want a **custom output path** (for example, a shared directory).
- When using the **JSON tool** or agents, no paths are ever needed — everything resolves automatically from the collection name.
- No — both commands write and read from your cache automatically.
- Use `--db` only if you want a **custom output path** (for example, a shared directory).
- When using the **JSON tool** or agents, no paths are ever needed — everything resolves automatically from the collection name.
- **When building my custom datastore what if I want to use different provider(s) and/or model(s) for my embeddings?** You can use a different provider/model when building your searchable datastore like we do in the example below — just make sure that if you want to keep the initial provider/model based datastore, you give this new build's collection a new name or else it will override the initial build.
@@ -566,16 +574,16 @@ ToolUniverse includes 8 tests under `tests/test_database_setup/`:
* **2 core tests** (SQLite + FAISS) always run automatically and require *no* API keys.
* The **other 6 tests** exercise real embedding pipelines (OpenAI, Azure, HF, or local). These are **skipped by default** unless you export:
```bash
export EMBED_PROVIDER=azure|openai|huggingface|local
export EMBED_MODEL=your-model-or-deployment
```
.. code-block:: bash
export EMBED_PROVIDER=azure|openai|huggingface|local
export EMBED_MODEL=your-model-or-deployment
You can run all embedding-enabled tests with:
```bash
pytest -m api
```
.. code-block:: bash
pytest -m api
These optional tests pass for all supported providers once credentials are set.
docs/guide/python_guide.rst
+51 -50
View File
@@ -54,9 +54,10 @@ Check that ToolUniverse is installed correctly:
print(f"ToolUniverse version: {tooluniverse.__version__}")
print("✅ Installation successful!")
.. success:: **Installation Complete**
You're ready to start using ToolUniverse!
.. admonition:: Installation Complete
:class: tip
You're ready to start using ToolUniverse!
Quick Start
-----------
@@ -171,15 +172,15 @@ Tool Finders
ToolUniverse has **three ways** to find tools. Don't browse 1000+ tools manually—use Tool Finder!
.. grid:: 1 1 2 2
:gutter: 3
:gutter: 3
.. grid-item-card:: Keyword Search
:class-card: hover-lift
:shadow: md
.. grid-item-card:: Keyword Search
:class-card: hover-lift
:shadow: md
**Fast text matching**
Best for: Exact terms you know
**Fast text matching**
Best for: Exact terms you know
.. code-block:: python
@@ -451,61 +452,61 @@ Advanced Features
-----------------
.. grid:: 1 1 2 2
:gutter: 3
:gutter: 3
.. grid-item-card:: Tool Composition
:link: tool_composition
:link-type: doc
:class-card: hover-lift
:shadow: md
.. grid-item-card:: Tool Composition
:link: tool_composition
:link-type: doc
:class-card: hover-lift
:shadow: md
Chain multiple tools into scientific workflows
Chain multiple tools into scientific workflows
.. grid-item-card:: Hooks System
:link: hooks/index
:link-type: doc
:class-card: hover-lift
:shadow: md
.. grid-item-card:: Hooks System
:link: hooks/index
:link-type: doc
:class-card: hover-lift
:shadow: md
Intelligent output processing and summarization
Intelligent output processing and summarization
.. grid-item-card:: Cache System
:link: cache_system
:link-type: doc
:class-card: hover-lift
:shadow: md
.. grid-item-card:: Cache System
:link: cache_system
:link-type: doc
:class-card: hover-lift
:shadow: md
Optimize performance with smart caching
Optimize performance with smart caching
.. grid-item-card:: HTTP API
:link: http_api
:link-type: doc
:class-card: hover-lift
:shadow: md
.. grid-item-card:: HTTP API
:link: http_api
:link-type: doc
:class-card: hover-lift
:shadow: md
Deploy ToolUniverse as a remote service
Deploy ToolUniverse as a remote service
.. grid-item-card:: ChatGPT API
:link: chatgpt_api
:link-type: doc
:class-card: hover-lift
:shadow: md
.. grid-item-card:: ChatGPT API
:link: chatgpt_api
:link-type: doc
:class-card: hover-lift
:shadow: md
Use ToolUniverse tools as OpenAI function calls
Use ToolUniverse tools as OpenAI function calls
.. button-ref:: tooluniverse_case_study
:color: primary
:shadow:
:expand:
:color: primary
:shadow:
:expand:
**Complete Case Study**: Drug discovery workflow with Gemini 2.5 Pro
**Complete Case Study**: Drug discovery workflow with Gemini 2.5 Pro
.. button-ref:: ../api/modules
:color: secondary
:shadow:
:expand:
.. button-ref:: /api/modules
:color: secondary
:shadow:
:expand:
**API Reference**: Detailed Python API documentation
**API Reference**: Detailed Python API documentation
.. toctree::
:maxdepth: 2
docs/guide/tool_caller.rst
+1 -1
View File
@@ -1,5 +1,5 @@
Tool Caller Tutorial
==================
====================
The Tool Caller is ToolUniverse's execution engine that handles tool instantiation, validation, and execution. It uses dynamic loading to efficiently manage hundreds of tools without loading them all at startup.
docs/guide/tool_composition.rst
+52 -41
View File
@@ -1,5 +1,5 @@
Tool Composition Tutorial
======================
=========================
**Chain ToolUniverse's 1000+ tools into powerful scientific workflows**
@@ -495,32 +495,37 @@ Common Issues and Solutions
~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. **Tool Not Found Error**
- Check that the tool name is correct in your compose script
- Ensure the tool is loaded in ToolUniverse
- Verify the tool is in the `required_tools` list
- Use `auto_load_dependencies: true` to automatically load missing tools
- Check that the tool name is correct in your compose script
- Ensure the tool is loaded in ToolUniverse
- Verify the tool is in the `required_tools` list
- Use `auto_load_dependencies: true` to automatically load missing tools
2. **Import Errors**
- Make sure your compose script is in the `compose_scripts/` directory
- Check that the function name matches `composition_function`
- Verify the function signature is correct: `def compose(arguments, tooluniverse, call_tool):`
- Make sure your compose script is in the `compose_scripts/` directory
- Check that the function name matches `composition_function`
- Verify the function signature is correct: `def compose(arguments, tooluniverse, call_tool):`
3. **Parameter Errors**
- Validate your parameter schema in the JSON configuration
- Check that required parameters are provided
- Ensure parameter types match the schema
- Follow the interaction protocol schema of ToolUniverse
- Validate your parameter schema in the JSON configuration
- Check that required parameters are provided
- Ensure parameter types match the schema
- Follow the interaction protocol schema of ToolUniverse
4. **Performance Issues**
- Limit the number of tools called in sequence
- Use `auto_load_dependencies: true` for automatic loading
- Consider caching results for repeated calls
- Implement proper error handling to avoid cascading failures
- Limit the number of tools called in sequence
- Use `auto_load_dependencies: true` for automatic loading
- Consider caching results for repeated calls
- Implement proper error handling to avoid cascading failures
5. **Heterogeneous Backend Issues**
- Ensure all required tools are available across different backends
- Use `fail_on_missing_tools: false` for graceful degradation
- Implement fallback mechanisms for critical workflow steps
- Ensure all required tools are available across different backends
- Use `fail_on_missing_tools: false` for graceful degradation
- Implement fallback mechanisms for critical workflow steps
Available Compose Tools
------------------------
@@ -530,38 +535,44 @@ ToolUniverse currently provides several pre-built compose tools that demonstrate
** Working Compose Tools**:
1. **LiteratureSearchTool** - Literature research and synthesis
- Searches EuropePMC, OpenAlex, and PubTator databases
- Uses AI agent for literature summarization
- Demonstrates broadcasting pattern
- Searches EuropePMC, OpenAlex, and PubTator databases
- Uses AI agent for literature summarization
- Demonstrates broadcasting pattern
2. **ComprehensiveDrugDiscoveryPipeline** - End-to-end drug discovery
- Target identification using OpenTargets
- Lead discovery from known drugs
- Safety assessment using ADMETAI tools
- Literature validation
- Demonstrates sequential chaining with tool integration
- Target identification using OpenTargets
- Lead discovery from known drugs
- Safety assessment using ADMETAI tools
- Literature validation
- Demonstrates sequential chaining with tool integration
3. **BiomarkerDiscoveryWorkflow** - Biomarker discovery and validation
- Literature-based biomarker discovery
- Multi-strategy gene search using HPA
- Comprehensive pathway analysis using HPA tools
- Clinical validation using FDA data
- Demonstrates multi-strategy fallbacks and error handling
- Literature-based biomarker discovery
- Multi-strategy gene search using HPA
- Comprehensive pathway analysis using HPA tools
- Clinical validation using FDA data
- Demonstrates multi-strategy fallbacks and error handling
4. **DrugSafetyAnalyzer** - Drug safety assessment
- PubChem compound information retrieval
- EuropePMC literature search
- Demonstrates safety-focused workflows
- PubChem compound information retrieval
- EuropePMC literature search
- Demonstrates safety-focused workflows
5. **ToolDescriptionOptimizer** - Tool optimization
- AI-powered tool description improvement
- Test case generation and quality evaluation
- Demonstrates agentic optimization loops
- AI-powered tool description improvement
- Test case generation and quality evaluation
- Demonstrates agentic optimization loops
6. **ToolDiscover** - Tool discovery and generation
- AI-powered tool creation from descriptions
- Iterative code improvement
- Demonstrates advanced agentic workflows
- AI-powered tool creation from descriptions
- Iterative code improvement
- Demonstrates advanced agentic workflows
**Key Features**:
- **All tools tested and working** with real data processing
docs/guide/tools.rst
+53 -53
View File
@@ -58,52 +58,52 @@ Tool Categories Summary
~~~~~~~~~~~~~~~~~~~~~~~
.. list-table:: Tool Distribution by Category
:header-rows: 1
:widths: 25 15 15 45
:header-rows: 1
:widths: 25 15 15 45
* - Category
- Count
- Percentage
- Primary Use Cases
* - APIs
- 281
- 48.4%
- External data access, real-time information
* - Software Packages
- 164
- 28.3%
- Computational analysis, local processing
* - Databases
- 84
- 14.5%
- Structured data storage and retrieval
* - AI Agents
- 33
- 5.7%
- Autonomous reasoning and planning
* - ML Models
- 15
- 2.6%
- Prediction and classification tasks
* - Expert Feedback
- 6
- 1.0%
- Human validation and guidance
* - Embedding Stores
- 4
- 0.7%
- Semantic search and similarity
* - Robotics
- 1
- 0.2%
- Laboratory automation
* - **Total**
- **588**
- **100%**
- **Comprehensive scientific ecosystem**
* - Category
- Count
- Percentage
- Primary Use Cases
* - APIs
- 281
- 48.4%
- External data access, real-time information
* - Software Packages
- 164
- 28.3%
- Computational analysis, local processing
* - Databases
- 84
- 14.5%
- Structured data storage and retrieval
* - AI Agents
- 33
- 5.7%
- Autonomous reasoning and planning
* - ML Models
- 15
- 2.6%
- Prediction and classification tasks
* - Expert Feedback
- 6
- 1.0%
- Human validation and guidance
* - Embedding Stores
- 4
- 0.7%
- Semantic search and similarity
* - Robotics
- 1
- 0.2%
- Laboratory automation
* - **Total**
- **588**
- **100%**
- **Comprehensive scientific ecosystem**
Molecular & Genetic Data
----------------------------
Molecular & Genetic Data
------------------------
UniProt - Protein Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -166,7 +166,7 @@ Comprehensive gene set enrichment analysis.
}
}
Disease & Target Data
Disease & Target Data
------------------------
OpenTargets Platform
@@ -210,7 +210,7 @@ Disease and experimental factor ontology.
"arguments": {"query": "diabetes"}
}
Drug & Chemical Data
Drug & Chemical Data
-----------------------
PubChem - Chemical Information
@@ -302,7 +302,7 @@ Official FDA drug labeling information.
"arguments": {"medicinalproduct": "metformin"}
}
Clinical Research
Clinical Research
--------------------
ClinicalTrials.gov
@@ -328,7 +328,7 @@ Clinical trial registry and results database.
}
}
Literature & Publications
Literature & Publications
-----------------------------
PubTator - Biomedical Literature
@@ -400,7 +400,7 @@ Open academic publication database.
* ``OpenAlex_get_author_info`` - Author information and metrics
* ``OpenAlex_get_institution_data`` - Institution research data
Specialized Databases
Specialized Databases
------------------------
Human Protein Atlas
@@ -461,7 +461,7 @@ Consumer health information.
* ``MedlinePlus_search_conditions`` - Search medical conditions
* ``MedlinePlus_get_drug_info`` - Consumer drug information
AI-Powered Tools
AI-Powered Tools
--------------------
Machine Learning Models (15 tools)
@@ -579,7 +579,7 @@ AI tools for discovering and combining other tools.
}
}
Search & Integration Tools
Search & Integration Tools
-----------------------------
Tool Finder
@@ -811,7 +811,7 @@ Tool Composition Patterns
else:
break
Tool Performance Tips
Tool Performance Tips
------------------------
Optimization Strategies
@@ -966,7 +966,7 @@ Future Extensions
- Community voting and validation
- Maintenance and updates
Next Steps
Next Steps
-------------
Now that you know what tools are available:
docs/help/faq.rst
+2 -1
View File
@@ -136,8 +136,9 @@ Many scientific APIs have rate limits. ToolUniverse implements automatic rate li
# Caching is enabled by default
tu = ToolUniverse()
result = tu.run(..., use_cache=True)
Tool returns empty results?
~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Check these common issues:**
docs/help/index.rst
+1
View File
@@ -9,6 +9,7 @@ Get help and find answers for ToolUniverse.
faq
troubleshooting
wechat_community
**Quick Links:**
docs/help/troubleshooting.rst
+3 -3
View File
@@ -1,5 +1,5 @@
Troubleshooting Tutorial
=====================
========================
Quick Diagnostic
----------------
@@ -680,8 +680,8 @@ If none of these solutions work:
4. **Join our community**: Discord server link
.. note::
=========
When reporting issues, please run the diagnostic script first:
When reporting issues, please run the diagnostic script first:
.. code-block:: python
docs/index.rst
+16
View File
@@ -214,15 +214,31 @@ Community & Support
:hidden:
:caption: Tutorials
guide/index
guide/tooluniverse_case_study
guide/agentic_tools_tutorial
guide/literature_search_tools_tutorial
guide/literature_search_web_ui_tutorial
guide/clinical_guidelines_tools
guide/scientific_workflows
guide/make_your_data_agent_searchable
guide/visualization_tutorial
guide/expert_feedback
guide/hooks/index
guide/cache_system
guide/tools
.. toctree::
:maxdepth: 3
:hidden:
:caption: Advanced
guide/logging
guide/streaming_tools
guide/openrouter_support
guide/vllm_support
guide/euhealth_tools_tutorial
.. toctree::
:maxdepth: 3
:hidden:
docs/sitemap.rst
+8 -13
View File
@@ -1,9 +1,11 @@
:orphan:
Documentation Sitemap
=====================
**Complete navigation of all ToolUniverse documentation**
Get Started
Get Started
--------------
- :doc:`guide/python_guide` - Python Developer Guide
@@ -11,7 +13,7 @@ Documentation Sitemap
- :doc:`guide/skills_showcase` - AI Agent Skills
- :doc:`guide/api_keys` - API Keys Configuration
Tutorials & Workflows
Tutorials & Workflows
-------------------------
- :doc:`guide/index` - Tutorials Overview
@@ -42,7 +44,7 @@ Documentation Sitemap
- :doc:`guide/http_api` - HTTP API
- :doc:`help/wechat_community` - WeChat Community
Expand ToolUniverse
Expand ToolUniverse
-----------------------
- :doc:`expand_tooluniverse/index` - Overview
@@ -52,18 +54,18 @@ Documentation Sitemap
- :doc:`expand_tooluniverse/contributing/index` - Contributing
- :doc:`expand_tooluniverse/architecture` - Architecture
Tools Catalog
Tools Catalog
-----------------
- :doc:`tools/tools_config_index` - Tools Configuration Index
- :doc:`tools/remote_tools` - Remote Tools
API Reference
API Reference
-----------------
- :doc:`api/modules` - API Modules
Help & Reference
Help & Reference
-------------------
- :doc:`reference/cli_tools` - CLI Tools
@@ -74,13 +76,6 @@ Documentation Sitemap
- :doc:`expand_tooluniverse/reference/index` - Reference
- :doc:`about/index` - About
Legacy Documentation
-----------------------
- :doc:`old/quickstart` - Quick Start (Legacy)
- :doc:`old/installation` - Installation (Legacy)
- :doc:`old/getting_started` - Getting Started (Legacy)
Python API Pages
----------------
docs/tools/cellosaurus_tools.rst
+3 -3
View File
@@ -13,7 +13,7 @@ Available Tools
**cellosaurus_get_cell_line_info** (Type: CellosaurusGetCellLineInfoTool)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Get detailed information about a specific cell line using its Cellosaurus accession number (CVCL_...
Get detailed information about a specific cell line using its Cellosaurus accession number (``CVCL_``...).
.. dropdown:: cellosaurus_get_cell_line_info tool specification
@@ -21,12 +21,12 @@ Get detailed information about a specific cell line using its Cellosaurus access
* **Name**: ``cellosaurus_get_cell_line_info``
* **Type**: ``CellosaurusGetCellLineInfoTool``
* **Description**: Get detailed information about a specific cell line using its Cellosaurus accession number (CVCL_ format).
* **Description**: Get detailed information about a specific cell line using its Cellosaurus accession number (``CVCL_`` format).
**Parameters:**
* ``accession`` (string) (required)
Cellosaurus accession number (must start with 'CVCL_')
Cellosaurus accession number (must start with ``CVCL_``)
* ``format`` (string) (required)
Response format
docs/tools/remote/ui.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 181 KiB

docs/tools/tools_config_index.rst
+5
View File
@@ -92,6 +92,11 @@ Packages Tools
Physics Astronomy Tools <physics_astronomy_tools>
.. toctree::
:maxdepth: 1
SIMBAD Astronomy Tools <simbad_tools>
.. toctree::
:maxdepth: 1
docs/tools/uniprot_tools.rst
+2 -2
View File
@@ -386,10 +386,10 @@ Search UniProtKB database with flexible query syntax. Returns protein entries wi
Maximum number of results to return (default: 25, max: 500). Accepts string or integer.
* ``min_length`` (integer) (optional)
Minimum sequence length. Auto-converts to 'length:[min TO *]' range query.
Minimum sequence length. Auto-converts to an open-ended length range query (min to unbounded).
* ``max_length`` (integer) (optional)
Maximum sequence length. Auto-converts to 'length:[* TO max]' range query.
Maximum sequence length. Auto-converts to an open-ended length range query (unbounded to max).
* ``fields`` (array) (optional)
List of field names to return (e.g., ['accession','gene_primary','length','organism_name']). When specified, returns raw API response with requested fields. Common fields: accession, id, gene_names, gene_primary, protein_name, organism_name, organism_id, length, mass, sequence, reviewed, cc_function. See UniProt API docs for full list. Default (no fields): returns formatted response with accession, id, protein_name, gene_names, organism, length.
pyproject.toml
+1 -1
View File
@@ -84,7 +84,7 @@ docs = [
"linkify-it-py>=2.0.0",
"sphinx-autobuild>=2021.3.14",
"sphinx-copybutton>=0.5.0",
"sphinx-tabs>=3.2.0",
"sphinx-tabs>=3.5.0",
"sphinx-design>=0.3.0",
"sphinx-notfound-page>=0.8",
"sphinx-autodoc-typehints>=1.12.0",
src/tooluniverse/data/uniprot_tools.json
+2 -2
View File
@@ -693,11 +693,11 @@
},
"min_length": {
"type": "integer",
"description": "Minimum sequence length. Auto-converts to 'length:[min TO *]' range query."
"description": "Minimum sequence length. Auto-converts to an open-ended length range query (min to unbounded)."
},
"max_length": {
"type": "integer",
"description": "Maximum sequence length. Auto-converts to 'length:[* TO max]' range query."
"description": "Maximum sequence length. Auto-converts to an open-ended length range query (unbounded to max)."
},
"fields": {
"type": "array",