Initial commit

skills/tooluniverse/references/api_reference.md

@@ -0,0 +1,298 @@
+# ToolUniverse Python API Reference
+
+## Core Classes
+
+### ToolUniverse
+
+Main class for interacting with the ToolUniverse ecosystem.
+
+```python
+from tooluniverse import ToolUniverse
+
+tu = ToolUniverse()
+```
+
+#### Methods
+
+##### `load_tools()`
+Load all available tools into the ToolUniverse instance.
+
+```python
+tu.load_tools()
+```
+
+**Returns:** None
+
+**Side effects:** Loads 600+ tools into memory for discovery and execution.
+
+---
+
+##### `run(tool_config)`
+Execute a tool with specified arguments.
+
+**Parameters:**
+- `tool_config` (dict): Configuration dictionary with keys:
+  - `name` (str): Tool name to execute
+  - `arguments` (dict): Tool-specific arguments
+
+**Returns:** Tool-specific output (dict, list, str, or other types)
+
+**Example:**
+```python
+result = tu.run({
+    "name": "OpenTargets_get_associated_targets_by_disease_efoId",
+    "arguments": {
+        "efoId": "EFO_0000537"
+    }
+})
+```
+
+---
+
+##### `list_tools(limit=None)`
+List all available tools or a subset.
+
+**Parameters:**
+- `limit` (int, optional): Maximum number of tools to return. If None, returns all tools.
+
+**Returns:** List of tool dictionaries
+
+**Example:**
+```python
+# List all tools
+all_tools = tu.list_tools()
+
+# List first 20 tools
+tools = tu.list_tools(limit=20)
+```
+
+---
+
+##### `get_tool_info(tool_name)`
+Get detailed information about a specific tool.
+
+**Parameters:**
+- `tool_name` (str): Name of the tool
+
+**Returns:** Dictionary containing tool metadata, parameters, and documentation
+
+**Example:**
+```python
+info = tu.get_tool_info("AlphaFold_get_structure")
+print(info['description'])
+print(info['parameters'])
+```
+
+---
+
+## Built-in Discovery Tools
+
+These are special tools that help find other tools in the ecosystem.
+
+### Tool_Finder
+
+Embedding-based semantic search for tools. Requires GPU.
+
+```python
+tools = tu.run({
+    "name": "Tool_Finder",
+    "arguments": {
+        "description": "protein structure prediction",
+        "limit": 10
+    }
+})
+```
+
+**Parameters:**
+- `description` (str): Natural language description of desired functionality
+- `limit` (int): Maximum number of tools to return
+
+**Returns:** List of relevant tools with similarity scores
+
+---
+
+### Tool_Finder_LLM
+
+LLM-based semantic search for tools. No GPU required.
+
+```python
+tools = tu.run({
+    "name": "Tool_Finder_LLM",
+    "arguments": {
+        "description": "Find tools for RNA sequencing analysis",
+        "limit": 10
+    }
+})
+```
+
+**Parameters:**
+- `description` (str): Natural language query
+- `limit` (int): Maximum number of tools to return
+
+**Returns:** List of relevant tools
+
+---
+
+### Tool_Finder_Keyword
+
+Fast keyword-based search through tool names and descriptions.
+
+```python
+tools = tu.run({
+    "name": "Tool_Finder_Keyword",
+    "arguments": {
+        "description": "pathway enrichment",
+        "limit": 10
+    }
+})
+```
+
+**Parameters:**
+- `description` (str): Keywords to search for
+- `limit` (int): Maximum number of tools to return
+
+**Returns:** List of matching tools
+
+---
+
+## Tool Output Hooks
+
+Post-processing hooks for tool results.
+
+### Summarization Hook
+```python
+result = tu.run({
+    "name": "some_tool",
+    "arguments": {"param": "value"}
+},
+hooks={
+    "summarize": {
+        "format": "brief"  # or "detailed"
+    }
+})
+```
+
+### File Saving Hook
+```python
+result = tu.run({
+    "name": "some_tool",
+    "arguments": {"param": "value"}
+},
+hooks={
+    "save_to_file": {
+        "filename": "output.json",
+        "format": "json"  # or "csv", "txt"
+    }
+})
+```
+
+---
+
+## Model Context Protocol (MCP)
+
+### Starting MCP Server
+
+Command-line interface:
+```bash
+tooluniverse-smcp
+```
+
+This launches an MCP server that exposes all ToolUniverse tools through the Model Context Protocol.
+
+**Configuration:**
+- Default port: Automatically assigned
+- Protocol: MCP standard
+- Authentication: None required for local use
+
+---
+
+## Integration Modules
+
+### OpenRouter Integration
+
+Access 100+ LLMs through OpenRouter API:
+
+```python
+from tooluniverse import OpenRouterClient
+
+client = OpenRouterClient(api_key="your_key")
+response = client.chat("Analyze this protein sequence", model="anthropic/claude-3-5-sonnet")
+```
+
+---
+
+## AI-Tool Interaction Protocol
+
+ToolUniverse uses a standardized protocol for LLM-tool communication:
+
+**Request Format:**
+```json
+{
+  "name": "tool_name",
+  "arguments": {
+    "param1": "value1",
+    "param2": "value2"
+  }
+}
+```
+
+**Response Format:**
+```json
+{
+  "status": "success",
+  "data": { ... },
+  "metadata": {
+    "execution_time": 1.23,
+    "tool_version": "1.0.0"
+  }
+}
+```
+
+---
+
+## Error Handling
+
+```python
+try:
+    result = tu.run({
+        "name": "some_tool",
+        "arguments": {"param": "value"}
+    })
+except ToolNotFoundError as e:
+    print(f"Tool not found: {e}")
+except InvalidArgumentError as e:
+    print(f"Invalid arguments: {e}")
+except ToolExecutionError as e:
+    print(f"Execution failed: {e}")
+```
+
+---
+
+## Type Hints
+
+```python
+from typing import Dict, List, Any, Optional
+
+def run_tool(
+    tu: ToolUniverse,
+    tool_name: str,
+    arguments: Dict[str, Any]
+) -> Any:
+    """Execute a tool with type-safe arguments."""
+    return tu.run({
+        "name": tool_name,
+        "arguments": arguments
+    })
+```
+
+---
+
+## Best Practices
+
+1. **Initialize Once**: Create a single ToolUniverse instance and reuse it
+2. **Load Tools Early**: Call `load_tools()` once at startup
+3. **Cache Tool Info**: Store frequently used tool information
+4. **Error Handling**: Always wrap tool execution in try-except blocks
+5. **Type Validation**: Validate argument types before execution
+6. **Resource Management**: Consider rate limits for remote APIs
+7. **Logging**: Enable logging for production environments