readme

probots-io · Feb 21, 2024 · c67b86f · c67b86f
1 parent 67bf3e1
commit c67b86f
Showing 1 changed file with 89 additions and 26 deletions.
diff --git 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