Metadata-Version: 2.4
Name: tkv
Version: 0.1.1
Summary: Temporal Key Value Store 
Requires-Python: >=3.12
Requires-Dist: fastapi==0.116.1
Requires-Dist: redislite==6.2.912183
Requires-Dist: rocksdict==0.3.27
Requires-Dist: sqlalchemy==2.0.41
Requires-Dist: typer==0.16.0
Requires-Dist: uvicorn==0.35.0
Description-Content-Type: text/markdown

# TKV - Temporal Key-Value Store

A key-value store that supports timestamp-based queries, allowing you to retrieve values as they existed at specific points in time.

## Features

- **Temporal queries**: Get the value for a key at the largest timestamp less than or equal to your query timestamp
- **Multiple backends**: SQLite as default, Redis and RocksDB as experimental alternatives
- **REST API**: FastAPI-based web interface
- **CLI interface**: Command-line tools for direct interaction

## Project Layout

```console
src/
├── service.py      # Core backend store implementations
├── api.py          # FastAPI web server
└── cli.py          # Command-line interface
```

The primary interest is `service.py`, which contains the main backend store implementation using SQLAlchemy/SQLite, as well as experimental alternatives using Redis and RocksDB. The CLI and API are implemented separately as distinct interfaces to the core functionality.

## Installation

### From PyPI (Recommended)

```bash
pip install tkv
```

### Development with uv

First install uv:

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Then clone and install:

```bash
git clone JackIsMyShephard/tkv.git
cd tkv
uv sync
```

## Usage

### CLI

```bash
# Store a value
tkv put mykey myvalue 1000

# Retrieve a value
tkv get mykey 1500
```

### Web API

Start the server:

```bash
tkv-web run
```

Store data:

```bash
curl -X PUT http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{"key":"mykey","value":"myvalue","timestamp":1000}'
```

Retrieve data:

```bash
curl "http://localhost:8000/mykey?timestamp=1500"
```

## Development

```bash
uv sync --group dev
uv run pytest
```
