Metadata-Version: 2.4
Name: ai-zkt
Version: 0.1.2
Summary: Python SDK for integrating with ZKTeco biometric devices (TCP/IP support)
Author-email: Ahmad Ibrahim <ahmad@example.com>
Maintainer-email: Ahmad Ibrahim <ahmad@example.com>
License: MIT
Project-URL: Homepage, https://github.com/ahmadibrahim/ai-zkt
Project-URL: Repository, https://github.com/ahmadibrahim/ai-zkt
Project-URL: Documentation, https://github.com/ahmadibrahim/ai-zkt#readme
Project-URL: Bug Tracker, https://github.com/ahmadibrahim/ai-zkt/issues
Keywords: zkteco,biometric,attendance,tcp,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware
Classifier: Topic :: Office/Business
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.5.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"

# ai-zkt

Python SDK for integrating with ZKTeco biometric devices via TCP/IP.

## Features

- **Device Communication**: Connect to ZKTeco devices via TCP/IP
- **Data Import**: Import attendance data from Excel, CSV files, or directly from devices
- **Data Processing**: Built-in deduplication and aggregation capabilities
- **Flexible Parsing**: Support for various date/time formats and column structures
- **Error Handling**: Comprehensive exception handling for robust op``````erations
- **Utilities**: Date/time utilities and helper functions
- **Clean API**: Simple and intuitive interface for common operations

## Installation

### Standard Installation

```bash
pip install ai-zkt
```


## Quick Start

### Excel Upload Function - Step by Step Guide

The Excel upload function supports three different Excel formats for attendance data. Follow these steps to import your Excel file:

#### **Step 1: Prepare Your Excel File**
Ensure your Excel file matches one of these supported formats:

**Format 1**: `User ID, Verify Mode, In/Out, Date, Time`
```
User ID | Verify Mode | In/Out   | Date       | Time
101     | 0           | Check In | 2026-04-15 | 08:55:12
101     | 0           | Check Out| 2026-04-15 | 17:02:30
```

**Format 2**: `User ID, DateTime, Status`
```
User ID | DateTime           | Status
101     | 2026-04-15 08:55:12| Check In
101     | 2026-04-15 17:02:30| Check Out
```

**Format 3**: `Emp Code, Name, Date, Check In, Check Out, Work Time`
```
Emp Code | Name   | Date       | Check In | Check Out | Work Time
101      | Ahmed  | 2026-04-15 | 08:55    | 17:02    | 08:07
102      | Mohamed| 2026-04-15 | 09:15    | 18:30    | 09:15
```

#### **Step 2: Use the ImportService**

```python
from ai_zkt import ImportService

# Create import service instance
service = ImportService()

# Import Excel file
logs = service.import_from_excel("your_attendance_file.xlsx")

# Get summary statistics
summary = service.get_import_summary(logs)
print(f"Total records: {summary['total_records']}")
print(f"Unique users: {summary['unique_users']}")
```

#### **Step 3: Process the Imported Data**

```python
# Remove duplicates if needed
clean_logs = service.deduplicate_logs(logs)

# Export to different format if needed
service.export_to_excel(clean_logs, "cleaned_attendance.xlsx")
service.export_to_csv(clean_logs, "cleaned_attendance.csv")

# Aggregate data for reporting
aggregated = service.aggregate_logs(clean_logs, group_by="user_id")
```

#### **Step 4: Command Line Usage**

You can also use the main script directly:

```bash
python main.py your_attendance_file.xlsx
```

#### **Step 5: Error Handling**

```python
from ai_zkt import ZKTecoError, DataError, ParseError

try:
    logs = service.import_from_excel("attendance.xlsx")
except ParseError as e:
    print(f"Excel parsing failed: {e}")
except DataError as e:
    print(f"Data processing failed: {e}")
except ZKTecoError as e:
    print(f"General error: {e}")
```

### **Supported Column Variations**

The system automatically recognizes these column name variations:

- **User ID**: `User ID`, `UserID`, `Employee ID`, `Emp ID`, `Emp Code`
- **Date/Time**: `Date`, `Time`, `DateTime`, `Date/Time`, `Timestamp`
- **Status**: `Status`, `Check Type`, `Type`, `In/Out`
- **Check Times**: `Check In`, `Check Out`, `Check-In`, `Check-Out`

### **Date Format Support**

The system automatically handles different date formats:
- `YYYY-MM-DD HH:MM:SS` (e.g., `2026-04-15 08:55:12`)
- `DD/MM/YYYY HH:MM` (e.g., `15/04/2026 08:55`)
- `MM/DD/YYYY HH:MM` (e.g., `04/15/2026 08:55`)
- And many more variations

``
### Basic Device Connection

```python
from ai_zkt import ZKTecoDevice

# Connect to a ZKTeco device
device = ZKTecoDevice("192.168.1.100")

try:
    device.connect()
    
    # Get attendance logs
    logs = device.get_attendance_logs()
    print(f"Fetched {len(logs)} attendance records")
    
    # Get device information
    info = device.get_device_info()
    print(f"Device: {info['model']} v{info['firmware_version']}")
    
finally:
    device.disconnect()
```

### Using Context Manager

```python
from ai_zkt import ZKTecoDevice

# Automatic connection management
with ZKTecoDevice("192.168.1.100") as device:
    logs = device.get_attendance_logs()
    for log in logs:
        print(f"User {log.user_id}: {log.timestamp} - {log.status}")
```

### Import Service

```python
from ai_zkt import ImportService

service = ImportService()

# Import from Excel file
logs = service.import_from_excel("attendance_data.xlsx")

# Import from CSV file
logs = service.import_from_csv("attendance_data.csv")

# Import directly from device
logs = service.import_from_device("192.168.1.100")

# Remove duplicates
clean_logs = service.deduplicate_logs(logs)

# Get summary statistics
summary = service.get_import_summary(clean_logs)
print(f"Total records: {summary['total_records']}")
print(f"Unique users: {summary['unique_users']}")
```

## API Reference

### ZKTecoDevice

Main class for communicating with ZKTeco devices.

```python
class ZKTecoDevice:
    def __init__(self, host: str, port: int = None, **kwargs)
    def connect(self) -> bool
    def disconnect(self)
    def is_connected(self) -> bool
    def get_attendance_logs(self) -> List[AttendanceLog]
    def get_device_info(self) -> Dict[str, Any]
```

### ImportService

Service for importing and processing attendance data.

```python
class ImportService:
    def import_from_excel(self, file_path: str, **kwargs) -> List[AttendanceLog]
    def import_from_csv(self, file_path: str, **kwargs) -> List[AttendanceLog]
    def import_from_device(self, device_host: str, device_port: int = None) -> List[AttendanceLog]
    def deduplicate_logs(self, logs: List[AttendanceLog]) -> List[AttendanceLog]
    def aggregate_logs(self, logs: List[AttendanceLog], **kwargs) -> Dict[str, Any]
    def export_to_excel(self, logs: List[AttendanceLog], output_path: str, **kwargs)
    def export_to_csv(self, logs: List[AttendanceLog], output_path: str, **kwargs)
    def get_import_summary(self, logs: List[AttendanceLog]) -> Dict[str, Any]
```

## Configuration

### Default Settings

The library uses sensible defaults for device communication:

```python
from ai_zkt.config import get_zkteco_config

config = get_zkteco_config()
print(config)
# {
#     "timeout": 30,
#     "port": 4370,
#     "retries": 3,
#     "retry_delay": 1,
#     "encoding": "utf-8"
# }
```

## Error Handling

The library provides specific exceptions for different error scenarios:

```python
from ai_zkt import ZKTecoError, ConnectionError, DataError, ParseError

try:
    logs = service.import_from_excel("data.xlsx")
except ConnectionError as e:
    print(f"Connection failed: {e}")
except ParseError as e:
    print(f"Data parsing failed: {e}")
except DataError as e:
    print(f"Data processing failed: {e}")
except ZKTecoError as e:
    print(f"General ZKTeco error: {e}")
```

## Development

### Setup Development Environment

```bash
git clone https://github.com/ahmadibrahim/ai-zkt.git
cd ai-zkt
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

## License

This project is licensed under the MIT License.

## Changelog

### Version 0.1.1
- Initial release
- Basic ZKTeco device communication
- Excel/CSV data import
- Data processing and aggregation
- Comprehensive error handling
- Date/time utilities
