Metadata-Version: 2.3
Name: fast-abtest
Version: 0.4.2
Summary: A fast and lightweight A/B testing library for Python.
License: MIT
Keywords: ab-testing,statistics,experiments,monitoring
Author: Evgenii Eliseev
Author-email: evgeniieliseeve@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Provides-Extra: fastapi
Provides-Extra: prometheus
Requires-Dist: fastapi (>=0.115.12) ; extra == "fastapi"
Requires-Dist: prometheus-client (>=0.22.1) ; extra == "prometheus"
Requires-Dist: pydantic (>=2.11.7,<3.0.0)
Project-URL: Documentation, https://github.com/Gifourm/fast-abtest#readme
Project-URL: Homepage, https://github.com/Gifourm/fast-abtest
Project-URL: Repository, https://github.com/Gifourm/fast-abtest
Description-Content-Type: text/markdown

# Fast ABTest

[![PyPI version](https://badge.fury.io/py/fast-abtest.svg)](https://badge.fury.io/py/fast-abtest)
[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)

A lightweight Python decorator for implementing A/B testing with automatic traffic distribution and built-in metrics monitoring. Compatible with FastAPI and works with both synchronous and asynchronous functions.

## Installation

```bash
pip install fast-abtest
```

## Quick Start

### Basic Usage

```python
from fast_abtest import ab_test, Metric

@ab_test(metrics=[Metric.LATENCY, Metric.ERRORS_TOTAL])
def recommendation_service(user_id: int) -> list[str]:
    # Main variant (A) - receives remaining traffic percentage
    return ["item1", "item2"]

@recommendation_service.register_variant(traffic_percent=30, disable_threshold=0.2)
def recommendation_service_b(user_id: int) -> list[str]:
    # Variant B - gets 30% of the traffic. If the error rate exceeds 0.2, traffic redirection will stop.
    return ["item3", "item4"]
```

### FastAPI Integration

```python
from fastapi import FastAPI, Depends
from fast_abtest import ab_test

app = FastAPI()

@app.get("/recommendations")
@ab_test(metrics=[])
async def get_recommendations(user_id: int):
    return {"items": ["A1", "A2"]}

@get_recommendations.register_variant(traffic_percent=30)
async def get_recommendations_b(user_id: int):
    return {"items": ["B1", "B2"]}
```

**Important**: For FastAPI, the route decorator (`@app.get`) must come **before** `@ab_test`.

### Consistent distribution

```python
from fastapi import FastAPI, Depends
from fast_abtest import ab_test

app = FastAPI()

@app.get("/recommendations")
@ab_test(metrics=[], consistency_key='user_id')
async def get_recommendations(user_id: int):
    return {"items": ["A1", "A2"]}

@get_recommendations.register_variant(traffic_percent=30)
async def get_recommendations_b(user_id: int):
    return {"items": ["B1", "B2"]}
```

