Download the PHP package falahatiali/homa without Composer

Homa is a simple and elegant AI assistant package for Laravel applications. Integrate multiple AI providers (OpenAI, Anthropic Claude, and more) with a clean, fluent API. Named after the mythical Persian bird that brings good fortune and wisdom to those it flies over.

✨ Features

• 🦅 Simple, Fluent API - Elegant interface inspired by Laravel's design philosophy
• 🔌 Multiple AI Providers - Support for OpenAI (GPT-4, GPT-3.5), Anthropic (Claude), Grok, Groq, Google Gemini, and Ollama (local)
• 💬 Conversation Management - Built-in context-aware multi-turn conversations
• ⚙️ Highly Configurable - Extensive configuration options for every use case
• 🧪 Fully Tested - 70 tests with 135 assertions covering all critical paths
• 📦 Zero Configuration - Works out of the box with sensible defaults
• 🎯 Extensible - Easy to add custom AI providers via Factory Pattern
• 🔒 Type Safe - Full PHP 8.1+ type hints and return types
• 🏗️ SOLID Principles - Clean architecture following best practices
• ⚡ Production Ready - Uses official OpenAI PHP client for reliability
• 🔍 Code Quality - PHPStan level 5 + Laravel Pint for consistency

📋 Requirements

• PHP 8.1 or higher
• Laravel 10.x or 11.x
• API keys for your chosen AI provider(s)

📦 Installation

Install the package via Composer:

Publish Configuration (Optional)

This will create a config/homa.php configuration file.

Quick Setup

1. Copy environment file:

2. Add your API keys to .env:

3. Start using Homa:

Configure Your API Keys

Copy the example environment file and add your AI provider API keys:

Required Environment Variables:

Get API Keys:

• OpenAI: platform.openai.com/api-keys
• Anthropic: console.anthropic.com
• Grok: console.x.ai
• Groq: console.groq.com
• Gemini: aistudio.google.com/apikey

🖥️ Use Ollama locally (free)

Ollama lets you run models like Llama 3, Mistral, Qwen locally with no API cost.

1) Install Ollama

2) Download and run a model

3) Configure Homa for Ollama

4) Use in code

Best local models (balanced): llama3.1:8b-instruct, mistral:7b-instruct, qwen2.5:7b-instruct, phi3:mini. Browse models: https://ollama.com/library and curated lists at https://llm-explorer.com/.

🚀 Quick Start

Basic Usage

Ask a simple question:

Configure On-The-Fly

Chain configuration methods for custom behavior:

Switch Between Providers

Easily switch between different AI providers:

Custom System Prompts

Set custom system prompts for specialized behavior:

Multi-Turn Conversations

Create context-aware conversations:

Advanced Chat Control

For full control over the conversation, use the chat() method:

Working with Responses

The AIResponse object provides several useful methods:

⚙️ Configuration

Configuration File

After publishing the config file, you can customize all aspects in config/homa.php. For environment variables, see .env.example for all available options:

Available Models

OpenAI:

• gpt-5 - Latest, most advanced model
• gpt-5o - Optimized GPT-5 variant
• gpt-4o - Latest GPT-4 with vision capabilities
• gpt-4o-mini - Smaller, faster GPT-4o
• gpt-4-turbo - Fast GPT-4 variant
• gpt-4 - Most capable, best for complex tasks
• gpt-3.5-turbo - Fast and cost-effective

Anthropic:

• claude-3-5-sonnet-20241022 - Latest, most capable
• claude-3-opus-20240229 - Most powerful for complex tasks
• claude-3-sonnet-20240229 - Balanced performance
• claude-3-haiku-20240307 - Fastest, most cost-effective

Groq (Ultra-fast inference):

• openai/gpt-oss-20b - Large, capable model
• openai/gpt-oss-7b - Smaller, faster model
• llama-3.1-70b-versatile - Meta's Llama model
• llama-3.1-8b-instant - Fast Llama model
• mixtral-8x7b-32768 - Mixtral model
• gemma-7b-it - Google's Gemma model

Gemini (Google AI with multimodal capabilities):

• gemini-2.0-flash-exp - Latest, fastest (experimental)
• gemini-1.5-pro-latest - Most capable
• gemini-1.5-flash-latest - Balanced speed and capability
• gemini-1.5-pro - Stable pro model
• gemini-1.5-flash - Fast and efficient
• gemini-1.5-pro-002 - Versioned pro model
• gemini-1.5-flash-002 - Versioned flash model

🎯 Use Cases

Content Generation

Code Assistance

Customer Support Bot

Data Analysis

🏗️ Architecture

Package Structure

Adding Custom Providers

You can extend Homa with custom AI providers by implementing the AIProviderInterface:

🧪 Testing

Run the test suite:

Or with PHPUnit directly:

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 Changelog

Please see CHANGELOG for more information on what has changed recently.

🔒 Security

If you discover any security-related issues, please email the maintainer instead of using the issue tracker.

📄 License

The MIT License (MIT). Please see License File for more information.

🌟 Credits

• Author: Ali Falahati
• Inspired by: The mythical Persian Homa bird, a symbol of wisdom and good fortune

📖 About Homa

In Persian mythology, the Homa (also spelled Huma) is a legendary bird that brings good fortune and wisdom to those fortunate enough to be graced by its shadow. The bird is said to never land, continuously soaring through the skies, much like how this package aims to elevate your Laravel applications with the power of AI.

Just as the Homa bird is known for its wisdom and grace, this package strives to bring intelligent, elegant solutions to your AI integration needs, making it effortless to incorporate cutting-edge AI capabilities into your Laravel applications.