interloper-assets 0.2.0__tar.gz

interloper_assets-0.2.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.3
+Name: interloper-assets
+Version: 0.2.0
+Summary: Interloper Assets
+Author: Guillaume Onfroy
+Author-email: Guillaume Onfroy <guillaume@digitlcloud.com>
+Requires-Dist: interloper-core
+Requires-Dist: interloper-pandas
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: tenacity>=9.1.4
+Requires-Dist: bingads>=13.0.24.1 ; extra == 'bing'
+Requires-Dist: facebook-business>=20.0.0 ; extra == 'facebook'
+Requires-Dist: google-api-python-client>=2.167.0 ; extra == 'google'
+Requires-Python: >=3.10
+Provides-Extra: bing
+Provides-Extra: facebook
+Provides-Extra: google
+Description-Content-Type: text/markdown
+
+# interloper-assets
+
+Asset definitions and source registry for Interloper.

interloper_assets-0.2.0/README.md

@@ -0,0 +1,3 @@
+# interloper-assets
+
+Asset definitions and source registry for Interloper.

interloper_assets-0.2.0/pyproject.toml

@@ -0,0 +1,53 @@
+# ###############
+# PROJECT / UV
+# ###############
+[project]
+name = "interloper-assets"
+version = "0.2.0"
+description = "Interloper Assets"
+readme = "README.md"
+authors = [{ name = "Guillaume Onfroy", email = "guillaume@digitlcloud.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "interloper-core",
+    "interloper-pandas",
+    "httpx>=0.28.1",
+    "pandas>=2.3.3",
+    "tenacity>=9.1.4",
+]
+
+[project.optional-dependencies]
+bing = ["bingads>=13.0.24.1"]
+google = ["google-api-python-client>=2.167.0"]
+facebook = ["facebook-business>=20.0.0"]
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+interloper-core = { workspace = true }
+interloper-pandas = { workspace = true }
+
+# ###############
+# RUFF
+# ###############
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+extend-select = ["E", "I", "UP", "ANN001", "ANN201", "ANN202"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "F403"]
+"**/schemas/**" = ["E501"]
+"tests/**" = ["ANN", "F811"]
+
+# ###############
+# PYRIGHT
+# ###############
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "basic"
+reportMissingParameterType = true
+ignore = ["libs/**", "tests/**", "scripts/**"]

interloper_assets-0.2.0/src/interloper_assets/__init__.py

@@ -0,0 +1,85 @@
+import interloper as il
+from interloper.errors import SourceError
+
+from interloper_assets.adservice.source import Adservice, AdserviceConfig
+from interloper_assets.adup.source import Adup, AdupConfig
+from interloper_assets.amazon_ads.source import AmazonAds, AmazonAdsConfig
+from interloper_assets.amazon_selling_partner.source import AmazonSellingPartner
+from interloper_assets.awin.source import Awin
+from interloper_assets.bing_ads.source import BingAds
+from interloper_assets.campaign_manager_360.source import CampaignManager360
+from interloper_assets.campaign_performance_analysis.source import CampaignPerformanceAnalysis
+from interloper_assets.criteo.source import Criteo
+from interloper_assets.demo.source import DemoConfig, DemoSource
+from interloper_assets.display_video_360.source import DisplayVideo360
+from interloper_assets.facebook_ads.source import FacebookAds
+from interloper_assets.facebook_insights.source import FacebookInsights
+from interloper_assets.instagram_insights.source import InstagramInsights
+from interloper_assets.linkedin_ads.source import LinkedinAds
+from interloper_assets.linkedin_organic.source import LinkedinOrganic
+from interloper_assets.pinterest_ads.source import PinterestAds
+from interloper_assets.search_ads_360.source import SearchAds360
+from interloper_assets.search_console.source import SearchConsole
+from interloper_assets.snapchat_ads.source import SnapchatAds
+from interloper_assets.teads.source import Teads
+from interloper_assets.thetradedesk.source import TheTradeDesk
+from interloper_assets.tiktok_ads.source import TiktokAds
+
+SOURCE_REGISTRY: dict[str, tuple[il.SourceDefinition, type[il.Config] | None]] = {
+    DemoSource.name: (DemoSource, DemoConfig),
+    Adup.name: (Adup, AdupConfig),
+    Adservice.name: (Adservice, AdserviceConfig),
+    AmazonAds.name: (AmazonAds, AmazonAdsConfig),
+    AmazonSellingPartner.name: (AmazonSellingPartner, None),
+    Awin.name: (Awin, None),
+    BingAds.name: (BingAds, None),
+    CampaignManager360.name: (CampaignManager360, None),
+    CampaignPerformanceAnalysis.name: (CampaignPerformanceAnalysis, None),
+    Criteo.name: (Criteo, None),
+    DisplayVideo360.name: (DisplayVideo360, None),
+    FacebookAds.name: (FacebookAds, None),
+    FacebookInsights.name: (FacebookInsights, None),
+    InstagramInsights.name: (InstagramInsights, None),
+    LinkedinAds.name: (LinkedinAds, None),
+    LinkedinOrganic.name: (LinkedinOrganic, None),
+    PinterestAds.name: (PinterestAds, None),
+    SearchAds360.name: (SearchAds360, None),
+    SearchConsole.name: (SearchConsole, None),
+    SnapchatAds.name: (SnapchatAds, None),
+    Teads.name: (Teads, None),
+    TheTradeDesk.name: (TheTradeDesk, None),
+    TiktokAds.name: (TiktokAds, None),
+}
+
+
+def get_source_and_config(id: str) -> tuple[il.SourceDefinition, type[il.Config] | None]:
+    """Get a source definition and its config type by source type ID.
+
+    Args:
+        id: Source type identifier (e.g. FacebookAds.name, DemoSource.name)
+
+    Returns:
+        Tuple of (SourceDefinition, ConfigType or None)
+
+    Raises:
+        ValueError: If the source ID is not found in the registry
+    """
+    if id not in SOURCE_REGISTRY:
+        raise SourceError(f"Unknown source ID: {id}")
+    return SOURCE_REGISTRY[id]
+
+
+def get_all_sources() -> dict[str, tuple[il.SourceDefinition, type[il.Config] | None]]:
+    """Get all registered sources.
+
+    Returns:
+        Dictionary mapping source type IDs to (SourceDefinition, ConfigType) tuples
+    """
+    return dict(SOURCE_REGISTRY)
+
+
+__all__ = [
+    "SOURCE_REGISTRY",
+    "get_all_sources",
+    "get_source_and_config",
+]

interloper_assets-0.2.0/src/interloper_assets/adservice/schemas/__init__.py

@@ -0,0 +1,15 @@
+from interloper_assets.adservice.schemas.campaigns import Campaigns
+from interloper_assets.adservice.schemas.campaigns_by_browser import CampaignsByBrowser
+from interloper_assets.adservice.schemas.campaigns_by_city import CampaignsByCity
+from interloper_assets.adservice.schemas.campaigns_by_device_type import CampaignsByDeviceType
+from interloper_assets.adservice.schemas.conversions import ConversionsReport
+from interloper_assets.adservice.schemas.conversions_by_time_of_day import ConversionsByTimeOfDay
+
+__all__ = [
+    "Campaigns",
+    "CampaignsByCity",
+    "CampaignsByDeviceType",
+    "CampaignsByBrowser",
+    "ConversionsReport",
+    "ConversionsByTimeOfDay",
+]

interloper_assets-0.2.0/src/interloper_assets/adservice/schemas/campaigns.py

@@ -0,0 +1,60 @@
+import datetime as dt
+
+from interloper.schema import AssetSchema
+from pydantic import Field
+
+
+class Campaigns(AssetSchema):
+    """
+    The Campaigns report provides insights into the performance and financial outcomes of advertising campaigns.
+    It includes key metrics such as click rates, conversion rates, revenue from various client activities such as
+    clicks, impressions, leads, and sales, as well as campaign and media information.
+    """
+
+    agent_id: int = Field(description="The unique identifier for the agent")
+    camp_id: int = Field(description="The unique identifier for the campaign")
+    camp_title: str = Field(description="The title of the campaign")
+    campaign_manager: str = Field(description="The name of the campaign manager")
+    campaign_manager_id: int = Field(description="The unique identifier for the campaign manager")
+    click_nun: int = Field(description="The number of clicks from unique visitors")
+    click_un: int = Field(description="The number of clicks from unique sources")
+    client_click_rev: float = Field(description="Revenue generated from client clicks")
+    client_impr_rev: float = Field(description="Revenue generated from client impressions")
+    client_lead_price: float = Field(description="Price of leads for the client")
+    client_lead_rev: float = Field(description="Revenue generated from client leads")
+    client_sale_rev: float = Field(description="Revenue generated from client sales")
+    client_subtotal: float = Field(description="Total revenue generated from client activities")
+    company_name: str = Field(description="The name of the company")
+    cpc: float = Field(description="Cost per click")
+    cr: float = Field(description="Conversion rate")
+    currency: str = Field(description="The currency used for transactions")
+    currency_code: str = Field(description="The currency code used")
+    currency_id: int = Field(description="The unique identifier for the currency")
+    currency_rate: float = Field(description="The exchange rate of the currency")
+    date: dt.date = Field(description="The date of the record")
+    date_from: dt.date = Field(description="The starting date for a time period")
+    date_max: dt.date = Field(description="The maximum date in a time period")
+    date_min: dt.date = Field(description="The minimum date in a time period")
+    date_to: dt.date = Field(description="The ending date for a time period")
+    default_banner: str = Field(description="The default banner for the campaign")
+    from_date: dt.date = Field(description="The starting date of an event or activity")
+    leads: int = Field(description="The number of leads generated")
+    media_id: int = Field(description="The unique identifier for the media")
+    medianame: str = Field(description="The name of the media")
+    mediatype: str = Field(description="The type of media")
+    monthyear: str = Field(description="The combination of month and year")
+    pcr: float = Field(description="Partial conversion rate")
+    pending_rev: float = Field(description="Revenue that is pending or not yet realized")
+    primary_category: int = Field(description="The primary category identifier")
+    primary_category_name: str = Field(description="The name of the primary category")
+    publisher_manager: str = Field(description="The name of the publisher manager")
+    publisher_manager_id: int = Field(description="The unique identifier for the publisher manager")
+    sales: float = Field(description="The number of sales")
+    sales_amount: float = Field(description="The total amount of sales")
+    stamp: dt.date = Field(description="The timestamp of the record")
+    to_date: dt.date = Field(description="The ending date of an event or activity")
+    week_to: dt.date = Field(description="The ending week of a time period")
+    weekyear: str = Field(description="The combination of week and year")
+    year: dt.date = Field(description="The year of the record")
+    year_from: dt.date = Field(description="The starting year of a time period")
+    year_to: dt.date = Field(description="The ending year of a time period")

interloper_assets-0.2.0/src/interloper_assets/adservice/schemas/campaigns_by_browser.py

@@ -0,0 +1,22 @@
+from interloper.schema import AssetSchema
+from pydantic import Field
+
+
+class CampaignsByBrowser(AssetSchema):
+    """
+    The Campaigns by Browser report provides insights into campaign performance based on the user's browser usage.
+    It includes key metrics such as conversion rates, the number of conversions, and user demographics such as
+    city, country, device model, device type, and operating system.
+    """
+
+    agent_id: int = Field(description="The ID of the agent")
+    browser: str = Field(description="The browser used by the user")
+    camp_id: int = Field(description="The ID of the campaign")
+    camp_title: str = Field(description="The title of the campaign")
+    city: str = Field(description="The city where the user is located")
+    conversion_pct: int = Field(description="The percentage of conversions")
+    conversions: int = Field(description="The number of conversions")
+    country: str = Field(description="The country where the user is located")
+    device_model: str = Field(description="The model of the device used by the user")
+    device_type: str = Field(description="The type of device used by the user")
+    os: str = Field(description="The operating system used by the user")

interloper_assets-0.2.0/src/interloper_assets/adservice/schemas/campaigns_by_city.py

@@ -0,0 +1,24 @@
+from interloper.schema import AssetSchema
+from pydantic import Field
+
+
+class CampaignsByCity(AssetSchema):
+    """
+    The Campaigns by City report provides insights into campaign performance segmented by cities.
+    It includes key metrics such as conversion rates, the number of conversions, and user demographics
+    such as browser usage, device type, operating system, and geographical coordinates (latitude and longitude).
+    """
+
+    agent_id: int = Field(description="The ID of the agent")
+    browser: str = Field(description="The browser used")
+    camp_id: int = Field(description="The ID of the campaign")
+    camp_title: str = Field(description="The title of the campaign")
+    city: str = Field(description="The city")
+    conversion_pct: int = Field(description="The conversion percentage")
+    conversions: int = Field(description="The number of conversions")
+    coordinates_lat: float = Field(description="The latitude coordinates")
+    coordinates_lng: float = Field(description="The longitude coordinates")
+    country: str = Field(description="The country")
+    device_model: str = Field(description="The device model")
+    device_type: str = Field(description="The device type")
+    os: str = Field(description="The operating system")

interloper_assets-0.2.0/src/interloper_assets/adservice/schemas/campaigns_by_device_type.py

@@ -0,0 +1,23 @@
+from interloper.schema import AssetSchema
+from pydantic import Field
+
+
+class CampaignsByDeviceType(AssetSchema):
+    """
+    The Campaigns by Device Type report provides insights into campaign performance
+    based on the type of device used by users. It includes key metrics such as
+    conversion rates, the number of conversions, and user demographics such as
+    browser usage, operating system, city, and country.
+    """
+
+    agent_id: int = Field(description="The ID of the agent")
+    browser: str = Field(description="The browser used")
+    camp_id: int = Field(description="The ID of the campaign")
+    camp_title: str = Field(description="The title of the campaign")
+    city: str = Field(description="The city where the campaign was run")
+    conversion_pct: int = Field(description="The percentage of conversions")
+    conversions: int = Field(description="The number of conversions")
+    country: str = Field(description="The country where the campaign was run")
+    device_model: str = Field(description="The model of the device")
+    device_type: str = Field(description="The type of the device")
+    os: str = Field(description="The operating system used")

interloper_assets-0.2.0/src/interloper_assets/adservice/schemas/conversions.py

@@ -0,0 +1,50 @@
+from interloper.schema import AssetSchema
+from pydantic import Field
+
+
+class ConversionsReport(AssetSchema):
+    """
+    The Conversions report provides insights on conversion events tracked within campaigns.
+    It includes key metrics such as the amount of conversions, conversion time, currency, IP geolocation data,
+    media information, order details, and user device information such as browser, device, and operating system.
+    """
+
+    agent_id: int = Field(description="Agent ID")
+    amount: str = Field(description="Amount")
+    camp_id: int = Field(description="Campaign ID")
+    camp_title: str = Field(description="Campaign Title")
+    cart_id: int = Field(description="Cart ID")
+    click_ref_id: int = Field(description="Click Reference ID")
+    click_stamp: int = Field(description="Click Stamp")
+    coid: int = Field(description="COID")
+    company_name: str = Field(description="Company Name")
+    conversion_time: int = Field(description="Conversion Time")
+    currency: str = Field(description="Currency")
+    id: int = Field(description="ID")
+    ip_city: str = Field(description="IP City")
+    ip_country_geoname_id: int = Field(description="IP Country Geoname ID")
+    ip_country_iso_code: str = Field(description="IP Country ISO Code")
+    ip_country_names_de: str = Field(description="IP Country Names (German)")
+    ip_country_names_en: str = Field(description="IP Country Names (English)")
+    ip_country_names_es: str = Field(description="IP Country Names (Spanish)")
+    ip_country_names_fr: str = Field(description="IP Country Names (French)")
+    ip_country_names_ja: str = Field(description="IP Country Names (Japanese)")
+    ip_country_names_pt_br: str = Field(description="IP Country Names (Portuguese - Brazil)")
+    ip_country_names_ru: str = Field(description="IP Country Names (Russian)")
+    ip_country_names_zh_cn: str = Field(description="IP Country Names (Chinese - Simplified)")
+    leaddata: str = Field(description="Lead Data")
+    media_id: int = Field(description="Media ID")
+    media_url: int = Field(description="Media URL")
+    medianame: str = Field(description="Media Name")
+    order_id: str = Field(description="Order ID")
+    price: str = Field(description="Price")
+    pricevariable: str = Field(description="Price Variable")
+    reject_reason: int = Field(description="Reject Reason")
+    result: str = Field(description="Result")
+    sensitive_data: int = Field(description="Sensitive Data")
+    stamp: str = Field(description="Stamp")
+    status: str = Field(description="Status")
+    user_agent: str = Field(description="User Agent")
+    user_browser: int = Field(description="User Browser")
+    user_device: int = Field(description="User Device")
+    user_os: int = Field(description="User OS")

interloper_assets-0.2.0/src/interloper_assets/adservice/schemas/conversions_by_time_of_day.py

@@ -0,0 +1,15 @@
+from interloper.schema import AssetSchema
+from pydantic import Field
+
+
+class ConversionsByTimeOfDay(AssetSchema):
+    """
+    The Conversions by Time of Day report provides insights into conversion patterns based on the day of the week
+    and hour of the day. It includes key metrics such as the number of conversions and revenue generated within each
+    time segment.
+    """
+
+    conversions: int = Field(description="Number of conversions")
+    day: str = Field(description="Day of the week")
+    hour: int = Field(description="Hour of the day")
+    revenue: float = Field(description="Revenue generated")

interloper_assets-0.2.0/src/interloper_assets/adservice/source.py

@@ -0,0 +1,148 @@
+import datetime as dt
+import logging
+
+import httpx
+import interloper as il
+import pandas as pd
+from pydantic_settings import SettingsConfigDict
+
+from interloper_assets.adservice import schemas
+
+logger = logging.getLogger(__name__)
+
+
+class AdserviceConfig(il.Config):
+    api_key: str
+
+    model_config = SettingsConfigDict(env_prefix="adservice_")
+
+
+@il.source(
+    config=AdserviceConfig,
+    tags=["Advertising"],
+)
+class Adservice:
+    """Adservice advertising platform integration."""
+
+    def __init__(self, config: AdserviceConfig) -> None:
+        base_url = "https://api.adservice.com/v2/client"
+        auth = httpx.BasicAuth(username="api", password=config.api_key)
+        self.client = il.RESTClient(base_url, auth)
+        self.base_url = base_url
+
+    def get_report(
+        self,
+        start_date: dt.date,
+        end_date: dt.date,
+        report_type: str,
+        group_by: str | None = None,
+        end_group: str | None = None,
+        sales_amount: int | None = None,
+    ) -> dict:
+        response = self.client.get(
+            url=f"{self.base_url}/{report_type}",
+            params={
+                "from_date": start_date.isoformat(),
+                "to_date": end_date.isoformat(),
+                "sales_amount": sales_amount,
+                "group_by": group_by,
+                "end_group": end_group,
+            },
+        )
+        response.raise_for_status()
+        return response.json()
+
+    @il.asset(
+        schema=schemas.Campaigns,
+        partitioning=il.TimePartitionConfig(column="date"),
+    )
+    def campaigns(self, context: il.ExecutionContext) -> pd.DataFrame:
+        """Campaign performance statistics with metrics like impressions, clicks, and conversions."""
+
+        response = self.get_report(
+            start_date=context.partition_date,
+            end_date=context.partition_date,
+            report_type="statistics",
+            group_by="stamp,camp_id",
+            end_group="stamp",
+            sales_amount=1,
+        )
+        data = response["data"]["rows"]
+        return pd.DataFrame(data)
+
+    @il.asset(
+        schema=schemas.ConversionsReport,
+        partitioning=il.TimePartitionConfig(column="date"),
+    )
+    def conversions(self, context: il.ExecutionContext) -> pd.DataFrame:
+        """Conversion events and attribution data."""
+        response = self.get_report(
+            start_date=context.partition_date,
+            end_date=context.partition_date,
+            report_type="conversions",
+        )
+        data = response["data"]
+        return pd.DataFrame(data)
+
+    @il.asset(
+        schema=schemas.ConversionsByTimeOfDay,
+        partitioning=il.TimePartitionConfig(column="date"),
+    )
+    def conversions_time_of_day(self, context: il.ExecutionContext) -> pd.DataFrame:
+        """Conversion events broken down by time of day."""
+
+        response = self.get_report(
+            start_date=context.partition_date,
+            end_date=context.partition_date,
+            report_type="statistics/conversions/timeofday",
+        )
+        data = response["data"]
+        return pd.DataFrame(data)
+
+    @il.asset(
+        schema=schemas.CampaignsByCity,
+        partitioning=il.TimePartitionConfig(column="date"),
+    )
+    def campaigns_by_city(self, context: il.ExecutionContext) -> pd.DataFrame:
+        """Campaign performance segmented by city."""
+
+        response = self.get_report(
+            start_date=context.partition_date,
+            end_date=context.partition_date,
+            report_type="statistics/devicedetails",
+            group_by="city",
+        )
+        data = response["data"]
+        return pd.DataFrame(data)
+
+    @il.asset(
+        schema=schemas.CampaignsByBrowser,
+        partitioning=il.TimePartitionConfig(column="date"),
+    )
+    def campaigns_by_browser(self, context: il.ExecutionContext) -> pd.DataFrame:
+        """Campaign performance segmented by browser."""
+
+        response = self.get_report(
+            start_date=context.partition_date,
+            end_date=context.partition_date,
+            report_type="statistics/devicedetails",
+            group_by="browser",
+        )
+        data = response["data"]
+        return pd.DataFrame(data)
+
+    @il.asset(
+        schema=schemas.CampaignsByDeviceType,
+        partitioning=il.TimePartitionConfig(column="date"),
+    )
+    def campaigns_by_device_type(self, context: il.ExecutionContext) -> pd.DataFrame:
+        """Campaign performance segmented by device type."""
+
+        response = self.get_report(
+            start_date=context.partition_date,
+            end_date=context.partition_date,
+            report_type="statistics/devicedetails",
+            group_by="device_type",
+        )
+        data = response["data"]
+        return pd.DataFrame(data)