Skip to content
Console(opens in a new tab)

Python SDK quickstart

Install the Enigma Python SDK, ask a question in plain English, and send your first GraphQL query.

The Enigma Python SDK, enigma-api-client, sends GraphQL queries to the Enigma GraphQL API and turns questions in plain English into those queries. These pages document the whole SDK.

  • An Enigma API key. Find yours in the Enigma Console under Settings > Account > API keys.
  • Python 3.11 or later.
  • To generate queries on your own machine with a local strategy (see Choose a strategy): an Anthropic or OpenRouter API key, or AWS credentials with access to Claude on Amazon Bedrock.

The examples read your Enigma API key from the ENIGMA_API_KEY environment variable:

Terminal window
export ENIGMA_API_KEY="your-api-key"
Terminal window
pip install enigma-api-client

Optional extras add dependencies for specific features:

Extra Installs Needed for
enigma-api-client[bedrock] botocore BedrockProvider, Claude on Amazon Bedrock as the large language model (LLM) of TemplateStrategy or GenerativeStrategy
enigma-api-client[anthropic] claude_agent_sdk AgentStrategy
enigma-api-client[all] botocore and claude_agent_sdk BedrockProvider and AgentStrategy

AnthropicProvider and OpenRouterProvider need no extra. The anthropic extra installs the Claude Agent SDK, which only AgentStrategy uses.

import asyncio
import os
from enigma_api_client import Client, ClientConfig
async def main():
config = ClientConfig(enigma_api_key=os.environ["ENIGMA_API_KEY"])
async with Client(config) as client:
response = await client.search(prompt="Tell me about Chipotle")
if not response.is_success():
raise RuntimeError(f"HTTP {response.status_code}: {response.errors}")
brand = response.data["search"][0]
print(brand["names"]["edges"][0]["node"]["name"]) # CHIPOTLE MEXICAN GRILL
print(brand["__url"]) # the brand's profile in the Enigma Console
asyncio.run(main())

The SDK turns the question into a GraphQL query, runs it, and returns the result. By default, Enigma’s hosted query service writes the query, so your Enigma API key is all you need. For the kinds of questions you can ask, see Generate queries from questions.

import asyncio
import os
from enigma_api_client import Client, ClientConfig
QUERY = """
query Brand($name: String!) {
search(searchInput: { name: $name, entityType: BRAND, conditions: { limit: 1 } }) {
... on Brand {
names(first: 1) { edges { node { name } } }
websites(first: 1) { edges { node { website } } }
}
}
}
"""
async def main():
config = ClientConfig(enigma_api_key=os.environ["ENIGMA_API_KEY"])
async with Client(config) as client:
response = await client.search(query=QUERY, variables={"name": "Chipotle"})
if not response.is_success():
raise RuntimeError(f"HTTP {response.status_code}: {response.errors}")
brand = response.data["search"][0]
print(brand["names"]["edges"][0]["node"]["name"]) # CHIPOTLE MEXICAN GRILL
print(brand["websites"]["edges"][0]["node"]["website"]) # https://www.chipotle.com
asyncio.run(main())

A name can match many entities, so conditions: { limit: 1 } keeps only the first. The GraphQL guide and the schema reference describe the queries you can write, and Write GraphQL by hand lists the mistakes to avoid.

Some snippets on the other pages of this guide show only what changes: usually a new config = ... line, sometimes with the imports and strategy it needs. To run one of them, start from one of the preceding programs and put the snippet’s lines in place of the program’s config = ... line. If the snippet has no config = ... line, put its lines just before the program’s config = ... line instead, and pass any strategy it builds, such as TemplateStrategy(...), to ClientConfig as query_strategy=.