- Docs
- Guides
- Build with Enigma
- Python SDK
Python SDK reference
Environment variables, logging, what the SDK sends off your machine, and the rules for GraphQL you write by hand.
Environment variables
Section titled “Environment variables”| 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. |
Logging
Section titled “Logging”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.
What leaves your machine
Section titled “What leaves your machine”- 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, whichClientConfig.urldoesn’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.
Write GraphQL by hand
Section titled “Write GraphQL by hand”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.
Common mistakes
Section titled “Common mistakes”| 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. searchreturns a list. Select through inline fragments, as insearch(...) { ... on Brand { ... } }; it has noedges.- A category in
namematches business names.name: "coffee shop"returns businesses with names like “Coffee Shop”. To count a category, useaggregate. - A company’s officers are under its registrations.
LegalEntity.personsis almost always empty for a company. FollowregisteredEntities, thenregistrations, thenroles, thenlegalEntities. - Connections have no
totalCount. Count with anaggregatequery, or withcount(field: ...)on an entity. - Website content sits under each website. Select
websiteContentsinsidewebsites:websites(first: 1) { edges { node { websiteContents(first: 1) { edges { node { httpStatusCode } } } } } }. - A brand search for a local franchise returns the whole chain. Searching
BRANDfor a single franchised hotel returns the parent brand with all its locations. SearchOPERATING_LOCATIONwith an address to find one location.
Rules the API enforces at execution
Section titled “Rules the API enforces at execution”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 |