Metadata-Version: 2.4
Name: feature_insights_iapi
Version: 0.4.0
Summary: IAPI Interface Files
Home-page: https://github.com/Cloudzero/feature-insights
Author: CloudZero
Author-email: support@cloudzero.com
License: UNLICENSED
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Description-Content-Type: text/markdown
Requires-Dist: cz-common-python>=0.10.22
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: requires-dist
Dynamic: summary


# Insights IAPI

This package contains the interface for the Insights iAPI. 

## Installing and Use
Add `feature_insights_iapi` to your requirements file or run `pip install feature_insights_iapi`. To use, add `from feature_insights_iapi import insights_client`.

## Insights Client


### Get

**Command**: `get_insight`

**Arguments**: 
- `cz_organization_id`: `str`
- `insight_id`: `str`

**Usage**: `insights_client.get_insight(cz_organization_id=1234568906, insight_id=2938547489534)`


### Create
**Command**: `create_insight`

**Arguments**:
- `cz_organization_id`: `str`
- `insight`: `dict` (*for most up to date `insight` structure, refer to* [CREATE_INSIGHT](https://github.com/Cloudzero/feature-insights/blob/develop/src/common/insights.py#L149-L158))
```python
{
    Required('status', default='new'): schema.VALID_STATUS,
    Optional('effort'): schema.VALID_EFFORT,
    Optional('cost_impact'): schema.CURRENCY,
    'description': str,
    'category': str,
    'title': str,
    Optional('link'): schema.CZ_LINK,
    Optional('source'): str
}
```
- `trusted_source`: `bool`, default `True`. Pass `False` when the insight comes from a user rather than a pipeline. The insight is then validated like one created in the UI: HTML is stripped from text fields, `type` is dropped, and `resources` or `resources_url` are rejected with a `BadRequestError`. To be deletable later with `delete_insight`, the insight must be created with `trusted_source=False`, no `source`, and a category other than `Cost Anomaly`.

**Request**: `insights_client.create_insight(cz_organization_id=<cz_organization_id>, insight=<insight>)`

**Response** (*for the most up to date response, refer to* [INSIGHT_RESPONSE](https://github.com/Cloudzero/feature-insights/blob/develop/src/common/insights.py#L23-L33])): 
```python
{
  'insight': {
      'id': str
      'status': schema.VALID_STATUS,
      Optional('effort'): schema.VALID_EFFORT,
      Optional('cost_impact'): schema.CURRENCY,
      'title': str,
      'description': str,
      'created': Number(),
      'last_updated': Number(),
      Optional('link'): Url(),
      Optional('source'): str
  }
}
```


### Update
**Command**: `update_insight`

**Arguments**:
- `cz_organization_id`: `str`
- `insight_id`: str
- `insight`: `dict` (*for most up to date `insight` structure, refer to* [INSIGHT_UPDATE_FIELDS](https://github.com/Cloudzero/feature-insights/blob/develop/src/common/insights.py#L125-L134))
```python
{
    'status': schema.VALID_STATUS,
    'effort': schema.VALID_EFFORT,
    'cost_impact': schema.CURRENCY,
    'category': str,
    'title': str,
    'description': str,
    'link': schema.CZ_LINK,
    'source': str
}
```

`update_insight` does not take `trusted_source`. Trust comes from the stored insight: insights that `delete_insight` treats as user-created are updated like the UI does (HTML stripped, `resources` and `resources_url` rejected), so an update cannot mark them trusted. Setting `source`, or setting `category` to `Cost Anomaly`, still makes them undeletable. All other insights, such as anomalies and Trusted Advisor insights, are updated as trusted.

**Request**: `insights_client.update_insight(cz_organization_id=<cz_organization_id>, insight_id=<insight_id>, insight=<insight>)`

**Response** (*for the most up to date response, refer to* [INSIGHT_RESPONSE](https://github.com/Cloudzero/feature-insights/blob/develop/src/common/insights.py#L23-L33])): 
```python
{
  'insight': {
      'id': str
      'status': schema.VALID_STATUS,
      Optional('effort'): schema.VALID_EFFORT,
      Optional('cost_impact'): schema.CURRENCY,
      'title': str,
      'description': str,
      'created': Number(),
      'last_updated': Number(),
      Optional('link'): Url(),
      Optional('source'): str
  }
}
```


### Delete
**Command**: `delete_insight`

Deletes an insight that a user created manually, along with its comments. Deleted records expire after 90 days and there is no restore API.

An insight counts as user-created when it has no `type`, no `source`, is not in the `Cost Anomaly` category, and was not created with `trusted_source=True`. Anything else, such as anomalies, recommendations and Trusted Advisor insights, is rejected with a `BadRequestError`. An unknown insight ID raises a `NotFoundError`.

**Arguments**:
- `cz_organization_id`: `str`
- `insight_id`: `str`

**Request**: `insights_client.delete_insight(cz_organization_id=<cz_organization_id>, insight_id=<insight_id>)`

**Response** (`resources` is always an empty list):
```python
{
  'insight': {'id': str},
  'comments': [{'id': str}],
  'resources': []
}
```

## Configuration Client

### Create Insight Configuration

**Command**: `create_insight_configuration`

**Arguments**:
- `cz_organization_id`: `str`
- `feature_name`: `str`
- `resource_dataset_name`: `str`
- `insight_type`: `str`

**Optional Arguments**:

- `insight_title`: `str`
- `insight_description`: `str`
- `link`: `dict`
- `data_table_name`: `str`
- `data_table_columns`: `dict`
- `data_table_columns_mode`: `str`
- `total_cost_impact_calculation`: `str`
- `signal_threshold`: `int`
- `use_element_cost_impact_column`: `bool`

**Request**: 
```python
configuration_client.create_insight_configuration(
    cz_organization_id='test_org_id',
    feature_name='test_feature_name',
    resource_dataset_name='test_resource_dataset',
    insight_title='test_insight_title',
    insight_type='test_insight_type',
    insight_description='test_insight_description',
    link={
        'partition': 'test_partition',
        'filters': {'test_filter': ['test_value']},
        'granularity': 'daily',
    },
    data_table_name='test_data_table',
    data_table_columns={'test_column_1': {'name': 'test_column_1', 'type': 'test_type', 'sortable': True}, 'test_column_2': {'name': 'test_column_2', 'type': 'test_type', 'json_path': 'test_json_path', 'sortable': True}},
    data_table_columns_mode='append',
    total_cost_impact_calculation='test_total_cost_impact_calculation',
    signal_threshold=100,
    use_element_cost_impact_column=True
)
```

**Response**: A dictionary containing the insight configuration and the configuration of the underlying datasets.
