# Property Mapping Implementation Summary

**Date:** 2026-02-11
**Feature:** Flexible HubSpot Property Mapping for ICP Triangulation Framework
**Status:** ✅ Complete and Tested

## Overview

Added flexible property mapping configuration system that allows Pro/Enterprise users to customize which HubSpot custom properties are used for ICP scoring. This enables the `qualify` tool to automatically fetch and score all three ICP dimensions (Firmographic, Behavioral, Strategic) from HubSpot data without manual JSON input.

## Problem Solved

**Before:**
- The `qualify` tool only fetched standard HubSpot properties (industry, revenue, employees, geography)
- Behavioral fit (tech stack, growth signals, content engagement) and Strategic fit (decision-maker access, budget authority, alignment) required manual JSON input
- Every HubSpot instance has different custom property names for these dimensions
- Users couldn't leverage their existing HubSpot data enrichment

**After:**
- Pro/Enterprise users can configure a JSON mapping file to specify their HubSpot custom property names
- The `qualify` tool automatically fetches and scores all configured properties
- Supports flexible property names, thresholds, and signal keywords
- Full three-dimensional ICP triangulation from HubSpot data

## Implementation Details

### New Files Created

1. **`src/artefact_mcp/core/property_mappings.py`**
   - Defines `PropertyMapping` dataclass with all configurable properties
   - Includes `DEFAULT_PROPERTY_MAPPING` (standard properties only)
   - Includes `EXAMPLE_CUSTOM_MAPPING` for documentation

2. **`src/artefact_mcp/core/property_mapper.py`**
   - `PropertyMapper` class that transforms HubSpot data to ICP scorer format
   - Handles tech stack parsing (list or delimited string)
   - Handles growth signals from multiple properties
   - Applies engagement thresholds
   - Calculates purchase history from deal count
   - Parses strategic fit properties

3. **`property_mapping.example.json`**
   - Full example configuration with all available options
   - Reference for Pro/Enterprise users

4. **`property_mapping.minimal.example.json`**
   - Minimal configuration example (growth signals only)
   - Quick start for users who want basic customization

5. **`test_property_mapping.py`**
   - Verification script with 3 test scenarios
   - Tests default mapping, custom mapping, and threshold logic

### Modified Files

1. **`src/artefact_mcp/core/hubspot_client.py`**
   - Added `fetch_company_with_custom_properties()` method
   - Returns raw properties dict for flexible mapping
   - Added `List` type import

2. **`src/artefact_mcp/tools/icp.py`**
   - Added `property_mapping` parameter to `qualify_prospect()`
   - Uses `PropertyMapper` to transform HubSpot data
   - Added `_get_required_properties()` helper
   - Added `_fetch_deal_count()` helper for purchase history
   - Added imports for PropertyMapping and PropertyMapper

3. **`src/artefact_mcp/server.py`**
   - Loads property mapping from `ARTEFACT_PROPERTY_MAPPING_PATH` env var
   - Only available for Pro/Enterprise tiers
   - Passes property mapping to `qualify` tool
   - Added imports for PropertyMapping

4. **`README.md`**
   - Added "Custom Property Mappings (Pro/Enterprise)" section
   - Documented all configuration options
   - Added table of example HubSpot properties
   - Explained how to use example configuration files
   - Added `ARTEFACT_PROPERTY_MAPPING_PATH` to configuration table

## Configuration Options

| Property | Type | Description |
|----------|------|-------------|
| `tech_stack` | string | HubSpot property name for tech stack |
| `tech_stack_delimiter` | string | Delimiter for parsing text fields (default: `";"`) |
| `growth_signals` | array | List of HubSpot properties indicating growth |
| `growth_signal_keywords` | object | Map property names to signal keywords |
| `content_engagement` | string | HubSpot property for engagement score |
| `content_engagement_thresholds` | object | Thresholds for active/occasional |
| `decision_maker_access` | string | Strategic fit property |
| `budget_authority` | string | Budget authority property |
| `strategic_alignment` | string | Strategic alignment property |

## Usage Example

### 1. Create Configuration File

```json
{
  "tech_stack": "technologies_used",
  "growth_signals": ["linkedin_hiring_count", "recent_funding"],
  "content_engagement": "hubspot_engagement_score",
  "decision_maker_access": "primary_contact_role"
}
```

### 2. Set Environment Variable

```bash
export ARTEFACT_PROPERTY_MAPPING_PATH=/path/to/property_mapping.json
```

### 3. Use the `qualify` Tool

```bash
# Via Claude Code / Claude Desktop
qualify(company_id="12345")

# Programmatic
from artefact_mcp.tools.icp import qualify_prospect
from artefact_mcp.core.hubspot_client import HubSpotClient
from artefact_mcp.core.property_mappings import PropertyMapping

mapping = PropertyMapping(
    tech_stack="technologies_used",
    growth_signals=["linkedin_hiring_count", "recent_funding"]
)

client = HubSpotClient(api_key="your-key")
result = qualify_prospect(
    company_id="12345",
    hubspot_client=client,
    property_mapping=mapping
)
```

## Testing

All tests pass successfully:

```
✅ Test 1: Default Mapping — Standard properties only
✅ Test 2: Custom Property Mapping — Custom properties with full configuration
✅ Test 3: Threshold Logic — Engagement and purchase history classification
```

Run tests:
```bash
python test_property_mapping.py
```

## Backward Compatibility

✅ **Fully backward compatible**

- Free tier users: No changes, works exactly as before
- Pro/Enterprise users without config file: Uses default mapping (standard properties)
- Pro/Enterprise users with config file: Uses custom mapping
- Manual `company_data` JSON input: Still works (bypasses property mapping)

## Future Enhancements

- **Auto-detection:** Analyze HubSpot schema and suggest property mappings
- **Web UI:** Configure mappings through a web interface
- **Multiple profiles:** Support different mappings per HubSpot portal (Enterprise)
- **Validation:** Validate that configured properties exist in HubSpot before scoring

## Files Summary

### Created
- `src/artefact_mcp/core/property_mappings.py` (60 lines)
- `src/artefact_mcp/core/property_mapper.py` (151 lines)
- `property_mapping.example.json` (20 lines)
- `property_mapping.minimal.example.json` (10 lines)
- `test_property_mapping.py` (172 lines)
- `IMPLEMENTATION_PROPERTY_MAPPING.md` (this file)

### Modified
- `src/artefact_mcp/core/hubspot_client.py` (+23 lines)
- `src/artefact_mcp/tools/icp.py` (+45 lines)
- `src/artefact_mcp/server.py` (+16 lines)
- `README.md` (+58 lines)

### Total Changes
- **6 new files**
- **4 modified files**
- **~545 lines of code and documentation added**

## Deployment Checklist

- [x] Implementation complete
- [x] Unit tests pass
- [x] Documentation updated (README)
- [x] Example configurations provided
- [x] Backward compatibility verified
- [x] Import verification passed
- [x] JSON validation passed

## Next Steps for User

1. **Identify custom properties** in your HubSpot instance
2. **Copy example configuration file:** `cp property_mapping.minimal.example.json my_mapping.json`
3. **Edit configuration** with your property names
4. **Set environment variable:** `export ARTEFACT_PROPERTY_MAPPING_PATH=$(pwd)/my_mapping.json`
5. **Test with qualify tool:** Use a known company ID to verify scoring

---

**Implementation Status:** ✅ Production Ready
**Tested:** ✅ All tests passing
**Documented:** ✅ README updated with examples
