Refract

A Laravel package for interacting with Large Language Models. Supports multiple providers including AWS Bedrock (Claude models) and OpenAI (GPT models), featuring a fluent API, streaming, tools, agents with agentic loops, and MCP server integration.

Requirements

• PHP 8.2+
• Laravel 12.0+
• AWS account with Bedrock access (for Claude models) and/or OpenAI API key

Installation

composer require refract/refract

The package will auto-register its service provider and facade.

Publish the configuration file:

php artisan vendor:publish --tag=refract-config

Configuration

Add your provider credentials to your .env file:

# AWS Bedrock (for Claude models)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1

# OpenAI (for GPT models)
OPENAI_API_KEY=your-openai-api-key

# Default provider
REFRACT_PROVIDER=bedrock

See Configuration for full configuration options.

Quick Start

Simple Text Generation

use Refract\Facades\Refract;

$response = Refract::text()
    ->prompt('Explain quantum computing in simple terms.')
    ->generate();

echo $response->text();

Specifying Provider and Model

// AWS Bedrock with Claude
$response = Refract::text()
    ->using('bedrock', 'claude-4-5-sonnet')
    ->prompt('Hello, world!')
    ->generate();

// OpenAI with GPT
$response = Refract::text()
    ->using('openai', 'gpt-4o')
    ->prompt('Hello, world!')
    ->generate();

Streaming

$stream = Refract::text()
    ->prompt('Write a story about space.')
    ->stream();

foreach ($stream as $event) {
    if ($event['type'] === 'text_delta') {
        echo $event['text'];
    }
}

Using Tools

use Refract\Tools\Tool;

$weatherTool = Tool::make(
    name: 'get_weather',
    description: 'Get the current weather for a location',
    schema: [
        'type' => 'object',
        'properties' => [
            'location' => ['type' => 'string'],
        ],
        'required' => ['location'],
    ],
    handler: fn($args) => ['temp' => 22, 'location' => $args['location']]
);

$response = Refract::text()
    ->prompt('What is the weather in Paris?')
    ->withTools([$weatherTool])
    ->generate();

Using Agents

use App\Agents\ResearchAgent;
use Refract\RefractManager;

$agent = new ResearchAgent(app(RefractManager::class));
$response = $agent->respond('What are the latest developments in AI?');

echo $response->text();

Providers

Provider	Models	Environment Variables
AWS Bedrock	Claude 4.5 Opus, Sonnet, Haiku	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION
OpenAI	GPT-4o, GPT-4o-mini, GPT-4 Turbo, o1, o1-mini	OPENAI_API_KEY, OPENAI_ORGANIZATION (optional)

The OpenAI provider also supports custom base URLs for Azure OpenAI, Ollama, and other API-compatible services.

Documentation

• Configuration - Environment variables, config options, custom base URLs
• Basic Usage - Text generation, streaming, multi-turn conversations
• Tools - Function calling, class-based tools, Laravel MCP adapter
• Agents - Agentic loops, handoff, iteration budgets
• MCP - Model Context Protocol server integration
• Schemas - Structured output with JSON Schema builder
• Registries - Global registries for agents, tools, schemas, MCP
• Events - Event system, logging, monitoring
• API Reference - Response object, errors, available models

Testing

./vendor/bin/pest

License

MIT License. See LICENSE for details.