Skip to content
Console(opens in a new tab)

Python SDK reference

Environment variables, logging, what the SDK sends off your machine, and the rules for GraphQL you write by hand.

Variable Used by Meaning
ENIGMA_API_KEY ServiceStrategy The key of a ServiceStrategy you create without enigma_api_key= (the default strategy uses the ClientConfig key)
ANTHROPIC_API_KEY AnthropicProvider Anthropic API key
OPENROUTER_API_KEY OpenRouterProvider OpenRouter API key
AWS_REGION, AWS_DEFAULT_REGION BedrockProvider, AgentStrategy Region when region= is not passed: AWS_REGION, else AWS_DEFAULT_REGION, else us-east-1
ENIGMA_SHAPE_CACHE_ENABLED TemplateStrategy, GenerativeStrategy 0, false, no, or off turns off the query shape cache. Read when the strategy is created.
ENIGMA_ADDRESS_SEARCH TemplateStrategy, GenerativeStrategy, AgentStrategy on, off, or auto (see Turn address lookups on or off). 1, true, and yes also mean on; 0, false, and no mean off. Read when the strategy is created.
ENIGMA_ARCHIVE_SEARCH TemplateStrategy, GenerativeStrategy, AgentStrategy off, 0, false, or no leaves the archive searches out of record queries (see Get government records). Read on each call.

The SDK logs through Python’s logging module, on loggers named enigma_api_client.*:

  • Lines at INFO and above are fixed messages with counts, statuses, names of the query rules the SDK checks, exception class names, schema field names, and file paths. They never contain your questions or the LLM’s text.
  • DEBUG lines can contain your questions, the LLM’s output, and AgentStrategy’s transcript. Don’t turn on DEBUG for these loggers where your logs must not hold that data.
  • Searches: the query and its variables go to the Enigma API with your Enigma API key.
  • ServiceStrategy: your question goes to Enigma’s hosted query service with your Enigma API key. The service writes the query with an LLM. It has its own URL, which ClientConfig.url doesn’t change.
  • Local strategies: your question and Enigma’s query instructions go to the LLM provider you configure (Amazon Bedrock for AgentStrategy). When the SDK asks the LLM to repair a query, it also sends the draft query and its errors. Search results never go to the LLM.
  • Schema checks: the SDK fetches the API schema from the Enigma API with the first Client’s key, or with the keys used by the introspector you register (see Schema checks and several tiers).

The SDK sends nothing else.

The Enigma schema has hundreds of fields, several of them named differently from what you might guess. A query can also pass schema validation and still be rejected when it runs. This section lists what most often goes wrong.

Field you might guess Actual field
status (of a location) operatingStatus
url website
description industryDesc
title jobTitle
averageRating reviewScoreAvg
  • A field that doesn’t exist fails the whole request with HTTP 400 and Cannot query field.
  • search returns a list. Select through inline fragments, as in search(...) { ... on Brand { ... } }; it has no edges.
  • A category in name matches business names. name: "coffee shop" returns businesses with names like “Coffee Shop”. To count a category, use aggregate.
  • A company’s officers are under its registrations. LegalEntity.persons is almost always empty for a company. Follow registeredEntities, then registrations, then roles, then legalEntities.
  • Connections have no totalCount. Count with an aggregate query, or with count(field: ...) on an entity.
  • Website content sits under each website. Select websiteContents inside websites: websites(first: 1) { edges { node { websiteContents(first: 1) { edges { node { httpStatusCode } } } } } }.
  • A brand search for a local franchise returns the whole chain. Searching BRAND for a single franchised hotel returns the parent brand with all its locations. Search OPERATING_LOCATION with an address to find one location.

These queries pass schema validation and are rejected when they run. GenerativeStrategy and AgentStrategy check these rules before they return a query, and the templates follow them.

Rule Error
search needs name, website, person, phoneNumber, id, or tin, even when it has a filter. An address alone works only in an entityType: ADDRESS search with address.street1 (a street line with a house number) or address.id. Search must include name, website, person, or phone_number
searchInput.prompt can’t be combined with a selection set. To have the API answer a question in plain English, send the question in searchInput.prompt with no selection set (see Prompt search). 'prompt' cannot be combined with a selection set
roles takes first and conditions only, although the schema lists last, after, and before. Fetch roles as one page. LegalEntity.roles does not currently support last, after or before (the error names the parent type)
A PERSON search finds people by person: { firstName, lastName }, id, or tin, not by name. Person search must include an identifier or first, middle or last name
A filter’s AND, OR, and NOT take a list of clauses, and NOT takes exactly one. Rejected
A filter clause has exactly one operator. Combine several clauses in one AND list. Rejected
IS_NULL and IS_NOT_NULL test a column. To test for related records on a connection path such as registrations, use HAS or NOT: [{ HAS: [...] }]. Rejected
An aggregate filter on brands.industries.industryCode needs { EQ: ["brands.industries.industryType", "naics_2022_code"] } in the same AND. Joins aren't allowed for filter