{"id":16883959,"url":"https://github.com/igorbenav/clientai","last_synced_at":"2025-04-07T06:11:32.494Z","repository":{"id":257822906,"uuid":"866274668","full_name":"igorbenav/clientai","owner":"igorbenav","description":"A unified client for AI providers with built-in agent support.","archived":false,"fork":false,"pushed_at":"2024-12-29T06:11:28.000Z","size":3875,"stargazers_count":48,"open_issues_count":13,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-06T06:48:19.747Z","etag":null,"topics":["agents","ai","ai-agents","artificial-intelligence","language-model","llm","llm-agent","llms","nlp","ollama","python","replicate-api"],"latest_commit_sha":null,"homepage":"https://igorbenav.github.io/clientai/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/igorbenav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"igorbenav"}},"created_at":"2024-10-02T00:27:34.000Z","updated_at":"2025-03-08T19:10:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"0b03a510-33c1-4596-a8cb-76b72102401b","html_url":"https://github.com/igorbenav/clientai","commit_stats":null,"previous_names":["igorbenav/clientai"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Fclientai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Fclientai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Fclientai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Fclientai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/igorbenav","download_url":"https://codeload.github.com/igorbenav/clientai/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247601448,"owners_count":20964864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","ai-agents","artificial-intelligence","language-model","llm","llm-agent","llms","nlp","ollama","python","replicate-api"],"created_at":"2024-10-13T16:15:55.827Z","updated_at":"2025-04-07T06:11:32.473Z","avatar_url":"https://github.com/igorbenav.png","language":"Python","funding_links":["https://github.com/sponsors/igorbenav"],"categories":[],"sub_categories":[],"readme":"# ClientAI\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://igorbenav.github.io/clientai/\"\u003e\n    \u003cimg src=\"assets/ClientAI.png\" alt=\"ClientAI logo\" width=\"45%\" height=\"auto\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ci\u003eA unified client for AI providers with built-in agent support.\u003c/i\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/igorbenav/clientai/actions/workflows/tests.yml\"\u003e\n  \u003cimg src=\"https://github.com/igorbenav/clientai/actions/workflows/tests.yml/badge.svg\" alt=\"Tests\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/clientai/\"\u003e\n  \u003cimg src=\"https://img.shields.io/pypi/v/clientai?color=%2334D058\u0026label=pypi%20package\" alt=\"PyPi Version\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/clientai/\"\u003e\n  \u003cimg src=\"https://img.shields.io/pypi/pyversions/clientai.svg?color=%2334D058\" alt=\"Supported Python Versions\"/\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003cb\u003eClientAI\u003c/b\u003e 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]) -\u003e 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) -\u003e 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 – [@igormagalhaesr](https://twitter.com/igormagalhaesr) – igormagalhaesr@gmail.com\n[github.com/igorbenav](https://github.com/igorbenav/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorbenav%2Fclientai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figorbenav%2Fclientai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorbenav%2Fclientai/lists"}