langgraph-tavily 0.1.0__tar.gz

langgraph_tavily-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langgraph_tavily-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: langgraph-tavily
+Version: 0.1.0
+Summary: Language analyser for trivia questions — parse, classify, and score question difficulty
+Project-URL: Homepage, https://github.com/brnv/langgraph-tavily
+Author-email: Artem <brnv@canva.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: language,nlp,question-analysis,quiz,trivia
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# langgraph-tavily
+
+Language analyser for trivia questions. Parse, classify, and score question difficulty using linguistic features.
+
+## Installation
+
+```bash
+pip install langgraph-tavily
+```
+
+## Usage
+
+```python
+from langgraph_tavily import TriviaAnalyser, TriviaGenerator
+
+# Analyse a question
+analyser = TriviaAnalyser()
+result = analyser.analyse("What ancient wonder was located in Alexandria?")
+print(result.difficulty)        # hard
+print(result.question_type)     # what
+print(result.category)          # history
+print(result.difficulty_score)  # 0.52
+print(result.keywords)          # ['ancient', 'wonder', 'located', 'alexandria']
+
+# Compare two questions
+cmp = analyser.compare(
+    "What color is the sky?",
+    "In what year was the Treaty of Westphalia signed?"
+)
+print(cmp["harder"])  # q2
+
+# Generate a quiz
+gen = TriviaGenerator()
+quiz = gen.quiz(count=10, mix=True)
+for q in quiz:
+    print(q.text)
+```
+
+## CLI
+
+```bash
+langgraph-tavily analyse "Who composed The Rite of Spring?"
+langgraph-tavily analyse "What is 2+2?" --json
+langgraph-tavily compare "What is the capital of France?" "Which element has atomic number 79?"
+langgraph-tavily quiz --count 5 --difficulty medium --show-answers
+langgraph-tavily batch questions.txt --json
+```
+
+## License
+
+MIT

langgraph_tavily-0.1.0/README.md

@@ -0,0 +1,51 @@
+# langgraph-tavily
+
+Language analyser for trivia questions. Parse, classify, and score question difficulty using linguistic features.
+
+## Installation
+
+```bash
+pip install langgraph-tavily
+```
+
+## Usage
+
+```python
+from langgraph_tavily import TriviaAnalyser, TriviaGenerator
+
+# Analyse a question
+analyser = TriviaAnalyser()
+result = analyser.analyse("What ancient wonder was located in Alexandria?")
+print(result.difficulty)        # hard
+print(result.question_type)     # what
+print(result.category)          # history
+print(result.difficulty_score)  # 0.52
+print(result.keywords)          # ['ancient', 'wonder', 'located', 'alexandria']
+
+# Compare two questions
+cmp = analyser.compare(
+    "What color is the sky?",
+    "In what year was the Treaty of Westphalia signed?"
+)
+print(cmp["harder"])  # q2
+
+# Generate a quiz
+gen = TriviaGenerator()
+quiz = gen.quiz(count=10, mix=True)
+for q in quiz:
+    print(q.text)
+```
+
+## CLI
+
+```bash
+langgraph-tavily analyse "Who composed The Rite of Spring?"
+langgraph-tavily analyse "What is 2+2?" --json
+langgraph-tavily compare "What is the capital of France?" "Which element has atomic number 79?"
+langgraph-tavily quiz --count 5 --difficulty medium --show-answers
+langgraph-tavily batch questions.txt --json
+```
+
+## License
+
+MIT

langgraph_tavily-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langgraph-tavily"
+version = "0.1.0"
+description = "Language analyser for trivia questions — parse, classify, and score question difficulty"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Artem", email = "brnv@canva.com" },
+]
+keywords = ["trivia", "language", "nlp", "quiz", "question-analysis"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: Linguistic",
+]
+
+[project.urls]
+Homepage = "https://github.com/brnv/langgraph-tavily"
+
+[project.scripts]
+langgraph-tavily = "langgraph_tavily.cli:main"

langgraph_tavily-0.1.0/src/langgraph_tavily/__init__.py

@@ -0,0 +1,16 @@
+"""langgraph-tavily: Language analyser for trivia questions."""
+
+__version__ = "0.1.0"
+
+from .analyser import TriviaAnalyser
+from .models import TriviaQuestion, QuestionType, Difficulty, AnalysisResult
+from .generator import TriviaGenerator
+
+__all__ = [
+    "TriviaAnalyser",
+    "TriviaQuestion",
+    "QuestionType",
+    "Difficulty",
+    "AnalysisResult",
+    "TriviaGenerator",
+]

langgraph_tavily-0.1.0/src/langgraph_tavily/analyser.py

@@ -0,0 +1,238 @@
+"""Trivia question analyser — classifies, scores, and extracts features."""
+
+from __future__ import annotations
+
+import math
+import re
+import string
+from collections import Counter
+
+from .models import (
+    TriviaQuestion, QuestionType, Difficulty, Category,
+    AnalysisResult,
+)
+
+# Common/easy words that reduce difficulty
+_COMMON_WORDS = frozenset(
+    "the a an is are was were be been being have has had do does did will would "
+    "shall should may might can could of in to for on with at by from as into "
+    "about between through during before after above below up down out off over "
+    "under again further then once and but or nor not so yet both either neither "
+    "each every all any few more most other some such no only own same than too "
+    "very just don also back even still already almost always never often "
+    "sometimes usually what which who whom whose where when why how".split()
+)
+
+# Category keyword mapping
+_CATEGORY_KEYWORDS: dict[Category, set[str]] = {
+    Category.SCIENCE: {"atom", "molecule", "element", "chemical", "physics", "biology",
+                       "cell", "dna", "planet", "gravity", "electron", "nucleus", "species",
+                       "evolution", "quantum", "telescope", "laboratory", "experiment"},
+    Category.HISTORY: {"war", "king", "queen", "empire", "dynasty", "century", "ancient",
+                       "medieval", "revolution", "president", "battle", "treaty", "colonial",
+                       "civilization", "pharaoh", "emperor"},
+    Category.GEOGRAPHY: {"country", "capital", "continent", "ocean", "river", "mountain",
+                         "island", "desert", "lake", "border", "population", "latitude",
+                         "longitude", "hemisphere"},
+    Category.ENTERTAINMENT: {"movie", "film", "actor", "actress", "director", "oscar",
+                             "show", "series", "episode", "character", "hollywood", "disney"},
+    Category.SPORTS: {"goal", "team", "player", "championship", "olympic", "medal",
+                      "score", "league", "cup", "match", "tournament", "coach", "athlete"},
+    Category.ART: {"painting", "sculpture", "artist", "museum", "gallery", "canvas",
+                   "portrait", "renaissance", "impressionism"},
+    Category.LITERATURE: {"novel", "author", "book", "poem", "poet", "chapter",
+                          "fiction", "publisher", "literary", "shakespeare"},
+    Category.MUSIC: {"song", "band", "album", "singer", "composer", "symphony",
+                     "guitar", "piano", "concert", "grammy", "genre", "melody"},
+    Category.FOOD: {"recipe", "cuisine", "dish", "ingredient", "chef", "restaurant",
+                    "flavor", "spice", "cook", "bake", "wine", "beer"},
+    Category.TECHNOLOGY: {"computer", "software", "programming", "internet", "algorithm",
+                          "digital", "robot", "ai", "silicon", "processor", "server"},
+    Category.NATURE: {"animal", "plant", "tree", "flower", "forest", "habitat",
+                      "ecosystem", "endangered", "predator", "prey", "migration"},
+    Category.MATH: {"equation", "theorem", "prime", "geometry", "algebra", "calculus",
+                    "probability", "fraction", "pi", "infinity", "fibonacci"},
+}
+
+
+class TriviaAnalyser:
+    """Analyse trivia questions for type, difficulty, category, and language features."""
+
+    def analyse(self, question: TriviaQuestion | str) -> AnalysisResult:
+        """Fully analyse a trivia question."""
+        if isinstance(question, str):
+            question = TriviaQuestion(text=question)
+
+        text = question.text.strip()
+        words = self._tokenize(text)
+        q_type = self._classify_type(text)
+        category = self._classify_category(words)
+        keywords = self._extract_keywords(words)
+        readability = self._readability_grade(text, words)
+        ambiguity = self._ambiguity_score(text, words)
+        specificity = self._specificity_score(text, words, keywords)
+        difficulty_score = self._difficulty_score(
+            text, words, keywords, readability, ambiguity, specificity, question)
+        difficulty = self._score_to_difficulty(difficulty_score)
+
+        features = {
+            "word_count": len(words),
+            "avg_word_length": sum(len(w) for w in words) / max(len(words), 1),
+            "sentence_count": max(1, text.count(".") + text.count("?") + text.count("!")),
+            "has_negation": any(w in {"not", "never", "no", "none", "neither", "nor", "isn't",
+                                       "wasn't", "doesn't", "don't", "won't", "can't"}
+                                for w in words),
+            "has_superlative": any(w.endswith("est") or w in {"most", "least", "best", "worst",
+                                                               "first", "last", "largest", "smallest"}
+                                   for w in words),
+            "has_numeric": bool(re.search(r"\d", text)),
+            "has_proper_noun": bool(re.search(r"\b[A-Z][a-z]+\b", text[1:])),  # skip first word
+            "unique_word_ratio": len(set(words)) / max(len(words), 1),
+            "rare_word_count": sum(1 for w in words if w not in _COMMON_WORDS and len(w) > 3),
+        }
+
+        return AnalysisResult(
+            question=question,
+            question_type=q_type,
+            difficulty=difficulty,
+            category=category,
+            difficulty_score=difficulty_score,
+            language_features=features,
+            keywords=keywords,
+            ambiguity_score=ambiguity,
+            specificity_score=specificity,
+            readability_grade=readability,
+        )
+
+    def batch_analyse(self, questions: list[TriviaQuestion | str]) -> list[AnalysisResult]:
+        return [self.analyse(q) for q in questions]
+
+    def compare(self, q1: TriviaQuestion | str, q2: TriviaQuestion | str) -> dict:
+        """Compare two questions."""
+        a1 = self.analyse(q1)
+        a2 = self.analyse(q2)
+        return {
+            "q1": a1.summary,
+            "q2": a2.summary,
+            "harder": "q1" if a1.difficulty_score > a2.difficulty_score else "q2",
+            "difficulty_delta": abs(a1.difficulty_score - a2.difficulty_score),
+            "same_category": a1.category == a2.category,
+            "same_type": a1.question_type == a2.question_type,
+        }
+
+    # ── Private helpers ──
+
+    def _tokenize(self, text: str) -> list[str]:
+        text = text.lower().translate(str.maketrans("", "", string.punctuation))
+        return text.split()
+
+    def _classify_type(self, text: str) -> QuestionType:
+        t = text.lower().strip()
+        if t.startswith("true or false") or t.startswith("t/f"):
+            return QuestionType.TRUE_FALSE
+        if "___" in t or "____" in t or "fill in" in t:
+            return QuestionType.FILL_BLANK
+
+        for qt in [QuestionType.WHO, QuestionType.WHAT, QuestionType.WHEN,
+                    QuestionType.WHERE, QuestionType.WHY, QuestionType.HOW,
+                    QuestionType.WHICH]:
+            if t.startswith(qt.value):
+                return qt
+
+        # Check for embedded question words
+        for qt in [QuestionType.WHO, QuestionType.WHAT, QuestionType.WHEN,
+                    QuestionType.WHERE, QuestionType.WHY, QuestionType.HOW]:
+            if f" {qt.value} " in f" {t} ":
+                return qt
+
+        return QuestionType.UNKNOWN
+
+    def _classify_category(self, words: list[str]) -> Category:
+        word_set = set(words)
+        scores: dict[Category, int] = {}
+        for cat, keywords in _CATEGORY_KEYWORDS.items():
+            overlap = len(word_set & keywords)
+            if overlap > 0:
+                scores[cat] = overlap
+        if scores:
+            return max(scores, key=scores.get)
+        return Category.GENERAL
+
+    def _extract_keywords(self, words: list[str]) -> list[str]:
+        return [w for w in words if w not in _COMMON_WORDS and len(w) > 2]
+
+    def _readability_grade(self, text: str, words: list[str]) -> float:
+        """Approximate Flesch-Kincaid grade level."""
+        sentences = max(1, text.count(".") + text.count("?") + text.count("!"))
+        syllables = sum(self._count_syllables(w) for w in words)
+        if not words:
+            return 0
+        return 0.39 * (len(words) / sentences) + 11.8 * (syllables / len(words)) - 15.59
+
+    def _count_syllables(self, word: str) -> int:
+        word = word.lower().rstrip("e")
+        count = len(re.findall(r"[aeiouy]+", word))
+        return max(1, count)
+
+    def _ambiguity_score(self, text: str, words: list[str]) -> float:
+        score = 0.0
+        ambiguous_markers = {"could", "might", "possibly", "perhaps", "sometimes",
+                             "often", "usually", "generally", "approximately", "roughly"}
+        score += 0.15 * len(set(words) & ambiguous_markers)
+        if "or" in words:
+            score += 0.1
+        if text.count("?") > 1:
+            score += 0.2
+        return min(1.0, score)
+
+    def _specificity_score(self, text: str, words: list[str], keywords: list[str]) -> float:
+        score = 0.0
+        if re.search(r"\d{4}", text):  # years
+            score += 0.2
+        if re.search(r"\b[A-Z][a-z]+\b", text[1:]):  # proper nouns
+            score += 0.2
+        score += min(0.4, len(keywords) * 0.05)
+        if any(w in words for w in ["exactly", "specifically", "precisely"]):
+            score += 0.2
+        return min(1.0, score)
+
+    def _difficulty_score(self, text: str, words: list[str], keywords: list[str],
+                          readability: float, ambiguity: float, specificity: float,
+                          question: TriviaQuestion) -> float:
+        score = 0.0
+
+        # Length factor
+        score += min(0.2, len(words) * 0.008)
+
+        # Rare words
+        rare = sum(1 for w in words if w not in _COMMON_WORDS and len(w) > 5)
+        score += min(0.2, rare * 0.04)
+
+        # Readability
+        score += min(0.15, max(0, readability - 5) * 0.015)
+
+        # Specificity increases difficulty
+        score += specificity * 0.2
+
+        # Negation makes questions trickier
+        if any(w in {"not", "never", "except", "least", "false"} for w in words):
+            score += 0.1
+
+        # Multiple choice reduces difficulty
+        if question.has_choices:
+            score -= 0.15
+
+        # True/false is generally easier
+        if text.lower().startswith("true or false"):
+            score -= 0.1
+
+        return max(0.0, min(1.0, score))
+
+    def _score_to_difficulty(self, score: float) -> Difficulty:
+        if score < 0.25:
+            return Difficulty.EASY
+        elif score < 0.5:
+            return Difficulty.MEDIUM
+        elif score < 0.75:
+            return Difficulty.HARD
+        return Difficulty.EXPERT

langgraph_tavily-0.1.0/src/langgraph_tavily/cli.py

@@ -0,0 +1,85 @@
+"""CLI for langgraph-tavily."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="langgraph-tavily",
+        description="Analyse trivia questions for difficulty, type, and language features",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # Analyse
+    a_p = sub.add_parser("analyse", help="Analyse a trivia question")
+    a_p.add_argument("question", help="The trivia question text")
+    a_p.add_argument("--json", action="store_true")
+
+    # Batch
+    b_p = sub.add_parser("batch", help="Analyse questions from a file (one per line)")
+    b_p.add_argument("file", help="Text file with one question per line")
+    b_p.add_argument("--json", action="store_true")
+
+    # Compare
+    c_p = sub.add_parser("compare", help="Compare two questions")
+    c_p.add_argument("q1", help="First question")
+    c_p.add_argument("q2", help="Second question")
+
+    # Quiz
+    q_p = sub.add_parser("quiz", help="Generate a trivia quiz")
+    q_p.add_argument("--count", type=int, default=5)
+    q_p.add_argument("--difficulty", choices=["easy", "medium", "hard", "expert"])
+    q_p.add_argument("--category", default="")
+    q_p.add_argument("--show-answers", action="store_true")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "analyse":
+        from .analyser import TriviaAnalyser
+        result = TriviaAnalyser().analyse(args.question)
+        if args.json:
+            print(json.dumps(result.to_dict(), indent=2))
+        else:
+            print(result.summary)
+            print(f"  Keywords: {', '.join(result.keywords)}")
+            print(f"  Ambiguity: {result.ambiguity_score:.2f}  Specificity: {result.specificity_score:.2f}")
+
+    elif args.command == "batch":
+        from .analyser import TriviaAnalyser
+        from pathlib import Path
+        questions = Path(args.file).read_text().strip().splitlines()
+        analyser = TriviaAnalyser()
+        results = analyser.batch_analyse(questions)
+        if args.json:
+            print(json.dumps([r.to_dict() for r in results], indent=2))
+        else:
+            for r in results:
+                print(r.summary)
+
+    elif args.command == "compare":
+        from .analyser import TriviaAnalyser
+        result = TriviaAnalyser().compare(args.q1, args.q2)
+        for k, v in result.items():
+            print(f"  {k}: {v}")
+
+    elif args.command == "quiz":
+        from .generator import TriviaGenerator
+        from .models import Difficulty
+        gen = TriviaGenerator()
+        diff = Difficulty(args.difficulty) if args.difficulty else None
+        questions = gen.random(args.count, difficulty=diff, category=args.category)
+        for i, q in enumerate(questions, 1):
+            print(f"  {i}. {q.text}")
+            if args.show_answers:
+                print(f"     Answer: {q.answer}")
+
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

langgraph_tavily-0.1.0/src/langgraph_tavily/generator.py

@@ -0,0 +1,89 @@
+"""Trivia question generator with difficulty control."""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+from .models import TriviaQuestion, Category, Difficulty
+
+# Built-in trivia bank
+_TRIVIA_BANK: list[dict] = [
+    {"q": "What planet is known as the Red Planet?", "a": "Mars", "cat": "science", "diff": "easy"},
+    {"q": "What is the largest ocean on Earth?", "a": "Pacific Ocean", "cat": "geography", "diff": "easy"},
+    {"q": "Who painted the Mona Lisa?", "a": "Leonardo da Vinci", "cat": "art", "diff": "easy"},
+    {"q": "In what year did World War II end?", "a": "1945", "cat": "history", "diff": "easy"},
+    {"q": "What is the chemical symbol for gold?", "a": "Au", "cat": "science", "diff": "medium"},
+    {"q": "Which country has the most natural lakes?", "a": "Canada", "cat": "geography", "diff": "medium"},
+    {"q": "Who wrote 'One Hundred Years of Solitude'?", "a": "Gabriel Garcia Marquez", "cat": "literature", "diff": "medium"},
+    {"q": "What instrument has 88 keys?", "a": "Piano", "cat": "music", "diff": "easy"},
+    {"q": "In which city would you find the Sagrada Familia?", "a": "Barcelona", "cat": "geography", "diff": "medium"},
+    {"q": "What is the smallest bone in the human body?", "a": "Stapes (stirrup bone)", "cat": "science", "diff": "medium"},
+    {"q": "Which element has the atomic number 79?", "a": "Gold", "cat": "science", "diff": "hard"},
+    {"q": "What ancient wonder was located in Alexandria?", "a": "The Lighthouse (Pharos)", "cat": "history", "diff": "hard"},
+    {"q": "Who composed 'The Rite of Spring'?", "a": "Igor Stravinsky", "cat": "music", "diff": "hard"},
+    {"q": "What is the only country to span four hemispheres?", "a": "Kiribati", "cat": "geography", "diff": "expert"},
+    {"q": "In what year was the Treaty of Westphalia signed?", "a": "1648", "cat": "history", "diff": "expert"},
+    {"q": "What is the Chandrasekhar limit measured in solar masses?", "a": "1.4 solar masses", "cat": "science", "diff": "expert"},
+    {"q": "Which programming language was created by Bjarne Stroustrup?", "a": "C++", "cat": "technology", "diff": "medium"},
+    {"q": "What sport uses a shuttlecock?", "a": "Badminton", "cat": "sports", "diff": "easy"},
+    {"q": "Which vitamin is produced when skin is exposed to sunlight?", "a": "Vitamin D", "cat": "science", "diff": "medium"},
+    {"q": "What is the world's largest desert by area?", "a": "Antarctic Desert", "cat": "geography", "diff": "hard"},
+]
+
+
+@dataclass
+class TriviaGenerator:
+    """Generate trivia questions from the built-in bank with filters."""
+
+    seed: int | None = None
+
+    def _rng(self) -> random.Random:
+        return random.Random(self.seed)
+
+    def random(self, count: int = 1, *, difficulty: Difficulty | None = None,
+               category: str = "") -> list[TriviaQuestion]:
+        """Get random trivia questions."""
+        rng = self._rng()
+        pool = list(_TRIVIA_BANK)
+
+        if difficulty:
+            pool = [q for q in pool if q["diff"] == difficulty.value]
+        if category:
+            pool = [q for q in pool if q["cat"] == category.lower()]
+
+        if not pool:
+            return []
+
+        picked = rng.sample(pool, min(count, len(pool)))
+        return [
+            TriviaQuestion(text=q["q"], answer=q["a"], category=q["cat"])
+            for q in picked
+        ]
+
+    def quiz(self, count: int = 10, mix: bool = True) -> list[TriviaQuestion]:
+        """Generate a balanced quiz with mixed difficulties."""
+        rng = self._rng()
+        if mix:
+            questions = []
+            for diff in [Difficulty.EASY, Difficulty.MEDIUM, Difficulty.HARD]:
+                pool = [q for q in _TRIVIA_BANK if q["diff"] == diff.value]
+                n = max(1, count // 3)
+                questions.extend(rng.sample(pool, min(n, len(pool))))
+            rng.shuffle(questions)
+            questions = questions[:count]
+        else:
+            questions = rng.sample(_TRIVIA_BANK, min(count, len(_TRIVIA_BANK)))
+
+        return [
+            TriviaQuestion(text=q["q"], answer=q["a"], category=q["cat"])
+            for q in questions
+        ]
+
+    @property
+    def categories(self) -> list[str]:
+        return sorted(set(q["cat"] for q in _TRIVIA_BANK))
+
+    @property
+    def total_questions(self) -> int:
+        return len(_TRIVIA_BANK)

langgraph_tavily-0.1.0/src/langgraph_tavily/models.py

@@ -0,0 +1,100 @@
+"""Core models for trivia question analysis."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class QuestionType(str, Enum):
+    WHO = "who"
+    WHAT = "what"
+    WHEN = "when"
+    WHERE = "where"
+    WHY = "why"
+    HOW = "how"
+    WHICH = "which"
+    TRUE_FALSE = "true_false"
+    MULTIPLE_CHOICE = "multiple_choice"
+    FILL_BLANK = "fill_blank"
+    UNKNOWN = "unknown"
+
+
+class Difficulty(str, Enum):
+    EASY = "easy"
+    MEDIUM = "medium"
+    HARD = "hard"
+    EXPERT = "expert"
+
+
+class Category(str, Enum):
+    SCIENCE = "science"
+    HISTORY = "history"
+    GEOGRAPHY = "geography"
+    ENTERTAINMENT = "entertainment"
+    SPORTS = "sports"
+    ART = "art"
+    LITERATURE = "literature"
+    MUSIC = "music"
+    FOOD = "food"
+    TECHNOLOGY = "technology"
+    NATURE = "nature"
+    POLITICS = "politics"
+    LANGUAGE = "language"
+    MATH = "math"
+    GENERAL = "general"
+
+
+@dataclass
+class TriviaQuestion:
+    """A trivia question with optional answer and choices."""
+    text: str
+    answer: str = ""
+    choices: list[str] = field(default_factory=list)
+    category: str = ""
+    source: str = ""
+
+    @property
+    def word_count(self) -> int:
+        return len(self.text.split())
+
+    @property
+    def has_choices(self) -> bool:
+        return len(self.choices) > 0
+
+
+@dataclass
+class AnalysisResult:
+    """Full analysis of a trivia question."""
+    question: TriviaQuestion
+    question_type: QuestionType
+    difficulty: Difficulty
+    category: Category
+    difficulty_score: float  # 0.0 (trivial) to 1.0 (impossible)
+    language_features: dict[str, Any] = field(default_factory=dict)
+    keywords: list[str] = field(default_factory=list)
+    ambiguity_score: float = 0.0  # 0 = clear, 1 = very ambiguous
+    specificity_score: float = 0.0  # 0 = vague, 1 = very specific
+    readability_grade: float = 0.0  # approximate grade level
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "question": self.question.text,
+            "answer": self.question.answer,
+            "question_type": self.question_type.value,
+            "difficulty": self.difficulty.value,
+            "difficulty_score": round(self.difficulty_score, 2),
+            "category": self.category.value,
+            "keywords": self.keywords,
+            "ambiguity_score": round(self.ambiguity_score, 2),
+            "specificity_score": round(self.specificity_score, 2),
+            "readability_grade": round(self.readability_grade, 1),
+            "language_features": self.language_features,
+        }
+
+    @property
+    def summary(self) -> str:
+        return (f"[{self.difficulty.value.upper()}] {self.question_type.value} "
+                f"({self.category.value}) — score: {self.difficulty_score:.2f}, "
+                f"readability: grade {self.readability_grade:.0f}")