ml/ml-intent-classifier

ML Intent Classifier

Classify message intent, urgency, and emotional tone using LLM analysis.

Installation

pip install lilith-ml-intent-classifier

Usage

from ml_intent_classifier import IntentClassifier, Intent

# Create classifier with your LLM client
classifier = IntentClassifier(model_client=llm)

# Classify a message
intent = await classifier.classify("Hey, are you free Saturday?")

print(intent.primary)               # PrimaryIntent.QUESTION
print(intent.urgency)               # 0.3
print(intent.emotional_tone)        # EmotionalTone.NEUTRAL
print(intent.topic)                 # TopicCategory.LOGISTICAL
print(intent.suggested_response_style)  # ResponseStyle.CASUAL

Classification Dimensions

Primary Intent

• question - Seeking information or clarification
• statement - Declarative or informative message
• request - Asking someone to do something
• greeting - Opening or initiating contact
• farewell - Closing or ending contact
• reaction - Emotional response to something
• acknowledgment - Confirming understanding or receipt

Urgency (0.0 - 1.0)

Score indicating message urgency, boosted by keywords like "urgent", "ASAP", "emergency".

Emotional Tone

• positive - Happy, excited, enthusiastic, grateful
• negative - Sad, angry, frustrated, disappointed
• neutral - Matter-of-fact, informational
• mixed - Contains elements of multiple tones

Topic

• personal - About personal life, relationships, emotions
• professional - Work-related, business, career
• casual - Small talk, general conversation
• logistical - Scheduling, planning, coordination

Suggested Response Style

• formal - Professional, structured response
• casual - Relaxed, friendly tone
• empathetic - Supportive, understanding approach
• brief - Short, to-the-point response

Configuration

from ml_intent_classifier import IntentClassifier, ClassifierConfig

config = ClassifierConfig(
    cache_enabled=True,          # Cache classification results
    cache_max_size=1000,         # Maximum cache entries
    urgency_keyword_boost=0.3,   # Urgency boost for keywords
    fallback_on_error=True,      # Return default on LLM error
)

classifier = IntentClassifier(model_client=llm, config=config)

LLM Client Protocol

Your LLM client must implement the async generate method:

class MyLLMClient:
    async def generate(
        self,
        messages: list[dict[str, str]],
        **kwargs,
    ) -> str:
        # messages format: [{"role": "system", "content": "..."}, ...]
        # Return the model's response text
        ...

Intent Properties

intent = await classifier.classify("URGENT: Need help immediately!")

intent.is_urgent       # True if urgency >= 0.7
intent.is_positive     # True if emotional_tone is POSITIVE
intent.is_negative     # True if emotional_tone is NEGATIVE
intent.needs_action    # True if REQUEST or urgent QUESTION
intent.raw_message     # Original message text

Confidence Scores

Access per-dimension confidence scores:

intent.confidence.primary_intent   # 0.0-1.0
intent.confidence.urgency          # 0.0-1.0
intent.confidence.emotional_tone   # 0.0-1.0
intent.confidence.topic            # 0.0-1.0
intent.confidence.response_style   # 0.0-1.0
intent.confidence.overall          # 0.0-1.0

Batch Classification

messages = [
    "Hello there!",
    "What time is the meeting?",
    "Thanks for the help!",
]

intents = await classifier.classify_batch(messages)

Cache Management

classifier.cache_size   # Current number of cached results
classifier.clear_cache()  # Clear all cached results

License

MIT