Enigma API Client

Python SDK for the Enigma GraphQL business intelligence API. Query Enigma's database of 250M+ businesses using raw GraphQL or natural language prompts.

Installation

Requires Python 3.11 or later.

# Core client: raw GraphQL plus every prompt strategy except AgentStrategy
pip install enigma-api-client

# AgentStrategy (Claude Agent SDK on Amazon Bedrock)
pip install "enigma-api-client[anthropic]"

# BedrockProvider (Claude on Amazon Bedrock)
pip install "enigma-api-client[bedrock]"

# Both of the above
pip install "enigma-api-client[all]"

Quick Start

The client supports both raw GraphQL queries and natural language queries.

• The example below sends a raw GraphQL query.
• Later examples show the natural language strategies.

Using GraphQL Queries

import asyncio
from enigma_api_client import Client, ClientConfig

async def main():
    config = ClientConfig(enigma_api_key="your-api-key")
    async with Client(config) as client:
        # Send a handwritten GraphQL query
        response = await client.search(
            query="""query {
              search(searchInput: { name: "Starbucks", entityType: BRAND }) {
                ... on Brand {
                  id
                  names(first: 1) { edges { node { name } } }
                }
              }
            }"""
        )
        print(response.data)

asyncio.run(main())

Connection lifecycle. A Client holds reusable keep-alive connections for the GraphQL endpoint and the query strategy. Reuse one client across requests and release it when done: use it as an async context manager (async with Client(config) as client:, shown above) or call await client.aclose().

Natural Language Query strategies

The client supports four strategies for turning natural language prompts into GraphQL queries. By default it uses ServiceStrategy, which sends the prompt to Enigma's hosted query generation service and authenticates with your Enigma API key, so client.search(prompt="...") works with no extra setup. To generate queries locally instead, pass a TemplateStrategy, GenerativeStrategy, or AgentStrategy via ClientConfig.query_strategy.

TemplateStrategy and GenerativeStrategy call Anthropic by default (the ANTHROPIC_API_KEY environment variable, or anthropic_api_key=); pass llm_provider= to use OpenRouter or Amazon Bedrock instead (see LLM providers below). AgentStrategy runs on Amazon Bedrock with AWS credentials and requires the claude_agent_sdk package (pip install "enigma-api-client[anthropic]"). ServiceStrategy runs generation server side and needs no LLM key.

Service Strategy (default)

Sends your prompt to Enigma's hosted query generation service over HTTPS, and query generation runs server side. It uses the template strategy by default. To choose another, construct one with your key, because a ServiceStrategy you create does not inherit the Client's key (without enigma_api_key= it reads ENIGMA_API_KEY): query_strategy=ServiceStrategy(query_strategy="generative", enigma_api_key="your-api-key"), imported from enigma_api_client.strategies.

import asyncio
from enigma_api_client import Client, ClientConfig

async def main():
    # ServiceStrategy is used when no query_strategy is configured
    async with Client(ClientConfig(enigma_api_key="your-api-key")) as client:
        # Brand lookup
        response = await client.search(prompt="Tell me about Chipotle")
        print(response.data)

        # Location search
        response = await client.search(prompt="Find Starbucks locations in California")
        print(response.data)

        # Person search
        response = await client.search(prompt="Find companies owned by Elon Musk")
        print(response.data)

        # KYB verification
        response = await client.search(prompt="Verify legal entity for Enigma Technologies in NY")
        print(response.data)

asyncio.run(main())

TemplateStrategy: LLM classified, template built

Uses an LLM to classify the prompt into one of 11 query templates (or into one of two refusal categories: category discovery, and prompts that name no business, person, or address) and to extract parameters, then assembles the GraphQL query deterministically from the matching template. Fast and reliable, with no hallucinated field names, because the GraphQL comes from tested templates. Two more templates join the menu when they apply: address lookups when address search is on (see Address lookups below), and card transactions when the strategy is called directly with an entitled tier (await strategy.generate_query(prompt, tier=AccessTier.EXTERNAL); Client.search always generates at the default tier, so it never offers this template).

import asyncio
from enigma_api_client import Client, ClientConfig
from enigma_api_client.strategies import TemplateStrategy

async def main():
    config = ClientConfig(enigma_api_key="your-api-key", query_strategy=TemplateStrategy())
    async with Client(config) as client:
        # Brand lookup
        response = await client.search(prompt="Tell me about Chipotle")
        print(response.data)

        # Location search
        response = await client.search(prompt="Find Starbucks locations in California")
        print(response.data)

        # Person search
        response = await client.search(prompt="Find companies owned by Elon Musk")
        print(response.data)

        # KYB verification
        response = await client.search(prompt="Verify legal entity for Enigma Technologies in NY")
        print(response.data)

asyncio.run(main())

The template strategy covers query patterns such as: brand profiles, brand lookups by website, locations, person search, corporate officers, legal entity verification, contacts, watchlist screening, operating location profiles, address lookups (what is at a street address), aggregate counts, and risk assessment. Prompts that don't map to a supported template (for example, open ended category discovery like "list coffee shops in Denver") raise an EnigmaClientException.

GenerativeStrategy: end to end LLM query generation

Uses a single LLM call to generate the full GraphQL query and variables directly. The LLM receives an excerpt of the bundled Enigma GraphQL skill reference plus fixed query patterns and guardrails as context. More flexible than TemplateStrategy for complex or unusual queries that don't fit the templates, but slower, and it carries some risk of hallucinated field names. Generated queries are validated against the API schema and repaired (deterministically where possible, otherwise with one more LLM call) before they are returned.

import asyncio
from enigma_api_client import Client, ClientConfig
from enigma_api_client.strategies import GenerativeStrategy

async def main():
    config = ClientConfig(enigma_api_key="your-api-key", query_strategy=GenerativeStrategy())
    async with Client(config) as client:
        response = await client.search(
            prompt="Find all open Dunkin' Donuts locations in Massachusetts with phone numbers"
        )
        print(response.data)

asyncio.run(main())

AgentStrategy: Claude Agent SDK with skill

Uses the Claude Agent SDK (claude_agent_sdk) to generate GraphQL queries through an agent that can read the full enigma-graphql skill, including the field whitelist, examples, field corrections, and pagination templates. The agent reasons about the query and refines its output, and the strategy validates the answer against the schema before returning it. It produces the highest quality queries for complex scenarios but is the slowest option.

The agent runs on Amazon Bedrock only. Credentials come from the standard AWS credential chain, and the identity needs bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream on the inference profile and on the foundation model in every region the profile routes to (default model us.anthropic.claude-haiku-4-5-20251001-v1:0; pass model= and region= to change it, and keep the region inside the profile's geography). Its one tool reads files inside the bundled plugin: it has no shell, file writes, web access, or file attachments, it runs with every inherited environment variable blanked except process basics, TLS and proxy settings and the AWS credential chain, and it keeps no session transcript on disk. Its answer is written inline (variables become literals typed against the tier's schema) and passes the same post-draft gates and checks as GenerativeStrategy, with the deterministic repair but no model repair pass. max_turns (default 8) and max_budget_usd (default 0.25) bound each call.

Requires: pip install "enigma-api-client[anthropic]"

import asyncio
from enigma_api_client import Client, ClientConfig
from enigma_api_client.strategies import AgentStrategy

async def main():
    config = ClientConfig(enigma_api_key="your-api-key", query_strategy=AgentStrategy())
    async with Client(config) as client:
        response = await client.search(
            prompt="Find all open Dunkin' Donuts locations in Massachusetts with phone numbers"
        )
        print(response.data)

asyncio.run(main())

Address lookups

TemplateStrategy and GenerativeStrategy answer "what is at this address" prompts: a street address with a house number and no business name, such as "What is at 100 Main St, Wichita, KS?" or "Who is registered at 200 Oak Ave, Floor 8, Springfield, IL?". The query is an entityType: ADDRESS search limited to 10 results. It returns the matched building and its units (up to 10 rows); when the prompt names a unit, that unit usually comes first. Each result carries the address fields, five counts (associatedBrandCount, operatingLocationOperatesAtCount, legalEntityReceivesMailAtCount, registrationRecordedCount, associatedPersonCount), and the operating locations (with brand names), legal entities, and registrations at the address.

• A business name plus an address ("the Starbucks at 123 Main St") stays an operating location lookup.
• A ZIP code alone, a street with no house number, or a business type on a street ("the barbershop on Elm Street") raises EnigmaClientException with UNSUPPORTED_DATA_REQUESTED.
• Before the query is sent, the SDK cleans the address the model extracted. It requires a house number, moves a suite, floor, or apartment into street2 in USPS short form (STE 1A, FL 8), drops a unit designator with no number, removes surrounding prose and a trailing country, and converts state names to their postal codes (such as NY). GenerativeStrategy.generate_query() and AgentStrategy.generate_query() include address-input in deterministic_repair for a cleaned query.
• TemplateStrategy, GenerativeStrategy, and AgentStrategy never return a query that selects brandViaLegalEntityCount, brandViaPersonLegalEntityCount, or legalEntityViaRegistrationCount. GenerativeStrategy and AgentStrategy remove them when they can and include deferred-field in deterministic_repair; otherwise GenerativeStrategy repairs the query with the model, and AgentStrategy raises EnigmaClientException with UNSUPPORTED_DATA_REQUESTED (or UnrepairedQueryError when a repair would land on one or the answer does not parse).
• Turn it on or off with address_search= on TemplateStrategy, GenerativeStrategy, or AgentStrategy (True, False, or "auto"), or with the ENIGMA_ADDRESS_SEARCH environment variable (on, off, or auto; unset or unrecognized means auto). The setting is read when the strategy is constructed.
• In auto mode, each strategy instance decides at its first prompt for an access tier whether the API schema supports address search, and keeps that answer, even one from a failed schema request, for the life of the instance. Client supplies the schema for the default tier. With no schema (no Client created in the process and no introspector registered through enigma_api_client.validation.set_schema_introspector, or a schema request that failed at that first prompt), auto stays off.
• With address search off, a prompt that gives only an address is refused; on TemplateStrategy the reason is bare address lookup.
• ServiceStrategy doesn't take this setting. AgentStrategy takes it like GenerativeStrategy: its answer's ADDRESS searches pass the same address gate.

import asyncio
from enigma_api_client import Client, ClientConfig
from enigma_api_client.strategies import TemplateStrategy

async def main():
    config = ClientConfig(enigma_api_key="your-api-key", query_strategy=TemplateStrategy(address_search=True))
    async with Client(config) as client:
        response = await client.search(prompt="What is at 1600 Pennsylvania Ave NW, Washington DC?")
        for address in response.data["search"]:
            print(address["fullAddress"], address["associatedBrandCount"])

asyncio.run(main())

Strategy comparison

When to use which:

• ServiceStrategy (default): Generation runs on Enigma's servers, so you get the latest query logic with no local model calls and no LLM key. Best default for most callers.
• TemplateStrategy: Best when you want deterministic local generation. Covers the common query patterns with 12 templates and no hallucination risk. The LLM only classifies and extracts parameters, and the GraphQL is deterministic.
• GenerativeStrategy: Best for complex or unusual queries that don't fit the templates. The LLM generates custom GraphQL from the API reference and fixed patterns. Good for prototyping and exploratory queries.
• AgentStrategy: Best for maximum quality when latency is not a concern. The agent can read examples, check field corrections, and reason about the query. Good for batch processing or one off complex queries.

LLM providers

TemplateStrategy and GenerativeStrategy take any LLM provider through llm_provider=. Without one they use AnthropicProvider with anthropic_api_key= or ANTHROPIC_API_KEY; the strategy's model= argument applies only to that default provider.

from enigma_api_client.strategies import (
    AnthropicProvider, BedrockProvider, GenerativeStrategy, OpenRouterProvider, TemplateStrategy,
)

# Anthropic Messages API (ANTHROPIC_API_KEY)
TemplateStrategy(llm_provider=AnthropicProvider(model="claude-haiku-4-5-20251001"))

# OpenRouter (OPENROUTER_API_KEY). provider_routing is sent as OpenRouter's "provider"
# object and reasoning as its "reasoning" object; omit either to keep the default.
GenerativeStrategy(llm_provider=OpenRouterProvider(
    model="anthropic/claude-haiku-4.5",
    provider_routing={"order": ["anthropic"], "allow_fallbacks": False},
    reasoning={"enabled": False},
))

# Claude on Amazon Bedrock (pip install "enigma-api-client[bedrock]"), signed with ambient AWS credentials.
# The default model is a US inference profile; pass model= outside US regions.
TemplateStrategy(llm_provider=BedrockProvider(region="us-east-1"))

A custom provider implements the LlmProvider protocol: async def complete(system, user, max_tokens) -> Completion. Raise ValueError for a missing key or bad configuration (reported as GENERATE_QUERY_CALLBACK_NOT_CONFIGURED) and RuntimeError for a provider failure (reported as TRANSIENT_PROVIDER_ERROR); any other exception propagates unwrapped.

Environment variables

Query shape cache

TemplateStrategy and GenerativeStrategy keep an in-process cache of query shapes learned from successful generations. Once a shape has been confirmed across several different entities, a matching prompt is served from the cache without an LLM call. The cache is on by default and is shared by every caller of the same strategy instance at the same tier. Disable it with shape_cache=False or ENIGMA_SHAPE_CACHE_ENABLED=0.

Errors and response fields

Generation failures raise EnigmaClientException; its error_code is an EnigmaClientErrorCode:

RESTRICTED_DATA_REQUESTED and INVALID_VARIABLES exist for callers that enforce their own policies; the SDK does not raise them.

The provider codes come from TemplateStrategy and GenerativeStrategy. ServiceStrategy reports any hosted service failure (any status other than 200, including 401, 429, and 5xx, or a GraphQL error) as INVALID_QUERY, and its network errors (timeouts, connection failures) propagate as httpx exceptions, as do network errors from Client.search itself.

Both exceptions below import from enigma_api_client.

• TruncatedOutputError: the model hit its output token cap. This repeats for the same model and prompt, so do not retry with the same model.
• UnrepairedQueryError: GenerativeStrategy produced a query that stayed invalid after repair. It carries .draft, .errors, and .tier, and you can pass it to another GenerativeStrategy as generate_query(prompt, prior_attempt=exc) to start from that draft. Its message quotes values from the generated query, so log the exception type and error_code rather than str(exc).

SearchResponse.unavailable_data lists the parts of a prompt Enigma cannot serve, as {"field", "reason", "message"} entries (reason is contractual or out_of_scope), while the rest of the prompt is still answered.

Calling a strategy directly (await strategy.generate_query(prompt)) returns a GenerateQueryResponse with query, variables, unavailable_data, and diagnostics such as cache_rule (set when the shape cache took part) and deterministic_repair (the SDK's rewrite kinds, when it repaired the query without a model call). After a call, enigma_api_client.strategies.GENERATION_USAGE.get() returns that call's token counts (LlmUsage) and GENERATION_STAGE.get() its last generation stage; read them in the same task that awaited the call. ServiceStrategy reports zero usage; AgentStrategy reports its run's totals.

Logging

The SDK's logging surface is split by level according to content. Raw model text (the agent transcript, the prose or non JSON draft echoes, the validator detail behind a failed repair) logs only at DEBUG on the emitting module's logger (enigma_api_client.*); enabling DEBUG on those loggers (or globally) writes prompts and model output to your log sink, so do not enable it in environments with data retention constraints. WARNING and INFO lines are fixed templates carrying counts, statuses, rule and kind vocabularies, and file paths, with no raw model or validator text.

Pagination

Connections (any field returning edges { node { ... } }) return at most one page at a time. Getting a full page back (for example 100 rows) does not tell you whether more exist. You need pageInfo for that.

Automatic page info injection

Set auto_inject_page_info=True on the client and it rewrites every outgoing query, adding pageInfo { hasNextPage endCursor } to every connection that does not already request it. This applies to both raw GraphQL and prompt generated queries:

config = ClientConfig(
    enigma_api_key="your-api-key",
    auto_inject_page_info=True,
)

• hasNextPage is an authoritative "is there more?" flag from the backend. Use it instead of inferring truncation from a full page of results. It stays correct even if the page size changes, so there is nothing to keep in sync on your end.
• endCursor is the cursor for the next page.

The flag is off by default. With it off, responses are unchanged byte for byte, so upgrading without setting it changes nothing.

Fetching the next page

Re-run the same query with after: $cursor on the connection, passing the previous page's endCursor. On the first page pass cursor: null (null starts from the beginning; omitting a declared $cursor variable is what triggers an HTTP 400 "Undefined variable"). A single parameterized query paginates every page, so there is no separate first page query.

# With auto_inject_page_info=True you can omit the explicit `pageInfo` line below;
# the client adds it for you. It is shown here so the response shape is clear.
query = """query Locations($cursor: String) {
  search(searchInput: { name: "Starbucks", entityType: BRAND }) {
    ... on Brand {
      operatingLocations(first: 100, after: $cursor) {
        edges { node { id } }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
}"""

async def all_location_ids(client):
    cursor, ids = None, []
    while True:
        response = await client.search(query=query, variables={"cursor": cursor})
        connection = response.data["search"][0]["operatingLocations"]
        ids += [edge["node"]["id"] for edge in connection["edges"]]
        page = connection["pageInfo"]
        if not page["hasNextPage"]:
            return ids
        cursor = page["endCursor"]

Keep the connection's conditions and orderBy fixed across a run, since cursors are bound to the arguments that minted them.

roles does not paginate. The schema advertises last, after, and before on roles, but the API rejects all three at execution (HTTP 400). Fetch roles as a single page with first: N, optionally narrowed with conditions.

Caveats: LLM generated GraphQL

The Enigma GraphQL schema has several non obvious conventions that make LLM generated queries unreliable without guardrails. Understanding these is important regardless of which strategy you use.

Why this is hard for LLMs

The Enigma schema has about 50 field names, 5 searchable entity types (BRAND, OPERATING_LOCATION, LEGAL_ENTITY, PERSON, ADDRESS), 10+ filter operators, and 6 connection patterns. Many field names are unintuitive, and LLMs consistently guess wrong:

These cause HTTP 400 errors ("Cannot query field") that are silent failures if not handled.

Structural pitfalls

Beyond field names, the graph structure has patterns that LLMs regularly get wrong:

• search returns a flat list, not a connection. LLMs write search { edges { node { ... } } }; the correct form is search { ... on Brand { ... } }.
• Every search needs a retrieval handle. A searchInput without name, website, person, or phoneNumber is schema valid but rejected at execution with HTTP 400 "Search must include name, website, person, or phone_number". Filters never retrieve. An address alone retrieves only as entityType: ADDRESS with address.street1 (a street line with a house number) or address.id (see Address lookups above); id and tin lookups also resolve an entity directly.
• LegalEntity.persons is almost always empty. To find officers, traverse registeredEntities, then registrations, then roles, then legalEntities. LLMs take the direct (empty) path.
• Searching OPERATING_LOCATION by brand name returns nothing. Search BRAND and filter its operatingLocations connection. LLMs don't know this.
• Do not use prompt on SearchInput. The field passes schema validation, but the API rejects any query that combines prompt with a selection set (HTTP 400 at execution). Retrieve by name, website, or person instead. There is no semantic discovery mode: name: "coffee shop" returns nothing useful, and category counts go through aggregate.
• totalCount does not exist on connections. Requesting it causes HTTP 400. Use aggregate queries instead.
• Cursor pagination uses one query, not two. A single query with $cursor: String and after: $cursor paginates every page. Pass cursor: null on page 1 (null starts from the beginning; omitting the declared variable is what causes HTTP 400 "Undefined variable"). Keep the connection's conditions and orderBy fixed across a run, since cursors are bound to the arguments that minted them.

Rules enforced at execution, not in the schema

Some constraints are not expressed in the GraphQL schema: a query can pass schema validation (or any introspection based tooling) and still be rejected when it executes. Known rules include:

GenerativeStrategy checks these rules offline (ess_runtime_rule_violations) and repairs or refuses before returning a query; this also covers ServiceStrategy calls that run the generative strategy server side. The prompt= argument to client.search() is the natural language request, unrelated to SearchInput.prompt. Other strategies and raw GraphQL callers should conform to the rules directly.

Data quality traps

Even syntactically valid queries can return silently wrong data:

• Franchise resolution: Searching BRAND for a local franchise (for example, a single Days Inn) returns the parent chain's data: 1,969 locations rolled up instead of the single franchisee.
• websiteContents is a connection, not a scalar. Use websiteContents(first: 1) { edges { node { httpStatusCode } } }.

How the strategies handle this

TemplateStrategy avoids all of the above. The LLM only classifies the prompt into a template and extracts parameters (company name, state, city, and so on). The GraphQL is assembled from 12 hand written, tested templates (plus the card and address templates when they apply). No hallucination risk, but limited to the patterns those templates cover.

GenerativeStrategy sends an excerpt of the skill reference plus fixed query patterns and guardrails as system prompt context, validates the result against the schema and the rules above, and repairs it when needed. This covers most pitfalls, but the LLM can still pick the wrong fields or miss structural rules, especially for unusual queries. Review generated queries before using them in production.

AgentStrategy has full access to the skill files, examples, and field corrections reference, and can refine queries iteratively. Highest quality, but slowest and most expensive. The strategy validates the agent's answer against the schema and raises UnrepairedQueryError when it fails.

Recommendations

• For production automation, use TemplateStrategy or raw GraphQL. The templates cover the most common query patterns and are fixed, tested queries.
• For prototyping or one off complex queries, use GenerativeStrategy or AgentStrategy, but always review the generated query before trusting the results.
• Always check response.is_success() and inspect response.errors before using response.data. A plausible looking query can still fail at the API level.

Upgrading from 0.8.x

• AgentStrategy runs on Amazon Bedrock only and takes the keyword arguments model, region, max_turns, and max_budget_usd; anthropic_api_key is removed. The calling identity needs bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream on the model.
• AgentStrategy raises instead of returning an empty query: UnrepairedQueryError when its answer fails schema validation or does not parse, UNSUPPORTED_DATA_REQUESTED from the refusal gates GenerativeStrategy applies, INVALID_QUERY for an empty prompt or answer (the "not applicable" refusal), a run that ends without a query, an answer off its schema, a mutation or subscription, an answer whose variables do not fit their declared types, one nested too deeply, or one a check could not read, and TRANSIENT_PROVIDER_ERROR or PROVIDER_ERROR when the model call or the CLI fails.
• AgentStrategy records its token usage in GENERATION_USAGE.
• The anthropic and all extras pin claude_agent_sdk==0.2.110.
• AgentStrategy serves its answer inline with {} variables, refuses the call before the agent runs when the tier has no schema (PROVIDER_ERROR), refuses a mutation or subscription (INVALID_QUERY), sets no unavailable_data, and takes address_search= like GenerativeStrategy.

Upgrading from 0.7.11 or earlier

• Custom LlmProvider: complete() now returns enigma_api_client.strategies.Completion(text, truncated, input_tokens=..., cache_read_tokens=..., cache_write_tokens=..., output_tokens=...) instead of str.
• Custom QueryStrategy: generate_query(prompt, *, tier=DEFAULT_TIER, prior_attempt=None) gained prior_attempt. Implementations must set GENERATION_USAGE to a fresh LlmUsage() on entry.
• GenerativeStrategy raises TruncatedOutputError and UnrepairedQueryError. Both subclass EnigmaClientException with code INVALID_QUERY, so existing handlers still catch them.
• LLM provider transport failures now raise EnigmaClientException: TRANSIENT_PROVIDER_ERROR for timeouts and connection errors, GENERATE_QUERY_CALLBACK_NOT_CONFIGURED for configuration faults. They used to surface as raw httpx exceptions.
• restricted_fields_for and gate_blocked_fields no longer list isMentionedInMediaContents, and now list headcounts, corporateFamilies, and customs for the EXTERNAL and REDISTRIBUTION tiers.
• Address lookups are new and default to auto (see Address lookups above). With ENIGMA_ADDRESS_SEARCH=off, a prompt that gives only an address raises UNSUPPORTED_DATA_REQUESTED; 0.7.11's TemplateStrategy sent it as a nameless operating location search that the API rejected with HTTP 400.
• GenerativeStrategy now refuses some drafts with UNSUPPORTED_DATA_REQUESTED instead of serving them: a person search by surname alone, an EIN or filing number placed in name, a wildcard name pattern, a street address placed in name, and a category count offered for a listing request.
• AgentStrategy logs its transcript at DEBUG on enigma_api_client.strategies.agent, not at INFO on the root logger.
• TemplateStrategy refuses a blank prompt with INVALID_QUERY before any LLM call.