Metadata-Version: 2.4
Name: rtv-workmate
Version: 0.1.1
Summary: Python client library for Workmate APIs
Author: jumashafara
Author-email: jumashafara0@gmail.com
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: requests (>=2.31.0)
Description-Content-Type: text/markdown

# Workmate Library

A Python client library for interacting with Workmate APIs.

## Installation

```bash
pip install -e .
```

## Modules

- **risk_assessment** - Model management functions
- **sbcc** - SBCC message feedback management functions

## Risk Assessment Module

The `risk_assessment` module provides functions for managing risk assessment models.

### Setup

First, configure the API connection:

```python
from rtv_workmate.risk_assessment import set_config

set_config(
    base_url="http://localhost:8000",
    api_key="wm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)

# Or use JWT token
set_config(
    base_url="http://localhost:8000",
    jwt_token="your_jwt_token_here"
)
```

### Usage Examples

#### List all models

```python
from rtv_workmate.risk_assessment import list_models, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
models = list_models()
for model in models:
    print(f"{model['name']} - {model['category']} v{model['version']}")
```

#### Get a specific model

```python
from rtv_workmate.risk_assessment import get_model, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
model = get_model({
    'name': 'UG_North_1_C',
    'category': 'classification',
    'version': '2025.0.1'
})
print(model['metrics'])
```

#### Create a model

```python
from rtv_workmate.risk_assessment import create_model, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
create_model({
    'name': 'UG_North_1_C',
    'category': 'classification',
    'version': '2025.0.1',
    'description': 'Latest model for North region',
    'metrics': {'accuracy': 0.76, 'precision': 0.72, 'recall': 0.80},
    'other_training_results': {
            'roc_auc': ...,
            'best_cutoff': ...,
            'feature_importances': ...,
            'numeric_features': ...,
            'categorical_features': ...,
            'one_way_pds': make_json_serializable(model_pdps),
            'two_way_pds': make_json_serializable(model_two_way_pdps)
        },
    'model_file_path': '/path/to/model.pkl'
})
```

#### Update a model

```python
from rtv_workmate.risk_assessment import update_model, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
updated_model = update_model(
    model_identifier={
        'name': 'UG_North_1_C',
        'category': 'classification',
        'version': '2025.0.1'
    },
    model_data={
        'description': 'Updated description',
        'metrics': {'accuracy': 0.78}
    }
)
```

#### Delete a model

```python
from rtv_workmate.risk_assessment import delete_model, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
delete_model({
    'name': 'UG_North_1_C',
    'category': 'classification',
    'version': '2025.0.1'
})
```

### Error Handling

```python
from rtv_workmate.risk_assessment import get_model, APIError, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")

try:
    model = get_model({'name': 'test', 'category': 'test', 'version': '1.0'})
except APIError as e:
    print(f"API Error: {e.message} (Status: {e.status_code})")
```

### API Reference

#### Configuration

- `set_config(base_url, api_key=None, jwt_token=None)` - Set global API configuration

#### Model Functions

- `list_models()` - Get all models
- `get_model(model_identifier)` - Get a specific model. `model_identifier` dict requires: `name`, `category`, `version`
- `create_model(model_data)` - Create a new model. `model_data` dict requires: `name`, `category`, `version`. Optional: `description`, `metrics`, `other_training_results`, `model_file`, `model_file_path`
- `update_model(model_identifier, model_data)` - Update an existing model. `model_identifier` dict requires: `name`, `category`, `version`. `model_data` dict can contain any fields to update
- `delete_model(model_identifier)` - Delete a model. `model_identifier` dict requires: `name`, `category`, `version`

#### Exceptions

- `APIError` - Exception raised for API errors. Contains `message` and `status_code` attributes.

## SBCC Module

The `sbcc` module provides functions for managing SBCC message feedback.

### Setup

First, configure the API connection:

```python
from rtv_workmate.sbcc import set_config

set_config(
    base_url="http://localhost:8000",
    api_key="wm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)

# Or use JWT token
set_config(
    base_url="http://localhost:8000",
    jwt_token="your_jwt_token_here"
)
```

### Usage Examples

#### List all message feedbacks

```python
from rtv_workmate.sbcc import list_message_feedbacks, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
feedbacks = list_message_feedbacks()
for feedback in feedbacks:
    print(f"{feedback['practice']} - {feedback['barrier']}")
```

#### List with filters

```python
from rtv_workmate.sbcc import list_message_feedbacks, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
# Filter by liked status and practice
feedbacks = list_message_feedbacks(filters={
    'is_liked': True,
    'practice': 'Handwashing'
})
```

#### Get a specific feedback

```python
from rtv_workmate.sbcc import get_message_feedback, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
feedback = get_message_feedback(pk=1)
print(feedback['generated_message'])
```

#### Create a feedback

```python
from rtv_workmate.sbcc import create_message_feedback, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
feedback = create_message_feedback({
    'form_guid': 'form-123',
    'user_guid': 'user-456',
    'practice': 'Handwashing',
    'barrier': 'Lack of soap',
    'generated_message': 'Remember to wash your hands with soap.',
    'is_liked': True,
    'preferred_message': 'Please wash hands before meals.',
    'test_mode': False  # Set to True to test without persisting
})
```

#### Update a feedback (full update)

```python
from rtv_workmate.sbcc import update_message_feedback, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
updated = update_message_feedback(
    pk=1,
    feedback_data={
        'form_guid': 'form-123',
        'user_guid': 'user-456',
        'practice': 'Handwashing',
        'barrier': 'Lack of soap',
        'generated_message': 'Updated message.',
        'is_liked': False,
        'preferred_message': 'Updated preferred message.'
    }
)
```

#### Partial update

```python
from rtv_workmate.sbcc import partial_update_message_feedback, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
updated = partial_update_message_feedback(
    pk=1,
    feedback_data={
        'is_liked': True,
        'preferred_message': 'New preferred message'
    }
)
```

#### Delete a feedback

```python
from rtv_workmate.sbcc import delete_message_feedback, set_config

set_config(base_url="http://localhost:8000", api_key="your_api_key")
delete_message_feedback(pk=1, test_mode=False)
```

#### Test Mode

All create/update/delete operations support test mode, which allows you to test requests without persisting data:

```python
# Test mode - data won't be persisted
create_message_feedback({
    'form_guid': 'form-123',
    'user_guid': 'user-456',
    'practice': 'Handwashing',
    'barrier': 'Lack of soap',
    'generated_message': 'Test message',
    'test_mode': True
})
```

### API Reference

#### Configuration

- `set_config(base_url, api_key=None, jwt_token=None)` - Set global API configuration

#### Message Feedback Functions

- `list_message_feedbacks(filters=None)` - List all feedbacks. `filters` dict can contain: `form_guid`, `user_guid`, `practice`, `barrier`, `is_liked`
- `get_message_feedback(pk)` - Get a specific feedback by ID
- `create_message_feedback(feedback_data)` - Create a new feedback. `feedback_data` dict requires: `form_guid`, `user_guid`, `practice`, `barrier`, `generated_message`. Optional: `is_liked`, `preferred_message`, `test_mode`
- `update_message_feedback(pk, feedback_data)` - Update all fields of a feedback (PUT). `feedback_data` dict requires: `form_guid`, `user_guid`, `practice`, `barrier`, `generated_message`, `is_liked`. Optional: `preferred_message`, `test_mode`
- `partial_update_message_feedback(pk, feedback_data)` - Partially update a feedback (PATCH). `feedback_data` dict can contain any fields to update. Optional: `test_mode`
- `delete_message_feedback(pk, test_mode=False)` - Delete a feedback

#### Exceptions

- `APIError` - Exception raised for API errors. Contains `message` and `status_code` attributes.

