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.
- enigma_api_client/__init__.py +16 -0
- enigma_api_client/client.py +134 -0
- enigma_api_client/client_inject_id_and_typename_helper.py +248 -0
- enigma_api_client/client_inject_urls_helper.py +26 -0
- enigma_api_client/plugins/.DS_Store +0 -0
- enigma_api_client/plugins/enigma-api/.claude-plugin/plugin.json +8 -0
- enigma_api_client/plugins/enigma-api/README.md +82 -0
- enigma_api_client/plugins/enigma-api/harness/conftest.py +42 -0
- enigma_api_client/plugins/enigma-api/harness/test_linter.py +863 -0
- enigma_api_client/plugins/enigma-api/harness/test_queries.py +143 -0
- enigma_api_client/plugins/enigma-api/harness/test_skill_rules.py +351 -0
- enigma_api_client/plugins/enigma-api/pyproject.toml +9 -0
- enigma_api_client/plugins/enigma-api/scripts/__pycache__/lint_query.cpython-313.pyc +0 -0
- enigma_api_client/plugins/enigma-api/scripts/__pycache__/query_validator.cpython-313.pyc +0 -0
- enigma_api_client/plugins/enigma-api/scripts/__pycache__/query_validator.cpython-314.pyc +0 -0
- enigma_api_client/plugins/enigma-api/scripts/generate_report.py +384 -0
- enigma_api_client/plugins/enigma-api/scripts/lint_query.py +712 -0
- enigma_api_client/plugins/enigma-api/scripts/query_validator.py +352 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/SKILL.md +620 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/brand/03_brand_profile.md +163 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/brand/13_brand_dump.md +95 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/derived/07_coalesce_ein_formation.md +146 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/discovery/01_coffee_shops_zip.md +287 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/discovery/11_ol_industry_discovery.md +116 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/export/08_segment_export.md +96 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/kyb/02_officers_lookup.md +366 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/kyb/10_kyb_verify.md +176 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/legal_entity/09_legal_entity_profile.md +97 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/locations/05_brand_locations_by_state.md +120 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/person_search/04_find_person_companies.md +160 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/revenue/06_brand_revenue.md +176 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/risk/12_risk_signals.md +118 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/references/card_transactions.md +91 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/references/field_corrections.json +106 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/references/filter_syntax.md +203 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/references/naics_2022_mapping.json +184 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/references/pagination_template.py +115 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/schema.graphql +44971 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/scripts/test_examples.py +1122 -0
- enigma_api_client/plugins/enigma-api/skills/enigma-graphql/scripts/validate_query.py +177 -0
- enigma_api_client/plugins/enigma-api/test-cases/graphql-test-cases.md +196 -0
- enigma_api_client/plugins/enigma-api/tests/accuracy_cases.csv +116 -0
- enigma_api_client/plugins/enigma-api/tests/applicability_review.csv +64 -0
- enigma_api_client/plugins/enigma-api/tests/parallel-ground-truth.csv +101 -0
- enigma_api_client/plugins/enigma-api/tests/run_tests.sh +320 -0
- enigma_api_client/plugins/enigma-api/tests/test_cases.yaml +213 -0
- enigma_api_client/plugins/enigma-api/tests/validation_cases.csv +101 -0
- enigma_api_client/py.typed +0 -0
- enigma_api_client/query_router/__init__.py +3 -0
- enigma_api_client/query_router/geo.py +121 -0
- enigma_api_client/query_router/templates.py +475 -0
- enigma_api_client/strategies/__init__.py +16 -0
- enigma_api_client/strategies/agent.py +63 -0
- enigma_api_client/strategies/base.py +15 -0
- enigma_api_client/strategies/generative.py +143 -0
- enigma_api_client/strategies/llm_provider.py +137 -0
- enigma_api_client/strategies/service.py +103 -0
- enigma_api_client/strategies/template.py +189 -0
- enigma_api_client-0.3.1.dist-info/METADATA +257 -0
- enigma_api_client-0.3.1.dist-info/RECORD +63 -0
- enigma_api_client-0.3.1.dist-info/WHEEL +5 -0
- enigma_api_client-0.3.1.dist-info/licenses/LICENSE +201 -0
- 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.
|
enigma_api_client/plugins/enigma-api/skills/enigma-graphql/examples/discovery/01_coffee_shops_zip.md
ADDED
|
@@ -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
|
+
```
|