ai-pipeline-core 0.3.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

ai_pipeline_core/{debug/writer.py → observability/_debug/_writer.py}

@@ -1,15 +1,15 @@
 """Local trace writer for filesystem-based debugging."""
 
+import asyncio
 import atexit
 import hashlib
+import importlib
 import json
 import os
 import re
 import shutil
 import socket
-from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from pathlib import Path
+from datetime import UTC, datetime
 from queue import Empty, Queue
 from threading import Lock, Thread
 from typing import Any
@@ -18,71 +18,22 @@ import yaml
 
 from ai_pipeline_core.logging import get_pipeline_logger
 
-from .config import TraceDebugConfig
-from .content import ArtifactStore, ContentWriter
+from ._config import TraceDebugConfig
+from ._content import ArtifactStore, ContentWriter
+from ._summary import generate_summary
+from ._types import SpanInfo, TraceState, WriteJob
 
 logger = get_pipeline_logger(__name__)
 
 
-@dataclass
-class WriteJob:
-    """Job for background writer thread."""
-
-    trace_id: str
-    span_id: str
-    name: str
-    parent_id: str | None
-    attributes: dict[str, Any]
-    events: list[Any]
-    status_code: str  # "OK" | "ERROR" | "UNSET"
-    status_description: str | None
-    start_time_ns: int
-    end_time_ns: int
-
-
-@dataclass
-class SpanInfo:
-    """Information about a span for index building."""
-
-    span_id: str
-    parent_id: str | None
-    name: str
-    span_type: str
-    status: str
-    start_time: datetime
-    path: Path  # Actual directory path for this span
-    depth: int = 0  # Nesting depth (0 for root)
-    order: int = 0  # Global execution order within trace
-    end_time: datetime | None = None
-    duration_ms: int = 0
-    children: list[str] = field(default_factory=list)
-    llm_info: dict[str, Any] | None = None
-    prefect_info: dict[str, Any] | None = None
-
-
-@dataclass
-class TraceState:
-    """State for an active trace."""
-
-    trace_id: str
-    name: str
-    path: Path
-    start_time: datetime
-    spans: dict[str, SpanInfo] = field(default_factory=dict)
-    root_span_id: str | None = None
-    total_tokens: int = 0
-    total_cost: float = 0.0
-    llm_call_count: int = 0
-    span_counter: int = 0  # Global counter for ordering span directories
-    merged_wrapper_ids: set[str] = field(default_factory=set)  # IDs of merged wrappers
-
-
 class LocalTraceWriter:
     """Writes trace spans to local filesystem via background thread.
 
     Uses a hierarchical directory structure where child spans are nested
     inside parent span directories. Directory names use numeric prefixes
     (01_, 02_, etc.) to preserve execution order when viewed with `tree`.
+    Generates index files and optionally produces _summary.md and
+    _auto_summary.md for trace analysis.
     """
 
     def __init__(self, config: TraceDebugConfig):
@@ -133,9 +84,7 @@ class LocalTraceWriter:
                 depth = parent_info.depth + 1
             elif parent_id:
                 # Parent ID provided but not found - orphan span, place at root
-                logger.warning(
-                    f"Span {span_id} has unknown parent {parent_id}, placing at trace root"
-                )
+                logger.warning(f"Span {span_id} has unknown parent {parent_id}, placing at trace root")
                 parent_path = trace.path
                 depth = 0
             else:
@@ -152,7 +101,7 @@ class LocalTraceWriter:
             span_dir.mkdir(parents=True, exist_ok=True)
 
             # Record span info
-            now = datetime.now(timezone.utc)
+            now = datetime.now(UTC)
             span_info = SpanInfo(
                 span_id=span_id,
                 parent_id=parent_id,
@@ -174,20 +123,6 @@ class LocalTraceWriter:
             if parent_id and parent_id in trace.spans:
                 trace.spans[parent_id].children.append(span_id)
 
-            # Append to event log (lightweight - just appends a line)
-            self._append_event(
-                trace,
-                {
-                    "type": "span_start",
-                    "span_id": span_id,
-                    "parent_id": parent_id,
-                    "name": name,
-                    "path": str(span_dir.relative_to(trace.path)),
-                },
-            )
-            # Note: _write_status() moved to on_span_end for performance
-            # (avoids blocking I/O in main thread on every span start)
-
     def on_span_end(self, job: WriteJob) -> None:
         """Queue span end job for background processing.
 
@@ -200,13 +135,22 @@ class LocalTraceWriter:
         """Flush queue and stop writer thread."""
         if self._shutdown:
             return
-        self._shutdown = True
 
-        # Signal shutdown
+        # Send sentinel before setting _shutdown so in-flight on_span_end calls
+        # can still queue their jobs (they check _shutdown before putting).
         self._queue.put(None)
-
-        # Wait for thread to finish
         self._writer_thread.join(timeout=timeout)
+        self._shutdown = True
+
+        # Drain any jobs that arrived after the sentinel (race window between
+        # sentinel pickup and thread exit where on_span_end could still queue).
+        while True:
+            try:
+                job = self._queue.get_nowait()
+                if job is not None:
+                    self._process_job(job)
+            except Empty:
+                break
 
         # Finalize any remaining traces (ones that didn't have root span end yet)
         with self._lock:
@@ -223,7 +167,7 @@ class LocalTraceWriter:
             return self._traces[trace_id]
 
         # Create new trace
-        timestamp = datetime.now(timezone.utc)
+        timestamp = datetime.now(UTC)
         safe_name = self._sanitize_name(name)
         dir_name = f"{timestamp.strftime('%Y%m%d_%H%M%S')}_{trace_id[:8]}_{safe_name}"
         trace_path = self._config.path / dir_name
@@ -245,16 +189,6 @@ class LocalTraceWriter:
         # Write initial trace metadata
         self._write_trace_yaml(trace)
 
-        # Append trace start event
-        self._append_event(
-            trace,
-            {
-                "type": "trace_start",
-                "trace_id": trace_id,
-                "name": name,
-            },
-        )
-
         return trace
 
     def _writer_loop(self) -> None:
@@ -274,7 +208,7 @@ class LocalTraceWriter:
             except Exception as e:
                 logger.warning(f"Trace debug write failed for span {job.span_id}: {e}")
 
-    def _process_job(self, job: WriteJob) -> None:
+    def _process_job(self, job: WriteJob) -> None:  # noqa: PLR0914
         """Process a span end job - write all span data."""
         with self._lock:
             trace = self._traces.get(job.trace_id)
@@ -309,7 +243,7 @@ class LocalTraceWriter:
             prefect_info = self._extract_prefect_info(job.attributes)
 
             # Update span info (span_info already validated above)
-            end_time = datetime.fromtimestamp(job.end_time_ns / 1e9, tz=timezone.utc)
+            end_time = datetime.fromtimestamp(job.end_time_ns / 1e9, tz=UTC)
             span_info.end_time = end_time
             span_info.duration_ms = int((job.end_time_ns - job.start_time_ns) / 1e6)
             span_info.status = "failed" if job.status_code == "ERROR" else "completed"
@@ -317,16 +251,22 @@ class LocalTraceWriter:
             span_info.llm_info = llm_info
             span_info.prefect_info = prefect_info
 
+            # Extract description and expected_cost from span attributes
+            span_info.description = job.attributes.get("description")
+            ec = job.attributes.get("expected_cost")
+            span_info.expected_cost = float(ec) if ec is not None else None
+
             # Update trace stats
             if llm_info:
                 trace.llm_call_count += 1
                 trace.total_tokens += llm_info.get("total_tokens", 0)
                 trace.total_cost += llm_info.get("cost", 0.0)
+                llm_expected = llm_info.get("expected_cost")
+                if llm_expected is not None:
+                    trace.total_expected_cost += float(llm_expected)
 
             # Build span metadata (input_ref and output_ref are now dicts)
-            span_meta = self._build_span_metadata_v3(
-                job, input_ref, output_ref, span_type, llm_info, prefect_info
-            )
+            span_meta = self._build_span_metadata_v3(job, input_ref, output_ref, span_type, llm_info, prefect_info)
 
             # Write _span.yaml
             span_yaml_path = span_dir / "_span.yaml"
@@ -335,8 +275,8 @@ class LocalTraceWriter:
                 encoding="utf-8",
             )
 
-            # Write events.yaml based on config
-            if job.events and self._should_write_events(job.status_code):
+            # Write events.yaml (OTel span events including log records from the bridge)
+            if job.events:
                 events_data = self._format_span_events(job.events)
                 events_path = span_dir / "events.yaml"
                 events_path.write_text(
@@ -344,17 +284,6 @@ class LocalTraceWriter:
                     encoding="utf-8",
                 )
 
-            # Append to trace event log
-            self._append_event(
-                trace,
-                {
-                    "type": "span_end",
-                    "span_id": job.span_id,
-                    "status": span_info.status if span_info else "unknown",
-                    "duration_ms": span_info.duration_ms if span_info else 0,
-                },
-            )
-
             # Update index
             self._write_index(trace)
 
@@ -368,7 +297,8 @@ class LocalTraceWriter:
                 if job.trace_id in self._artifact_stores:
                     del self._artifact_stores[job.trace_id]
 
-    def _extract_input(self, attributes: dict[str, Any]) -> Any:
+    @staticmethod
+    def _extract_input(attributes: dict[str, Any]) -> Any:
         """Extract input from span attributes."""
         input_str = attributes.get("lmnr.span.input")
         if input_str:
@@ -378,7 +308,8 @@ class LocalTraceWriter:
                 return input_str
         return None
 
-    def _extract_output(self, attributes: dict[str, Any]) -> Any:
+    @staticmethod
+    def _extract_output(attributes: dict[str, Any]) -> Any:
         """Extract output from span attributes."""
         output_str = attributes.get("lmnr.span.output")
         if output_str:
@@ -388,7 +319,8 @@ class LocalTraceWriter:
                 return output_str
         return None
 
-    def _extract_span_type(self, attributes: dict[str, Any]) -> str:
+    @staticmethod
+    def _extract_span_type(attributes: dict[str, Any]) -> str:
         """Extract span type from attributes."""
         span_type = attributes.get("lmnr.span.type", "DEFAULT")
         # Map to our types
@@ -399,30 +331,29 @@ class LocalTraceWriter:
         }
         return type_map.get(span_type, "default")
 
-    def _extract_llm_info(self, attributes: dict[str, Any]) -> dict[str, Any] | None:
+    @staticmethod
+    def _extract_llm_info(attributes: dict[str, Any]) -> dict[str, Any] | None:
         """Extract LLM-specific info from attributes."""
         # Check for LLM attributes
-        input_tokens = attributes.get("gen_ai.usage.input_tokens") or attributes.get(
-            "gen_ai.usage.prompt_tokens"
-        )
-        output_tokens = attributes.get("gen_ai.usage.output_tokens") or attributes.get(
-            "gen_ai.usage.completion_tokens"
-        )
+        input_tokens = attributes.get("gen_ai.usage.input_tokens") or attributes.get("gen_ai.usage.prompt_tokens")
+        output_tokens = attributes.get("gen_ai.usage.output_tokens") or attributes.get("gen_ai.usage.completion_tokens")
 
         if input_tokens is None and output_tokens is None:
             return None
 
         return {
-            "model": attributes.get("gen_ai.response.model")
-            or attributes.get("gen_ai.request.model"),
+            "model": attributes.get("gen_ai.response.model") or attributes.get("gen_ai.request.model"),
             "provider": attributes.get("gen_ai.system"),
             "input_tokens": input_tokens or 0,
             "output_tokens": output_tokens or 0,
             "total_tokens": (input_tokens or 0) + (output_tokens or 0),
             "cost": attributes.get("gen_ai.usage.cost", 0.0),
+            "expected_cost": attributes.get("expected_cost"),
+            "purpose": attributes.get("purpose"),
         }
 
-    def _extract_prefect_info(self, attributes: dict[str, Any]) -> dict[str, Any] | None:
+    @staticmethod
+    def _extract_prefect_info(attributes: dict[str, Any]) -> dict[str, Any] | None:
         """Extract Prefect-specific info from attributes."""
         run_id = attributes.get("prefect.run.id")
         if not run_id:
@@ -435,8 +366,10 @@ class LocalTraceWriter:
             "tags": attributes.get("prefect.tags", []),
         }
 
-    def _build_span_metadata_v3(
-        self,
+    _EXCLUDED_ATTRIBUTES: frozenset[str] = frozenset({"lmnr.span.input", "lmnr.span.output"})
+
+    @staticmethod
+    def _build_span_metadata_v3(  # noqa: PLR0917
         job: WriteJob,
         input_ref: dict[str, Any],
         output_ref: dict[str, Any],
@@ -445,8 +378,8 @@ class LocalTraceWriter:
         prefect_info: dict[str, Any] | None,
     ) -> dict[str, Any]:
         """Build span metadata dictionary (V3 format with dict refs)."""
-        start_time = datetime.fromtimestamp(job.start_time_ns / 1e9, tz=timezone.utc)
-        end_time = datetime.fromtimestamp(job.end_time_ns / 1e9, tz=timezone.utc)
+        start_time = datetime.fromtimestamp(job.start_time_ns / 1e9, tz=UTC)
+        end_time = datetime.fromtimestamp(job.end_time_ns / 1e9, tz=UTC)
         duration_ms = int((job.end_time_ns - job.start_time_ns) / 1e6)
 
         meta: dict[str, Any] = {
@@ -470,6 +403,14 @@ class LocalTraceWriter:
         if llm_info:
             meta["llm"] = llm_info
 
+        # Add observability metadata
+        description = job.attributes.get("description")
+        if description:
+            meta["description"] = description
+        expected_cost = job.attributes.get("expected_cost")
+        if expected_cost is not None:
+            meta["expected_cost"] = float(expected_cost)
+
         # Add content references (input_ref and output_ref are dicts from ContentWriter.write())
         meta["input"] = input_ref
         meta["output"] = output_ref
@@ -480,18 +421,22 @@ class LocalTraceWriter:
                 "message": job.status_description,
             }
 
+        # Add raw span attributes (excluding input/output which are in separate files)
+        filtered_attrs = {k: v for k, v in job.attributes.items() if k not in LocalTraceWriter._EXCLUDED_ATTRIBUTES}
+        if filtered_attrs:
+            meta["attributes"] = filtered_attrs
+
         return meta
 
-    def _format_span_events(self, events: list[Any]) -> list[dict[str, Any]]:
+    @staticmethod
+    def _format_span_events(events: list[Any]) -> list[dict[str, Any]]:
         """Format span events for YAML output."""
-        result = []
+        result: list[dict[str, Any]] = []
         for event in events:
             try:
                 event_dict = {
                     "name": event.name,
-                    "timestamp": datetime.fromtimestamp(
-                        event.timestamp / 1e9, tz=timezone.utc
-                    ).isoformat(),
+                    "timestamp": datetime.fromtimestamp(event.timestamp / 1e9, tz=UTC).isoformat(),
                 }
                 if event.attributes:
                     event_dict["attributes"] = dict(event.attributes)
@@ -500,28 +445,8 @@ class LocalTraceWriter:
                 continue
         return result
 
-    def _should_write_events(self, status_code: str) -> bool:
-        """Check if events.yaml should be written based on config."""
-        mode = self._config.events_file_mode
-
-        if mode == "none":
-            return False
-        elif mode == "errors_only":
-            return status_code == "ERROR"
-        elif mode == "all":
-            return True
-        else:
-            # Default to errors_only if unknown mode
-            return status_code == "ERROR"
-
-    def _append_event(self, trace: TraceState, event: dict[str, Any]) -> None:
-        """Append event to trace event log (JSONL format)."""
-        event["ts"] = datetime.now(timezone.utc).isoformat()
-        events_path = trace.path / "_events.jsonl"
-        with events_path.open("a", encoding="utf-8") as f:
-            f.write(json.dumps(event) + "\n")
-
-    def _write_trace_yaml(self, trace: TraceState) -> None:
+    @staticmethod
+    def _write_trace_yaml(trace: TraceState) -> None:
         """Write _trace.yaml file."""
         trace_meta = {
             "trace_id": trace.trace_id,
@@ -564,10 +489,11 @@ class LocalTraceWriter:
         if self._config.include_error_index:
             self._write_errors_index(trace, sorted_spans)
 
-    def _write_tree_index(self, trace: TraceState, sorted_spans: list[SpanInfo]) -> None:
+    @staticmethod
+    def _write_tree_index(trace: TraceState, sorted_spans: list[SpanInfo]) -> None:
         """Write _tree.yaml - lightweight tree structure (~5KB)."""
         span_paths: dict[str, str] = {}
-        tree_entries = []
+        tree_entries: list[dict[str, Any]] = []
 
         for span in sorted_spans:
             # Skip spans that were identified as wrappers during merge
@@ -596,7 +522,7 @@ class LocalTraceWriter:
 
             tree_entries.append(entry)
 
-        tree_data = {
+        tree_data: dict[str, Any] = {
             "format_version": 3,
             "trace_id": trace.trace_id,
             "root_span_id": trace.root_span_id,
@@ -611,9 +537,10 @@ class LocalTraceWriter:
             encoding="utf-8",
         )
 
-    def _write_llm_index(self, trace: TraceState, sorted_spans: list[SpanInfo]) -> None:
+    @staticmethod
+    def _write_llm_index(trace: TraceState, sorted_spans: list[SpanInfo]) -> None:
         """Write _llm_calls.yaml - LLM-specific details."""
-        llm_calls = []
+        llm_calls: list[dict[str, Any]] = []
 
         for span in sorted_spans:
             if span.llm_info:
@@ -634,6 +561,8 @@ class LocalTraceWriter:
                     "output_tokens": span.llm_info.get("output_tokens", 0),
                     "total_tokens": span.llm_info.get("total_tokens", 0),
                     "cost": span.llm_info.get("cost", 0.0),
+                    "expected_cost": span.llm_info.get("expected_cost"),
+                    "purpose": span.llm_info.get("purpose"),
                     "duration_ms": span.duration_ms,
                     "status": span.status,
                     "path": relative_path,
@@ -644,12 +573,13 @@ class LocalTraceWriter:
 
                 llm_calls.append(llm_entry)
 
-        llm_data = {
+        llm_data: dict[str, Any] = {
             "format_version": 3,
             "trace_id": trace.trace_id,
             "llm_call_count": len(llm_calls),
             "total_tokens": trace.total_tokens,
             "total_cost": round(trace.total_cost, 6),
+            "total_expected_cost": round(trace.total_expected_cost, 6),
             "calls": llm_calls,
         }
 
@@ -659,9 +589,10 @@ class LocalTraceWriter:
             encoding="utf-8",
         )
 
-    def _write_errors_index(self, trace: TraceState, sorted_spans: list[SpanInfo]) -> None:
+    @staticmethod
+    def _write_errors_index(trace: TraceState, sorted_spans: list[SpanInfo]) -> None:
         """Write _errors.yaml - failed spans only."""
-        error_spans = []
+        error_spans: list[dict[str, Any]] = []
 
         for span in sorted_spans:
             if span.status == "failed":
@@ -682,7 +613,7 @@ class LocalTraceWriter:
                     error_entry["end_time"] = span.end_time.isoformat()
 
                 # Get parent chain for context
-                parent_chain = []
+                parent_chain: list[str] = []
                 current_id = span.parent_id
                 while current_id and current_id in trace.spans:
                     parent = trace.spans[current_id]
@@ -694,7 +625,7 @@ class LocalTraceWriter:
                 error_spans.append(error_entry)
 
         if error_spans:  # Only write if there are errors
-            errors_data = {
+            errors_data: dict[str, Any] = {
                 "format_version": 3,
                 "trace_id": trace.trace_id,
                 "error_count": len(error_spans),
@@ -703,13 +634,12 @@ class LocalTraceWriter:
 
             errors_path = trace.path / "_errors.yaml"
             errors_path.write_text(
-                yaml.dump(
-                    errors_data, default_flow_style=False, allow_unicode=True, sort_keys=False
-                ),
+                yaml.dump(errors_data, default_flow_style=False, allow_unicode=True, sort_keys=False),
                 encoding="utf-8",
             )
 
-    def _detect_wrapper_spans(self, trace: TraceState) -> set[str]:
+    @staticmethod
+    def _detect_wrapper_spans(trace: TraceState) -> set[str]:
         """Detect Prefect wrapper spans that should be merged with their inner spans.
 
         Detection criteria:
@@ -718,7 +648,7 @@ class LocalTraceWriter:
         3. Parent has no I/O (input type is "none")
         4. Parent has prefect.run.id, child does not
         """
-        wrappers = set()
+        wrappers: set[str] = set()
 
         for span_id, span in trace.spans.items():
             # Must have exactly one child
@@ -798,17 +728,16 @@ class LocalTraceWriter:
                 if wrapper_id in grandparent.children:
                     idx = grandparent.children.index(wrapper_id)
                     grandparent.children[idx] = child_id
-            else:
-                # Wrapper was root - child becomes new root
-                if trace.root_span_id == wrapper_id:
-                    trace.root_span_id = child_id
+            # Wrapper was root - child becomes new root
+            elif trace.root_span_id == wrapper_id:
+                trace.root_span_id = child_id
 
             # Mark wrapper as merged (used in index generation)
             wrapper.children = []  # Clear to indicate it's merged
 
     def _finalize_trace(self, trace: TraceState) -> None:
         """Finalize a trace - update metadata and generate summary."""
-        end_time = datetime.now(timezone.utc)
+        end_time = datetime.now(UTC)
         duration = (end_time - trace.start_time).total_seconds()
 
         # Determine final status
@@ -835,6 +764,7 @@ class LocalTraceWriter:
                 "llm_calls": trace.llm_call_count,
                 "total_tokens": trace.total_tokens,
                 "total_cost": round(trace.total_cost, 6),
+                "total_expected_cost": round(trace.total_expected_cost, 6),
             },
         }
 
@@ -848,24 +778,30 @@ class LocalTraceWriter:
         self._write_index(trace)
 
         # Generate summary if enabled
+        summary: str | None = None
         if self._config.generate_summary:
-            # Lazy import to avoid circular dependency
-            from .summary import generate_summary  # noqa: PLC0415
-
             summary = generate_summary(trace)
             summary_path = trace.path / "_summary.md"
             summary_path.write_text(summary, encoding="utf-8")
 
-        # Append trace end event
-        self._append_event(
-            trace,
-            {
-                "type": "trace_end",
-                "trace_id": trace.trace_id,
-                "status": status,
-                "duration_seconds": round(duration, 2),
-            },
-        )
+        # Generate LLM-powered auto-summary if enabled.
+        # asyncio.run() is unsafe when the current thread already has a running event loop.
+        # Skip if static summary is unavailable: auto-summary uses it as context input.
+        has_running_loop = False
+        try:
+            asyncio.get_running_loop()
+            has_running_loop = True
+        except RuntimeError:
+            pass
+        if self._config.auto_summary_enabled and not has_running_loop and summary is not None:
+            try:
+                auto_mod = importlib.import_module("ai_pipeline_core.observability._debug._auto_summary")
+                auto_summary_text = asyncio.run(auto_mod.generate_auto_summary(trace, summary, self._config.auto_summary_model))
+                if auto_summary_text:
+                    auto_summary_path = trace.path / "_auto_summary.md"
+                    auto_summary_path.write_text(auto_summary_text, encoding="utf-8")
+            except Exception as e:
+                logger.warning(f"Auto-summary generation failed: {e}")
 
     def _cleanup_old_traces(self) -> None:
         """Delete old traces beyond max_traces limit."""
@@ -873,10 +809,7 @@ class LocalTraceWriter:
             return
 
         # Get all trace directories sorted by modification time
-        trace_dirs = []
-        for path in self._config.path.iterdir():
-            if path.is_dir() and (path / "_trace.yaml").exists():
-                trace_dirs.append((path.stat().st_mtime, path))
+        trace_dirs = [(path.stat().st_mtime, path) for path in self._config.path.iterdir() if path.is_dir() and (path / "_trace.yaml").exists()]
 
         trace_dirs.sort(reverse=True)  # Newest first
 
@@ -887,7 +820,8 @@ class LocalTraceWriter:
             except Exception as e:
                 logger.warning(f"Failed to delete old trace {path}: {e}")
 
-    def _sanitize_name(self, name: str) -> str:
+    @staticmethod
+    def _sanitize_name(name: str) -> str:
         """Sanitize name for safe filesystem use.
 
         Truncates to 24 chars + 4-char hash to avoid collisions and keep
@@ -897,11 +831,7 @@ class LocalTraceWriter:
         safe = safe.strip(". ")
 
         # Handle Windows reserved names (CON, PRN, AUX, NUL, COM1-9, LPT1-9)
-        reserved = (
-            {"CON", "PRN", "AUX", "NUL"}
-            | {f"COM{i}" for i in range(1, 10)}
-            | {f"LPT{i}" for i in range(1, 10)}
-        )
+        reserved = {"CON", "PRN", "AUX", "NUL"} | {f"COM{i}" for i in range(1, 10)} | {f"LPT{i}" for i in range(1, 10)}
         if safe.upper() in reserved:
             safe = f"_{safe}"