Bash Mode + Flexible Tool Descriptions + Registry-Based Tool Management

[pk8189]

Overview

This PR introduces a comprehensive system for organizing, customizing, and managing pctx tool descriptions across all AI frameworks (LangChain, CrewAI, OpenAI Agents SDK, Pydantic AI). It adds filesystem-based SDK exploration as a first-class workflow alongside the traditional discovery tools, making tool descriptions fully customizable and enabling arbitrary tool combinations.

What's New

1. Filesystem Mode for SDK Exploration

Added execute_bash and execute_typescript tools that present the TypeScript SDK as an in-memory filesystem, enabling exploration using familiar bash commands:

# New "fs" mode
tools = pctx.langchain_tools("fs")
# Returns: [execute_bash, execute_typescript]

Workflow:

1. Use execute_bash to explore: cat README.md, ls Tools/, grep -r "functionName"
2. Examine type definitions: cat Tools/functionName.d.ts
3. Execute code with execute_typescript using the discovered functions

This provides an alternative to the traditional list_functions → get_function_details → execute workflow, particularly useful for developers who prefer command-line exploration.

2. Organized Tool Description System

Tool descriptions are now organized into styles that users can choose between:

pctx_client/tool_descriptions/
├── prescriptive/                  # Detailed, workflow-focused (default)
│   ├── execute_bash.py           # "Explore SDK filesystem..."
│   ├── execute_typescript.py     # "Execute TypeScript code..."
│   └── ...
└── terminal/                      # Concise, technical style
    ├── execute_bash.py           # "Run bash in Deno sandbox"
    └── ...

Users can swap styles:

from pctx_client.tool_descriptions import TERMINAL_STYLE_DESCRIPTIONS

tools = pctx.langchain_tools(descriptions=TERMINAL_STYLE_DESCRIPTIONS)

3. Tool Registry Pattern (Maintainability)

Refactored tool registration from 24 scattered if-statements across 4 framework adapters to a single registry with exhaustive validation.

4. Mix-and-Match Tool Configurations

Users can create arbitrary tool combinations for custom workflows:

from pctx_client.tools import ToolConfig

# Just bash exploration (no execution)
explore_only = ToolConfig(tools=["execute_bash"])

# Search-first workflow
search_workflow = ToolConfig(
    tools=["search_functions", "get_function_details", "execute"],
    descriptions={"search_functions": "Find SDK functions by keyword..."}
)

# Hybrid: bash exploration + traditional discovery
hybrid = ToolConfig(
    tools=["execute_bash", "list_functions", "execute"]
)

5. Workflow Guidance System

Added contextual prompts that help AI agents understand tool combinations:

from pctx_client.tool_descriptions.workflows import get_workflow_prompt

# Generates workflow guidance
prompt = get_workflow_prompt(["execute_bash", "execute_typescript"])
# "1. Use execute_bash to explore the SDK filesystem...
#  2. Then use execute_typescript to run your code..."

Examples: Before & After

Example 1: Filesystem Exploration

Before: Only one workflow (list → get_details → execute)

After:

# Option A: Preset filesystem mode
tools = pctx.langchain_tools("fs")

# Option B: Custom descriptions
fs_custom = ToolConfig(
    tools=["execute_bash", "execute_typescript"],
    descriptions={
        "execute_bash": "Explore SDK using bash: cat, ls, grep..."
    }
)
tools = pctx.langchain_tools(fs_custom)

Example 2: Description Styles

Before: Descriptions hardcoded, no alternatives

After:

from pctx_client.tool_descriptions import (
    PRESCRIPTIVE_DESCRIPTIONS,  # Detailed (default)
    TERMINAL_STYLE_DESCRIPTIONS # Concise
)

# Concise technical style
tools = pctx.langchain_tools(descriptions=TERMINAL_STYLE_DESCRIPTIONS)

# Mix styles
mixed = {
    "execute_bash": TERMINAL_STYLE_DESCRIPTIONS["execute_bash"],
    "execute": PRESCRIPTIVE_DESCRIPTIONS["execute"],
}
tools = pctx.langchain_tools(descriptions=mixed)

Example 3: Single-Tool Use Case

Before: Had to include full preset mode

After:

# Just execute (user already knows the SDK)
tools = pctx.langchain_tools(ToolConfig(tools=["execute"]))

# Just bash (exploration only)
tools = pctx.langchain_tools(ToolConfig(tools=["execute_bash"]))

Technical Details

Files Changed

New:

• pctx-py/src/pctx_client/_tool_registry.py - Central tool registry with validation
• pctx-py/src/pctx_client/tools.py - ToolConfig dataclass, mode definitions
• pctx-py/src/pctx_client/tool_descriptions/ - Organized description styles
  • prescriptive/*.py - Detailed descriptions (default)
  • terminal/*.py - Concise descriptions
  • workflows.py - Workflow guidance generator

Modified:

• pctx-py/src/pctx_client/_client.py - Refactored 4 framework adapters to use registry
• pctx-py/tests/test_tool_converters.py - Added 14 new tests (66 total)

Test Coverage

New test classes:

• TestToolRegistry (3 tests) - Registry validation
• TestToolConfigMixAndMatch (11 tests) - Custom combinations

Coverage includes: single tool configs across all frameworks, filesystem mode (execute_bash + execute_typescript), custom tool combinations, custom descriptions with ToolConfig, all 6 tools simultaneously, cross-framework consistency, and edge cases (empty lists, duplicates, ordering).

Result: 66 tests passing (up from 52)

Migration Guide

This is 100% backward compatible:

# All existing code still works
pctx.langchain_tools()                 # Default tools
pctx.langchain_tools("fs")             # NEW: Filesystem mode
pctx.langchain_tools(descriptions={})  # Custom descriptions

New capabilities:

from pctx_client.tools import ToolConfig
from pctx_client.tool_descriptions import TERMINAL_STYLE_DESCRIPTIONS

# Use filesystem mode with custom descriptions
pctx.langchain_tools("fs", descriptions=TERMINAL_STYLE_DESCRIPTIONS)

# Create custom combinations
pctx.langchain_tools(ToolConfig(
    tools=["execute_bash", "list_functions", "execute"],
    descriptions={"execute_bash": "Custom description"}
))

Benefits Summary

For Users:

• Choice: Filesystem exploration vs traditional discovery workflows
• Customization: Override any tool description
• Flexibility: Mix and match tools for custom workflows
• Discoverability: All descriptions organized by style

For Maintainers:

• Reliability: Registry validates completeness at import time
• Cleaner code: Reduced duplication (~200 lines removed)
• Type safety: Registry keys are ToolName literals
• Maintainability: Adding tools requires 1 registry entry, not 4 if-statements