typosaurus-sandbox/README.md

# retoor <retoor@molodetz.nl>

# typosaurus-sandbox

Sandbox for Typosaurus end-to-end verification.

A FastAPI application serving arithmetic operations over HTTP with JSON request/response bodies.

## Configuration

The application uses a single `.env.json` file at the project root as its central point of truth
for configuration. Defaults are plug-and-play and require no setup:

```json
{
    "host": "127.0.0.1",
    "port": 8000
}
```

When no `.env.json` is present, the application starts with these defaults. To customise, create
`.env.json` in the project root and populate only the keys that differ.

## Usage

### Start the server

```sh
python -m typosaurus_sandbox
```

The server listens on `http://127.0.0.1:8000` by default.

### Health check

```
GET /health
```

Response:

```json
{"status": "ok"}
```

## API endpoints

All calculator endpoints accept `POST` requests with a JSON body and return a JSON response.

### POST /api/v1/calculator/add

Add two integers.

Request:

```json
{"left": 3, "right": 5}
```

Response:

```json
{"result": 8}
```

### POST /api/v1/calculator/subtract

Subtract the right integer from the left.

Request:

```json
{"left": 10, "right": 3}
```

Response:

```json
{"result": 7}
```

### POST /api/v1/calculator/clamp

Clamp a value between a low and high bound.

Request:

```json
{"value": 15, "low": 0, "high": 10}
```

Response:

```json
{"result": 10}
```

Boundaries are inclusive. A `low > high` combination produces a 422 validation response.

### POST /api/v1/calculator/clamp-to-byte

Clamp an integer to the byte range [0, 255].

Request:

```json
{"value": 300}
```

Response:

```json
{"result": 255}
```

### POST /api/v1/calculator/average

Compute the arithmetic mean of a list of values.

Request:

```json
{"values": [1, 2, 3, 4, 5]}
```

Response:

```json
{"result": 3.0}
```

An empty list produces a 422 validation response.

### POST /api/v1/calculator/median

Compute the median of a list of values. Values are sorted internally; an even-length list returns the average of the two middle values as a float.

Request:

```json
{"values": [1, 3, 5]}
```

Response:

```json
{"result": 3.0}
```

Request (even length):

```json
{"values": [1, 2, 3, 4]}
```

Response:

```json
{"result": 2.5}
```

An empty list produces a 422 validation response.

### POST /api/v1/calculator/variance

Compute the population variance of a list of values.

Request:

```json
{"values": [1, 2, 3, 4, 5]}
```

Response:

```json
{"result": 2.0}
```

An empty list produces a 422 validation response.

### POST /api/v1/calculator/percentage

Compute what percentage `value` is of `total`.

Request:

```json
{"value": 50, "total": 100}
```

Response:

```json
{"result": 50.0}
```

A zero `total` produces a 422 validation response.

## Verification

```sh
make verify
```

Runs compile-all checks against all source and test files, then executes the full test suite.
Zero warnings are tolerated.