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

enigma_api_client/__init__.py

@@ -0,0 +1,16 @@
+"""enigma_api_client - Enigma's Public API SDK"""
+
+from typing import Sequence
+
+from enigma_api_client.client import Client, ClientConfig, SearchResponse, EnigmaClientException, EnigmaClientErrorCode
+from enigma_api_client.strategies.base import QueryStrategy
+
+__version__ = "0.3.1"
+__all__: Sequence[str] = [
+    "Client",
+    "ClientConfig",
+    "SearchResponse",
+    "EnigmaClientException",
+    "EnigmaClientErrorCode",
+    "QueryStrategy",
+]

enigma_api_client/client.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, TYPE_CHECKING
+
+import httpx
+
+from enigma_api_client.client_inject_id_and_typename_helper import inject_fields_in_query
+from enigma_api_client.client_inject_urls_helper import inject_urls
+
+if TYPE_CHECKING:
+    from enigma_api_client.strategies.base import QueryStrategy
+
+
+class EnigmaClientErrorCode(Enum):
+    INVALID_QUERY = "INVALID_GRAPHQL_QUERY"
+    INVALID_VARIABLES = "INVALID_VARIABLES"
+    GENERATE_QUERY_CALLBACK_NOT_CONFIGURED = "GENERATE_QUERY_CALLBACK_NOT_CONFIGURED"
+
+class EnigmaClientException(Exception):
+    def __init__(self, error_code: EnigmaClientErrorCode, message: str):
+        self.error_code = error_code
+        super().__init__(message)
+
+
+@dataclass
+class ClientConfig:
+    # Enigma API key
+    enigma_api_key: str
+
+    # Pluggable query strategy for generating GraphQL from natural language prompts.
+    # Available strategies: ServiceStrategy (default), TemplateStrategy, GenerativeStrategy, AgentStrategy
+    # Default: ServiceStrategy (delegates to the Enigma Semantic Transformation Service)
+    query_strategy: QueryStrategy | None = None
+
+    # If True, automatically downloads new skills from Enigma at client initialization and every 24 hours.
+    # If False, will only use static skills packaged with the client.
+    # Default: True
+    auto_download_new_skills: bool = True
+
+    # Enigma GraphQL API endpoint
+    url: str = "https://api.enigma.com/graphql"
+
+    # Auto Inject ID and typename in query. This is required in order to get __url fields in the response.
+    auto_inject_id_and_typename: bool = True
+
+
+@dataclass
+class SearchResponse:
+    status_code: int
+    errors: Any = None
+    data: dict[str, Any] | None = None
+    extensions: Any = None
+
+    def is_success(self) -> bool:
+        return 200 <= self.status_code <= 299 and not self.errors
+
+class Client:
+    def __init__(self, config: ClientConfig):
+        self._config = config
+
+    async def search(self, *, prompt: str | None = None, query: str | None = None, variables: dict[str, Any] | None = None) -> SearchResponse:
+        """
+        Executes a GraphQL request against Enigma GraphQL API
+
+        :param prompt: will use prompt to generate a query using the configured query_strategy.
+            If query_strategy is NOT configured on ClientConfig, an exception with the error code
+            "GENERATE_QUERY_CALLBACK_NOT_CONFIGURED" will be raised.
+            Cannot be used together with query or variables parameters.
+        :param query: A string representing the GraphQL query. Cannot be used together with the prompt parameter.
+        :param variables: A dict representing the GraphQL variables. Cannot be used together with the prompt parameter.
+        :return: `SearchResponse` containing the response of the search.
+        """
+
+        if prompt and (query or variables):
+            raise EnigmaClientException(EnigmaClientErrorCode.INVALID_QUERY, "Cannot provide both query/variable and prompt parameters")
+
+        if not prompt and not query and not variables:
+            raise EnigmaClientException(EnigmaClientErrorCode.INVALID_QUERY, "Invalid query. Must provide either query/variable or prompt parameters")
+
+        if prompt is not None:
+            strategy = self._config.query_strategy
+            if strategy is None:
+                from enigma_api_client.strategies.service import ServiceStrategy
+                strategy = ServiceStrategy(enigma_api_key=self._config.enigma_api_key, query_strategy="template")
+                self._config.query_strategy = strategy
+            query, variables = await strategy.generate_query(prompt)
+
+        return await self._execute_graphql_request(query, variables)
+
+    async def _execute_graphql_request(self, query: str | None, variables: dict[str, Any] | None) -> SearchResponse:
+        headers = {
+            "Content-Type": "application/json",
+            "x-api-key": self._config.enigma_api_key or os.getenv("ENIGMA_API_KEY", ""),
+        }
+
+        payload = {
+            "query": query,
+            "variables": variables or {},
+        }
+        if self._config.auto_inject_id_and_typename:
+            payload = self._inject_id_and_typename_whereever_needed(payload)
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                self._config.url,
+                json=payload,
+                headers=headers,
+                timeout=30.0
+            )
+        status_code = response.status_code
+        resp_json = response.json()
+
+        return SearchResponse(
+            data=inject_urls(resp_json.get("data")),
+            errors=resp_json.get("errors"),
+            extensions=resp_json.get("extensions"),
+            status_code=status_code
+        )
+
+    def _inject_id_and_typename_whereever_needed(self, payload: dict[str, Any]) -> dict[str, Any]:
+        query = payload.get("query")
+        if not query or not isinstance(query, str):
+            return payload
+        try:
+            new_query = inject_fields_in_query(query)
+        except Exception:
+            return payload  # never break on a parse failure
+        if new_query == query:
+            return payload
+        return {**payload, "query": new_query}
+

enigma_api_client/client_inject_id_and_typename_helper.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from typing import Any
+
+# ── GraphQL field injector ─────────────────────────────────────────────────────
+#
+# Parses the raw query string and injects `id` and `__typename` into every
+# selection set that opens an inline fragment (`... on TypeName { … }`) or a
+# connection node (`edges { node { … } }`), but only when those fields are not
+# already present.  All other selection sets are left untouched.
+#
+# Implementation is a hand-rolled tokeniser + single-pass walker so that we have
+# zero extra dependencies.  The original query string is only modified at the
+# exact character positions that need an injection; everything else is preserved
+# verbatim (whitespace, comments, aliases, arguments, etc.).
+
+# Token kinds: 'ws' | 'comment' | 'string' | 'spread' | 'punct' | 'name' | 'num'
+_Token = tuple[str, str, int]   # (kind, value, end_pos)  – end_pos is exclusive
+
+
+def _gql_tokenize(query: str) -> list[_Token]:
+    """Tokenise a GraphQL query string into (kind, value, end_pos) triples."""
+    tokens: list[_Token] = []
+    i = 0
+    n = len(query)
+    while i < n:
+        c = query[i]
+        # Block string  """…"""
+        if query[i:i+3] == '"""':
+            j = query.find('"""', i + 3)
+            j = (j + 3) if j != -1 else n
+            tokens.append(('string', query[i:j], j)); i = j
+        # Regular string  "…"
+        elif c == '"':
+            j = i + 1
+            while j < n:
+                if query[j] == '\\': j += 2
+                elif query[j] == '"': j += 1; break
+                else: j += 1
+            tokens.append(('string', query[i:j], j)); i = j
+        # Line comment  #…
+        elif c == '#':
+            j = query.find('\n', i); j = j if j != -1 else n
+            tokens.append(('comment', query[i:j], j)); i = j
+        # Insignificant whitespace and commas
+        elif c in ' \t\n\r,':
+            j = i + 1
+            while j < n and query[j] in ' \t\n\r,': j += 1
+            tokens.append(('ws', query[i:j], j)); i = j
+        # Fragment spread operator
+        elif query[i:i+3] == '...':
+            tokens.append(('spread', '...', i + 3)); i += 3
+        # Single-character punctuation
+        elif c in '{}()[]!$:=@|&':
+            tokens.append(('punct', c, i + 1)); i += 1
+        # Identifiers  [_A-Za-z][_A-Za-z0-9]*
+        elif c.isalpha() or c == '_':
+            j = i + 1
+            while j < n and (query[j].isalnum() or query[j] == '_'): j += 1
+            tokens.append(('name', query[i:j], j)); i = j
+        # Numbers (treated as opaque)
+        elif c.isdigit() or (c == '-' and i + 1 < n and query[i + 1].isdigit()):
+            j = i + 1
+            while j < n and (query[j].isdigit() or query[j] in '.eE+-'): j += 1
+            tokens.append(('num', query[i:j], j)); i = j
+        else:
+            tokens.append(('num', c, i + 1)); i += 1
+    return tokens
+
+
+def _selection_field_names(tokens: list[_Token], brace_idx: int) -> set[str]:
+    """
+    Return the set of field names selected at depth-1 inside the selection set
+    opened by tokens[brace_idx] (which must be a '{' punct token).
+
+    Handles: nested braces, argument lists (parens), inline fragments (skipped),
+    named fragment spreads (skipped), aliases (the alias is skipped; the actual
+    field name is collected).
+    """
+    n = len(tokens)
+    depth = 0       # brace depth relative to the opening '{'
+    paren_depth = 0
+    fields: set[str] = set()
+    # Last two non-ws tokens seen (for pattern matching)
+    recent: list[tuple[str, str]] = []
+
+    def push(k: str, v: str) -> None:
+        recent.append((k, v))
+        if len(recent) > 2:
+            recent.pop(0)
+
+    i = brace_idx
+    while i < n:
+        kind, value, _ = tokens[i]
+
+        if kind in ('ws', 'comment'):
+            i += 1; continue
+
+        # Skip everything inside argument lists
+        if paren_depth > 0:
+            if kind == 'punct' and value == '(': paren_depth += 1
+            elif kind == 'punct' and value == ')': paren_depth -= 1
+            i += 1; continue
+
+        if kind == 'punct' and value == '(':
+            paren_depth += 1; i += 1; continue
+
+        if kind == 'punct' and value == '{':
+            depth += 1; push(kind, value); i += 1; continue
+
+        if kind == 'punct' and value == '}':
+            depth -= 1
+            if depth == 0: break
+            push(kind, value); i += 1; continue
+
+        if depth == 1 and kind == 'name':
+            prev = recent[-1] if recent else None
+            # Skip: type name after 'on'  (... on TypeName)
+            if prev == ('name', 'on'):
+                push(kind, value); i += 1; continue
+            # Skip: named fragment reference  ...FragmentName
+            if prev == ('spread', '...'):
+                push(kind, value); i += 1; continue
+            # Skip: alias name  (alias: fieldName — collect fieldName on next iter via ':')
+            j = i + 1
+            next_tok: tuple[str, str] | None = None
+            while j < n:
+                if tokens[j][0] not in ('ws', 'comment'):
+                    next_tok = (tokens[j][0], tokens[j][1]); break
+                j += 1
+            if next_tok == ('punct', ':'):
+                push(kind, value); i += 1; continue
+            # Actual field name
+            fields.add(value)
+
+        push(kind, value)
+        i += 1
+
+    return fields
+
+
+def _classify_opening_brace(
+    recent_sig: list[tuple[str, str]],
+    ctx_stack: list[str],
+) -> str:
+    """
+    Classify the context of an opening '{' given the last few significant
+    (non-ws, non-comment) tokens that preceded it and the current context stack.
+
+    Returns one of: 'inline_fragment' | 'node_in_edges' | 'edges' | 'other'
+    """
+    r = recent_sig  # most-recent last
+
+    # Inline fragment:  ... on TypeName  [optional directives]  {
+    # We scan backwards for  (name, 'on') preceded (somewhere) by (spread, '...')
+    for idx in range(len(r) - 1, -1, -1):
+        if r[idx] == ('name', 'on'):
+            # Is there a spread '...' anywhere before this 'on' in recent?
+            if any(t == ('spread', '...') for t in r[:idx]):
+                return 'inline_fragment'
+            break  # 'on' not preceded by spread — not an inline fragment
+
+    # Find the last field name in recent (ignoring structural punctuation and 'on')
+    last_field: str | None = None
+    for kind, value in reversed(r):
+        if kind == 'name' and value != 'on':
+            last_field = value
+            break
+        if kind == 'punct' and value in ('{', '}'):
+            break  # structural boundary — stop looking
+
+    if last_field == 'node' and ctx_stack and ctx_stack[-1] == 'edges':
+        return 'node_in_edges'
+    if last_field == 'edges':
+        return 'edges'
+    return 'other'
+
+
+def _find_injections(query: str) -> list[tuple[int, list[str]]]:
+    """
+    Return a list of (insert_pos, fields) where insert_pos is the character
+    position immediately after a '{' that opens an injection-target selection
+    set, and fields is the subset of ['id', '__typename'] not already present.
+    """
+    tokens = _gql_tokenize(query)
+    injections: list[tuple[int, list[str]]] = []
+    ctx_stack: list[str] = []   # context for each open '{'
+    paren_depth = 0
+    recent_sig: list[tuple[str, str]] = []  # last ≤4 significant tokens
+
+    def push_sig(k: str, v: str) -> None:
+        recent_sig.append((k, v))
+        if len(recent_sig) > 4:
+            recent_sig.pop(0)
+
+    for idx, (kind, value, end_pos) in enumerate(tokens):
+        if kind in ('ws', 'comment'):
+            continue
+
+        # Inside argument lists — track depth but don't update context
+        if paren_depth > 0:
+            if kind == 'punct' and value == '(': paren_depth += 1
+            elif kind == 'punct' and value == ')': paren_depth -= 1
+            # Intentionally NOT calling push_sig here so argument content
+            # does not pollute the recent-token window used for classification.
+            continue
+
+        if kind == 'punct' and value == '(':
+            paren_depth += 1
+            continue  # don't push to recent_sig either
+
+        if kind == 'punct' and value == '{':
+            ctx = _classify_opening_brace(recent_sig, ctx_stack)
+            if ctx in ('inline_fragment', 'node_in_edges'):
+                existing = _selection_field_names(tokens, idx)
+                to_inject = [f for f in ('id', '__typename') if f not in existing]
+                if to_inject:
+                    injections.append((end_pos, to_inject))
+            ctx_stack.append(ctx)
+            push_sig(kind, value)
+            continue
+
+        if kind == 'punct' and value == '}':
+            if ctx_stack:
+                ctx_stack.pop()
+            push_sig(kind, value)
+            continue
+
+        push_sig(kind, value)
+
+    return injections
+
+
+def inject_fields_in_query(query: str) -> str:
+    """
+    Return a copy of *query* with `id` and `__typename` injected into every
+    inline-fragment and edge-node selection set that is missing them.
+    Injections are applied in reverse position order to keep earlier offsets valid.
+    """
+    injections = _find_injections(query)
+    if not injections:
+        return query
+    # Sort descending so we insert from the back, preserving earlier positions.
+    injections.sort(key=lambda x: x[0], reverse=True)
+    result = query
+    for pos, fields in injections:
+        result = result[:pos] + ' ' + ' '.join(fields) + result[pos:]
+    return result

enigma_api_client/client_inject_urls_helper.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+_PERMALINK_TYPES_TO_PATH = {
+    "OperatingLocation": "operating-location",
+    "Brand": "brand",
+    "LegalEntity": "legal-entity",
+    "Person": "person",
+}
+_PERMALINK_BASE = "https://console.enigma.com/explore/profile"
+
+
+def inject_urls(node: Any) -> Any:
+    """Recursively walk a GraphQL response node and add ``__url`` to any object
+    that has both ``__typename`` and ``id`` and whose type is in _PERMALINK_TYPES."""
+    if isinstance(node, dict):
+        typename = node.get("__typename")
+        entity_id = node.get("id")
+        result = {k: inject_urls(v) for k, v in node.items()}
+        if typename and entity_id is not None and (path := _PERMALINK_TYPES_TO_PATH.get(typename)):
+            result["__url"] = f"{_PERMALINK_BASE}/{path}/{entity_id}"
+        return result
+    if isinstance(node, list):
+        return [inject_urls(item) for item in node]
+    return node

enigma_api_client/plugins/enigma-api/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "enigma-api",
+  "description": "Query Enigma APIs — GraphQL business data, KYB verification, sanctions screening, and government archive records",
+  "version": "1.1.0",
+  "author": {
+    "name": "Jarrod Parker"
+  }
+}

enigma_api_client/plugins/enigma-api/README.md

@@ -0,0 +1,82 @@
+# enigma-api
+
+Query Enigma APIs — GraphQL business data, KYB verification, sanctions screening, and government archive records. Claude automatically uses the appropriate skill based on what you're asking about.
+
+## Installation
+
+```
+/plugin install enigma-api@enigma-plugins
+```
+
+## Prerequisites
+
+Set your Enigma API key in your environment:
+
+```bash
+export ENIGMA_API_KEY=your_api_key_here
+```
+
+Get your API key from [console.enigma.com](https://console.enigma.com/).
+
+## Skills
+
+### enigma-graphql
+
+Query the Enigma GraphQL API for business intelligence data — brands, operating locations, legal entities, corporate structure, and more.
+
+```
+"Look up Starbucks in the Enigma API"
+"Find all operating locations for Target in California"
+"Search for the legal entity behind Acme Corp"
+"Get the corporate structure for Nike"
+```
+
+### enigma-kyb
+
+Verify businesses using the KYB (Know Your Business) API — check registration status, name verification, and due diligence.
+
+```
+"Verify Enigma Technologies Inc as a business"
+"Run KYB on Acme Corp in New York"
+"Check if this business is registered: Smith & Sons LLC, 123 Main St, Chicago IL"
+```
+
+### enigma-screen
+
+Screen persons and organizations against sanctions, PEP, and watchlist databases.
+
+```
+"Screen Vladimir Putin for sanctions"
+"Check if Acme International Trading is on any watchlists"
+"Run a sanctions screening on John Smith"
+"Screen this text for sanctioned entities: 'Payment to Bank of Russia'"
+```
+
+### enigma-gov-archive
+
+Search government archive public records — violations, licenses, liens, legal actions, debarments, and contracts.
+
+```
+"Search government records for Blue Bottle Coffee"
+"Find any violations or liens for Acme Corp"
+"Check government archives for Smith Construction LLC"
+```
+
+## Supported Entity Types (GraphQL)
+
+| Type | What it represents |
+|---|---|
+| Brand | A business brand/company — industries, locations, revenue signals |
+| Operating Location | A physical business location — address, phone, status, reviews |
+| Legal Entity | A registered legal entity — officers, TINs, filings, registrations |
+| Person | A person — associated companies, officer roles, registrations |
+
+## Documentation
+
+- [Enigma API Docs](https://documentation.enigma.com/)
+- [GraphQL Guide](https://documentation.enigma.com/guides/graphql)
+- [API Playground](https://console.enigma.com/explore/graphql)
+
+## Author
+
+Jarrod Parker

enigma_api_client/plugins/enigma-api/harness/conftest.py

@@ -0,0 +1,42 @@
+# ABOUTME: Shared pytest fixtures for the enigma-api test harness
+# ABOUTME: Provides skill_path, skill_content, and graphql_blocks fixtures
+
+"""
+Shared pytest fixtures for the Enigma GraphQL test harness.
+
+Fixtures:
+    skill_path  — absolute path to SKILL.md
+    skill_content — full text of SKILL.md
+    graphql_blocks — list of {query, variables, section, line_number} dicts
+"""
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+# Add scripts/ to path so we can import lint_query and query_validator
+PLUGIN_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(PLUGIN_ROOT / "scripts"))
+
+
+@pytest.fixture(scope="session")
+def skill_path() -> Path:
+    """Path to the SKILL.md file."""
+    p = PLUGIN_ROOT / "skills" / "enigma-graphql" / "SKILL.md"
+    assert p.exists(), f"SKILL.md not found at {p}"
+    return p
+
+
+@pytest.fixture(scope="session")
+def skill_content(skill_path: Path) -> str:
+    """Full text content of SKILL.md."""
+    return skill_path.read_text(encoding="utf-8")
+
+
+@pytest.fixture(scope="session")
+def graphql_blocks(skill_content: str) -> list[dict]:
+    """All GraphQL code blocks extracted from SKILL.md with section context."""
+    from query_validator import extract_graphql_blocks_with_context
+    return extract_graphql_blocks_with_context(skill_content)