1+ #!/usr/bin/env python3
2+ """
3+ HelpingAI Tool Usage Examples
4+
5+ This script demonstrates proper usage patterns for the HelpingAI client,
6+ specifically addressing common issues with tool configuration and API requests.
7+
8+ Common Issues Addressed:
9+ 1. Tool conversion errors - "Unsupported tools format"
10+ 2. HTTP 400 errors suggesting stream=True
11+ 3. Proper tool format specifications
12+ """
13+
14+ import os
15+ import sys
16+
17+ # Add parent directory to path for development
18+ sys .path .insert (0 , os .path .dirname (os .path .dirname (os .path .abspath (__file__ ))))
19+
20+ from HelpingAI import HAI
21+
22+ def example_built_in_tools ():
23+ """Example: Using built-in tools correctly."""
24+ print ("=== Example 1: Built-in Tools ===" )
25+
26+ client = HAI (api_key = os .getenv ("HAI_API_KEY" , "your-api-key" ))
27+
28+ # ✅ CORRECT: Use built-in tool names as strings
29+ tools = ["code_interpreter" , "web_search" ]
30+
31+ try :
32+ response = client .chat .completions .create (
33+ model = "HelpingAI2.5-10B" ,
34+ messages = [{"role" : "user" , "content" : "What's 2+2 and search for Python tutorials?" }],
35+ tools = tools ,
36+ stream = False # Try stream=True if you get HTTP 400 errors
37+ )
38+ print ("✅ Request successful with built-in tools" )
39+
40+ except Exception as e :
41+ print (f"❌ Error: { e } )
42+ if "400" in str (e ) and "stream" in str (e ).lower ():
43+ print ("💡 Tip: Try setting stream=True" )
44+
45+ def example_openai_format_tools ():
46+ """Example: Using OpenAI-format tools correctly."""
47+ print ("\n === Example 2: OpenAI Format Tools ===" )
48+
49+ client = HAI (api_key = os .getenv ("HAI_API_KEY" , "your-api-key" ))
50+
51+ # ✅ CORRECT: OpenAI tool format
52+ tools = [
53+ {
54+ "type" : "function" ,
55+ "function" : {
56+ "name" : "calculate" ,
57+ "description" : "Perform basic math calculations" ,
58+ "parameters" : {
59+ "type" : "object" ,
60+ "properties" : {
61+ "expression" : {
62+ "type" : "string" ,
63+ "description" : "Math expression to evaluate"
64+ }
65+ },
66+ "required" : ["expression" ]
67+ }
68+ }
69+ }
70+ ]
71+
72+ try :
73+ response = client .chat .completions .create (
74+ model = "HelpingAI2.5-10B" ,
75+ messages = [{"role" : "user" , "content" : "Calculate 15 * 23" }],
76+ tools = tools
77+ )
78+ print ("✅ Request successful with OpenAI format tools" )
79+
80+ except Exception as e :
81+ print (f"❌ Error: { e } )
82+
83+ def example_mcp_tools ():
84+ """Example: Using MCP (Model Context Protocol) tools correctly."""
85+ print ("\n === Example 3: MCP Tools ===" )
86+
87+ client = HAI (api_key = os .getenv ("HAI_API_KEY" , "your-api-key" ))
88+
89+ # ✅ CORRECT: MCP server configuration
90+ tools = [
91+ {
92+ 'mcpServers' : {
93+ 'time' : {
94+ 'command' : 'uvx' ,
95+ 'args' : ['mcp-server-time' ]
96+ },
97+ 'fetch' : {
98+ 'command' : 'uvx' ,
99+ 'args' : ['mcp-server-fetch' ]
100+ }
101+ }
102+ }
103+ ]
104+
105+ try :
106+ response = client .chat .completions .create (
107+ model = "HelpingAI2.5-10B" ,
108+ messages = [{"role" : "user" , "content" : "What time is it?" }],
109+ tools = tools
110+ )
111+ print ("✅ Request successful with MCP tools" )
112+
113+ except ImportError :
114+ print ("❌ MCP dependencies not installed. Run: pip install 'HelpingAI[mcp]'" )
115+ except Exception as e :
116+ print (f"❌ Error: { e } )
117+
118+ def example_mixed_tools ():
119+ """Example: Mixing different tool types correctly."""
120+ print ("\n === Example 4: Mixed Tools ===" )
121+
122+ client = HAI (api_key = os .getenv ("HAI_API_KEY" , "your-api-key" ))
123+
124+ # ✅ CORRECT: Mix built-in tools with OpenAI format
125+ tools = [
126+ "code_interpreter" , # Built-in tool
127+ {
128+ "type" : "function" ,
129+ "function" : {
130+ "name" : "custom_tool" ,
131+ "description" : "A custom tool" ,
132+ "parameters" : {"type" : "object" , "properties" : {}}
133+ }
134+ }
135+ ]
136+
137+ try :
138+ response = client .chat .completions .create (
139+ model = "HelpingAI2.5-10B" ,
140+ messages = [{"role" : "user" , "content" : "Help me with coding" }],
141+ tools = tools
142+ )
143+ print ("✅ Request successful with mixed tools" )
144+
145+ except Exception as e :
146+ print (f"❌ Error: { e } )
147+
148+ def example_streaming_usage ():
149+ """Example: Using streaming to avoid HTTP 400 errors."""
150+ print ("\n === Example 5: Streaming Usage ===" )
151+
152+ client = HAI (api_key = os .getenv ("HAI_API_KEY" , "your-api-key" ))
153+
154+ try :
155+ # If you get HTTP 400 errors, try streaming
156+ response = client .chat .completions .create (
157+ model = "HelpingAI2.5-10B" ,
158+ messages = [{"role" : "user" , "content" : "Tell me a story" }],
159+ tools = ["web_search" ],
160+ stream = True # 🔑 KEY: Enable streaming
161+ )
162+
163+ print ("✅ Streaming request initiated" )
164+
165+ # Process streaming response
166+ for chunk in response :
167+ if chunk .choices [0 ].delta .content :
168+ print (chunk .choices [0 ].delta .content , end = "" )
169+ print ("\n ✅ Streaming completed" )
170+
171+ except Exception as e :
172+ print (f"❌ Error: { e } )
173+
174+ def common_mistakes ():
175+ """Examples of common mistakes to avoid."""
176+ print ("\n === Common Mistakes to Avoid ===" )
177+
178+ # ❌ WRONG: Invalid tool names
179+ print ("❌ DON'T: Use invalid built-in tool names" )
180+ print (" tools = ['invalid_tool'] # Will cause warnings" )
181+
182+ # ❌ WRONG: Wrong data types
183+ print ("❌ DON'T: Use wrong data types for tools" )
184+ print (" tools = [1, 2, 3] # Will cause warnings" )
185+
186+ # ❌ WRONG: Incorrect format
187+ print ("❌ DON'T: Use incorrect tool format" )
188+ print (" tools = {'not': 'a list'} # Should be a list" )
189+
190+ # ✅ CORRECT alternatives
191+ print ("\n ✅ DO: Use correct formats" )
192+ print (" tools = ['code_interpreter', 'web_search'] # Built-in tools" )
193+ print (" tools = [{'type': 'function', ...}] # OpenAI format" )
194+ print (" tools = [{'mcpServers': {...}}] # MCP format" )
195+
196+ def troubleshooting_tips ():
197+ """Troubleshooting tips for common issues."""
198+ print ("\n === Troubleshooting Tips ===" )
199+
200+ print ("🔧 If you see 'Tool conversion failed' warnings:" )
201+ print (" - Check that tool names are correct (code_interpreter, web_search)" )
202+ print (" - Ensure tools are in proper format (list of strings/dicts)" )
203+ print (" - For MCP tools, install: pip install 'HelpingAI[mcp]'" )
204+
205+ print ("\n 🔧 If you get HTTP 400 'stream=True' errors:" )
206+ print (" - Try setting stream=True in your request" )
207+ print (" - Some models/endpoints require streaming" )
208+ print (" - Tool-heavy requests often need streaming" )
209+
210+ print ("\n 🔧 If you get 'Unknown built-in tool' errors:" )
211+ print (" - Available built-in tools: code_interpreter, web_search" )
212+ print (" - For custom tools, use OpenAI format with 'type': 'function'" )
213+
214+ print ("\n 🔧 For MCP tools:" )
215+ print (" - Install MCP dependencies: pip install 'HelpingAI[mcp]'" )
216+ print (" - Ensure MCP servers are properly configured" )
217+ print (" - Check server commands and arguments" )
218+
219+ if __name__ == "__main__" :
220+ print ("HelpingAI Tool Usage Examples" )
221+ print ("=" * 40 )
222+
223+ # Set up API key check
224+ if not os .getenv ("HAI_API_KEY" ):
225+ print ("⚠️ Set HAI_API_KEY environment variable to run actual requests" )
226+ print (" Examples will show structure without making API calls" )
227+ print ()
228+
229+ # Run examples
230+ example_built_in_tools ()
231+ example_openai_format_tools ()
232+ example_mcp_tools ()
233+ example_mixed_tools ()
234+ example_streaming_usage ()
235+
236+ # Show common mistakes and tips
237+ common_mistakes ()
238+ troubleshooting_tips ()
239+
240+ print ("\n ✅ For more examples, see: examples/mcp_example.py" )
241+ print ("📚 Documentation: https://helpingai.co/docs" )
0 commit comments