- Docs
- Guides
- Build with Enigma
- Python SDK
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.
Upgrading from 0.12.1
Section titled “Upgrading from 0.12.1”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.
Upgrading from 0.11.0
Section titled “Upgrading from 0.11.0”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.
TemplateStrategyanswers a question that names several businesses, people, or street addresses with several searches in the same query, undersearch,search2, andsearch3(see Generate queries from questions). Before, it answered one of them or refused the question.GenerativeStrategylikewise searches each brand a question names, undersearch,search2, andsearch3. Before, it usually searched only the first brand, and otherwise keyed the searches with other aliases, such asaandb.GenerativeStrategycounts each brand a how-many question names, underaggregate,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. ServiceStrategyraisesINVALID_QUERYonce the hosted service adopts this release.
- A local strategy raises
GenerativeStrategyandAgentStrategyrefuse 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
GenerativeStrategyorAgentStrategyquery that repeats a top-level field with different arguments, it keys the second onesearch2(oraggregate2). Before, it keyed itsearch_2(oraggregate_2). - Templates return a brand’s affiliated brands 50 to a page, up from 10.
GenerativeStrategyasks 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,
TemplateStrategysearches 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.
Upgrading from 0.10.3
Section titled “Upgrading from 0.10.3”- Address lookups no longer select the five
Addresscount fields (associatedBrandCount,operatingLocationOperatesAtCount,legalEntityReceivesMailAtCount,registrationRecordedCount, andassociatedPersonCount).- An address result no longer carries those keys, so code that reads
address["associatedBrandCount"]raisesKeyError. 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.
- An address result no longer carries those keys, so code that reads
- 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
Addresstype carriesassociatedBrandCount, as before. - One that defines an
Addresstype and theNodeinterface. This kind is new.
- One whose
- When a question asks how many, other than a headcount, and the query is an address lookup that selects no count,
unavailable_datahas anaddress countsentry (out_of_scope).
Upgrading from 0.10.2
Section titled “Upgrading from 0.10.2”SearchResponse.headersholds the HTTP response headers, so you can readRetry-Afteron a 429. It takes no part in==orrepr.dataclasses.asdict(response)anddataclasses.astuple(response)now include it as anhttpx.Headers, whichjson.dumpscan’t serialize.- A response body that isn’t a JSON object, such as a gateway’s error page, no longer raises
ValueError(orAttributeErrorfor JSON that isn’t an object).client.searchreturns it withdataset toNone, an error inerrors, and the body inraw_body, sois_success()is false.ServiceStrategyraisesEnigmaClientExceptionwithINVALID_QUERYfor one, andintrospect_schemaraises 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 theidand__typenameit adds to the first field, and the API rejected the query. EnigmaClientException.status_codeholds 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.headersholds 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
ValueErrornaming 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.HTTPErrorcaught. - For a character outside ASCII, the
UnicodeEncodeError, whichexcept UnicodeEncodeErrorcaught.
- The httpx error that could quote the value, which
introspect_schema, which sent an API key outside ASCII encoded as UTF-8, now refuses it the same way.- A custom
LlmProvidercan raiseProviderHTTPError, now exported fromenigma_api_client.strategies, with the HTTP status of a failure. 408, 429, and 5xx are reported asTRANSIENT_PROVIDER_ERROR, any other HTTP status asPROVIDER_ERROR, and a value that is not an HTTP status asTRANSIENT_PROVIDER_ERROR.
Upgrading from 0.10.1
Section titled “Upgrading from 0.10.1”Client.searchasks 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. AClientConfig.urlthat setsmax_background_task_waitormax_call_durationto 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’sidin place ofinternalWatchlistEntryId, which the API is retiring. The two identifiers differ, so ids you stored frominternalWatchlistEntryIdwon’t match.
Upgrading from 0.10.0
Section titled “Upgrading from 0.10.0”- An
unavailable_dataentry 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.
Upgrading from 0.9.14
Section titled “Upgrading from 0.9.14”- With
TemplateStrategy,GenerativeStrategy, orAgentStrategy, 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 gainsarchiveRecords. Beside a name search withentityType: BRAND,entityType: OPERATING_LOCATION, or noentityType, it also gainsarchiveBrandRecords. A question that asks for no records returns the same query as in 0.9.14. unavailable_dataleaves 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_dataand carries the message “This query does not return these records.” - When the SDK adds no record fields, a
violationsentry says that violation records are served as the Gov Archive records of a business, location, person, or address.
Upgrading from 0.9.13
Section titled “Upgrading from 0.9.13”- The query reference
AgentStrategyreads no longer listsinternalId, which the API is retiring on every type.
Upgrading from 0.9.12
Section titled “Upgrading from 0.9.12”- Generated queries select
pageInfo { hasNextPage endCursor }onBrand.affiliatedBrandsandLegalEntity.legalEntities, so a corporate family longer than one page can be paged withafter:.
Upgrading from 0.9.11
Section titled “Upgrading from 0.9.11”TemplateStrategylookups 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.TemplateStrategycan refuse a question about several businesses or people at once withUNSUPPORTED_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 raisesUNSUPPORTED_DATA_REQUESTEDinstead of being sent as an empty search. TemplateStrategy’s brand profiles selectoperatingLocationsin place of thehqAddressalias, so the response key changes, and no longer selectisMarketables.TemplateStrategyanswers 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.searchthen returns aLegalEntitywhose officers are underregisteredEntities,registrations, androles. Other names, including names ending in Corp, Corporation, or Ltd, still search brands.
Upgrading from 0.9.10
Section titled “Upgrading from 0.9.10”restricted_fields_forandgate_blocked_fieldsalso listplaceClasses,siteTypes, andtiersfor theEXTERNALandREDISTRIBUTIONtiers, andlegalEntitiesAppearsOnandlegalEntitiesIsFlaggedByforREDISTRIBUTION; the API does not serve them to those tiers.TemplateStrategyanswers a question about how many businesses of a category are in a place with a count instead of refusing it.
Upgrading from 0.9.9
Section titled “Upgrading from 0.9.9”restricted_fields_forandgate_blocked_fieldsno longer listheadcountsfor theEXTERNALandREDISTRIBUTIONtiers; 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,
TemplateStrategyandGenerativeStrategystill declareemployees(out_of_scope).TemplateStrategy’s entry has a new message.
Upgrading from 0.9.8
Section titled “Upgrading from 0.9.8”- The SDK also calls a schema introspector, the function registered with
enigma_api_client.validation.set_schema_introspector(including the oneClientregisters), 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 introspectorClientregisters uses the five-minute interval.- A local strategy refuses an address search, whatever
address_searchsays, while the cached schema for the access tier shows no support for address lookups. The refusal raisesUNSUPPORTED_DATA_REQUESTEDwithbare address lookupin its message. From 0.9.9 through 0.10.3, such a schema is one that lacksAddress.associatedBrandCount. For 0.11.0 and later, see Upgrading from 0.10.3. - While no schema for the access tier is cached yet,
TemplateStrategyandGenerativeStrategywith address lookups turned on (address_search=TrueorENIGMA_ADDRESS_SEARCH=on) still write address lookups. - In addition to the
restricted_fields_forfields,TemplateStrategyoutput and answers from the query shape cache drop any field your tier’s schema doesn’t define, and declare each inunavailable_dataascontractual.
Upgrading from 0.9.7
Section titled “Upgrading from 0.9.7”restricted_fields_forandgate_blocked_fieldslisttins,watchlistEntries,isFlaggedByWatchlistEntries, andappearsOnWatchlistEntriesfor theREDISTRIBUTIONtier; the API no longer serves them to it.GenerativeStrategy,TemplateStrategy, andAgentStrategydrop from the query they return each field the tier is not served, declare it inunavailable_data(contractual, withfieldset to the field’s schema name), and addrestricted-fieldtodeterministic_repair. A query left with nothing else, or whose filter,orderBy, orfieldargument path still names such a field, raisesUNSUPPORTED_DATA_REQUESTED.ClientConfig.tier(defaultAccessTier.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.ServiceStrategyignores it.- Schema validation is process-wide and follows the first
Client’s tier. A laterClientat another tier validates without the schema, and itsAgentStrategyraisesPROVIDER_ERROR. Client.searchpassestier=togenerate_querywhenClientConfig.tieris not the default, so a customQueryStrategymust accept atierkeyword argument.
Upgrading from 0.9.1
Section titled “Upgrading from 0.9.1”__urllinks 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__urllinks to the brand it appears under, or to Enigma’s website when it appears under none, instead of a person profile.
Upgrading from 0.9.0
Section titled “Upgrading from 0.9.0”TemplateStrategycounts a brand’s locations (“How many Starbucks are in Texas?”) with a brand search, so the count moves fromdata.aggregate.locationsCounttodata.search[0].locationsCount.brandsCountis no longer returned, andsearchis 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.
Upgrading from 0.8.x
Section titled “Upgrading from 0.8.x”AgentStrategyruns on Amazon Bedrock only and takes the keyword argumentsmodel,region,max_turns, andmax_budget_usd;anthropic_api_keyis removed. The calling identity needsbedrock:InvokeModelandbedrock:InvokeModelWithResponseStreamon the model.AgentStrategyraises instead of returning an empty query:UnrepairedQueryErrorwhen its answer fails schema validation or does not parse.UNSUPPORTED_DATA_REQUESTEDfrom the refusal checksGenerativeStrategyapplies.INVALID_QUERYfor:- 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.
- An empty prompt or answer (the message starts
TRANSIENT_PROVIDER_ERRORorPROVIDER_ERRORwhen the model call or the Claude Code CLI the agent runs fails.
AgentStrategyrecords its token usage inGENERATION_USAGE.- The
anthropicandallextras pin an exactclaude_agent_sdkversion (currently 0.2.121). AgentStrategywrites every value into the query text and returns{}as its variables. When the tier has no schema, it refuses the call withPROVIDER_ERRORbefore the agent runs. It takesaddress_search=likeGenerativeStrategy.
Upgrading from 0.7.x or earlier
Section titled “Upgrading from 0.7.x or earlier”- Custom
LlmProvider:complete()now returnsenigma_api_client.strategies.Completion(text, truncated, input_tokens=..., cache_read_tokens=..., cache_write_tokens=..., output_tokens=...)instead ofstr. - Custom
QueryStrategy:generate_query(prompt, *, tier=DEFAULT_TIER, prior_attempt=None)gainedprior_attempt. Implementations must setGENERATION_USAGEto a freshLlmUsage()on entry. GenerativeStrategyraisesTruncatedOutputErrorandUnrepairedQueryError. Both subclassEnigmaClientExceptionwith codeINVALID_QUERY, so existing handlers still catch them.- LLM provider transport failures now raise
EnigmaClientException:TRANSIENT_PROVIDER_ERRORfor timeouts and connection errors,GENERATE_QUERY_CALLBACK_NOT_CONFIGUREDfor configuration faults. They used to surface as rawhttpxexceptions. restricted_fields_forandgate_blocked_fieldsno longer listisMentionedInMediaContents, and now listheadcounts,corporateFamilies, andcustomsfor theEXTERNALandREDISTRIBUTIONtiers.- Address lookups are new and default to
auto(see Look up an address). - With address lookups off (for example,
ENIGMA_ADDRESS_SEARCH=off),TemplateStrategyusually refuses a question that gives only an address, raisingUNSUPPORTED_DATA_REQUESTEDorINVALID_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. GenerativeStrategynow refuses some queries its LLM writes withUNSUPPORTED_DATA_REQUESTEDinstead of serving them: a person search by surname alone, an EIN or filing number placed inname, a wildcard name pattern, a street address placed inname, and a category count written for a question that asks for a list.AgentStrategylogs its transcript at DEBUG onenigma_api_client.strategies.agent, not at INFO on the root logger.TemplateStrategyrefuses a blank prompt withINVALID_QUERYbefore any LLM call.