Download the PHP package aimatchfun/laravel-ai without Composer

Laravel AI

A Laravel package that provides a fluent interface for interacting with AI providers:

• Ollama
• OpenAI
• Anthropic
• Novita
• OpenRouter
• Together

Installation

You can install the package via composer:

The package will automatically register itself.

Standalone Usage (Without Laravel)

If you want to test the examples without installing Laravel, see STANDALONE_EXAMPLES.md for instructions on running examples with minimal dependencies.

You can publish the configuration file with:

This will publish a config/ai.php file where you can configure your AI providers.

Preview Messages

The package now supports preview messages to provide context for conversations. You can pass an array of messages in the format that AI models expect:

Or use the Message object for better type safety:

Configuration

After publishing the configuration file, you can configure your AI providers in the config/ai.php file:

You can also set these values in your .env file:

Timeout: You can set the timeout (in seconds) for each provider. If a request takes longer than this value, it will fail with a timeout error. The default is 30 seconds for all providers.

Usage

The package provides a fluent interface through the AI facade:

About the AIResponse object

The run() method returns an instance of AIResponse:

Standard fields:

• answer: The AI's response to your prompt(s).
• inputTokens: Number of input tokens used (available for Novita, OpenAI, Anthropic, Together, and OpenRouter providers).
• outputTokens: Number of output tokens used (available for Novita, OpenAI, Anthropic, Together, and OpenRouter providers).

Ollama-specific fields:

• model: The model used for the response.
• createdAt: Timestamp when the response was created.
• done: Whether the response is complete.
• doneReason: Reason why the response finished.
• totalDuration: Total duration in nanoseconds.
• loadDuration: Model load duration in nanoseconds.
• promptEvalCount: Number of tokens in the prompt.
• promptEvalDuration: Time spent evaluating the prompt in nanoseconds.
• evalCount: Number of tokens generated.
• evalDuration: Time spent generating tokens in nanoseconds.
• thinking: The thinking process (if available in the model).

Anthropic-specific fields:

• id: Unique identifier for the message.
• type: Type of the response (usually "message").
• role: Role of the message (usually "assistant").
• stopReason: Reason why the response stopped (e.g., "end_turn").
• stopSequence: Stop sequence that triggered the end (if any).
• cacheCreationInputTokens: Number of input tokens used for cache creation.
• cacheReadInputTokens: Number of input tokens read from cache.
• cacheCreation: Cache creation details with ephemeral token counts.
• serviceTier: Service tier used for the request (e.g., "standard").

OpenAI-specific fields:

• id: Unique identifier for the completion.
• object: Type of object (usually "chat.completion").
• created: Unix timestamp when the response was created.
• index: Index of the choice in the choices array.
• finishReason: Reason why the response finished (e.g., "stop").
• refusal: Refusal message if the model refused to respond.
• annotations: Array of annotations on the response.
• logprobs: Log probabilities for the response.
• totalTokens: Total number of tokens used (input + output).
• promptTokensDetails: Details about prompt tokens (cached_tokens, audio_tokens).
• completionTokensDetails: Details about completion tokens (reasoning_tokens, audio_tokens, etc.).
• systemFingerprint: System fingerprint for the response.

Novita-specific fields:

• contentFilterResults: Content filter results including hate, self_harm, sexual, violence, jailbreak, and profanity filters with their filtered/detected status.

Together-specific fields:

• seed: The seed value used for generation (if provided).
• toolCalls: Array of tool calls made by the model (if any).
• cachedTokens: Number of cached tokens used in the response.

Common fields:

• raw: Raw response data from the provider.

Note: Token information is only available for providers that return usage data in their API responses. For providers like Ollama, these values will be null. Provider-specific fields are only available when using the corresponding provider.

Preview Messages

The previewMessages method allows you to provide context for your AI conversations by passing an array of previous messages. This is useful for maintaining conversation context without persisting data to a database.

• Messages should be in the format ['role' => 'user|assistant|system', 'content' => 'message content']
• You can also use the Message object for better type safety and validation
• Preview messages are merged with the current prompt before sending to the AI provider

Example:

Response Format (Structured Outputs)

The responseFormat method allows you to request structured outputs from the AI, such as JSON objects following a specific schema. This is useful when you need the AI to return data in a consistent, parseable format.

Supported Providers: Novita only

Example with JSON schema:

Note: Currently, only the Novita provider supports structured outputs via responseFormat. Please consult the Novita documentation on structured outputs to confirm which models support this feature and for specific schema requirements.

Available Providers Enum

The package provides an enum with all available AI providers for easy access and type safety:

Advanced Parameters (NovitaProvider)

The NovitaProvider supports advanced parameter control methods for fine-tuning AI responses. These methods can be chained together when using the provider directly:

Available Methods:

• temperature(float $temperature) - Controls randomness. Higher values = more creative responses. Range typically 0.0 to 2.0.
• maxTokens(int $maxTokens) - Sets the maximum number of tokens the AI can generate in its response.
• topP(float $topP) - Nucleus sampling parameter. Controls cumulative probability of token selection. Range typically 0.0 to 1.0.
• topK(int $topK) - Limits the number of candidate tokens considered at each step. Lower values make output more focused.
• presencePenalty(float $presencePenalty) - Penalizes tokens that have already appeared in the text, encouraging more diverse vocabulary.
• frequencyPenalty(float $frequencyPenalty) - Reduces the likelihood of repeating tokens that have appeared frequently in the text.
• repetitionPenalty(float $repetitionPenalty) - General repetition control. Values > 1.0 penalize repetition, values < 1.0 encourage it.

Note: All parameters are optional. If not specified, the API will use its default values. Parameters are only included in the request payload when explicitly set.

Available Providers Enum

The package provides an enum with all available AI providers for easy access and type safety:

Available Models

Novita Models

The package provides an enum with all available Novita models for easy access and type safety:

Note: The list of available models in the enum may become outdated as Novita adds or removes models. Always check the official Novita documentation for the most current list of available models.

Extending

You can add your own AI providers by extending the AIService class in a service provider:

Your custom provider needs to implement the AIMatchFun\LaravelAI\Contracts\AIProvider interface or extend the AIMatchFun\LaravelAI\Services\Providers\AbstractProvider class.

Testing

The package includes integration tests for all supported AI providers. These tests make real API calls to verify that each provider works correctly.

Setup

Before running the tests, create a .env file in the root directory with the necessary environment variables:

Edit the .env file and add your API keys. You don't need to configure all providers - only the ones you want to test.

Running Tests

Run all integration tests:

Run tests for a specific provider:

Run a specific test:

Test Behavior

• Tests are automatically skipped if the provider is not configured (environment variable not set)
• Tests make real API calls to provider APIs - make sure you have credits available
• No API keys are hardcoded - all come from the .env file

Test Coverage

Each provider is tested for:

1. ✅ Basic response generation (test_can_generate_response)
2. ✅ Response generation with system instruction (test_can_generate_response_with_system_instruction)
3. ✅ Streaming response generation (test_can_generate_stream_response)
4. ✅ Temperature configuration (test_can_set_temperature)
5. ✅ Model configuration (test_can_set_model)
6. ✅ Usage data retrieval (test_can_get_usage_data) - when supported
7. ✅ Exception validation when no messages provided (test_throws_exception_when_no_user_messages)

Important Notes

• ⚠️ Never commit the .env file with your real API keys
• ⚠️ Tests make real API calls and may consume credits
• ⚠️ Some providers may have rate limits - run tests carefully
• ✅ Tests are designed to be idempotent and should not cause side effects

Simple PHP Test Scripts

Alternatively, you can use simple PHP scripts to test each provider individually:

These scripts will:

• Load environment variables from .env file
• Test basic response generation
• Test system instructions
• Test streaming responses
• Test usage data (when available)

Contributing

Contributions are welcome! If you would like to improve this package, please follow these steps:

1. Fork the repository.
2. Create a branch for your feature or bugfix (git checkout -b my-feature).
3. Make your changes and add tests if necessary.
4. Commit your changes (git commit -am 'Add new feature').
5. Push to your branch (git push origin my-feature).
6. Open a Pull Request describing your changes.

Please follow the project's code style and write tests whenever possible.

License

This package is open-sourced software licensed under the MIT license.