{"id":9107,"library":"metaphor-python","title":"Metaphor Python API Client","description":"Metaphor-python is a Python client library for interacting with the Metaphor API, a search engine optimized for Large Language Models (LLMs). It enables neural search and content retrieval, providing clean HTML content from search results. The library is currently at version 0.1.23 and is under active development, indicated by its 'Alpha' status on PyPI. While no explicit release cadence is documented, updates are released as new features and improvements to the Metaphor API are made available.","status":"active","version":"0.1.23","language":"en","source_language":"en","source_url":"https://github.com/metaphorsystems/metaphor-python","tags":["AI","LLM","search","API client","natural language processing","information retrieval"],"install":[{"cmd":"pip install metaphor-python","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"Metaphor","correct":"from metaphor_python import Metaphor"}],"quickstart":{"code":"import os\nfrom metaphor_python import Metaphor\n\n# Ensure your Metaphor API key is set as an environment variable\n# e.g., export METAPHOR_API_KEY=\"your_metaphor_api_key_here\"\napi_key = os.environ.get('METAPHOR_API_KEY')\n\nif not api_key:\n    print(\"Error: METAPHOR_API_KEY environment variable not set.\")\nelse:\n    try:\n        metaphor = Metaphor(api_key=api_key)\n        # Perform a search\n        results = metaphor.search(\"latest developments in AI agents\", num_results=3, use_autoprompt=True)\n\n        if results.contents:\n            print(\"Search Results:\")\n            for i, item in enumerate(results.contents):\n                print(f\"---\\nResult {i+1}:\\nTitle: {item.title}\\nURL: {item.url}\\nExtract: {item.extract[:200]}...\")\n        else:\n            print(\"No search results found.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")","lang":"python","description":"Initializes the Metaphor client using an API key from an environment variable and performs a basic search query, printing the title, URL, and a snippet of the content for the top results."},"warnings":[{"fix":"Ensure the 'METAPHOR_API_KEY' environment variable is correctly set with your valid API key before initializing the Metaphor client. Alternatively, pass the key directly to the `Metaphor()` constructor: `metaphor = Metaphor(api_key='your_key')`.","message":"The Metaphor API key is crucial for authentication. Failing to provide a valid key will result in authentication errors when making API calls.","severity":"gotcha","affected_versions":"0.1.x"},{"fix":"Monitor the official GitHub repository for changes and consult release notes (if available) when upgrading to new versions. Pin the version of `metaphor-python` in your `requirements.txt` to avoid unexpected breakage.","message":"The library is in an 'Alpha' development status (0.1.x), meaning its API might evolve rapidly, and breaking changes could occur in minor or patch releases without strict adherence to semantic versioning until a 1.0 release.","severity":"gotcha","affected_versions":"0.1.x"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify that your `METAPHOR_API_KEY` environment variable holds the correct and active API key obtained from the Metaphor website. Re-initialize the `Metaphor` client after updating the key.","cause":"The Metaphor API key provided is either missing, incorrect, or expired.","error":"metaphor_python.api.ApiException: (401)\nReason: Unauthorized\nHTTP response body: b'{\"detail\":\"Invalid API key\"}'"},{"fix":"Consult the official Metaphor API documentation and the `metaphor-python` library's source or examples to ensure you are using the correct method names and arguments. The main methods are `search()`, `find_similar()`, and `get_contents()` (from the search results).","cause":"Attempting to call a method or access an attribute that does not exist on the `Metaphor` client object or its response objects. This could be due to a typo or misunderstanding the available API methods.","error":"AttributeError: 'Metaphor' object has no attribute 'some_non_existent_method'"}]}