Skip to content

docs: make ReliAPI beta claims verifiable #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kiku-jw merged 1 commit into from
Jul 23, 2026
Merged

docs: make ReliAPI beta claims verifiable #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 42 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,28 @@
# ReliAPI

Reliability layer for API calls: retries, caching, dedup, circuit breakers.
Beta self-hosted proxy for HTTP and LLM calls with Redis-backed caching,
non-streaming LLM idempotency, and configurable LLM budget guardrails.

[![npm version](https://badge.fury.io/js/reliapi-sdk.svg)](https://www.npmjs.com/package/reliapi-sdk)
[![PyPI version](https://badge.fury.io/py/reliapi-sdk.svg)](https://pypi.org/project/reliapi-sdk/)
[![Docker](https://img.shields.io/docker/v/kikudoc/reliapi?label=docker)](https://hub.docker.com/r/kikudoc/reliapi)

**[Open the project site](https://kikuai-lab.github.io/reliapi/)**

> [!IMPORTANT]
> ReliAPI is beta software for evaluation and self-hosting. It does not provide
> an SLA, managed multi-upstream fallback, exactly-once delivery, quantified
> savings, or published performance targets.

## Features

- **Retries with Backoff** - Automatic retries with exponential backoff
- **Circuit Breaker** - Prevent cascading failures
- **Caching** - TTL cache for GET requests and LLM responses
- **Idempotency** - Request coalescing with idempotency keys
- **Rate Limiting** - Built-in rate limiting per tier
- **LLM Proxy** - Unified interface for OpenAI, Anthropic, Mistral
- **Cost Control** - Budget caps and cost estimation
- **Self-Service Onboarding** - Automated API key generation
- **Paddle Payments** - Subscription management
- **Caching** - TTL cache for HTTP GET/HEAD and non-streaming LLM responses
- **Idempotency** - Redis-backed primitives used by the non-streaming LLM path
- **LLM Proxy** - Configured OpenAI, Anthropic, and Mistral targets
- **Budget Guardrails** - Pre-request estimates with hard and soft caps
- **Rate Limiting** - Built-in request limits per configured tier
- **Experimental Resilience** - Retry and circuit-breaker code remains under
beta review and is not part of the documented reliability baseline

## Project Structure

Expand Down Expand Up @@ -50,10 +54,14 @@ Try ReliAPI directly on [RapidAPI](https://rapidapi.com/kikuai-lab-kikuai-lab-de
### Self-Hosting with Docker

```bash
docker run -d -p 8000:8000 \
-e REDIS_URL="redis://localhost:6379/0" \
-e RELIAPI_CONFIG_PATH=/app/config.yaml \
kikudoc/reliapi:latest
git clone https://github.com/KikuAI-Lab/reliapi.git
cd reliapi
cp .env.example .env

# Add the provider key(s) referenced by config.yaml to .env, then start
# ReliAPI and its Redis service.
docker compose up -d --build
curl http://localhost:8000/healthz
```

### Local Development
Expand Down Expand Up @@ -109,8 +117,8 @@ targets:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/proxy/http` | POST | Proxy any HTTP API with reliability |
| `/proxy/llm` | POST | Proxy LLM requests with cost control |
| `/v1/proxy/http` | POST | Proxy a request to a configured HTTP target |
| `/v1/proxy/llm` | POST | Proxy a request to a configured LLM target |
| `/healthz` | GET | Health check |
| `/metrics` | GET | Prometheus metrics |

Expand Down Expand Up @@ -160,7 +168,7 @@ PADDLE_ENVIRONMENT=sandbox
from reliapi_sdk import ReliAPI

client = ReliAPI(
base_url="https://reliapi.kikuai.dev",
base_url="http://localhost:8000",
api_key="your-api-key"
)

Expand All @@ -187,7 +195,7 @@ llm_response = client.proxy_llm(
import { ReliAPI } from 'reliapi-sdk';

const client = new ReliAPI({
baseUrl: 'https://reliapi.kikuai.dev',
baseUrl: 'http://localhost:8000',
apiKey: 'your-api-key'
});

Expand All @@ -198,6 +206,20 @@ const response = await client.proxyLlm({
});
```

## Beta Limitations

- Redis must be reachable for shared cache and idempotency behavior.
- HTTP response caching applies to GET and HEAD; LLM caching applies to the
non-streaming path.
- The documented idempotency baseline covers non-streaming LLM calls. HTTP
idempotency and streaming behavior remain under beta review.
- Idempotency is not a promise of exactly-once upstream execution or provider
billing behavior.
- Budget caps use pre-request estimates, not authoritative invoices or
account-wide spending limits.
- Deployment security, target allow-lists, Redis durability, observability, and
provider quotas remain the self-hosting operator's responsibility.

## Testing

```bash
Expand All @@ -222,7 +244,8 @@ See [`docs/release.md`](./docs/release.md) and [`docs/SECRETS_SETUP.md`](./docs/

- [OpenAPI Spec](./openapi/openapi.yaml)
- [Postman Collection](./postman/collection.json)
- [Live Docs](https://reliapi.kikuai.dev/docs)
- [Project Site](https://kikuai-lab.github.io/reliapi/)
- [Wiki](https://github.com/KikuAI-Lab/reliapi/wiki)

## Support

Expand Down
Loading