unitpulse-channels 0.1.0__tar.gz

unitpulse_channels-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UnitPulse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unitpulse_channels-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: unitpulse-channels
+Version: 0.1.0
+Summary: Canonical communication-channel enum and lead-source registry
+Author: UnitPulse
+Author-email: honglu.he@unitpulse.ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+# unitpulse-channels
+
+Single source of truth for UnitPulse's communication-channel and lead-source
+vocabulary. Import it everywhere a `channel` or `lead_source` value is produced
+so services stop re-declaring (and drifting) their own lists.
+
+## Concepts
+
+Three distinct things that were historically conflated into one free-form field:
+
+| concept | field | governance |
+|---|---|---|
+| **channel** | per-message medium | CLOSED enum (`Channel`) |
+| **first_touch_channel** | mode of first contact (prospect) | same `Channel` enum |
+| **lead_source** | acquisition / attribution | OPEN curated registry (`LEAD_SOURCES`) |
+
+`channel` is closed: unknown input → `other` (+ WARN log). `lead_source` is an
+open curated registry: unknown input → `other` but the original raw string is
+preserved so new sources can be promoted by review.
+
+## Usage
+
+```python
+from unitpulse_channels import (
+    normalize_channel, normalize_lead_source, classify_prospect_source,
+)
+
+normalize_channel("FB Messenger")        # -> "fb messenger"
+normalize_channel("call in")             # -> "phone"
+normalize_channel("walk in")             # -> "in_person"
+
+normalize_lead_source("ZILLOW").value    # -> "zillow"
+normalize_lead_source("1133 Hope")       # -> LeadSource(value="other", raw="1133 Hope")
+
+# Split a raw prospect "source" into both dimensions:
+classify_prospect_source("Walk in")            # -> ("direct", "in_person")
+classify_prospect_source("Zillow")             # -> ("zillow", None)  # derive channel from 1st activity
+classify_prospect_source("Facebook Messenger") # -> ("facebook", "fb messenger")
+```
+
+Design + backfill: `design-docs` → `unitpulse/specs/2026-06-18-channel-enum-cleanup.md`.

unitpulse_channels-0.1.0/README.md

@@ -0,0 +1,41 @@
+# unitpulse-channels
+
+Single source of truth for UnitPulse's communication-channel and lead-source
+vocabulary. Import it everywhere a `channel` or `lead_source` value is produced
+so services stop re-declaring (and drifting) their own lists.
+
+## Concepts
+
+Three distinct things that were historically conflated into one free-form field:
+
+| concept | field | governance |
+|---|---|---|
+| **channel** | per-message medium | CLOSED enum (`Channel`) |
+| **first_touch_channel** | mode of first contact (prospect) | same `Channel` enum |
+| **lead_source** | acquisition / attribution | OPEN curated registry (`LEAD_SOURCES`) |
+
+`channel` is closed: unknown input → `other` (+ WARN log). `lead_source` is an
+open curated registry: unknown input → `other` but the original raw string is
+preserved so new sources can be promoted by review.
+
+## Usage
+
+```python
+from unitpulse_channels import (
+    normalize_channel, normalize_lead_source, classify_prospect_source,
+)
+
+normalize_channel("FB Messenger")        # -> "fb messenger"
+normalize_channel("call in")             # -> "phone"
+normalize_channel("walk in")             # -> "in_person"
+
+normalize_lead_source("ZILLOW").value    # -> "zillow"
+normalize_lead_source("1133 Hope")       # -> LeadSource(value="other", raw="1133 Hope")
+
+# Split a raw prospect "source" into both dimensions:
+classify_prospect_source("Walk in")            # -> ("direct", "in_person")
+classify_prospect_source("Zillow")             # -> ("zillow", None)  # derive channel from 1st activity
+classify_prospect_source("Facebook Messenger") # -> ("facebook", "fb messenger")
+```
+
+Design + backfill: `design-docs` → `unitpulse/specs/2026-06-18-channel-enum-cleanup.md`.

unitpulse_channels-0.1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"

unitpulse_channels-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unitpulse_channels-0.1.0/setup.py

@@ -0,0 +1,31 @@
+"""Setup for unitpulse-channels SDK."""
+
+from pathlib import Path
+from setuptools import setup, find_packages
+
+long_description = Path(__file__).parent.joinpath("README.md").read_text(encoding="utf-8")
+
+setup(
+    name="unitpulse-channels",
+    version="0.1.0",
+    author="UnitPulse",
+    author_email="honglu.he@unitpulse.ai",
+    description="Canonical communication-channel enum and lead-source registry",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    packages=find_packages(exclude=["tests*"]),
+    python_requires=">=3.8",
+    install_requires=[],
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ],
+)

unitpulse_channels-0.1.0/tests/test_channel.py

@@ -0,0 +1,60 @@
+import logging
+import pytest
+from unitpulse_channels import Channel, normalize_channel, CANONICAL_CHANNELS, is_canonical
+
+
+@pytest.mark.parametrize("raw,expected", [
+    ("sms", "sms"),
+    ("SMS", "sms"),
+    ("  Email ", "email"),
+    ("sms_callback", "sms"),            # direction stripped from channel
+    ("email_callback", "email"),
+    ("gmail", "email"),
+    ("call in", "phone"),
+    ("call-in", "phone"),
+    ("fb messenger", "fb messenger"),
+    ("fb-messenger", "fb messenger"),
+    ("Facebook Messenger", "fb messenger"),
+    ("wechat", "wecom"),
+    ("wecom", "wecom"),
+    ("rednote", "rednote"),
+    ("website chatbot", "website_chatbot"),
+    ("walk in", "in_person"),
+    ("walk-in", "in_person"),
+    ("in person", "in_person"),
+    ("system", "system"),
+    ("NOTE", "system"),
+])
+def test_known_aliases_normalize(raw, expected):
+    assert normalize_channel(raw) == expected
+    assert is_canonical(normalize_channel(raw))
+
+
+@pytest.mark.parametrize("raw", ["Zillow", "ApartmentList", "1133 Hope", "weird-thing"])
+def test_unknown_maps_to_other_and_logs(raw, caplog):
+    with caplog.at_level(logging.WARNING):
+        assert normalize_channel(raw) == "other"
+    assert any(raw in str(rec.args) or raw in rec.getMessage() for rec in caplog.records)
+
+
+@pytest.mark.parametrize("raw", [None, "", "   "])
+def test_empty_or_none_maps_to_other(raw):
+    assert normalize_channel(raw) == "other"
+
+
+def test_canonical_set_is_closed():
+    assert CANONICAL_CHANNELS == {
+        "sms", "email", "phone", "fb messenger", "wecom", "rednote",
+        "website_chatbot", "in_person", "system", "other",
+    }
+
+
+def test_enum_values_match_strings():
+    assert Channel.FB_MESSENGER == "fb messenger"
+    assert Channel.IN_PERSON.value == "in_person"
+    assert Channel.PHONE.value == "phone"
+
+
+def test_bare_facebook_is_not_a_channel():
+    # bare "facebook" is a lead SOURCE, not the fb messenger channel
+    assert normalize_channel("facebook") == "other"

unitpulse_channels-0.1.0/tests/test_lead_source.py

@@ -0,0 +1,63 @@
+import logging
+import pytest
+from unitpulse_channels import (
+    LEAD_SOURCES, normalize_lead_source, is_known_lead_source,
+    classify_prospect_source,
+)
+
+
+@pytest.mark.parametrize("raw,expected", [
+    ("Zillow", "zillow"),
+    ("ZILLOW", "zillow"),
+    ("ApartmentList", "apartmentlist"),
+    ("Apartmentlist", "apartmentlist"),
+    ("apartments.com", "apartments_com"),
+    ("EveryApartment", "everyapartment"),
+    ("Furnished Finder", "furnished_finder"),
+    ("Appfolio", "appfolio"),
+    ("Facebook", "facebook"),
+    ("Referral", "referral"),
+])
+def test_known_sources_normalize_to_curated_slug(raw, expected):
+    result = normalize_lead_source(raw)
+    assert result.value == expected
+    assert is_known_lead_source(result.value)
+    assert result.raw == raw.strip()
+
+
+@pytest.mark.parametrize("raw", ["1133 Hope", "tripalink2 unknown blah", "some-new-campaign-2026"])
+def test_unknown_source_buckets_to_other_but_keeps_raw(raw, caplog):
+    with caplog.at_level(logging.WARNING):
+        result = normalize_lead_source(raw)
+    assert result.value == "other"
+    assert result.raw == raw.strip()
+
+
+@pytest.mark.parametrize("raw", [None, "", "   "])
+def test_empty_source_is_other_with_empty_raw(raw):
+    result = normalize_lead_source(raw)
+    assert result.value == "other"
+    assert result.raw == ""
+
+
+def test_registry_excludes_channels():
+    # walk_in/call_in and pure media are channels, not sources
+    for not_a_source in ("walk_in", "call_in", "sms", "wecom", "rednote"):
+        assert not_a_source not in LEAD_SOURCES
+
+
+@pytest.mark.parametrize("raw,src,ch", [
+    ("Walk in", "direct", "in_person"),
+    ("Call In", "direct", "phone"),
+    ("Email", "direct", "email"),
+    ("Zillow", "zillow", None),                          # channel derived from 1st activity
+    ("Facebook Messenger", "facebook", "fb messenger"),
+    ("CXM Call-in_Zillow", "zillow", "phone"),           # composite: source + channel
+    ("Apartmentlists", "apartmentlist", None),           # legacy spelling
+    ("1133 Hope", "property_website", None),             # property name -> property_website
+    ("some-brand-new-thing", "other", None),             # unrecognized but present -> other
+    ("", None, None),                                    # no source at all -> unknown
+    (None, None, None),
+])
+def test_classify_prospect_source_splits_both_dimensions(raw, src, ch):
+    assert classify_prospect_source(raw) == (src, ch)

unitpulse_channels-0.1.0/unitpulse_channels/__init__.py

@@ -0,0 +1,36 @@
+"""Canonical UnitPulse communication-channel and lead-source vocabulary.
+
+Single source of truth for:
+  * Channel               closed enum (communication medium / first-touch)
+  * normalize_channel     coerce any string -> canonical channel
+  * LEAD_SOURCES          curated (open) lead-source registry
+  * normalize_lead_source coerce any string -> LeadSource(value, raw)
+  * classify_prospect_source  split a raw prospect source into (source, channel)
+"""
+from .channel import (
+    Channel,
+    CANONICAL_CHANNELS,
+    normalize_channel,
+    is_canonical,
+)
+from .lead_source import (
+    LeadSource,
+    LEAD_SOURCES,
+    normalize_lead_source,
+    is_known_lead_source,
+    classify_prospect_source,
+)
+
+__all__ = [
+    "Channel",
+    "CANONICAL_CHANNELS",
+    "normalize_channel",
+    "is_canonical",
+    "LeadSource",
+    "LEAD_SOURCES",
+    "normalize_lead_source",
+    "is_known_lead_source",
+    "classify_prospect_source",
+]
+
+__version__ = "0.1.0"

unitpulse_channels-0.1.0/unitpulse_channels/channel.py

@@ -0,0 +1,148 @@
+"""Canonical communication-channel enum and normalizer.
+
+`channel` is a CLOSED set: the communication MEDIUM of a contact. The same enum
+serves both the per-message medium (activities_history[].channel) and the
+prospect-level first_touch_channel. Direction (inbound/outbound) and acquisition
+source (Zillow, ApartmentList, ...) are NOT channels and belong elsewhere.
+"""
+import logging
+import re
+from enum import Enum
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class Channel(str, Enum):
+    SMS = "sms"
+    EMAIL = "email"
+    PHONE = "phone"                 # inbound "call-in" is first_touch_channel=phone
+    FB_MESSENGER = "fb messenger"   # value matches the system-wide live constant (with space)
+    WECOM = "wecom"
+    REDNOTE = "rednote"
+    WEBSITE_CHATBOT = "website_chatbot"
+    IN_PERSON = "in_person"         # "walk-in" (face-to-face)
+    SYSTEM = "system"
+    OTHER = "other"
+
+
+CANONICAL_CHANNELS = frozenset(c.value for c in Channel)
+
+# Known spellings/synonyms -> canonical Channel. Keys MUST be lowercase +
+# whitespace-stripped (lookups lowercase/strip first). Extend as new spellings
+# appear. Bare "facebook" is intentionally NOT here (it is a lead SOURCE); only
+# explicit messenger spellings map to the FB_MESSENGER channel.
+_ALIASES = {
+    "sms": Channel.SMS,
+    "sms_callback": Channel.SMS,
+    "text message": Channel.SMS,
+    "email": Channel.EMAIL,
+    "email_callback": Channel.EMAIL,
+    "gmail": Channel.EMAIL,
+    "outlook": Channel.EMAIL,
+    "yahoo": Channel.EMAIL,
+    "yahoo mail": Channel.EMAIL,
+    "icloud": Channel.EMAIL,
+    "phone": Channel.PHONE,
+    "call in": Channel.PHONE,
+    "call-in": Channel.PHONE,
+    "callin": Channel.PHONE,
+    "cxm call-in": Channel.PHONE,
+    "phone call": Channel.PHONE,
+    "fb messenger": Channel.FB_MESSENGER,
+    "fb-messenger": Channel.FB_MESSENGER,
+    "fb_messenger": Channel.FB_MESSENGER,
+    "facebook messenger": Channel.FB_MESSENGER,
+    "facebook_messenger": Channel.FB_MESSENGER,
+    "messenger": Channel.FB_MESSENGER,
+    "wecom": Channel.WECOM,
+    "wechat": Channel.WECOM,
+    "rednote": Channel.REDNOTE,
+    "red note": Channel.REDNOTE,
+    "website_chatbot": Channel.WEBSITE_CHATBOT,
+    "website chatbot": Channel.WEBSITE_CHATBOT,
+    "web chatbot": Channel.WEBSITE_CHATBOT,
+    "website chatbox": Channel.WEBSITE_CHATBOT,
+    "website-chatbot": Channel.WEBSITE_CHATBOT,
+    "walk in": Channel.IN_PERSON,
+    "walk-in": Channel.IN_PERSON,
+    "walkin": Channel.IN_PERSON,
+    "in person": Channel.IN_PERSON,
+    "in-person": Channel.IN_PERSON,
+    "face to face": Channel.IN_PERSON,
+    "system": Channel.SYSTEM,
+    "note": Channel.SYSTEM,
+}
+
+
+def _lookup_channel(raw: Optional[str]) -> Optional[str]:
+    """Return the canonical channel value for an exact alias hit, else None.
+
+    Does NOT log or coerce; used by both normalize_channel and the combined
+    prospect-source classifier (which must probe without emitting warnings).
+    """
+    if raw is None:
+        return None
+    key = str(raw).strip().lower()
+    if not key:
+        return None
+    mapped = _ALIASES.get(key)
+    return mapped.value if mapped is not None else None
+
+
+def normalize_channel(raw: Optional[str]) -> str:
+    """Coerce any inbound channel string to a canonical Channel value.
+
+    Unknown / empty / None inputs map to Channel.OTHER and emit a WARN log
+    carrying the original value so a worklist of un-canonicalized inputs can be
+    mined from logs.
+    """
+    v = _lookup_channel(raw)
+    if v is not None:
+        return v
+    if raw is None or not str(raw).strip():
+        logger.warning("normalize_channel: empty/None channel -> 'other'")
+    else:
+        logger.warning("normalize_channel: unknown channel %r -> 'other'", raw)
+    return Channel.OTHER.value
+
+
+def is_canonical(value: str) -> bool:
+    return value in CANONICAL_CHANNELS
+
+
+# Ordered, first-match-wins substring/regex rules for classifying a MESSY prospect
+# "source" string's channel dimension (composites like "CXM Call-in_Zillow",
+# legacy spellings, etc.). This is the readable Python port of the SQL backfill's
+# regex CASE — deterministic, unit-tested, and shared by the backfill + the LLM
+# tagger's residual selection. `normalize_channel` above stays the fast exact-key
+# path for clean forward-writes; these rules are the fuzzy fallback for the
+# backfill. Order matters (e.g. "walk" before "call": a "cxm call-in_walk in"
+# value is an in-person visit).
+_CHANNEL_RULES = [
+    (re.compile(r"walk"), Channel.IN_PERSON),
+    (re.compile(r"in.person|face.to.face"), Channel.IN_PERSON),
+    (re.compile(r"call.?in|cxm call|phone"), Channel.PHONE),
+    (re.compile(r"messenger"), Channel.FB_MESSENGER),
+    (re.compile(r"website chatbot|web chatbot|chatbox|website_chatbot"), Channel.WEBSITE_CHATBOT),
+    (re.compile(r"wechat"), Channel.WECOM),
+    (re.compile(r"rednote|red note|^red$"), Channel.REDNOTE),
+    (re.compile(r"gmail|outlook|yahoo|icloud|e-?mail"), Channel.EMAIL),
+    (re.compile(r"^sms$|text message"), Channel.SMS),
+]
+
+
+def regex_channel(raw: Optional[str]) -> Optional[str]:
+    """Fuzzy channel classification for a messy source string. Returns a canonical
+    channel value, or None when the string carries no channel signal. Unlike
+    normalize_channel this does NOT coerce unknowns to 'other' — a missing signal
+    is None so the caller can fall back to deriving the channel from activity."""
+    if raw is None:
+        return None
+    key = str(raw).strip().lower()
+    if not key:
+        return None
+    for pattern, channel in _CHANNEL_RULES:
+        if pattern.search(key):
+            return channel.value
+    return None

unitpulse_channels-0.1.0/unitpulse_channels/lead_source.py

@@ -0,0 +1,196 @@
+"""Curated lead-source registry, normalizer, and combined prospect classifier.
+
+`lead_source` is an OPEN but curated registry (acquisition/attribution). Unknown
+values coerce to "other" but the original raw string is preserved so genuinely
+new sources can be promoted into the registry by review.
+
+Unlike `channel`, this set is extensible. Channel-type strings (walk in, call in,
+email, wechat, ...) are NOT sources -- they classify as channels.
+"""
+import logging
+import re
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from .channel import regex_channel
+
+logger = logging.getLogger(__name__)
+
+# Curated canonical lead-source slugs. Finalized from a full production
+# customers_wide_table dry-run (~300 raw values). Extend by adding a slug here
+# and its spellings to _SOURCE_ALIASES.
+LEAD_SOURCES = frozenset({
+    # ILS / marketplaces
+    "zillow", "apartmentlist", "apartments_com", "everyapartment",
+    "furnished_finder", "zumper", "hotpads", "uloop", "padmapper",
+    "realtor_com", "redfin", "trulia", "rent_com", "rentcafe", "entrata",
+    "airbnb", "college_pads", "university_living", "uhomes",
+    # social / search
+    "facebook", "instagram", "google",
+    # owned / direct / PMS
+    "property_website", "appfolio", "unitpulse_app", "jotform", "tripalink",
+    "direct",
+    # offline / people
+    "referral", "signage", "campus_outreach", "existing_resident",
+    # system / catch-all
+    "internal_system", "other",
+})
+
+# Exact-key spellings -> canonical slug (lowercase + whitespace-collapsed keys).
+# Starter map for clean forward-writes; the FULL historical map is seeded from
+# the reviewed migration.source_channel_map after the backfill (see the
+# backfill runbook + spec Op 8). Extend as needed.
+_SOURCE_ALIASES = {
+    "zillow": "zillow", "alexis-zillow": "zillow",
+    "apartmentlist": "apartmentlist", "apartment list": "apartmentlist",
+    "apartmentlists": "apartmentlist",
+    "apartments": "apartments_com", "apartments.com": "apartments_com",
+    "apartment.com": "apartments_com", "apartments247": "apartments_com",
+    "everyapartment": "everyapartment", "every apartment": "everyapartment",
+    "furnished finder": "furnished_finder",
+    "zumper": "zumper", "hotpads": "hotpads", "uloop": "uloop",
+    "padmapper": "padmapper", "realtor.com": "realtor_com", "realtor": "realtor_com",
+    "redfin": "redfin", "trulia": "trulia",
+    "rentcafe": "rentcafe", "rent cafe": "rentcafe",
+    "rent.com": "rent_com", "rent": "rent_com",
+    "entrata": "entrata", "airbnb": "airbnb",
+    "college pads": "college_pads", "rent college pads": "college_pads",
+    "collegerentals": "college_pads",
+    "university living": "university_living",
+    "uhome": "uhomes", "uhomes": "uhomes", "awehome": "uhomes",
+    "facebook": "facebook", "facebook messenger": "facebook",
+    "facebook marketplace and groups": "facebook",
+    "instagram": "instagram",
+    "google": "google", "google search": "google",
+    "appfolio": "appfolio", "jotform": "jotform",
+    "property website": "property_website", "website": "property_website",
+    "tripalink": "tripalink",
+    "referral": "referral", "friend referral": "referral",
+    "word of mouth": "referral", "roommate": "referral",
+    "signage": "signage", "walk in": "direct", "call in": "direct",
+    "campus promotion": "campus_outreach", "open house": "campus_outreach",
+    "current resident": "existing_resident", "renewal": "existing_resident",
+    "transfer": "existing_resident", "relet": "existing_resident",
+    "unitpulse-app": "unitpulse_app", "unitpulse-website": "unitpulse_app",
+    "unit pulse": "unitpulse_app",
+    "other": "other",
+}
+
+
+@dataclass(frozen=True)
+class LeadSource:
+    value: str   # canonical slug or "other"
+    raw: str     # original trimmed input, always preserved
+
+
+def _slug(text: str) -> str:
+    return re.sub(r"\s+", " ", text.strip()).lower()
+
+
+def normalize_lead_source(raw: Optional[str]) -> LeadSource:
+    """Normalize a lead-source string against the curated registry.
+
+    Unknown inputs map to "other" and WARN-log so new sources can be promoted.
+    The original trimmed string is always preserved on the returned object.
+    """
+    original = "" if raw is None else str(raw).strip()
+    if not original:
+        return LeadSource(value="other", raw="")
+    mapped = _SOURCE_ALIASES.get(_slug(original))
+    if mapped is not None:
+        return LeadSource(value=mapped, raw=original)
+    logger.warning("normalize_lead_source: unknown source %r -> 'other'", original)
+    return LeadSource(value="other", raw=original)
+
+
+def is_known_lead_source(value: str) -> bool:
+    return value in LEAD_SOURCES
+
+
+# Ordered, first-match-wins regex rules for the SOURCE dimension of a messy
+# prospect "source" string. Readable Python port of the SQL backfill's regex
+# CASE (same order — marketplace/specific before generic). Deterministic and
+# unit-tested. `normalize_lead_source` above stays the exact-key path for clean
+# forward-writes; these rules are the fuzzy fallback used by classify_prospect_source.
+_SOURCE_RULES = [
+    (re.compile(r"zillow"), "zillow"),
+    (re.compile(r"apartmentlist|apartment list"), "apartmentlist"),
+    (re.compile(r"apartments\.com|apartment\.com|\bapartments\b|apartments247"), "apartments_com"),
+    (re.compile(r"everyapartment|every apartment"), "everyapartment"),
+    (re.compile(r"furnished finder"), "furnished_finder"),
+    (re.compile(r"zumper"), "zumper"),
+    (re.compile(r"hotpads"), "hotpads"),
+    (re.compile(r"uloop"), "uloop"),
+    (re.compile(r"padmapper"), "padmapper"),
+    (re.compile(r"realtor"), "realtor_com"),
+    (re.compile(r"redfin"), "redfin"),
+    (re.compile(r"trulia"), "trulia"),
+    (re.compile(r"rentcafe|rent cafe"), "rentcafe"),
+    (re.compile(r"rent\.com|^rent\.?$"), "rent_com"),
+    (re.compile(r"entrata"), "entrata"),
+    (re.compile(r"airbnb"), "airbnb"),
+    (re.compile(r"college ?pads|college ?rentals|collegerentals"), "college_pads"),
+    (re.compile(r"university living"), "university_living"),
+    (re.compile(r"uhome|uhomes|异乡好居|集好家|awehome|amber ?student"), "uhomes"),
+    (re.compile(r"jotform"), "jotform"),
+    (re.compile(r"appfolio"), "appfolio"),
+    (re.compile(r"instagram"), "instagram"),
+    (re.compile(r"facebook|fb-|fb |^fb$"), "facebook"),
+    (re.compile(r"google|^seo|^sem|search engine"), "google"),
+    (re.compile(
+        r"property website|_property_website|hopedtla|1133 |squarespace|cyberoptik|"
+        r"websitefirstlogin|corporate website|apartment website|liveinktown|liveatlas|"
+        r"solare arcadia|sawyerliving|letterman|sclark|kara apartments|somi apartments|"
+        r"audrey ?apts|atlas house|maude official|nexen official|archer official|keystone|"
+        r"maxwell official|gemma ?official|addams|orange box|30 ?sixty|funliving|casita|"
+        r"hooli|unishack|coliving|resident360|officialwebsite|^official|official$|^website$"
+    ), "property_website"),
+    (re.compile(r"tripa+link|tripaaalink"), "tripalink"),
+    (re.compile(r"referral|refer$|reffer|friend|word of mouth|roommate|同事推荐"), "referral"),
+    (re.compile(r"signage|drive/|drive by|signs"), "signage"),
+    (re.compile(r"campus|off.?campus|dawg daze|housing fair|open house|outreach|innout"), "campus_outreach"),
+    (re.compile(r"current resident|relet|renewal|transfer|^owner"), "existing_resident"),
+    (re.compile(r"unit ?pulse|unitpulse|up leasing|web-messages"), "unitpulse_app"),
+    (re.compile(
+        r"parse_conversation|renty_|gemma_|arden_|_request_tour|_save_lead|_contact_us|"
+        r"_apply_now|conversion_cloud|tenant_event|auto_?ref|postofficial|post official"
+    ), "internal_system"),
+    (re.compile(r"^direct|direct website|direct contact|direct inquiry|^online|post to internet"), "direct"),
+]
+
+
+def _regex_source(key: str) -> Optional[str]:
+    for pattern, slug in _SOURCE_RULES:
+        if pattern.search(key):
+            return slug
+    return None
+
+
+def classify_prospect_source(raw: Optional[str]) -> Tuple[Optional[str], Optional[str]]:
+    """Split a messy prospect "source" string into (lead_source, first_touch_channel).
+
+    A raw value can carry a source, a channel, or both — classified independently
+    (mirrors the SQL backfill's two-output map):
+        "Walk in"            -> ("direct",  "in_person")
+        "Call In"            -> ("direct",  "phone")
+        "Zillow"             -> ("zillow",  None)             # channel derived from 1st activity
+        "CXM Call-in_Zillow" -> ("zillow",  "phone")
+        "Facebook Messenger" -> ("facebook","fb messenger")
+        "1133 Hope"          -> ("property_website", None)    # property name -> property_website
+        ""                   -> (None,     None)              # no source at all -> unknown
+
+    Rules:
+    - lead_source: a matched source slug; if the string is only a channel (walk/call/
+      email/...) -> "direct"; if it carries neither -> "other"; if the string is
+      empty/None -> None (genuinely unknown, hand to the LLM / leave NULL).
+    - first_touch_channel: matched channel value, else None (caller derives from
+      the earliest activity).
+    """
+    key = "" if raw is None else str(raw).strip().lower()
+    if not key:
+        return None, None
+    channel = regex_channel(key)
+    source = _regex_source(key)
+    if source is None:
+        source = "direct" if channel is not None else "other"
+    return source, channel

unitpulse_channels-0.1.0/unitpulse_channels.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: unitpulse-channels
+Version: 0.1.0
+Summary: Canonical communication-channel enum and lead-source registry
+Author: UnitPulse
+Author-email: honglu.he@unitpulse.ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+# unitpulse-channels
+
+Single source of truth for UnitPulse's communication-channel and lead-source
+vocabulary. Import it everywhere a `channel` or `lead_source` value is produced
+so services stop re-declaring (and drifting) their own lists.
+
+## Concepts
+
+Three distinct things that were historically conflated into one free-form field:
+
+| concept | field | governance |
+|---|---|---|
+| **channel** | per-message medium | CLOSED enum (`Channel`) |
+| **first_touch_channel** | mode of first contact (prospect) | same `Channel` enum |
+| **lead_source** | acquisition / attribution | OPEN curated registry (`LEAD_SOURCES`) |
+
+`channel` is closed: unknown input → `other` (+ WARN log). `lead_source` is an
+open curated registry: unknown input → `other` but the original raw string is
+preserved so new sources can be promoted by review.
+
+## Usage
+
+```python
+from unitpulse_channels import (
+    normalize_channel, normalize_lead_source, classify_prospect_source,
+)
+
+normalize_channel("FB Messenger")        # -> "fb messenger"
+normalize_channel("call in")             # -> "phone"
+normalize_channel("walk in")             # -> "in_person"
+
+normalize_lead_source("ZILLOW").value    # -> "zillow"
+normalize_lead_source("1133 Hope")       # -> LeadSource(value="other", raw="1133 Hope")
+
+# Split a raw prospect "source" into both dimensions:
+classify_prospect_source("Walk in")            # -> ("direct", "in_person")
+classify_prospect_source("Zillow")             # -> ("zillow", None)  # derive channel from 1st activity
+classify_prospect_source("Facebook Messenger") # -> ("facebook", "fb messenger")
+```
+
+Design + backfill: `design-docs` → `unitpulse/specs/2026-06-18-channel-enum-cleanup.md`.

unitpulse_channels-0.1.0/unitpulse_channels.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+tests/test_channel.py
+tests/test_lead_source.py
+unitpulse_channels/__init__.py
+unitpulse_channels/channel.py
+unitpulse_channels/lead_source.py
+unitpulse_channels.egg-info/PKG-INFO
+unitpulse_channels.egg-info/SOURCES.txt
+unitpulse_channels.egg-info/dependency_links.txt
+unitpulse_channels.egg-info/top_level.txt

unitpulse_channels-0.1.0/unitpulse_channels.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

unitpulse_channels-0.1.0/unitpulse_channels.egg-info/top_level.txt

@@ -0,0 +1 @@
+unitpulse_channels