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

flowsense_engine-0.4.0/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+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.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
+
+- 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
+
+- Renamed the Python distribution to `flowsense-engine` while preserving the
+  `flowsense` import package and CLI command.
+- Added tokenless PyPI publishing through GitHub Actions Trusted Publishing.
+
+## [0.2.0] - 2026-09-10
+
+### Added
+
+- Task handoff drift, impact classification, propagation, and root-cause analysis.
+- Configurable drift, mapped-task aggregation, change-point, and trend policies.
+- Apache Airflow 2 and 3 API compatibility with pagination and bounded history.
+- Retry, timeout, backoff, and `Retry-After` handling for Airflow requests.
+- Historical DAG run analysis with preceding-history isolation.
+- Rich CLI reports, JSON output, severity-based exit thresholds, and schema output.
+- MCP analysis tool with the same policy and versioned response contract as the CLI.
+- Typed `AnalysisRequest` and `AnalysisDocument` contracts with JSON Schema support.
+- Supported top-level library API, typed package marker, and Python 3.12/3.13 CI.
+
+### Changed
+
+- Split the analysis workflow into domain, application, infrastructure, and adapter
+  boundaries.
+- Analysis output schema advanced to version `1.1` with `current_dag_run_id`.
+- Expected configuration, Airflow API, and payload failures now use a unified error
+  hierarchy.
+
+### Fixed
+
+- Preserved anomaly origins across normal dependency gaps.
+- Detected drift when the historical median absolute deviation is zero.
+- Aggregated dynamically mapped task instances before analysis.
+- Reported insufficient history and invalid handoff timing as diagnostics.
+
+## [0.1.0] - 2026-08-18
+
+### Added
+
+- Initial FlowSense prototype with Airflow task-duration collection and robust
+  median/MAD drift detection.

flowsense_engine-0.4.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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowsense-engine
-Version: 0.2.1
+Version: 0.4.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.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.
+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.
 
@@ -177,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
@@ -189,6 +193,16 @@ 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.
+
 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
@@ -272,22 +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 AirflowClient, analyze_dag
+from flowsense import FlowSenseClient
+from flowsense.infrastructure.airflow import create_airflow_data_source
 
-with AirflowClient() as source:
-    analysis = analyze_dag(
-        dag_id="flowsense_demo",
-        source=source,
-    )
+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
@@ -345,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.2.1 → flowsense_engine-0.4.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.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.
+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.
 
@@ -142,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
@@ -154,6 +158,16 @@ 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.
+
 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
@@ -237,22 +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 AirflowClient, analyze_dag
+from flowsense import FlowSenseClient
+from flowsense.infrastructure.airflow import create_airflow_data_source
 
-with AirflowClient() as source:
-    analysis = analyze_dag(
-        dag_id="flowsense_demo",
-        source=source,
-    )
+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
@@ -310,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.4.0/docs/architecture.md

@@ -0,0 +1,138 @@
+# 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.
+
+`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,
+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.
+
+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`, `flowsense.mcp`, and `flowsense.observability` translate user input into an
+`AnalysisRequest`, invoke `AnalyzeDAG`, and translate the result into their own
+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
+
+```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.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/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.