audience-advisor

Audience Advisor

Purpose

Coaches users toward building the right audience for their business outcome, not just any audience. Uses Lytics analytical APIs -- ML feature importance, content affinities, fieldinfo distributions, segment summaries -- to make evidence-based recommendations. Gracefully degrades when advanced features aren't configured.

Supports two modes:

• Create from goal: "Help me build an audience to drive more purchases"
• Improve existing: "How can I improve my 'High Value Customers' segment?"

Environment

Requires authenticated API access. See ../references/auth.md for credential resolution.

Flow

Step 1: Understand the Intent

Determine which mode the user needs:

Path A -- New audience from a business goal: Ask what they're trying to achieve, not what audience they want:

• "Drive more purchases" -> conversion-focused
• "Re-engage lapsed users" -> retention-focused
• "Grow email subscribers" -> acquisition-focused
• "Promote new product line" -> awareness-focused

Classify the goal type -- this determines which fields and strategies to prioritize later.

Path B -- Improve an existing segment: Accept a segment name or ID. Fetch it and its current FilterQL:

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Find the matching segment, note its current size, and parse its FilterQL to understand existing filters.

Both paths converge at Step 2.

Step 2: Inventory Existing Segments

Fetch all segments to understand what's already built:

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

• Identify segments related to the goal by name, tags, or kind
• Look for "goal" or "conversion" kind segments -- these represent business outcomes and are valuable reference points
• Note total population size for percentage calculations later
• Flag any existing segment that already targets this goal to avoid duplication

Step 3: Gather Analytical Signals

Try each data source. Skip any that return empty or error -- proceed with whatever is available.

3a. ML Feature Importance (best signal, may not exist):

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/ml" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

If models exist, find one whose target segment matches the user's desired outcome. Each model predicts user similarity to its target segment:

• List all models and examine their target segment names/descriptions

• Match target segment against the user's stated goal (e.g., goal = "drive purchases" -> look for models targeting a "purchasers" or "converters" segment)

• If a relevant model is found, fetch its summary:

  curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/ml/${MODEL_ID}/summary" \
    -H "Authorization: ${LYTICS_API_TOKEN}"
  

  The response contains model quality metrics and a features array ranking which fields most differentiate the target audience:

  {
    "data": {
      "id": "model_id",
      "name": "Model Name",
      "state": "completed",
      "summary": {
        "auc": 0.85,
        "accuracy": 0.82,
        "reach": 0.75,
        "model_health": "good",
        "mse": 0.12,
        "rsq": 0.71
      },
      "features": [
        {
          "kind": "score",
          "type": "numeric",
          "name": "visit_count",
          "importance": 1.79,
          "field_prevalence": {"source": 0.30, "target": 0.99},
          "correlation": 0.23,
          "impact": {"lift": 0.35, "threshold": 2}
        }
      ]
    }
  }
  

  Key feature fields for recommendations:

  • name -- the schema field name to filter on
  • importance -- higher = more predictive of target segment membership
  • field_prevalence.source vs .target -- how common the field is in general population vs target (large gap = strong differentiator)
  • correlation -- direction and strength of relationship
  • impact.lift -- how much this field increases likelihood of being in the target
  • impact.threshold -- suggested cutoff value for filtering

• If no model's target segment relates to the goal: skip ML. Tell the user: "No ML model targets this outcome. You could create a lookalike model using your conversion segment as the target to get predictive feature rankings."

• If multiple models could apply: prefer the one whose target segment most closely matches the goal.

• If no models exist at all: skip silently, proceed to next signal.

3b. Content Affinities (may not be configured):

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/content/affinity" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

If affinities exist and a reference segment is available:

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/content/recommend/segment/${SEGMENT_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

This reveals topic interests that differentiate the audience. If not configured: skip silently.

3c. Fieldinfo Analysis (always available -- the baseline):

For a reference segment (goal/conversion segment, or the segment being improved). Important: Use the segment's id hash, not the slug name -- slugs return HTTP 500.

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/fieldinfo?limit=50" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

For segment summary with aspect overlap:

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/summary" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

If no reference segment exists, use schema-level field distributions:

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/schema/user/fieldinfo" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

This always works -- field coverage, value distributions, and cardinality are always available.

Step 4: Synthesize and Recommend

Present findings organized by signal strength:

With ML feature importance:

"Your ML model targeting 'Purchasers' ranks these as the top predictors:

1. visit_count -- users with 5+ visits are 3.2x more likely to convert
2. email_engagement -- engaged email readers convert at 2.8x the baseline
3. products_viewed -- browsing 3+ product categories indicates high intent

I'd recommend building filters around these fields."

With content affinities:

"Your converters over-index on 'Technology' content (3.2x vs baseline) and 'Product Reviews' (2.5x). Consider using content affinity as a targeting signal."

With fieldinfo only (always available):

"Looking at your 'Recent Purchasers' segment:

• 78% have visit_count >= 5 (vs 30% of all users)
• 92% have email populated (good for email campaigns)
• country: 65% US, 15% CA, 10% UK

Filtering on visit_count >= 5 would capture most converters while excluding low-intent users."

For improving existing segments:

"Your 'High Value' segment currently has 50,000 users (35% of total) -- quite broad for targeted campaigns. Here's what I found:

• The filter EXISTS email matches 92% of all users -- it's not adding much selectivity
• Only 20% of this segment has purchase_history populated -- that field may not be useful here
• Adding visit_count >= 5 would narrow to 15,000 (10%) while keeping 78% of your actual converters

Suggested updated FilterQL: FILTER AND (visit_count >= 5, email_engagement > 0.3) FROM user ALIAS high_value_v2"

Step 5: Iterate on Sizing

Test filter variations without creating segments. Show the user how each change affects audience size:

# Get total population size for percentage context
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER * FROM user'

# Test each filter variation
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (visit_count >= 5) FROM user'

Present as incremental refinement:

Starting point: 145,000 total users (100%)

1. visit_count >= 5          -> 43,500 (30%)
2. + email_engagement > 0.3  -> 18,200 (13%)
3. + last_visit > "now-30d"  -> 12,400 (9%)   <-- recommended

This 9% audience captures your highest-intent users with recent activity.

Validate each FilterQL before sizing:

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/validate" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (visit_count >= 5, email_engagement > 0.3, last_visit > "now-30d") FROM user'

Step 6: Confirm and Create

Once the user is satisfied with the proposed audience, hand off to the audience-builder skill to create the segment with the full confirmation gate pattern.

For improving existing segments, use PUT /v2/segment/:id instead.

Step 7: Post-Creation Snapshot

After creation, offer to run an audience-snapshot skill to show the final audience composition and confirm it looks right.

Audience Sizing Guidance

% of Total	Assessment	Best For
< 1%	Very narrow -- may limit reach and statistical significance	Hyper-personalized, VIP programs
1-10%	Well-targeted	Conversion campaigns, retargeting
10-30%	Broad targeting	Awareness campaigns, email blasts
> 30%	Very broad -- consider if tighter targeting would improve ROI	Broad announcements only

Field Selection Guidance by Goal Type

Goal	Preferred Field Types	Why
Conversion/Purchase	Behavioral: visit_count, pages_viewed, cart activity	Actions predict intent better than demographics
Re-engagement/Retention	Temporal: last_visit, last_purchase, recency scores	Recency identifies lapsed users
Awareness/Reach	Demographic: country, industry, interest categories	Broad attributes reach the right population
Email/Channel Growth	Channel: email_opt_in, channel_preferences, engagement scores	Channel-specific signals matter most

Refinement Patterns

• Start broad, narrow incrementally -- show size impact at each step so the user understands the tradeoff
• Use AND for narrowing, OR for expanding -- guide users on composition
• Check field coverage before recommending -- a field with 20% coverage limits the audience to at most 20%
• Prefer INTERSECTS for set fields (e.g., products_purchased), comparison operators for numeric
• Use date math for temporal targeting -- "now-30d" for recent, "now-90d" for medium-term, "now-1y" for long-term

Error Handling

• No ML models: Skip gracefully, rely on fieldinfo analysis. Suggest creating a lookalike model.
• No affinities: Skip silently, proceed with fieldinfo.
• No conversion/goal segments: Ask the user to describe their ideal customer characteristics manually. Use schema discovery to find matching fields.
• Empty segment after filtering: Suggest broadening -- remove the most restrictive filter or adjust thresholds.
• User unsure about goal: Offer common goal categories and let them pick.

Dependencies

• Composes: audience-builder skill, audience-snapshot skill, segment-manager skill, schema-discovery skill
• References: ../references/auth.md, ../references/api-client.md, ../references/field-types.md, ../references/filterql-grammar.md