tritopic 0.1.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

tritopic/labeling/__init__.py

@@ -1,5 +0,0 @@
-"""LLM-based topic labeling for TriTopic."""
-
-from tritopic.labeling.llm_labeler import LLMLabeler
-
-__all__ = ["LLMLabeler"]

tritopic/labeling/llm_labeler.py

@@ -1,279 +0,0 @@
-"""
-LLM-based Topic Labeling
-=========================
-
-Generate human-readable topic labels using LLMs:
-- Claude (Anthropic)
-- GPT-4 (OpenAI)
-"""
-
-from __future__ import annotations
-
-from typing import Literal
-import json
-
-
-class LLMLabeler:
-    """
-    Generate topic labels using Large Language Models.
-    
-    Uses LLMs to create meaningful, human-readable labels for topics
-    based on their keywords and representative documents.
-    
-    Parameters
-    ----------
-    provider : str
-        LLM provider: "anthropic" or "openai"
-    api_key : str
-        API key for the provider.
-    model : str, optional
-        Model name. Defaults to best available model.
-    max_tokens : int
-        Maximum tokens in response. Default: 200
-    temperature : float
-        Sampling temperature. Default: 0.3
-    language : str
-        Output language. Default: "english"
-    """
-    
-    def __init__(
-        self,
-        provider: Literal["anthropic", "openai"] = "anthropic",
-        api_key: str | None = None,
-        model: str | None = None,
-        max_tokens: int = 200,
-        temperature: float = 0.3,
-        language: str = "english",
-    ):
-        self.provider = provider
-        self.api_key = api_key
-        self.model = model or self._default_model()
-        self.max_tokens = max_tokens
-        self.temperature = temperature
-        self.language = language
-        
-        self._client = None
-    
-    def _default_model(self) -> str:
-        """Get default model for provider."""
-        if self.provider == "anthropic":
-            return "claude-3-haiku-20240307"
-        else:
-            return "gpt-4o-mini"
-    
-    def _init_client(self):
-        """Initialize API client."""
-        if self._client is not None:
-            return
-        
-        if self.provider == "anthropic":
-            try:
-                from anthropic import Anthropic
-                self._client = Anthropic(api_key=self.api_key)
-            except ImportError:
-                raise ImportError(
-                    "anthropic package not installed. "
-                    "Install with: pip install anthropic"
-                )
-        else:
-            try:
-                from openai import OpenAI
-                self._client = OpenAI(api_key=self.api_key)
-            except ImportError:
-                raise ImportError(
-                    "openai package not installed. "
-                    "Install with: pip install openai"
-                )
-    
-    def generate_label(
-        self,
-        keywords: list[str],
-        representative_docs: list[str],
-        domain_hint: str | None = None,
-    ) -> tuple[str, str]:
-        """
-        Generate a label for a topic.
-        
-        Parameters
-        ----------
-        keywords : list[str]
-            Topic keywords (top 10 recommended).
-        representative_docs : list[str]
-            Representative documents for the topic.
-        domain_hint : str, optional
-            Domain context (e.g., "tourism", "technology").
-            
-        Returns
-        -------
-        label : str
-            Short topic label (2-5 words).
-        description : str
-            Brief description of the topic.
-        """
-        self._init_client()
-        
-        # Build prompt
-        prompt = self._build_prompt(keywords, representative_docs, domain_hint)
-        
-        # Call API
-        if self.provider == "anthropic":
-            response = self._call_anthropic(prompt)
-        else:
-            response = self._call_openai(prompt)
-        
-        # Parse response
-        label, description = self._parse_response(response)
-        
-        return label, description
-    
-    def _build_prompt(
-        self,
-        keywords: list[str],
-        representative_docs: list[str],
-        domain_hint: str | None = None,
-    ) -> str:
-        """Build the labeling prompt."""
-        # Truncate long documents
-        docs_text = ""
-        for i, doc in enumerate(representative_docs[:5], 1):
-            truncated = doc[:500] + "..." if len(doc) > 500 else doc
-            docs_text += f"\nDocument {i}: {truncated}\n"
-        
-        domain_context = ""
-        if domain_hint:
-            domain_context = f"\nDomain context: This is about {domain_hint}.\n"
-        
-        prompt = f"""You are an expert at creating concise, meaningful topic labels.
-
-Given the following information about a topic, create:
-1. A SHORT LABEL (2-5 words, title case, no special characters)
-2. A BRIEF DESCRIPTION (1-2 sentences explaining what this topic is about)
-
-Keywords (most representative words for this topic):
-{', '.join(keywords[:10])}
-
-Representative Documents:
-{docs_text}
-{domain_context}
-Requirements:
-- The label should be specific and descriptive, not generic
-- The label should capture the main theme, not just list keywords
-- The description should explain what documents in this topic discuss
-- Output in {self.language}
-
-Respond in this exact JSON format:
-{{"label": "Your Topic Label", "description": "Your brief description."}}
-
-JSON response:"""
-        
-        return prompt
-    
-    def _call_anthropic(self, prompt: str) -> str:
-        """Call Anthropic API."""
-        response = self._client.messages.create(
-            model=self.model,
-            max_tokens=self.max_tokens,
-            temperature=self.temperature,
-            messages=[{"role": "user", "content": prompt}],
-        )
-        return response.content[0].text
-    
-    def _call_openai(self, prompt: str) -> str:
-        """Call OpenAI API."""
-        response = self._client.chat.completions.create(
-            model=self.model,
-            max_tokens=self.max_tokens,
-            temperature=self.temperature,
-            messages=[{"role": "user", "content": prompt}],
-        )
-        return response.choices[0].message.content
-    
-    def _parse_response(self, response: str) -> tuple[str, str]:
-        """Parse LLM response to extract label and description."""
-        try:
-            # Try to parse as JSON
-            # Find JSON in response
-            start = response.find("{")
-            end = response.rfind("}") + 1
-            
-            if start != -1 and end > start:
-                json_str = response[start:end]
-                data = json.loads(json_str)
-                
-                label = data.get("label", "Unknown Topic")
-                description = data.get("description", "")
-                
-                return label, description
-        except (json.JSONDecodeError, KeyError):
-            pass
-        
-        # Fallback: extract from text
-        lines = response.strip().split("\n")
-        label = lines[0] if lines else "Unknown Topic"
-        description = " ".join(lines[1:]) if len(lines) > 1 else ""
-        
-        # Clean up
-        label = label.replace('"', "").replace("Label:", "").strip()
-        description = description.replace('"', "").replace("Description:", "").strip()
-        
-        return label, description
-    
-    def generate_labels_batch(
-        self,
-        topics_data: list[dict],
-        domain_hint: str | None = None,
-    ) -> list[tuple[str, str]]:
-        """
-        Generate labels for multiple topics.
-        
-        Parameters
-        ----------
-        topics_data : list[dict]
-            List of dicts with "keywords" and "representative_docs".
-        domain_hint : str, optional
-            Domain context.
-            
-        Returns
-        -------
-        labels : list[tuple[str, str]]
-            List of (label, description) tuples.
-        """
-        results = []
-        
-        for topic in topics_data:
-            label, desc = self.generate_label(
-                keywords=topic["keywords"],
-                representative_docs=topic["representative_docs"],
-                domain_hint=domain_hint,
-            )
-            results.append((label, desc))
-        
-        return results
-
-
-class SimpleLabeler:
-    """
-    Simple rule-based labeler (no LLM required).
-    
-    Creates labels from top keywords.
-    """
-    
-    def __init__(self, n_words: int = 3):
-        self.n_words = n_words
-    
-    def generate_label(
-        self,
-        keywords: list[str],
-        **kwargs,
-    ) -> tuple[str, str]:
-        """Generate label from top keywords."""
-        # Take top n keywords
-        top_keywords = keywords[:self.n_words]
-        
-        # Title case
-        label = " & ".join(kw.title() for kw in top_keywords)
-        
-        # Description from more keywords
-        description = f"Topics related to: {', '.join(keywords[:6])}"
-        
-        return label, description

tritopic/utils/__init__.py

@@ -1,13 +0,0 @@
-"""Utility functions for TriTopic."""
-
-from tritopic.utils.metrics import (
-    compute_coherence,
-    compute_diversity,
-    compute_stability,
-)
-
-__all__ = [
-    "compute_coherence",
-    "compute_diversity", 
-    "compute_stability",
-]

tritopic/utils/metrics.py

@@ -1,254 +0,0 @@
-"""
-Evaluation Metrics for Topic Models
-====================================
-
-Provides standard metrics for evaluating topic model quality:
-- Coherence (NPMI, CV)
-- Diversity
-- Stability (ARI between runs)
-"""
-
-from __future__ import annotations
-
-import numpy as np
-from collections import Counter
-from itertools import combinations
-
-
-def compute_coherence(
-    keywords: list[str],
-    documents: list[str],
-    method: str = "npmi",
-    window_size: int = 10,
-) -> float:
-    """
-    Compute topic coherence based on keyword co-occurrence.
-    
-    Parameters
-    ----------
-    keywords : list[str]
-        Topic keywords.
-    documents : list[str]
-        Documents used to compute co-occurrence.
-    method : str
-        Coherence method: "npmi" (default), "uci", "umass"
-    window_size : int
-        Window size for co-occurrence. Default: 10
-        
-    Returns
-    -------
-    coherence : float
-        Coherence score (higher is better).
-    """
-    if len(keywords) < 2:
-        return 0.0
-    
-    # Tokenize documents
-    def tokenize(text):
-        import re
-        return set(re.findall(r'\b\w+\b', text.lower()))
-    
-    doc_tokens = [tokenize(doc) for doc in documents]
-    n_docs = len(documents)
-    
-    # Count document frequencies
-    word_doc_freq = Counter()
-    for tokens in doc_tokens:
-        for word in tokens:
-            word_doc_freq[word] += 1
-    
-    # Count co-occurrences (document-level)
-    pair_doc_freq = Counter()
-    for tokens in doc_tokens:
-        for w1, w2 in combinations(keywords, 2):
-            if w1.lower() in tokens and w2.lower() in tokens:
-                pair_doc_freq[(w1.lower(), w2.lower())] += 1
-    
-    # Compute coherence
-    coherence_scores = []
-    
-    for w1, w2 in combinations(keywords, 2):
-        w1_lower, w2_lower = w1.lower(), w2.lower()
-        
-        freq_w1 = word_doc_freq.get(w1_lower, 0)
-        freq_w2 = word_doc_freq.get(w2_lower, 0)
-        freq_pair = pair_doc_freq.get((w1_lower, w2_lower), 0)
-        
-        if freq_w1 == 0 or freq_w2 == 0:
-            continue
-        
-        if method == "npmi":
-            # Normalized Pointwise Mutual Information
-            p_w1 = freq_w1 / n_docs
-            p_w2 = freq_w2 / n_docs
-            p_pair = (freq_pair + 1) / n_docs  # Add-1 smoothing
-            
-            pmi = np.log(p_pair / (p_w1 * p_w2 + 1e-10))
-            npmi = pmi / (-np.log(p_pair + 1e-10) + 1e-10)
-            coherence_scores.append(npmi)
-            
-        elif method == "uci":
-            # UCI coherence
-            p_pair = (freq_pair + 1) / n_docs
-            p_w1 = freq_w1 / n_docs
-            p_w2 = freq_w2 / n_docs
-            
-            pmi = np.log(p_pair / (p_w1 * p_w2 + 1e-10))
-            coherence_scores.append(pmi)
-            
-        elif method == "umass":
-            # UMass coherence
-            if freq_w2 > 0:
-                score = np.log((freq_pair + 1) / freq_w2)
-                coherence_scores.append(score)
-    
-    return float(np.mean(coherence_scores)) if coherence_scores else 0.0
-
-
-def compute_diversity(
-    all_keywords: list[str],
-    n_topics: int,
-) -> float:
-    """
-    Compute topic diversity (proportion of unique keywords).
-    
-    Diversity measures how different topics are from each other.
-    A model where every topic has the same keywords has diversity 0.
-    
-    Parameters
-    ----------
-    all_keywords : list[str]
-        All keywords from all topics (flattened).
-    n_topics : int
-        Number of topics.
-        
-    Returns
-    -------
-    diversity : float
-        Diversity score between 0 and 1 (higher is better).
-    """
-    if not all_keywords or n_topics == 0:
-        return 0.0
-    
-    unique_keywords = set(kw.lower() for kw in all_keywords)
-    
-    # Diversity = unique keywords / total keywords
-    diversity = len(unique_keywords) / len(all_keywords)
-    
-    return float(diversity)
-
-
-def compute_stability(
-    partitions: list[np.ndarray],
-) -> float:
-    """
-    Compute clustering stability as average pairwise ARI.
-    
-    Parameters
-    ----------
-    partitions : list[np.ndarray]
-        Multiple cluster assignments from different runs.
-        
-    Returns
-    -------
-    stability : float
-        Average Adjusted Rand Index between partitions.
-    """
-    from sklearn.metrics import adjusted_rand_score
-    
-    if len(partitions) < 2:
-        return 1.0
-    
-    ari_scores = []
-    for i in range(len(partitions)):
-        for j in range(i + 1, len(partitions)):
-            ari = adjusted_rand_score(partitions[i], partitions[j])
-            ari_scores.append(ari)
-    
-    return float(np.mean(ari_scores))
-
-
-def compute_silhouette(
-    embeddings: np.ndarray,
-    labels: np.ndarray,
-) -> float:
-    """
-    Compute silhouette score for cluster quality.
-    
-    Parameters
-    ----------
-    embeddings : np.ndarray
-        Document embeddings.
-    labels : np.ndarray
-        Cluster assignments.
-        
-    Returns
-    -------
-    silhouette : float
-        Silhouette score between -1 and 1 (higher is better).
-    """
-    from sklearn.metrics import silhouette_score
-    
-    # Filter out outliers
-    mask = labels != -1
-    if mask.sum() < 2:
-        return 0.0
-    
-    unique_labels = np.unique(labels[mask])
-    if len(unique_labels) < 2:
-        return 0.0
-    
-    return float(silhouette_score(embeddings[mask], labels[mask]))
-
-
-def compute_downstream_score(
-    embeddings: np.ndarray,
-    labels: np.ndarray,
-    y_true: np.ndarray,
-    task: str = "classification",
-) -> float:
-    """
-    Evaluate topic model by downstream task performance.
-    
-    Parameters
-    ----------
-    embeddings : np.ndarray
-        Document embeddings.
-    labels : np.ndarray
-        Topic assignments.
-    y_true : np.ndarray
-        True labels for downstream task.
-    task : str
-        Task type: "classification" or "clustering"
-        
-    Returns
-    -------
-    score : float
-        Task-specific score.
-    """
-    from sklearn.linear_model import LogisticRegression
-    from sklearn.metrics import f1_score, adjusted_rand_score
-    from sklearn.model_selection import cross_val_score
-    
-    # Create topic features (one-hot + embedding)
-    n_topics = len(np.unique(labels[labels != -1]))
-    
-    # One-hot encode topics
-    topic_features = np.zeros((len(labels), n_topics + 1))
-    for i, label in enumerate(labels):
-        if label == -1:
-            topic_features[i, -1] = 1  # Outlier feature
-        else:
-            topic_features[i, label] = 1
-    
-    # Combine with embeddings
-    features = np.hstack([embeddings, topic_features])
-    
-    if task == "classification":
-        # Cross-validated F1
-        clf = LogisticRegression(max_iter=1000, random_state=42)
-        scores = cross_val_score(clf, features, y_true, cv=5, scoring="f1_macro")
-        return float(np.mean(scores))
-    else:
-        # Clustering ARI
-        return float(adjusted_rand_score(labels, y_true))

tritopic/visualization/__init__.py

@@ -1,5 +0,0 @@
-"""Visualization components for TriTopic."""
-
-from tritopic.visualization.plotter import TopicVisualizer
-
-__all__ = ["TopicVisualizer"]