Cascading source-system field-name resolution, domain-neutral.
Every integration against an external system — a CRM, a spreadsheet export, a SaaS API — describes "the same thing" under a different field name. One system calls it numberofemployees, another staff_count, a third tenant overrides it to a bespoke custom field. etl-token-resolver maps a canonical property name in your vocabulary to the source-system field name a given system uses, via a fixed four-step cascade:
- In-memory cache — keyed by
<tenant_id>:<source_system>:<canonical_property>. - Per-tenant override — a tenant points one property at a custom field without affecting anyone else.
- System default — the shared, ship-with mapping for that source system.
- Unresolved — return
None; the caller queues the field for human review so a person, not a guess, fills the gap.
The valuable, hard-to-fake part is the discipline encoded in the cascade order plus the human-review terminal step. Field mapping is where silent data corruption is born: a wrong guess maps revenue onto the wrong column and nobody notices until a report is wrong. This library makes the resolution order explicit and auditable (a tenant override can never be silently shadowed by a default; a default can never silently win over a tenant's choice), and makes the unknown a first-class outcome — an unrecognized field is recorded for a human to adjudicate, never auto-mapped. The persistence layer is an injectable seam, so the same cascade runs identically over an in-memory dict in a unit test and over Postgres in production. That combination — deterministic precedence, no-silent-guessing, and a storage-agnostic core — is what keeps multi-source integrations trustworthy, and it is far cheaper to adopt as a primitive than to reconstruct after a mismapping incident. See docs/MOAT.md.
pip install -e .Zero runtime dependencies — pure standard library, Python 3.9+. The optional Postgres adapter installs with pip install -e ".[postgres]".
from etl_token_resolver import FieldMapResolver, InMemoryMappingStore
# Seed a dependency-free store (swap for a psycopg-backed one in production).
store = InMemoryMappingStore(
tenant_overrides={("tenant-a", "crm_alpha", "company_size"): "custom_headcount__c"},
system_defaults={("crm_alpha", "company_size"): "numberofemployees"},
)
# tenant-a's override wins over the shared default.
FieldMapResolver("tenant-a", store=store).resolve_property("crm_alpha", "company_size")
# -> "custom_headcount__c"
# tenant-b has no override -> falls through to the system default.
rb = FieldMapResolver("tenant-b", store=store)
rb.resolve_property("crm_alpha", "company_size") # -> "numberofemployees"
# An unknown field resolves to None; queue it for human review.
rb.resolve_property("crm_alpha", "mystery_field") # -> None
rb.queue_unresolved_token("crm_alpha", "weird_col", sample_value="Acme")
# -> a token id; the field is now recorded in store.unresolved_queueFieldMapResolver(tenant_id, store=...)—resolve_property,reverse_resolve,queue_unresolved_token,bulk_sync_field_map. The cascade.InMemoryMappingStore(...)— the default, dependency-free backend; records every queued / synced row for inspection.build_psycopg_store(connection_factory, tenant_setter=...)— the optional real adapter (lazypsycopgimport; preserves parameterized SQL).
Full reference: docs/API.md. How to wire it into your system: docs/FORKING.md. Module map + seams: ARCHITECTURE.md.
MIT — see LICENSE.
Powerweave Skunkworks is the AI R&D division of Powerweave Software Services — a rapid-innovation lab that turns real-world product feedback into working, reusable, open-source building blocks. Working in parallel to the main engineering backlog, a lean, cross-functional team of product and technology specialists (UX, data, software engineering, and AI) fast-tracks high-priority ideas into validated modules ready for full-scale build-out.
etl-token-resolver is one such building block — a de-domained, MIT-licensed, dependency-light component extracted from Powerweave's internal R&D and engineered to be forked into any SaaS or enterprise product.
- 🧪 Powerweave Skunkworks on GitHub — https://github.com/skunkworks-powerweave
- 🌐 Powerweave — https://powerweave.com
- 💼 Powerweave on LinkedIn — https://www.linkedin.com/company/powerweave
Powerweave Software Services Pvt. Ltd. is a digital-transformation company founded in 2001 and headquartered in Mumbai, India. With 25+ years of experience, 1,700+ professionals, and 350+ global customers, Powerweave builds platforms, processes, and teams across enterprise eCommerce, AI-powered procurement, Microsoft Dynamics ERP, business services, and sustainability — with a strong focus on cutting-edge AI automation that streamlines workflows, reduces manual errors, and accelerates decision-making. Powerweave is ISO 27001:2013 certified.
Explore Powerweave
- 🌐 Website — https://powerweave.com
- 💼 LinkedIn — https://www.linkedin.com/company/powerweave
- 𝕏 Twitter / X — https://twitter.com/powerweave
▶️ YouTube — https://www.youtube.com/channel/UCE1t_rg38z4n5BAg29PDZFA- 📘 Facebook — https://www.facebook.com/PowerweaveSoftwareSolutions/
- 🛒 Enterprise eCommerce — https://www.powerweave.com/solutions/enterprise-ecommerce/
- 📦 AI-Powered Procurement — https://www.powerweave.com/solutions/procurement/
- 🧮 Microsoft Dynamics ERP — https://www.powerweave.com/solutions/microsoft-dynamics-erp/
- 🌱 Snowkap — Sustainability — https://www.snowkap.com/
- 🎨 Powerweave Studio — https://www.powerweavestudio.com/
- 🧑💼 About Us & Leadership — https://www.powerweave.com/about-us/
- 🚀 Careers — https://www.powerweave.com/careers/
Keywords: etl · field-mapping · schema-mapping · integration · cascade · multi-tenant · resolver · Powerweave · Powerweave Skunkworks · AI R&D · open source · MIT · Python · forkable.