PackageToolSet

The PackageToolSet provides package and tool discovery capabilities with keyword and semantic search support for Pantheon workspaces.

Overview

Key features:

• Package Discovery: List and search available packages

• Tool Search: Find tools using keyword or semantic search

• LLM-Based Matching: Intelligent semantic search using LLM

• MCP Integration: Works with MCP-based packages

Basic Usage

from pantheon.agent import Agent
from pantheon.toolsets import PackageToolSet

# Create package toolset
package_tools = PackageToolSet(
    name="packages",
    workdir="/path/to/workspace",
    enable_semantic_search=True
)

# Create agent and add toolset at runtime
agent = Agent(
    name="assistant",
    instructions="You can find and use available tools and packages."
)
await agent.toolset(package_tools)

await agent.chat()

Constructor Parameters

Parameter	Type	Description
name	str	Name of the toolset
workdir	str | Path | None	Workspace root directory. Packages are stored in .pantheon/packages.
enable_semantic_search	bool	Enable LLM-based semantic search (default: True)
semantic_model	str	Model for semantic search (default: “low” for cost efficiency)

Tools Reference

search_tools

Search for extended tools using keyword or semantic search.

# Semantic search (default)
result = await package_tools.search_tools(
    query="convert CSV to Excel",
    semantic=True,
    top_k=5
)

# Keyword search
result = await package_tools.search_tools(
    query="export",
    semantic=False,
    top_k=10
)

# List all tools
result = await package_tools.search_tools()

Parameters:

• query: Search query (natural language or keywords). None returns all tools.

• semantic: Use LLM-based semantic search (default: True)

• top_k: Maximum number of results

• use_context: Use conversation history for context-aware search

Returns:

{
    "success": True,
    "tools": [
        {
            "package": "data_tools",
            "method": "csv_to_excel",
            "signature": "(input_path: str, output_path: str)",
            "doc": "Convert CSV file to Excel format",
            "async": True,
            "call_example": "await packages.data_tools.csv_to_excel(...)"
        }
    ]
}

search_packages (Internal)

List and search packages (not exposed to LLM, used by UI/API):

# List all packages
result = await package_tools.search_packages()

# Filter by keyword
result = await package_tools.search_packages(query="data")

Returns:

{
    "success": True,
    "packages": [
        {
            "name": "data_tools",
            "description": "Data processing utilities",
            "methods": ["csv_to_excel", "json_to_yaml"],
            "status": "ready",
            "origin": "user"
        }
    ]
}

Using Discovered Tools

After finding tools, use them in Python code:

from pantheon.packages import packages as pp

# Interactive (Notebook/IPython)
result = await pp.packages.data_tools.csv_to_excel(
    input_path="data.csv",
    output_path="data.xlsx"
)

# Standalone script
import asyncio

async def main():
    return await pp.packages.data_tools.csv_to_excel(
        input_path="data.csv",
        output_path="data.xlsx"
    )

result = asyncio.run(main())

Package API

Discover packages directly using the package API:

from pantheon.packages import packages as pp

# List all packages
packages = await pp.packages.list_packages()

# Get package details
info = pp.packages.describe("data_tools")

Examples

Finding Data Processing Tools

# Find tools for data conversion
result = await package_tools.search_tools(
    query="convert data between formats like CSV, JSON, Excel"
)

for tool in result["tools"]:
    print(f"{tool['package']}.{tool['method']}: {tool['doc']}")

Context-Aware Search

# After discussing a task in conversation
result = await package_tools.search_tools(
    query="find something similar to what we discussed",
    use_context=True  # Uses conversation history
)

Agent-Driven Tool Discovery

from pantheon.agent import Agent
from pantheon.toolsets import PackageToolSet

package_tools = PackageToolSet(name="packages")

assistant = Agent(
    name="assistant",
    instructions="""When users need functionality:
    1. Use search_tools to find relevant packages
    2. Explain what tools are available
    3. Show how to use them with code examples"""
)
await assistant.toolset(package_tools)

result = await assistant.run(
    "I need to process some CSV files and convert them to different formats"
)

Best Practices

1. Use semantic search: Better results for natural language queries

2. Combine with code: Build complete programs using discovered tools

3. Check async status: Use await for async tools

4. Limit results: Use top_k for focused results

5. Explore packages: Use describe() for detailed method info