{"id":9106,"library":"metal-sdk","title":"Metal Python SDK","description":"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.","status":"active","version":"2.5.1","language":"en","source_language":"en","source_url":"https://github.com/getmetal/Metal","tags":["AI","ML","embeddings","vector database","semantic search","retrieval augmented generation","RAG"],"install":[{"cmd":"pip install metal-sdk","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for integrations with LangChain, such as `MetalRetriever`.","package":"langchain-community","optional":true}],"imports":[{"note":"The primary class for interacting with the Metal API is 'Metal', located within the 'metal' submodule of 'metal_sdk'.","wrong":"import metal_sdk.Metal","symbol":"Metal","correct":"from metal_sdk.metal import Metal"}],"quickstart":{"code":"import os\nfrom metal_sdk.metal import Metal\n\n# It's recommended to load credentials from environment variables\napi_key = os.environ.get('METAL_API_KEY', 'your_api_key_here')\nclient_id = os.environ.get('METAL_CLIENT_ID', 'your_client_id_here')\nindex_id = os.environ.get('METAL_INDEX_ID', 'your_index_id_here')\n\nif not all([api_key, client_id, index_id]):\n    print(\"Warning: API_KEY, CLIENT_ID, or INDEX_ID are missing. Please set environment variables or replace placeholders.\")\n    exit(1)\n\nmetal = Metal(api_key, client_id, index_id)\n\ntry:\n    # Example: Indexing a document\n    response = metal.index({\"text\": \"The quick brown fox jumps over the lazy dog.\"})\n    print(f\"Document indexed successfully. ID: {response['data']['id']}\")\n\n    # Example: Searching for documents\n    search_results = metal.search(text=\"quick fox\", limit=1)\n    if search_results and search_results['data']:\n        print(f\"Search result: {search_results['data'][0]['text']}\")\n    else:\n        print(\"No search results found.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The provided API Key or Client ID is incorrect, expired, or lacks the necessary permissions to access the Metal API.","error":"metal_sdk.exceptions.UnauthorizedException: (401) Reason: Unauthorized"},{"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.","cause":"The specified `index_id` does not exist or the provided credentials do not have access to it.","error":"metal_sdk.exceptions.NotFoundException: (404) Reason: Not Found"},{"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.","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.","error":"TypeError: 'dict' object is not callable"}]}