Developer Program

​

• What is the Ekyam SDK?

​

• Purpose of Ekyam’s SDK

1. Build Custom Connectors: The custom connectors will be able to seamlessly integrate any proprietary or niche data source (ERP, warehouse system, or a marketing tool) into the Ekyam system.  

2. Create Intelligent Automations: The custom connectors are designed  by developers to execute complex workflows, thereby leveraging the full context of Retail Knowledge Graph (RKG) and Universal Ledger to build custom logics. 

3. Develop Standalone Retail Applications: The developers will build entirely new applications (advance analytics dashboards, custom merchandising tools etc) that use Ekyam as their intelligent back-end for real-time, unified retail data. 

• Data Normalization: Standardize disparate data formats into a consistent schema.
• Data Validation: Implement rules to ensure data quality and integrity.
• Code and Unit Conversions: Assists in converting product codes, measurement units or currency formats.

​

• Core Components of the SDK

1. SecureConnectionManager: It handles the secure storage and management of credentials that are needed to connect to external systems. A developer declares the authentication type ( OAuth 2.0, API Key). This component efficiently handles the complex token refresh loops, signature generation and secure vaulting so credentials are never exposed in the connector code. 

2. DataMapper (Reader and Writer Engine):  This component translates data from any external format to the Ekyam Internal Data standards. A DataMapper defines a rule, ensuring that the data is understood by the system each time. A developer may use the DataMapper to define how the data from a custom source needs to be read and understood by Ekyam; and how Ekyam’s standard data should be written back to the system in its required format.
3. Schema and Ontology Toolkit: This toolkit works with the DataMapper. Developers use this to ensure the data their custom application reads or writes is perfectly structured to become part of the Ekyam Retail Knowledge Graph. The DataMapper translates data to be used by Retail Knowledge Graph. 
4. RetailTransformationEngine: The developers can use these helpers during the mapping process to add intelligence. It can be used for: 
   • Hierarchical Category Mapping: This is used for intelligently mapping a flat category string from a legacy system to Ekyam’s structured multi-level category model. 
   • Sentiment Analysis: This analysis takes the unstructured text like a review or support email to return a structured response.  
5. AIEnrichmentClient: This component provides a direct interface for developers to send data to Ekyam’s AI services for processing, allowing the custom connectors or applications to think beyond simple data transformation. For instance: If a developer wants to send a list of basic products to the client, it can use Ekyam’s AI to write a description. Also, a developer can pass unstructured customer review text to the client, and the AI can analyze this and return with a structured object. The new structured data can then be used for advanced analytics. 
6. WorkflowManager: This component allows developers to create, trigger and manage Ekyam Workflows. A custom application can be used to build a new automation process to trigger an existing workflow with a specific data payload. 
7. EventLogClient: This component gives the access to the developer to build custom monitoring dashboards or external alerting systems to track integrations and provides a record of every transaction that flows through the platform.
8. ExceptionhandlingFramework:
   It is a crucial component for building connectors. Ekyam’s SDK provides a set of specific, pre-defined exception classes (eg, Authentication Error, Data Validation Error).  When a developer raises these exceptions, the Ekyam platform can intelligently handle the failure by initiating an automatic retry or creating a detailed alert for the user.

​

• Why build with the Ekyam SDK?

1. Access a Unified View of Retail Data: The SDK provides a simple interface to the Ekyam Universal Ledger. This implies that the application can instantly access standardized real-time data from across the entire retail landscape (ERP, WMS, PIM, OMS, CRM, IDocs, EDI etc), without handling the complexity of connecting to each source individually. 

2. Leveraging the Retail Knowledge Graph (RKG): This is an intelligent semantic model that is used by Ekyam SDK. The SDK provides high-level objects and methods to query the RKG, allowing the users to understand the relationships and meaning between products, inventory, orders, and customers in a simplified manner than using a complex or a custom logic. 

3. Directly integrating with the AI and Agentic Framework: Ekyam’s SDK methods allows the custom code to directly invoke Ekyam’s AI ecosystem. This ecosystem is built on a technical stack that includes MCP, Langchain, Multiple LLMs, and the Ekyam RKG- these are designed with a natural language prompt with a retail-specific context. The custom components become a part of the Ekyam’s AI agents. 

4. Build Custom Connectors to Unify the Entire Ecosystem: The Ekyam SDK is the primary tool for integrating diverse and proprietary systems. Building a connector transforms any data source—from legacy to modern—into intelligent, actionable data within the Ekyam platform.

​

• The Custom Connector Lifecycle

ekyam-cli init --connector "My-Custom-ERP"

# In config.py
from pydantic import BaseModel, Field, SecretStr

class MyCustomERPConfig(BaseModel):
    server_address: str = Field(
        ...,
        title="Server Address",
        description="The full URL of the ERP API. e.g., https://api.my-erp.com"
    )
    api_key: SecretStr = Field(
        ...,
        title="API Key",
        description="Your unique API key for authenticating with the ERP."
    )

# In your read() or write() method
from ekyam_sdk import exceptions
import requests

try:
    response = requests.get(url, headers=auth_headers, timeout=10)
    response.raise_for_status() # Raises an exception for bad status codes (4xx or 5xx)
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 401:
        raise exceptions.AuthenticationError("Invalid API Key provided.")
    elif e.response.status_code == 429:
        raise exceptions.RateLimitError("External API rate limit exceeded.")
    else:
        raise exceptions.ApiError(f"API Error: {e.response.text}")
except requests.exceptions.RequestException as e:
    raise exceptions.ApiConnectionError(f"Connection failed: {e}")