metal-sdk

library2.5.1pypypi✓ verified 85d ago

metal-sdk is the official Python SDK for getmetal.io, a managed service for ML Embeddings and an AI-first datastore & retrieval engine. It allows developers to easily integrate Metal's capabilities, such as semantic search and building AI-powered applications, into their Python projects. The current version is 2.5.1, released on November 10, 2023, with the broader Metal platform actively maintained and updated.

vector-search ai-ml llm-agents

pip install metal-sdk

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · METAL-SDK

metal-sdk

vector-searchpythonv2.5.1

Install

2.1s avg

Import

217ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.5.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.222s · 22MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.1s · import 0.212s · 23MB

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Metal

✓ from metal_sdk.metal import Metal

✗ import metal_sdk.Metal

The primary class for interacting with the Metal API is 'Metal', located within the 'metal' submodule of 'metal_sdk'.

Initializes the Metal client using API credentials and demonstrates how to index a simple text document and perform a basic search. It's crucial to replace placeholder credentials or set them as environment variables.

import os from metal_sdk.metal import Metal # It's recommended to load credentials from environment variables api_key = os.environ.get('METAL_API_KEY', 'your_api_key_here') client_id = os.environ.get('METAL_CLIENT_ID', 'your_client_id_here') index_id = os.environ.get('METAL_INDEX_ID', 'your_index_id_here') if not all([api_key, client_id, index_id]): print("Warning: API_KEY, CLIENT_ID, or INDEX_ID are missing. Please set environment variables or replace placeholders.") exit(1) metal = Metal(api_key, client_id, index_id) try: # Example: Indexing a document response = metal.index({"text": "The quick brown fox jumps over the lazy dog."}) print(f"Document indexed successfully. ID: {response['data']['id']}") # Example: Searching for documents search_results = metal.search(text="quick fox", limit=1) if search_results and search_results['data']: print(f"Search result: {search_results['data'][0]['text']}") else: print("No search results found.") except Exception as e: print(f"An error occurred: {e}")

metal --version

Debug

Known issues

gotchaIncorrect API Key, Client ID, or Index ID will lead to authentication failures (HTTP 401 Unauthorized) or resource not found errors. These credentials must be generated from the Metal application dashboard.

fix

Ensure `METAL_API_KEY`, `METAL_CLIENT_ID`, and `METAL_INDEX_ID` environment variables are correctly set, or that the values passed during `Metal` initialization are accurate and valid. Verify permissions for the provided API key.

affects: All

gotchaConfusing `metal-sdk` (for getmetal.io) with other Python libraries also named 'Metal' (e.g., PyObjC's Metal framework for Apple GPUs, or metal-stack's Python API client) can lead to `ModuleNotFoundError` or `AttributeError`.

fix

Always ensure you are importing `from metal_sdk.metal import Metal` and that `pip install metal-sdk` was used. Consult documentation specific to getmetal.io when troubleshooting.

affects: All

gotchaThe Metal API has rate limits and pagination for certain endpoints. Exceeding rate limits (HTTP 429) or not handling pagination for large result sets will impact application performance and data retrieval.

fix

Implement retry logic with exponential backoff for rate limit errors. For endpoints like `/v1/indexes/:id/documents`, utilize the `page` and `limit` query parameters, or `lastObjectIdSeen` for deep pagination, as described in the Metal API documentation.

affects: All

Errors

Common errors & fixes

metal_sdk.exceptions.UnauthorizedException: (401) Reason: Unauthorized

The provided API Key or Client ID is incorrect, expired, or lacks the necessary permissions to access the Metal API.

fix

Double-check your `METAL_API_KEY` and `METAL_CLIENT_ID`. Regenerate them in the Metal dashboard if unsure, and ensure they are correctly set as environment variables or passed to the `Metal` constructor.

metal_sdk.exceptions.NotFoundException: (404) Reason: Not Found

The specified `index_id` does not exist or the provided credentials do not have access to it.

fix

Verify that the `METAL_INDEX_ID` is correct and corresponds to an existing index in your Metal account. Ensure the API key has permissions to interact with that specific index.

TypeError: 'dict' object is not callable

Attempting to call a dictionary-like response object as a function, often after an API call, or providing incorrect data format to indexing methods.

fix

Ensure you are accessing attributes/keys of the API response correctly (e.g., `response['data']` instead of `response()`). When indexing, verify that the input dictionary for methods like `index()` matches the expected schema, typically `{'text': 'your_text_here'}` for simple cases.

Upgrade

Version history

2.5.1latest on PyPI · released Nov 10, 2023

Audit

Dependencies

langchain-communityoptionalRequired for integrations with LangChain, such as `MetalRetriever`.

Agent activity

41 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/getmetal/metal-python ↗

packagehttps://pypi.org/project/metal-sdk/ ↗

homepagehttps://getmetal.io ↗