Skip to main content

Vibe Classifier Training Guide

This guide explains how to use the Nyckel classifier training utilities for organizing and training vibe taxonomies.

Overview​

The vibe classifier training system allows you to:

  • Organize vibes into hierarchical taxonomies (Energy Level, Aesthetic, Status, etc.)
  • Generate training datasets from places with existing vibes
  • Export training data to CSV for manual review
  • Create and train Nyckel classifiers for specific taxonomies
  • Upload training samples programmatically

Vibe Taxonomies​

The system organizes vibes into the following taxonomies:

1. Energy Level (energy_level)​

Vibes related to the energy and intensity of a place

  • High/Wild: adrenaline, action, chaotic, crazy, electric, energetic, extreme, intense, loud, rowdy, turnt, popping, lit, hyped, busy, buzzing, crowded, lively, party
  • Chill/Low: calm, chill, laidback, low-key, mellow, quiet, relaxing, serene, slow, sober, soothing, tranquil, zen, peaceful

2. Aesthetic & Decor (aesthetic_decor)​

Visual style and design aesthetics

  • Modern/Clean: airy, bright, chic, clean, contemporary, fresh, futuristic, minimalist, modern, open, polished, sleek
  • Vintage/Old School: analog, antique, art-deco, classic, cottage, cottagecore, mid-century, nostalgic, old, oldschool, retro, rustic, throwback, timeless, vintage
  • Dark/Edgy: dark, dope, eerie, gothic, grimy, grunge, industrial, moody, mysterious, smokey, underground, scary, haunted
  • Arts/Whimsy: absurd, aesthetic, art, artsy, bizarre, bohemian, camp, cinematic, colorful, creative, dreamy, eclectic, fairytale, fantasy, funky, kitsch, magical, psychedelic, quirky, rainbow, strange, surreal, trippy, whimsical

3. Status & Class (status_class)​

Economic and social positioning

  • High End: boujee, classy, deluxe, elegant, exclusive, fancy, glam, highbrow, luxe, luxury, opulent, posh, refined, sophisticated, upscale, vip
  • Accessible/Local: affordable, cheap, dive, local, neighborhood, no-frills, simple, thrift, thrifty

4. Emotional Feel (emotional_feel)​

Emotional atmosphere and vibe

  • Warmth: adorable, charming, comfy, comforting, cozy, friendly, gentle, hearty, homey, hygge, inviting, lovely, sweet, warm, welcoming, wholesome
  • Cool Factor: badass, bussin, cool, drip, epic, famous, flex, hip, hipster, iconic, indie, legendary, legit, radical, sassy, swag, trendy, vibe
  • Romantic: candlelit, datespot, flirty, intimate, love, passionate, romantic, seductive, sensual, sexy

5. Occasions (occasions)​

Specific use cases and occasions

  • Social: after-work, celebration, getaway, hangout, happy-hour, mingle, reunion, staycation, weekend
  • Productive: collaborative, focused, hardworking, meeting, study, work, workshop
  • Personal Care: healing, meditation, pampering, rejuvenating, restorative, selfcare, treatyourself, wellness

6. Demographics & Inclusivity (demographics_inclusivity)​

Community and inclusivity aspects

  • Inclusive: accessible, aware, belonging, community, diverse, family-friendly, feminist, gay, inclusive, lgbtq, queer, safe, solidarity, transgender, women-owned
  • Niche Groups: animals, anime, beatnik, biker, cowboy, gamer, geeky, granola, hippie, nerdy, punk, skater, witchy, wizard, yogi

7. Amenities & Setting (amenities_setting)​

Physical location and attributes

  • Location Type: city-life, coastal, desert, forest, garden, hidden-gem, mountain, ocean, outdoors, panoramic, park, rooftop, scenic, skyline, urban, views, waterfront
  • Physical Attributes: ada-compliant, architecture, big, dog-friendly, historic, landmark, patio, photo-op, photogenic, plant-filled, small, spacious

Usage​

List Available Taxonomies​

python manage.py train_vibe_classifier --list-taxonomies

This displays all available taxonomies with their categories and vibe counts.

Get Taxonomy Information​

python manage.py train_vibe_classifier --taxonomy energy_level --info

Shows detailed information about a specific taxonomy, including all vibes organized by category.

Export Training Data to CSV​

Export training data for manual review or external use:

# Export to file
python manage.py train_vibe_classifier --taxonomy energy_level --export --output energy_level_training.csv

# Control sample size
python manage.py train_vibe_classifier --taxonomy aesthetic_decor --export --output aesthetic.csv --limit-per-vibe 100

# Dry run to see what would be exported
python manage.py train_vibe_classifier --taxonomy emotional_feel --export --dry-run

Create a New Nyckel Classifier​

Create a new classifier function in Nyckel:

# Create with custom name
python manage.py train_vibe_classifier --taxonomy energy_level --create --name "Energy Level Classifier v2"

# Create with auto-generated name
python manage.py train_vibe_classifier --taxonomy aesthetic_decor --create

This will return a function ID that you can use for uploading samples.

Upload Training Samples​

Upload training samples to an existing Nyckel function:

# Upload to existing function
python manage.py train_vibe_classifier --taxonomy energy_level --upload --function-id abc123xyz456

# Control sample size and quality
python manage.py train_vibe_classifier --taxonomy status_class --upload --function-id abc123 --limit-per-vibe 75 --min-text-length 250

# Dry run to preview samples
python manage.py train_vibe_classifier --taxonomy occasions --upload --function-id abc123 --dry-run

Create and Train in One Command​

Create a new classifier and immediately upload training data:

python manage.py train_vibe_classifier \
  --taxonomy energy_level \
  --create \
  --upload \
  --name "Energy Level Classifier" \
  --limit-per-vibe 50

Python API Usage​

You can also use the NyckelTrainer class directly in Python:

from etl.utils.nyckel_trainer import NyckelTrainer, VIBE_TAXONOMIES

# Initialize trainer
trainer = NyckelTrainer()

# List all taxonomies
taxonomies = trainer.list_taxonomies()

# Get vibes for a taxonomy
energy_vibes = trainer.get_taxonomy_vibes('energy_level')
high_energy_vibes = trainer.get_taxonomy_vibes('energy_level', 'high_wild')

# Get taxonomy info
info = trainer.get_taxonomy_info('aesthetic_decor')
print(f"{info['name']}: {info['description']}")

# Generate training samples
samples = trainer.generate_training_samples('energy_level', limit_per_vibe=50)
print(f"Generated {len(samples)} samples")

# Export to CSV
csv_content = trainer.export_training_csv('emotional_feel', output_path='emotional_feel.csv')

# Create new classifier
function_id = trainer.create_classifier_function('My Classifier', 'energy_level')

# Upload samples
stats = trainer.upload_training_samples(function_id, samples)
print(f"Uploaded: {stats['uploaded']}, Failed: {stats['failed']}")

Training Data Quality​

The system automatically:

  • Filters out closed, duplicate places
  • Requires minimum description length (default: 100 chars)
  • Combines name, description, short_description, and tips
  • Cleans and normalizes text
  • Limits samples per vibe to avoid imbalance

Customizing Text Extraction​

# Extract text with different options
text = trainer.extract_text_from_place(
    place,
    include_tips=True,
    include_reviews=False  # Reviews can be noisy
)

Best Practices​

  1. Start with a dry run: Always use --dry-run first to preview what will happen
  2. Review CSV exports: Export and manually review training data before uploading
  3. Balance your dataset: Use --limit-per-vibe to prevent overrepresentation
  4. Iterate on min-text-length: Adjust based on your data quality needs
  5. Test with small batches: Start with small --limit-per-vibe values and scale up
  6. Monitor upload stats: Check the upload statistics for errors

Workflow Example​

Complete workflow for training a new classifier:

# 1. Explore the taxonomy
python manage.py train_vibe_classifier --taxonomy energy_level --info

# 2. Preview training data (dry run)
python manage.py train_vibe_classifier --taxonomy energy_level --export --dry-run

# 3. Export for manual review
python manage.py train_vibe_classifier --taxonomy energy_level --export --output review.csv --limit-per-vibe 30

# 4. Review the CSV file manually
# (Check for quality, balance, accuracy)

# 5. Create classifier and upload
python manage.py train_vibe_classifier \
  --taxonomy energy_level \
  --create \
  --upload \
  --name "Energy Level Classifier v1.0" \
  --limit-per-vibe 50 \
  --min-text-length 200

# 6. Note the function ID for future use
# Function ID: abc123xyz456

Troubleshooting​

No places found for a vibe​

Some vibes may not have enough places in the database yet. Check:

  • Are places properly tagged with this vibe?
  • Are there enough places with descriptions?
  • Try lowering --min-text-length

Upload failures​

Common causes:

  • Invalid function ID
  • Network issues
  • API rate limits
  • Authentication problems

Check the error messages in the output for specific issues.

Empty or short text​

If samples have insufficient text:

  • Lower --min-text-length (but maintain quality)
  • Check if places have descriptions
  • Ensure tips and reviews are being included

Advanced Usage​

Training Multiple Taxonomies​

Create a script to train all taxonomies:

#!/bin/bash

TAXONOMIES=(
  "energy_level"
  "aesthetic_decor"
  "status_class"
  "emotional_feel"
  "occasions"
  "demographics_inclusivity"
  "amenities_setting"
)

for taxonomy in "${TAXONOMIES[@]}"; do
  echo "Training $taxonomy..."
  python manage.py train_vibe_classifier \
    --taxonomy "$taxonomy" \
    --create \
    --upload \
    --name "$taxonomy Classifier" \
    --limit-per-vibe 50
done

Updating Existing Classifiers​

To add more training data to an existing classifier:

# Get more samples (increase limit)
python manage.py train_vibe_classifier \
  --taxonomy energy_level \
  --upload \
  --function-id existing_function_id \
  --limit-per-vibe 100

Integration with Existing Code​

This new system complements the existing nlp_categories.py command. You can:

  1. Use the old system for general category classification
  2. Use this new system for specialized vibe taxonomies
  3. Combine predictions from multiple classifiers

Example integration:

from api.management.commands.nlp_categories import TextClassificationMulti
from etl.utils.nyckel_trainer import NyckelTrainer

# Use existing classifier for categories
category_classifier = TextClassificationMulti(which_classifer='place_categories')

# Use new trainer for vibe taxonomies
vibe_trainer = NyckelTrainer()

# Get training data for energy vibes
energy_samples = vibe_trainer.generate_training_samples('energy_level')

Files Created​

  • etl/utils/nyckel_trainer.py - Main trainer utility class
  • api/management/commands/train_vibe_classifier.py - Django management command
  • docs/VIBE_CLASSIFIER_TRAINING.md - This documentation

Next Steps​

  1. Review and adjust taxonomy definitions in nyckel_trainer.py as needed
  2. Export training data for your taxonomies
  3. Create classifiers for each taxonomy you want to use
  4. Integrate classifier predictions into your place/event processing pipeline
  5. Monitor classifier performance and retrain as needed