SIENTIAPDE-1811

Enhance OPC UA communication and metrics tracking

- Updated README.md to include new OPC UA Communication section and detailed metrics for session and write diagnostics.
- Added new metrics in laborious/metrics.py for tracking OPC UA session states and write attempts.
- Refactored OPC activity in laborious/activities/opc.py to handle session errors and improve error reporting.
- Updated e2e tests to cover new scenarios for OPC session/channel errors and reconnect handling.
- Modified .gitignore to include relatorio files and mlruns directory.
- Added ipykernel to requirements-dev.txt for Jupyter notebook support.

README.md

@@ -48,6 +48,7 @@ A comprehensive, Temporal-based ML orchestration system for industrial data proc
   - [Prediction Operation Metrics](#prediction-operation-metrics)
   - [OPC Export Metrics](#opc-export-metrics)
   - [Data Quality Metrics](#data-quality-metrics)
+- [OPC UA Communication](#opc-ua-communication)
 - [Configuration](#configuration-1)
   - [Environment Variables](#environment-variables)
   - [OPC Configuration](#opc-configuration)
@@ -164,7 +165,7 @@ Laborious uses a Temporal-based architecture with strong separation of concerns
 - `connectors_config.py`: Env-driven configuration builders
 - `models/minio_dataframe_payload.py`: MinIO-offloaded DataFrame payload model
 - ML models are loaded via `SientiaMLflowRepository` (wrapper-based, `@production` alias) constructed in `Activities` from `build_mlflow_config()`.
-- `repository/opc_repository.py`: OPC communication and writes
+- `repository/opc_repository.py`: OPC UA client, writes, session recovery (see [OPC UA Communication](#opc-ua-communication))
 - `repository/minio_manager.py`: MinIO object storage operations
 - `filters/conditional_filters.py` and `filters/mlflow_filters.py`
 
@@ -778,6 +779,15 @@ The Laborious system exposes comprehensive Prometheus metrics for operational vi
   - Labels: `pod_id`, `model_name`, `workflow_name`, `opc_server_id`
   - Buckets: [0.01, 0.05, 0.1, 0.2, 0.5, 1.0, 2.0, 5.0, 10.0]
 
+OPC UA session and write diagnostics (Prometheus, `laborious/metrics.py`):
+
+- `opc_connections_initiated_total`, `opc_connections_failed_total`, `opc_connection_status`
+- `opc_session_created_total`, `opc_session_closed_total`, `opc_session_revised_timeout_milliseconds`
+- `opc_write_attempts_total` (label `result`: `OK` or exception name, e.g. `BadSessionIdInvalid`)
+- `opc_write_inter_arrival_over_session_timeout_total`
+
+See [OPC UA Communication](#opc-ua-communication) for semantics, concurrency, and confidence codes **12** / **14**.
+
 ### Data Quality Metrics
 - Filter pass/fail rates through notification system
 - MLFlow API response validation metrics
@@ -822,7 +832,7 @@ The Laborious system exposes comprehensive Prometheus metrics for operational vi
 | `OPC_CERT_PATH` | OPC client certificate path | `None` | No |
 | `OPC_PRIVATE_KEY_PATH` | OPC private key path | `None` | No |
 | `OPC_SERVER_CERT_PATH` | OPC server certificate path | `None` | No |
-| `OPC_RECONNECTION_INTERVAL` | OPC reconnection interval (ms) | `120` | No |
+| `OPC_RECONNECTION_INTERVAL` | Minimum seconds between OPC reconnects | `120` | No |
 | `PI_WEB_API_BASE_URL` | PI Web API server base URL | `None` | No |
 | `PI_WEB_API_AUTH_TYPE` | PI Web API authentication type (basic/bearer) | `None` | No |
 | `PI_WEB_API_AUTH_TOKEN` | PI Web API authentication token | `None` | No |
@@ -915,6 +925,12 @@ Legacy MinIO object layout (relative key):
 `training_datasets/{model_name}/{object_prefix}_{timestamp}.parquet` where `object_prefix` is sanitized
 (slashes replaced by underscores) to keep a stable model-level directory.
 
+## OPC UA Communication
+
+Full reference: **[docs/opc-communication.md](docs/opc-communication.md)** (connection lifecycle, Tier-1 `Bad*` reconnect, connection lock / session readiness, metrics, PostgreSQL confidence **12** vs **14**, tests).
+
+Implementation plan: [`.cursor/plans/opc_bad_reconnect_ac4c6045.plan.md`](.cursor/plans/opc_bad_reconnect_ac4c6045.plan.md).
+
 ### OPC Configuration
 
 For multiple OPC servers, use the `OPC_CONFIG` environment variable:
@@ -1180,8 +1196,10 @@ laborious/
    - Ensure proper connection pool configuration
 
 4. **OPC Connection Failures**
-   - Verify OPC server is accessible
+   - See [docs/opc-communication.md](docs/opc-communication.md)
+   - Verify OPC server is accessible and `OPC_RECONNECTION_INTERVAL` is appropriate
    - Check certificate and key file paths
+   - Correlate `opc_write_attempts_total` with `opc_session_*` metrics; count session errors via `prediction_confidence = 14`
    - Review OPC server logs for connection issues
 
 5. **PI Web API Connection Failures**