Taxonomy & Tagging

​

The 8 categories

​

Why per-category floors

• Precision-critical (hook_type, cta_style, format) — wrong tags here directly poison downstream signals like exhaustion. High floor (0.7+) means we’d rather miss a tag than misattribute one.
• Inherently fuzzy (emotion, audience_signal, pace, visual_style) — the model’s confidence on these will rarely exceed 0.6 even when correct. Lower floors (0.5–0.55) keep recall reasonable.
• Middle ground (messaging_theme) — narrative themes are objectively identifiable but the model can drift. 0.65 splits the difference.

​

System tag inventory

​

Vision prompt — taxonomy injection

Allowed taxonomy (use exactly these slugs):
  hook_type: before_after, celebrity_endorsement, curiosity_gap, demonstration, ...
  format: animation, dialog_skit, lifestyle, live_action_review, ...
  visual_style: bold_color, brand_aligned, high_contrast, ...
  pace: fast_cut, medium, slow_burn, static_image
  emotion: aspirational, calm, confident, ...
  cta_style: discount, implicit, learn_more, none, shop_now, subscribe
  audience_signal: fitness, gen_x, gen_z, luxury, ...
  messaging_theme: comparison, education, founder_story, ...

​

How auto-tags get promoted

{
  "auto_tags": [
    {"category": "hook_type", "slug": "testimonial",
     "confidence": 0.88, "evidence": "voiceover: 'this changed my routine'"},
    {"category": "format", "slug": "ugc",
     "confidence": 0.92, "evidence": "hand-held vertical, no studio polish"},
    {"category": "emotion", "slug": "relatable",
     "confidence": 0.55, "evidence": "casual tone, kitchen setting"},
    ...
  ]
}

1. Skip if confidence < per-category floor. A hook_type tag at 0.7 is dropped (floor 0.75); the same emotion tag at 0.55 is kept (floor 0.5).
2. Skip if the (category, slug) pair isn’t a system tag. No invented slugs.
3. Skip if client_id is empty. Auto-tag rows without a tenant would collide in the unique constraint.
4. Upsert via _upsert_assignment:
   • If no row exists for (tag, creative_id) → create with source='auto'.
   • If a row exists with source='manual' → leave it alone. Manual tags are never overwritten.
   • If a row exists with source='auto' → refresh confidence + evidence so re-analyses pick up improvements.
5. IntegrityError is caught — concurrent re-fires from the sweep + the post_save signal hitting the same creative would otherwise race; the catch path falls through to the refresh branch.

​

What v2 explicitly removed

​

Custom tags per tenant

• The frontend Creative Library’s tag editor (calls POST /api/marketing_resources/creative_tags/).
• A bulk-assign endpoint at POST /api/marketing_resources/creative_tags/bulk_assign/.

​

Endpoints

​

Extending the taxonomy

from django.db import migrations

NEW_TAGS = [
    ('founder_voiceover', 'Founder Voiceover', '#10b981', 'mic'),
    ('skit_series',       'Skit Series',       '#f59e0b', 'theater_comedy'),
]

def seed(apps, schema_editor):
    Category = apps.get_model('marketing_resources', 'CreativeTagCategory')
    Tag = apps.get_model('marketing_resources', 'CreativeTag')

    fmt = Category.objects.get(slug='format', is_system=True)
    for slug, name, color, icon in NEW_TAGS:
        Tag.objects.update_or_create(
            slug=slug, category=fmt, is_system=True,
            defaults={'name': name, 'color': color, 'icon': icon,
                      'client_id': '__system__'},
        )

class Migration(migrations.Migration):
    dependencies = [('marketing_resources', '0013_messaging_theme_seed')]
    operations = [migrations.RunPython(seed, migrations.RunPython.noop)]

• Display names must be unique within client_id='__system__' (the constraint is (lower(name), client_id)). If the new tag’s display name collides with an existing one, prefix it (e.g. "Theme: Problem → Solution" vs "Problem → Solution").
• Once seeded, the vision prompt picks up the new slug on the next call — no code change needed. The auto-tagger will start emitting it as soon as the model believes a creative matches.

​

Where the code lives

• marketing_resources/models/creative_tag.py — CreativeTagCategory, CreativeTag, CreativeTagAssignment.
• marketing_resources/migrations/0010_creative_taxonomy_seed.py — original 7-category seed.
• marketing_resources/migrations/0013_messaging_theme_seed.py — adds messaging_theme + per-category floors.
• knowledge_base/creative_analysis.py:_allowed_taxonomy_block — vision prompt injection.
• knowledge_base/creative_analysis.py:_apply_auto_tags — promotion + floor enforcement.
• marketing_resources/views/creative_taxonomy.py — the read endpoint.