README

Overview

adachsoft/vector-store-json-file is a file-based implementation of the VectorStoreInterface from the adachsoft/vector-store-contracts package.

Each vector collection is stored as a single JSON file on disk. The JSON file contains:

• global configuration of the collection (dimensions, distance metric),
• all vector records (embeddings),
• arbitrary metadata attached to each record.

This package is intended for small to medium vector stores where a simple JSON file is sufficient and a database or external service would be overkill.

Requirements

• PHP 8.3 or higher
• Composer
• Runtime dependencies:
  • adachsoft/vector-store-contracts (vector store contracts and DTOs)
  • adachsoft/collection (immutable collections for vectors and metadata)

Installation

Install the package via Composer:

composer require adachsoft/vector-store-json-file

Usage

Basic store setup

use AdachSoft\VectorStoreJsonFile\JsonFileVectorStore;
use AdachSoft\VectorStoreContracts\Enum\DistanceMetricEnum;

$storagePath = __DIR__ . '/var/vector-store';

// Create the store instance (the directory must exist and be writable)
$store = new JsonFileVectorStore($storagePath);

// Create a new collection backed by a single JSON file
$store->createCollection('documents', 384, DistanceMetricEnum::COSINE);

// Get a repository for this collection
$repository = $store->getCollection('documents');

Upserting and searching

use AdachSoft\VectorStoreContracts\Dto\VectorRecordDto;
use AdachSoft\VectorStoreContracts\Dto\SearchQueryDto;
use AdachSoft\VectorStoreContracts\Collection\FilterCollection;

// Upsert a vector record
$record = new VectorRecordDto(
    'doc-123',
    // 384-dimensional vector (example values)
    [0.1, 0.2, 0.3, 0.4 /* ... */],
    ['category' => 'technology', 'language' => 'en']
);

$repository->upsert($record);

// Build a search query
$query = new SearchQueryDto(
    [0.11, 0.21, 0.31, 0.41 /* ... */], // query vector
    5,                                   // topK
    null,                                // optional minimum score
    new FilterCollection(['language' => 'en'])
);

// Execute the search
$results = $repository->search($query);

foreach ($results as $result) {
    $record = $result->record;
    $score  = $result->score;

    // Handle the result (e.g. display ID and score)
}

Using the factory

If you prefer configuration-based creation, you can use the factory:

use AdachSoft\VectorStoreJsonFile\JsonFileVectorStoreFactory;

$factory = new JsonFileVectorStoreFactory();

$store = $factory->create([
    'storage_path' => __DIR__ . '/var/vector-store',
]);

Testing

This project includes a test suite based on the contract tests from adachsoft/vector-store-contracts.

Run tests with:

vendor/bin/phpunit

The test configuration is defined in phpunit.xml in the project root.

Code style and static analysis

The project uses adachsoft/php-code-style for a unified code style, Rector rules and PHPStan configuration.

Convenience Composer scripts:

composer cs:check  # run PHP-CS-Fixer in dry-run mode
composer cs:fix    # fix coding style issues
composer stan      # run PHPStan analysis
composer rector    # run Rector refactorings

License

This library is open-sourced under the MIT license. See the license field in composer.json for details.