Metal Python SDK

Common errors

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

  cause 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

  cause 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

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

Warnings

• gotcha Incorrect 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.
• gotcha Confusing `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.
• gotcha The 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.

Install

• pip install metal-sdk Install stable version

Imports

• Metal
  wrong:

  import metal_sdk.Metal

  correct:

  from metal_sdk.metal import Metal

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

Quickstart

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