@rcrsr/rill-ext-pinecone 0.8.6 → 0.11.0

package/README.md

@@ -39,213 +39,16 @@ const result = await execute(parse(script), ctx);
 dispose?.();
 ```
 
-## Host Functions
-
-All vector database extensions share identical function signatures. Swap `pinecone::` for `qdrant::` or `chroma::` with no script changes.
-
-### pinecone::upsert(id, vector, metadata?)
-
-Insert or update a single vector with metadata.
-
-```rill
-pinecone::upsert("doc-1", $embedding, [title: "Example", page: 1]) => $result
-$result.id -> log       # "doc-1"
-$result.success -> log  # true
-```
-
-**Idempotent.** Duplicate ID overwrites existing vector.
-
-### pinecone::upsert_batch(items)
-
-Batch insert or update vectors. Processes sequentially; halts on first failure.
-
-```rill
-pinecone::upsert_batch([
-  [id: "doc-1", vector: $v1, metadata: [title: "First"]],
-  [id: "doc-2", vector: $v2, metadata: [title: "Second"]]
-]) => $result
-$result.succeeded -> log  # 2
-```
-
-Returns `{ succeeded }` on success. Returns `{ succeeded, failed, error }` on failure.
-
-### pinecone::search(vector, options?)
-
-Search for k nearest neighbors.
-
-```rill
-pinecone::search($embedding, [k: 5, score_threshold: 0.8]) => $results
-$results -> each { "{.id}: {.score}" -> log }
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `k` | number | `10` | Max results to return |
-| `filter` | dict | `{}` | Metadata filter conditions |
-| `score_threshold` | number | (none) | Exclude results below threshold |
-
-Returns `[{ id, score, metadata }]`. Empty results return `[]`.
-
-### pinecone::get(id)
-
-Fetch a vector by ID.
-
-```rill
-pinecone::get("doc-1") => $point
-$point.id -> log        # "doc-1"
-$point.metadata -> log  # [title: "Example", page: 1]
-```
-
-Returns `{ id, vector, metadata }`. Halts with error if ID not found.
-
-### pinecone::delete(id)
-
-Delete a vector by ID.
-
-```rill
-pinecone::delete("doc-1") => $result
-$result.deleted -> log  # true
-```
-
-Returns `{ id, deleted }`. Halts with error if ID not found.
-
-### pinecone::delete_batch(ids)
-
-Batch delete vectors. Processes sequentially; halts on first failure.
-
-```rill
-pinecone::delete_batch(["doc-1", "doc-2", "doc-3"]) => $result
-$result.succeeded -> log  # 3
-```
-
-Returns `{ succeeded }` on success. Returns `{ succeeded, failed, error }` on failure.
-
-### pinecone::count()
-
-Count vectors in the index.
-
-```rill
-pinecone::count() -> log  # 42
-```
-
-Returns a number.
-
-### pinecone::create_collection(name, options?)
-
-Create a new collection.
-
-```rill
-pinecone::create_collection("my_vectors", [dimensions: 384, distance: "cosine"]) => $result
-$result.created -> log  # true
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `dimensions` | number | (none) | Vector dimension size |
-| `distance` | string | `"cosine"` | `"cosine"`, `"euclidean"`, or `"dot"` |
-
-Returns `{ name, created }`. **Not idempotent** — halts if collection exists.
-
-### pinecone::delete_collection(id)
-
-Delete a collection.
-
-```rill
-pinecone::delete_collection("old_vectors") => $result
-$result.deleted -> log  # true
-```
-
-Returns `{ name, deleted }`. **Not idempotent** — halts if collection not found.
-
-### pinecone::list_collections()
-
-List all collection names.
-
-```rill
-pinecone::list_collections() -> log  # ["my_vectors", "archive"]
-```
-
-Returns a list of strings.
-
-### pinecone::describe()
-
-Describe the configured index.
-
-```rill
-pinecone::describe() => $info
-$info.name -> log        # "my-index"
-$info.count -> log       # 42
-$info.dimensions -> log  # 384
-$info.distance -> log    # "cosine"
-```
-
-Returns `{ name, count, dimensions, distance }`.
-
-## Configuration
-
-```typescript
-const ext = createPineconeExtension({
-  apiKey: process.env.PINECONE_API_KEY!,
-  index: 'my-index',
-  namespace: 'production',
-  timeout: 30000,
-});
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `apiKey` | string | required | Pinecone API key |
-| `index` | string | required | Index name |
-| `namespace` | string | `''` | Namespace for partitioning |
-| `timeout` | number | `30000` | Request timeout in ms |
-
-## Error Handling
-
-All errors use `RuntimeError('RILL-R004', 'pinecone: <message>')` and halt script execution.
-
-| Condition | Message |
-|-----------|---------|
-| HTTP 401 | `pinecone: authentication failed (401)` |
-| Collection not found | `pinecone: collection not found` |
-| Rate limit (429) | `pinecone: rate limit exceeded` |
-| Timeout | `pinecone: request timeout` |
-| Dimension mismatch | `pinecone: dimension mismatch (expected N, got M)` |
-| Collection exists | `pinecone: collection already exists` |
-| ID not found | `pinecone: id not found` |
-| After dispose | `pinecone: operation cancelled` |
-| Other | `pinecone: <error message>` |
-
-## Cloud Setup
-
-Create a free account at [pinecone.io](https://www.pinecone.io). Find your API key in the Pinecone Console under **API Keys**.
-
-```bash
-pinecone index create my-index \
-  --dimension 384 \
-  --metric cosine \
-  --cloud aws \
-  --region us-east-1
-```
-
-Free tier includes 1 serverless index, 2GB storage, 10K vectors per namespace. See [Pinecone Pricing](https://www.pinecone.io/pricing/) for current limits.
-
-## Lifecycle
-
-```typescript
-const ext = createPineconeExtension({ ... });
-// ... use extension ...
-await ext.dispose?.();
-```
+## Documentation
 
-`dispose()` aborts pending requests and closes the SDK client. Idempotent — second call resolves without error.
+See [full documentation](docs/extension-vectordb-pinecone.md) for configuration, functions, error handling, and cloud setup.
 
-## Documentation
+## Related
 
-| Document | Description |
-|----------|-------------|
-| [Extensions Guide](https://github.com/rcrsr/rill/blob/main/docs/integration-extensions.md) | Extension contract and patterns |
-| [Host API Reference](https://github.com/rcrsr/rill/blob/main/docs/ref-host-api.md) | Runtime context and host functions |
-| [Pinecone Documentation](https://docs.pinecone.io) | Official Pinecone docs |
+- [rill](https://github.com/rcrsr/rill) — Core language runtime
+- [Extensions Guide](https://github.com/rcrsr/rill/blob/main/docs/integration-extensions.md) — Extension contract and patterns
+- [Host API Reference](https://github.com/rcrsr/rill/blob/main/docs/ref-host-api.md) — Runtime context and host functions
+- [Pinecone Documentation](https://docs.pinecone.io) — Official Pinecone docs
 
 ## License
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 // Generated by dts-bundle-generator v9.5.1
 
-import { ExtensionResult } from '@rcrsr/rill';
+import { ExtensionConfigSchema, ExtensionResult } from '@rcrsr/rill';
 
 /**
  * Type definitions for Pinecone extension.
@@ -84,5 +84,6 @@ export type PineconeExtensionConfig = PineconeConfig;
  */
 export declare function createPineconeExtension(config: PineconeConfig): ExtensionResult;
 export declare const VERSION = "0.0.1";
+export declare const configSchema: ExtensionConfigSchema;
 
 export {};

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/factory.ts
 import { Pinecone } from "@pinecone-database/pinecone";
 import {
-  RuntimeError as RuntimeError4,
+  RuntimeError as RuntimeError6,
   emitExtensionEvent as emitExtensionEvent3,
   createVector
 } from "@rcrsr/rill";
@@ -111,18 +111,156 @@ function assertRequired(value, fieldName) {
 // ../../shared/ext-vector/dist/wrapper.js
 import { emitExtensionEvent as emitExtensionEvent2 } from "@rcrsr/rill";
 
+// ../../shared/ext-vector/dist/param.js
+import { RuntimeError as RuntimeError4 } from "@rcrsr/rill";
+function validateParamName(name) {
+  if (name === "")
+    throw new RuntimeError4("RILL-R001", "param name must not be empty");
+  if (/\s/.test(name))
+    throw new RuntimeError4("RILL-R001", "param name must be a valid identifier");
+}
+function vectorParam(name) {
+  validateParamName(name);
+  return {
+    name,
+    type: { type: "vector" },
+    defaultValue: void 0,
+    annotations: {}
+  };
+}
+
+// ../../shared/ext-param/dist/param.js
+import { RuntimeError as RuntimeError5 } from "@rcrsr/rill";
+function validateParamName2(name) {
+  if (name === "") {
+    throw new RuntimeError5("RILL-R001", "param name must not be empty");
+  }
+  if (/\s/.test(name)) {
+    throw new RuntimeError5("RILL-R001", "param name must be a valid identifier");
+  }
+}
+function buildAnnotations(desc) {
+  if (desc !== void 0) {
+    return { description: desc };
+  }
+  return {};
+}
+var p = {
+  /**
+   * IR-1: Creates a string parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param desc - Optional description
+   * @returns RillParam with type 'string'
+   */
+  str(name, desc) {
+    validateParamName2(name);
+    return {
+      name,
+      type: { type: "string" },
+      defaultValue: void 0,
+      annotations: buildAnnotations(desc)
+    };
+  },
+  /**
+   * IR-2: Creates a number parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param desc - Optional description
+   * @param def - Optional default value
+   * @returns RillParam with type 'number'
+   */
+  num(name, desc, def) {
+    validateParamName2(name);
+    return {
+      name,
+      type: { type: "number" },
+      defaultValue: def,
+      annotations: buildAnnotations(desc)
+    };
+  },
+  /**
+   * IR-3: Creates a boolean parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param desc - Optional description
+   * @param def - Optional default value
+   * @returns RillParam with type 'bool'
+   */
+  bool(name, desc, def) {
+    validateParamName2(name);
+    return {
+      name,
+      type: { type: "bool" },
+      defaultValue: def,
+      annotations: buildAnnotations(desc)
+    };
+  },
+  /**
+   * IR-4: Creates a dict parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param desc - Optional description
+   * @param def - Optional default value
+   * @returns RillParam with type 'dict'
+   */
+  dict(name, desc, def) {
+    validateParamName2(name);
+    return {
+      name,
+      type: { type: "dict" },
+      defaultValue: def,
+      annotations: buildAnnotations(desc)
+    };
+  },
+  /**
+   * IR-5: Creates a list parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param itemType - Optional element type; omitted when not provided
+   * @param desc - Optional description
+   * @returns RillParam with type 'list' (with element if itemType provided)
+   */
+  list(name, itemType, desc) {
+    validateParamName2(name);
+    const type = itemType !== void 0 ? { type: "list", element: itemType } : { type: "list" };
+    return {
+      name,
+      type,
+      defaultValue: void 0,
+      annotations: buildAnnotations(desc)
+    };
+  },
+  /**
+   * IR-6: Creates a callable parameter descriptor.
+   *
+   * @param name - Parameter name (must be a valid identifier)
+   * @param desc - Optional description
+   * @returns RillParam with type 'closure'
+   */
+  callable(name, desc) {
+    validateParamName2(name);
+    return {
+      name,
+      type: { type: "closure" },
+      defaultValue: void 0,
+      annotations: buildAnnotations(desc)
+    };
+  }
+};
+
 // src/factory.ts
 function mapPineconeError(error) {
   if (error instanceof Error) {
     const message = error.message;
     if (message.toLowerCase().includes("authentication")) {
-      return new RuntimeError4(
+      return new RuntimeError6(
         "RILL-R004",
         "pinecone: authentication failed (401)"
       );
     }
     if (message.toLowerCase().includes("index") && message.toLowerCase().includes("not found")) {
-      return new RuntimeError4("RILL-R004", "pinecone: collection not found");
+      return new RuntimeError6("RILL-R004", "pinecone: collection not found");
     }
   }
   return mapVectorError("pinecone", error);
@@ -157,9 +295,9 @@ function createPineconeExtension(config) {
     // IR-1: pinecone::upsert
     upsert: {
       params: [
-        { name: "id", type: "string" },
-        { name: "vector", type: "vector" },
-        { name: "metadata", type: "dict", defaultValue: {} }
+        p.str("id"),
+        vectorParam("vector"),
+        p.dict("metadata", void 0, {})
       ],
       fn: async (args, ctx) => {
         checkDisposed2();
@@ -174,13 +312,15 @@ function createPineconeExtension(config) {
           { id },
           async () => {
             const index = client.Index(factoryIndex);
-            await index.namespace(factoryNamespace).upsert([
-              {
-                id,
-                values: Array.from(vector.data),
-                metadata
-              }
-            ]);
+            await index.namespace(factoryNamespace).upsert({
+              records: [
+                {
+                  id,
+                  values: Array.from(vector.data),
+                  metadata
+                }
+              ]
+            });
             return {
               id,
               success: true
@@ -189,11 +329,11 @@ function createPineconeExtension(config) {
         );
       },
       description: "Insert or update single vector with metadata",
-      returnType: "dict"
+      returnType: { type: "dict" }
     },
     // IR-2: pinecone::upsert_batch
     upsert_batch: {
-      params: [{ name: "items", type: "list" }],
+      params: [p.list("items")],
       fn: async (args, ctx) => {
         const startTime = Date.now();
         try {
@@ -224,13 +364,15 @@ function createPineconeExtension(config) {
             const metadataArg = item["metadata"] ?? {};
             const metadata = convertMetadata(metadataArg);
             try {
-              await index.namespace(factoryNamespace).upsert([
-                {
-                  id,
-                  values: Array.from(vector.data),
-                  metadata
-                }
-              ]);
+              await index.namespace(factoryNamespace).upsert({
+                records: [
+                  {
+                    id,
+                    values: Array.from(vector.data),
+                    metadata
+                  }
+                ]
+              });
               succeeded++;
             } catch (error) {
               const rillError = mapPineconeError(error);
@@ -272,13 +414,13 @@ function createPineconeExtension(config) {
         }
       },
       description: "Batch insert/update vectors",
-      returnType: "dict"
+      returnType: { type: "dict" }
     },
     // IR-3: pinecone::search
     search: {
       params: [
-        { name: "vector", type: "vector" },
-        { name: "options", type: "dict", defaultValue: {} }
+        vectorParam("vector"),
+        p.dict("options", void 0, {})
       ],
       fn: async (args, ctx) => {
         checkDisposed2();
@@ -344,11 +486,11 @@ function createPineconeExtension(config) {
         }
       },
       description: "Search k nearest neighbors",
-      returnType: "list"
+      returnType: { type: "list" }
     },
     // IR-4: pinecone::get
     get: {
-      params: [{ name: "id", type: "string" }],
+      params: [p.str("id")],
       fn: async (args, ctx) => {
         checkDisposed2();
         const id = args[0];
@@ -359,14 +501,14 @@ function createPineconeExtension(config) {
           { id },
           async () => {
             const index = client.Index(factoryIndex);
-            const response = await index.namespace(factoryNamespace).fetch([id]);
+            const response = await index.namespace(factoryNamespace).fetch({ ids: [id] });
             if (!response.records || response.records[id] === void 0) {
-              throw new RuntimeError4("RILL-R004", "pinecone: id not found");
+              throw new RuntimeError6("RILL-R004", "pinecone: id not found");
             }
             const record = response.records[id];
             const vectorData = record.values;
             if (!vectorData || !Array.isArray(vectorData)) {
-              throw new RuntimeError4(
+              throw new RuntimeError6(
                 "RILL-R004",
                 "pinecone: invalid vector format"
               );
@@ -382,11 +524,11 @@ function createPineconeExtension(config) {
         );
       },
       description: "Fetch vector by ID",
-      returnType: "dict"
+      returnType: { type: "dict" }
     },
     // IR-5: pinecone::delete
     delete: {
-      params: [{ name: "id", type: "string" }],
+      params: [p.str("id")],
       fn: async (args, ctx) => {
         checkDisposed2();
         const id = args[0];
@@ -398,7 +540,7 @@ function createPineconeExtension(config) {
           async () => {
             const index = client.Index(factoryIndex);
             const ns = factoryNamespace || "";
-            await index.namespace(ns).deleteOne(id);
+            await index.namespace(ns).deleteOne({ id });
             return {
               id,
               deleted: true
@@ -407,11 +549,11 @@ function createPineconeExtension(config) {
         );
       },
       description: "Delete vector by ID",
-      returnType: "dict"
+      returnType: { type: "dict" }
     },
     // IR-6: pinecone::delete_batch
     delete_batch: {
-      params: [{ name: "ids", type: "list" }],
+      params: [p.list("ids")],
       fn: async (args, ctx) => {
         const startTime = Date.now();
         try {
@@ -422,7 +564,7 @@ function createPineconeExtension(config) {
           for (let i = 0; i < ids.length; i++) {
             const id = ids[i];
             try {
-              await index.namespace(factoryNamespace).deleteOne(id);
+              await index.namespace(factoryNamespace).deleteOne({ id });
               succeeded++;
             } catch (error) {
               const rillError = mapPineconeError(error);
@@ -464,7 +606,7 @@ function createPineconeExtension(config) {
         }
       },
       description: "Batch delete vectors",
-      returnType: "dict"
+      returnType: { type: "dict" }
     },
     // IR-7: pinecone::count
     count: {
@@ -485,13 +627,13 @@ function createPineconeExtension(config) {
         );
       },
       description: "Return total vector count in collection",
-      returnType: "number"
+      returnType: { type: "number" }
     },
     // IR-8: pinecone::create_collection
     create_collection: {
       params: [
-        { name: "name", type: "string" },
-        { name: "options", type: "dict", defaultValue: {} }
+        p.str("name"),
+        p.dict("options", void 0, {})
       ],
       fn: async (args, ctx) => {
         checkDisposed2();
@@ -500,7 +642,7 @@ function createPineconeExtension(config) {
         const dimensions = options["dimensions"];
         const distance = options["distance"] ?? "cosine";
         if (!dimensions || typeof dimensions !== "number" || dimensions <= 0) {
-          throw new RuntimeError4(
+          throw new RuntimeError6(
             "RILL-R004",
             "pinecone: dimensions must be a positive integer"
           );
@@ -538,11 +680,11 @@ function createPineconeExtension(config) {
         );
       },
       description: "Create new vector collection",
-      returnType: "dict"
+      returnType: { type: "dict" }
     },
     // IR-9: pinecone::delete_collection
     delete_collection: {
-      params: [{ name: "name", type: "string" }],
+      params: [p.str("name")],
       fn: async (args, ctx) => {
         checkDisposed2();
         const name = args[0];
@@ -561,7 +703,7 @@ function createPineconeExtension(config) {
         );
       },
       description: "Delete vector collection",
-      returnType: "dict"
+      returnType: { type: "dict" }
     },
     // IR-10: pinecone::list_collections
     list_collections: {
@@ -581,7 +723,7 @@ function createPineconeExtension(config) {
         );
       },
       description: "List all collection names",
-      returnType: "list"
+      returnType: { type: "list" }
     },
     // IR-11: pinecone::describe
     describe: {
@@ -618,7 +760,7 @@ function createPineconeExtension(config) {
         );
       },
       description: "Describe configured collection",
-      returnType: "dict"
+      returnType: { type: "dict" }
     }
   };
   result.dispose = dispose2;
@@ -627,7 +769,14 @@ function createPineconeExtension(config) {
 
 // src/index.ts
 var VERSION = "0.0.1";
+var configSchema = {
+  apiKey: { type: "string", required: true, secret: true },
+  index: { type: "string", required: true },
+  namespace: { type: "string" },
+  timeout: { type: "number" }
+};
 export {
   VERSION,
+  configSchema,
   createPineconeExtension
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rcrsr/rill-ext-pinecone",
-  "version": "0.8.6",
+  "version": "0.11.0",
   "description": "rill extension for Pinecone vector database integration",
   "license": "MIT",
   "author": "Andre Bremer",
@@ -17,14 +17,14 @@
     "scripting"
   ],
   "peerDependencies": {
-    "@rcrsr/rill": "^0.8.6"
+    "@rcrsr/rill": "^0.11.0"
   },
   "devDependencies": {
-    "@types/node": "^25.2.3",
+    "@rcrsr/rill": "^0.11.0",
+    "@types/node": "^25.3.0",
     "dts-bundle-generator": "^9.5.1",
-    "tsup": "^8.5.0",
-    "undici-types": "^7.21.0",
-    "@rcrsr/rill": "^0.8.6",
+    "tsup": "^8.5.1",
+    "undici-types": "^7.22.0",
     "@rcrsr/rill-ext-vector-shared": "^0.0.1"
   },
   "files": [
@@ -32,18 +32,19 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rcrsr/rill.git",
+    "url": "git+https://github.com/rcrsr/rill-ext.git",
     "directory": "packages/ext/vectordb-pinecone"
   },
-  "homepage": "https://rill.run/docs/extensions/pinecone/",
+  "homepage": "https://github.com/rcrsr/rill-ext/tree/main/packages/ext/vectordb-pinecone#readme",
   "bugs": {
-    "url": "https://github.com/rcrsr/rill/issues"
+    "url": "https://github.com/rcrsr/rill-ext/issues"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@pinecone-database/pinecone": "^3.0.3"
+    "@pinecone-database/pinecone": "^7.1.0",
+    "@rcrsr/rill-ext-param-shared": "^0.0.1"
   },
   "scripts": {
     "build": "tsup && dts-bundle-generator --config dts-bundle-generator.config.cjs",