HelpingAI Python SDK

The official Python library for the HelpingAI API - Advanced AI with Emotional Intelligence

🚀 Features

• Function-Calling Friendly API: Drop-in replacement with familiar interface
• Emotional Intelligence: Advanced AI models with emotional understanding
• MCP Integration: Seamless connection to external tools via Model Context Protocol servers
• Tool Calling Made Easy: @tools decorator for effortless function-to-tool conversion
• Direct Tool Execution: Simple .call() method for executing tools without registry manipulation
• Automatic Schema Generation: Type hint-based JSON schema creation with docstring parsing
• Universal Tool Compatibility: Seamless integration with standard tool definition schemas
• Streaming Support: Real-time response streaming
• Comprehensive Error Handling: Detailed error types and retry mechanisms
• Type Safety: Full type hints and IDE support
• Flexible Configuration: Environment variables and direct initialization

📦 Installation

pip install HelpingAI

Optional Features

# Install with MCP (Model Context Protocol) support
pip install HelpingAI[mcp]

🔑 Authentication

Get your API key from the HelpingAI Dashboard.

Environment Variable (Recommended)

export HAI_API_KEY='your-api-key'

Direct Initialization

fromHelpingAIimportHAIhai=HAI(api_key='your-api-key')

🎯 Quick Start

fromHelpingAIimportHAI# Initialize clienthai=HAI()
# Create a chat completionresponse=hai.chat.completions.create(
model="Dhanishtha-2.0-preview",
messages=[
{"role": "system", "content": "You are an expert in emotional intelligence."},
{"role": "user", "content": "What makes a good leader?"}
]
)
print(response.choices[0].message.content)

🌊 Streaming Responses

# Stream responses in real-timeforchunkinhai.chat.completions.create(
model="Dhanishtha-2.0-preview",
messages=[{"role": "user", "content": "Tell me about empathy"}],
stream=True
):
ifchunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")

⚙️ Advanced Configuration

Parameter Control

response=hai.chat.completions.create(
model="Dhanishtha-2.0-preview",
messages=[{"role": "user", "content": "Write a story about empathy"}],
temperature=0.7, # Controls randomness (0-1)max_tokens=500, # Maximum length of responsetop_p=0.9, # Nucleus sampling parameterfrequency_penalty=0.3, # Reduces repetitionpresence_penalty=0.3, # Encourages new topicshide_think=True# Filter out reasoning blocks
)

Client Configuration

hai=HAI(
api_key="your-api-key",
base_url="https://api.helpingai.co/v1", # Custom base URLtimeout=30.0, # Request timeoutorganization="your-org-id"# Organization ID
)

🛡️ Error Handling

fromHelpingAIimportHAI, HAIError, RateLimitError, InvalidRequestErrorimporttimedefmake_completion_with_retry(messages, max_retries=3):
forattemptinrange(max_retries):
try:
returnhai.chat.completions.create(
model="Dhanishtha-2.0-preview",
messages=messages
)
exceptRateLimitErrorase:
ifattempt==max_retries-1:
raisetime.sleep(e.retry_afteror1)
exceptInvalidRequestErrorase:
print(f"Invalid request: {str(e)}")
raiseexceptHAIErrorase:
print(f"API error: {str(e)}")
raise

🤖 Available Models

Dhanishtha-2.0-preview

• World's First Intermediate Thinking Model: Multi-phase reasoning with self-correction capabilities
• Unique Features: Multiple <think>...</think> blocks for transparent reasoning, structured emotional reasoning (SER)
• Best For: Complex problem-solving, analytical tasks, educational content, reasoning-heavy applications

Dhanishtha-2.0-preview-mini

• Lightweight Reasoning Model: Efficient version of Dhanishtha-2.0-preview
• Unique Features: Same reasoning capabilities in a more compact model
• Best For: Faster responses, mobile applications, resource-constrained environments

Helpingai3-raw

• Advanced Emotional Intelligence Model: Enhanced contextual awareness with emotional reasoning capabilities
• Unique Features: Advanced language understanding, emotional intelligence, therapeutic exchanges support
• Best For: Conversational AI, emotional support, content creation, general-purpose tasks

HELVETE-X

• 🔞 18+ Role-Playing Model: Highly advanced NSFW model with unrestricted capabilities
• Unique Features: Badass personality, uncensored responses, advanced role-playing abilities
• Best For: Adult role-playing scenarios, creative writing, mature content generation
• ⚠️ Warning: 18+ only - Contains mature/explicit content

Dhanishtha-NSFW

• 🔞 18+ Intermediate Thinking Model: Similar to Dhanishtha-2.0-preview but with NSFW capabilities and role-playing specialization
• Unique Features: Multiple <think>...</think> blocks for transparent reasoning, structured emotional reasoning (SER), plus mature content handling
• Best For: Adult conversations, NSFW role-playing scenarios, mature content creation with advanced reasoning
• ⚠️ Warning: 18+ only - Contains mature/explicit content

# List all available modelsmodels=hai.models.list()
formodelinmodels:
print(f"Model: {model.id} - {model.description}")
# Get specific model infomodel=hai.models.retrieve("Dhanishtha-2.0-preview")
print(f"Model: {model.name}")
# Use Dhanishtha-2.0 for complex reasoningresponse=hai.chat.completions.create(
model="Dhanishtha-2.0-preview",
messages=[{"role": "user", "content": "Solve this step by step: What's 15% of 240?"}],
hide_think=False# Show reasoning process
)

🛠️ MCP (Model Context Protocol) Integration

Connect to external tools and services through MCP servers for expanded AI capabilities.

Quick Start with MCP

fromHelpingAIimportHAIclient=HAI(api_key="your-api-key")
# Configure MCP serverstools= [
{
'mcpServers': {
'time': {
'command': 'uvx',
'args': ['mcp-server-time', '--local-timezone=Asia/Shanghai']
},
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
]
# Use MCP tools in chat completionresponse=client.chat.completions.create(
model="Dhanishtha-2.0-preview",
messages=[{"role": "user", "content": "What time is it in Shanghai?"}],
tools=tools
)
print(response.choices[0].message.content)

Supported Server Types

# Stdio-based servers (most common)
{
'command': 'uvx',
'args': ['mcp-server-time'],
'env': {'TIMEZONE': 'UTC'} # optional
}
# HTTP SSE servers
{
'url': 'https://api.example.com/mcp',
'headers': {'Authorization': 'Bearer token'},
'sse_read_timeout': 300
}
# Streamable HTTP servers
{
'type': 'streamable-http',
'url': 'http://localhost:8000/mcp'
}

Popular MCP Servers

• mcp-server-time - Time and timezone operations
• mcp-server-fetch - HTTP requests and web scraping
• mcp-server-filesystem - File system operations
• mcp-server-memory - Persistent memory across conversations
• mcp-server-sqlite - SQLite database operations
• Custom servers - Any MCP-compliant server

Combined Usage

Mix MCP servers with regular tools:

# Regular tool definitionsregular_tools= [{
"type": "function",
"function": {
"name": "calculate",
"description": "Perform calculations",
"parameters": {
"type": "object",
"properties": {
"expression": {"type": "string"}
}
}
}
}]
# Combined with MCP serversall_tools=regular_tools+ [{
'mcpServers': {
'time': {
'command': 'uvx',
'args': ['mcp-server-time']
}
}
}]
response=client.chat.completions.create(
model="Dhanishtha-2.0-preview",
messages=[{"role": "user", "content": "Calculate 2+2 and tell me the current time"}],
tools=all_tools
)

Installation & Setup

# Install MCP support
pip install HelpingAI[mcp]
# Or install MCP package separately
pip install -U mcp

Note: MCP functionality requires the mcp package. The SDK provides graceful error handling when MCP is not installed.

🔧 Tool Calling with @tools Decorator

Transform any Python function into a powerful AI tool with zero boilerplate using the @tools decorator.

Quick Start with Tools

fromHelpingAIimportHAIfromHelpingAI.toolsimporttools, get_tools@toolsdefget_weather(city: str, units: str="celsius") ->str:
"""Get current weather information for a city. Args: city: The city name to get weather for units: Temperature units (celsius or fahrenheit) """# Your weather API logic herereturnf"Weather in {city}: 22°{units[0].upper()}"@toolsdefcalculate_tip(bill_amount: float, tip_percentage: float=15.0) ->dict:
"""Calculate tip and total amount for a bill. Args: bill_amount: The original bill amount tip_percentage: Tip percentage (default: 15.0) """tip=bill_amount* (tip_percentage/100)
total=bill_amount+tipreturn {"tip": tip, "total": total, "original": bill_amount}
# Use with chat completionshai=HAI()
response=hai.chat.completions.create(
model="Dhanishtha-2.0-preview",
messages=[{"role": "user", "content": "What's the weather in Paris and calculate tip for $50 bill?"}],
tools=get_tools() # Automatically includes all @tools functions
)
print(response.choices[0].message.content)

Direct Tool Execution

The HAI client provides a convenient .call() method to directly execute tools without having to manually use the registry:

fromHelpingAIimportHAIfromHelpingAI.toolsimporttools@toolsdefsearch(query: str, max_results: int=5):
"""Search the web for information"""# Implementation herereturn {"results": [{"title": "Result 1", "url": "https://example.com"}]}
# Create a client instanceclient=HAI()
# Directly call a tool by name with argumentssearch_result=client.call("search", {"query": "python programming", "max_results": 3})
print("Search results:", search_result)
# You can also execute tools from model responsesresponse=client.chat.completions.create(
model="Dhanishtha-2.0-preview",
messages=[{"role": "user", "content": "search for quantum computing"}],
tools=get_tools(),
tool_choice="auto"
)
# Extract tool name and arguments from the model's tool calltool_call=response.choices[0].message.tool_calls[0]
tool_name=tool_call.function.nametool_args=json.loads(tool_call.function.arguments)
# Execute the tool directlytool_result=client.call(tool_name, tool_args)
print(f"Result: {tool_result}")

Advanced Tool Features

Type System Support

The @tools decorator automatically generates JSON schemas from Python type hints:

fromtypingimportList, Optional, UnionfromenumimportEnumclassPriority(Enum):
LOW="low"MEDIUM="medium"HIGH="high"@toolsdefcreate_task(
title: str,
description: Optional[str] =None,
priority: Priority=Priority.MEDIUM,
tags: List[str] =None,
due_date: Union[str, None] =None
) ->dict:
"""Create a new task with advanced type support. Args: title: Task title description: Optional task description priority: Task priority level tags: List of task tags due_date: Due date in YYYY-MM-DD format """return {
"title": title,
"description": description,
"priority": priority.value,
"tags": tagsor [],
"due_date": due_date
}

Tool Registry Management

fromHelpingAI.toolsimportget_tools, get_registry, clear_registry# Get specific toolsweather_tools=get_tools(["get_weather", "calculate_tip"])
# Registry inspectionregistry=get_registry()
print(f"Registered tools: {registry.list_tool_names()}")
print(f"Total tools: {registry.size()}")
# Check if tool existsifregistry.has_tool("get_weather"):
weather_tool=registry.get_tool("get_weather")
print(f"Tool: {weather_tool.name} - {weather_tool.description}")

Universal Tool Compatibility

Seamlessly combine @tools functions with existing standard tool definitions:

fromHelpingAI.toolsimportmerge_tool_lists, ensure_tool_format# Existing standard tool definitionslegacy_tools= [{
"type": "function",
"function": {
"name": "search_web",
"description": "Search the web for information",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"}
},
"required": ["query"]
}
}
}]
# Combine with @tools functionscombined_tools=merge_tool_lists(
legacy_tools, # Existing toolsget_tools(), # @tools functions"math"# Category name (if you have categorized tools)
)
# Use in chat completionresponse=hai.chat.completions.create(
model="Dhanishtha-2.0-preview",
messages=[{"role": "user", "content": "Help me with weather, calculations, and web search"}],
tools=combined_tools
)

Error Handling & Best Practices

fromHelpingAI.toolsimportToolExecutionError, SchemaValidationError, ToolRegistrationError@toolsdefdivide_numbers(a: float, b: float) ->float:
"""Divide two numbers safely. Args: a: The dividend  b: The divisor """ifb==0:
raiseValueError("Cannot divide by zero")
returna/b# Handle tool execution in your applicationdefexecute_tool_safely(tool_name: str, arguments: dict):
try:
# You can use the direct call method instead of registry manipulationhai=HAI()
returnhai.call(tool_name, arguments)
exceptToolExecutionErrorase:
print(f"Tool execution failed: {e}")
return {"error": str(e)}
exceptSchemaValidationErrorase:
print(f"Invalid arguments: {e}")
return {"error": "Invalid parameters provided"}
exceptToolRegistrationErrorase:
print(f"Tool registration issue: {e}")
return {"error": "Tool configuration error"}
# Example usageresult=execute_tool_safely("divide_numbers", {"a": 10, "b": 2})
print(result) # 5.0error_result=execute_tool_safely("divide_numbers", {"a": 10, "b": 0})
print(error_result) # {"error": "Cannot divide by zero"}

Migration from Legacy Tools

Transform your existing tool definitions with minimal effort:

Before (Manual Schema):

tools= [{
"type": "function",
"function": {
"name": "get_weather", "description": "Get weather information",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"},
"units": {"type": "string", "description": "Temperature units", "enum": ["celsius", "fahrenheit"]}
},
"required": ["city"]
}
}
}]

After (@tools Decorator):

fromtypingimportLiteral@toolsdefget_weather(city: str, units: Literal["celsius", "fahrenheit"] ="celsius") ->str:
"""Get weather information Args: city: City name units: Temperature units """# Implementation herepass

The @tools decorator automatically:

• ✅ Generates JSON schema from type hints
• ✅ Extracts descriptions from docstrings
• ✅ Handles required/optional parameters
• ✅ Supports multiple docstring formats (Google, Sphinx, NumPy)
• ✅ Provides comprehensive error handling
• ✅ Maintains thread-safe tool registry

📚 Documentation

Comprehensive documentation is available:

• 📖 Getting Started Guide - Installation and basic usage
• 🔧 API Reference - Complete API documentation
• 🛠️ Tool Calling Guide - Creating and using AI-callable tools
• 🔌 MCP Integration Guide - Model Context Protocol integration
• 💡 Examples - Code examples and use cases
• ❓ FAQ - Frequently asked questions

🔧 Requirements

• Python: 3.7-3.14
• Dependencies:
  • requests - HTTP client
  • typing_extensions - Type hints support

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support & Community

• Issues: GitHub Issues
• Documentation: HelpingAI Docs
• Dashboard: HelpingAI Dashboard
• Email: Team@helpingai.co

Built with ❤️ by the HelpingAI Team

Empowering AI with Emotional Intelligence