Skip to content
Console(opens in a new tab)

Upgrade notes

What changes for your code when you upgrade the SDK from an earlier release.

Each section lists what changed after the version it names. Read every section that names your current version or a later one.

For AccessTier.REDISTRIBUTION, a local strategy no longer selects emailAddresses or phoneNumbers under a role (see Access tiers), so code that reads them from a generated query’s results raises KeyError. The API answers a redistribution key with placeholder values for both. A generated query that selects nothing else is refused with UNSUPPORTED_DATA_REQUESTED. On every tier, TemplateStrategy’s contacts lookup now also returns the address and phone number of the location whose roles it lists. With Client’s default strategy, this reaches you when the hosted service adopts this release.

With Client’s default strategy, the hosted service builds the query. The TemplateStrategy and GenerativeStrategy changes in this section reach you when the service adopts this release, whatever SDK version you run.

  • TemplateStrategy answers a question that names several businesses, people, or street addresses with several searches in the same query, under search, search2, and search3 (see Generate queries from questions). Before, it answered one of them or refused the question.
  • GenerativeStrategy likewise searches each brand a question names, under search, search2, and search3. Before, it usually searched only the first brand, and otherwise keyed the searches with other aliases, such as a and b.
  • GenerativeStrategy counts each brand a how-many question names, under aggregate, aggregate2, and so on. Before, it counted only the first brand.
  • Code that reads only data["search"] gets the first search. Read the other keys for the rest.
  • A generated query with more than three top-level fields (searches or counts) is refused. The government-record searches the SDK adds beside them don’t count.
    • A local strategy raises UNSUPPORTED_DATA_REQUESTED.
    • ServiceStrategy raises INVALID_QUERY once the hosted service adopts this release.
  • GenerativeStrategy and AgentStrategy refuse a query when any one of its searches is a kind they refuse (see GenerativeStrategy). Before, they refused it only when every top-level field in it was such a search.
  • When the SDK repairs a GenerativeStrategy or AgentStrategy query that repeats a top-level field with different arguments, it keys the second one search2 (or aggregate2). Before, it keyed it search_2 (or aggregate_2).
  • Templates return a brand’s affiliated brands 50 to a page, up from 10. GenerativeStrategy asks its LLM for the same page size.
  • A template legal entity lookup lists a business’s registrations in each state the question gives that business (see How template queries read places). Before, it listed none when the question gave several states.
  • In a lookup of one location of a business (“the Starbucks at 1 Main St”) or of an address, TemplateStrategy searches each street, city, and state the question lists, and, in an address lookup, each unit and ZIP code. Before, it sent the list in a single field, dropped it, or refused the question. A question about a brand’s locations in several cities still gets one search covering them all.
  • How template queries read places describes how the places a question lists apply to several businesses or people, and when a list of places is refused.
  • Address lookups no longer select the five Address count fields (associatedBrandCount, operatingLocationOperatesAtCount, legalEntityReceivesMailAtCount, registrationRecordedCount, and associatedPersonCount).
    • An address result no longer carries those keys, so code that reads address["associatedBrandCount"] raises KeyError. Read the operating locations, legal entities, and registrations each address lists instead.
    • With Client’s default strategy, the hosted service builds the query, so this change reaches you when the service adopts the release, whatever SDK version you run.
  • Two kinds of schema now count as supporting address lookups, both for address_search="auto" and for the address-search refusal described in Turn address lookups on or off:
    • One whose Address type carries associatedBrandCount, as before.
    • One that defines an Address type and the Node interface. This kind is new.
  • When a question asks how many, other than a headcount, and the query is an address lookup that selects no count, unavailable_data has an address counts entry (out_of_scope).
  • SearchResponse.headers holds the HTTP response headers, so you can read Retry-After on a 429. It takes no part in == or repr. dataclasses.asdict(response) and dataclasses.astuple(response) now include it as an httpx.Headers, which json.dumps can’t serialize.
  • A response body that isn’t a JSON object, such as a gateway’s error page, no longer raises ValueError (or AttributeError for JSON that isn’t an object). client.search returns it with data set to None, an error in errors, and the body in raw_body, so is_success() is false. ServiceStrategy raises EnigmaClientException with INVALID_QUERY for one, and introspect_schema raises its “no schema data” RuntimeError.
  • A query written with no space after an opening brace, such as node{name}, is sent correctly. The client used to join the id and __typename it adds to the first field, and the API rejected the query.
  • EnigmaClientException.status_code holds the HTTP status of the failed LLM provider or hosted-service call behind an error, when there was one, so retry logic needs no message parsing.
  • For the hosted service, EnigmaClientException.headers holds its response headers.
  • When the SDK maps a provider’s exception to EnigmaClientException, that exception is its __cause__.
  • The error code for each HTTP status is unchanged.
  • An API key or header value an HTTP header can’t carry as written, such as one with a newline or a trailing space, raises ValueError naming the header, before the API request is sent. It replaces two errors, so the handlers that caught them no longer catch this case:
    • The httpx error that could quote the value, which except httpx.HTTPError caught.
    • For a character outside ASCII, the UnicodeEncodeError, which except UnicodeEncodeError caught.
  • introspect_schema, which sent an API key outside ASCII encoded as UTF-8, now refuses it the same way.
  • A custom LlmProvider can raise ProviderHTTPError, now exported from enigma_api_client.strategies, with the HTTP status of a failure. 408, 429, and 5xx are reported as TRANSIENT_PROVIDER_ERROR, any other HTTP status as PROVIDER_ERROR, and a value that is not an HTTP status as TRANSIENT_PROVIDER_ERROR.
  • Client.search asks the API to wait up to 25 seconds for values it computes in the background, such as some counts, before it answers. The API answers a request with no background work at once. A ClientConfig.url that sets max_background_task_wait or max_call_duration to a non-blank value keeps its own wait.
  • SearchResponse.is_success() is false for an HTTP 206 answer, whose background values are still null. It is also false for an answer that reports a background task that failed, was canceled, or ran out of credits.
  • TemplateStrategy’s brand watchlist template selects each watchlist entry’s id in place of internalWatchlistEntryId, which the API is retiring. The two identifiers differ, so ids you stored from internalWatchlistEntryId won’t match.
  • An unavailable_data entry for something the selected government records answer only in part, such as “tax liens”, gets the message “The returned records cover this only in part.” when the query selects those records.
  • The phrases “work permit”, “export permit”, “licensing agreement”, and “drivers’ license” no longer ask for government records.
  • With TemplateStrategy, GenerativeStrategy, or AgentStrategy, a question that asks for an entity’s government or public records returns a query that selects them. Each returned entity carries the fields listed under Records on each entity. Beside a search by a name, person, or street address, the response gains archiveRecords. Beside a name search with entityType: BRAND, entityType: OPERATING_LOCATION, or no entityType, it also gains archiveBrandRecords. A question that asks for no records returns the same query as in 0.9.14.
  • unavailable_data leaves out an entry the selected records answer in full, such as “liquor licenses” or “violations”.
  • When the SDK adds record counts but none of the records the question asks for, each entry those records would answer in full stays in unavailable_data and carries the message “This query does not return these records.”
  • When the SDK adds no record fields, a violations entry says that violation records are served as the Gov Archive records of a business, location, person, or address.
  • The query reference AgentStrategy reads no longer lists internalId, which the API is retiring on every type.
  • Generated queries select pageInfo { hasNextPage endCursor } on Brand.affiliatedBrands and LegalEntity.legalEntities, so a corporate family longer than one page can be paged with after:.
  • TemplateStrategy lookups return a core set of fields plus only the data the question asks for (see TemplateStrategy). A plain “verify” question no longer returns TINs, watchlist entries, bankruptcies, or officers; ask for them, or ask a compliance question.
  • TemplateStrategy’s legal entity lookup searches by name only, and reads a state in the question as the registrations to list in that state.
  • TemplateStrategy can refuse a question about several businesses or people at once with UNSUPPORTED_DATA_REQUESTED. From 0.12.0 it answers up to three at once (see Upgrading from 0.11.0).
  • With TemplateStrategy, a question with no usable name, website, or person name raises UNSUPPORTED_DATA_REQUESTED instead of being sent as an empty search.
  • TemplateStrategy’s brand profiles select operatingLocations in place of the hqAddress alias, so the response key changes, and no longer select isMarketables.
  • TemplateStrategy answers an officers question by searching legal entities when the name has more than one word, ends in Inc, Incorporated, Co, Company, LLC, LP, LLP, LLLP, or PLLC, and comes with no website. search then returns a LegalEntity whose officers are under registeredEntities, registrations, and roles. Other names, including names ending in Corp, Corporation, or Ltd, still search brands.
  • restricted_fields_for and gate_blocked_fields also list placeClasses, siteTypes, and tiers for the EXTERNAL and REDISTRIBUTION tiers, and legalEntitiesAppearsOn and legalEntitiesIsFlaggedBy for REDISTRIBUTION; the API does not serve them to those tiers.
  • TemplateStrategy answers a question about how many businesses of a category are in a place with a count instead of refusing it.
  • restricted_fields_for and gate_blocked_fields no longer list headcounts for the EXTERNAL and REDISTRIBUTION tiers; the API serves it to every tier.
  • A headcount question on a brand or legal entity now selects each legal entity’s headcount band instead of declaring headcount in unavailable_data.
  • For a headcount question whose query is not a company or legal entity lookup, TemplateStrategy and GenerativeStrategy still declare employees (out_of_scope). TemplateStrategy’s entry has a new message.
  • The SDK also calls a schema introspector, the function registered with enigma_api_client.validation.set_schema_introspector (including the one Client registers), from a background thread with no context variables set. It does so:
    • When a strategy needs a tier’s schema and none is cached yet.
    • On the first use of a cached schema that is more than five minutes old.
  • The introspector must be thread-safe, return in bounded time, and not rely on context variables.
  • set_schema_introspector(introspector, refresh_seconds=None) turns off the refresh of cached schemas. A missing schema is still fetched in the background. The introspector Client registers uses the five-minute interval.
  • A local strategy refuses an address search, whatever address_search says, while the cached schema for the access tier shows no support for address lookups. The refusal raises UNSUPPORTED_DATA_REQUESTED with bare address lookup in its message. From 0.9.9 through 0.10.3, such a schema is one that lacks Address.associatedBrandCount. For 0.11.0 and later, see Upgrading from 0.10.3.
  • While no schema for the access tier is cached yet, TemplateStrategy and GenerativeStrategy with address lookups turned on (address_search=True or ENIGMA_ADDRESS_SEARCH=on) still write address lookups.
  • In addition to the restricted_fields_for fields, TemplateStrategy output and answers from the query shape cache drop any field your tier’s schema doesn’t define, and declare each in unavailable_data as contractual.
  • restricted_fields_for and gate_blocked_fields list tins, watchlistEntries, isFlaggedByWatchlistEntries, and appearsOnWatchlistEntries for the REDISTRIBUTION tier; the API no longer serves them to it.
  • GenerativeStrategy, TemplateStrategy, and AgentStrategy drop from the query they return each field the tier is not served, declare it in unavailable_data (contractual, with field set to the field’s schema name), and add restricted-field to deterministic_repair. A query left with nothing else, or whose filter, orderBy, or field argument path still names such a field, raises UNSUPPORTED_DATA_REQUESTED.
  • ClientConfig.tier (default AccessTier.REDISTRIBUTION) is the tier a local strategy generates for and validates against. Set it to your key’s tier to keep TIN and watchlist selections with an external key. ServiceStrategy ignores it.
  • Schema validation is process-wide and follows the first Client’s tier. A later Client at another tier validates without the schema, and its AgentStrategy raises PROVIDER_ERROR.
  • Client.search passes tier= to generate_query when ClientConfig.tier is not the default, so a custom QueryStrategy must accept a tier keyword argument.
  • __url links point at the Enigma Console’s profile pages: https://console.enigma.com/profile/brand/<id>, /profile/legal-entity/<id>, and /profile/operating-location/<id>. Old links still redirect. A person’s __url links to the brand it appears under, or to Enigma’s website when it appears under none, instead of a person profile.
  • TemplateStrategy counts a brand’s locations (“How many Starbucks are in Texas?”) with a brand search, so the count moves from data.aggregate.locationsCount to data.search[0].locationsCount. brandsCount is no longer returned, and search is empty when no brand matches. The count covers only that brand’s open locations in the state and city the question names; before, it counted every open location, whatever the brand.
  • 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 checks GenerativeStrategy applies.
    • INVALID_QUERY for:
      • An empty prompt or answer (the message starts Query is not applicable to the Enigma API).
      • A run that ends without a query.
      • An answer that doesn’t match the agent’s answer format.
      • A mutation or subscription.
      • An answer whose variables don’t fit their declared types.
      • An answer nested too deeply.
      • An answer the SDK couldn’t check.
      • An answer over 10,000 characters.
    • TRANSIENT_PROVIDER_ERROR or PROVIDER_ERROR when the model call or the Claude Code CLI the agent runs fails.
  • AgentStrategy records its token usage in GENERATION_USAGE.
  • The anthropic and all extras pin an exact claude_agent_sdk version (currently 0.2.121).
  • AgentStrategy writes every value into the query text and returns {} as its variables. When the tier has no schema, it refuses the call with PROVIDER_ERROR before the agent runs. It takes address_search= like GenerativeStrategy.
  • 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 Look up an address).
  • With address lookups off (for example, ENIGMA_ADDRESS_SEARCH=off), TemplateStrategy usually refuses a question that gives only an address, raising UNSUPPORTED_DATA_REQUESTED or INVALID_QUERY (see Turn address lookups on or off). Before 0.8.0, it could send such a question as a nameless operating location search, which the API rejected with HTTP 400.
  • GenerativeStrategy now refuses some queries its LLM writes 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 written for a question that asks for a list.
  • 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.