https://github.com/droath/nextus-ai
Nextus AI is a unified Laravel client library for multiple LLM providers (OpenAI, Anthropic, Perplexity), providing seamless backend integration for AI-powered applications.
https://github.com/droath/nextus-ai
Last synced: 6 months ago
JSON representation
Nextus AI is a unified Laravel client library for multiple LLM providers (OpenAI, Anthropic, Perplexity), providing seamless backend integration for AI-powered applications.
- Host: GitHub
- URL: https://github.com/droath/nextus-ai
- Owner: droath
- License: mit
- Created: 2025-10-31T04:02:29.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-11-02T19:55:19.000Z (9 months ago)
- Last Synced: 2026-01-11T13:38:23.828Z (7 months ago)
- Language: PHP
- Size: 146 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Nextus AI - Laravel LLM Provider Client
[](https://packagist.org/packages/droath/nextus-ai)
[](https://github.com/droath/nextus-ai/actions?query=workflow%3Arun-tests+branch%3Amain)
[](https://github.com/droath/nextus-ai/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
[](https://packagist.org/packages/droath/nextus-ai)
Nextus AI is a unified Laravel client library designed for multiple LLM
providers, including OpenAI, Anthropic Claude, and Perplexity. This package
offers a consistent interface for working with Large Language Models, featuring
agent coordination, tool execution, and flexible memory strategies.
## Features
- **Multi-Provider Support**: Seamlessly switch between OpenAI, Anthropic
Claude, and Perplexity with a unified API
- **Driver Pattern Architecture**: Clean abstraction layer for LLM provider
integrations
- **Agent System**: Coordinate multiple AI agents with parallel, sequential, or
router strategies
- **Tool Integration**: Define and execute tools that LLMs can call during
conversations
- **Memory Strategies**: Flexible memory management with database, session, or
null strategies
- **Streaming Support**: Real-time streaming responses from compatible providers
- **Testing Helpers**: Built-in fake clients and testing utilities
- **Laravel Integration**: Native Laravel service provider with auto-discovery
## Requirements
- PHP 8.3 or higher
- Laravel 11.x or higher
- Valid API keys for desired LLM providers
## Installation
Install the package via Composer:
```bash
composer require droath/nextus-ai
```
The service provider will be automatically discovered by Laravel.
## Configuration
Publish the configuration file:
```bash
php artisan vendor:publish --tag="nextus-ai-config"
```
This will create `config/nextus-ai.php` where you can configure your LLM
providers.
### Environment Variables
Add your API keys to your `.env` file:
```env
# OpenAI Configuration
OPENAI_API_KEY=your-openai-api-key
OPENAI_ORGANIZATION=your-org-id # Optional
# Anthropic Claude Configuration
CLAUDE_API_KEY=your-claude-api-key
# Perplexity Configuration
PERPLEXITY_API_KEY=your-perplexity-api-key
```
### Database Migrations
If you plan to use the database memory strategy or agent memory features, run
the migrations:
```bash
php artisan migrate
```
## Usage
### Basic Chat Example
```php
use Droath\NextusAi\Facades\NextusAiClient;
use Droath\NextusAi\Drivers\Enums\LlmProvider;
use Droath\NextusAi\Messages\UserMessage;
// Using OpenAI with Message objects (recommended)
$response = NextusAiClient::driver(LlmProvider::OPENAI)
->chat()
->withMessages([
UserMessage::make('What is Laravel?')
])();
echo $response->getMessage();
// Alternative: Using array syntax (also supported)
$response = NextusAiClient::driver(LlmProvider::OPENAI)
->chat()
->withMessages([
['role' => 'user', 'content' => 'What is Laravel?']
])();
```
### Using Different Providers
```php
use Droath\NextusAi\Facades\NextusAiClient;
use Droath\NextusAi\Messages\UserMessage;
use Droath\NextusAi\Messages\SystemMessage;
use Droath\NextusAi\Drivers\Enums\LlmProvider;
// Using Claude with Message objects
$driver = NextusAiClient::driver(LlmProvider::CLAUDE);
$claudeResponse = $driver->chat()
->withModel('claude-3-5-sonnet-20241022')
->withMessages([
SystemMessage::make('You are a helpful programming assistant.'),
UserMessage::make('Explain async programming')
])();
// Using Perplexity
$driver = NextusAiClient::driver(LlmProvider::PERPLEXITY);
$perplexityResponse = $driver->chat()
->withMessages([
UserMessage::make('Latest news on AI developments')
])();
```
### Message Classes
The package provides dedicated message classes for better type safety and
structure:
```php
use Droath\NextusAi\Facades\NextusAiClient;
use Droath\NextusAi\Drivers\Enums\LlmProvider;
use Droath\NextusAi\Messages\UserMessage;
use Droath\NextusAi\Messages\SystemMessage;
use Droath\NextusAi\Messages\AssistantMessage;
// Create messages using the make() method
$systemMessage = SystemMessage::make('You are a helpful assistant.');
$userMessage = UserMessage::make('Hello, how are you?');
// Send conversation with multiple messages
$driver = NextusAiClient::driver(LlmProvider::OPENAI);
$response = $driver->chat()
->withMessages([
SystemMessage::make('You are a helpful assistant specialized in Laravel.'),
UserMessage::make('What are the new features in Laravel 11?'),
])();
// UserMessage supports context for additional metadata
$messageWithContext = UserMessage::make(
'Analyze this code',
context: 'This is a Laravel controller with CRUD operations'
);
```
**Available Message Classes:**
- `UserMessage` - Messages from the user
- `SystemMessage` - System instructions/prompts
- `AssistantMessage` - Messages from the AI assistant
### Working with Agents
Create intelligent agents that can coordinate tasks:
```php
use Droath\NextusAi\Agents\Agent;
use Droath\NextusAi\Agents\AgentCoordinator;
use Droath\NextusAi\Agents\Enums\AgentStrategy;
// Create specialized agents
$researchAgent = Agent::make()
->setSystemPrompt('You are a research assistant specialized in gathering information.');
$writerAgent = Agent::make()
->setSystemPrompt('You are a content writer who creates engaging articles.');
// Coordinate agents with a strategy
$coordinator = AgentCoordinator::make(
'Create a blog post about Laravel',
[$researchAgent, $writerAgent],
AgentStrategy::SEQUENTIAL
);
$result = $coordinator->run($resource);
```
### Using Tools
Define tools that LLMs can invoke:
```php
use Droath\NextusAi\Facades\NextusAiClient;
use Droath\NextusAi\Drivers\Enums\LlmProvider;
use Droath\NextusAi\Messages\UserMessage;
use Droath\NextusAi\Tools\Tool;
use Droath\NextusAi\Tools\ToolProperty;
$weatherTool = Tool::make('get_weather')
->describe('Get the current weather for a location')
->using(function (array $arguments) {
// Your tool implementation here
$location = $arguments['location'];
$unit = $arguments['unit'] ?? 'fahrenheit';
// Example: fetch weather from an API
return "The current weather in {$location} is 72 degrees {$unit}.";
})
->withProperties([
ToolProperty::make('location', 'string')
->describe('The city and state, e.g. San Francisco, CA')
->required(),
ToolProperty::make('unit', 'string')
->describe('Temperature unit: celsius or fahrenheit')
->withEnums(['celsius', 'fahrenheit']),
]);
$driver = NextusAiClient::driver(LlmProvider::OPENAI);
$response = $driver->chat()
->withTools([$weatherTool])
->withMessages([
UserMessage::make('What is the weather in San Francisco?')
])();
// If the LLM decides to use the tool, it will be automatically executed
// and the response will include the tool's output
```
### Memory Strategies
Use memory to maintain context across interactions:
```php
use Droath\NextusAi\Memory\MemoryDefinition;
use Droath\NextusAi\Memory\MemoryStrategyFactory;
use Droath\NextusAi\Agents\Agent;
// Database memory strategy
$memoryDefinition = new MemoryDefinition('database', [
'connection' => 'mysql',
'table' => 'llm_agent_memory'
]);
$factory = new MemoryStrategyFactory($memoryDefinition);
$memory = $factory->createInstance();
$agent = Agent::make()
->setSystemPrompt('You remember previous conversations')
->setMemory($memory);
// Store information
$memory->set('user_preference', 'prefers concise answers');
// Retrieve later
$preference = $memory->get('user_preference');
```
### Streaming Responses
Get real-time streaming responses using callbacks:
```php
use Droath\NextusAi\Facades\NextusAiClient;
use Droath\NextusAi\Messages\UserMessage;
use Droath\NextusAi\Drivers\Enums\LlmProvider;
use Droath\NextusAi\Responses\NextusAiResponseMessage;
$driver = NextusAiClient::driver(LlmProvider::OPENAI);
$streamOutput = '';
$chat = $driver->chat()
->withModel('gpt-4')
->withMessages([
UserMessage::make('Write a long story')
])
->usingStream(
function (string $chunk, bool $initialized) use (&$streamOutput) {
// Process each chunk as it arrives
echo $chunk;
$streamOutput .= $chunk;
},
function (NextusAiResponseMessage $response) {
// Called when streaming is complete
echo "\n\nStreaming finished!";
}
);
// Execute the chat request
$response = $chat();
```
## Supported LLM Providers
### OpenAI
- Models: GPT-4, GPT-4 Turbo, GPT-3.5 Turbo, and more
- Features: Chat, embeddings, function calling, streaming
- Configuration: API key, organization ID (optional), base URL (optional)
### Anthropic Claude
- Models: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku
- Features: Chat, function calling, streaming
- Configuration: API key
### Perplexity
- Models: Various Perplexity models
- Features: Chat with web search capabilities
- Configuration: API key
## Advanced Features
### Agent Coordination Strategies
1. **Parallel**: Execute multiple agents simultaneously
2. **Sequential**: Execute agents one after another, passing results
3. **Router**: Intelligently route requests to the most appropriate agent
### Memory Strategies
- **Database Strategy**: Persistent storage using Laravel's database
- **Session Strategy**: Session-based temporary storage
- **Null Strategy**: No memory persistence (stateless)
### Custom Drivers
Extend the package to support additional LLM providers by implementing the
driver interface:
```php
use Droath\NextusAi\Drivers\NextusAiDriver;
class CustomDriver extends NextusAiDriver
{
// Implement required methods
}
```
## Testing
Run the test suite:
```bash
composer test
```
Run code style checks:
```bash
vendor/bin/pint
```
Run static analysis:
```bash
vendor/bin/phpstan analyse
```
### Testing Your Application
Use the built-in fake client for testing:
```php
use Droath\NextusAi\Facades\NextusAi;
use Droath\NextusAi\Responses\NextusAiResponseMessage;
NextusAi::fake(
responseCallback: fn() => NextusAiResponseMessage::fromString('Fake response')
);
// Your test code here
```
## Console Commands
### Memory Cleanup
Clean up expired memory entries:
```bash
# Perform cleanup
php artisan nextus-ai:memory:cleanup
# Dry run to see what would be cleaned
php artisan nextus-ai:memory:cleanup --dry-run
```
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## Credits
- [Travis Tomka](https://github.com/droath)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more
information.