Metadata-Version: 2.4
Name: mtchart-sdk
Version: 0.4.0
Summary: SDK for building thermal monitoring, traceability, and reporting systems derived from MTChart Pro.
Author: MTD Softwares
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/Romero-Softwares/mtchart_sdk
Project-URL: Repository, https://github.com/Romero-Softwares/mtchart_sdk
Project-URL: Documentation, https://github.com/Romero-Softwares/mtchart_sdk#readme
Project-URL: Issues, https://github.com/Romero-Softwares/mtchart_sdk/issues
Keywords: monitoring,thermal-process,traceability,aviation,industrial
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Provides-Extra: hardware
Requires-Dist: pymodbus>=3.6; extra == "hardware"
Requires-Dist: pyModbusTCP>=0.3; extra == "hardware"
Provides-Extra: reports
Requires-Dist: openpyxl>=3.1; extra == "reports"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# MTChart SDK

SDK for developers who want to build systems similar to MTChart Pro using reusable classes and methods.

This first version is separate from the desktop application and provides a clean core to:

- register thermal processes;
- validate temperature readings;
- calculate expected exit time;
- register a parts and PN catalog in the backend chosen by the developer;
- build traceability data without depending on the desktop interface;
- calculate output folders by year/month, oven, and file type;
- standardize log names, entry control files, and report numbers.
- record auditable operation logs compatible with MTChart Pro V9;
- format and export audit logs to Excel for validation packages.
- connect to MTChart-compatible Modbus hardware through an optional driver manager.

## Installation

```powershell
python -m pip install mtchart-sdk
```

For hardware communication, install the optional Modbus dependencies:

```powershell
python -m pip install "mtchart-sdk[hardware]"
```

## Quick Example

```python
from datetime import datetime

from mtchart_sdk import MTChartService, PartItem, PenConfig, ProcessInput

service = MTChartService()

process = service.create_process(
    ProcessInput(
        report_number="CH-0001",
        project="OS-123",
        process_name="Embrittlement relief",
        oven="Oven 01",
        relief_hours=3,
        pen=PenConfig(id="1", name="Pen 1", stabilization_target=189, low_limit=175.9),
        items=[
            PartItem(name="Bracket", pn="PN-001", sn="SN-001", qty=1),
        ],
        started_at=datetime(2026, 6, 28, 8, 0, 0),
    )
)

reading = service.evaluate_reading(process, value=188.7)

print(process.report_number)
print(reading.status)
print(reading.can_start_process)
```

## Structure

- `mtchart_sdk.models`: process data models.
- `mtchart_sdk.rules`: pure temperature and time rules.
- `mtchart_sdk.reports`: report, log, batch, audit, date, and traceability utilities.
- `mtchart_sdk.output_paths`: output folder organization matching MTChart Pro.
- `mtchart_sdk.storage`: catalog contract and default SQLite backend.
- `mtchart_sdk.driver_manager`: optional Modbus serial/TCP driver manager.
- `mtchart_sdk.service`: main facade for use by other systems.
- `mtchart_sdk.cli`: command-line demo to validate installation.
- `examples/basic_process.py`: minimal executable example.

## Main API

- `MTChartService.create_process(data)`: normalizes parts, calculates total quantity, and expected exit time.
- `MTChartService.evaluate_reading(process, value)`: classifies the reading as `OK`, `LOW`, `HIGH`, or `N/A`.
- `MTChartService.search_parts(term)`: searches the local parts catalog by name or PN.
- `MTChartService.build_output_paths(root, reference_date, oven=...)`: calculates LOGS, control, PDF, and chart folders by period.
- `MTChartService.parts_control_path(root, process)`: builds the parts control path using the report number.
- `MTChartService.report_summary(process)`: summarizes items, total quantity, and main report data.
- `MTChartService.record_audit_operation(operator_id, action, tab, details)`: persists an operation log.
- `MTChartService.list_audit_operations(start=..., end=...)`: lists operation logs newest first.
- `clean_identifier(value)`: removes common prefixes such as `PN:`, `P/N:`, `LOTE:`, and `BATCH:`.
- `format_report_number(value)`: replaces `/` with `-` for stable file names.
- `temperature_log_filename(identity)`: generates the Excel log name using report number, PN, and SN.
- `export_audit_operations(logs, output_path)`: creates an Excel workbook with auditable operation logs.
- `DriverManager(config)`: connects to serial/TCP Modbus hardware and reads configured pens.

## Hardware Driver

`DriverManager` reads the same hardware and pen structure used by MTChart Pro. The configuration object can be a dictionary or an object exposing `get_val()` and, optionally, `set_pena_valor()`.

```python
from mtchart_sdk import DriverManager

config = {
    "hardware": {
        "metodo_conexao": "TCP",
        "ip_fieldlogger": "192.168.0.100",
        "modbus_port": 502,
    },
    "penas": [
        {"id": "1", "ativa": True, "slave_id": 1, "endereco_modbus": 0, "tipo_dado": "int16", "escala": 1},
    ],
}

driver = DriverManager(config)
if driver.conectar():
    readings, ok = driver.capturar_todas_penas()
```

## Audit Logs

```python
from datetime import datetime

from mtchart_sdk import MTChartService, export_audit_operations

service = MTChartService(catalog_db="mtchart.db")
service.record_audit_operation(
    operator_id="OP-123",
    action="REGISTROU_ENTRADA",
    tab="DASHBOARD",
    details="pn=PN-001; projeto=OS-123; inicio_imediato=True",
    occurred_at=datetime(2026, 7, 11, 10, 30, 0),
)

logs = service.list_audit_operations(start="2026-07-11 10:30", end="2026-07-11 10:30")
export_audit_operations(logs, "operation_logs.xlsx")
```

## Flexible Database

The SDK uses SQLite by default to make the first use simple:

```python
from mtchart_sdk import MTChartService

service = MTChartService(catalog_db="catalog.db")
```

To use PostgreSQL, MySQL, SQL Server, MongoDB, an internal API, or any other storage layer, inject your own backend with `save()` and `search()` methods:

```python
from mtchart_sdk import MTChartService


class MyCatalog:
    def save(self, name: str, pn: str, increment: bool = True) -> None:
        # Store in any database, ORM, or external service.
        ...

    def search(self, term: str = "", limit: int = 100) -> list[dict[str, object]]:
        # Return dictionaries with at least name and pn.
        return []


service = MTChartService(catalog=MyCatalog())
```

This contract keeps MTChart rules independent from the database. SQLite remains available as the default backend, but it is not mandatory for SDK integrations.

## Demo CLI

After installing locally, run:

```powershell
mtchart-sdk-demo --value 188.7
```

Or run it as a script without installing:

```powershell
python -m mtchart_sdk.cli --catalog-db .tmp_demo.db --value 188.7
```

The command creates a sample process, evaluates the reading, and returns JSON with status, expected exit time, and local catalog results.

## Local Validation

To validate a local SDK copy during development:

```powershell
python tools/validate_package.py
```

The validator checks metadata, compiles modules, runs tests, and executes the demo example/CLI.

## Status

Version 0.4.0. The public API follows the latest catalog, traceability, report number, report folder, operation audit, log export, and optional hardware driver updates.
