Node SDK

Visit the GitHub Repo

You’ll need to Create an API Key to Authentication with Metal.

Installation

npm install @getmetal/metal-sdk
# or
yarn add @getmetal/metal-sdk

Retrieval

You’ll need to Create an API Key to Authenticate with Metal.

App Setup

ParamTypeDescription
apiKeystringThe API Key for your Org. Learn more.
clientIdstringThe Client ID for your Org. Learn more.
indexIdstringThe 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

ParamTypeDescription
namestringName of the app.
const app = await metal.addApp({
    name: "My App",
    indexes: ["index-id"]
});

getApp()

Parameters

ParamTypeDescription
appIdstringIdentifier for the app.
const app = await metal.getApp("app-id");

getApps()

const apps = await metal.getApps();

updateApp()

Parameters

ParamTypeDescription
appIdstringThe unique identifier of the app you want to update.
namestring (optional)The updated name for the App.
indexesarray (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

ParamTypeDescription
modelstringIdentifier for the model being used, e.g., “text-embedding-ada-002”.
namestringName of the index.
datasourcestringUnique identifier for the Datasource.
indexTypestringType of index structure, e.g., “FLAT”, “HNSW”.
dimensionsnumberNumber of dimensions for the index. e.g.1536
filtersarrayAn array of filters specifying fields for advanced searching.

Filters

ParamTypeDescription
fieldstringName of the attribute you wish to filter by.
typestringType 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

ParamTypeDescription
indexIdstringIdentifier 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" });
// or
const imgEmbedding = await metal.index({ imageUrl: "https://path-to.img" });
// or
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

ParamTypeDescription
Embed - embeddingnumber[]Raw embedding to be indexed.
Embed - imageUrlstringA URL for an image to be embedded and indexed.
Embed - textstringThe text to be embedded and indexed.
idstringOptional. Identifier for your embedding.
metadataobjectOptional. 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

ParamTypeDescription
indexstringRequired. Index id.
embeddingnumber[]Raw embeddings to be indexed.
imageUrlstringA URL for an image to be vectorized and indexed.
textstringThe text to be vectorized and indexed.
idstringOptional. identifier for your embedding.
metadataobjectOptional. A flexible metdata object to be stored w/ the embedding.
await metal.indexMany([
  { text: "Megadeth", index: "index-id" },
  { text: "Metallica", index: "index-id" },
]);

Parameters

ParamTypeDescription
embeddingnumber[]Raw embeddings to be searched.
imageUrlstringA URL for an image to be vectorized and searched.
textstringThe text to be vectorized and searched.
filtersFilterFilters included for filtered search.
indexIdstringOptional index id where record will get indexed.
idsOnlybooleanReturn only the ids of the documents.
limitnumberNumber of documents returned by the API

Filter Object

ParamTypeDescription
andFilterItem[]And clause, all members have to be satisfied.
orFilterItem[]Or clause, at least one member has to be satisfied.

Filter Item

ParamTypeDescription
fieldstringName of the field to filter
valuestring | numberValue to match the filter
operatorstringOne 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

ParamTypeDescription
idstringThe ID of the document to retrieve.
indexIdstringOptional. index id where record will get indexed.
const document = await metal.getOne("documentId-123");

getMany()

Parameters

NameTypeDescription
idsArray of strAn array of document IDs to retrieve.
indexIdstr, optionalThe 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

NameTypeDescription
indexIdstrThe ID of the index from which to retrieve documents.
const queries = await metal.getQueries("index-id");

deleteOne()

Delete a single embedding document.

Parameters

ParamTypeDescription
idstringThe ID of the document to delte.
indexIdstringOptional. 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

ParamTypeDescription
idstring[]The IDs of the documents to delete.
indexIdstringOptional. The ID of the index containing the document.
const document = await metal.deleteOne("documentId-123");

Memory (Motorhead)

App Setup

ParamTypeDescription
apiKeystringFor Managed. The API Key for your Org. [details](- Create an API Key for Authentication.
clientIdstringFor Managed.The Client ID for your Org. [details](- Create an API Key for Authentication.
baseUrlstringFor Self-hosted. The URL path to your motorhead instance
import { Motorhead } from "@getmetal/metal-sdk";

// Managed
const motorhead = new Motorhead({ apiKey: "apiKey", clientId: "clientId" });

// Self-hosted
const motorhead = new Motorhead({
  baseUrl: "https://motorhead.yourdomain.com",
});

addMemory()

interface Memory {
  messages: {
    content: string;
    role: "AI" | "Human";
  };
  context: string;
}
ParamTypeDescription
sessionIdstringThe ID of the session. If the session does not exist, it will create one
memoryMemory[]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()

ParamTypeDescription
sessionIdstringThe ID of the session to retrieve memory for
await motorhead.getMemory("session-id");

deleteMemory()

ParamTypeDescription
sessionIdstringThe ID of the session to delete memory for
await motorhead.deleteMemory("session-id");

Datasources

addDatasource()

Add a new Datasource to your Metal instance.

Parameters

NameTypeDescription
namestringName of the Datasource.
sourcetypestringType of the source. It can either be ‘File’ or ‘Text’.
autoExtractbooleanFlag indicating whether auto-extraction is enabled.
metadataFieldsarrayAn array of fields specifying which attributes you wish to extract. Each object should have name, type, and description properties.

Metadata Fields

NameTypeDescription
namestringName of the attribute you wish to extract.
typestringType of the attribute (e.g., “String”, “Number”).
descriptionstringBrief description or example of the attribute.
autoExtractbooleanDetermines 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

NameTypeDescription
datasourceIdstringIdentifier of the Datasource you want to update.
namestringUpdated name of the Datasource.
sourcetypestringUpdated type of the source. Either ‘File’ or ‘Text’.
autoExtractbooleanUpdated flag indicating whether auto-extraction is enabled.
metadataFieldsarrayUpdated 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

NameTypeDescription
dataSourceIdstringIdentifier of the Datasource you want to retrieve information about.
const datasourceId = "existing_datasourceId";
const response = await Metal.getDatasource(datasourceId);

getAllDatasources()

Parameters

NameTypeDescription
limitnumber(Optional) The maximum number of Datasources to return. Default is 10, with a maximum of 100.
pagenumber(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

NameTypeDescription
datasourceIdstringThe ID of the Datasource you want to delete.
const datasourceId = 'your_data_source_id';
const response = await Metal.deleteDatasource(datasourceId);

Data Entities

addDataEntity()

Parameters

NameTypeDescription
datasourceIdstringThe ID of the datasource where the file belongs.
filepathstringThe local file path of the file to upload.
metadataobjectAdditional 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

NameTypeDescription
idstringThe ID of the data entity you want to retrieve.

const dataEntityId = 'your_dataentity_id';

const dataEntity = await metal.getDataEntity(dataEntityId);

getAllDataEntities()

Parameters

NameTypeDescription
datasourceIDstringThe ID of the datasource for which you want to list the data entities.
limitnumber(Optional) The maximum number of data entities to return. Default is 10, with a maximum of 100.
pagenumber(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

NameTypeDescription
idstringThe 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