README

A comprehensive AI abstraction library for PHP with unified support for multiple AI providers.

Features

Multi-provider support: OpenAI, Anthropic Claude, Google Gemini, xAI Grok, Mistral, DeepSeek, Ollama
Unified API: Same interface across all providers
Streaming: Real-time token streaming
Function/Tool calling: Structured function execution
Prompt templates: Reusable template system with variables, conditionals, loops
Conversation memory: Persistent context across requests
Batch processing: Queue and process multiple AI requests
MCP server support: Model Context Protocol integration
Text classification: Sentiment, intent, entity extraction
Embeddings: Vector generation and similarity search
Image generation: DALL-E integration
Structured output: JSON schema enforcement

Installation

composer require memran/marwa-ai

Quick Start

use Marwa\AI\MarwaAI;

// Simple completion
$response = MarwaAI::instance()->conversation('Hello, how are you?')->send();
echo $response->getContent();

// With provider-specific options
$response = MarwaAI::driver('anthropic')
    ->completion([
        ['role' => 'user', 'content' => 'Explain quantum computing']
    ], [
        'temperature' => 0.7,
        'max_tokens' => 500,
    ]);

Using the Helper Functions

use function Marwa\AI\{ai, complete, conversation};

// Quick completion
$result = complete('Tell me a joke');
echo $result->getContent();

// Create conversation with helper
$conv = conversation('You are a helpful assistant');
$conv->user('What is PHP?')
     ->send()
     ->getContent();

Conversations

$conv = ai()->conversation([
    ['role' => 'system', 'content' => 'You are a PHP expert.'],
    ['role' => 'user', 'content' => 'What is dependency injection?']
]);

$response = $conv->send();
echo $response->getContent();

// Continue the conversation
$conv->user('Can you show me an example?')
     ->send();

Context & Metadata

$conv = ai()->conversation()
    ->withContext(['user_id' => 123, 'locale' => 'en'])
    ->setSystem('Remember the user prefers concise answers.');

// Later, restore from storage
$conv = \Marwa\AI\Support\Conversation::fromArray($savedData);

Streaming

// Using the helper
use function Marwa\AI\stream;

stream('Write a poem about code', function ($chunk) {
    echo $chunk->getDelta();
    flush();
});

// Or using conversation directly
foreach (ai()->conversation('Write a poem about code')->stream() as $chunk) {
    echo $chunk->getDelta();
}

Prompt Templates

$template = ai()->prompt('
    You are a {{role}} expert.
    {{#show_tips}}
    Provide practical examples.
    {{/show_tips}}
    Question: {{question}}
');

$response = $template
    ->variable('role', 'PHP developer')
    ->variable('show_tips', true)
    ->render([
        'question' => 'What is a closure?'
    ]);

Tools / Function Calling

use function Marwa\AI\ai_tool;

ai()->tool(ai_tool(
    'get_weather',
    'Get current weather for a location',
    [
        'type' => 'object',
        'properties' => [
            'city' => ['type' => 'string', 'description' => 'City name'],
            'country' => ['type' => 'string', 'description' => 'Country code'],
        ],
        'required' => ['city'],
    ],
    function (array $args) {
        // Your business logic here
        return "Weather in {$args['city']}: 22°C, sunny";
    }
));

$conv = ai()->conversation('What is the weather in Paris?');
$response = $conv->send(['tools' => ai()->getTools()]);

if ($response->hasToolCalls()) {
    // Auto-execute tools and continue
    $final = $conv->continueWithTools(ai()->getTools());
    echo $final->getContent();
}

Classification

use function Marwa\AI\ai_classify;

// Sentiment analysis
$sentiment = ai_classify()->sentiment('I love this product!');
if ($sentiment->isPositive()) {
    echo "Positive score: " . $sentiment->getSentimentScore();
}

// Intent detection
$intent = ai_classify()->detectIntent(
    'I need to reset my password',
    ['greeting', 'password_reset', 'billing', 'technical_support']
);
echo "Detected: " . $intent->getIntent();
echo "Confidence: " . $intent->getConfidence();

// Entity extraction
$entities = ai_classify()->extractEntities(
    'Contact John Doe at john@example.com',
    ['person', 'email', 'organization']
);

// Zero-shot classification
$result = ai_classify()->zeroShot(
    'The new iPhone has an amazing camera',
    ['technology', 'sports', 'politics']
);

Batch Processing

$batch = ai_batch();

// Add multiple tasks
$batch->add('completion', ['prompt' => 'Summarize article A'], ['provider' => 'openai']);
$batch->add('completion', ['prompt' => 'Summarize article B'], ['provider' => 'openai']);
$batch->add('embedding', ['texts' => ['doc1', 'doc2']], ['provider' => 'openai']);

// Process all
$result = $batch->process();

foreach ($result->getResults() as $id => $output) {
    echo "Task {$id}: Done\n";
}

foreach ($result->getFailures() as $failure) {
    echo "Task {$failure['id']} failed: {$failure['error']}\n";
}

Memory & Context

use function Marwa\AI\ai_memory;

$memory = ai_memory();

// Store semantic memories for RAG
$memory->rememberSemantic(
    'Users prefer dark mode with large fonts',
    ['user_id' => 123, 'category' => 'preferences']
);

// Search by semantic similarity
$results = $memory->search('interface preferences');
foreach ($results as $match) {
    echo "Score: {$match['score']}\n";
    echo "Memory: {$match['memory']['text']}\n";
}

// Conversation history storage
$memory->storeMessages('conv_123', $messages);
$history = $memory->getMessages('conv_123');

Embeddings

use function Marwa\AI\embed;
use function Marwa\AI\cosine_similarity;

$embeddings = embed(['Text 1', 'Text 2', 'Text 3']);

// Get individual vectors
$vec1 = $embeddings->getEmbedding(0);

// Cosine similarity
$sim = cosine_similarity(
    $embeddings->getEmbedding(0),
    $embeddings->getEmbedding(1)
);

// Dimensions
$dim = $embeddings->getDimensions();

Image Generation

use function Marwa\AI\image;

$images = image('A sunset over mountains', [
    'size' => '1024x1024',
    'quality' => 'hd',
    'n' => 3,
]);

foreach ($images->getUrls() as $url) {
    echo "Image URL: {$url}\n";
}

// Save to disk
$paths = $images->save('/path/to/save', 'sunset_');

Structured Output

use function Marwa\AI\ai_structured;

$result = ai_structured(
    [
        'type' => 'object',
        'properties' => [
            'name' => ['type' => 'string'],
            'age' => ['type' => 'integer'],
            'skills' => [
                'type' => 'array',
                'items' => ['type' => 'string']
            ],
        ],
    ],
    [
        ['role' => 'user', 'content' => 'Extract: John is 30 and knows PHP, JS']
    ]
);

echo $result->name;  // "John"
echo $result->age;   // 30
echo implode(', ', $result->skills); // "PHP, JS"

Health Checks

use function Marwa\AI\ai_health;

$health = ai_health('openai');

if ($health->check()->isOperational()) {
    echo "Latency: " . $health->getLatency() . "ms\n";
    $models = $health->getModels();
    print_r($models);
}

Configuration

Standalone Usage (Singleton)

use Marwa\AI\MarwaAI;

$ai = MarwaAI::initialize([
    'default' => 'anthropic',
    'anthropic' => [
        'api_key' => 'sk-ant-...',
        'model' => 'claude-3-sonnet',
    ],
    'openai' => [
        'api_key' => 'sk-...',
        'model' => 'gpt-4o',
    ],
]);

$response = $ai->conversation('Hello')->send();

Alternative: Application Instance (Non-singleton)

If you prefer not to use the global singleton, you can instantiate the Application class.

use Marwa\AI\Application;

$ai = new Application([
    'default' => 'openai',
    'openai' => ['api_key' => '...']
]);

$response = $ai->conversation('Hello')->send();

Using a Config File

// config/ai.php
return [
    'default' => 'ollama',

    'providers' => [
        'openai' => [
            'api_key' => getenv('OPENAI_API_KEY'),
            'model' => 'gpt-4o',
            'timeout' => 60,
            'retries' => 3,
        ],
        'anthropic' => [
            'api_key' => getenv('ANTHROPIC_API_KEY'),
            'model' => 'claude-3-opus-20240229',
        ],
        'google' => [
            'api_key' => getenv('GOOGLE_API_KEY'),
            'model' => 'gemini-1.5-pro',
        ],
        'grok' => [
            'api_key' => getenv('XAI_API_KEY'),
            'model' => 'grok-2-latest',
        ],
        'mistral' => [
            'api_key' => getenv('MISTRAL_API_KEY'),
            'model' => 'mistral-large-latest',
        ],
        'deepseek' => [
            'api_key' => getenv('DEEPSEEK_API_KEY'),
            'model' => 'deepseek-chat',
        ],
        'ollama' => [
            'base_url' => 'http://localhost:11434/v1/',
            'model' => 'llama3.2',
        ],
    ],
];

Detailed Provider Configuration

Each provider supports the following parameters in the configuration array:

Parameter	Type	Description
`api_key`	string	Your provider API key
`model`	string	Default model to use for requests
`base_url`	string	Custom API endpoint (e.g., for proxies or local Ollama)
`timeout`	int	Request timeout in seconds (default: 30)
`retries`	int	Number of automatic retries on failure (default: 3)

Environment Variables Reference

Provider	API Key Env	Default Model	Base URL Env
OpenAI	`OPENAI_API_KEY`	`gpt-4o`	`OPENAI_BASE_URL`
Anthropic	`ANTHROPIC_API_KEY`	`claude-3-opus`	-
Google	`GOOGLE_API_KEY`	`gemini-pro`	-
xAI (Grok)	`XAI_API_KEY`	`grok-2-latest`	-
Mistral	`MISTRAL_API_KEY`	`mistral-large`	-
DeepSeek	`DEEPSEEK_API_KEY`	`deepseek-chat`	-
Ollama	-	`llama3.2`	`OLLAMA_BASE_URL`

Chain / Pipeline

use function Marwa\AI\ai;

$chain = ai()->chain([
    fn($input) => "Analyze: {$input}",
    fn($analysis) => strtoupper($analysis),
    fn($upper) => "Final: {$upper}",
]);

$result = $chain->execute();

// Streaming chain
foreach ($chain->stream() as $chunk) {
    echo $chunk->getDelta();
}

// View execution history
$history = $chain->getHistory();
foreach ($history->getSteps() as $step) {
    printf(
        "Step %s: %.3fs\n",
        $step['name'],
        $step['duration']
    );
}

MCP Server

use Marwa\AI\Contracts\MCPServerInterface;
use Marwa\AI\Contracts\MCPResponse;

$server = new class implements MCPServerInterface {
    public function getName(): string { return 'my-server'; }
    public function getVersion(): string { return '1.0.0'; }
    public function getCapabilities() { /* ... */ }
    public function listTools(): array { return [/* ... */]; }
    public function handleToolCall(string $tool, array $args): MCPResponse {
        // Handle MCP tool calls
        return MCPResponse::success($result);
    }
};

ai()->registerMcpServer('my-server', $server);

Error Handling

use Marwa\AI\Exceptions\AIException;
use Marwa\AI\Exceptions\ConfigurationException;
use Marwa\AI\Exceptions\RateLimitException;

try {
    $resp = ai()->driver('openai')->completion($messages);
} catch (RateLimitException $e) {
    echo "Rate limited. Retry after {$e->retryAfter} seconds";
    sleep($e->retryAfter);
} catch (ConfigurationException $e) {
    echo "Check your API key configuration";
} catch (AIException $e) {
    echo "AI error: " . $e->getMessage();
}

CLI Tool

# Interactive chat session
php bin/marwa-ai chat --provider=openai

# Single question
php bin/marwa-ai ask "What is PHP?"

# List available providers
php bin/marwa-ai providers

Providers Reference

Provider	Streaming	Tools	Vision	Embeddings
OpenAI	Yes	Yes	Yes	Yes
Anthropic Claude	Yes	Yes	Yes	Yes
Google Gemini	Yes	Yes	Yes	Yes
xAI Grok	Yes	Yes	Yes	No
Mistral	Yes	Yes	No	Yes
DeepSeek	Yes	Yes	No	Yes
Ollama (local)	Yes	Yes	Yes	Yes*

*Embeddings depend on the loaded model

Environment Variables

Variable	Purpose
`AI_PROVIDER`	Default provider
`OPENAI_API_KEY`	OpenAI credentials
`OPENAI_MODEL`	OpenAI model override
`ANTHROPIC_API_KEY`	Anthropic credentials
`ANTHROPIC_MODEL`	Anthropic model override
`GOOGLE_API_KEY`	Google credentials
`GOOGLE_MODEL`	Google model override
`XAI_API_KEY`	xAI Grok credentials
`MISTRAL_API_KEY`	Mistral credentials
`DEEPSEEK_API_KEY`	DeepSeek credentials
`OLLAMA_BASE_URL`	Ollama endpoint

License

MIT

memran / marwa-ai

Maintainers

Package info

Statistics

Security