play-parser 1.2.0__tar.gz → 1.2.1__tar.gz

{play_parser-1.2.0/src/play_parser.egg-info → play_parser-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: play-parser
-Version: 1.2.0
+Version: 1.2.1
 Summary: Parse dramatic play text into ordered dramatic events.
 Author-email: Stergios Poularakis <stpoular@gmail.com>
 License-Expression: MIT

{play_parser-1.2.0 → play_parser-1.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "play-parser"
-version = "1.2.0"
+version = "1.2.1"
 description = "Parse dramatic play text into ordered dramatic events."
 readme = "README.md"
 requires-python = ">=3.10"

{play_parser-1.2.0 → play_parser-1.2.1}/src/play_parser/__init__.py

@@ -8,6 +8,7 @@ from play_parser.domain import Act, Character, Dialogue, Monologue, Play, Scene,
 from play_parser.ingestion import PlayIngestor
 from play_parser.parsers import FSMPlayParser, PlayParser, RuleBasedPlayParser, SimplePlayParser
 from play_parser.parsing.hints import PlayParseConfig, PlayParseHints, load_play_parse_config
+from play_parser.parsing.profile_detection import ProfileDetectionResult, ProfileScore, detect_format_profile
 from play_parser.parsing.profiles import (
     FormatProfile,
     get_format_profile,
@@ -52,6 +53,9 @@ __all__ = [
     "FSMPlayParser",
     "PlayParseConfig",
     "PlayParseHints",
+    "ProfileDetectionResult",
+    "ProfileScore",
+    "detect_format_profile",
     "Scene",
     "Speech",
     "assemble_play_text",

{play_parser-1.2.0 → play_parser-1.2.1}/src/play_parser/document/types.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Literal, TypedDict
+from typing import Any, Literal, TypedDict
 
 
 class ActStartEvent(TypedDict):
@@ -95,6 +95,8 @@ class PlayMetadataRequired(TypedDict):
 
 class PlayMetadata(PlayMetadataRequired, total=False):
     preamble: str
+    selected_format_profile: str
+    profile_detection: dict[str, Any]
 
 
 class PlayDocument(TypedDict):

{play_parser-1.2.0 → play_parser-1.2.1}/src/play_parser/document/validation.py

@@ -12,7 +12,7 @@ from .types import PlayDocument, PlayEvent, PlayMetadata
 
 DEFAULT_DIFF_CONTEXT_SIZE = 50
 REQUIRED_METADATA_FIELDS = {"title", "author", "characters", "acts", "scenes", "stats"}
-OPTIONAL_METADATA_FIELDS = {"preamble"}
+OPTIONAL_METADATA_FIELDS = {"preamble", "selected_format_profile", "profile_detection"}
 REQUIRED_DOCUMENT_FIELDS = {"metadata", "events"}
 REQUIRED_ACT_SUMMARY_FIELDS = {"act_number", "label"}
 REQUIRED_SCENE_SUMMARY_FIELDS = {"act_number", "scene_number", "label"}

{play_parser-1.2.0 → play_parser-1.2.1}/src/play_parser/parsers.py

@@ -12,6 +12,7 @@ from play_parser.domain import Play
 from play_parser.ingestion.ingestor import ProfileInput, resolve_format_profile
 from play_parser.parsing.fsm import FSMDocumentParser, PlayFSMScoring
 from play_parser.parsing.hints import PlayParseHints
+from play_parser.parsing.profile_detection import detect_format_profile
 
 ParserMethod = Literal["simple", "rule", "fsm"]
 
@@ -79,6 +80,16 @@ class PlayParser(ABC):
         ).as_dict()
 
 
+def _should_auto_detect_profile(profile: ProfileInput, profile_path: str | Path | None) -> bool:
+    if profile_path is not None:
+        return False
+    if profile is None:
+        return False
+    if isinstance(profile, str):
+        return profile.strip().lower().replace("-", "_") in {"auto", "default"}
+    return False
+
+
 def _coerce_hints(hints: PlayParseHints | Mapping[str, object] | None) -> PlayParseHints | None:
     if hints is None:
         return None
@@ -109,13 +120,23 @@ class SimplePlayParser(PlayParser):
         if existing_document is not None:
             return Play(existing_document)
 
-        resolved_profile = resolve_format_profile(profile=profile, profile_path=profile_path)
+        coerced_hints = _coerce_hints(hints)
+        detection = None
+        if _should_auto_detect_profile(profile, profile_path):
+            detection = detect_format_profile(data, hints=coerced_hints)
+            resolved_profile = None if detection.selected_profile == "generic" else resolve_format_profile(profile=detection.selected_profile)
+        else:
+            resolved_profile = resolve_format_profile(profile=profile, profile_path=profile_path)
+
         document = build_play_document(
             data,
             play_name=Path(source_name).stem if source_name else None,
             profile=resolved_profile,
-            hints=_coerce_hints(hints),
+            hints=coerced_hints,
         )
+        if detection is not None:
+            document.setdefault("metadata", {})["selected_format_profile"] = detection.selected_profile
+            document.setdefault("metadata", {})["profile_detection"] = detection.as_dict()
         return Play(document)
 
 
@@ -149,12 +170,22 @@ class FSMPlayParser(PlayParser):
         if existing_document is not None:
             return Play(existing_document)
 
-        resolved_profile = resolve_format_profile(profile=profile, profile_path=profile_path)
+        coerced_hints = _coerce_hints(hints)
+        detection = None
+        if _should_auto_detect_profile(profile, profile_path):
+            detection = detect_format_profile(data, hints=coerced_hints)
+            resolved_profile = None if detection.selected_profile == "generic" else resolve_format_profile(profile=detection.selected_profile)
+        else:
+            resolved_profile = resolve_format_profile(profile=profile, profile_path=profile_path)
+
         document = FSMDocumentParser(
             profile=resolved_profile,
-            hints=_coerce_hints(hints),
+            hints=coerced_hints,
             source_name=source_name,
             beam_width=self.beam_width,
             scoring=self.scoring,
         ).parse(data)
+        if detection is not None:
+            document.setdefault("metadata", {})["selected_format_profile"] = detection.selected_profile
+            document.setdefault("metadata", {})["profile_detection"] = detection.as_dict()
         return Play(document)

play_parser-1.2.1/src/play_parser/parsing/profile_detection.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from play_parser.document.text import count_words
+from play_parser.document.types import PlayEvent
+from collections.abc import Mapping
+
+from play_parser.parsing.hints import PlayParseHints
+from play_parser.parsing.parser import parse_play_text
+from play_parser.parsing.profiles import get_format_profile
+
+CANDIDATE_FORMAT_PROFILES: tuple[str, ...] = (
+    "dot_block",
+    "colon_inline",
+    "dot_inline",
+    "mixed_parenthetical",
+    "narrative_stage_heavy",
+    "generic",
+)
+DEFAULT_SAMPLE_CHARS = 2_000
+LOW_SCORE = -10_000
+
+
+@dataclass(frozen=True, slots=True)
+class ProfileScore:
+    profile: str
+    score: int
+    speeches: int = 0
+    unique_speakers: tuple[str, ...] = ()
+    repeated_speakers: tuple[str, ...] = ()
+    stage_directions: int = 0
+    meta_events: int = 0
+    avg_words_per_speech: float = 0.0
+    very_short_ratio: float = 0.0
+    very_long_ratio: float = 0.0
+    alternation_ratio: float = 0.0
+    error: str | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "profile": self.profile,
+            "score": self.score,
+            "speeches": self.speeches,
+            "unique_speakers": list(self.unique_speakers),
+            "repeated_speakers": list(self.repeated_speakers),
+            "stage_directions": self.stage_directions,
+            "meta_events": self.meta_events,
+            "avg_words_per_speech": self.avg_words_per_speech,
+            "very_short_ratio": self.very_short_ratio,
+            "very_long_ratio": self.very_long_ratio,
+            "alternation_ratio": self.alternation_ratio,
+            "error": self.error,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ProfileDetectionResult:
+    selected_profile: str
+    confidence: str
+    sample_chars: int
+    scores: tuple[ProfileScore, ...]
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "method": "sample_score",
+            "selected_profile": self.selected_profile,
+            "confidence": self.confidence,
+            "sample_chars": self.sample_chars,
+            "scores": [score.as_dict() for score in self.scores],
+        }
+
+
+def sample_script_body(text: str, *, max_chars: int = DEFAULT_SAMPLE_CHARS) -> str:
+    """Return a stable parser-detection sample without cutting mid-line when possible."""
+
+    stripped = text.strip()
+    if len(stripped) <= max_chars:
+        return stripped
+
+    sample = stripped[:max_chars]
+    last_newline = sample.rfind("\n")
+    if last_newline > max(300, max_chars // 3):
+        return sample[:last_newline].strip()
+    return sample.strip()
+
+
+def score_parsed_events(events: list[PlayEvent]) -> ProfileScore:
+    return _score_events("<parsed>", events)
+
+
+def score_profile_events(profile: str, events: list[PlayEvent], *, error: str | None = None) -> ProfileScore:
+    if error is not None:
+        return ProfileScore(profile=profile, score=LOW_SCORE, error=error)
+    return _score_events(profile, events)
+
+
+def _score_events(profile: str, events: list[PlayEvent]) -> ProfileScore:
+    if not events:
+        return ProfileScore(profile=profile, score=LOW_SCORE, error="No events detected")
+
+    speeches = [event for event in events if event.get("type") == "speech"]
+    stage_dirs = [event for event in events if event.get("type") == "stage_direction"]
+    meta = [event for event in events if event.get("type") == "meta"]
+
+    speakers = [
+        str(event.get("speaker") or "").strip()
+        for event in speeches
+        if str(event.get("speaker") or "").strip()
+    ]
+    unique_speakers = tuple(sorted(set(speakers)))
+
+    if not speeches or not unique_speakers:
+        return ProfileScore(
+            profile=profile,
+            score=LOW_SCORE,
+            speeches=len(speeches),
+            unique_speakers=unique_speakers,
+            stage_directions=len(stage_dirs),
+            meta_events=len(meta),
+            error="No speeches or speakers detected",
+        )
+
+    word_counts = [count_words(str(event.get("text") or "")) for event in speeches]
+    avg_words = sum(word_counts) / max(1, len(word_counts))
+    very_short_ratio = sum(1 for count in word_counts if count <= 1) / len(word_counts)
+    very_long_ratio = sum(1 for count in word_counts if count > 80) / len(word_counts)
+
+    plausible_speakers = [speaker for speaker in unique_speakers if _is_plausible_speaker_name(speaker)]
+    implausible_speakers = len(unique_speakers) - len(plausible_speakers)
+
+    repeated_speakers = tuple(sorted({speaker for speaker in unique_speakers if speakers.count(speaker) >= 2}))
+
+    speaker_changes = sum(1 for previous, current in zip(speakers, speakers[1:]) if previous != current)
+    alternation_ratio = speaker_changes / max(1, len(speakers) - 1)
+    meta_ratio = len(meta) / max(1, len(events))
+
+    score = 0
+    score += min(len(unique_speakers), 8) * 80
+    score += min(len(repeated_speakers), 8) * 100
+    score += min(len(speeches), 25) * 8
+    score += min(len(stage_dirs), 8) * 10
+
+    if 2 <= avg_words <= 35:
+        score += 150
+    elif 35 < avg_words <= 80:
+        score += 40
+    else:
+        score -= 150
+
+    if 0.25 <= alternation_ratio <= 1.0:
+        score += 60
+
+    if len(stage_dirs) > len(speeches) * 0.5:
+        score -= 120
+    if 0 < alternation_ratio < 0.15 and len(speeches) >= 6:
+        score -= 120
+    score -= int(meta_ratio * 250)
+    score -= implausible_speakers * 120
+    score -= int(very_short_ratio * 180)
+    score -= int(very_long_ratio * 220)
+
+    return ProfileScore(
+        profile=profile,
+        score=score,
+        speeches=len(speeches),
+        unique_speakers=unique_speakers,
+        repeated_speakers=repeated_speakers,
+        stage_directions=len(stage_dirs),
+        meta_events=len(meta),
+        avg_words_per_speech=round(avg_words, 3),
+        very_short_ratio=round(very_short_ratio, 3),
+        very_long_ratio=round(very_long_ratio, 3),
+        alternation_ratio=round(alternation_ratio, 3),
+    )
+
+
+def _is_plausible_speaker_name(value: str) -> bool:
+    if not value or len(value) > 40:
+        return False
+    if any(char in value for char in ".?!,:;()[]{}"):
+        return False
+    parts = value.split()
+    return 1 <= len(parts) <= 4
+
+
+def detect_format_profile(
+    text: str,
+    *,
+    hints: PlayParseHints | Mapping[str, object] | None = None,
+    candidate_profiles: tuple[str, ...] | list[str] = CANDIDATE_FORMAT_PROFILES,
+    sample_chars: int = DEFAULT_SAMPLE_CHARS,
+) -> ProfileDetectionResult:
+    """Detect the most plausible built-in format profile for raw play text.
+
+    The detector parses only a short sample with each candidate profile and scores
+    the resulting dramatic structure. It is intended for profile selection, not
+    final document parsing.
+    """
+
+    sample = sample_script_body(text, max_chars=sample_chars)
+    coerced_hints = _coerce_hints(hints)
+    scores: list[ProfileScore] = []
+
+    for profile_name in _unique_profiles(candidate_profiles):
+        try:
+            profile = None if profile_name == "generic" else get_format_profile(profile_name)
+            events = parse_play_text(sample, profile=profile, hints=coerced_hints)
+            scores.append(score_profile_events(profile_name, events))
+        except Exception as exc:  # pragma: no cover - defensive path depends on profile internals
+            scores.append(score_profile_events(profile_name, [], error=str(exc)))
+
+    scores.sort(key=lambda item: item.score, reverse=True)
+    if not scores:
+        raise ValueError("No candidate format profiles supplied")
+
+    best = scores[0]
+    second = scores[1] if len(scores) > 1 else None
+    confidence = _confidence(best, second)
+    return ProfileDetectionResult(
+        selected_profile=best.profile,
+        confidence=confidence,
+        sample_chars=len(sample),
+        scores=tuple(scores),
+    )
+
+
+def _unique_profiles(profiles: tuple[str, ...] | list[str]) -> list[str]:
+    seen: set[str] = set()
+    output: list[str] = []
+    for profile in profiles:
+        if profile in seen:
+            continue
+        seen.add(profile)
+        output.append(profile)
+    return output
+
+
+def _confidence(best: ProfileScore, second: ProfileScore | None) -> str:
+    if best.score < 250:
+        return "low"
+    if second is not None and best.score - second.score < 75:
+        return "medium"
+    return "high"
+
+
+def _coerce_hints(hints: PlayParseHints | Mapping[str, object] | None) -> PlayParseHints | None:
+    if hints is None:
+        return None
+    if isinstance(hints, PlayParseHints):
+        return hints
+    return PlayParseHints(**dict(hints))

{play_parser-1.2.0 → play_parser-1.2.1/src/play_parser.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: play-parser
-Version: 1.2.0
+Version: 1.2.1
 Summary: Parse dramatic play text into ordered dramatic events.
 Author-email: Stergios Poularakis <stpoular@gmail.com>
 License-Expression: MIT

{play_parser-1.2.0 → play_parser-1.2.1}/src/play_parser.egg-info/SOURCES.txt

@@ -699,6 +699,7 @@ src/play_parser/parsing/front_matter.py
 src/play_parser/parsing/fsm.py
 src/play_parser/parsing/hints.py
 src/play_parser/parsing/parser.py
+src/play_parser/parsing/profile_detection.py
 src/play_parser/parsing/speakers.py
 src/play_parser/parsing/speech.py
 src/play_parser/parsing/stage.py
@@ -727,6 +728,7 @@ tests/test_ingestor.py
 tests/test_json_schema.py
 tests/test_parser_core.py
 tests/test_parser_factory.py
+tests/test_profile_detection.py
 tests/test_profiles.py
 tests/test_public_api.py
 tests/test_validation_strict_types.py

play_parser-1.2.1/tests/test_profile_detection.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from play_parser import PlayParser, detect_format_profile
+
+
+DOT_BLOCK_TEXT = """Gin vs Whiskey
+A light comic scene for two men
+
+Characters:
+TOM - Warm, precise.
+BEN - Easygoing, dry wit.
+
+---
+
+(TOM sits at the bar. BEN enters.)
+
+BEN
+Evening.
+
+TOM
+Evening. You're late.
+
+BEN
+By four minutes.
+
+TOM
+In cocktail time, that's a lifetime.
+"""
+
+COLON_INLINE_TEXT = """The Ferry Bell
+
+FERRYMAN: Last crossing.
+PASSENGER: Is there room?
+FERRYMAN: For one more.
+"""
+
+
+def test_detect_format_profile_picks_generic_for_bare_speaker_blocks() -> None:
+    result = detect_format_profile(DOT_BLOCK_TEXT, hints={"body_start_after": "---"})
+
+    assert result.selected_profile == "generic"
+    assert result.confidence in {"medium", "high"}
+    assert result.scores[0].score > result.scores[-1].score
+
+
+def test_auto_profile_parsing_detects_characters_and_records_metadata() -> None:
+    document = PlayParser.create("rule").parse_document(
+        DOT_BLOCK_TEXT,
+        profile="auto",
+        hints={"body_start_after": "---"},
+        source_name="Gin vs Whiskey.txt",
+    )
+
+    assert document["metadata"]["selected_format_profile"] == "generic"
+    assert document["metadata"]["profile_detection"]["method"] == "sample_score"
+    assert document["metadata"]["characters"] == ["Ben", "Tom"]
+    assert document["metadata"]["stats"]["speeches"] == 4
+
+
+def test_default_profile_alias_uses_auto_detection_for_backward_compatibility() -> None:
+    document = PlayParser.create("rule").parse_document(
+        DOT_BLOCK_TEXT,
+        profile="default",
+        hints={"body_start_after": "---"},
+        source_name="Gin vs Whiskey.txt",
+    )
+
+    assert document["metadata"]["selected_format_profile"] == "generic"
+    assert document["metadata"]["characters"] == ["Ben", "Tom"]
+
+
+def test_detect_format_profile_picks_colon_inline_for_colon_dialogue() -> None:
+    result = detect_format_profile(COLON_INLINE_TEXT)
+
+    assert result.selected_profile == "colon_inline"