project-risk-agent 0.2.0__py3-none-any.whl

project_risk_agent/__init__.py

@@ -0,0 +1,3 @@
+"""Project Risk Agent."""
+
+__version__ = "0.2.0"

project_risk_agent/analysis.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from hashlib import sha256
+
+from project_risk_agent.decisions import extract_decision_requests
+from project_risk_agent.evidence import evidence_for_signals
+from project_risk_agent.models import Evidence, Finding, FindingType, ProjectSignal, RiskCategory
+from project_risk_agent.temporal import has_repeated_change, signal_sequence
+
+PATTERNS: tuple[tuple[str, RiskCategory], ...] = (
+    (r"\b(delayed?|slipp(?:ed|ing)|miss(?:ed|ing)|behind|cannot start|can't start)\b", RiskCategory.SCHEDULE),
+    (r"\b(moved from .+ to .+|date change|date changed|schedule changed|second date change|another date change)\b", RiskCategory.SCHEDULE),
+    (r"\b(depend(?:ency|encies)|depends on|waiting for|blocked by|until .+ is available)\b", RiskCategory.DEPENDENCY),
+    (r"\b(understaffed|no capacity|resource constraint|vacancy|bandwidth)\b", RiskCategory.RESOURCE),
+    (r"\b(scope creep|out of scope|requirements changed|change request)\b", RiskCategory.SCOPE),
+    (r"\b(defect|bug|failed test|quality issue|regression)\b", RiskCategory.QUALITY),
+    (r"\b(vendor|supplier|third party)\b", RiskCategory.VENDOR),
+    (r"\b(budget|cost overrun|funding|financial)\b", RiskCategory.FINANCIAL),
+    (r"\b(customer escalation|stakeholder concern|sponsor concern)\b", RiskCategory.STAKEHOLDER),
+    (r"\b(outage|integration failure|performance issue|technical debt)\b", RiskCategory.TECHNICAL),
+)
+
+
+def _matched_categories(text: str) -> list[RiskCategory]:
+    lowered = text.lower()
+    return [category for pattern, category in PATTERNS if re.search(pattern, lowered)]
+
+
+def _finding_id(signals: list[ProjectSignal], finding_type: FindingType, category: RiskCategory) -> str:
+    raw = ":".join(sorted(s.id for s in signals)) + f":{finding_type.value}:{category.value}"
+    return "finding-" + sha256(raw.encode()).hexdigest()[:12]
+
+
+class SignalReasoner:
+    """Conservative, evidence-first reasoning baseline."""
+
+    def analyze(self, signals: list[ProjectSignal]) -> list[Finding]:
+        findings: list[Finding] = []
+        ordered = signal_sequence(signals)
+        decision_requests = {request.signal_id: request for request in extract_decision_requests(signals)}
+        for signal in signals:
+            text = signal.content.strip()
+            if not text:
+                continue
+            categories = _matched_categories(text)
+            finding_type = self._finding_type(text)
+            if not categories and finding_type != FindingType.DECISION:
+                continue
+            category = self._category(categories, finding_type)
+            decision = decision_requests.get(signal.id)
+            findings.append(
+                Finding(
+                    id=_finding_id([signal], finding_type, category),
+                    type=finding_type,
+                    category=category,
+                    title=self._title(finding_type, category),
+                    description=text[:500],
+                    likelihood=self._likelihood(text),
+                    impact=self._impact(text),
+                    urgency=self._urgency(text),
+                    confidence=0.68,
+                    evidence=[Evidence(signal_id=signal.id, excerpt=text[:500], rationale="Signal contains language associated with a management concern.")],
+                    owner=decision.owner if decision else None,
+                    decision_required=finding_type == FindingType.DECISION,
+                    decision_owner=decision.owner if decision and finding_type == FindingType.DECISION else None,
+                    decision_deadline=decision.deadline if decision and finding_type == FindingType.DECISION else None,
+                    recommended_actions=self._actions(finding_type, category),
+                )
+            )
+        findings = self._corroborate(findings)
+        findings = self._infer_contradictions(ordered, findings)
+        findings = self._infer_cross_signal_schedule_risk(ordered, findings)
+        return self._infer_recurring_patterns(ordered, findings)
+
+    @staticmethod
+    def _category(categories: list[RiskCategory], finding_type: FindingType) -> RiskCategory:
+        if finding_type == FindingType.DEPENDENCY and RiskCategory.DEPENDENCY in categories:
+            return RiskCategory.DEPENDENCY
+        return categories[0] if categories else RiskCategory.OTHER
+
+    @staticmethod
+    def _corroborate(findings: list[Finding]) -> list[Finding]:
+        groups: dict[tuple[FindingType, RiskCategory], list[Finding]] = defaultdict(list)
+        for finding in findings:
+            groups[(finding.type, finding.category)].append(finding)
+        output: list[Finding] = []
+        for group in groups.values():
+            primary = group[0]
+            if len(group) > 1:
+                primary.evidence = [e for item in group for e in item.evidence]
+                primary.confidence = min(0.95, primary.confidence + 0.08 * (len(group) - 1))
+                primary.description = f"Corroborated by {len(group)} project signals. " + primary.description
+            output.append(primary)
+        return output
+
+    @staticmethod
+    def _infer_contradictions(signals: list[ProjectSignal], findings: list[Finding]) -> list[Finding]:
+        """Surface materially conflicting status language as a human-reviewable risk."""
+        positive = re.compile(r"\b(on track|on schedule|on time|still on track|no delay)\b", re.IGNORECASE)
+        negative = re.compile(r"\b(delayed?|slipp(?:ed|ing)|behind schedule|date changed|moved from .+ to .+)\b", re.IGNORECASE)
+        if not any(positive.search(s.content) for s in signals) or not any(negative.search(s.content) for s in signals):
+            return findings
+        evidence = evidence_for_signals(signals, lambda s: bool(positive.search(s.content) or negative.search(s.content)), "Conflicting schedule-status language requires human verification.")
+        existing = next((f for f in findings if f.type == FindingType.RISK and f.category == RiskCategory.SCHEDULE), None)
+        if existing:
+            existing.evidence = evidence
+            existing.confidence = min(0.95, max(existing.confidence, 0.84))
+            existing.description = "Project signals contain conflicting schedule-status statements."
+            existing.recommended_actions = ["Reconcile the conflicting status updates with the project owner and confirm the current schedule baseline."]
+            return findings
+        findings.append(Finding(id=_finding_id(signals, FindingType.RISK, RiskCategory.SCHEDULE), type=FindingType.RISK, category=RiskCategory.SCHEDULE, title="Conflicting schedule status", description="Project signals contain conflicting schedule-status statements.", likelihood="medium", impact="medium", urgency="medium", confidence=0.84, evidence=evidence, recommended_actions=["Reconcile the conflicting status updates with the project owner and confirm the current schedule baseline."]))
+        return findings
+
+    def _infer_cross_signal_schedule_risk(self, signals: list[ProjectSignal], findings: list[Finding]) -> list[Finding]:
+        movement_pattern = r"\b(moved from .+ to .+|date change|date changed|schedule changed|delayed?|slipp(?:ed|ing)|pushed)\b"
+        dependency_pattern = r"\b(depends on|dependency|dependencies|waiting for|blocked by|cannot start|until .+ is available)\b"
+        has_schedule_movement = any(re.search(movement_pattern, s.content.lower()) for s in signals)
+        has_downstream_dependency = any(re.search(dependency_pattern, s.content.lower()) for s in signals)
+        repeated_change = has_repeated_change(signals)
+        if not ((has_schedule_movement and has_downstream_dependency) or repeated_change):
+            return findings
+        evidence = evidence_for_signals(signals, lambda s: bool(re.search(movement_pattern + "|" + dependency_pattern, s.content.lower())), "Cross-signal evidence for schedule exposure.")
+        existing = next((f for f in findings if f.type == FindingType.RISK and f.category == RiskCategory.SCHEDULE), None)
+        if existing:
+            existing.evidence = evidence or existing.evidence
+            existing.confidence = min(0.95, max(existing.confidence, 0.82 if has_downstream_dependency else 0.78))
+            if repeated_change and has_downstream_dependency:
+                existing.description = "Repeated schedule movement is coupled to a downstream dependency."
+                existing.likelihood = "high"
+            elif repeated_change:
+                existing.description = "Repeated schedule or status changes indicate increasing schedule exposure."
+            return findings
+        findings.append(Finding(id=_finding_id(signals, FindingType.RISK, RiskCategory.SCHEDULE), type=FindingType.RISK, category=RiskCategory.SCHEDULE, title="Potential schedule concern", description="Repeated schedule or status changes are creating schedule exposure." if repeated_change and not has_downstream_dependency else "Schedule movement is coupled to a downstream dependency.", likelihood="high" if has_downstream_dependency else "medium", impact="medium", urgency="medium", confidence=0.82 if has_downstream_dependency else 0.78, evidence=evidence, recommended_actions=["Validate the dependency date and downstream contingency with the owners."]))
+        return findings
+
+    @staticmethod
+    def _infer_recurring_patterns(signals: list[ProjectSignal], findings: list[Finding]) -> list[Finding]:
+        """Increase attention when the same concern recurs across distinct project updates."""
+        category_counts: dict[RiskCategory, int] = defaultdict(int)
+        for signal in signals:
+            for category in _matched_categories(signal.content):
+                category_counts[category] += 1
+        for finding in findings:
+            count = category_counts.get(finding.category, 0)
+            if count < 3 or len(finding.evidence) < 2:
+                continue
+            finding.confidence = min(0.95, finding.confidence + 0.06)
+            if finding.likelihood == "medium":
+                finding.likelihood = "high"
+            finding.description = f"Recurring across {count} project signals. {finding.description}"
+            finding.recommended_actions.append("Review the recurring pattern and address the underlying cause rather than the latest symptom.")
+        return findings
+
+    @staticmethod
+    def _finding_type(text: str) -> FindingType:
+        lowered = text.lower()
+        if re.search(r"\b(decision|decide|approval|approve|choose|needs sign[- ]off)\b", lowered):
+            return FindingType.DECISION
+        if re.search(r"\b(risk|at risk|may miss|might miss|could miss|potential)\b", lowered):
+            return FindingType.RISK
+        if re.search(r"\b(already missed|has failed|failed test|outage|currently blocked|currently unavailable)\b", lowered):
+            return FindingType.ISSUE
+        if re.search(r"\b(depends on|dependency|dependencies|waiting for|blocked by|cannot start|can't start|until .+ is available)\b", lowered):
+            return FindingType.DEPENDENCY
+        return FindingType.RISK
+
+    @staticmethod
+    def _title(finding_type: FindingType, category: RiskCategory) -> str:
+        prefix = {FindingType.RISK: "Potential", FindingType.ISSUE: "Active", FindingType.DEPENDENCY: "Dependency", FindingType.DECISION: "Decision needed for"}[finding_type]
+        return f"{prefix} {category.value} concern"
+
+    @staticmethod
+    def _likelihood(text: str) -> str:
+        lowered = text.lower()
+        return "high" if re.search(r"\b(blocked|cannot|critical|miss|failed)\b", lowered) else "medium"
+
+    @staticmethod
+    def _impact(text: str) -> str:
+        lowered = text.lower()
+        return "high" if re.search(r"\b(launch|deadline|critical|customer|revenue|production)\b", lowered) else "medium"
+
+    @staticmethod
+    def _urgency(text: str) -> str:
+        lowered = text.lower()
+        return "high" if re.search(r"\b(today|tomorrow|blocked|critical|production|outage)\b", lowered) else "medium"
+
+    @staticmethod
+    def _actions(finding_type: FindingType, category: RiskCategory) -> list[str]:
+        if finding_type == FindingType.DECISION:
+            return ["Confirm the decision owner and required decision date."]
+        if finding_type == FindingType.DEPENDENCY:
+            return ["Confirm the dependency owner, required-by date, and contingency."]
+        if finding_type == FindingType.ISSUE:
+            return ["Assign an owner, recovery action, and next checkpoint."]
+        return [f"Validate the {category.value} concern with the responsible owner."]

project_risk_agent/analyzer.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from project_risk_agent.analysis import SignalReasoner
+from project_risk_agent.models import Finding, ProjectSignal
+
+
+class RiskAnalyzer:
+    """Public analysis facade for the project risk agent."""
+
+    def __init__(self, reasoner: SignalReasoner | None = None) -> None:
+        self.reasoner = reasoner or SignalReasoner()
+
+    def analyze(self, signals: list[ProjectSignal]) -> list[Finding]:
+        return self.reasoner.analyze(signals)

project_risk_agent/api.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from pydantic import BaseModel
+
+from project_risk_agent.analyzer import RiskAnalyzer
+from project_risk_agent.brief import management_brief
+from project_risk_agent.models import ProjectSignal
+from project_risk_agent.providers import DeterministicProvider, ModelProvider
+from project_risk_agent.service import AnalysisResult, RiskAnalysisService
+
+
+class AnalyzeRequest(BaseModel):
+    signals: list[ProjectSignal]
+
+
+def _changes(result: AnalysisResult) -> list[dict[str, object]]:
+    return [asdict(change) | {"attention_direction": change.attention_direction} for change in result.changed_findings]
+
+
+def _trajectories(result: AnalysisResult) -> list[dict[str, object]]:
+    return [asdict(item) for item in result.trajectories]
+
+
+def _freshness(result: AnalysisResult) -> list[dict[str, object]]:
+    return [asdict(item) for item in result.freshness or []]
+
+
+def _decisions(result: AnalysisResult) -> list[dict[str, object]]:
+    return [asdict(item) for item in result.decision_requests or []]
+
+
+def _dependencies(result: AnalysisResult) -> list[dict[str, object]]:
+    return [asdict(item) for item in result.dependencies or []]
+
+
+def create_app(provider: ModelProvider | None = None):
+    try:
+        from fastapi import FastAPI
+        from fastapi.middleware.cors import CORSMiddleware
+    except ImportError as exc:  # pragma: no cover - exercised only without API extra
+        raise RuntimeError("Install the 'api' extra to run the HTTP API") from exc
+
+    app = FastAPI(title="Project Risk Agent", version="0.1.0")
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["http://127.0.0.1:8001", "http://localhost:8001"],
+        allow_methods=["GET", "POST"],
+        allow_headers=["Content-Type"],
+    )
+    service = RiskAnalysisService(provider or DeterministicProvider(RiskAnalyzer()))
+
+    @app.get("/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok"}
+
+    def response(result: AnalysisResult) -> dict[str, object]:
+        return {
+            "analyzed_at": result.analyzed_at,
+            "signals_analyzed": result.signals_analyzed,
+            "trend": result.trend,
+            "findings": result.management_attention,
+            "changed_findings": _changes(result),
+            "trajectories": _trajectories(result),
+            "freshness": _freshness(result),
+            "decision_requests": _decisions(result),
+            "dependencies": _dependencies(result),
+        }
+
+    @app.post("/analyze")
+    def analyze(request: AnalyzeRequest) -> dict[str, object]:
+        return response(service.analyze(request.signals))
+
+    @app.post("/brief")
+    def brief(request: AnalyzeRequest) -> dict[str, object]:
+        result = service.analyze(request.signals)
+        return response(result) | {
+            "markdown": management_brief(
+                result.management_attention, result.decision_requests, result.dependencies
+            )
+        }
+
+    return app
+
+
+app = create_app()

project_risk_agent/brief.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from project_risk_agent.decisions import DecisionRequest
+from project_risk_agent.dependencies import DependencyItem
+from project_risk_agent.models import Finding
+
+
+def management_brief(
+    findings: list[Finding],
+    decision_requests: list[DecisionRequest] | None = None,
+    dependencies: list[DependencyItem] | None = None,
+) -> str:
+    """Render findings as a concise, human-reviewable management brief."""
+    if not findings and not decision_requests and not dependencies:
+        return "No management-relevant findings detected."
+
+    lines = ["# Project Risk Brief", ""]
+    for index, finding in enumerate(findings, start=1):
+        lines.extend([
+            f"## {index}. {finding.title}",
+            f"**Type:** {finding.type.value}  **Category:** {finding.category.value}",
+            f"**Confidence:** {finding.confidence:.0%}",
+            "",
+            finding.description,
+            "",
+            "### Evidence",
+        ])
+        for evidence in finding.evidence:
+            lines.append(f"- `{evidence.signal_id}` — {evidence.excerpt}")
+        if finding.recommended_actions:
+            lines.extend(["", "### Suggested next actions"])
+            lines.extend(f"- {action}" for action in finding.recommended_actions)
+        if finding.decision_required:
+            lines.extend(["", "**Management decision required:** Yes"])
+        lines.append("")
+    if decision_requests:
+        lines.extend(["## Decision queue", ""])
+        for request in decision_requests:
+            details = [f"**Readiness:** {request.readiness.replace('_', ' ')}"]
+            if request.owner:
+                details.append(f"**Owner:** {request.owner}")
+            if request.deadline:
+                details.append(f"**Deadline:** {request.deadline}")
+            lines.extend([f"- `{request.signal_id}` — {request.description}", "  " + "  ".join(details)])
+        lines.append("")
+    if dependencies:
+        lines.extend(["## Dependency queue", ""])
+        for dependency in dependencies:
+            details = [f"**Status:** {dependency.status}"]
+            if dependency.owner:
+                details.append(f"**Owner:** {dependency.owner}")
+            if dependency.required_by:
+                details.append(f"**Required by:** {dependency.required_by}")
+            lines.extend([f"- `{dependency.finding_id}` — {dependency.title}", "  " + "  ".join(details)])
+        lines.append("")
+    return "\n".join(lines)

project_risk_agent/cli.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from project_risk_agent.analyzer import RiskAnalyzer
+from project_risk_agent.brief import management_brief
+from project_risk_agent.connectors.file import FileConnector
+from project_risk_agent.prioritizer import prioritize
+from project_risk_agent.providers import DeterministicProvider, openai_provider_from_environment
+from project_risk_agent.service import RiskAnalysisService
+from project_risk_agent.state import JsonProjectStateStore
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Analyze project information for management risks.")
+    parser.add_argument("path", type=Path, help="Text or JSON file containing project signals")
+    parser.add_argument("--brief", action="store_true", help="Print a concise management brief")
+    parser.add_argument("--all", action="store_true", help="Include all findings instead of prioritized findings")
+    parser.add_argument(
+        "--provider",
+        choices=("deterministic", "openai"),
+        default="deterministic",
+        help="Reasoning provider (default: deterministic)",
+    )
+    parser.add_argument(
+        "--model",
+        help="OpenAI model ID; required with --provider openai unless configured in the environment",
+    )
+    parser.add_argument(
+        "--state",
+        type=Path,
+        help="Persist project intelligence at this path and report changes from the prior run",
+    )
+    args = parser.parse_args()
+
+    signals = FileConnector().load(args.path)
+    provider = (
+        openai_provider_from_environment(args.model)
+        if args.provider == "openai"
+        else DeterministicProvider(RiskAnalyzer())
+    )
+    service = RiskAnalysisService(provider)
+    result = service.analyze_with_state(signals, JsonProjectStateStore(args.state)) if args.state else service.analyze(signals)
+    findings = result.findings if args.all else prioritize(result.findings)
+
+    if args.brief:
+        print(management_brief(findings, result.decision_requests, result.dependencies))
+        print(f"\nTrajectory: {result.trend}")
+        for trajectory in result.trajectories:
+            print(f"- {trajectory.finding_id}: {trajectory.state} ({trajectory.freshness})")
+        if result.changed_findings:
+            print("\nChanged findings:")
+            for change in result.changed_findings:
+                fields = ", ".join(change.changed_fields)
+                print(f"- {change.finding_id}: {change.attention_direction} ({fields})")
+        return
+
+    payload = {
+        "analyzed_at": result.analyzed_at,
+        "signals_analyzed": result.signals_analyzed,
+        "trend": result.trend,
+        "findings": [finding.model_dump(mode="json") for finding in findings],
+        "trajectories": [
+            {
+                "finding_id": item.finding_id,
+                "state": item.state,
+                "attention_direction": item.attention_direction,
+                "freshness": item.freshness,
+            }
+            for item in result.trajectories
+        ],
+        "freshness": [
+            {
+                "finding_id": item.finding_id,
+                "age_days": item.age_days,
+                "status": item.status,
+            }
+            for item in result.freshness or []
+        ],
+        "decision_requests": [
+            {
+                "signal_id": item.signal_id,
+                "description": item.description,
+                "owner": item.owner,
+                "deadline": item.deadline,
+                "readiness": item.readiness,
+            }
+            for item in result.decision_requests or []
+        ],
+        "dependencies": [
+            {
+                "finding_id": item.finding_id,
+                "title": item.title,
+                "status": item.status,
+                "evidence_signal_ids": item.evidence_signal_ids,
+                "owner": item.owner,
+                "required_by": item.required_by,
+            }
+            for item in result.dependencies or []
+        ],
+        "changed_findings": [
+            {
+                "finding_id": change.finding_id,
+                "changed_fields": change.changed_fields,
+                "previous_attention": change.previous_attention,
+                "current_attention": change.current_attention,
+                "attention_direction": change.attention_direction,
+            }
+            for change in result.changed_findings
+        ],
+    }
+    print(json.dumps(payload, indent=2, default=str))
+
+
+if __name__ == "__main__":
+    main()

project_risk_agent/connectors/__init__.py

@@ -0,0 +1,8 @@
+"""Project data connectors."""
+
+from project_risk_agent.connectors.base import ProjectConnector
+from project_risk_agent.connectors.file import FileConnector
+from project_risk_agent.connectors.jira import JiraConnector
+from project_risk_agent.connectors.slack import SlackConnector
+
+__all__ = ["FileConnector", "JiraConnector", "ProjectConnector", "SlackConnector"]

project_risk_agent/connectors/base.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from project_risk_agent.models import ProjectSignal
+
+
+class ProjectConnector(ABC):
+    """Interface implemented by every external project-data connector."""
+
+    name: str
+
+    @abstractmethod
+    def authenticate(self) -> None:
+        """Validate or establish authentication for the connector."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_projects(self) -> list[dict[str, Any]]:
+        """Return projects available to the authenticated user."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_signals(self, project_id: str) -> list[ProjectSignal]:
+        """Return normalized signals for a project."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def normalize(self, source_data: Any) -> ProjectSignal:
+        """Convert source-specific data into the common signal model."""
+        raise NotImplementedError

project_risk_agent/connectors/file.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from project_risk_agent.connectors.base import ProjectConnector
+from project_risk_agent.models import ProjectSignal
+
+
+class FileConnector(ProjectConnector):
+    """Ingest local text or JSON files for development and evaluation."""
+
+    name = "file"
+
+    def authenticate(self) -> None:
+        return None
+
+    def get_projects(self) -> list[dict[str, Any]]:
+        return [{"id": "local", "name": "Local project"}]
+
+    def get_signals(self, project_id: str) -> list[ProjectSignal]:
+        return []
+
+    def normalize(self, source_data: Any) -> ProjectSignal:
+        if isinstance(source_data, str):
+            content = source_data
+            metadata: dict[str, object] = {}
+        else:
+            content = str(source_data.get("content", ""))
+            metadata = dict(source_data.get("metadata", {}))
+
+        return ProjectSignal(
+            id=f"file-{abs(hash(content))}",
+            source="file",
+            source_type="document",
+            timestamp=datetime.now(UTC),
+            project_id=metadata.pop("project_id", None),
+            author=metadata.pop("author", None),
+            content=content,
+            metadata=metadata,
+            provenance={"connector": self.name},
+        )
+
+    def load(self, path: str | Path) -> list[ProjectSignal]:
+        file_path = Path(path)
+        if file_path.suffix.lower() == ".json":
+            data = json.loads(file_path.read_text(encoding="utf-8"))
+            items = data if isinstance(data, list) else [data]
+        else:
+            items = [file_path.read_text(encoding="utf-8")]
+        return [self.normalize(item) for item in items]