enigma-api-client 0.3.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. enigma_api_client/__init__.py +16 -0
  2. enigma_api_client/client.py +134 -0
  3. enigma_api_client/client_inject_id_and_typename_helper.py +248 -0
  4. enigma_api_client/client_inject_urls_helper.py +26 -0
  5. enigma_api_client/plugins/.DS_Store +0 -0
  6. enigma_api_client/plugins/enigma-api/.claude-plugin/plugin.json +8 -0
  7. enigma_api_client/plugins/enigma-api/README.md +82 -0
  8. enigma_api_client/plugins/enigma-api/harness/conftest.py +42 -0
  9. enigma_api_client/plugins/enigma-api/harness/test_linter.py +863 -0
  10. enigma_api_client/plugins/enigma-api/harness/test_queries.py +143 -0
  11. enigma_api_client/plugins/enigma-api/harness/test_skill_rules.py +351 -0
  12. enigma_api_client/plugins/enigma-api/pyproject.toml +9 -0
  13. enigma_api_client/plugins/enigma-api/scripts/__pycache__/lint_query.cpython-313.pyc +0 -0
  14. enigma_api_client/plugins/enigma-api/scripts/__pycache__/query_validator.cpython-313.pyc +0 -0
  15. enigma_api_client/plugins/enigma-api/scripts/__pycache__/query_validator.cpython-314.pyc +0 -0
  16. enigma_api_client/plugins/enigma-api/scripts/generate_report.py +384 -0
  17. enigma_api_client/plugins/enigma-api/scripts/lint_query.py +712 -0
  18. enigma_api_client/plugins/enigma-api/scripts/query_validator.py +352 -0
  19. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/SKILL.md +620 -0
  20. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/brand/03_brand_profile.md +163 -0
  21. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/brand/13_brand_dump.md +95 -0
  22. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/derived/07_coalesce_ein_formation.md +146 -0
  23. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/discovery/01_coffee_shops_zip.md +287 -0
  24. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/discovery/11_ol_industry_discovery.md +116 -0
  25. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/export/08_segment_export.md +96 -0
  26. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/kyb/02_officers_lookup.md +366 -0
  27. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/kyb/10_kyb_verify.md +176 -0
  28. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/legal_entity/09_legal_entity_profile.md +97 -0
  29. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/locations/05_brand_locations_by_state.md +120 -0
  30. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/person_search/04_find_person_companies.md +160 -0
  31. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/revenue/06_brand_revenue.md +176 -0
  32. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/risk/12_risk_signals.md +118 -0
  33. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/references/card_transactions.md +91 -0
  34. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/references/field_corrections.json +106 -0
  35. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/references/filter_syntax.md +203 -0
  36. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/references/naics_2022_mapping.json +184 -0
  37. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/references/pagination_template.py +115 -0
  38. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/schema.graphql +44971 -0
  39. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/scripts/test_examples.py +1122 -0
  40. enigma_api_client/plugins/enigma-api/skills/enigma-graphql/scripts/validate_query.py +177 -0
  41. enigma_api_client/plugins/enigma-api/test-cases/graphql-test-cases.md +196 -0
  42. enigma_api_client/plugins/enigma-api/tests/accuracy_cases.csv +116 -0
  43. enigma_api_client/plugins/enigma-api/tests/applicability_review.csv +64 -0
  44. enigma_api_client/plugins/enigma-api/tests/parallel-ground-truth.csv +101 -0
  45. enigma_api_client/plugins/enigma-api/tests/run_tests.sh +320 -0
  46. enigma_api_client/plugins/enigma-api/tests/test_cases.yaml +213 -0
  47. enigma_api_client/plugins/enigma-api/tests/validation_cases.csv +101 -0
  48. enigma_api_client/py.typed +0 -0
  49. enigma_api_client/query_router/__init__.py +3 -0
  50. enigma_api_client/query_router/geo.py +121 -0
  51. enigma_api_client/query_router/templates.py +475 -0
  52. enigma_api_client/strategies/__init__.py +16 -0
  53. enigma_api_client/strategies/agent.py +63 -0
  54. enigma_api_client/strategies/base.py +15 -0
  55. enigma_api_client/strategies/generative.py +143 -0
  56. enigma_api_client/strategies/llm_provider.py +137 -0
  57. enigma_api_client/strategies/service.py +103 -0
  58. enigma_api_client/strategies/template.py +189 -0
  59. enigma_api_client-0.3.1.dist-info/METADATA +257 -0
  60. enigma_api_client-0.3.1.dist-info/RECORD +63 -0
  61. enigma_api_client-0.3.1.dist-info/WHEEL +5 -0
  62. enigma_api_client-0.3.1.dist-info/licenses/LICENSE +201 -0
  63. enigma_api_client-0.3.1.dist-info/top_level.txt +5 -0
@@ -0,0 +1,163 @@
1
+ # Brand Lookup Examples
2
+
3
+ ## User Intent
4
+
5
+ Look up a specific company to get its profile, revenue, locations, contacts, and corporate structure.
6
+
7
+ ## Key Concepts
8
+
9
+ - Use `name` (entity resolution) with `entityType: BRAND`
10
+ - Brand-level card transactions always require `IS_NULL: ["platformBrandId"]`
11
+ - Contacts live on `operatingLocations → roles`, NOT `Brand.roles` (which is empty)
12
+ - Two paths for people: brand contacts (via OL roles) and legal entity contacts (via registrations)
13
+
14
+ ---
15
+
16
+ ## Full Brand Profile
17
+
18
+ ```graphql
19
+ query BrandProfile($searchInput: SearchInput!) {
20
+ search(searchInput: $searchInput) {
21
+ ... on Brand {
22
+ id
23
+ names(first: 1) { edges { node { name } } }
24
+ legalNames: legalEntities(first: 1) {
25
+ edges { node { registeredEntities(first: 1) { edges { node { name } } } } }
26
+ }
27
+ brandCardRevenueAmount: cardTransactions(first: 1, conditions: {
28
+ filter: { AND: [
29
+ { EQ: ["quantityType", "card_revenue_amount"] }
30
+ { EQ: ["rank", 0] }
31
+ { EQ: ["period", "12m"] }
32
+ { IS_NULL: ["platformBrandId"] }
33
+ ]}
34
+ }) {
35
+ edges { node { projectedQuantity periodEndDate period quantityType } }
36
+ }
37
+ websites { edges { node { website domain } } }
38
+ primaryPhone: operatingLocations(first: 1, conditions: { filter: { HAS: ["phoneNumbers"] } }) {
39
+ edges { node { phoneNumbers(first: 1) { edges { node { phoneNumber } } } } }
40
+ }
41
+ hqAddress: operatingLocations(first: 1) {
42
+ edges { node {
43
+ addresses(first: 1) { edges { node { fullAddress streetAddress1 streetAddress2 zip city state msa } } }
44
+ } }
45
+ }
46
+ peopleConnectedToLegalEntity: legalEntities {
47
+ edges { node {
48
+ registeredEntities { edges { node {
49
+ registrations { edges { node {
50
+ roles(first: 5, conditions: { filter: { NE: ["jobTitle", "registered agent"] } }) {
51
+ edges { node {
52
+ jobTitle
53
+ legalEntities { edges { node {
54
+ persons(first: 1) { edges { node {
55
+ names(first: 1) { edges { node { firstName lastName } } }
56
+ } } }
57
+ } } }
58
+ } }
59
+ }
60
+ } } }
61
+ } } }
62
+ } }
63
+ }
64
+ peopleConnectedToBrand: operatingLocations(first: 1) {
65
+ edges { node {
66
+ roles(first: 10, conditions: { filter: { NE: ["jobTitle", "registered agent"] } }) {
67
+ edges { node {
68
+ jobFunction jobTitle
69
+ legalEntities { edges { node {
70
+ persons(first: 1) { edges { node {
71
+ names(first: 1) { edges { node { firstName lastName } } }
72
+ } } }
73
+ } } }
74
+ } }
75
+ }
76
+ } }
77
+ }
78
+ }
79
+ }
80
+ }
81
+ ```
82
+
83
+ ```json
84
+ {
85
+ "searchInput": {
86
+ "conditions": { "limit": 1 },
87
+ "entityType": "BRAND",
88
+ "name": "CONSIGNMENT BROOKLYN",
89
+ "website": "https://www.consignmentbrooklyn.com/"
90
+ }
91
+ }
92
+ ```
93
+
94
+ ---
95
+
96
+ ## Marketing Overview
97
+
98
+ ```graphql
99
+ query MarketingBrand($searchInput: SearchInput!) {
100
+ search(searchInput: $searchInput) {
101
+ ... on Brand {
102
+ id
103
+ names { edges { node { name } } }
104
+ industries { edges { node { industryDesc industryCode industryType } } }
105
+ revenueQualities { edges { node { issueReason issueSeverity issueDescription } } }
106
+ isMarketables { edges { node { isMarketable } } }
107
+ websites { edges { node { website domain } } }
108
+ locationDescriptions { edges { node { locationDescription } } }
109
+ operatingLocations(first: 500) {
110
+ pageInfo { hasNextPage endCursor }
111
+ edges {
112
+ node {
113
+ addresses(first: 1) { edges { node { fullAddress } } }
114
+ operatingStatuses(first: 1) { edges { node { operatingStatus } } }
115
+ }
116
+ }
117
+ }
118
+ }
119
+ }
120
+ }
121
+ ```
122
+
123
+ ---
124
+
125
+ ## Brand Locations by Geography
126
+
127
+ **NEVER search `OPERATING_LOCATION` by brand name** — returns empty. Search BRAND, filter locations:
128
+
129
+ ```graphql
130
+ query BrandLocations($searchInput: SearchInput!, $conditions: ConnectionConditions) {
131
+ search(searchInput: $searchInput) {
132
+ ... on Brand {
133
+ id
134
+ names { edges { node { name } } }
135
+ operatingLocations(first: 500, conditions: $conditions) {
136
+ pageInfo { hasNextPage endCursor }
137
+ edges {
138
+ node {
139
+ id
140
+ names { edges { node { name } } }
141
+ addresses(first: 1) { edges { node { fullAddress state city } } }
142
+ phoneNumbers(first: 1) { edges { node { phoneNumber } } }
143
+ operatingStatuses(first: 1) { edges { node { operatingStatus } } }
144
+ }
145
+ }
146
+ }
147
+ }
148
+ }
149
+ }
150
+ ```
151
+
152
+ **Filter by state**: `{ "conditions": { "filter": { "EQ": ["addresses.state", "NY"] } } }`
153
+
154
+ **Filter by city**: `{ "conditions": { "filter": { "IN": ["addresses.city", ["NEW YORK", "BROOKLYN"]] } } }`
155
+
156
+ ---
157
+
158
+ ## Common Mistakes to Avoid
159
+
160
+ 1. **Missing `IS_NULL: ["platformBrandId"]`** on brand card transactions — revenue will be 2x-5x inflated
161
+ 2. **Searching `OPERATING_LOCATION` by brand name** — always returns empty
162
+ 3. **Using `Brand.roles`** to find contacts — always empty. Use `operatingLocations → roles`
163
+ 4. **Franchise/chain confusion** — brand-level revenue is the entire chain. For single-location, use OPERATING_LOCATION search with street address
@@ -0,0 +1,95 @@
1
+ # Data Engineering: Comprehensive Brand Dump
2
+
3
+ ## User Intent
4
+
5
+ Fetch ALL available connections and scalar fields for a brand — a complete data dump for analysis.
6
+
7
+ ## Key Concepts
8
+
9
+ - Includes `activities`, `isMarketables`, `locationDescriptions` (often overlooked scalar connections)
10
+ - Use the Pagination Template to fetch more of any connection
11
+ - Brand-level card transactions always need `IS_NULL: ["platformBrandId"]`
12
+
13
+ ---
14
+
15
+ ## Full Brand Dump Query
16
+
17
+ ```graphql
18
+ query FullBrand($searchInput: SearchInput!) {
19
+ search(searchInput: $searchInput) {
20
+ ... on Brand {
21
+ id
22
+ names { edges { node { name } } }
23
+ websites { edges { node { website domain } } }
24
+ industries { edges { node { industryDesc industryCode industryType } } }
25
+ revenueQualities { edges { node { issueReason issueSeverity issueDescription } } }
26
+ isMarketables { edges { node { isMarketable } } }
27
+ locationDescriptions { edges { node { locationDescription } } }
28
+ activities { edges { node { activityType } } }
29
+ cardTransactions(first: 1, conditions: { filter: { AND: [
30
+ { EQ: ["period", "12m"] }
31
+ { EQ: ["quantityType", "card_revenue_amount"] }
32
+ { EQ: ["rank", 0] }
33
+ { IS_NULL: ["platformBrandId"] }
34
+ ] } }) {
35
+ edges { node { projectedQuantity rawQuantity periodStartDate periodEndDate } }
36
+ }
37
+ legalEntities(first: 10) {
38
+ edges {
39
+ node {
40
+ names { edges { node { name } } }
41
+ types { edges { node { type } } }
42
+ tins { edges { node { tin } } }
43
+ }
44
+ }
45
+ }
46
+ operatingLocations(first: 10) {
47
+ pageInfo { hasNextPage endCursor }
48
+ edges {
49
+ node {
50
+ names { edges { node { name } } }
51
+ addresses(first: 1) { edges { node { fullAddress } } }
52
+ operatingStatuses(first: 1) { edges { node { operatingStatus } } }
53
+ phoneNumbers(first: 1) { edges { node { phoneNumber } } }
54
+ }
55
+ }
56
+ }
57
+ }
58
+ }
59
+ }
60
+ ```
61
+
62
+ ```json
63
+ {
64
+ "searchInput": { "name": "Warby Parker", "entityType": "BRAND" }
65
+ }
66
+ ```
67
+
68
+ ---
69
+
70
+ ## Extending the Dump
71
+
72
+ Use the **Pagination Template** (`references/pagination_template.py`) to fetch more of any connection. For example, to get all operating locations:
73
+
74
+ 1. Run the query above to get the first page
75
+ 2. Check `operatingLocations.pageInfo.hasNextPage`
76
+ 3. If true, use the pagination template with `operatingLocations(first: 100, after: $cursor)`
77
+
78
+ ### Additional Fields You Can Add
79
+
80
+ | Connection | Useful Fields |
81
+ |---|---|
82
+ | `operatingLocations → cardTransactions` | Per-location revenue (no `platformBrandId` filter needed at OL level) |
83
+ | `operatingLocations → reviewSummaries` | `reviewScoreAvg`, `reviewCount` |
84
+ | `operatingLocations → technologiesUseds` | Technology stack |
85
+ | `operatingLocations → ranks` | Ranking data |
86
+ | `legalEntities → registeredEntities` | Formation year, entity type, registrations |
87
+ | `legalEntities → bankruptcies` | Bankruptcy records |
88
+
89
+ ---
90
+
91
+ ## Common Mistakes to Avoid
92
+
93
+ 1. **Forgetting `IS_NULL: ["platformBrandId"]`** on brand card transactions — revenue inflated 2x-5x
94
+ 2. **Requesting `totalCount`** on connections — causes HTTP 400. Use `hasNextPage` instead
95
+ 3. **Querying `cardTransactions` without filters** — returns hundreds of records. Always filter by `period`, `quantityType`, and `rank`
@@ -0,0 +1,146 @@
1
+ # Derived Attributes: @coalesce and @skip
2
+
3
+ The V2 API supports derived attributes — virtual fields computed from multiple traversal paths.
4
+
5
+ ## Key Concepts
6
+
7
+ | Directive | Purpose |
8
+ |---|---|
9
+ | `_fn @coalesce(refs: [...])` | Returns the **first non-null value** from an ordered list of traversal paths |
10
+ | `@skip(if: true)` | Declares a traversal path for `@coalesce` without returning it in the response |
11
+
12
+ **How it works:**
13
+ 1. `_fn @coalesce(refs: ["path1", "path2"])` — try path1 first, if null try path2
14
+ 2. Each `ref` is a dot-delimited path (e.g., `"legalEntities.edges.0.node.tins.edges.0.node.tin"`)
15
+ 3. Corresponding traversal fields must be in the query — use `@skip(if: true)` to include without cluttering response
16
+ 4. `conditions` and `orderBy` on `@skip`-annotated fields DO affect what `@coalesce` resolves
17
+
18
+ ---
19
+
20
+ ## EIN / TIN Lookup
21
+
22
+ Resolves EIN for an operating location — tries direct legal entity first, falls back to brand's legal entity:
23
+
24
+ ```graphql
25
+ query EINLookup($searchInput: SearchInput!) {
26
+ search(searchInput: $searchInput) {
27
+ ... on OperatingLocation {
28
+ EIN: _fn @coalesce(refs: [
29
+ "legalEntities.edges.0.node.tins.edges.0.node.tin"
30
+ "brands.edges.0.node.legalEntities.edges.0.node.tins.edges.0.node.tin"
31
+ ])
32
+ legalEntities(conditions: { filter: { HAS: ["tins"] } }) @skip(if: true) {
33
+ edges { node { tins(first: 1) { edges { node { tin } } } } }
34
+ }
35
+ brands @skip(if: true) {
36
+ edges { node {
37
+ legalEntities(conditions: { filter: { HAS: ["tins"] } }) {
38
+ edges { node { tins(first: 1) { edges { node { tin } } } } }
39
+ }
40
+ } }
41
+ }
42
+ }
43
+ }
44
+ }
45
+ ```
46
+
47
+ ```json
48
+ {
49
+ "searchInput": {
50
+ "name": "D & D DRYWALL",
51
+ "entityType": "OPERATING_LOCATION",
52
+ "address": { "street1": "2071 WOOD RD", "city": "FULTON", "state": "CA", "postalCode": "95439" }
53
+ }
54
+ }
55
+ ```
56
+
57
+ **Response**: `{ "data": { "search": [{ "EIN": "12-3456789" }] } }`
58
+
59
+ ---
60
+
61
+ ## Formation Year
62
+
63
+ Resolves formation year — tries direct legal entity first, falls back to **earliest** across brand's entities:
64
+
65
+ ```graphql
66
+ query FormationYearLookup($searchInput: SearchInput!) {
67
+ search(searchInput: $searchInput) {
68
+ ... on OperatingLocation {
69
+ formationYear: _fn @coalesce(refs: [
70
+ "legalEntities.edges.0.node.registeredEntities.edges.0.node.formationYear"
71
+ "brands.edges.0.node.legalEntities.edges.0.node.registeredEntities.edges.0.node.formationYear"
72
+ ])
73
+ legalEntities @skip(if: true) {
74
+ edges { node { registeredEntities { edges { node { formationYear } } } } }
75
+ }
76
+ brands @skip(if: true) {
77
+ edges { node {
78
+ legalEntities(conditions: { orderBy: ["registeredEntities.formationYear ASC"] }) {
79
+ edges { node {
80
+ registeredEntities(conditions: { orderBy: ["formationYear ASC"] }) {
81
+ edges { node { formationYear } }
82
+ }
83
+ } }
84
+ }
85
+ } }
86
+ }
87
+ }
88
+ }
89
+ }
90
+ ```
91
+
92
+ ---
93
+
94
+ ## Combined: EIN + Formation Year + Revenue
95
+
96
+ ```graphql
97
+ query LocationProfile($searchInput: SearchInput!, $revCond: ConnectionConditions!) {
98
+ search(searchInput: $searchInput) {
99
+ ... on OperatingLocation {
100
+ names(first: 1) { edges { node { name } } }
101
+ addresses(first: 1) { edges { node { fullAddress city state zip } } }
102
+ operatingStatuses(first: 1) { edges { node { operatingStatus } } }
103
+
104
+ EIN: _fn @coalesce(refs: [
105
+ "legalEntities.edges.0.node.tins.edges.0.node.tin"
106
+ "brands.edges.0.node.legalEntities.edges.0.node.tins.edges.0.node.tin"
107
+ ])
108
+ formationYear: _fn @coalesce(refs: [
109
+ "legalEntities.edges.0.node.registeredEntities.edges.0.node.formationYear"
110
+ "brands.edges.0.node.legalEntities.edges.0.node.registeredEntities.edges.0.node.formationYear"
111
+ ])
112
+
113
+ revenue: cardTransactions(first: 1, conditions: $revCond) {
114
+ edges { node { projectedQuantity periodStartDate periodEndDate } }
115
+ }
116
+
117
+ legalEntities(conditions: { filter: { HAS: ["tins"] } }) @skip(if: true) {
118
+ edges {
119
+ node {
120
+ tins(first: 1) { edges { node { tin } } }
121
+ registeredEntities { edges { node { formationYear } } }
122
+ }
123
+ }
124
+ }
125
+ brands @skip(if: true) {
126
+ edges {
127
+ node {
128
+ legalEntities(conditions: { filter: { HAS: ["tins"] }, orderBy: ["registeredEntities.formationYear ASC"] }) {
129
+ edges {
130
+ node {
131
+ tins(first: 1) { edges { node { tin } } }
132
+ registeredEntities(conditions: { orderBy: ["formationYear ASC"] }) {
133
+ edges { node { formationYear } }
134
+ }
135
+ }
136
+ }
137
+ }
138
+ }
139
+ }
140
+ }
141
+ }
142
+ }
143
+ }
144
+ ```
145
+
146
+ Returns flat response: name, address, status, EIN, formation year, and revenue from a single query.
@@ -0,0 +1,287 @@
1
+ # Discovery Example: Coffee Shops in Specific Zip Codes
2
+
3
+ ## User Intent
4
+
5
+ Find all coffee shops operating in specific zip codes (12983, 12946, 12989) that are currently open.
6
+
7
+ ## Key Concepts
8
+
9
+ - Use `prompt` (NOT `name`) for semantic industry discovery
10
+ - Only works with `entityType: BRAND`
11
+ - Use `conditions.filter` on `SearchInput` to narrow by geography and operating status
12
+ - Field path for zip codes: `operatingLocations.addresses.zip`
13
+ - Field path for operating status: `operatingLocations.operatingStatuses.operatingStatus`
14
+
15
+ ## Variables
16
+
17
+ ```json
18
+ {
19
+ "searchInput": {
20
+ "prompt": "coffee shop",
21
+ "entityType": "BRAND",
22
+ "conditions": {
23
+ "filter": {
24
+ "AND": [
25
+ { "IN": ["operatingLocations.addresses.zip", ["12983", "12946", "12989"]] },
26
+ { "EQ": ["operatingLocations.operatingStatuses.operatingStatus", "Open"] }
27
+ ]
28
+ },
29
+ "limit": 50
30
+ }
31
+ },
32
+ "locConditions": {
33
+ "filter": {
34
+ "IN": ["addresses.zip", ["12983", "12946", "12989"]]
35
+ }
36
+ }
37
+ }
38
+ ```
39
+
40
+ ## GraphQL Query
41
+
42
+ ```graphql
43
+ query DiscoverCoffeeShops($searchInput: SearchInput!, $locConditions: ConnectionConditions) {
44
+ search(searchInput: $searchInput) {
45
+ ... on Brand {
46
+ id
47
+ names: names(first: 1) { edges { node { name } } }
48
+ industries: industries(first: 3) {
49
+ edges {
50
+ node {
51
+ industryDesc
52
+ industryCode
53
+ industryType
54
+ }
55
+ }
56
+ }
57
+ websites: websites { edges { node { website domain } } }
58
+ operatingLocations(first: 500, conditions: $locConditions) {
59
+ edges {
60
+ node {
61
+ names: names(first: 1) { edges { node { name } } }
62
+ addresses: addresses(first: 1) {
63
+ edges {
64
+ node {
65
+ fullAddress
66
+ city
67
+ zip
68
+ }
69
+ }
70
+ }
71
+ phoneNumbers: phoneNumbers(first: 1) {
72
+ edges {
73
+ node {
74
+ phoneNumber
75
+ }
76
+ }
77
+ }
78
+ operatingStatuses: operatingStatuses(first: 1) {
79
+ edges {
80
+ node {
81
+ operatingStatus
82
+ }
83
+ }
84
+ }
85
+ reviewSummaries: reviewSummaries(first: 1) {
86
+ edges {
87
+ node {
88
+ reviewScoreAvg
89
+ reviewCount
90
+ }
91
+ }
92
+ }
93
+ }
94
+ }
95
+ }
96
+ }
97
+ }
98
+ }
99
+ ```
100
+
101
+ ## Expected Output Format
102
+
103
+ **Markdown table with:**
104
+ - Brand name
105
+ - Location name (if different)
106
+ - Address
107
+ - Phone
108
+ - Rating (if available)
109
+ - Status
110
+
111
+ **Example:**
112
+ ```
113
+ Found 8 coffee shop brands operating in zip codes 12983, 12946, 12989:
114
+
115
+ | Brand | Location | Address | Phone | Rating | Status |
116
+ |---|---|---|---|---|---|
117
+ | Starbucks | Starbucks - Lake Placid | 123 Main St, Lake Placid, 12946 | (518) 555-0100 | 4.2 (150 reviews) | Open |
118
+ | Dunkin' | Dunkin' - Saranac Lake | 456 Broadway, Saranac Lake, 12983 | (518) 555-0200 | 4.0 (89 reviews) | Open |
119
+ | ... | ... | ... | ... | ... | ... |
120
+ ```
121
+
122
+ ## Common Mistakes to Avoid
123
+
124
+ 1. ❌ **Using `name` instead of `prompt`**:
125
+ ```json
126
+ { "name": "coffee shop", "entityType": "BRAND" } // WRONG - returns nothing
127
+ ```
128
+ ✅ Use:
129
+ ```json
130
+ { "prompt": "coffee shop", "entityType": "BRAND" } // CORRECT
131
+ ```
132
+
133
+ 2. ❌ **Searching OPERATING_LOCATION by industry**:
134
+ ```json
135
+ { "prompt": "coffee shop", "entityType": "OPERATING_LOCATION" } // WRONG - prompt only works with BRAND
136
+ ```
137
+
138
+ 3. ❌ **Using `postalCode` in filter**:
139
+ ```json
140
+ { "IN": ["operatingLocations.addresses.postalCode", ["12983"]] } // WRONG - field is 'zip'
141
+ ```
142
+ ✅ Use:
143
+ ```json
144
+ { "IN": ["operatingLocations.addresses.zip", ["12983"]] } // CORRECT
145
+ ```
146
+
147
+ 4. ❌ **Lowercase values**:
148
+ ```json
149
+ { "EQ": ["operatingLocations.operatingStatuses.operatingStatus", "open"] } // WRONG
150
+ ```
151
+ ✅ Use:
152
+ ```json
153
+ { "EQ": ["operatingLocations.operatingStatuses.operatingStatus", "Open"] } // CORRECT
154
+ ```
155
+
156
+ ## Variations
157
+
158
+ ### By State Instead of Zip
159
+
160
+ ```json
161
+ {
162
+ "searchInput": {
163
+ "prompt": "coffee shop",
164
+ "entityType": "BRAND",
165
+ "conditions": {
166
+ "filter": {
167
+ "AND": [
168
+ { "EQ": ["operatingLocations.addresses.state", "NY"] },
169
+ { "EQ": ["operatingLocations.operatingStatuses.operatingStatus", "Open"] }
170
+ ]
171
+ },
172
+ "limit": 100
173
+ }
174
+ }
175
+ }
176
+ ```
177
+
178
+ ### By City (Remember: UPPERCASE)
179
+
180
+ ```json
181
+ {
182
+ "searchInput": {
183
+ "prompt": "coffee shop",
184
+ "entityType": "BRAND",
185
+ "conditions": {
186
+ "filter": {
187
+ "AND": [
188
+ { "EQ": ["operatingLocations.addresses.city", "LAKE PLACID"] },
189
+ { "EQ": ["operatingLocations.addresses.state", "NY"] }
190
+ ]
191
+ },
192
+ "limit": 50
193
+ }
194
+ }
195
+ }
196
+ ```
197
+
198
+ ### With Phone Number Requirement
199
+
200
+ ```json
201
+ {
202
+ "searchInput": {
203
+ "prompt": "coffee shop",
204
+ "entityType": "BRAND",
205
+ "conditions": {
206
+ "filter": {
207
+ "AND": [
208
+ { "IN": ["operatingLocations.addresses.zip", ["12983", "12946"]] },
209
+ { "HAS": ["operatingLocations.phoneNumbers"] }
210
+ ]
211
+ },
212
+ "limit": 50
213
+ }
214
+ }
215
+ }
216
+ ```
217
+
218
+ ## Python Execution Template
219
+
220
+ ```bash
221
+ python3 << 'PYEOF'
222
+ import json, urllib.request, os
223
+
224
+ query = '''query DiscoverCoffeeShops($searchInput: SearchInput!, $locConditions: ConnectionConditions) {
225
+ search(searchInput: $searchInput) {
226
+ ... on Brand {
227
+ id
228
+ names: names(first: 1) { edges { node { name } } }
229
+ operatingLocations(first: 500, conditions: $locConditions) {
230
+ edges {
231
+ node {
232
+ names: names(first: 1) { edges { node { name } } }
233
+ addresses: addresses(first: 1) {
234
+ edges { node { fullAddress city zip } }
235
+ }
236
+ phoneNumbers: phoneNumbers(first: 1) {
237
+ edges { node { phoneNumber } }
238
+ }
239
+ operatingStatuses: operatingStatuses(first: 1) {
240
+ edges { node { operatingStatus } }
241
+ }
242
+ }
243
+ }
244
+ }
245
+ }
246
+ }
247
+ }'''
248
+
249
+ variables = {
250
+ "searchInput": {
251
+ "prompt": "coffee shop",
252
+ "entityType": "BRAND",
253
+ "conditions": {
254
+ "filter": {
255
+ "AND": [
256
+ { "IN": ["operatingLocations.addresses.zip", ["12983", "12946", "12989"]] },
257
+ { "EQ": ["operatingLocations.operatingStatuses.operatingStatus", "Open"] }
258
+ ]
259
+ },
260
+ "limit": 50
261
+ }
262
+ },
263
+ "locConditions": {
264
+ "filter": { "IN": ["addresses.zip", ["12983", "12946", "12989"]] }
265
+ }
266
+ }
267
+
268
+ payload = json.dumps({'query': query, 'variables': variables})
269
+ req = urllib.request.Request(
270
+ 'https://api.enigma.com/graphql',
271
+ data=payload.encode(),
272
+ headers={'content-type': 'application/json', 'x-api-key': os.environ['ENIGMA_API_KEY']}
273
+ )
274
+ try:
275
+ resp = urllib.request.urlopen(req)
276
+ data = json.loads(resp.read())
277
+ if 'errors' in data:
278
+ for err in data['errors']:
279
+ print(f'GraphQL Error: {err.get("message", err)}')
280
+ else:
281
+ print(json.dumps(data, indent=2))
282
+ except urllib.error.HTTPError as e:
283
+ print(f'HTTP {e.code}: {e.read().decode()}')
284
+ except KeyError:
285
+ print('ERROR: ENIGMA_API_KEY not set. Run: export ENIGMA_API_KEY=your_key')
286
+ PYEOF
287
+ ```