diff --git a/README.md b/README.md index 2d06d0f..e471fb8 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,9 @@ A beautiful, extendable PHP Package to communicate with your [pinecone.io](https vectors, powered by [Saloon](https://github.com/saloonphp/saloon). > **Info** -> This package is not yet usable. Working on Upgrading to the latest Pinecone API. +> 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! [![probots.io](art/probots-banner-1000x400.png)](https://probots.io) @@ -32,34 +34,90 @@ First, you will need to create an Api Key in your [pinecone.io](https://pinecone ```php use \Probots\Pinecone\Client as Pinecone; - $apiKey = 'YOUR_PINECONE_API_KEY'; -$environment = 'YOU_PINECONE_ENVIRONMENT'; // Initialize Pinecone -$pinecone = new Pinecone($apiKey, $environment); +$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. + +```php +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 + +```php +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 +``` + ## Responses All responses are returned as a `Response` object. Please check the [Saloon documentation](https://docs.saloon.dev/the-basics/responses#available-methods) to see all available methods. +# Control Pane + ## Index Operations Work(s) with your indices. -### Create Index +### Create Index (POD) [Pinecone Docs](https://docs.pinecone.io/reference/create_index) ```php -$response = $pinecone->index()->create( - name: 'my-index', - dimension: 1536 +$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](https://docs.pinecone.io/reference/create_index) + +```php +$response = $pinecone->control()->index('my-index')->createServerless( + dimension: 1536, + metric: 'cosine', + cloud: 'aws', + region: 'us-west-2' + // ... more options ); if($response->successful()) { @@ -72,7 +130,7 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/describe_index) ```php -$response = $pinecone->index('my-index')->describe(); +$response = $pinecone->control()->index('my-index')->describe(); if($response->successful()) { // @@ -84,7 +142,7 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/list_indexes) ```php -$response = $pinecone->index()->list(); +$response = $pinecone->control()->index()->list(); if($response->successful()) { // @@ -96,7 +154,7 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/configure_index) ```php -$response = $pinecone->index('my-index')->configure( +$response = $pinecone->control()->index('my-index')->configure( pod_type: 'p1.x1', replicas: 1 ); @@ -111,7 +169,7 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/delete_index) ```php -$response = $pinecone->index('my-index')->delete(); +$response = $pinecone->control()->index('my-index')->delete(); if($response->successful()) { // @@ -127,8 +185,7 @@ Work(s) with your collections too. [Pinecone Docs](https://docs.pinecone.io/reference/create_collection) ```php -$response = $pinecone->collections()->create( - name: 'my-collection', +$response = $pinecone->control()->collections('my-collection')->create( source: 'my-index' ); @@ -142,7 +199,7 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/describe_collection) ```php -$response = $pinecone->collections('my-collection')->describe(); +$response = $pinecone->control()->collections('my-collection')->describe(); if($response->successful()) { // @@ -154,7 +211,7 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/list_collections) ```php -$response = $pinecone->collections()->list(); +$response = $pinecone->control()->collections()->list(); if($response->successful()) { // @@ -166,23 +223,29 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/delete_collection) ```php -$response = $pinecone->collections('my-collection')->delete(); +$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. -### Describe Index Stats +### Get Index Stats -TBD +[Pinecone Docs](https://docs.pinecone.io/reference/describe_index_stats) ```php -$response = $pinecone->index('my-index')->vectors()->stats(); +$response = $pinecone->data()->vectors()->stats(); if($response->successful()) { // @@ -194,7 +257,7 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/update) ```php -$response = $pinecone->index('my-index')->vectors()->update( +$response = $pinecone->data()->vectors()->update( id: 'vector_1', values: array_fill(0, 128, 0.14), setMetadata: [ @@ -212,7 +275,7 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/upsert) ```php -$response = $pinecone->index('my-index')->vectors()->upsert(vectors: [ +$response = $pinecone->data()->vectors()->upsert(vectors: [ 'id' => 'vector_1', 'values' => array_fill(0, 128, 0.14), 'metadata' => [ @@ -230,7 +293,7 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/query) ```php -$response = $pinecone->index('my-index')->vectors()->query( +$response = $pinecone->data()->vectors()->query( vector: array_fill(0, 128, 0.12), topK: 1, ); @@ -245,7 +308,7 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/delete_post) ```php -$response = $pinecone->index('my-index')->vectors()->delete( +$response = $pinecone->data()->vectors()->delete( deleteAll: true ); @@ -259,7 +322,7 @@ if($response->successful()) { [Pinecone Docs](https://docs.pinecone.io/reference/fetch) ```php -$response = $pinecone->index('my-index')->vectors()->fetch([ +$response = $pinecone->data()->vectors()->fetch([ 'vector_1', 'vector_2' ]); @@ -282,7 +345,7 @@ Copy .env.example to .env and update accordingly. The MIT License (MIT). Please see [License File](LICENSE.md) for more information. -## TODO: +## TODO - Submit PR if you want to contribute: - [ ] validate parameters based on API docs - needs more checking - [ ] Implement Custom Exceptions