Metadata-Version: 2.4
Name: enigma-api-client
Version: 0.15.3
Summary: Python SDK for the Enigma GraphQL API: search business data with GraphQL queries or questions in plain English
Author-email: Enigma Technologies <info@enigma.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.enigma.com/
Project-URL: Documentation, https://documentation.enigma.com/guides/python-sdk/quickstart/
Project-URL: Upgrade notes, https://documentation.enigma.com/guides/python-sdk/upgrade-notes/
Project-URL: GraphQL API, https://documentation.enigma.com/guides/graphql-api/quickstart/
Keywords: enigma,graphql,business data,company data,kyb,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx==0.28.1
Requires-Dist: pyyaml==6.0.3
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: graphql-core==3.2.12
Provides-Extra: anthropic
Requires-Dist: claude_agent_sdk==0.2.121; extra == "anthropic"
Provides-Extra: bedrock
Requires-Dist: botocore>=1.34.0; extra == "bedrock"
Provides-Extra: all
Requires-Dist: claude_agent_sdk==0.2.121; extra == "all"
Requires-Dist: botocore>=1.34.0; extra == "all"
Provides-Extra: turbo
Requires-Dist: enigma-turbo-model==0.2.2; extra == "turbo"
Requires-Dist: onnxruntime==1.31.1; extra == "turbo"
Requires-Dist: tokenizers<0.24,>=0.20; extra == "turbo"
Requires-Dist: numpy<2.6,>=1.26.4; extra == "turbo"
Dynamic: license-file

# Enigma API Client

The Enigma Python SDK, [`enigma-api-client`](https://pypi.org/project/enigma-api-client/), sends GraphQL queries to the [Enigma GraphQL API](https://documentation.enigma.com/guides/graphql-api/quickstart/) and turns questions in plain English into those queries. This page gets you started, and the [Python SDK guide](https://documentation.enigma.com/guides/python-sdk/quickstart/) covers the rest.

## Before You Begin

- An Enigma API key. Find yours in the [Enigma Console](https://console.enigma.com/settings/api-keys) under **Settings > Account > API keys**.
- Python 3.11 or later.

The examples read your Enigma API key from the `ENIGMA_API_KEY` environment variable:

```bash
export ENIGMA_API_KEY="your-api-key"
```

## Install

```bash
pip install enigma-api-client
```

The examples on this page need no extra. The guide's [quickstart](https://documentation.enigma.com/guides/python-sdk/quickstart/#install) lists the optional extras for generating queries on your own machine, and its [Choose a strategy](https://documentation.enigma.com/guides/python-sdk/questions/#choose-a-strategy) section gives the time each strategy takes to write a query.

The experimental [`TurboStrategy`](https://documentation.enigma.com/guides/python-sdk/questions/#turbostrategy) writes queries on your machine with a small model and no LLM call. The `turbo` extra installs its model, the [`enigma-turbo-model`](https://pypi.org/project/enigma-turbo-model/) package, and the libraries that run it:

```bash
pip install "enigma-api-client[turbo]"
```

## Quickstart

### Ask a Question

```python
import asyncio
import os

from enigma_api_client import Client, ClientConfig


async def main():
    config = ClientConfig(enigma_api_key=os.environ["ENIGMA_API_KEY"])
    async with Client(config) as client:
        response = await client.search(prompt="Tell me about Chipotle")
        if not response.is_success():
            raise RuntimeError(f"HTTP {response.status_code}: {response.errors}")
        brand = response.data["search"][0]
        print(brand["names"]["edges"][0]["node"]["name"])  # CHIPOTLE MEXICAN GRILL
        print(brand["__url"])  # the brand's profile in the Enigma Console


asyncio.run(main())
```

The SDK turns the question into a GraphQL query, runs it, and returns the result. By default, Enigma's hosted query service writes the query, so your Enigma API key is all you need.

### Send a GraphQL Query

```python
import asyncio
import os

from enigma_api_client import Client, ClientConfig

QUERY = """
query Brand($name: String!) {
  search(searchInput: { name: $name, entityType: BRAND, conditions: { limit: 1 } }) {
    ... on Brand {
      names(first: 1) { edges { node { name } } }
      websites(first: 1) { edges { node { website } } }
    }
  }
}
"""


async def main():
    config = ClientConfig(enigma_api_key=os.environ["ENIGMA_API_KEY"])
    async with Client(config) as client:
        response = await client.search(query=QUERY, variables={"name": "Chipotle"})
        if not response.is_success():
            raise RuntimeError(f"HTTP {response.status_code}: {response.errors}")
        brand = response.data["search"][0]
        print(brand["names"]["edges"][0]["node"]["name"])  # CHIPOTLE MEXICAN GRILL
        print(brand["websites"]["edges"][0]["node"]["website"])  # https://www.chipotle.com


asyncio.run(main())
```

A name can match many entities, so `conditions: { limit: 1 }` keeps only the first.

## Python SDK Guide

- [Quickstart](https://documentation.enigma.com/guides/python-sdk/quickstart/): install the SDK, ask a question in plain English, and send your first GraphQL query.
- [Configure the client and read responses](https://documentation.enigma.com/guides/python-sdk/client/): set up the client, read what a search returns, handle errors, and page through connections.
- [Generate queries from questions](https://documentation.enigma.com/guides/python-sdk/questions/): the questions the SDK answers, the strategies that turn them into GraphQL, and the data each access tier returns.
- [Customize query generation](https://documentation.enigma.com/guides/python-sdk/customize/): pick the LLM provider, write your own provider or strategy, control the query shape cache, and read the token usage of each call.
- [Look up addresses and government records](https://documentation.enigma.com/guides/python-sdk/addresses-and-records/): find what is at a street address and get the government records of a business, person, or address.
- [Python SDK reference](https://documentation.enigma.com/guides/python-sdk/reference/): environment variables, logging, what the SDK sends off your machine, and the rules for GraphQL you write by hand.
- [Upgrade notes](https://documentation.enigma.com/guides/python-sdk/upgrade-notes/): what changes for your code when you upgrade the SDK from an earlier release.

## GraphQL API

- [GraphQL quickstart](https://documentation.enigma.com/guides/graphql-api/quickstart/): how a GraphQL query reads Enigma data, with a first search.
- [GraphQL reference](https://documentation.enigma.com/reference/graphql/): every keyword of the schema.
- [API basics](https://documentation.enigma.com/reference/graphql/api-basics/): the endpoint, authentication, status codes, rate limits, and credits.
- [How Enigma models a business](https://documentation.enigma.com/data-model/): brands, legal entities, operating locations, people, and addresses, and how they connect.
- [Ask a question in plain English](https://documentation.enigma.com/guides/graphql-api/prompt-search/): send a question to the API, which writes and runs the search.
- [Gov Archive records](https://documentation.enigma.com/guides/graphql-api/gov-archive/): government records about a business, a person, or an address.

## Support

For help, write to [Enigma support](mailto:support@enigma.com).
