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

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

@@ -5,6 +5,33 @@ All notable changes to FlowSense are documented in this file. The project uses
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-20
+
+### Added
+
+- Added paginated Airflow 2 and 3 DAG discovery with optional paused-DAG
+  inclusion.
+- Added an immutable multi-DAG analysis result and bounded, opt-in concurrency
+  through `FlowSenseClient.analyze_many()`.
+- Added a versioned, typed batch output document with serialization and JSON
+  Schema helpers.
+- Added the `FlowSenseClient` facade for concise embedded Python usage and an
+  explicit Airflow data-source factory for application-owned configuration.
+- Added pluggable Airflow authentication providers for Basic Auth, login-token
+  exchange, static or rotating bearer tokens, and deployment-specific headers.
+- Added a bounded Prometheus metrics exporter and the optional
+  `flowsense serve-metrics` command for continuous DAG analysis.
+- Added a provisioned Grafana dashboard and local Docker Compose example for
+  inspecting analysis health, coverage, severity, task drift, and handoffs.
+- Added Prometheus alert rules, Alertmanager configuration, synthetic rule
+  tests, and CI validation for FlowSense analysis failures and anomalies.
+
+### Changed
+
+- Kept observability integrations as optional delivery adapters so the core
+  analysis package remains independent from Prometheus, Grafana, and hosted
+  service infrastructure.
+
 ## [0.3.0] - 2026-09-20
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowsense-engine
-Version: 0.3.0
+Version: 0.4.0
 Summary: Temporal drift and anomaly detection for Apache Airflow
 Author: Omer Cengiz
 License-Expression: Apache-2.0
@@ -37,7 +37,7 @@ Dynamic: license-file
 
 Temporal drift, anomaly detection, and dependency-aware propagation analysis for Apache Airflow.
 
-Current package release: `0.3.0`. See [CHANGELOG.md](CHANGELOG.md) for release
+Current package release: `0.4.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.
@@ -180,6 +180,7 @@ AIRFLOW_USERNAME=your_username
 AIRFLOW_PASSWORD=your_password
 AIRFLOW_API_VERSION=v2
 AIRFLOW_AUTH_MODE=token
+# AIRFLOW_BEARER_TOKEN=your_static_token
 AIRFLOW_CONNECT_TIMEOUT=10
 AIRFLOW_READ_TIMEOUT=10
 AIRFLOW_MAX_RETRIES=2
@@ -192,6 +193,12 @@ 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.
 
+Static bearer tokens can use `AIRFLOW_AUTH_MODE=bearer` with
+`AIRFLOW_BEARER_TOKEN`; username and password are not required in that mode.
+Library integrations may inject a custom `AirflowAuthProvider` for rotating
+tokens, identity-aware proxies, or deployment-specific headers. See
+[docs/authentication.md](docs/authentication.md) for the complete contract.
+
 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.
@@ -279,21 +286,41 @@ tooling, or client code generation.
 
 ## Library API
 
-FlowSense can also be used as a Python library through its supported top-level
-API:
+`FlowSenseClient` is the recommended in-process Python API. The environment
+configured Airflow factory keeps the basic setup concise:
 
 ```python
-from flowsense import AnalysisRequest, AnalyzeDAG
+from flowsense import FlowSenseClient
 from flowsense.infrastructure.airflow import create_airflow_data_source
 
-analysis = AnalyzeDAG(create_airflow_data_source).execute(
-    AnalysisRequest(dag_id="flowsense_demo")
-)
+client = FlowSenseClient(create_airflow_data_source)
+analysis = client.analyze("flowsense_demo")
 
 print(analysis.overall_severity)
 print(analysis.primary_origin)
 ```
 
+Applications that own configuration can combine `AirflowConfig` with
+`create_airflow_data_source_factory`. Typed integrations may continue to call
+`client.execute(AnalysisRequest(...))`. See the complete
+[Python API guide](docs/python-api.md).
+
+Multiple DAGs can be analyzed with bounded, opt-in concurrency. Expected
+FlowSense failures are isolated per DAG:
+
+```python
+result = client.analyze_many(
+    ["orders", "payments", "inventory"],
+    max_concurrency=3,
+)
+```
+
+`AirflowClient.list_dag_ids()` provides paginated DAG discovery and excludes
+paused DAGs by default.
+
+`serialize_batch_analysis(result)` converts the result into the stable batch
+output contract without exposing raw exception objects.
+
 Analysis behavior can be customized with an immutable policy:
 
 ```python
@@ -351,6 +378,23 @@ The server exposes the `analyze_airflow_dag` tool, which returns task drift,
 handoff drift, impact classification, propagation paths, and primary root-cause
 information for a DAG.
 
+## Prometheus
+
+Run continuous analysis and expose the latest DAG and bounded task-level metrics:
+
+```bash
+flowsense serve-metrics example_dag --host 0.0.0.0 --port 9108
+```
+
+See [docs/prometheus.md](docs/prometheus.md) for the metric contract,
+cardinality policy, and Prometheus scrape configuration.
+
+A provisioned Prometheus and Grafana development stack, including the
+`FlowSense Overview` dashboard, is documented in
+[docs/grafana.md](docs/grafana.md).
+Default operational alerts and Alertmanager routing are documented in
+[docs/alerting.md](docs/alerting.md).
+
 ## Development
 
 Run unit tests:

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

@@ -2,7 +2,7 @@
 
 Temporal drift, anomaly detection, and dependency-aware propagation analysis for Apache Airflow.
 
-Current package release: `0.3.0`. See [CHANGELOG.md](CHANGELOG.md) for release
+Current package release: `0.4.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.
@@ -145,6 +145,7 @@ AIRFLOW_USERNAME=your_username
 AIRFLOW_PASSWORD=your_password
 AIRFLOW_API_VERSION=v2
 AIRFLOW_AUTH_MODE=token
+# AIRFLOW_BEARER_TOKEN=your_static_token
 AIRFLOW_CONNECT_TIMEOUT=10
 AIRFLOW_READ_TIMEOUT=10
 AIRFLOW_MAX_RETRIES=2
@@ -157,6 +158,12 @@ 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.
 
+Static bearer tokens can use `AIRFLOW_AUTH_MODE=bearer` with
+`AIRFLOW_BEARER_TOKEN`; username and password are not required in that mode.
+Library integrations may inject a custom `AirflowAuthProvider` for rotating
+tokens, identity-aware proxies, or deployment-specific headers. See
+[docs/authentication.md](docs/authentication.md) for the complete contract.
+
 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.
@@ -244,21 +251,41 @@ tooling, or client code generation.
 
 ## Library API
 
-FlowSense can also be used as a Python library through its supported top-level
-API:
+`FlowSenseClient` is the recommended in-process Python API. The environment
+configured Airflow factory keeps the basic setup concise:
 
 ```python
-from flowsense import AnalysisRequest, AnalyzeDAG
+from flowsense import FlowSenseClient
 from flowsense.infrastructure.airflow import create_airflow_data_source
 
-analysis = AnalyzeDAG(create_airflow_data_source).execute(
-    AnalysisRequest(dag_id="flowsense_demo")
-)
+client = FlowSenseClient(create_airflow_data_source)
+analysis = client.analyze("flowsense_demo")
 
 print(analysis.overall_severity)
 print(analysis.primary_origin)
 ```
 
+Applications that own configuration can combine `AirflowConfig` with
+`create_airflow_data_source_factory`. Typed integrations may continue to call
+`client.execute(AnalysisRequest(...))`. See the complete
+[Python API guide](docs/python-api.md).
+
+Multiple DAGs can be analyzed with bounded, opt-in concurrency. Expected
+FlowSense failures are isolated per DAG:
+
+```python
+result = client.analyze_many(
+    ["orders", "payments", "inventory"],
+    max_concurrency=3,
+)
+```
+
+`AirflowClient.list_dag_ids()` provides paginated DAG discovery and excludes
+paused DAGs by default.
+
+`serialize_batch_analysis(result)` converts the result into the stable batch
+output contract without exposing raw exception objects.
+
 Analysis behavior can be customized with an immutable policy:
 
 ```python
@@ -316,6 +343,23 @@ The server exposes the `analyze_airflow_dag` tool, which returns task drift,
 handoff drift, impact classification, propagation paths, and primary root-cause
 information for a DAG.
 
+## Prometheus
+
+Run continuous analysis and expose the latest DAG and bounded task-level metrics:
+
+```bash
+flowsense serve-metrics example_dag --host 0.0.0.0 --port 9108
+```
+
+See [docs/prometheus.md](docs/prometheus.md) for the metric contract,
+cardinality policy, and Prometheus scrape configuration.
+
+A provisioned Prometheus and Grafana development stack, including the
+`FlowSense Overview` dashboard, is documented in
+[docs/grafana.md](docs/grafana.md).
+Default operational alerts and Alertmanager routing are documented in
+[docs/alerting.md](docs/alerting.md).
+
 ## Development
 
 Run unit tests:

flowsense_engine-0.4.0/docs/alerting.md

@@ -0,0 +1,57 @@
+# Prometheus alerting
+
+The local observability stack loads a tested set of FlowSense alert rules and
+routes firing alerts to Alertmanager.
+
+## Included alerts
+
+| Alert | Default condition | Severity |
+| --- | --- | --- |
+| `FlowSenseExporterDown` | Metrics endpoint unavailable for 2 minutes | Critical |
+| `FlowSenseAnalysisFailed` | Latest analysis failed for 2 minutes | Warning |
+| `FlowSenseAnalysisStale` | No successful analysis for 10 minutes in total | Warning |
+| `FlowSenseCriticalDAG` | DAG severity remains critical for 2 minutes | Critical |
+| `FlowSenseCriticalTask` | Task severity remains critical for 2 minutes | Critical |
+| `FlowSenseTaskMetricsDropped` | Cardinality limit omits tasks for 5 minutes | Warning |
+| `FlowSenseAnalysisSlow` | Analysis remains above 30 seconds for 5 minutes | Warning |
+
+The stale rule expression becomes true after five minutes without a successful
+analysis and must remain true for another five minutes before firing. Adjust
+thresholds in `deploy/observability/alerts.yml` to match the configured analysis
+interval and operational expectations.
+
+## Validate rules
+
+Run syntax and unit checks with the Prometheus image pinned by the Compose file:
+
+```bash
+docker run --rm \
+  --entrypoint promtool \
+  -v "$PWD/deploy/observability:/workspace:ro" \
+  -w /workspace \
+  prom/prometheus:v3.14.0 \
+  check rules alerts.yml
+
+docker run --rm \
+  --entrypoint promtool \
+  -v "$PWD/deploy/observability:/workspace:ro" \
+  -w /workspace \
+  prom/prometheus:v3.14.0 \
+  test rules alerts.test.yml
+```
+
+## Configure notifications
+
+The committed Alertmanager configuration intentionally uses an empty local
+receiver. Firing alerts are visible in the Alertmanager UI and the Grafana
+dashboard, but no external notification is sent by default.
+
+For production, replace the receiver in
+`deploy/observability/alertmanager.yml` with the organization's managed email,
+Slack, PagerDuty, webhook, or other supported integration. Keep credentials out
+of Git and inject them through the deployment platform's secret management
+mechanism.
+
+Alertmanager is available locally at `http://localhost:9093`. Verify routing and
+notification delivery in a non-production environment before enabling it for
+operational incidents.

{flowsense_engine-0.3.0 → flowsense_engine-0.4.0}/docs/architecture.md

@@ -48,6 +48,17 @@ implemented by infrastructure adapters. The existing functional
 `analyze_dag(dag_id, source, policy)` API remains available for callers that
 already own a data source.
 
+`FlowSenseClient` is the supported convenience facade for embedded Python
+consumers. It translates the concise `analyze(...)` call into an
+`AnalysisRequest` and delegates to `AnalyzeDAG`; it contains no collection or
+analysis logic of its own. Its optional multi-DAG operation creates one
+use-case execution and context-managed data source per DAG, preserving the
+single-DAG application boundary.
+
+`BatchAnalysisDocument` is a separate versioned envelope around the existing
+single-DAG `AnalysisDocument`. Expected failures cross the output boundary as
+typed failure records rather than runtime exception objects.
+
 `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,
@@ -66,12 +77,17 @@ are required.
 variables. `load_airflow_config()` and `create_airflow_data_source()` belong to
 the infrastructure composition boundary.
 
+Authentication is supplied through `AirflowAuthProvider`. Built-in providers
+cover Basic Auth, Airflow login-token exchange, static bearer tokens, and custom
+headers without coupling request collection to a deployment's identity system.
+
 ### Delivery adapters
 
-`flowsense.cli` and `flowsense.mcp` translate user input into an
+`flowsense.cli`, `flowsense.mcp`, and `flowsense.observability` 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.
+output mechanism. Prometheus export implements the `AnalysisMetricsSink` port
+and keeps a bounded latest-value snapshot. Business analysis and data-collection
+orchestration must not be duplicated in these adapters.
 
 ## Main analysis flow
 

flowsense_engine-0.4.0/docs/authentication.md

@@ -0,0 +1,77 @@
+# Airflow authentication
+
+FlowSense keeps Airflow authentication behind the `AirflowAuthProvider` port.
+The collector does not need to know whether credentials come from Airflow,
+a reverse proxy, a secret manager, or an external identity system.
+
+## Built-in modes
+
+### Airflow login token
+
+This remains the default for Airflow 3 deployments that expose `/auth/token`:
+
+```env
+AIRFLOW_AUTH_MODE=token
+AIRFLOW_USERNAME=airflow
+AIRFLOW_PASSWORD=secret
+```
+
+FlowSense exchanges the credentials once and caches the returned bearer token
+for the lifetime of the client.
+
+### Basic authentication
+
+Common Airflow 2 Stable REST API deployments can use:
+
+```env
+AIRFLOW_API_VERSION=v1
+AIRFLOW_AUTH_MODE=basic
+AIRFLOW_USERNAME=airflow
+AIRFLOW_PASSWORD=secret
+```
+
+### Static bearer token
+
+For deployments that issue a token outside Airflow:
+
+```env
+AIRFLOW_AUTH_MODE=bearer
+AIRFLOW_BEARER_TOKEN=secret-token
+```
+
+Username and password are not required in bearer mode. Secrets are excluded
+from the `AirflowConfig` representation, but applications must still keep them
+out of logs, shell history, source control, and command-line arguments.
+
+## Custom provider
+
+Enterprise integrations can inject an `AirflowAuthProvider` directly. This is
+appropriate for rotating tokens, identity-aware proxies, workload identity, or
+deployment-specific headers:
+
+```python
+from flowsense.infrastructure.airflow import (
+    AirflowClient,
+    AirflowConfig,
+    HeaderAuthProvider,
+)
+
+provider = HeaderAuthProvider({"X-Forwarded-User": "flowsense"})
+client = AirflowClient(
+    AirflowConfig(base_url="https://airflow.example.com"),
+    auth_provider=provider,
+)
+```
+
+For rotating bearer credentials, pass a callable. It is evaluated for every
+Airflow request:
+
+```python
+from flowsense.infrastructure.airflow import BearerTokenAuthProvider
+
+provider = BearerTokenAuthProvider(load_current_token)
+```
+
+Custom providers should return only authentication material and leave request
+execution, retry, timeout, payload validation, and error translation to
+`AirflowClient`.

flowsense_engine-0.4.0/docs/grafana.md

@@ -0,0 +1,66 @@
+# Grafana dashboard
+
+FlowSense ships a provisioned local observability stack containing Prometheus
+and Grafana. Airflow credentials stay in the host process running FlowSense;
+the containers only scrape the exported metrics.
+
+## Start FlowSense metrics
+
+Configure the required `AIRFLOW_*` environment variables, then run:
+
+```bash
+flowsense serve-metrics example_dag another_dag \
+  --host 0.0.0.0 \
+  --port 9108 \
+  --interval-seconds 60
+```
+
+Binding to `0.0.0.0` makes the endpoint reachable from the local Prometheus
+container. Do not expose this port to untrusted networks without an appropriate
+network policy or reverse proxy.
+
+## Start Prometheus and Grafana
+
+From the repository root:
+
+```bash
+docker compose -f deploy/observability/docker-compose.yml up -d
+```
+
+Open:
+
+- Grafana: `http://localhost:3000` (`admin` / `admin` by default)
+- Prometheus: `http://localhost:9090`
+- Alertmanager: `http://localhost:9093`
+
+Set `GRAFANA_ADMIN_USER` and `GRAFANA_ADMIN_PASSWORD` before starting Compose
+to override the local defaults. The Prometheus data source and `FlowSense
+Overview` dashboard are provisioned automatically.
+
+## Dashboard panels
+
+The dashboard provides:
+
+- current DAG severity and analysis health;
+- analysis coverage and runtime;
+- anomalous task and handoff counts;
+- DAG severity history;
+- task duration deviation and robust z-score history;
+- current task severity;
+- task cardinality omissions;
+- last successful analysis time.
+- currently firing FlowSense alerts.
+
+Use the DAG and task variables at the top of the dashboard to narrow the view.
+The default time range is six hours and the dashboard refreshes every 30 seconds.
+See [alerting.md](alerting.md) for rule behavior, validation, and production
+notification configuration.
+
+## Stop the stack
+
+```bash
+docker compose -f deploy/observability/docker-compose.yml down
+```
+
+Prometheus and Grafana data remain in named volumes. To explicitly remove those
+local volumes, add `--volumes` to the command.

flowsense_engine-0.4.0/docs/prometheus.md

@@ -0,0 +1,58 @@
+# Prometheus metrics
+
+FlowSense can continuously analyze one or more Airflow DAGs and expose the
+latest results using the Prometheus text exposition format. The endpoint uses
+only the Python standard library, so no additional runtime dependency is
+required.
+
+Start the service:
+
+```bash
+flowsense serve-metrics example_dag another_dag \
+  --host 0.0.0.0 \
+  --port 9108 \
+  --interval-seconds 60
+```
+
+The command uses the same `AIRFLOW_*` configuration as `flowsense analyze`.
+Configure Prometheus to scrape `http://<flowsense-host>:9108/metrics`.
+
+## Metric contract
+
+All metrics are gauges. DAG-level metrics carry only the `dag_id` label:
+
+- `flowsense_analysis_success`
+- `flowsense_analysis_duration_seconds`
+- `flowsense_analysis_last_success_timestamp_seconds`
+- `flowsense_analysis_last_failure_timestamp_seconds`
+- `flowsense_dag_overall_severity`
+- `flowsense_dag_runs_analyzed`
+- `flowsense_dag_analysis_coverage_ratio`
+- `flowsense_dag_anomalous_tasks`
+- `flowsense_dag_anomalous_handoffs`
+- `flowsense_dag_affected_tasks`
+- `flowsense_dag_change_points`
+- `flowsense_dag_trends`
+- `flowsense_dag_diagnostics`
+- `flowsense_dag_dropped_tasks`
+
+Task-level metrics additionally carry `task_id`:
+
+- `flowsense_task_severity`
+- `flowsense_task_deviation_percent`
+- `flowsense_task_robust_z_score`
+
+Severity values are `0` for normal, `1` for medium, `2` for high, and `3` for
+critical.
+
+## Cardinality policy
+
+Task metrics are limited to 200 task IDs per DAG by default. Task IDs are sorted
+to make selection deterministic. Use `--max-tasks-per-dag` to change the
+limit, or set it to `0` to publish DAG-level metrics only. The exporter reports
+the number of omitted tasks through `flowsense_dag_dropped_tasks`.
+
+The exporter retains the latest successful analysis snapshot when a later
+collection fails. In that case `flowsense_analysis_success` becomes `0` and the
+failure timestamp advances, while the last known DAG and task measurements
+remain available.

flowsense_engine-0.4.0/docs/python-api.md

@@ -0,0 +1,142 @@
+# Python library API
+
+`FlowSenseClient` is the recommended entry point for applications embedding
+FlowSense. It is a lightweight in-process facade: it does not start a server,
+own a scheduler, or store analysis results.
+
+## Environment-configured Airflow
+
+Use the standard Airflow environment variables for the shortest setup:
+
+```python
+from flowsense import FlowSenseClient
+from flowsense.infrastructure.airflow import create_airflow_data_source
+
+client = FlowSenseClient(create_airflow_data_source)
+analysis = client.analyze("example_dag")
+
+print(analysis.overall_severity)
+print(analysis.primary_origin)
+```
+
+## Explicit Airflow configuration
+
+Applications that own their configuration should avoid process-global
+environment state:
+
+```python
+from flowsense import FlowSenseClient
+from flowsense.infrastructure.airflow import (
+    AirflowConfig,
+    BasicAuthProvider,
+    create_airflow_data_source_factory,
+)
+
+config = AirflowConfig(
+    base_url="https://airflow.example.com",
+    api_version="v2",
+    history_run_limit=100,
+)
+source_factory = create_airflow_data_source_factory(
+    config,
+    auth_provider=BasicAuthProvider("flowsense", "secret"),
+)
+client = FlowSenseClient(source_factory)
+
+analysis = client.analyze(
+    "example_dag",
+    history_run_limit=50,
+    dag_run_id="scheduled__2026-09-20T00:00:00+00:00",
+)
+```
+
+Secrets are deliberately supplied to an authentication provider rather than
+stored in application code. See [authentication.md](authentication.md) for
+built-in and custom providers.
+
+## Typed requests and policies
+
+Use `execute()` when a request is created at another application boundary:
+
+```python
+from flowsense import AnalysisPolicy, AnalysisRequest
+
+request = AnalysisRequest(
+    dag_id="example_dag",
+    history_run_limit=50,
+    policy=AnalysisPolicy(
+        minimum_history=10,
+        baseline_window=30,
+    ),
+)
+analysis = client.execute(request)
+```
+
+Both `analyze()` and `execute()` return the domain-level `DAGAnalysis` model.
+Use `serialize_analysis()` or `build_analysis_document()` when a versioned
+external output contract is required.
+
+## Analyze multiple DAGs
+
+Airflow-backed applications can discover active DAG ids before starting a
+batch. Discovery uses the configured, paginated Airflow 2 or 3 REST API:
+
+```python
+from flowsense.infrastructure.airflow import AirflowClient
+
+with AirflowClient(config, auth_provider=auth_provider) as airflow:
+    dag_ids = airflow.list_dag_ids()
+
+result = client.analyze_many(dag_ids, max_concurrency=3)
+```
+
+Paused DAGs are excluded by default. Pass `include_paused=True` when they are
+also required.
+
+`analyze_many()` is intended for applications that monitor several DAGs in one
+process. It preserves the requested DAG order and separates successful analyses
+from expected FlowSense failures:
+
+```python
+result = client.analyze_many(
+    ["orders", "payments", "inventory"],
+    history_run_limit=50,
+    max_concurrency=3,
+)
+
+for dag_id, analysis in result.analyses.items():
+    print(dag_id, analysis.overall_severity)
+
+for dag_id, failure in result.failures.items():
+    print(dag_id, failure)
+```
+
+Batch results have their own versioned external contract. Raw exception objects
+are converted to stable failure records containing `error_type` and `message`:
+
+```python
+from flowsense import serialize_batch_analysis
+
+payload = serialize_batch_analysis(result)
+```
+
+Use `build_batch_analysis_document()` for a typed Pydantic document or
+`batch_analysis_json_schema()` for the corresponding JSON Schema. The current
+batch envelope schema version is `1.0`; each successful analysis retains its
+own analysis schema version.
+
+Concurrency is opt-in and bounded; `max_concurrency` defaults to `1`. Each DAG
+receives its own context-managed data source. Expected `FlowSenseError`
+instances are isolated in `failures`, while unexpected programming or adapter
+errors still propagate to the caller. Use individual `AnalysisRequest` objects
+when each DAG needs a different policy or historical run id. When concurrency
+is greater than one, custom data-source factories and injected analysis engines
+must be safe to call from multiple threads.
+
+## Custom data sources and engines
+
+`FlowSenseClient` depends on the `DAGDataSourceFactory` and
+`DAGAnalysisEngine` application ports. A new platform adapter can implement the
+data-source protocol and supply a context-managed factory without depending on
+Airflow. A complete alternative analysis workflow can be injected through the
+optional `analysis_engine` constructor argument.