# HaliosAI SDK
[](https://pypi.org/project/haliosai/)
[](https://pypi.org/project/haliosai/)
[](https://opensource.org/licenses/Apache-2.0)
**HaliosAI : Ship Reliable AI Agents Faster!** 🚀🚀🚀
HaliosAI SDK helps you catch tricky AI agent failures before they reach users. It supports both offline and live guardrail checks, streaming response validation, parallel processing, and multi-agent setups. Integration is seamless - just add a simple decorator to your code. HaliosAI instantly plugs into your agent workflows, making it easy to add safety and reliability without changing your architecture.
## Features
- 🛡️ **Easy Integration**: Simple decorators and patchers for existing AI agent code
- ⚡ **Parallel Processing**: Run guardrails and agent calls simultaneously for optimal performance
- 🌊 **Streaming Support**: Real-time guardrail evaluation for streaming responses
- 🤖 **Multi-Agent Support**: Per-agent guardrail profiles for complex AI systems
- 🔧 **Framework Support**: Built-in support for OpenAI, Anthropic, and OpenAI Agents
- 📊 **Detailed Timing**: Performance metrics and execution insights
- 🚨 **Violation Handling**: Automatic blocking and detailed error reporting
## Installation
```bash
pip install haliosai
```
For specific LLM providers:
```bash
pip install haliosai[openai] # For OpenAI support
pip install haliosai[agents] # For OpenAI Agents support
pip install haliosai[all] # For all providers
```
## Prerequisites
1. **Get your API key**: Visit [console.halios.ai](https://console.halios.ai) to obtain your HaliosAI API key
2. **Create an agent**: Follow the [documentation](https://docs.halios.ai) to create your first agent and configure guardrails
3. **Keep your agent_id handy**: You'll need it for SDK integration
Set required environment variables:
```bash
export HALIOS_API_KEY="your-api-key"
export HALIOS_AGENT_ID="your-agent-id"
export OPENAI_API_KEY="your-openai-key" # For OpenAI examples
```
## Quick Start
### Basic Usage (Decorator Pattern)
```python
import asyncio
import os
from openai import AsyncOpenAI
from haliosai import guarded_chat_completion, GuardrailViolation
# Validate required environment variables
REQUIRED_VARS = ["HALIOS_API_KEY", "HALIOS_AGENT_ID", "OPENAI_API_KEY"]
missing = [var for var in REQUIRED_VARS if not os.getenv(var)]
if missing:
raise EnvironmentError(f"Missing required environment variables: {', '.join(missing)}")
HALIOS_AGENT_ID = os.getenv("HALIOS_AGENT_ID")
@guarded_chat_completion(agent_id=HALIOS_AGENT_ID)
async def call_llm(messages):
"""LLM call with automatic guardrail evaluation"""
client = AsyncOpenAI()
response = await client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
max_tokens=100
)
return response
async def main():
# Customize messages for your agent's persona
messages = [{"role": "user", "content": "Hello, can you help me?"}]
try:
response = await call_llm(messages)
content = response.choices[0].message.content
print(f"✓ Response: {content}")
except GuardrailViolation as e:
print(f"✗ Blocked: {e.violation_type} - {len(e.violations)} violation(s)")
if __name__ == "__main__":
asyncio.run(main())
```
### Advanced Usage (Context Manager Pattern)
For fine-grained control over guardrail evaluation:
```python
import asyncio
import os
from openai import AsyncOpenAI
from haliosai import HaliosGuard, GuardrailViolation
HALIOS_AGENT_ID = os.getenv("HALIOS_AGENT_ID")
async def main():
messages = [{"role": "user", "content": "Hello, how can you help?"}]
async with HaliosGuard(agent_id=HALIOS_AGENT_ID) as guard:
try:
# Step 1: Validate request
await guard.validate_request(messages)
print("✓ Request passed")
# Step 2: Call LLM
client = AsyncOpenAI()
response = await client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
max_tokens=100
)
# Step 3: Validate response
response_message = response.choices[0].message
full_conversation = messages + [{"role": "assistant", "content": response_message.content}]
await guard.validate_response(full_conversation)
print("✓ Response passed")
print(f"Response: {response_message.content}")
except GuardrailViolation as e:
print(f"✗ Blocked: {e.violation_type} - {len(e.violations)} violation(s)")
if __name__ == "__main__":
asyncio.run(main())
```
## OpenAI Agents Framework Integration
For native integration with OpenAI Agents framework:
```python
from openai import AsyncOpenAI
from agents import Agent
from haliosai import RemoteInputGuardrail, RemoteOutputGuardrail
# Create guardrails
input_guardrail = RemoteInputGuardrail(agent_id="your-agent-id")
output_guardrail = RemoteOutputGuardrail(agent_id="your-agent-id")
# Create agent with guardrails
agent = Agent(
model="gpt-4o",
instructions="You are a helpful assistant.",
input_guardrails=[input_guardrail],
output_guardrails=[output_guardrail]
)
# Use the agent normally - guardrails run automatically
client = AsyncOpenAI()
runner = await client.beta.agents.get_agent_runner(agent)
result = await runner.run(
starting_agent=agent,
input="Write a professional email"
)
```
## Examples
Check out the `examples/` directory for complete working examples.
### 🚀 Recommended Starting Point
**`06_interactive_chatbot.py`** - Interactive chat session
- Works with ANY agent configuration
- Type your own messages relevant to your agent's persona
- See guardrails in action in real-time
- Best way to explore the SDK!
### 📚 SDK Mechanics
**`01_basic_usage.py`** - Simple decorator pattern
- Shows basic `@guarded_chat_completion` usage
- Request/response guardrail evaluation
- Exception handling
**`02_streaming_response_guardrails.py`** - Streaming responses
- Real-time streaming with guardrails
- Character-based and time-based buffering
- Hybrid buffering modes
**`03_tool_calling_simple.py`** - Tool/function calling
- Guardrails for function calling scenarios
- Tool invocation tracking
**`04_context_manager_pattern.py`** - Manual control
- Context manager for explicit guardrail calls
- Separate request/response validation
**`05_tool_calling_advanced.py`** - Advanced tool calling with comprehensive guardrails
- Request validation
- Tool result validation (prevents data leakage)
- Response validation
- Context manager pattern for fine-grained control
**`05_openai_agents_guardrails_integration.py`** - OpenAI Agents framework
- Integration with OpenAI Agents SDK
- Multi-agent workflows
## Note
Currently, HaliosAI SDK supports OpenAI and OpenAI Agents frameworks natively. Other providers (e.g. Anthropic and Gemini) can be integrated using their OpenAI-compatible APIs via OpenAI SDK. Support for additional frameworks is coming soon.
This is beta release. API and features may change. Please report any issues or feedback on GitHub.
## Requirements
- Python 3.9+
- httpx >= 0.24.0
- typing-extensions >= 4.0.0
### Optional Dependencies
- openai >= 1.0.0 (for OpenAI integration)
- anthropic >= 0.25.0 (for Anthropic integration)
- openai-agents >= 0.1.0 (for OpenAI Agents integration)
## Documentation
- 📖 **Full Documentation**: [docs.halios.ai](https://docs.halios.ai)
## Support
- 🌐 **Website**: [halios.ai](https://halios.ai)
- 📧 **Email**: support@halios.ai
- � **Issues**: [GitHub Issues](https://github.com/HaliosAI/haliosai-python-sdk/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/HaliosAI/haliosai-python-sdk/discussions)
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "haliosai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "HaliosLabs <support@halios.ai>",
"keywords": "ai, guardrails, llm, safety, content-moderation, openai, anthropic, agents, streaming, parallel, reliability, ai security, llm security, llm guardrails, ai guardrails, ai agent evaluation, eval, prompt injection, jailbreak, sensitive data detection, pii detection, mcp security",
"author": null,
"author_email": "HaliosLabs <support@halios.ai>",
"download_url": "https://files.pythonhosted.org/packages/82/c8/1837a4d2cedbcea8edff5461b2e57320997c0e4093c40a4835d888ae217f/haliosai-1.0.5.tar.gz",
"platform": null,
"description": "# HaliosAI SDK\n\n[](https://pypi.org/project/haliosai/)\n[](https://pypi.org/project/haliosai/)\n[](https://opensource.org/licenses/Apache-2.0)\n\n**HaliosAI : Ship Reliable AI Agents Faster!** \ud83d\ude80\ud83d\ude80\ud83d\ude80\n\nHaliosAI SDK helps you catch tricky AI agent failures before they reach users. It supports both offline and live guardrail checks, streaming response validation, parallel processing, and multi-agent setups. Integration is seamless - just add a simple decorator to your code. HaliosAI instantly plugs into your agent workflows, making it easy to add safety and reliability without changing your architecture.\n\n## Features\n\n- \ud83d\udee1\ufe0f **Easy Integration**: Simple decorators and patchers for existing AI agent code\n- \u26a1 **Parallel Processing**: Run guardrails and agent calls simultaneously for optimal performance\n- \ud83c\udf0a **Streaming Support**: Real-time guardrail evaluation for streaming responses\n- \ud83e\udd16 **Multi-Agent Support**: Per-agent guardrail profiles for complex AI systems\n- \ud83d\udd27 **Framework Support**: Built-in support for OpenAI, Anthropic, and OpenAI Agents\n- \ud83d\udcca **Detailed Timing**: Performance metrics and execution insights\n- \ud83d\udea8 **Violation Handling**: Automatic blocking and detailed error reporting\n\n## Installation\n\n```bash\npip install haliosai\n```\n\nFor specific LLM providers:\n```bash\npip install haliosai[openai] # For OpenAI support\npip install haliosai[agents] # For OpenAI Agents support\npip install haliosai[all] # For all providers\n```\n\n## Prerequisites\n\n1. **Get your API key**: Visit [console.halios.ai](https://console.halios.ai) to obtain your HaliosAI API key\n2. **Create an agent**: Follow the [documentation](https://docs.halios.ai) to create your first agent and configure guardrails\n3. **Keep your agent_id handy**: You'll need it for SDK integration\n\nSet required environment variables:\n```bash\nexport HALIOS_API_KEY=\"your-api-key\"\nexport HALIOS_AGENT_ID=\"your-agent-id\"\nexport OPENAI_API_KEY=\"your-openai-key\" # For OpenAI examples\n```\n\n## Quick Start\n\n### Basic Usage (Decorator Pattern)\n\n```python\nimport asyncio\nimport os\nfrom openai import AsyncOpenAI\nfrom haliosai import guarded_chat_completion, GuardrailViolation\n\n# Validate required environment variables\nREQUIRED_VARS = [\"HALIOS_API_KEY\", \"HALIOS_AGENT_ID\", \"OPENAI_API_KEY\"]\nmissing = [var for var in REQUIRED_VARS if not os.getenv(var)]\nif missing:\n raise EnvironmentError(f\"Missing required environment variables: {', '.join(missing)}\")\n\nHALIOS_AGENT_ID = os.getenv(\"HALIOS_AGENT_ID\")\n\n@guarded_chat_completion(agent_id=HALIOS_AGENT_ID)\nasync def call_llm(messages):\n \"\"\"LLM call with automatic guardrail evaluation\"\"\"\n client = AsyncOpenAI()\n response = await client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=messages,\n max_tokens=100\n )\n return response\n\nasync def main():\n # Customize messages for your agent's persona\n messages = [{\"role\": \"user\", \"content\": \"Hello, can you help me?\"}]\n \n try:\n response = await call_llm(messages)\n content = response.choices[0].message.content\n print(f\"\u2713 Response: {content}\")\n except GuardrailViolation as e:\n print(f\"\u2717 Blocked: {e.violation_type} - {len(e.violations)} violation(s)\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### Advanced Usage (Context Manager Pattern)\n\nFor fine-grained control over guardrail evaluation:\n\n```python\nimport asyncio\nimport os\nfrom openai import AsyncOpenAI\nfrom haliosai import HaliosGuard, GuardrailViolation\n\nHALIOS_AGENT_ID = os.getenv(\"HALIOS_AGENT_ID\")\n\nasync def main():\n messages = [{\"role\": \"user\", \"content\": \"Hello, how can you help?\"}]\n \n async with HaliosGuard(agent_id=HALIOS_AGENT_ID) as guard:\n try:\n # Step 1: Validate request\n await guard.validate_request(messages)\n print(\"\u2713 Request passed\")\n \n # Step 2: Call LLM\n client = AsyncOpenAI()\n response = await client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=messages,\n max_tokens=100\n )\n \n # Step 3: Validate response\n response_message = response.choices[0].message\n full_conversation = messages + [{\"role\": \"assistant\", \"content\": response_message.content}]\n await guard.validate_response(full_conversation)\n \n print(\"\u2713 Response passed\")\n print(f\"Response: {response_message.content}\")\n \n except GuardrailViolation as e:\n print(f\"\u2717 Blocked: {e.violation_type} - {len(e.violations)} violation(s)\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## OpenAI Agents Framework Integration\n\nFor native integration with OpenAI Agents framework:\n\n```python\nfrom openai import AsyncOpenAI\nfrom agents import Agent\nfrom haliosai import RemoteInputGuardrail, RemoteOutputGuardrail\n\n# Create guardrails\ninput_guardrail = RemoteInputGuardrail(agent_id=\"your-agent-id\")\noutput_guardrail = RemoteOutputGuardrail(agent_id=\"your-agent-id\")\n\n# Create agent with guardrails\nagent = Agent(\n model=\"gpt-4o\",\n instructions=\"You are a helpful assistant.\",\n input_guardrails=[input_guardrail],\n output_guardrails=[output_guardrail]\n)\n\n# Use the agent normally - guardrails run automatically\nclient = AsyncOpenAI()\nrunner = await client.beta.agents.get_agent_runner(agent)\nresult = await runner.run(\n starting_agent=agent,\n input=\"Write a professional email\"\n)\n```\n\n## Examples\n\nCheck out the `examples/` directory for complete working examples.\n\n### \ud83d\ude80 Recommended Starting Point\n\n**`06_interactive_chatbot.py`** - Interactive chat session\n- Works with ANY agent configuration\n- Type your own messages relevant to your agent's persona\n- See guardrails in action in real-time\n- Best way to explore the SDK!\n\n### \ud83d\udcda SDK Mechanics\n\n**`01_basic_usage.py`** - Simple decorator pattern\n- Shows basic `@guarded_chat_completion` usage\n- Request/response guardrail evaluation\n- Exception handling\n\n**`02_streaming_response_guardrails.py`** - Streaming responses\n- Real-time streaming with guardrails\n- Character-based and time-based buffering\n- Hybrid buffering modes\n\n**`03_tool_calling_simple.py`** - Tool/function calling\n- Guardrails for function calling scenarios\n- Tool invocation tracking\n\n**`04_context_manager_pattern.py`** - Manual control\n- Context manager for explicit guardrail calls\n- Separate request/response validation\n\n**`05_tool_calling_advanced.py`** - Advanced tool calling with comprehensive guardrails\n- Request validation\n- Tool result validation (prevents data leakage)\n- Response validation\n- Context manager pattern for fine-grained control\n\n**`05_openai_agents_guardrails_integration.py`** - OpenAI Agents framework\n- Integration with OpenAI Agents SDK\n- Multi-agent workflows\n\n\n\n## Note\nCurrently, HaliosAI SDK supports OpenAI and OpenAI Agents frameworks natively. Other providers (e.g. Anthropic and Gemini) can be integrated using their OpenAI-compatible APIs via OpenAI SDK. Support for additional frameworks is coming soon.\n\nThis is beta release. API and features may change. Please report any issues or feedback on GitHub.\n\n## Requirements\n\n- Python 3.9+\n- httpx >= 0.24.0\n- typing-extensions >= 4.0.0\n\n### Optional Dependencies\n\n- openai >= 1.0.0 (for OpenAI integration)\n- anthropic >= 0.25.0 (for Anthropic integration)\n- openai-agents >= 0.1.0 (for OpenAI Agents integration)\n\n## Documentation\n\n- \ud83d\udcd6 **Full Documentation**: [docs.halios.ai](https://docs.halios.ai)\n\n## Support\n\n- \ud83c\udf10 **Website**: [halios.ai](https://halios.ai)\n- \ud83d\udce7 **Email**: support@halios.ai\n- \ufffd **Issues**: [GitHub Issues](https://github.com/HaliosAI/haliosai-python-sdk/issues)\n- \ud83d\udcac **Discussions**: [GitHub Discussions](https://github.com/HaliosAI/haliosai-python-sdk/discussions)\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Advanced Guardrails and Evaluation SDK for AI Agents",
"version": "1.0.5",
"project_urls": {
"Bug Reports": "https://github.com/HaliosAI/haliosai-python-sdk/issues",
"Changelog": "https://github.com/HaliosAI/haliosai-python-sdk/releases",
"Documentation": "https://docs.halios.ai",
"Homepage": "https://github.com/HaliosAI/haliosai-python-sdk",
"Repository": "https://github.com/HaliosAI/haliosai-python-sdk"
},
"split_keywords": [
"ai",
" guardrails",
" llm",
" safety",
" content-moderation",
" openai",
" anthropic",
" agents",
" streaming",
" parallel",
" reliability",
" ai security",
" llm security",
" llm guardrails",
" ai guardrails",
" ai agent evaluation",
" eval",
" prompt injection",
" jailbreak",
" sensitive data detection",
" pii detection",
" mcp security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2ad40a4a3aa0fc5be65181366fe5ee80ef7e28d8cb18a98bf1f83533ebe2923a",
"md5": "862d06cd1c6c08f3f95b2f33f115ce26",
"sha256": "15aab786470f081007fad9362a3fb3147917dd04f675833d05f327507bac1e5f"
},
"downloads": -1,
"filename": "haliosai-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "862d06cd1c6c08f3f95b2f33f115ce26",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 28136,
"upload_time": "2025-10-23T18:05:32",
"upload_time_iso_8601": "2025-10-23T18:05:32.508365Z",
"url": "https://files.pythonhosted.org/packages/2a/d4/0a4a3aa0fc5be65181366fe5ee80ef7e28d8cb18a98bf1f83533ebe2923a/haliosai-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "82c81837a4d2cedbcea8edff5461b2e57320997c0e4093c40a4835d888ae217f",
"md5": "d083064b02f542e087a2b40bca9e13d8",
"sha256": "b2619059ad38efbab770050773c9b0df9a20c5c0e3d953ad7d94825850a826a2"
},
"downloads": -1,
"filename": "haliosai-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "d083064b02f542e087a2b40bca9e13d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 44402,
"upload_time": "2025-10-23T18:05:33",
"upload_time_iso_8601": "2025-10-23T18:05:33.752090Z",
"url": "https://files.pythonhosted.org/packages/82/c8/1837a4d2cedbcea8edff5461b2e57320997c0e4093c40a4835d888ae217f/haliosai-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 18:05:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HaliosAI",
"github_project": "haliosai-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "haliosai"
}
JSON
