probots-io/pinecone-php

Unofficial PHP Client for Pinecone Vector Database (pinecone.io)

1.0.1 2024-02-21 16:15 UTC

Requires

• php: ^8.2
• saloonphp/saloon: ^3.6

Requires (Dev)

• pestphp/pest: ^2.4
• pestphp/pest-plugin-faker: ^2.0
• pestphp/pest-plugin-watch: ^2.0
• phpstan/phpstan: ^1.10
• symfony/var-dumper: ^6.2
• vlucas/phpdotenv: ^5.5

MIT

• Marcus Pohorely

• database
• client
• sdk
• vector
• pinecone

README

A beautiful, extendable PHP Package to communicate with your pinecone.io indices, collections and vectors, powered by Saloon.

Info From Version 1.x onwards we are using the latest Pinecone API which support serverless. If you need the legacy API please use a version before 1.0.0!

Introduction

This API provides a feature rich, elegant baseline for working with the pinecone.io API. Developers can install and leverage this API to help them integrate pinecone.io easily and beautifully.

Installation

composer require probots-io/pinecone-php

Features

Currently supports all of the available endpoints in the pinecone.io API based on the official documentation

Authentication

Authentication via Api Key is the only available authentication methods currently supported. First, you will need to create an Api Key in your pinecone.io instance.

use \Probots\Pinecone\Client as Pinecone;

$apiKey = 'YOUR_PINECONE_API_KEY';

// Initialize Pinecone
$pinecone = new Pinecone($apiKey);

// Now you are ready to make requests, all requests will be authenticated automatically.

Quick Start

There are two ways to initialize the SDK. You can either provide an index during initialization or you can provide it later on.

use \Probots\Pinecone\Client as Pinecone;

$apiKey = 'YOUR_PINECONE_API_KEY';
$pinecone = new Pinecone($apiKey);

// all control methods are available now, create an index or similar
// e.g. $pinecone->control()->index()

// later on you can provide the index
$pinecone->setIndexHost('INDEX_HOST_FROM_PINECONE');

// data methods are available now

// e.g. $pinecone->data()->vectors()

or

use \Probots\Pinecone\Client as Pinecone;

$apiKey = 'YOUR_PINECONE_API_KEY';
$indexHost = 'INDEX_HOST_FROM_PINECONE';

$pinecone = new Pinecone($apiKey, $indexHost);

// all control AND data methods are available now

Info The index host should include https://, which you may need to prepend to the value returned from Pinecone.

Responses

All responses are returned as a Response object. Please check the Saloon documentation to see all available methods.

Control Pane

Index Operations

Work(s) with your indices.

Create Index (POD)

Pinecone Docs

$response = $pinecone->control()->index('my-index')->createPod(
    dimension: 1536,
    metric: 'cosine',
    podType: 'p1.x1',
    replicas: 1
    // ... more options    
);

if($response->successful()) {
    // 
}

Create Index (Serverless)

Pinecone Docs

$response = $pinecone->control()->index('my-index')->createServerless(
    dimension: 1536,
    metric: 'cosine',
    cloud: 'aws',
    region: 'us-west-2'
    // ... more options    
);

if($response->successful()) {
    // 
}

Describe Index

Pinecone Docs

$response = $pinecone->control()->index('my-index')->describe();

if($response->successful()) {
    // 
}

List Indices

Pinecone Docs

$response = $pinecone->control()->index()->list();

if($response->successful()) {
    // 
}

Configure Index

Pinecone Docs

$response = $pinecone->control()->index('my-index')->configure(
    pod_type: 'p1.x1',
    replicas: 1
);

if($response->successful()) {
    // 
}

Delete Index

Pinecone Docs

$response = $pinecone->control()->index('my-index')->delete();

if($response->successful()) {
    // 
}

Collection Operations

Work(s) with your collections too.

Create Collection

Pinecone Docs

$response = $pinecone->control()->collections('my-collection')->create(
    source: 'my-index'
);

if($response->successful()) {
    // 
}

Describe Collection

Pinecone Docs

$response = $pinecone->control()->collections('my-collection')->describe();

if($response->successful()) {
    // 
}

List Collections

Pinecone Docs

$response = $pinecone->control()->collections()->list();

if($response->successful()) {
    // 
}

Delete Collections

Pinecone Docs

$response = $pinecone->control()->collections('my-collection')->delete();

if($response->successful()) {
    // 
}

Data Pane

Info These operations need the index to be set. You can set the index during initialization or later on. See description at the beginning.

Vector Operations

Vectors are the basic unit of data in Pinecone. Use them.

Get Index Stats

Pinecone Docs

$response = $pinecone->data()->vectors()->stats();

if($response->successful()) {
    // 
}

Update Vector

Pinecone Docs

$response = $pinecone->data()->vectors()->update(
    id: 'vector_1',
    values: array_fill(0, 128, 0.14),
    setMetadata: [
        'meta1' => 'value1',
    ]
);

if($response->successful()) {
    // 
}

Upsert Vectors

Pinecone Docs

$response = $pinecone->data()->vectors()->upsert(vectors: [
    'id' => 'vector_1',
    'values' => array_fill(0, 128, 0.14),
    'metadata' => [
        'meta1' => 'value1',
    ]
]);

if($response->successful()) {
    // 
}

Query Vectors

Pinecone Docs

$response = $pinecone->data()->vectors()->query(
    vector: array_fill(0, 128, 0.12),
    topK: 1,
);

if($response->successful()) {
    // 
}

Delete Vectors

Pinecone Docs

$response = $pinecone->data()->vectors()->delete(
    deleteAll: true
);

if($response->successful()) {
    // 
}

Fetch Vectors

Pinecone Docs

$response = $pinecone->data()->vectors()->fetch([
    'vector_1', 'vector_2'
]);

if($response->successful()) {
    // 
}

Testing

Testing is done via PestPHP. You can run the tests by running ./vendor/bin/pest in the root of the project. Copy .env.example to .env and update accordingly.

Credits

• Marcus Pohorely
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

TODO - Submit PR if you want to contribute:

• validate parameters based on API docs - needs more checking
• Implement Custom Exceptions
• Add failure tests
• Add some examples
• Finish docs