# ClientAI
<p align="center">
<a href="https://igorbenav.github.io/clientai/">
<img src="assets/ClientAI.png" alt="ClientAI logo" width="45%" height="auto">
</a>
</p>
<p align="center">
<i>A unified client for AI providers with built-in agent support.</i>
</p>
<p align="center">
<a href="https://github.com/igorbenav/clientai/actions/workflows/tests.yml">
<img src="https://github.com/igorbenav/clientai/actions/workflows/tests.yml/badge.svg" alt="Tests"/>
</a>
<a href="https://pypi.org/project/clientai/">
<img src="https://img.shields.io/pypi/v/clientai?color=%2334D058&label=pypi%20package" alt="PyPi Version"/>
</a>
<a href="https://pypi.org/project/clientai/">
<img src="https://img.shields.io/pypi/pyversions/clientai.svg?color=%2334D058" alt="Supported Python Versions"/>
</a>
</p>
---
<b>ClientAI</b> is a Python package that provides a unified framework for building AI applications, from direct provider interactions to transparent LLM-powered agents, with seamless support for OpenAI, Replicate, Groq and Ollama.
**Documentation**: [igorbenav.github.io/clientai/](https://igorbenav.github.io/clientai/)
---
## Features
- **Unified Interface**: Consistent methods across multiple AI providers (OpenAI, Replicate, Groq, Ollama).
- **Streaming Support**: Real-time response streaming and chat capabilities.
- **Intelligent Agents**: Framework for building transparent, multi-step LLM workflows with tool integration.
- **Output Validation**: Built-in validation system for ensuring structured, reliable outputs from each step.
- **Modular Design**: Use components independently, from simple provider wrappers to complete agent systems.
- **Type Safety**: Comprehensive type hints for better development experience.
## Installing
To install ClientAI with all providers, run:
```sh
pip install "clientai[all]"
```
Or, if you prefer to install only specific providers:
```sh
pip install "clientai[openai]" # For OpenAI support
pip install "clientai[replicate]" # For Replicate support
pip install "clientai[ollama]" # For Ollama support
pip install "clientai[groq]" # For Groq support
```
## Quick Start Examples
### Basic Provider Usage
```python
from clientai import ClientAI
# Initialize with OpenAI
client = ClientAI('openai', api_key="your-openai-key")
# Generate text
response = client.generate_text(
"Tell me a joke",
model="gpt-3.5-turbo",
)
print(response)
# Chat functionality
messages = [
{"role": "user", "content": "What is the capital of France?"},
{"role": "assistant", "content": "Paris."},
{"role": "user", "content": "What is its population?"}
]
response = client.chat(
messages,
model="gpt-3.5-turbo",
)
print(response)
```
### Quick-Start Agent
```python
from clientai import client
from clientai.agent import create_agent, tool
@tool(name="calculator")
def calculate_average(numbers: list[float]) -> float:
"""Calculate the arithmetic mean of a list of numbers."""
return sum(numbers) / len(numbers)
analyzer = create_agent(
client=client("groq", api_key="your-groq-key"),
role="analyzer",
system_prompt="You are a helpful data analysis assistant.",
model="llama-3.2-3b-preview",
tools=[calculate_average]
)
result = analyzer.run("Calculate the average of these numbers: [1000, 1200, 950, 1100]")
print(result)
```
### 3. Custom Agent with Validation
For guaranteed output structure and type safety:
```python
from clientai.agent import Agent, think
from pydantic import BaseModel, Field
from typing import List
class Analysis(BaseModel):
summary: str = Field(min_length=10)
key_points: List[str] = Field(min_items=1)
sentiment: str = Field(pattern="^(positive|negative|neutral)$")
class DataAnalyzer(Agent):
@think(
name="analyze",
json_output=True, # Enable JSON formatting
)
def analyze_data(self, data: str) -> Analysis: # Enable validation
"""Analyze data with validated output structure."""
return """
Analyze this data and return a JSON with:
- summary: at least 10 characters
- key_points: non-empty list
- sentiment: positive, negative, or neutral
Data: {data}
"""
# Initialize and use
analyzer = DataAnalyzer(client=client, default_model="gpt-4")
result = analyzer.run("Sales increased by 25% this quarter")
print(f"Sentiment: {result.sentiment}")
print(f"Key Points: {result.key_points}")
```
See our [documentation](https://igorbenav.github.io/clientai/) for more examples, including:
- Custom workflow agents with multiple steps
- Complex tool integration and selection
- Advanced usage patterns and best practices
## Design Philosophy
The ClientAI Agent module is built on four core principles:
1. **Prompt-Centric Design**: Prompts are explicit, debuggable, and transparent. What you see is what is sent to the model.
2. **Customization First**: Every component is designed to be extended or overridden. Create custom steps, tool selectors, or entirely new workflow patterns.
3. **Zero Lock-In**: Start with high-level components and drop down to lower levels as needed. You can:
- Extend `Agent` for custom behavior
- Use individual components directly
- Gradually replace parts with your own implementation
- Or migrate away entirely - no lock-in
## Requirements
- **Python:** Version 3.9 or newer
- **Dependencies:** Core package has minimal dependencies. Provider-specific packages are optional.
## Contributing
Contributions are welcome! Please see our [Contributing Guidelines](CONTRIBUTING.md) for more information.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contact
Igor Magalhaes – [@igormagalhaesr](https://twitter.com/igormagalhaesr) – igormagalhaesr@gmail.com
[github.com/igorbenav](https://github.com/igorbenav/)
Raw data
{
"_id": null,
"home_page": null,
"name": "clientai",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "ai, agents, llm, nlp, language-model, ai-agents",
"author": "Igor Benav",
"author_email": "igor.magalhaes.r@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/99/8b/8b299e3b8ae27122d07016fb4cbe8511a45e749dd959050f096943403f34/clientai-0.5.0.tar.gz",
"platform": null,
"description": "# ClientAI\n\n<p align=\"center\">\n <a href=\"https://igorbenav.github.io/clientai/\">\n <img src=\"assets/ClientAI.png\" alt=\"ClientAI logo\" width=\"45%\" height=\"auto\">\n </a>\n</p>\n\n<p align=\"center\">\n <i>A unified client for AI providers with built-in agent support.</i>\n</p>\n\n<p align=\"center\">\n<a href=\"https://github.com/igorbenav/clientai/actions/workflows/tests.yml\">\n <img src=\"https://github.com/igorbenav/clientai/actions/workflows/tests.yml/badge.svg\" alt=\"Tests\"/>\n</a>\n<a href=\"https://pypi.org/project/clientai/\">\n <img src=\"https://img.shields.io/pypi/v/clientai?color=%2334D058&label=pypi%20package\" alt=\"PyPi Version\"/>\n</a>\n<a href=\"https://pypi.org/project/clientai/\">\n <img src=\"https://img.shields.io/pypi/pyversions/clientai.svg?color=%2334D058\" alt=\"Supported Python Versions\"/>\n</a>\n</p>\n\n---\n\n<b>ClientAI</b> is a Python package that provides a unified framework for building AI applications, from direct provider interactions to transparent LLM-powered agents, with seamless support for OpenAI, Replicate, Groq and Ollama.\n\n**Documentation**: [igorbenav.github.io/clientai/](https://igorbenav.github.io/clientai/)\n\n---\n\n## Features\n\n- **Unified Interface**: Consistent methods across multiple AI providers (OpenAI, Replicate, Groq, Ollama).\n- **Streaming Support**: Real-time response streaming and chat capabilities.\n- **Intelligent Agents**: Framework for building transparent, multi-step LLM workflows with tool integration.\n- **Output Validation**: Built-in validation system for ensuring structured, reliable outputs from each step.\n- **Modular Design**: Use components independently, from simple provider wrappers to complete agent systems.\n- **Type Safety**: Comprehensive type hints for better development experience.\n\n## Installing\n\nTo install ClientAI with all providers, run:\n\n```sh\npip install \"clientai[all]\"\n```\n\nOr, if you prefer to install only specific providers:\n\n```sh\npip install \"clientai[openai]\" # For OpenAI support\npip install \"clientai[replicate]\" # For Replicate support\npip install \"clientai[ollama]\" # For Ollama support\npip install \"clientai[groq]\" # For Groq support\n```\n\n## Quick Start Examples\n\n### Basic Provider Usage\n\n```python\nfrom clientai import ClientAI\n\n# Initialize with OpenAI\nclient = ClientAI('openai', api_key=\"your-openai-key\")\n\n# Generate text\nresponse = client.generate_text(\n \"Tell me a joke\",\n model=\"gpt-3.5-turbo\",\n)\nprint(response)\n\n# Chat functionality\nmessages = [\n {\"role\": \"user\", \"content\": \"What is the capital of France?\"},\n {\"role\": \"assistant\", \"content\": \"Paris.\"},\n {\"role\": \"user\", \"content\": \"What is its population?\"}\n]\n\nresponse = client.chat(\n messages,\n model=\"gpt-3.5-turbo\",\n)\nprint(response)\n```\n\n### Quick-Start Agent\n\n```python\nfrom clientai import client\nfrom clientai.agent import create_agent, tool\n\n@tool(name=\"calculator\")\ndef calculate_average(numbers: list[float]) -> float:\n \"\"\"Calculate the arithmetic mean of a list of numbers.\"\"\"\n return sum(numbers) / len(numbers)\n\nanalyzer = create_agent(\n client=client(\"groq\", api_key=\"your-groq-key\"),\n role=\"analyzer\", \n system_prompt=\"You are a helpful data analysis assistant.\",\n model=\"llama-3.2-3b-preview\",\n tools=[calculate_average]\n)\n\nresult = analyzer.run(\"Calculate the average of these numbers: [1000, 1200, 950, 1100]\")\nprint(result)\n```\n\n### 3. Custom Agent with Validation\n\nFor guaranteed output structure and type safety:\n\n```python\nfrom clientai.agent import Agent, think\nfrom pydantic import BaseModel, Field\nfrom typing import List\n\nclass Analysis(BaseModel):\n summary: str = Field(min_length=10)\n key_points: List[str] = Field(min_items=1)\n sentiment: str = Field(pattern=\"^(positive|negative|neutral)$\")\n\nclass DataAnalyzer(Agent):\n @think(\n name=\"analyze\",\n json_output=True, # Enable JSON formatting\n )\n\n def analyze_data(self, data: str) -> Analysis: # Enable validation\n \"\"\"Analyze data with validated output structure.\"\"\"\n return \"\"\"\n Analyze this data and return a JSON with:\n - summary: at least 10 characters\n - key_points: non-empty list\n - sentiment: positive, negative, or neutral\n\n Data: {data}\n \"\"\"\n\n# Initialize and use\n\nanalyzer = DataAnalyzer(client=client, default_model=\"gpt-4\")\nresult = analyzer.run(\"Sales increased by 25% this quarter\")\nprint(f\"Sentiment: {result.sentiment}\")\nprint(f\"Key Points: {result.key_points}\")\n```\n\nSee our [documentation](https://igorbenav.github.io/clientai/) for more examples, including:\n\n- Custom workflow agents with multiple steps\n- Complex tool integration and selection\n- Advanced usage patterns and best practices\n\n## Design Philosophy\n\nThe ClientAI Agent module is built on four core principles:\n\n1. **Prompt-Centric Design**: Prompts are explicit, debuggable, and transparent. What you see is what is sent to the model.\n\n2. **Customization First**: Every component is designed to be extended or overridden. Create custom steps, tool selectors, or entirely new workflow patterns.\n\n3. **Zero Lock-In**: Start with high-level components and drop down to lower levels as needed. You can:\n - Extend `Agent` for custom behavior\n - Use individual components directly\n - Gradually replace parts with your own implementation\n - Or migrate away entirely - no lock-in\n\n## Requirements\n\n- **Python:** Version 3.9 or newer\n- **Dependencies:** Core package has minimal dependencies. Provider-specific packages are optional.\n\n## Contributing\n\nContributions are welcome! Please see our [Contributing Guidelines](CONTRIBUTING.md) for more information.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contact\n\nIgor Magalhaes \u2013 [@igormagalhaesr](https://twitter.com/igormagalhaesr) \u2013 igormagalhaesr@gmail.com\n[github.com/igorbenav](https://github.com/igorbenav/)",
"bugtrack_url": null,
"license": null,
"summary": "A unified client for AI providers with built-in agent support.",
"version": "0.5.0",
"project_urls": null,
"split_keywords": [
"ai",
" agents",
" llm",
" nlp",
" language-model",
" ai-agents"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b36b55fe1f755b7373c189b4815f71d269cea3e841e749b5f7025c9ea9153f06",
"md5": "785b748d6969550a2aa1391d7ec1e3b3",
"sha256": "8b6abdbaddb5a312dd1ea725988c4394aac64c32459b6f078c441caf3299c8b0"
},
"downloads": -1,
"filename": "clientai-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "785b748d6969550a2aa1391d7ec1e3b3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 111992,
"upload_time": "2024-12-29T06:07:50",
"upload_time_iso_8601": "2024-12-29T06:07:50.115534Z",
"url": "https://files.pythonhosted.org/packages/b3/6b/55fe1f755b7373c189b4815f71d269cea3e841e749b5f7025c9ea9153f06/clientai-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "998b8b299e3b8ae27122d07016fb4cbe8511a45e749dd959050f096943403f34",
"md5": "87ce3095a007b72c75f94c3050c98f95",
"sha256": "bb445fcefc2cabbfe0715187d936670e5e1eb155d23c1f7834231ff92338753f"
},
"downloads": -1,
"filename": "clientai-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "87ce3095a007b72c75f94c3050c98f95",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 85503,
"upload_time": "2024-12-29T06:07:53",
"upload_time_iso_8601": "2024-12-29T06:07:53.637465Z",
"url": "https://files.pythonhosted.org/packages/99/8b/8b299e3b8ae27122d07016fb4cbe8511a45e749dd959050f096943403f34/clientai-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-29 06:07:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "clientai"
}
JSON