> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privetag.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Pipeline

> How PriveTag processes context for intelligent recommendations

# Context Pipeline

The Context Pipeline is PriveTag's system for understanding user needs and providing relevant recommendations.

## The 8 Golden Points

We capture 8 key data points that drive recommendation quality:

<CardGroup cols={4}>
  <Card title="1. Travel Type" icon="users">
    Family, couple, solo, business, friends
  </Card>

  <Card title="2. Nationality" icon="flag">
    Cultural preferences and language
  </Card>

  <Card title="3. Interests" icon="heart">
    Activities user enjoys
  </Card>

  <Card title="4. Budget" icon="wallet">
    Spending preferences
  </Card>

  <Card title="5. Age Group" icon="cake-candles">
    Activity difficulty matching
  </Card>

  <Card title="6. Location" icon="location-dot">
    Current or target area
  </Card>

  <Card title="7. Weather" icon="cloud-sun">
    Real-time conditions
  </Card>

  <Card title="8. Time" icon="clock">
    Time of day relevance
  </Card>
</CardGroup>

## Pipeline Architecture

```mermaid theme={null}
graph TD
    subgraph "Input Layer"
        UP[User Profile]
        LOC[Location Data]
        REQ[Request Filters]
    end

    subgraph "Enrichment Layer"
        WX[Weather API]
        TZ[Timezone]
        GT[Ground Truth DB]
    end

    subgraph "Processing Layer"
        NRM[Normalization]
        SCR[Scoring Engine]
        RNK[Ranking Algorithm]
    end

    subgraph "Output Layer"
        REC[Recommendations]
        CTX[Context Log]
    end

    UP --> NRM
    LOC --> WX
    LOC --> TZ
    REQ --> NRM

    WX --> SCR
    TZ --> SCR
    GT --> SCR
    NRM --> SCR

    SCR --> RNK
    RNK --> REC
    RNK --> CTX
```

## Data Flow Example

### Input: API Request

```json theme={null}
{
  "user_profile": {
    "travel_type": "family",
    "nationality": "KR",
    "interests": ["theme-park", "zoo"],
    "budget": "mid"
  },
  "location": {
    "city": "Bangkok",
    "lat": 13.7563,
    "lon": 100.5018
  },
  "limit": 5
}
```

### Step 1: Enrichment

The pipeline enriches the request with external data:

```json theme={null}
{
  "weather": {
    "condition": "sunny",
    "temperature": 32,
    "humidity": 65,
    "is_outdoor_suitable": true
  },
  "time_context": {
    "local_time": "14:30",
    "day_period": "afternoon",
    "is_weekend": true
  }
}
```

### Step 2: Ground Truth Lookup

Query historical data for similar profiles:

```sql theme={null}
-- What did Korean families actually visit in Bangkok?
SELECT activity_id, COUNT(*) as visits
FROM ground_truth
WHERE travel_type = 'family'
  AND nationality = 'KR'
  AND city = 'Bangkok'
  AND is_verified = TRUE
GROUP BY activity_id
ORDER BY visits DESC
```

### Step 3: Scoring

Each activity is scored on multiple factors:

| Factor        | Weight | Safari World | Dream World | Night Market |
| ------------- | ------ | ------------ | ----------- | ------------ |
| Profile Match | 30%    | 28/30        | 25/30       | 15/30        |
| Ground Truth  | 25%    | 24/25        | 20/25       | 10/25        |
| Weather Match | 20%    | 18/20        | 18/20       | 12/20        |
| Time Match    | 15%    | 14/15        | 14/15       | 8/15         |
| Budget Match  | 10%    | 9/10         | 9/10        | 10/10        |
| **Total**     | 100%   | **93**       | **86**      | **55**       |

### Step 4: Output

```json theme={null}
{
  "recommendations": [
    {
      "id": "act_safari",
      "title": "Safari World Bangkok",
      "relevance_score": 93,
      "recommendation_reason": "Top choice for Korean families - verified visits"
    },
    {
      "id": "act_dream",
      "title": "Dream World",
      "relevance_score": 86,
      "recommendation_reason": "Family-friendly theme park for afternoon"
    }
  ],
  "context": {
    "log_id": "ctx_abc123",
    "user_profile_summary": "Korean family, theme-park & zoo interests, mid budget",
    "environment_summary": "Bangkok, sunny 32°C, Saturday afternoon"
  }
}
```

## Scoring Factors Explained

### 1. Profile Match (30%)

How well does the activity match user preferences?

| User Attribute | Matching Logic                   |
| -------------- | -------------------------------- |
| `travel_type`  | Family → kid-friendly activities |
| `interests`    | Direct category match            |
| `budget`       | Price range alignment            |
| `age_group`    | Activity difficulty level        |

### 2. Ground Truth (25%)

Real visit data from similar users:

<Info>
  **Ground Truth Scoring**: Activities that similar profiles actually visited (and verified via NFC/QR) get higher scores than those only booked.
</Info>

```
Score = (verified_visits / total_recommendations) * 25
```

### 3. Weather Match (20%)

Real-time weather appropriateness:

| Condition      | Indoor Activities | Outdoor Activities |
| -------------- | ----------------- | ------------------ |
| Sunny, \< 35°C | 15/20             | 20/20              |
| Sunny, > 35°C  | 18/20             | 10/20              |
| Rainy          | 20/20             | 5/20               |
| Overcast       | 17/20             | 18/20              |

### 4. Time Match (15%)

Activity timing relevance:

| Time Period       | Best Activities                  |
| ----------------- | -------------------------------- |
| Morning (6-11)    | Tours, outdoor, breakfast spots  |
| Afternoon (11-17) | Theme parks, museums, malls      |
| Evening (17-21)   | Dinner, shows, sunset activities |
| Night (21+)       | Nightlife, late dining           |

### 5. Budget Match (10%)

Price alignment with stated budget:

```
budget: "budget"  → Activities < 500 THB score highest
budget: "mid"     → Activities 500-2000 THB score highest
budget: "luxury"  → Activities > 2000 THB score highest
```

## Context Logging

Every recommendation request creates a context log:

```json theme={null}
{
  "log_id": "ctx_abc123",
  "created_at": "2025-12-10T14:30:00Z",
  "input": {
    "user_profile": { /* ... */ },
    "location": { /* ... */ }
  },
  "enriched": {
    "weather": { /* ... */ },
    "time_context": { /* ... */ }
  },
  "ground_truth_matches": 45,
  "recommended_activities": ["act_safari", "act_dream", "act_sea"],
  "scores": {
    "act_safari": 93,
    "act_dream": 86,
    "act_sea": 78
  }
}
```

### Why Context Logging Matters

When a user later books and visits an activity:

```mermaid theme={null}
graph LR
    A[Context Log Created] --> B[User Selects Activity]
    B --> C[Booking Created]
    C --> D[User Visits Venue]
    D --> E[QR Verified]
    E --> F[Ground Truth Recorded]
    F --> G[Linked to Context Log]
    G --> H[Future Recommendations Improved]
```

This **feedback loop** is what makes PriveTag's recommendations improve over time.

## Customization Options

### Filters

Override automatic scoring with explicit filters:

```json theme={null}
{
  "filters": {
    "is_indoor": true,      // Force indoor only
    "max_price": 2000,      // Price ceiling
    "categories": ["spa"],  // Specific categories
    "difficulty": "easy"    // Activity intensity
  }
}
```

### Boosting

Boost specific factors for the request:

```json theme={null}
{
  "scoring_weights": {
    "ground_truth": 0.4,    // Increase GT weight from 25% to 40%
    "weather": 0.1          // Decrease weather weight from 20% to 10%
  }
}
```

## Performance

| Metric                   | Value      |
| ------------------------ | ---------- |
| Average Processing Time  | \< 200ms   |
| Weather API Cache TTL    | 15 minutes |
| Ground Truth Query Cache | 1 hour     |
| Max Concurrent Requests  | 1000/sec   |

## Best Practices

<AccordionGroup>
  <Accordion title="Always provide lat/lon when available">
    Location coordinates enable weather-aware recommendations. Without them, we default to city-level weather which may be less accurate.
  </Accordion>

  <Accordion title="Include all known user attributes">
    More context = better recommendations. Even if optional, providing nationality, age\_group, and budget significantly improves relevance.
  </Accordion>

  <Accordion title="Use context_log_id for bookings">
    Pass the log\_id when booking to complete the feedback loop. This is how Ground Truth data improves over time.
  </Accordion>

  <Accordion title="Don't over-filter">
    Let the scoring algorithm work. Excessive filters can eliminate good options that would score highly.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Ground Truth" icon="check-double" href="/b2a-platform/ground-truth">
    How verified behavior data works
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/b2a/recommend">
    Implement recommendations
  </Card>
</CardGroup>