production-analytics/README.md

production-analytics

production-analytics is a small Python service that derives production analytics from ENLYZE data for Grafana. ENLYZE remains the authority for raw process data; this project persists only derived metrics, events, relevant production-order context, and calculation state.

Status

This repository includes a read-only ENLYZE API exploration CLI. It contains no verified ENLYZE operation wrappers, database migrations, or HTTP endpoints.

Intended flow

ENLYZE (raw data) -> retrieval boundary -> calculations -> TimescaleDB -> Grafana
                                      \-> calculation provenance/state

Production orders are the primary attribution context for results. Every persisted result will ultimately be traceable to its machine, order/article context, source time range, and calculation implementation version.

Development

Requires Python 3.11 or newer. Install the project and development tools:

python3 -m pip install -e '.[dev]'
pytest
ruff check .

Copy .env.example to .env for public/local configuration documentation. Put real ENLYZE credentials only in secrets/enlyze.env, which is ignored. The CLI reads that file by default without executing it; it accepts only simple KEY=VALUE lines (quoted values are supported). Environment variables may be used instead when appropriate. Never pass keys as command-line arguments.

The generic request command only performs GET requests and requires the operator to provide an API path that is known to be safe and authorized:

production-analytics enlyze raw /verified/path --pretty
production-analytics enlyze raw /verified/path --save-fixture response.json

Public ENLYZE documentation verifies Bearer-token authentication. Put ENLYZE_API_KEY='...' in the local secret file; the exploration client sends it as an Authorization: Bearer … header and never prints that header/value.

The second command saves a sanitized, reviewable fixture under fixtures/enlyze/ by default. Raw captures belong in the ignored data/raw/enlyze/ directory and must not be committed.

The OpenAPI server URL is https://app.enlyze.com/api/; its operation paths begin with /v2/. Set ENLYZE_BASE_URL to that server URL, not to an operation path. The documented read-only time-series operation is exposed for exploration as production-analytics enlyze timeseries.

The current Compose file has no application service, so it deliberately does not pass ENLYZE credentials to TimescaleDB. A future application service should use env_file: ./secrets/enlyze.env rather than copying secrets into Compose.

Peak-cycle detection

PeakCycleDetector is a pure calculation-domain component for roll length, roll weight, and comparable sawtooth/batch signals. It retains the current maximum and emits it only after the value is below drop_ratio * current_peak continuously for hold_seconds. Configuration is min_peak, drop_ratio (strictly between 0 and 1), non-negative hold_seconds, and positive max_sample_gap_seconds. The hold uses elapsed timestamps, never a sample count; an interval longer than the configured maximum sample gap restarts a reset candidate, so a timestamp gap alone is not evidence that a signal remained below threshold. max_sample_gap_seconds is required rather than defaulted, so the source's continuity assumption is explicit for each detector configuration. Reset values can be negative and need not be zero. Equal timestamps are accepted in arrival order but add no elapsed hold time; backwards timestamps are rejected.

The first real-world validation case is K7 roll length (m), variable bf81c547-dccf-4709-aee2-0f78366d1dfc. When the ignored local capture is present, run python scripts/validate_k7_roll_length.py to inspect detected peaks without adding the raw capture to tests or version control.

docker compose up -d timescaledb is an optional local database design for a future persistence milestone. It is not required for the bootstrap tests.

See PROJECT_KNOWLEDGE.md for durable project context and docs/roadmap.md for the implementation sequence.