flowsense-engine 0.2.1__tar.gz → 0.3.0__tar.gz

{flowsense_engine-0.2.1 → flowsense_engine-0.3.0}/CHANGELOG.md

@@ -3,6 +3,38 @@
 All notable changes to FlowSense are documented in this file. The project uses
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.3.0] - 2026-09-20
+
+### Added
+
+- Added `AnalyzeDAG` as the shared application use-case boundary for CLI, MCP,
+  and library integrations.
+- Added the `DAGAnalysisEngine` extension port and injectable default analysis
+  engine.
+- Added versioned golden regression coverage for the complete analysis output.
+- Added deterministic performance benchmarks with machine-readable results and
+  a manually triggered GitHub Actions workflow.
+- Added an Airflow 2 and Airflow 3 REST contract test matrix covering
+  authentication, routing, validation, mapping, and end-to-end analysis.
+
+### Changed
+
+- Separated environment loading and Airflow client construction through explicit
+  `AirflowConfig` and infrastructure factories.
+- Made the `TaskRun` domain entity immutable and framework-independent while
+  keeping Pydantic at external DTO and output-contract boundaries.
+- Added automated enforcement preventing the domain layer from importing
+  Pydantic.
+- Added architecture dependency guardrails and documented supported extension
+  points and compatibility boundaries.
+
+### Fixed
+
+- Rejected non-finite and negative analysis inputs at the domain boundary.
+- Made root-cause selection deterministic when candidates have equal scores.
+
 ## [0.2.1] - 2026-09-10
 
 ### Changed

flowsense_engine-0.3.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include CHANGELOG.md
+recursive-include docs *.md

{flowsense_engine-0.2.1/src/flowsense_engine.egg-info → flowsense_engine-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowsense-engine
-Version: 0.2.1
+Version: 0.3.0
 Summary: Temporal drift and anomaly detection for Apache Airflow
 Author: Omer Cengiz
 License-Expression: Apache-2.0
@@ -37,8 +37,11 @@ Dynamic: license-file
 
 Temporal drift, anomaly detection, and dependency-aware propagation analysis for Apache Airflow.
 
-Current package release: `0.2.1`. See [CHANGELOG.md](CHANGELOG.md) for release
-notes and [docs/releasing.md](docs/releasing.md) for the release checklist.
+Current package release: `0.3.0`. See [CHANGELOG.md](CHANGELOG.md) for release
+notes, [docs/architecture.md](docs/architecture.md) for the system architecture,
+[docs/benchmarks.md](docs/benchmarks.md) for performance measurement, and
+[docs/migrating-to-0.3.md](docs/migrating-to-0.3.md) for migration guidance.
+Maintainers can use [docs/releasing.md](docs/releasing.md) as the release checklist.
 
 FlowSense analyzes historical DAG executions to identify abnormal task behavior and trace how anomalies propagate through downstream dependencies.
 
@@ -189,6 +192,10 @@ Stable REST API deployments. Airflow 3.x uses the `v2` API and typically uses
 token authentication. Authentication still depends on the API auth backend
 configured in the Airflow deployment.
 
+CI verifies both integrations through versioned Airflow 2 and Airflow 3 REST
+contract fixtures. These boundary tests cover authentication, endpoint routing,
+response validation, domain mapping, and the complete analysis use case.
+
 Transient transport failures and HTTP `429`, `502`, `503`, and `504` responses
 are retried with exponential backoff. `Retry-After` is honored when Airflow
 provides it. Connect/read timeouts, retry count, and base backoff can be tuned
@@ -276,13 +283,12 @@ FlowSense can also be used as a Python library through its supported top-level
 API:
 
 ```python
-from flowsense import AirflowClient, analyze_dag
+from flowsense import AnalysisRequest, AnalyzeDAG
+from flowsense.infrastructure.airflow import create_airflow_data_source
 
-with AirflowClient() as source:
-    analysis = analyze_dag(
-        dag_id="flowsense_demo",
-        source=source,
-    )
+analysis = AnalyzeDAG(create_airflow_data_source).execute(
+    AnalysisRequest(dag_id="flowsense_demo")
+)
 
 print(analysis.overall_severity)
 print(analysis.primary_origin)

{flowsense_engine-0.2.1 → flowsense_engine-0.3.0}/README.md

@@ -2,8 +2,11 @@
 
 Temporal drift, anomaly detection, and dependency-aware propagation analysis for Apache Airflow.
 
-Current package release: `0.2.1`. See [CHANGELOG.md](CHANGELOG.md) for release
-notes and [docs/releasing.md](docs/releasing.md) for the release checklist.
+Current package release: `0.3.0`. See [CHANGELOG.md](CHANGELOG.md) for release
+notes, [docs/architecture.md](docs/architecture.md) for the system architecture,
+[docs/benchmarks.md](docs/benchmarks.md) for performance measurement, and
+[docs/migrating-to-0.3.md](docs/migrating-to-0.3.md) for migration guidance.
+Maintainers can use [docs/releasing.md](docs/releasing.md) as the release checklist.
 
 FlowSense analyzes historical DAG executions to identify abnormal task behavior and trace how anomalies propagate through downstream dependencies.
 
@@ -154,6 +157,10 @@ Stable REST API deployments. Airflow 3.x uses the `v2` API and typically uses
 token authentication. Authentication still depends on the API auth backend
 configured in the Airflow deployment.
 
+CI verifies both integrations through versioned Airflow 2 and Airflow 3 REST
+contract fixtures. These boundary tests cover authentication, endpoint routing,
+response validation, domain mapping, and the complete analysis use case.
+
 Transient transport failures and HTTP `429`, `502`, `503`, and `504` responses
 are retried with exponential backoff. `Retry-After` is honored when Airflow
 provides it. Connect/read timeouts, retry count, and base backoff can be tuned
@@ -241,13 +248,12 @@ FlowSense can also be used as a Python library through its supported top-level
 API:
 
 ```python
-from flowsense import AirflowClient, analyze_dag
+from flowsense import AnalysisRequest, AnalyzeDAG
+from flowsense.infrastructure.airflow import create_airflow_data_source
 
-with AirflowClient() as source:
-    analysis = analyze_dag(
-        dag_id="flowsense_demo",
-        source=source,
-    )
+analysis = AnalyzeDAG(create_airflow_data_source).execute(
+    AnalysisRequest(dag_id="flowsense_demo")
+)
 
 print(analysis.overall_severity)
 print(analysis.primary_origin)

flowsense_engine-0.3.0/docs/architecture.md

@@ -0,0 +1,122 @@
+# FlowSense Architecture
+
+FlowSense uses an inward-facing layered architecture. Delivery mechanisms and
+external systems depend on application contracts; the analysis domain does not
+depend on Airflow, CLI, MCP, or environment configuration.
+
+## Dependency direction
+
+```text
+CLI / MCP
+    |
+    v
+Application use cases -----> Domain models and policies
+    |                              ^
+    v                              |
+Application ports <----- Infrastructure adapters
+                              |
+                              v
+                         Apache Airflow
+```
+
+Dependencies must point toward the application and domain layers. The
+composition roots in the CLI and MCP adapters are responsible for selecting
+concrete infrastructure implementations.
+
+## Layers
+
+### Domain
+
+`flowsense.domain` contains the analysis vocabulary: task runs, policies,
+severity and impact classifications, results, and expected domain failures.
+It must not import application, infrastructure, CLI, MCP, or compatibility
+modules. Domain entities and results use standard-library dataclasses; they do
+not depend on validation or transport frameworks.
+
+`flowsense.engine` currently contains pure analysis services such as drift,
+trend, handoff, propagation, and root-cause calculations. These services may
+depend on the domain but not on delivery or infrastructure code.
+
+### Application
+
+`flowsense.application` coordinates use cases without knowing how Airflow data
+is retrieved or how results are displayed.
+
+`AnalysisRequest` is the validated input contract. `AnalyzeDAG.execute()` is the
+primary use-case boundary. `DAGDataSource` and `DAGDataSourceFactory` are ports
+implemented by infrastructure adapters. The existing functional
+`analyze_dag(dag_id, source, policy)` API remains available for callers that
+already own a data source.
+
+`DAGAnalysisEngine` is the coarse-grained algorithm extension port. The default
+implementation owns the complete statistical workflow after data collection.
+Alternative engines can be injected into `AnalyzeDAG` without changing CLI,
+MCP, data-source, or output-contract code. Individual detector interfaces are
+intentionally avoided until independent detector replacement is required.
+
+### Infrastructure
+
+`flowsense.infrastructure.airflow` implements Airflow HTTP access. Pydantic DTOs
+validate external API payloads and mappers translate them into domain objects.
+Pydantic is intentionally restricted to infrastructure DTOs and application
+output contracts, where runtime boundary validation and JSON Schema generation
+are required.
+
+`AirflowClient` receives an explicit `AirflowConfig` and never reads environment
+variables. `load_airflow_config()` and `create_airflow_data_source()` belong to
+the infrastructure composition boundary.
+
+### Delivery adapters
+
+`flowsense.cli` and `flowsense.mcp` translate user input into an
+`AnalysisRequest`, invoke `AnalyzeDAG`, and translate the result into their own
+output mechanism. Business analysis and data-collection orchestration must not
+be duplicated in these adapters.
+
+## Main analysis flow
+
+```text
+Input options
+    -> AnalysisRequest
+    -> AnalyzeDAG
+    -> DAGDataSourceFactory
+    -> DAGDataSource
+    -> task and handoff histories
+    -> drift / change-point / trend analysis
+    -> impact and propagation analysis
+    -> primary root-cause selection
+    -> DAGAnalysis
+    -> versioned AnalysisDocument
+```
+
+## Extension points
+
+- Add another data source by implementing `DAGDataSource` and providing a
+  `DAGDataSourceFactory`.
+- Replace the complete analysis workflow by implementing `DAGAnalysisEngine`
+  and injecting it into `AnalyzeDAG`.
+- Add a delivery mechanism by creating an adapter that builds an
+  `AnalysisRequest` and invokes `AnalyzeDAG`.
+- Extend output consumers through `AnalysisDocument`; incompatible contract
+  changes require a schema-version change.
+- Keep external payload models inside their infrastructure adapter and map them
+  into domain models before analysis.
+
+## Compatibility policy
+
+The following pre-layered import paths remain temporarily available:
+
+- `flowsense.models` -> `flowsense.domain`
+- `flowsense.collector` -> `flowsense.infrastructure.airflow`
+- `flowsense.config` -> `flowsense.infrastructure.airflow`
+- `flowsense.engine.analyzer` -> `flowsense.AnalyzeDAG`
+
+They emit `DeprecationWarning` and must not be used by new internal code. They
+will be removed only in an explicitly announced breaking release.
+
+## Automated guardrails
+
+`tests/test_architecture.py` parses internal imports and fails when a layer
+introduces a forbidden outward dependency. The compatibility analyzer is the
+only documented exception. New exceptions require an architectural decision and
+must not be added merely to make the test pass.

flowsense_engine-0.3.0/docs/benchmarks.md

@@ -0,0 +1,37 @@
+# Performance benchmarks
+
+FlowSense includes a deterministic synthetic benchmark for measuring the
+default analysis engine independently from Airflow and network latency.
+
+The benchmark creates an ordered chain DAG, generates repeatable task timings,
+injects anomalies into the latest run, and reports:
+
+- analysis execution time;
+- total time including versioned output serialization;
+- peak Python memory observed through `tracemalloc`;
+- scenario dimensions and analyzed task count.
+
+Run the default scenario:
+
+```bash
+uv run python -m benchmarks.benchmark_analysis
+```
+
+Run a larger scenario and save machine-readable results:
+
+```bash
+uv run python -m benchmarks.benchmark_analysis \
+  --tasks 500 \
+  --runs 100 \
+  --iterations 5 \
+  --output benchmark-results.json
+```
+
+The GitHub `Analysis benchmark` workflow provides the same parameters and
+uploads the JSON result as a workflow artifact.
+
+Benchmark results are observational and do not use hard pass/fail time limits.
+Shared CI runners have variable performance, so fixed thresholds would create
+flaky checks. Compare runs produced with the same scenario, Python version, and
+similar hardware. Introduce performance gates only after a stable baseline has
+been collected on controlled runners.

flowsense_engine-0.3.0/docs/migrating-to-0.3.md

@@ -0,0 +1,66 @@
+# Migrating to FlowSense 0.3
+
+FlowSense 0.3 strengthens the library architecture without changing the
+versioned analysis output contract. The schema remains at version `1.1`, so
+existing CLI JSON and MCP consumers do not need a response migration.
+
+## Supported imports
+
+Library integrations should import public contracts directly from `flowsense`:
+
+```python
+from flowsense import AnalysisRequest, AnalyzeDAG, TaskRun
+```
+
+The following compatibility namespaces still work in 0.3 but emit
+`DeprecationWarning` and are planned for removal in a future breaking release:
+
+| Deprecated import | Replacement |
+| --- | --- |
+| `flowsense.models` | `flowsense.domain` or public names from `flowsense` |
+| `flowsense.collector` | `flowsense.infrastructure.airflow` |
+| `flowsense.config` | `flowsense.infrastructure.airflow` |
+| `flowsense.engine.analyzer` | `flowsense.AnalyzeDAG` |
+
+Applications should migrate these imports now; no compatibility namespace is
+used by FlowSense internals.
+
+## Analysis entry point
+
+Use `AnalyzeDAG` when FlowSense owns data-source creation:
+
+```python
+from flowsense import AnalysisRequest, AnalyzeDAG
+from flowsense.infrastructure.airflow import create_airflow_data_source
+
+analysis = AnalyzeDAG(create_airflow_data_source).execute(
+    AnalysisRequest(dag_id="example_dag")
+)
+```
+
+Existing integrations that already own a `DAGDataSource` can continue using
+the public `analyze_dag` function. Custom analysis implementations can implement
+`DAGAnalysisEngine` and inject that engine into `AnalyzeDAG`.
+
+## Airflow configuration
+
+`AirflowClient` now receives an explicit immutable `AirflowConfig`. Environment
+access belongs to `load_airflow_config()` or `create_airflow_data_source()`:
+
+```python
+from flowsense.infrastructure.airflow import AirflowClient, load_airflow_config
+
+client = AirflowClient(load_airflow_config())
+```
+
+CLI and MCP users can keep using the existing `AIRFLOW_*` environment variables.
+For Airflow 2 use `AIRFLOW_API_VERSION=v1` with the authentication mode provided
+by the deployment, commonly `basic`. Airflow 3 normally uses
+`AIRFLOW_API_VERSION=v2` and `token` authentication.
+
+## Domain model behavior
+
+`TaskRun` is now an immutable standard-library dataclass. Code that mutated a
+task run after construction must instead create a new value, for example with
+`dataclasses.replace`. Invalid negative or non-finite durations are rejected at
+construction time.

{flowsense_engine-0.2.1 → flowsense_engine-0.3.0}/docs/releasing.md

@@ -33,11 +33,15 @@ After the release pull request is merged into `master` and CI passes:
 ```bash
 git switch master
 git pull --ff-only origin master
-git tag -a v0.2.1 -m "FlowSense 0.2.1"
-git push origin v0.2.1
+git tag -a v0.3.0 -m "FlowSense 0.3.0"
+git push origin v0.3.0
 ```
 
 Create and publish the corresponding GitHub Release after pushing the tag. The
 release workflow builds that exact tag and publishes it through the protected
 `pypi` environment. Package publication should run only after the built artifacts
 have been verified.
+
+Use `FlowSense 0.3.0` as the release title, select `Latest`, and do not mark a
+stable release as a pre-release. Copy the `0.3.0` section from `CHANGELOG.md` into
+the release notes.

{flowsense_engine-0.2.1 → flowsense_engine-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flowsense-engine"
-version = "0.2.1"
+version = "0.3.0"
 description = "Temporal drift and anomaly detection for Apache Airflow"
 readme = "README.md"
 license = "Apache-2.0"
@@ -68,12 +68,13 @@ where = ["src"]
 flowsense = ["py.typed"]
 
 [tool.pyright]
-include = ["src"]
+include = ["src", "benchmarks"]
 typeCheckingMode = "standard"
 pythonVersion = "3.12"
 
 [tool.pytest.ini_options]
-pythonpath = ["src"]
+pythonpath = ["src", "."]
 markers = [
+    "airflow_contract: Airflow REST API boundary contract tests",
     "integration: tests that require a running Airflow instance",
 ]

{flowsense_engine-0.2.1 → flowsense_engine-0.3.0}/src/flowsense/__init__.py

@@ -1,8 +1,12 @@
 from flowsense.application import (
     ANALYSIS_SCHEMA_VERSION,
+    DEFAULT_DAG_ANALYSIS_ENGINE,
     AnalysisDocument,
     AnalysisRequest,
+    AnalyzeDAG,
+    DAGAnalysisEngine,
     DAGDataSource,
+    DefaultDAGAnalysisEngine,
     analysis_json_schema,
     analyze_dag,
     build_analysis_document,
@@ -21,6 +25,7 @@ from flowsense.domain import (
     FlowSenseError,
     ImpactClassification,
     InsufficientHistoryError,
+    InvalidObservationError,
     InvalidTaskTimingError,
     MappedTaskAggregation,
     PropagationResult,
@@ -42,6 +47,7 @@ from flowsense.version import __version__
 __all__ = [
     "ANALYSIS_SCHEMA_VERSION",
     "DEFAULT_ANALYSIS_POLICY",
+    "DEFAULT_DAG_ANALYSIS_ENGINE",
     "AirflowApiError",
     "AirflowClient",
     "AirflowDagRunNotFoundError",
@@ -50,16 +56,20 @@ __all__ = [
     "AnalysisDocument",
     "AnalysisPolicy",
     "AnalysisRequest",
+    "AnalyzeDAG",
     "ChangeDirection",
     "ChangePointResult",
     "ConfigurationError",
     "DAGAnalysis",
+    "DAGAnalysisEngine",
     "DAGAnalysisSummary",
     "DAGDataSource",
+    "DefaultDAGAnalysisEngine",
     "DriftResult",
     "FlowSenseError",
     "ImpactClassification",
     "InsufficientHistoryError",
+    "InvalidObservationError",
     "InvalidTaskTimingError",
     "MappedTaskAggregation",
     "PropagationResult",

{flowsense_engine-0.2.1 → flowsense_engine-0.3.0}/src/flowsense/application/__init__.py

@@ -1,18 +1,28 @@
+from flowsense.application.analysis_engine import (
+    DEFAULT_DAG_ANALYSIS_ENGINE,
+    DefaultDAGAnalysisEngine,
+)
 from flowsense.application.analyzer import analyze_dag
 from flowsense.application.output import ANALYSIS_SCHEMA_VERSION, AnalysisDocument
-from flowsense.application.ports import DAGDataSource
+from flowsense.application.ports import DAGAnalysisEngine, DAGDataSource
 from flowsense.application.request import AnalysisRequest
 from flowsense.application.serialization import (
     analysis_json_schema,
     build_analysis_document,
     serialize_analysis,
 )
+from flowsense.application.use_cases import AnalyzeDAG, DAGDataSourceFactory
 
 __all__ = [
     "ANALYSIS_SCHEMA_VERSION",
+    "DEFAULT_DAG_ANALYSIS_ENGINE",
     "AnalysisDocument",
     "AnalysisRequest",
+    "AnalyzeDAG",
+    "DAGAnalysisEngine",
     "DAGDataSource",
+    "DAGDataSourceFactory",
+    "DefaultDAGAnalysisEngine",
     "analysis_json_schema",
     "analyze_dag",
     "build_analysis_document",

flowsense_engine-0.3.0/src/flowsense/application/analysis_engine.py

@@ -0,0 +1,71 @@
+from flowsense.application.pipeline import (
+    analyze_handoff_histories,
+    analyze_task_histories,
+    classify_task_impacts,
+    determine_overall_severity,
+)
+from flowsense.domain import AnalysisPolicy, DAGAnalysis, TaskRun
+from flowsense.engine.history import build_duration_history
+from flowsense.engine.propagation import analyze_propagation
+from flowsense.engine.root_cause import select_primary_origin
+
+
+class DefaultDAGAnalysisEngine:
+    """Default stateless implementation of the DAG analysis domain workflow."""
+
+    def analyze(
+        self,
+        dag_id: str,
+        task_runs: list[TaskRun],
+        dependencies: dict[str, list[str]],
+        policy: AnalysisPolicy,
+    ) -> DAGAnalysis:
+        duration_history = build_duration_history(
+            task_runs,
+            aggregation=policy.mapped_task_aggregation,
+        )
+
+        task_analysis = analyze_task_histories(duration_history, policy)
+        handoff_analysis = analyze_handoff_histories(task_runs, dependencies, policy)
+        task_impacts = classify_task_impacts(
+            task_analysis.drift_results,
+            handoff_analysis.drift_results,
+        )
+        propagation_results = analyze_propagation(
+            drift_results=task_analysis.drift_results,
+            dependencies=dependencies,
+        )
+        primary_origin = select_primary_origin(
+            drift_results=task_analysis.drift_results,
+            task_impacts=task_impacts,
+            dependencies=dependencies,
+            propagation_results=propagation_results,
+        )
+
+        return DAGAnalysis(
+            dag_id=dag_id,
+            runs_analyzed=len({run.dag_run_id for run in task_runs}),
+            current_dag_run_id=(task_runs[-1].dag_run_id if task_runs else None),
+            overall_severity=determine_overall_severity(
+                task_analysis.drift_results,
+                handoff_analysis.drift_results,
+            ),
+            primary_origin=primary_origin,
+            drift_results=task_analysis.drift_results,
+            handoff_drift_results=handoff_analysis.drift_results,
+            task_impacts=task_impacts,
+            propagation_results=propagation_results,
+            dependencies=dependencies,
+            diagnostics=[
+                *task_analysis.diagnostics,
+                *handoff_analysis.diagnostics,
+            ],
+            policy=policy,
+            change_point_results=task_analysis.change_point_results,
+            handoff_change_point_results=handoff_analysis.change_point_results,
+            trend_results=task_analysis.trend_results,
+            handoff_trend_results=handoff_analysis.trend_results,
+        )
+
+
+DEFAULT_DAG_ANALYSIS_ENGINE = DefaultDAGAnalysisEngine()

flowsense_engine-0.3.0/src/flowsense/application/analyzer.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from flowsense.application.analysis_engine import DEFAULT_DAG_ANALYSIS_ENGINE
+from flowsense.application.ports import DAGAnalysisEngine, DAGDataSource
+from flowsense.domain import DEFAULT_ANALYSIS_POLICY, AnalysisPolicy, DAGAnalysis
+
+
+def analyze_dag(
+    dag_id: str,
+    source: DAGDataSource,
+    policy: AnalysisPolicy = DEFAULT_ANALYSIS_POLICY,
+    analysis_engine: DAGAnalysisEngine = DEFAULT_DAG_ANALYSIS_ENGINE,
+) -> DAGAnalysis:
+    task_runs = source.collect_task_runs(dag_id)
+    dependencies = source.get_dag_dependencies(dag_id)
+    return analysis_engine.analyze(
+        dag_id=dag_id,
+        task_runs=task_runs,
+        dependencies=dependencies,
+        policy=policy,
+    )

flowsense_engine-0.3.0/src/flowsense/application/ports.py

@@ -0,0 +1,23 @@
+from typing import Protocol
+
+from flowsense.domain import AnalysisPolicy, DAGAnalysis, TaskRun
+
+
+class DAGDataSource(Protocol):
+    def collect_task_runs(self, dag_id: str) -> list[TaskRun]:
+        """Return task runs ordered from oldest DAG run to newest."""
+        ...
+
+    def get_dag_dependencies(self, dag_id: str) -> dict[str, list[str]]: ...
+
+
+class DAGAnalysisEngine(Protocol):
+    """Analyze already collected domain data without performing I/O."""
+
+    def analyze(
+        self,
+        dag_id: str,
+        task_runs: list[TaskRun],
+        dependencies: dict[str, list[str]],
+        policy: AnalysisPolicy,
+    ) -> DAGAnalysis: ...

flowsense_engine-0.3.0/src/flowsense/application/use_cases.py

@@ -0,0 +1,36 @@
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+
+from flowsense.application.analysis_engine import DEFAULT_DAG_ANALYSIS_ENGINE
+from flowsense.application.ports import DAGAnalysisEngine, DAGDataSource
+from flowsense.application.request import AnalysisRequest
+from flowsense.domain import DAGAnalysis
+
+DAGDataSourceFactory = Callable[
+    [AnalysisRequest],
+    AbstractContextManager[DAGDataSource],
+]
+
+
+class AnalyzeDAG:
+    """Application use case coordinating data collection and DAG analysis."""
+
+    def __init__(
+        self,
+        source_factory: DAGDataSourceFactory,
+        analysis_engine: DAGAnalysisEngine = DEFAULT_DAG_ANALYSIS_ENGINE,
+    ) -> None:
+        self._source_factory = source_factory
+        self._analysis_engine = analysis_engine
+
+    def execute(self, request: AnalysisRequest) -> DAGAnalysis:
+        with self._source_factory(request) as source:
+            task_runs = source.collect_task_runs(request.dag_id)
+            dependencies = source.get_dag_dependencies(request.dag_id)
+
+            return self._analysis_engine.analyze(
+                dag_id=request.dag_id,
+                task_runs=task_runs,
+                dependencies=dependencies,
+                policy=request.policy,
+            )