Node SDK Visit the GitHub Repo
Installation
npm install @getmetal/metal-sdk
yarn add @getmetal/metal-sdk
Retrieval
App Setup
Param Type Description apiKey
string The API Key for your Org. Learn more. clientId
string The Client ID for your Org. Learn more. indexId
string The ID of the index you want to connect with. Learn more.
import { Metal } from "@getmetal/metal-sdk" ;
const metal = new Metal ( "pk_123" , "ci_123" , "index-id" ) ;
addApp()
Parameters
Param Type Description name
string Name of the app.
const app = await metal. addApp ( {
name: "My App" ,
indexes: [ "index-id" ]
} ) ;
getApp()
Parameters
Param Type Description appId
string Identifier for the app.
const app = await metal. getApp ( "app-id" ) ;
getApps()
const apps = await metal. getApps ( ) ;
updateApp()
Parameters
Param Type Description appId
string The unique identifier of the app you want to update. name
string (optional) The updated name for the App. indexes
array (optional) An updated array of the index connected to the app.
const app = await metal. updateApp ( "app-id" , { name: "updated name" , indexes: [ "index-id" ] } ) ;
addIndex()
Parameters
Param Type Description model
string Identifier for the model being used, e.g., “text-embedding-ada-002”. name
string Name of the index. datasource
string Unique identifier for the Datasource. indexType
string Type of index structure, e.g., “FLAT”, “HNSW”. dimensions
number Number of dimensions for the index. e.g.1536 filters
array An array of filters specifying fields for advanced searching.
Filters
Param Type Description field
string Name of the attribute you wish to filter by. type
string Type of the attribute (e.g., “string”, “number”).
const payload = {
model: "text-embedding-ada-002" ,
name: "my index" ,
datasource: "<datasource_id>" ,
indexType: "FLAT" ,
dimensions: 1536 ,
filters: [
{
field: "name" ,
type: "string"
} ,
{
field: "age" ,
type: "number"
}
]
} ;
const newIndex = await metal. addIndex ( payload) ;
getIndex()
Parameters
Param Type Description indexId
string Identifier for the index.
const index = await metal. getIndex ( "index-id" ) ;
index()
Add a single embedding to an index. When invoked, we will generate an embedding with one of the below embedding params and store it into a vector db.
You can only pass one of the following fields: text
, imageUrl
, or
embedding
. We only embed one field in a single request.
const textEmbedding = await metal. index ( { text: "Rocket" } ) ;
const imgEmbedding = await metal. index ( { imageUrl: "https://path-to.img" } ) ;
const rawEmbedding = await metal. index ( { embedding: [ 0.1 , 0.2 , 0.3 ] } ) ;
You can also pass an optional id
and metadata
object to be stored with the embedding. Eg.
const opts = {
id: "rocket1" ,
metadata: {
category: "space" ,
another: "field" ,
} ,
} ;
const embedding = await metal. index ( {
text: "Rocket" ,
... opts,
} ) ;
Parameters
Param Type Description Embed - embedding
number[] Raw embedding to be indexed. Embed - imageUrl
string A URL for an image to be embedded and indexed. Embed - text
string The text to be embedded and indexed. id
string Optional. Identifier for your embedding. metadata
object Optional. A flexible metdata object to be stored w/ the embedding.
indexMany()
Bulk add multiple embedding documents to an index. When invoked, we will generate an embedding with one of the below “Embed” params and store it in a vector index.
You can only pass one of the following fields: text
, imageUrl
, or
embedding
. We only embed one field in a single request.
Parameters
Param Type Description index
string Required. Index id. embedding
number[] Raw embeddings to be indexed. imageUrl
string A URL for an image to be vectorized and indexed. text
string The text to be vectorized and indexed. id
string Optional. identifier for your embedding. metadata
object Optional. A flexible metdata object to be stored w/ the embedding.
await metal. indexMany ( [
{ text: "Megadeth" , index: "index-id" } ,
{ text: "Metallica" , index: "index-id" } ,
] ) ;
search()
Parameters
Param Type Description embedding
number[] Raw embeddings to be searched. imageUrl
string A URL for an image to be vectorized and searched. text
string The text to be vectorized and searched. filters
Filter Filters included for filtered search. indexId
string Optional index id where record will get indexed. idsOnly
boolean Return only the ids of the documents. limit
number Number of documents returned by the API
Filter Object
Param Type Description and
FilterItem[] And clause, all members have to be satisfied. or
FilterItem[] Or clause, at least one member has to be satisfied.
Filter Item
Param Type Description field
string Name of the field to filter value
string | number Value to match the filter operator
string One of: eq
, gt
, gte
, lt
, lte
.
const results = await metal. search ( {
text: "term-to-search" ,
filters: { and: [ { field: "favoriteNumber" , value: 666 , operator: "lt" } ] } ,
indexId: "indexId" ,
idsOnly: false ,
limit: 100 ,
} ) ;
getOne()
Retrieve a single embedding document.
Parameters
Param Type Description id
string The ID of the document to retrieve. indexId
string Optional. index id where record will get indexed.
const document = await metal. getOne ( "documentId-123" ) ;
getMany()
Parameters
Name Type Description ids
Array of str An array of document IDs to retrieve. indexId
str, optional The ID of the index from which to retrieve documents. If not provided, the default index ID will be used.
const documentIDs = [ 'document_id_123' , 'document_id_456' ] ;
const result = await Metal. getMany ( documentIDs) ;
getQueries()
Parameters
Name Type Description indexId
str The ID of the index from which to retrieve documents.
const queries = await metal. getQueries ( "index-id" ) ;
uploadFile()
Only .csv
, .docx
and .pdf
are accepted.
Parameters
Param Type Description file
string | File File path (NodeJs) or File Object (Browser).
| indexId
| string | Optional index id where record will get indexed. |
const results = await metal. uploadFile ( "./path/to/file.csv" ) ;
tune()
Parameters
Param Type Description idA
string The ID of the first embedding.. idB
string The ID of the second embedding. label
number[-1, 0, 1] The “closeness score” of the two items. Either -1
, 0
or 1
indexId
string Optional index id where tuning pair will get recorded.
await metal. tune ( { idA, idB, label, indexId: "indexId" } ) ;
deleteOne()
Delete a single embedding document.
Parameters
Param Type Description id
string The ID of the document to delte. indexId
string Optional. The ID of the index containing the document.
const document = await metal. deleteOne ( "documentId-123" ) ;
deleteMany()
Deletes multiple documents in an index based on their IDs.
Parameters
Param Type Description id
string[] The IDs of the documents to delete. indexId
string Optional. The ID of the index containing the document.
const document = await metal. deleteOne ( "documentId-123" ) ;
Memory (Motorhead)
App Setup
import { Motorhead } from "@getmetal/metal-sdk" ;
const motorhead = new Motorhead ( { apiKey: "apiKey" , clientId: "clientId" } ) ;
const motorhead = new Motorhead ( {
baseUrl: "https://motorhead.yourdomain.com" ,
} ) ;
addMemory()
interface Memory {
messages: {
content: string ;
role: "AI" | "Human" ;
} ;
context: string ;
}
Param Type Description sessionId
string The ID of the session. If the session does not exist, it will create one memory
Memory[] A memory payload to update the session memory
const memoryPayload = {
messages: [
{ role: "Human" , content: "Who is the best vocalist of all time?" } ,
{ role: "AI" , content: "Ozzy!" } ,
] ,
context:
"User ask what can he eat in Colombia. The AI responds arepas are really nice" ,
} ;
await motorhead. addMemory ( "session-id" , memoryPayload) ;
getMemory()
Param Type Description sessionId
string The ID of the session to retrieve memory for
await motorhead. getMemory ( "session-id" ) ;
deleteMemory()
Param Type Description sessionId
string The ID of the session to delete memory for
await motorhead. deleteMemory ( "session-id" ) ;
Datasources
addDatasource()
Add a new Datasource to your Metal instance.
Parameters
Name Type Description name
string Name of the Datasource. sourcetype
string Type of the source. It can either be ‘File’ or ‘Text’. autoExtract
boolean Flag indicating whether auto-extraction is enabled. metadataFields
array An array of fields specifying which attributes you wish to extract. Each object should have name
, type
, and description
properties.
Name Type Description name
string Name of the attribute you wish to extract. type
string Type of the attribute (e.g., “String”, “Number”). description
string Brief description or example of the attribute. autoExtract
boolean Determines if attribute will be auto extracted from content or not.
const dataSourcePayload = {
name: "my datasource" ,
sourcetype: "File" ,
autoExtract: true ,
metadataFields: [
{
name: "band" ,
type: "String" ,
description: "Which heavy metal band is represented by the iconic mascot Eddie?" ,
autoExtract: true ,
}
]
} ;
const response = await metal. addDatasource ( datasourcePayload) ;
updateDatasource()
Parameters
Name Type Description datasourceId
string Identifier of the Datasource you want to update. name
string Updated name of the Datasource. sourcetype
string Updated type of the source. Either ‘File’ or ‘Text’. autoExtract
boolean Updated flag indicating whether auto-extraction is enabled. metadataFields
array Updated fields specifying which attributes you wish to extract.
const updatedDatasourcePayload = {
name: "updated_datasource" ,
sourcetype: "Text" ,
autoExtract: false ,
metadataFields: [
{
name: "song" ,
type: "String" ,
description: "Which was Iron Maiden's first single?"
}
]
} ;
const response = await Metal. updateDatasource ( "existing_dataSourceId" , updatedDataSourcePayload) ;
getDatasource()
Parameters
Name Type Description dataSourceId
string Identifier of the Datasource you want to retrieve information about.
const datasourceId = "existing_datasourceId" ;
const response = await Metal. getDatasource ( datasourceId) ;
getAllDatasources()
Parameters
Name Type Description limit
number (Optional) The maximum number of Datasources to return. Default is 10, with a maximum of 100. page
number (Optional) The page number for pagination. Should be a positive integer up to 100.
const limit = 10 ;
const page = 2 ;
const response = await Metal. getAllDatasources ( { limit, page } ) ;
deleteDatasource()
Parameters
Name Type Description datasourceId
string The ID of the Datasource you want to delete.
const datasourceId = 'your_data_source_id' ;
const response = await Metal. deleteDatasource ( datasourceId) ;
Data Entities
addDataEntity()
Parameters
Name Type Description datasourceId
string The ID of the datasource where the file belongs. filepath
string The local file path of the file to upload. metadata
object Additional Metadata that isn’t extracted.
Example
const datasourceId = 'your_datasource_id' ;
const filePath = './file_path.csv' ;
const results = await metal. addDataEntity ( {
datasource: datasourceId,
filepath,
metadata: {
band: 'Iron Maiden' ,
song: 'The Trooper' ,
} ,
} ) ;
getDataEntity()
Parameters
Name Type Description id
string The ID of the data entity you want to retrieve.
const dataEntityId = 'your_dataentity_id' ;
const dataEntity = await metal. getDataEntity ( dataEntityId) ;
getAllDataEntities()
Parameters
Name Type Description datasourceID
string The ID of the datasource for which you want to list the data entities. limit
number (Optional) The maximum number of data entities to return. Default is 10, with a maximum of 100. page
number (Optional) The page number for pagination. Should be a positive integer up to 100.
const datasourceID = 'your_datasource_id' ;
const page = 1 ;
const limit = 10 ;
const dataEntities = await Metal. listDataEntities ( datasourceID, page, limit) ;
deleteDataEntity()
Parameters
Name Type Description id
string The ID of the data entity you want to delete.
Example
const dataEntityID = 'your_dataentity_id' ;
const result = await Metal. deleteDataEntity ( dataEntityID) ;
Checkout the code on Github