Getting Started

Minimal Setup

Install the Package:

composer require symfony/ai-weaviate-store

Configure Weaviate Connection: Add to config/services.php or a dedicated Weaviate config file:

'weaviate' => [
    'host' => env('WEAVIATE_HOST', 'http://localhost:8080'),
    'api_key' => env('WEAVIATE_API_KEY', null),
    'collection' => env('WEAVIATE_COLLECTION', 'default'),
],

Create a Store Service Provider:

// app/Providers/WeaviateServiceProvider.php
use Symfony\Component\AI\Store\StoreInterface;
use Symfony\Component\AI\Store\WeaviateStore;

class WeaviateServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton(StoreInterface::class, function ($app) {
            $config = $app['config']['weaviate'];
            return new WeaviateStore(
                $config['host'],
                $config['collection'],
                $config['api_key'] ?? null
            );
        });
    }
}

First Use Case: Storing and Retrieving Vectors

// In a controller or command
$store = app(StoreInterface::class);

// Upsert a vector (e.g., from an embedding)
$store->upsert([
    'id' => 'doc_123',
    'embedding' => [0.1, 0.5, ..., 0.9], // Your vector data
    'metadata' => ['title' => 'Example Document', 'category' => 'tech'],
]);

// Find nearest vectors
$results = $store->findNearest(
    [0.2, 0.6, ..., 0.8], // Query vector
    limit: 5,
    filter: ['category' => 'tech'] // Optional Weaviate filter
);

Where to Look First

Package Docs: Symfony AI Weaviate Store (limited but covers core methods).
Weaviate Docs:
- REST API (for raw HTTP calls if needed).
- GraphQL Get (advanced queries).
- Similarity Search (for tuning findNearest).
Symfony AI Store Interface: StoreInterface (defines upsert, findNearest, remove).

Implementation Patterns

Core Workflows

1. Vector CRUD Operations

Upsert: Store or update vectors with metadata.

$store->upsert([
    'id' => 'unique_id',
    'embedding' => $vectorArray,
    'metadata' => ['author' => 'John', 'tags' => ['ai', 'php']],
]);

Remove: Delete vectors by ID.
```
$store->remove(['id' => 'unique_id']);
```

Batch Operations: Use Weaviate’s bulk API (not natively supported; wrap in Laravel Queues).

foreach ($vectors as $vector) {
    Queue::push(new UpsertWeaviateVector($store, $vector));
}

2. Semantic Search

Nearest Neighbors: Retrieve similar vectors.

$results = $store->findNearest(
    $queryVector,
    limit: 3,
    filter: ['tags' => ['ai']] // Filter by metadata
);

Hybrid Search: Combine keyword and vector search (Weaviate GraphQL).

// Requires raw GraphQL query (not in StoreInterface)
$client = $store->getHttpClient();
$response = $client->request('POST', '/graphql', [
    'json' => [
        'query' => '
            {
              Get {
                MyCollection(
                  where: { path: ["tags"], operator: ContainsAny, valueText: "ai" }
                ) {
                  vectors {
                    nearestVector {
                      id
                      distance
                    }
                  }
                }
              }
            }
        ',
    ],
]);

3. Integration with Laravel AI

Retrieval-Augmented Generation (RAG):

// 1. Retrieve context
$context = $store->findNearest($queryEmbedding, limit: 2);

// 2. Pass to LLM (e.g., via symfony/ai)
$aiClient = new AiClient(new OpenAI());
$response = $aiClient->ask(
    "Answer based on: " . implode("\n", $context),
    "What is the user asking?"
);

4. Filtered Queries

Leverage Weaviate’s filtering for metadata-based retrieval.

$filteredResults = $store->findNearest(
    $vector,
    filter: [
        'operator' => 'And',
        'operands' => [
            ['path' => ['category'], 'operator' => 'Equal', 'valueString' => 'tech'],
            ['path' => ['rating'], 'operator' => 'GreaterThan', 'valueNumber' => 4],
        ],
    ]
);

Laravel-Specific Patterns

1. Service Provider Wrapper

Extend the Symfony store with Laravel-specific features:

// app/Services/WeaviateStoreDecorator.php
class WeaviateStoreDecorator implements StoreInterface
{
    use StoreTrait;

    public function __construct(private StoreInterface $store) {}

    public function findNearest(array $vector, int $limit = 3, ?array $filter = null): array
    {
        $results = $this->store->findNearest($vector, $limit, $filter);

        // Add Laravel-specific logic (e.g., caching, logging)
        Cache::remember("weaviate_{$vector[0]}", now()->addHours(1), fn() => $results);

        return $results;
    }
}

2. Queued Batch Processing

Offload heavy operations to Laravel Queues:

// app/Jobs/UpsertWeaviateVectors.php
class UpsertWeaviateVectors implements ShouldQueue
{
    public function handle(StoreInterface $store, array $vectors)
    {
        foreach ($vectors as $vector) {
            $store->upsert($vector);
        }
    }
}

3. Event-Driven Updates

Trigger Weaviate updates via Laravel Events:

// In a model observer
ModelObserved::created(function ($model) {
    UpsertWeaviateVector::dispatch(
        $model->toVectorArray(), // Convert model to vector format
        $model->weaviateCollection
    );
});

4. Caching Layer

Cache frequent queries with Laravel Cache:

public function findNearest(array $vector, int $limit = 3, ?array $filter = null): array
{
    $cacheKey = md5(serialize([$vector, $limit, $filter]));
    return Cache::remember($cacheKey, now()->addMinutes(5), function() use ($vector, $limit, $filter) {
        return $this->store->findNearest($vector, $limit, $filter);
    });
}

Gotchas and Tips

Pitfalls

1. Schema Mismatches

Issue: Weaviate collections must match the expected schema (e.g., embedding property type, metadata fields).

Fix: Define the schema once and validate before upserts:

// Check if collection exists and has correct schema
$client = $store->getHttpClient();
$response = $client->request('GET', '/v1/schema');
if (!isset($response['data']['collections'][$config['collection']])) {
    throw new \RuntimeException("Weaviate collection not found");
}

2. Vector Dimension Mismatch

Issue: Weaviate requires all vectors in a collection to have the same dimension. Upserting mismatched vectors fails silently or corrupts data.

Fix: Validate dimensions before upsert:

$expectedDim = 384; // Example: 'text-embedding-ada-002' outputs 1536 dims
if (count($vector) !== $expectedDim) {
    throw new \InvalidArgumentException("Vector dimension mismatch");
}

3. Rate Limiting

Issue: Weaviate’s default rate limits (e.g., 100

Ai Weaviate Store Laravel Package