8.6 KiB
Project knowledge
Purpose
This service is a calculation and persistence layer between ENLYZE and Grafana. Its primary use case is to continuously integrate material consumption for the currently active production order and expose its cumulative value in Grafana while production is running. K7 fiber is the first validated application, not the scope of the product. It must not become a second historian: raw process data stays in ENLYZE and is retrieved again when historical calculations need reproduction.
Core architectural decisions
- Python with a
src/package layout. - FastAPI is the preferred future service layer; no HTTP API is needed now.
- PostgreSQL with TimescaleDB is the target derived-data store.
- Grafana reads derived data from that database as an additional datasource.
- Secrets are environment variables only; no credentials or site-specific configuration are committed.
- Calculations are modular, testable Python implementations. Configuration declares instances; it is not a generic low-code language.
- Historical production-order analysis/backfill is secondary. It uses the same generic integration engine as live processing: one integration engine with live incremental and historical replay/backfill operating modes.
Material-consumption integration
The core calculation is generic rate integration: cumulative material
consumption increases by material_rate * elapsed_time when the configured
machine/process-specific validity or gating conditions are satisfied. It is
reusable across machines, materials, rate variables, units, and gates. The
project deliberately does not define a broader configuration schema here.
Peak-cycle detector
The first generic calculation is a timestamp-based PeakCycleDetector under
calculations. It is transport-independent and works for roll length, roll
weight, and similar cyclic signals. It maintains the maximum in an open cycle;
after a value falls below drop_ratio * current_peak, it emits that maximum
only after actual subsequent below-threshold observations support a continuous
hold_seconds interval. min_peak is a generic detector setting, along with
drop_ratio (0 < ratio < 1), hold_seconds (>= 0), and an explicit positive
max_sample_gap_seconds. They are selected per signal, rather than being
globally fixed process constants. Elapsed time, never a sample count, determines
confirmation. An interval longer than the configured maximum sample gap
restarts a reset candidate, so a timestamp gap is not
continuous-below evidence. Reset values can be negative rather than zero,
equal timestamps add no elapsed time, and backwards timestamps are rejected.
The maximum gap is required rather than inferred or defaulted, making each
source's continuity assumption explicit.
K7 roll length, variable bf81c547-dccf-4709-aee2-0f78366d1dfc (m), is the
clean reference validation case. With min_peak=10, drop_ratio=0.75,
hold_seconds=60, and max_sample_gap_seconds=20, its continuous 10-second
capture produced exactly four plausible peaks of approximately 49.98 m. Its
shorter-than-requested result was caused by an end time queried in the future,
not observed time-series gaps.
Bento 2 roll weight is the second, more realistic robustness validation case:
machine 6201f3de-b940-45d7-930c-1481c5ae9e1d, variable
059c0015-9aff-4270-a4ce-f21b83f99378 (kg). Its observed cadence is 10
seconds, but it has long plateaus, reset values roughly 300–470 kg, and
materially varying peaks. With min_peak=800, drop_ratio=0.75,
hold_seconds=60, and max_sample_gap_seconds=20, the extended capture
yielded 13 plausible completed peaks: 936, 919, 935, 930, 930, 920, 909,
1195, 921, 930, 939, 912, and 914 kg (from 00:46:50Z through 03:06:30Z on
2026-09-04). The approximately 1195 kg peak is retained as a real
process/mechanical condition, not special-cased as a defect; it is emitted
only after its following reset has enough below-threshold observations. A
reset is not expected to approach zero, and peak values are not assumed to be
constant. Raw captures remain ignored and deterministic tests use synthetic
fixtures only.
Central domain context
Production orders connect machine, article/material, source interval, and
derived results. An ENLYZE Production Run is a time segment; one
production_order can have one or more Production Runs. Integrate each run
separately, then aggregate derived values on the production-order level. Never
implicitly bridge gaps between runs. Metrics and events must retain calculation
type/version and source-time-range provenance.
K7 fiber integration
The current K7 candidate fiber mass-flow signal is Stundenleistung Anlage
in kg/h. Observed behaviour supports treating it as a process-responsive
band-scale signal, but it can remain frozen at a non-zero value during a
machine stop. It must therefore be integrated only while the validated gate
Geschwindigkeit Gesamtanlage > 0.5 m/min is active. The ENLYZE boolean
Anlage läuft is not the primary integration gate.
The process-derived result is fiber_feed_kg for a Production Run. It is not
automatically a finished-product mass or a per-order material yield. Material
measured at the band scale may still be in the machine at an order transition,
and ERP feedback can arrive asynchronously or periodically. Differences from
reported finished-product quantities must not automatically be labelled scrap;
an exact per-order yield needs WIP/transport-delay accounting.
Bento 1 bentonite-powder integration
Bento 1 bentonite-powder consumption is the next planned application of the same generic integration mechanism. Its ENLYZE source variable and its validity/gating logic have not yet been selected or validated; both must be determined from Bento 1 process data before implementation. Bento 1 does not need a separate subsystem or calculation formula.
Quantity-total interpretation
For this customer setup, production_run.quantity_total is populated from
ERP/BI production feedback received by ENLYZE, rather than necessarily being
calculated from machine signals. The tested source CSV field is
PCO_FEEDB_QUANTITY. For inspected machines/articles it represents reported
finished-product area in m² (for example, 5.00 m × 50 m = 250.00 m²; 4.75 m ×
50 m = 237.50 m²; 5.80 m × 50 m = 290.00 m²). The unit displayed by ENLYZE is
separately configured and must not be considered authoritative until its
configuration is validated.
Known versus unknown
Validated K7 historical tests show physically plausible fiber-feed totals when
the band-scale kg/h signal is speed-gated. For production order
K 7-12026000842, its run from 2026-08-31T10:57:54Z to
2026-08-31T18:23:11Z had ERP quantity_total of 12,420 m², approximately
5.206 active hours, approximately 5,180.1 kg integrated fiber feed,
approximately 2,174.2 m integrated machine length, and approximately
995.1 kg/h average active throughput. Article external ID 213408 has width
6.0 m and static mean basis weight 390.16 g/m²; the corresponding approximate
reported finished-product mass is 4,845.8 kg. This is a plausibility validation
case, not a precise material-yield calculation.
Known from the ENLYZE UI/API exploration: machine and product identity, Production Runs, and relevant K7 process signals are available. Some API and time-series semantics remain unverified; do not infer them beyond documented evidence. The active evidence and open-question list is in docs/enlyze-api.md.
Future refinement
An optional future historical mass-balance refinement is to obtain actual QA/QS basis-weight measurements from SQL instead of using static article basis weight. It is not a blocker for the live material-consumption MVP.
Exploration workflow
A deliberately generic, read-only CLI is available as
production-analytics enlyze raw PATH. It only makes GET requests, never
guesses endpoint schemas, and emits sanitized response metadata/body. The
operator must first obtain an authorized base URL, a verified safe path, and
the authentication method. Credentials reside in ignored secrets/enlyze.env;
the CLI parses simple assignments without sourcing/executing the file. Public
ENLYZE documentation verifies an Authorization: Bearer <ENLYZE_API_KEY>
authentication header; its value is never printed.
Unmodified captures are local in ignored data/raw/enlyze/. Fixtures written
to fixtures/enlyze/ are sanitized, but must still be reviewed before commit.
The exploration deliverable is verified API observations and sanitized
fixtures. The next product deliverable is live incremental material
integration, using a generic material-rate integrator rather than a separate
historical-only calculation path.