Metadata-Version: 2.4
Name: airstat
Version: 1.0.0
Summary: CLI for AirMettle's Airstat service on Azure
Project-URL: Homepage, https://airmettle.com/airstat
Author-email: AirMettle <support@airmettle.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: msal>=1.28.0
Requires-Dist: pydantic>=2.11.7
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: requests>=2.32.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# AirStat CLI

Command-line tool for AirMettle's AirStat service on Azure.
Generate AirTree histograms and run queries against data stored in your own Azure Blob Storage.

## Installation

```bash
pip install airstat
```

## Quick Start

1. Authenticate once with your Microsoft account (organizational or personal).
2. Create two small JSON configuration files.
3. Run the generate command.

## 1. Authenticate

```bash
airstat auth login
```

This starts a device-code flow. Follow the instructions in your terminal (you'll be asked to open a browser and enter a short code). Your token is cached locally so you only need to do this occasionally.

Other useful auth commands:

```bash
airstat auth status     # Show who you're logged in as
airstat auth logout     # Clear cached credentials
```

## 2. Create Configuration Files

You need two files:

profile.json – Your storage account and target service

```json
{
  "bucket_props": {
    "account_name": "yourstorageaccount",
    "account_key": "YOUR_STORAGE_ACCOUNT_KEY",
    "container": "your-container",
    "object": "your-input-file.bin"
  }
}
```

• bucket_props: Location of your input data in Azure Blob Storage.
• airstat_url (optional): The CLI talks to AirMettle's AirStat service by default. Set this only to target a different AirStat deployment.

airstat.json – The AirTree request you want to run

```json
{
  "airtree": {
    "config": "1DxT",
    "schema": {
      "id": "binary",
      "dtype": "double"
    }
  }
}
```

See the samples/ directory in the source repository for more complete examples (including 2D/3D/4D configs).

## 3. Run a Generate Operation

```bash
airstat generate -p profile.json -a airstat.json
```

The CLI will:
- Use your cached Microsoft token
- Send the request to the configured Airstat service (protected by Azure Easy Auth)
- Return the result

## How Authentication Works

The CLI uses Microsoft Authentication Library (MSAL) with the device code flow.
You authenticate interactively once. The resulting access token is sent as a Bearer token to the Airstat service.

No secrets are required on your machine beyond the one-time interactive login.

### Configuration Files

---------------------------------------------------------------------------------
| File         | Purpose                                      | Required for    |
|---------------|---------------------------------------------|-----------------|
| profile.json | Storage account + optional Airstat URL       | All commands    |
| airstat.json | The actual AirTree request (config + schema) | generate, query |


## Examples

The `samples/` folder contains ready-to-use `airstat.json` request bodies. Each file holds only the `airtree` payload — pair it with your own `profile.json` (storage account, plus optional service URL override) via `-p` and `-a`.

### Generate (`/api/v1/generate`)

| Sample file | Config | Input schema | Notes |
|-------------|--------|--------------|-------|
| `airstat.json` | 1DxT | binary (`double`) | Minimal 1D example |
| `1DxT_generate.json` | 1DxT | binary (`double`) | 13-bit, most compact |
| `1DxF_generate.json` | 1DxF | binary (`double`) | 16-bit, fastest |
| `1DxP_generate.json` | 1DxP | binary (`double`) | 20-bit, highest precision |
| `2DxP_generate.json` | 2DxP | Parquet (`PAR1`) | 2 columns |
| `2DxF_generate.json` | 2DxF | Parquet (`PAR1`) | 2 columns |
| `3DxP_generate.json` | 3DxP | Parquet (`PAR1`) | 3 columns |
| `3DxF_generate.json` | 3DxF | Parquet (`PAR1`) | 3 columns |
| `4DxP_generate.json` | 4DxP | Parquet (`PAR1`) | 4 columns |
| `4DxF_generate.json` | 4DxF | Parquet (`PAR1`) | 4 columns |
| `4DxPc_generate.json` | 4DxPc | Parquet (`PAR1`) | 4 columns |

1D configs require a raw binary blob; set `bucket_props.object` in `profile.json` to your `.bin` file. Supported binary dtypes: `double`, `float`, `int32`, `int64`.

2D–4D configs require a Parquet file; set `dimInfo.colName` to match your column names.

```bash
airstat generate -p profile.json -a samples/1DxT_generate.json
airstat generate -p profile.json -a samples/2DxP_generate.json
```

### Query (`/api/v1/query`)

Query samples target an existing histogram in blob storage (the output of a prior generate). Point `bucket_props.object` in `profile.json` at that `.airtree` file.

| Sample file | Query type | Typical histogram |
|-------------|------------|-------------------|
| `minvalue_query.json` | `minvalue` | 1D |
| `maxvalue_query.json` | `maxvalue` | 1D |
| `mincount_query.json` | `mincount` | 1D |
| `maxcount_query.json` | `maxcount` | 1D |
| `topk_query.json` | `topk` | 1D |
| `percentile_query.json` | `percentile` | 1D |
| `cdf_query.json` | `cdf` | 1D |
| `box_query.json` | `box` | 2D |
| `grid_query.json` | `grid` | 2D |

```bash
airstat query -p profile.json -a samples/minvalue_query.json 
airstat query -p profile.json -a samples/grid_query.json
```

## Notes

- The package is built with the required Entra client ID pre-bundled. You do not need to set any environment variables.
- All network calls to the Airstat service are authenticated with your Microsoft identity.

## License

MIT — see the LICENSE file. Use of the AirStat services themselves is
governed by your service agreement (e.g., via the Microsoft commercial
marketplace).
