Tool Registry API - Implementation Summary#
Overview#
Successfully refactored the AI API to support a tool registry where tools are defined once in the constructor and then referenced by name in a type-safe manner throughout the application.
Key Changes#
1. Tool Registry in Constructor#
Before:
const ai = new AI({
adapters: { /* ... */ }
});
// Had to pass full tool definitions every time
ai.chat({
messages: [...],
tools: [
{ type: "function", function: { name: "get_weather", ... }, execute: ... },
{ type: "function", function: { name: "calculate", ... }, execute: ... },
],
});
After:
const ai = new AI({
adapters: { /* ... */ },
tools: {
get_weather: {
type: "function" as const,
function: { name: "get_weather", ... },
execute: async (args) => { ... },
},
calculate: {
type: "function" as const,
function: { name: "calculate", ... },
execute: async (args) => { ... },
},
},
});
// Reference by name - type-safe!
ai.chat({
messages: [...],
tools: ["get_weather", "calculate"], // ← Type-safe string array!
});
2. Type System Updates#
Added new generic parameter to AI class:
class AI<T extends AdapterMap, TTools extends ToolRegistry>
Where:
T- Adapter map (existing)TTools- Tool registry (new!)
3. Type-Safe Tool Names#
Tool names are extracted from the registry type:
type ToolNames<TTools extends ToolRegistry> = keyof TTools & string;
TypeScript provides:
- ✅ Autocomplete for tool names
- ✅ Compile-time validation
- ✅ Refactoring safety
4. Updated Method Signatures#
All chat methods now accept tool names instead of full tool objects:
// ChatOptionsWithAdapter
type ChatOptionsWithAdapter<TAdapters, TTools> = {
// ... other options
tools?: ReadonlyArray<ToolNames<TTools>>; // ← Type-safe tool names!
};
5. Internal Tool Resolution#
New helper methods:
class AI {
getTool(name: ToolNames<TTools>): Tool; // Get single tool
get toolNames(): Array<ToolNames<TTools>>; // List all tool names
private getToolsByNames(names: ToolNames<TTools>[]): Tool[]; // Convert names to objects
}
API Examples#
Basic Usage#
const ai = new AI({
adapters: {
openai: new OpenAIAdapter({ apiKey: "..." }),
},
tools: {
get_weather: { /* ... */ },
calculate: { /* ... */ },
},
});
// Use specific tools
await ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [...],
tools: ["get_weather"], // ← Type-safe!
});
// Use multiple tools
await ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [...],
tools: ["get_weather", "calculate"], // ← Both validated!
});
// No tools
await ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [...],
// No tools specified
});
With Streaming#
const stream = ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [...],
tools: ["get_weather", "calculate"],
as: "stream" as const,
});
for await (const chunk of stream) {
// Handle chunks
}
With HTTP Response#
return ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [...],
tools: ["get_weather", "search_products"],
as: "response" as const,
});
Real-World Example: api.tanchat.ts#
Before:
const tools: Tool[] = [
{ type: "function", function: { name: "getGuitars", ... }, execute: ... },
{ type: "function", function: { name: "recommendGuitar", ... }, execute: ... },
];
const ai = new AI({ adapters: { /* ... */ } });
ai.chat({
messages: [...],
tools, // ← Pass array of Tool objects
});
After:
const tools = {
getGuitars: {
type: "function" as const,
function: { name: "getGuitars", ... },
execute: async () => { ... },
},
recommendGuitar: {
type: "function" as const,
function: { name: "recommendGuitar", ... },
execute: async (args) => { ... },
},
} as const;
const ai = new AI({
adapters: { /* ... */ },
tools, // ← Register once!
});
ai.chat({
messages: [...],
tools: ["getGuitars", "recommendGuitar"], // ← Type-safe names!
as: "response" as const,
});
Benefits#
1. Type Safety#
- ✅ Autocomplete for tool names in IDE
- ✅ Compile-time errors for invalid tool names
- ✅ Refactoring support (rename tools safely)
2. Better Organization#
- ✅ Centralized tool definitions
- ✅ Single source of truth
- ✅ Easy to maintain and update
3. Code Reusability#
- ✅ Define tools once, use everywhere
- ✅ Share tools across different chat calls
- ✅ No duplication
4. Developer Experience#
- ✅ Cleaner code (tool names vs full objects)
- ✅ Less typing (just reference by name)
- ✅ Better readability
5. Runtime Safety#
- ✅ Validation that tools exist
- ✅ Clear error messages
- ✅ No silent failures
Implementation Details#
Type System#
// Tool registry type
type ToolRegistry = Record<string, Tool>;
// Extract tool names
type ToolNames<TTools extends ToolRegistry> = keyof TTools & string;
// AI class with tool registry
class AI<T extends AdapterMap, TTools extends ToolRegistry> {
private tools: TTools;
constructor(config: AIConfig<T, TTools>) {
this.tools = config.tools || {} as TTools;
}
private getToolsByNames(names: ReadonlyArray<ToolNames<TTools>>): Tool[] {
return names.map(name => this.getTool(name));
}
}
Chat Options#
type ChatOptionsWithAdapter<TAdapters, TTools> = {
adapter: keyof TAdapters;
model: ExtractModels<TAdapters[adapter]>;
messages: Message[];
tools?: ReadonlyArray<ToolNames<TTools>>; // ← Tool names, not objects
// ... other options
};
Internal Resolution#
When chat() is called:
- Extract tool names from options
- Convert tool names to Tool objects using
getToolsByNames() - Pass Tool objects to adapter methods
- Adapters work with full Tool objects (no changes needed)
Files Changed#
Core Implementation#
- ✅
packages/ai/src/ai.ts- Added
TToolsgeneric parameter toAIclass - Added
ToolRegistryandToolNamestypes - Updated
ChatOptionsWithAdapterandChatOptionsWithFallback - Added
getTool(),toolNames, andgetToolsByNames()methods - Updated
chatPromise()andchatStream()to convert tool names
- Added
Documentation#
- ✅
docs/TOOL_REGISTRY.md- Comprehensive guide - ✅
docs/TOOL_REGISTRY_QUICK_START.md- Quick reference - ✅
examples/tool-registry-example.ts- Full examples
Example Updates#
- ✅
examples/ts-chat/src/routes/demo/api.tanchat.ts- Updated to use tool registry
Migration Guide#
Step 1: Convert Tool Array to Registry#
// Before
const tools: Tool[] = [
{ type: "function", function: { name: "tool1", ... } },
{ type: "function", function: { name: "tool2", ... } },
];
// After
const tools = {
tool1: { type: "function" as const, function: { name: "tool1", ... } },
tool2: { type: "function" as const, function: { name: "tool2", ... } },
} as const; // ← Important!
Step 2: Register Tools in Constructor#
// Before
const ai = new AI({ adapters: { /* ... */ } });
// After
const ai = new AI({
adapters: { /* ... */ },
tools, // ← Add tools here
});
Step 3: Use Tool Names in Chat Calls#
// Before
ai.chat({
messages: [...],
tools: tools, // ← Full array
});
// After
ai.chat({
messages: [...],
tools: ["tool1", "tool2"], // ← Just names!
});
Testing#
Verify type safety:
const ai = new AI({
adapters: { /* ... */ },
tools: {
get_weather: { /* ... */ },
calculate: { /* ... */ },
},
});
// ✅ Should work
ai.chat({ messages: [], tools: ["get_weather"] });
// ❌ Should show TypeScript error
ai.chat({ messages: [], tools: ["invalid_tool"] });
Performance#
No performance impact:
- Tool name resolution happens once per chat call
- Minimal overhead (simple object lookup)
- Tool execution unchanged
Backward Compatibility#
Breaking Change: This is a breaking change. Users must:
- Convert tool arrays to registries
- Register tools in constructor
- Use tool names instead of objects
However, the migration path is straightforward and provides significant benefits.
Future Enhancements#
Potential improvements:
- Tool namespaces (e.g.,
weather.get,weather.forecast) - Tool permissions/access control
- Tool versioning
- Dynamic tool registration
- Tool composition/chaining
Summary#
The Tool Registry API provides:
✅ Type-Safe Tool References - Autocomplete and validation ✅ Centralized Management - Define once, use everywhere ✅ Cleaner Code - Reference by name instead of objects ✅ Better Reusability - Share tools across chats ✅ Runtime Validation - Clear error messages ✅ Developer Experience - Improved DX with less code
Result: More maintainable, type-safe, and developer-friendly tool management! 🎉