oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/reporting/content/executive.py

@@ -0,0 +1,127 @@
+"""Executive summary auto-generation.
+
+Automatically generates concise executive summaries with key findings,
+pass/fail status, and critical violations highlighted.
+
+
+References:
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+@dataclass
+class ExecutiveSummary:
+    """Executive summary of analysis results.
+
+    Attributes:
+        overall_status: Overall pass/fail status.
+        pass_count: Number of passing tests.
+        total_count: Total number of tests.
+        key_findings: List of 3-5 key findings.
+        critical_violations: List of critical violations.
+        min_margin_pct: Minimum margin percentage.
+        summary_text: Natural language summary.
+
+    References:
+        REPORT-004: Executive Summary Auto-Generation
+    """
+
+    overall_status: bool
+    pass_count: int
+    total_count: int
+    key_findings: list[str] = field(default_factory=list)
+    critical_violations: list[str] = field(default_factory=list)
+    min_margin_pct: float | None = None
+    summary_text: str = ""
+
+
+def generate_executive_summary(
+    results: dict[str, Any],
+    *,
+    max_findings: int = 5,
+    length: Literal["short", "detailed"] = "short",
+) -> ExecutiveSummary:
+    """Generate executive summary from analysis results.
+
+    Automatically extracts top 3-5 key findings, pass/fail status in first
+    sentence, and critical violations in bullet list.
+
+    Args:
+        results: Analysis results dictionary.
+        max_findings: Maximum number of key findings (default 5).
+        length: Summary length (short=1 paragraph, detailed=1 page).
+
+    Returns:
+        ExecutiveSummary with generated content.
+
+    Example:
+        >>> results = {"pass_count": 10, "total_count": 12}
+        >>> summary = generate_executive_summary(results)
+        >>> print(summary.summary_text)
+        'All 10 tests passed with >25% margin. No violations.'
+
+    References:
+        REPORT-004: Executive Summary Auto-Generation
+    """
+    # Extract basic counts
+    pass_count = results.get("pass_count", 0)
+    total_count = results.get("total_count", 0)
+    fail_count = total_count - pass_count if total_count else 0
+    overall_status = fail_count == 0
+
+    # Extract violations
+    violations = results.get("violations", [])
+    critical_violations = [v for v in violations if v.get("severity", "").lower() == "critical"]
+
+    # Extract key findings
+    key_findings: list[str] = []
+    if critical_violations:
+        key_findings.append(
+            f"{len(critical_violations)} critical violation(s) require immediate attention"
+        )
+    elif violations:
+        key_findings.append(f"{len(violations)} violation(s) detected")
+
+    # Add margin information
+    min_margin = results.get("min_margin")
+    if min_margin is not None and min_margin < 20:
+        status = "critical" if min_margin < 10 else "marginal"
+        key_findings.append(f"Minimum margin is {min_margin:.1f}% ({status})")
+
+    # Build summary text in natural language
+    if overall_status and total_count > 0:
+        summary_text = f"All {pass_count} tests passed."
+        if min_margin is not None and min_margin > 20:
+            summary_text += f" Minimum margin: {min_margin:.1f}%."
+    elif total_count > 0:
+        pct = fail_count / total_count * 100
+        summary_text = f"{fail_count} of {total_count} tests failed ({pct:.0f}% failure rate)."
+    else:
+        summary_text = "Analysis completed successfully."
+
+    if critical_violations:
+        summary_text += (
+            f" Critical: {len(critical_violations)} violation(s) require immediate action."
+        )
+
+    # Add detailed findings for detailed mode
+    if length == "detailed" and key_findings:
+        summary_text += "\n\nKey Findings:\n"
+        summary_text += "\n".join(f"  - {finding}" for finding in key_findings[:max_findings])
+
+    return ExecutiveSummary(
+        overall_status=overall_status,
+        pass_count=pass_count,
+        total_count=total_count,
+        key_findings=key_findings[:max_findings],
+        critical_violations=[str(v) for v in critical_violations],
+        min_margin_pct=min_margin,
+        summary_text=summary_text,
+    )
+
+
+__all__ = ["ExecutiveSummary", "generate_executive_summary"]

oscura/reporting/content/filtering.py

@@ -0,0 +1,191 @@
+"""Smart content filtering for reports.
+
+Shows only relevant information based on context, severity, and audience
+with conditional sections and violation-only modes.
+
+
+References:
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Literal
+
+from oscura.reporting.formatting.standards import Severity
+
+
+class AudienceType(Enum):
+    """Audience types for content filtering."""
+
+    EXECUTIVE = "executive"
+    ENGINEERING = "engineering"
+    DEBUG = "debug"
+    REGULATORY = "regulatory"
+    PRODUCTION = "production"
+
+
+@dataclass
+class ContentFilter:
+    """Smart content filtering configuration.
+
+    Attributes:
+        severity_threshold: Minimum severity to show (critical/warning/info).
+        audience: Target audience type.
+        show_only: Show only specific content (violations, changes, all).
+        hide_empty_sections: Hide sections with no data.
+        relevance_threshold: Minimum relevance score (0.0-1.0).
+
+    References:
+        REPORT-005: Smart Content Filtering
+    """
+
+    severity_threshold: Severity = Severity.INFO
+    audience: AudienceType = AudienceType.ENGINEERING
+    show_only: Literal["all", "violations", "changes"] = "all"
+    hide_empty_sections: bool = True
+    relevance_threshold: float = 0.5
+
+
+def filter_by_severity(
+    items: list[dict[str, Any]],
+    min_severity: Severity | str,
+) -> list[dict[str, Any]]:
+    """Filter items by severity level.
+
+    Args:
+        items: List of items with 'severity' field.
+        min_severity: Minimum severity to include.
+
+    Returns:
+        Filtered list of items.
+
+    Example:
+        >>> items = [{"name": "test1", "severity": "critical"},
+        ...          {"name": "test2", "severity": "info"}]
+        >>> filtered = filter_by_severity(items, "warning")
+        >>> len(filtered)  # Only critical items
+        1
+
+    References:
+        REPORT-005: Smart Content Filtering
+    """
+    if isinstance(min_severity, str):
+        min_severity = Severity(min_severity.lower())
+
+    severity_order = {
+        Severity.INFO: 0,
+        Severity.WARNING: 1,
+        Severity.ERROR: 2,
+        Severity.CRITICAL: 3,
+    }
+
+    min_level = severity_order.get(min_severity, 0)
+
+    filtered = []
+    for item in items:
+        item_severity_str = item.get("severity", "info").lower()
+        try:
+            item_severity = Severity(item_severity_str)
+            item_level = severity_order.get(item_severity, 0)
+            if item_level >= min_level:
+                filtered.append(item)
+        except (ValueError, KeyError):
+            continue
+
+    return filtered
+
+
+def filter_by_audience(
+    content: dict[str, Any],
+    audience: AudienceType | str,
+) -> dict[str, Any]:
+    """Filter content for specific audience.
+
+    Args:
+        content: Content dictionary with various sections.
+        audience: Target audience type.
+
+    Returns:
+        Filtered content dictionary.
+
+    Example:
+        >>> content = {"methodology": "...", "results": "...", "raw_data": "..."}
+        >>> filtered = filter_by_audience(content, "executive")
+        >>> "raw_data" in filtered  # False - executives don't need raw data
+        False
+
+    References:
+        REPORT-005: Smart Content Filtering
+    """
+    if isinstance(audience, str):
+        audience = AudienceType(audience.lower())
+
+    # Define what each audience sees
+    audience_sections = {
+        AudienceType.EXECUTIVE: ["executive_summary", "key_findings", "recommendations"],
+        AudienceType.ENGINEERING: ["summary", "results", "methodology", "plots"],
+        AudienceType.DEBUG: ["summary", "results", "methodology", "plots", "raw_data", "logs"],
+        AudienceType.REGULATORY: ["summary", "compliance", "test_procedures", "standards"],
+        AudienceType.PRODUCTION: ["summary", "pass_fail", "margin", "yield"],
+    }
+
+    allowed_sections = audience_sections.get(audience, list(content.keys()))
+
+    filtered = {}
+    for key, value in content.items():
+        if key in allowed_sections:
+            filtered[key] = value
+
+    return filtered
+
+
+def calculate_relevance_score(
+    item: dict[str, Any],
+    context: dict[str, Any] | None = None,
+) -> float:
+    """Calculate relevance score for content item.
+
+    Args:
+        item: Content item.
+        context: Optional context for relevance scoring.
+
+    Returns:
+        Relevance score 0.0-1.0.
+
+    References:
+        REPORT-005: Smart Content Filtering
+    """
+    score = 0.5  # Base score
+
+    # Increase score for violations
+    if item.get("status") == "fail":
+        score += 0.3
+
+    # Increase score for critical severity
+    severity = item.get("severity", "").lower()
+    if severity == "critical":
+        score += 0.3
+    elif severity == "warning":
+        score += 0.1
+
+    # Increase score for outliers
+    if item.get("is_outlier"):
+        score += 0.2
+
+    # Increase score for low margins
+    margin = item.get("margin_pct")
+    if margin is not None and margin < 20:
+        score += 0.2
+
+    return min(1.0, score)
+
+
+__all__ = [
+    "AudienceType",
+    "ContentFilter",
+    "calculate_relevance_score",
+    "filter_by_audience",
+    "filter_by_severity",
+]

oscura/reporting/content/minimal.py

@@ -0,0 +1,257 @@
+"""Minimal boilerplate content generation.
+
+This module eliminates unnecessary static text and focuses on data-driven
+narrative with compact formatting and automated captions.
+
+
+Example:
+    >>> from oscura.reporting.content import generate_compact_text
+    >>> compact = generate_compact_text(value=2.3e-9, spec=5e-9, unit="s")
+    >>> print(compact)  # "Rise time: 2.3ns (spec <5ns, ✓ 54% margin)"
+
+References:
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+
+@dataclass
+class MinimalContent:
+    """Minimal boilerplate content generator.
+
+    Focuses on data-driven content with minimal filler text.
+
+    Attributes:
+        auto_units: Auto-scale units (2300ns → 2.3μs).
+        data_first: Show results before methodology.
+        show_passing: Include passing tests or violations only.
+        auto_captions: Generate captions from data, not static templates.
+
+    References:
+        REPORT-003: Minimal Boilerplate Content
+    """
+
+    auto_units: bool = True
+    data_first: bool = True
+    show_passing: bool = True
+    auto_captions: bool = True
+
+
+def generate_compact_text(
+    value: float,
+    spec: float | None = None,
+    unit: str = "",
+    *,
+    spec_type: Literal["max", "min"] = "max",
+    name: str = "",
+) -> str:
+    """Generate compact, data-driven text.
+
+    Avoids filler text like "The measurement was performed and the result was...".
+    Instead produces compact format: "Rise time: 2.3ns (spec <5ns, ✓ 54% margin)".
+
+    Args:
+        value: Measured value.
+        spec: Specification limit (optional).
+        unit: Unit string.
+        spec_type: Type of specification (max or min).
+        name: Measurement name (optional).
+
+    Returns:
+        Compact formatted string.
+
+    Example:
+        >>> generate_compact_text(2.3e-9, 5e-9, "s", name="Rise time")
+        'Rise time: 2.3ns (spec <5ns, ✓ 54% margin)'
+
+    References:
+        REPORT-003: Minimal Boilerplate Content
+    """
+    from oscura.reporting.formatting.numbers import format_with_units
+
+    # Format value with auto-scaled units
+    value_str = format_with_units(value, unit)
+
+    # Build compact text
+    parts = []
+    if name:
+        parts.append(f"{name}:")
+
+    parts.append(value_str)
+
+    # Add spec context if provided
+    if spec is not None:
+        spec_str = format_with_units(spec, unit)
+        spec_symbol = "<" if spec_type == "max" else ">"
+
+        # Calculate pass/fail and margin
+        if spec_type == "max":
+            passed = value <= spec
+            margin = (spec - value) / spec * 100 if spec != 0 else 0
+        else:
+            passed = value >= spec
+            margin = (value - spec) / spec * 100 if spec != 0 else 0
+
+        status_symbol = "\u2713" if passed else "\u2717"  # ✓ or ✗
+        spec_part = f"(spec {spec_symbol}{spec_str}, {status_symbol} {margin:.0f}% margin)"
+        parts.append(spec_part)
+
+    return " ".join(parts)
+
+
+def auto_caption(
+    data_type: str,
+    data: dict[str, Any],
+    *,
+    include_stats: bool = True,
+) -> str:
+    """Generate automated captions from data.
+
+    Instead of static templates, generates captions based on actual data content.
+
+    Args:
+        data_type: Type of data (measurement, plot, table).
+        data: Data dictionary.
+        include_stats: Include statistics in caption.
+
+    Returns:
+        Generated caption string.
+
+    Example:
+        >>> data = {"name": "Rise time", "count": 100, "mean": 2.3e-9}
+        >>> auto_caption("measurement", data)
+        'Rise time measurement (n=100, mean=2.3ns)'
+
+    References:
+        REPORT-003: Minimal Boilerplate Content
+    """
+    parts = []
+
+    # Extract key information
+    name = data.get("name", data_type.title())
+    parts.append(name)
+
+    # Add data-specific information
+    if data_type == "measurement" and include_stats:
+        count = data.get("count")
+        if count:
+            parts.append(f"(n={count}")
+
+            mean = data.get("mean")
+            if mean is not None:
+                from oscura.reporting.formatting.numbers import format_with_units
+
+                unit = data.get("unit", "")
+                mean_str = format_with_units(mean, unit)
+                parts[-1] += f", mean={mean_str}"
+
+            parts[-1] += ")"
+
+    elif data_type == "plot":
+        plot_type = data.get("type", "plot")
+        if plot_type != "plot":
+            parts.append(f"- {plot_type}")
+
+    elif data_type == "table":
+        rows = data.get("rows")
+        cols = data.get("cols")
+        if rows and cols:
+            parts.append(f"({rows}x{cols})")
+
+    return " ".join(parts)
+
+
+def remove_filler_text(text: str) -> str:
+    """Remove common filler phrases from text.
+
+    Args:
+        text: Input text.
+
+    Returns:
+        Text with filler removed.
+
+    Example:
+        >>> text = "The measurement was performed and the result was 2.3ns."
+        >>> remove_filler_text(text)
+        'Result: 2.3ns.'
+
+    References:
+        REPORT-003: Minimal Boilerplate Content
+    """
+    # Common filler phrases to remove
+    filler_phrases = [
+        "The measurement was performed and",
+        "The result was",
+        "It was found that",
+        "The analysis shows that",
+        "It can be seen that",
+        "As can be observed",
+        "The data indicates",
+        "It should be noted that",
+    ]
+
+    result = text
+    for phrase in filler_phrases:
+        result = result.replace(phrase, "").strip()
+
+    # Clean up extra spaces
+    while "  " in result:
+        result = result.replace("  ", " ")
+
+    # Capitalize first letter after removal
+    if result and not result[0].isupper():
+        result = result[0].upper() + result[1:]
+
+    return result
+
+
+def conditional_section(
+    data: list[Any] | dict[str, Any],
+    section_title: str,
+) -> tuple[bool, str]:
+    """Determine if section should be shown.
+
+    Only show sections if data exists (no empty sections).
+
+    Args:
+        data: Section data.
+        section_title: Section title.
+
+    Returns:
+        Tuple of (should_show, reason).
+
+    Example:
+        >>> should_show, reason = conditional_section([], "Violations")
+        >>> print(should_show)  # False
+        >>> print(reason)  # "No violations found"
+
+    References:
+        REPORT-003: Minimal Boilerplate Content
+    """
+    if isinstance(data, list):
+        if not data:
+            return False, f"No {section_title.lower()} found"
+        return True, f"{len(data)} {section_title.lower()}"
+
+    elif isinstance(data, dict):
+        if not data or all(not v for v in data.values()):
+            return False, f"No {section_title.lower()} found"
+        return True, ""
+
+    else:
+        # For other types, check if truthy
+        if not data:  # type: ignore[unreachable]
+            return False, f"No {section_title.lower()} found"
+        return True, ""
+
+
+__all__ = [
+    "MinimalContent",
+    "auto_caption",
+    "conditional_section",
+    "generate_compact_text",
+    "remove_filler_text",
+]