CLASP

Installation

Install globally

npm install -g clasp-ai

Via Docker

```bash

Run with Docker (from GitHub Container Registry)

docker run -d -p 8080:8080 \ -e OPENAI_API_KEY=sk-... \ ghcr.io/jedarden/clasp:latest

Or with docker-compose

docker-compose up -d ```

Available Docker tags: - latest - Latest stable release - 0.24 - Latest 0.24.x release - 0.24.8 - Specific version

Docker

Build and Run

```bash

Build Docker image

make docker

Docker Compose

Create a .env file with your configuration:

PROVIDER=openai
OPENAI_API_KEY=sk-...
CLASP_DEFAULT_MODEL=gpt-4o

Then start the service:

docker-compose up -d

Docker Environment Variables

All configuration is done through environment variables. See the Environment Variables section above.

Build

make build

Build for all platforms

make build-all

Build Docker image

make docker

Quick Start

Example Usage

Configuration

CLASP supports three configuration methods, with the following precedence (highest to lowest): 1. Command-line flags - Override all other settings 2. Environment variables - Override config file settings 3. Configuration file - YAML-based configuration 4. Default values - Built-in defaults

Configuration File

CLASP can load configuration from a YAML file, which is cleaner for complex setups and version control friendly.

Configuration file locations (searched in order): 1. ./clasp.yaml or ./clasp.yml - Current directory 2. ~/.clasp/config.yaml - User config directory 3. ~/.config/clasp/config.yaml - XDG config directory 4. /etc/clasp/config.yaml - System-wide config 5. Custom path via CLASP_CONFIG_FILE environment variable

Example configuration file (clasp.yaml):

```yaml

API Keys (supports ${VAR} syntax for environment variables)

api_keys: openai: ${OPENAI_API_KEY} # azure: ${AZURE_API_KEY} # openrouter: ${OPENROUTER_API_KEY}

Custom endpoints (optional)

endpoints: openai: https://api.openai.com/v1 ollama: http://localhost:11434

Model configuration

models: default: gpt-4o opus: gpt-4o # Maps claude-opus- to gpt-4o sonnet: gpt-4o-mini # Maps claude-sonnet- to gpt-4o-mini haiku: gpt-4o-mini # Maps claude-haiku-* to gpt-4o-mini

Server settings

server: port: 8080 log_level: info

Command Line Options

clasp [options]

Options:
  -port <port>           Port to listen on (default: 8080)
  -provider <name>       LLM provider: openai, azure, openrouter, custom
  -model <model>         Default model to use for all requests
  -debug                 Enable debug logging (full request/response)
  -rate-limit            Enable rate limiting
  -cache                 Enable response caching
  -cache-max-size <n>    Maximum cache entries (default: 1000)
  -cache-ttl <n>         Cache TTL in seconds (default: 3600)
  -multi-provider        Enable multi-provider tier routing
  -fallback              Enable fallback routing for auto-failover
  -auth                  Enable API key authentication
  -auth-api-key <key>    API key for authentication (required with -auth)
  -version               Show version information
  -help                  Show help message

Environment Variables

Custom cache settings

clasp -cache -cache-max-size 500 -cache-ttl 1800

Via environment

CLASP_CACHE=true CLASP_CACHE_MAX_SIZE=500 clasp ```

Caching behavior: - Only non-streaming requests are cached - Requests with temperature > 0 are not cached (non-deterministic) - Cache uses LRU (Least Recently Used) eviction when full - Cache entries expire after TTL (time-to-live) - Response headers include X-CLASP-Cache: HIT or X-CLASP-Cache: MISS

Via environment variable

CLASP_DEBUG=true clasp

Or via environment variables

CLASP_AUTH=true CLASP_AUTH_API_KEY="my-secret-key" clasp ```

Authentication Options

Custom queue settings

clasp -queue -queue-max-size 200 -queue-max-wait 60

Via environment

CLASP_QUEUE=true CLASP_QUEUE_MAX_SIZE=200 clasp ```

Queue Options

Custom circuit breaker settings

clasp -circuit-breaker -cb-threshold 10 -cb-recovery 3 -cb-timeout 60

Via environment

CLASP_CIRCUIT_BREAKER=true clasp ```

Circuit Breaker Options

Maximum Resilience Configuration

For production deployments requiring maximum resilience:

```bash

Set your API key

export OPENAI_API_KEY=sk-...

API Endpoints

Via CLI flag

clasp -debug

Enable authentication with CLI flags

clasp -auth -auth-api-key "my-secret-key"

Providing the API Key

Clients can provide the API key in two ways:

```bash

Via x-api-key header

curl http://localhost:8080/v1/messages \ -H "x-api-key: my-secret-key" \ -H "Content-Type: application/json" \ -d '{"model": "claude-3-5-sonnet-20241022", ...}'

Endpoint Access with Authentication Enabled