span-data 0.4.0__cp311-abi3-win_amd64.whl

span_data/__init__.py

@@ -0,0 +1,5 @@
+"""span_data: identity resolution and Customer 360 libraries."""
+
+from span_data.io import DataSource, TableResult
+
+__all__ = ["DataSource", "TableResult"]

span_data/cli/__init__.py

@@ -0,0 +1,106 @@
+"""Command-line interface for span_data (SpanConfig validate and local runs)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from span_data.io.config import load_span_config
+from span_data.io.config.errors import SpanConfigError
+from span_data.io.config.pipeline import run_local_span_config
+
+
+def _cmd_validate_config(path: Path) -> int:
+    load_span_config(path)
+    print(f"OK: {path}")
+    return 0
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    span_config = load_span_config(args.config)
+    run_c360: bool | None = False if args.skip_c360 else None
+    run_local_span_config(
+        span_config,
+        args.data_dir,
+        args.output_dir,
+        app_name=args.app_name,
+        run_id_graph=not args.skip_id_graph,
+        run_c360=run_c360,
+        output_format=args.format,
+        data_extension=args.data_extension,
+    )
+    print(f"Finished. Outputs written to {args.output_dir}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="span-data", description="SPAN span_data CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    validate_parser = subparsers.add_parser(
+        "validate-config",
+        help="Validate a SpanConfig YAML file",
+    )
+    validate_parser.add_argument("config", type=Path, help="Path to span_config.yaml")
+
+    run_parser = subparsers.add_parser(
+        "run",
+        help="Run ID Graph and/or C360 from SpanConfig using local data files",
+    )
+    run_parser.add_argument("config", type=Path, help="Path to span_config.yaml")
+    run_parser.add_argument(
+        "--data-dir",
+        type=Path,
+        required=True,
+        help="Directory of input CSV/Parquet files (named by derive_source_name(dataset))",
+    )
+    run_parser.add_argument(
+        "--output-dir",
+        type=Path,
+        required=True,
+        help="Directory for pipeline outputs",
+    )
+    run_parser.add_argument(
+        "--app-name",
+        default="LOCAL",
+        help="Application database name for C360 ID Graph view reference (default: LOCAL)",
+    )
+    run_parser.add_argument(
+        "--format",
+        choices=("csv", "parquet"),
+        default="csv",
+        help="C360 output file format (default: csv)",
+    )
+    run_parser.add_argument(
+        "--data-extension",
+        choices=("csv", "parquet"),
+        default="csv",
+        help="Input file extension under --data-dir (default: csv)",
+    )
+    run_parser.add_argument(
+        "--skip-id-graph",
+        action="store_true",
+        help="Skip ID Graph; requires data-dir/id_graph.csv when C360 is enabled",
+    )
+    run_parser.add_argument(
+        "--skip-c360",
+        action="store_true",
+        help="Run ID Graph only (no C360 compile)",
+    )
+
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "validate-config":
+            return _cmd_validate_config(args.config)
+        if args.command == "run":
+            return _cmd_run(args)
+    except (SpanConfigError, ValueError, FileNotFoundError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    parser.error(f"unknown command: {args.command}")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

span_data/cli/__main__.py

@@ -0,0 +1,6 @@
+"""span-data console entry point."""
+
+from span_data.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

span_data/io/config/examples/data/ANALYTICS_EVENTS_EMAIL_EVENTS.csv

@@ -0,0 +1,3 @@
+EVENT_ID,CRM_CONTACT_ID,SENT_AT,OPENED,CLICKED
+E1,C1,2024-02-01 10:00:00+00:00,True,False
+E2,C1,2024-02-10 10:00:00+00:00,True,True

span_data/io/config/examples/data/ANALYTICS_EVENTS_ORDER_EVENTS.csv

@@ -0,0 +1,4 @@
+ORDER_ID,RETAIL_CUSTOMER_ID,ORDER_AT,ORDER_AMOUNT,ORDER_STATUS
+O1,R1,2024-02-20 00:00:00+00:00,100.0,completed
+O2,R1,2024-02-25 00:00:00+00:00,50.0,completed
+O3,R2,2024-03-03 00:00:00+00:00,75.0,completed

span_data/io/config/examples/data/ANALYTICS_EVENTS_SESSION_EVENTS.csv

@@ -0,0 +1,3 @@
+SESSION_ID,PORTAL_USER_ID,SESSION_START_AT,SESSION_DURATION_SEC
+S1,U1,2024-02-18 14:00:00+00:00,300
+S2,U1,2024-02-19 15:00:00+00:00,600

span_data/io/config/examples/data/ANALYTICS_SOURCES_CRM_CONTACTS.csv

@@ -0,0 +1,2 @@
+CONTACT_ID,EMAIL,FIRST_NAME,LAST_NAME,GENDER,BIRTH_DATE,ZIP_CODE,STATE,PHONE,UPDATED_AT,CREATED_AT
+C1,alice@example.com,Alice,Anderson,F,1990-01-01,10001,NY,555-0001,2024-01-10 10:00:00+00:00,2023-01-01 00:00:00+00:00

span_data/io/config/examples/data/ANALYTICS_SOURCES_PORTAL_USERS.csv

@@ -0,0 +1,2 @@
+USER_ID,EMAIL,FIRST_NAME,LAST_NAME,ZIP_CODE,UPDATED_AT,CREATED_AT
+U1,alice@example.com,Alice,Anderson,10001,2024-02-20 08:00:00+00:00,2023-08-01 00:00:00+00:00

span_data/io/config/examples/data/ANALYTICS_SOURCES_RETAIL_CUSTOMERS.csv

@@ -0,0 +1,3 @@
+CUSTOMER_ID,EMAIL,FIRST_NAME,LAST_NAME,PHONE,ZIP_CODE,STATE,CITY,UPDATED_AT,CREATED_AT
+R1,alice@example.com,Alice,Anderson,555-0001,10001,NY,New York,2024-02-15 12:00:00+00:00,2023-06-01 00:00:00+00:00
+R2,bob@example.com,Bob,Brown,555-0002,10002,CA,Los Angeles,2024-03-01 09:00:00+00:00,2024-01-15 00:00:00+00:00

span_data/io/config/examples/example_span_config.yaml

@@ -0,0 +1,279 @@
+# SpanConfig (illustrative example)
+# Symmetric top-level: id_graph (identity resolution) + c360 (customer 360).
+# Source identity is the qualified dataset name — no short aliases.
+# id_graph output dataset is NOT authored — injected at runtime
+# (Native App: {app}.APP_PUBLIC.{view_name}; free tier: path from ID Graph run).
+
+schema_version: "2.0"
+config_name: example_span_config
+# Optional for community, mandatory for Snowflake Native app
+app_settings:
+  view_name: example_span_config
+
+id_graph:
+  linkage:
+    blocking_rules:
+      - columns: [useremail]
+      - columns: [useremail, firstname]
+      - columns: [phone, firstname]
+
+  sources:
+    - dataset: ANALYTICS.SOURCES.CRM_CONTACTS
+      id_column: CONTACT_ID
+      fields:
+        useremail: { column: EMAIL, type: email }
+        firstname: { column: FIRST_NAME, type: text }
+        lastname: { column: LAST_NAME, type: text }
+        gender: { column: GENDER, type: text }
+        birthdate: { column: BIRTH_DATE, type: text }
+        zipcode: { column: ZIP_CODE, type: text }
+        state: { column: STATE, type: text }
+        phone: { column: PHONE, type: phonenumber }
+
+    - dataset: ANALYTICS.SOURCES.RETAIL_CUSTOMERS
+      id_column: CUSTOMER_ID
+      fields:
+        useremail: { column: EMAIL, type: email }
+        firstname: { column: FIRST_NAME, type: text }
+        lastname: { column: LAST_NAME, type: text }
+        phone: { column: PHONE, type: phonenumber }
+        zipcode: { column: ZIP_CODE, type: text }
+        state: { column: STATE, type: text }
+        city: { column: CITY, type: text }
+
+    - dataset: ANALYTICS.SOURCES.PORTAL_USERS
+      id_column: USER_ID
+      fields:
+        useremail: { column: EMAIL, type: email }
+        firstname: { column: FIRST_NAME, type: text }
+        lastname: { column: LAST_NAME, type: text }
+        zipcode: { column: ZIP_CODE, type: text }
+
+  # Optional ID Graph inputs (grant consumer tables before use)
+  # overrides:
+  #   dataset: ANALYTICS.SOURCES.ID_GRAPH_OVERRIDES
+  # seed:
+  #   dataset: ANALYTICS.SOURCES.ID_GRAPH_SEED
+
+c360:
+  enabled: true
+
+  # Demographics keyed by id_graph source dataset
+  demographics:
+    ANALYTICS.SOURCES.CRM_CONTACTS:
+      email: EMAIL
+      first_name: FIRST_NAME
+      last_name: LAST_NAME
+      gender: GENDER
+      birthdate: BIRTH_DATE
+      zip_code: ZIP_CODE
+      state: STATE
+      phone: PHONE
+      updated_at: UPDATED_AT
+      effective_from: CREATED_AT
+    ANALYTICS.SOURCES.RETAIL_CUSTOMERS:
+      email: EMAIL
+      first_name: FIRST_NAME
+      last_name: LAST_NAME
+      phone: PHONE
+      zip_code: ZIP_CODE
+      city: CITY
+      state: STATE
+      updated_at: UPDATED_AT
+      effective_from: CREATED_AT
+    ANALYTICS.SOURCES.PORTAL_USERS:
+      email: EMAIL
+      first_name: FIRST_NAME
+      last_name: LAST_NAME
+      zip_code: ZIP_CODE
+      updated_at: UPDATED_AT
+      effective_from: CREATED_AT
+
+  sources:
+    - dataset: ANALYTICS.EVENTS.EMAIL_EVENTS
+      id_column: CRM_CONTACT_ID
+      date_column: SENT_AT
+      dim_source: ANALYTICS.SOURCES.CRM_CONTACTS
+      suffix: email_sends
+
+    - dataset: ANALYTICS.EVENTS.ORDER_EVENTS
+      id_column: RETAIL_CUSTOMER_ID
+      date_column: ORDER_AT
+      dim_source: ANALYTICS.SOURCES.RETAIL_CUSTOMERS
+      suffix: orders
+
+    - dataset: ANALYTICS.EVENTS.SESSION_EVENTS
+      id_column: PORTAL_USER_ID
+      date_column: SESSION_START_AT
+      dim_source: ANALYTICS.SOURCES.PORTAL_USERS
+      suffix: web_sessions
+
+  precedence:
+    default:
+      strategy: coalesce
+      sources:
+        - ANALYTICS.SOURCES.CRM_CONTACTS
+        - ANALYTICS.SOURCES.RETAIL_CUSTOMERS
+        - ANALYTICS.SOURCES.PORTAL_USERS
+    zip_code:
+      strategy: coalesce
+      sources:
+        - ANALYTICS.SOURCES.RETAIL_CUSTOMERS
+        - ANALYTICS.SOURCES.CRM_CONTACTS
+        - ANALYTICS.SOURCES.PORTAL_USERS
+    city:
+      strategy: coalesce
+      sources:
+        - ANALYTICS.SOURCES.RETAIL_CUSTOMERS
+        - ANALYTICS.SOURCES.CRM_CONTACTS
+        - ANALYTICS.SOURCES.PORTAL_USERS
+    state:
+      strategy: coalesce
+      sources:
+        - ANALYTICS.SOURCES.RETAIL_CUSTOMERS
+        - ANALYTICS.SOURCES.CRM_CONTACTS
+        - ANALYTICS.SOURCES.PORTAL_USERS
+    updated_at:
+      strategy: greatest
+      sources:
+        - ANALYTICS.SOURCES.CRM_CONTACTS
+        - ANALYTICS.SOURCES.RETAIL_CUSTOMERS
+        - ANALYTICS.SOURCES.PORTAL_USERS
+    effective_from:
+      strategy: least
+      sources:
+        - ANALYTICS.SOURCES.CRM_CONTACTS
+        - ANALYTICS.SOURCES.RETAIL_CUSTOMERS
+        - ANALYTICS.SOURCES.PORTAL_USERS
+
+  consent:
+    conflict_precedence: [denied, unknown, granted]
+    mappings:
+      - source: ANALYTICS.SOURCES.CRM_CONTACTS
+        effective_date: CREATED_AT
+        purpose: promotional
+        medium: email
+        status: granted
+      - source: ANALYTICS.SOURCES.CRM_CONTACTS
+        effective_date: CREATED_AT
+        purpose: promotional
+        medium: sms
+        status: granted
+      - source: ANALYTICS.EVENTS.ORDER_EVENTS
+        effective_date: ORDER_AT
+        purpose: transactional
+        medium: email
+        status: granted
+
+  output_names:
+    dimensions: dim_c360_demographic_example_span_config
+    metrics: dim_c360_metric_example_span_config
+    consent: fct_c360_consent_example_span_config
+    segments: dim_c360_segment_example_span_config
+    fact: fct_c360_example_span_config_
+
+  metrics:
+    ltv_6m:
+      source: ANALYTICS.EVENTS.ORDER_EVENTS
+      measure: "SUM(CASE WHEN ORDER_STATUS = 'refund' THEN 0 ELSE ORDER_AMOUNT END)"
+      window: 6m
+    ltv_12m:
+      source: ANALYTICS.EVENTS.ORDER_EVENTS
+      measure: "SUM(CASE WHEN ORDER_STATUS = 'refund' THEN 0 ELSE ORDER_AMOUNT END)"
+      window: 12m
+    ltv_lifetime:
+      source: ANALYTICS.EVENTS.ORDER_EVENTS
+      measure: "SUM(CASE WHEN ORDER_STATUS = 'refund' THEN 0 ELSE ORDER_AMOUNT END)"
+      window: lifetime
+    order_count:
+      source: ANALYTICS.EVENTS.ORDER_EVENTS
+      measure: "CASE WHEN COUNT(ORDER_ID) = 0 THEN NULL ELSE COUNT(DISTINCT ORDER_ID) END"
+      window: lifetime
+    last_purchase_at:
+      source: ANALYTICS.EVENTS.ORDER_EVENTS
+      measure: "MAX(ORDER_AT)"
+      window: lifetime
+    email_send_count:
+      source: ANALYTICS.EVENTS.EMAIL_EVENTS
+      measure: "CASE WHEN COUNT(EVENT_ID) = 0 THEN NULL ELSE COUNT(DISTINCT EVENT_ID) END"
+      window: lifetime
+    email_open_count:
+      source: ANALYTICS.EVENTS.EMAIL_EVENTS
+      measure: "SUM(CASE WHEN OPENED = TRUE THEN 1 ELSE 0 END)"
+      window: lifetime
+    email_click_count:
+      source: ANALYTICS.EVENTS.EMAIL_EVENTS
+      measure: "SUM(CASE WHEN CLICKED = TRUE THEN 1 ELSE 0 END)"
+      window: lifetime
+    last_email_opened_at:
+      source: ANALYTICS.EVENTS.EMAIL_EVENTS
+      measure: "MAX(CASE WHEN OPENED = TRUE THEN SENT_AT ELSE NULL END)"
+      window: lifetime
+    web_session_count:
+      source: ANALYTICS.EVENTS.SESSION_EVENTS
+      measure: "CASE WHEN COUNT(SESSION_ID) = 0 THEN NULL ELSE COUNT(DISTINCT SESSION_ID) END"
+      window: lifetime
+    web_session_engagement:
+      source: ANALYTICS.EVENTS.SESSION_EVENTS
+      measure: "SUM(SESSION_DURATION_SEC)"
+      window: lifetime
+    last_web_session_started_at:
+      source: ANALYTICS.EVENTS.SESSION_EVENTS
+      measure: "MAX(SESSION_START_AT)"
+      window: lifetime
+    email_open_rate:
+      source: derived
+      expression: "email_open_count / COALESCE(email_send_count, 1)"
+    email_click_rate:
+      source: derived
+      expression: "email_click_count / COALESCE(email_send_count, 1)"
+    avg_session_duration_seconds:
+      source: derived
+      expression: "web_session_engagement / COALESCE(web_session_count, 1)"
+    average_order_value:
+      source: derived
+      expression: "ltv_lifetime / COALESCE(order_count, 1)"
+    last_touched_at:
+      source: derived
+      expression: "GREATEST(last_purchase_at, last_web_session_started_at, last_email_opened_at)"
+    customer_engagement_score:
+      source: derived
+      expression: >
+        (COALESCE(email_open_count, 0) / MAX(COALESCE(email_open_count, 0)) OVER()) * 25 +
+        (COALESCE(web_session_count, 0) / MAX(COALESCE(web_session_count, 0)) OVER()) * 25 +
+        (COALESCE(ltv_lifetime, 0) / MAX(COALESCE(ltv_lifetime, 0)) OVER()) * 50
+
+  segments:
+    is_crm_contact:
+      type: source_based
+      source: ANALYTICS.SOURCES.CRM_CONTACTS
+    is_retail_customer:
+      type: source_based
+      source: ANALYTICS.SOURCES.RETAIL_CUSTOMERS
+    is_portal_user:
+      type: source_based
+      source: ANALYTICS.SOURCES.PORTAL_USERS
+    is_active_customer:
+      type: filter_based
+      filter: "ltv_6m > 0"
+    is_new_customer:
+      type: filter_based
+      filter: "last_purchase_at >= NOW() - INTERVAL '7 days'"
+    value_tier_click_rate:
+      type: categorical_cohort
+      source_expression: email_click_rate
+      boundaries:
+        type: fixed_thresholds
+        bands:
+          - { label: low_click_rate, below: 0.01 }
+          - { label: medium_click_rate, below: 0.05 }
+          - { label: high_click_rate }
+    engagement_level:
+      type: categorical_cohort
+      source_expression: customer_engagement_score
+      boundaries:
+        type: percentile_thresholds
+        bands:
+          - { label: low_engagement, below: 0.20 }
+          - { label: medium_engagement, below: 0.80 }
+          - { label: high_engagement }