Metadata-Version: 2.4
Name: kelvin-app-storage
Version: 0.0.1
Summary: Library for storing and retrieving state of Kelvin applications.
Author-email: Kelvin Inc <engineering@kelvininc.com>
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: pyyaml==6.0.3
Requires-Dist: redis[hiredis]==7.1.0
Requires-Dist: structlog==25.5.0

# kelvin-app-storage

Redis-backed library for storing and retrieving state of Kelvin applications. Keys are automatically prefixed with the application name and version derived from `app.yaml`.

## Prerequisites

A running Redis instance is required. For local development:

```bash
docker run -d --name redis -p 6379:6379 redis
```

## Installation

```bash
uv sync
```

## Usage

```python
from kelvin_app_storage.client import StorageClient

client = StorageClient()

client.set("sensor_id", "abc-123")
client.get("sensor_id")       # "abc-123"
client.list_keys()             # ["myapp_1.0_sensor_id"]
```

To disable automatic key prefixing:

```python
client = StorageClient(no_prefix=True)
```

## Configuration

| Environment Variable | Default | Description |
|---|---|---|
| `KELVIN_APP_STORAGE_HOST` | `kelvin-app-storage.app` | Redis host |
| `KELVIN_APP_STORAGE_PORT` | `6379` | Redis port |
| `KELVIN_APP_STORAGE_PREFIX` | Derived from `app.yaml` | Custom key prefix |
| `KELVIN_APP_STORAGE_LOG_LEVEL` | `INFO` | Log level (`DEBUG` or `INFO`) |

## app.yaml

The key prefix is derived from `app.yaml` in the working directory. Expected format:

```yaml
info:
  name: myapp
  version: "1.0"
```

This produces the prefix `myapp_1.0`. If `app.yaml` is missing or unreadable, a random UUID is used as fallback.

## Supported Value Types

`str`, `int`, `float`, `bool`, `list`, `dict` — complex types are serialized as JSON.

## Running Tests

```bash
make test
```

Or directly with pytest:

```bash
uv run pytest tests/ -v
```
