# exobrain-actions-client

[![License: Private](https://img.shields.io/badge/license-private-red)](LICENSE.md)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/release/python-3120/)

This package provides a REST API client for interacting with the Exobrain Actions API.

Key features:

- Access to various API resources such as version status and health checks (ping).
- Retrieval, triggering, or updating of action data specific to a service or organization.
- Standardized HTTP calls to different API endpoints (version, health, action data, calculation triggers, KPI updates).


## User Guide

### Installation

To install the Exobrain Actions Client, use the following command:

```shell
pip install exobrain-actions-client
```

### Usage

To update the actual KPIs of a given action, create a client, instantiate the accessor, and call `update_actuals`
with the service name, organization ID, action ID, and a dictionary of KPI values.

```python
from uuid import UUID

from exobrain.actions.client.accessor import ActionsAccessor
from exobrain.actions.client.http_client import ClientType, create_client
from exobrain.actions.client.http_client.interfaces import HTTPStatusError

org_id = UUID("12345678-1234-5678-1234-567812345678")
action_id = UUID("87654321-4321-8765-4321-876543218765")
kpis = {
    "RESPONSIVENESS": 0.87,
    "RELIABILITY": 0.75,
    "INVENTORY_COVERAGE": 0.37,
    "INVENTORY_VALUE": 0.314
}

base_url = "https://actions-service.com/"
service = "stock-rebalancing"

client = create_client(
    ClientType.REQUESTS,
    base_url=base_url,
    verify=True,  # Set to False if you want to disable SSL verification
    timeout=10,
)
accessor = ActionsAccessor(client)
try:
    accessor.update_actuals(service, org_id, action_id, kpis=kpis)
except HTTPStatusError as e:
    print(f"Failed to update KPIs: {e.response.status_code} - {e}")
else:
    print("KPIs updated successfully!")
```

## Development workflow

### Prerequisites

Before starting development, make sure you have the following tools installed:

- **[Hatch](https://hatch.pypa.io/)**: a modern Python project, environment, and packaging manager.

- **[uv](https://github.com/astral-sh/uv)**: a fast Python package installer and resolver.

### Project Structure

- **Code:** Place your models in `exobrain/actions/client/`.
- **Tests:** Add your tests in `tests/`.

### Development Commands

All tasks (testing, linting, type checking, packaging, etc.) are managed via **hatch** environments and scripts:

#### 1. Installing Dependencies

Install all dependencies (including development tools):

```shell
hatch env create
```

#### 2. Running Tests

Launch all tests using `pytest`:

```shell
hatch test
```

#### 3. Linting and Formatting

Format your code:

```shell
hatch fmt -f
```

Check code style:

```shell
hatch fmt
```

#### 4. Type Checking

Run type checks with `mypy`:

```shell
hatch run types:check
```

#### 5. Coverage

Check test coverage with:

```shell
hatch test --cover
```

#### 6. Building the Package

Build the package for distribution:

```shell
hatch build
```

#### 7. Releasing

The release process uses **uv** and Github Actions.

- For pre-release on TestPyPI: push a tag with `rc` or `beta` in the version (`0.1rc1`, `0.2b1` etc.).
- For release: push a tag type `v0.1` (main release) on `main` branch.
- Configure secrets for PyPI tokens in repository settings (`PYPI_TOKEN`, `TEST_PYPI_TOKEN`).

### Continuous Integration

All pushes and pull requests on `main` or `development` branches trigger the Continuous Integration pipeline  
(see `.github/workflows/` directory for details).

---

## License

This project is private and confidential.