Python SDK

Visit the GitHub Repo

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

Installation

pip3 install metal-sdk

Retrieval

App Setup

Param	Type	Description
`api_key`	string	The API Key for your Org. Learn more.
`client_id`	string	The Client ID for your Org. Learn more.
`index_id`	string	The ID of the index you want to connect with. Learn more.

from metal_sdk.metal import Metal

metal = Metal("api_key", "client_id", "index_id")

Adding an App

Param	Type	Description
`name`	string	Name of the App.
`indexes`	array	An array of the index connected to the app.

metal.add_app({"name": "My App", "indexes": ["index1"]})

Get One App

Param	Type	Description
`app_id`	string	ID of the App.

metal.get_app("app_id")

Get All Apps

metal.get_apps()

Updating an App

Param	Type	Description
`app_id`	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.

metal.update_app("app_id", {"name": "Updated Metal App", "indexes": ["index1"]})

Adding an Index

Payload

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”).

metal = Metal("api_key", "client_id")

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"
      }
    ]
}

metal.add_index(payload)

Get One Index

Param	Type	Description
`index_id`	string	The unique identifier of the index you want to retrieve.

metal.get_index("index_id")

Indexing a Document

Param	Type	Description
`payload`	dict	Dictionary with index parameters
`index_id`	string	Optional index id where record will get indexed.

Payload

Param	Type	Description
`id`	string	Optional identifier for your embedding.
`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.
`metadata`	object	A flexible metdata object to be stored w/ the embedding.

metal.index({ "text": "text-to-index" }, "index_id")

Multi(Bulk) Indexing

You can index up to 100 records in a single request.

Param	Type	Description
`payload`	BulkIndexItem[]	Array of bulk items

BulkIndexItem

Param	Type	Description
`id`	string	Optional identifier for your embedding.
`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.
`metadata`	object	A flexible metdata object to be stored w/ the embedding.

metal.index_many([{ "text": "blacksabbath", "index": "index-id" }, { "text": "ironmaiden", "index": "index-id" }])

Searching

self, payload: SearchPayload = {}, index_id=None, ids_only=False, limit=1

Param	Type	Description
`payload`	dict	search payload.
`index_id`	string	Id of index to search.
`ids_only`	boolean	Optional return only the ids
`limit`	number	Number of documents returned by the API (default=1).

Payload

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`	dict[]	List of filters to match in search.

Filter

Param	Type	Description
`and`	dict	And clause, all members have to be satisfied.
`or`	dict	Or clause, at least one member has to be satisfied.

Param	Type	Description
`value`	string \| number	Value to match.
`field`	string	Field to filter.
`operator`	string	Possible values: `eq`, `gt`, `gte`, `lt`, `lte`.

results = metal.search({ "text": "term-to-search", "filters": { "and": [{"field": "band", "value": "Black Sabbath", "operator":"eq"}]} }, index_id="indexID", limit=10)

Get One Document

Param	Type	Description
`id`	string	The ID of the document to retrieve.
`index_id`	string	Optional. Id of index to search.

document = metal.get_one("document_id_123")

Get Many Documents

Param	Type	Description
`ids`	list of str	A list of document IDs to retrieve.
`index_id`	str, optional	The ID of the index from which to retrieve documents. If not provided, the default index ID will be used.

document = metal.get_many("[document_id_123, document_id_456]")

Get Queries

Param	Type	Description
`index_id`	string	The ID of the Index to retrieve.

queries = metal.get_queries("index_id")

Delete One

Param	Type	Description
`embedding_id`	string	The ID of the document or embedding to delete.
`index_id`	string	The ID of the index containing the document.

metal.delete_one("embedding_id", "index_id")

Delete Many (Bulk)

Param	Type	Description
`embedding_ids`	list	A list of IDs for the documents or embeddings to delete.
`index_id`	string	The ID of the index containing the documents.

embedding_ids_to_delete = ["id1", "id2", "id3"]
metal.delete_many(embedding_ids_to_delete, "index_id")

Memory (Motorhead)

App Setup

Param	Type	Description
`api_key`	string	For Managed. The API Key for your Org. [details](- Create an API Key for Authentication.
`client_id`	string	For Managed.The Client ID for your Org. [details](- Create an API Key for Authentication.
`base_url`	string	For Self-hosted. The URL path to your motorhead instance

from metal_sdk.motorhead import Motorhead

# Managed
motorhead = Motorhead({ "api_key": "api_key", "client_id": "client-id" })

# Self-hosted
motorhead = Motorhead({ "base_url": "https://motorhead.yourdomain.com" })

Create Memory

class Message:
    content: str
    role: str  # "AI" or "Human"

class Memory:
    messages: list  # List of Message instances
    context: str

Param	Type	Description
`session_id`	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

memory_payload = {
  "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",
}


motorhead.add_memory("session-id", memory_payload)

Get Memory

Param	Type	Description
`session_id`	string	The ID of the session to retrieve memory for

motorhead.get_memory("session-id")

Delete Memory

Param	Type	Description
`session_id`	string	The ID of the session to delete memory for

motorhead.delete_memory("session-id")

Datasources

Add a Datasource

Param	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.

Metadata Fields

Param	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.

from metal_sdk.metal import Metal

payload = {
    "name": "my datasource",
    "sourcetype": "File",
    "autoExtract": True,
    "metadataFields": [
      {
        "name": "band",
        "type": "string",
        "description": "Which heavy metal band is represented by the iconic mascot Eddie?"
      }
    ]
}

metal.add_datasource(payload)

Update Datasource

Parameters

Param	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.

Example

payload = {
    "name": "updated_datasource",
    "sourcetype": "Text",
    "autoExtract": False,
    "metadataFields": [
        {
            "name": "song",
            "type": "string",
            "description": "Which was Iron Maiden's first single?"
        }
    ]
}

metal.update_datasource("existing_datasourceId", payload)

Get Datasource

Parameters

Param	Type	Description
`dataSourceId`	string	Identifier of the Datasource you want to retrieve information about.

Example

metal.get_datasource("existing_datasourceId")
print(response)  # This will display detailed information about the Datasource

List Datasources

Parameters

Param	Type	Description
`limit`	int	(Optional) The maximum number of Datasources to return. Default is 10 and a maximum of 100.
`page`	int	(Optional) The page number for pagination. Should be a positive integer up to 100.

metal.get_all_datasources(page=1, limit=10)

Delete Datasource

Parameters

Param	Type	Description
`datasource_id`	string	The ID of the Datasource you want to delete.

Example

response = metal.delete_datasource("datasourceID")
print(response)  # Expected: "Datasource successfully deleted."

Data Entities

Add a Data entity

.pdf, doc, .docx, .xlsx, and .csv are accepted.

Parameters

Name	Type	Description
`datasourceId`	string	The ID of the datasource where the file belongs.
`file_path`	string	The local file path of the file to upload.
`metadata`	object	Additional Metadata that isn’t extracted.

Example

results = metal.add_data_entity("datasource_id", "./file_path.csv", metadata=metadata)

Get Data Entity

Parameters

Param	Type	Description
`id`	string	The ID of the data entity you want to retrieve.

metal.get_data_entity("data_entity_id")

List Data Entities

Parameters

Param	Type	Description
`datasourceID`	string	The ID of the datasource for which you want to list the data entities.
`limit`	int	(Optional) The maximum number of data entities to return. Default is 10 and a maximum of 100.
`page`	int	(Optional) The page number for pagination. Should be a positive integer up to 100.

metal.get_all_data_entities("datasource_id", page=1, limit=10)

Delete Data Entity

Parameters

Param	Type	Description
`id`	string	The ID of the data entity you want to delete.

metal.delete_data_entity("data_entity_id")

Python SDK

​Installation

​Retrieval

​App Setup

​Adding an App

​Get One App

​Get All Apps

​Updating an App

​Adding an Index

​Payload

​Filters

​Get One Index

​Indexing a Document

​Payload

​Multi(Bulk) Indexing

​BulkIndexItem

​Searching

​Payload

​Filter

​Filter Item

​Get One Document

​Get Many Documents

​Get Queries

​Delete One

​Delete Many (Bulk)

​Memory (Motorhead)

​App Setup

​Create Memory

​Get Memory

​Delete Memory

​Datasources

​Add a Datasource

​Metadata Fields

​Update Datasource

​Parameters

​Example

​Get Datasource

​Parameters

​Example

​List Datasources

​Parameters

​Delete Datasource

​Parameters

​Example

​Data Entities

​Add a Data entity

​Parameters

​Example

​Get Data Entity

​Parameters

​List Data Entities

​Parameters

​Delete Data Entity

​Parameters

Installation

Retrieval

App Setup

Adding an App

Get One App

Get All Apps

Updating an App

Adding an Index

Payload

Filters

Get One Index

Indexing a Document

Payload

Multi(Bulk) Indexing

BulkIndexItem

Searching

Payload

Filter

Filter Item

Get One Document

Get Many Documents

Get Queries

Delete One

Delete Many (Bulk)

Memory (Motorhead)

App Setup

Create Memory

Get Memory

Delete Memory

Datasources

Add a Datasource

Metadata Fields

Update Datasource

Parameters

Example

Get Datasource

Parameters

Example

List Datasources

Parameters

Delete Datasource

Parameters

Example

Data Entities

Add a Data entity

Parameters

Example

Get Data Entity

Parameters

List Data Entities

Parameters

Delete Data Entity

Parameters