### Start the DeltaLLM Admin UI

Source: https://github.com/deltawi/deltallm/blob/main/docs/getting-started/installation.md

Navigate to the UI directory and run these commands to install dependencies and start the development server for the admin UI. It proxies requests to the backend API.

```bash
cd ui
npm ci
npm run dev
```

--------------------------------

### Run Docker Compose (High Availability)

Source: https://github.com/deltawi/deltallm/blob/main/ui/README.md

Starts a high-availability setup of the DeltaLLM backend and UI using Docker Compose.

```bash
docker compose --profile ha up -d
```

--------------------------------

### Start UI Development Server

Source: https://github.com/deltawi/deltallm/blob/main/CONTRIBUTING.md

Navigate to the UI directory and start the development server using npm.

```bash
cd ui
npm run dev
```

--------------------------------

### Start DeltaLLM with Docker Compose

Source: https://github.com/deltawi/deltallm/blob/main/README.md

Start the DeltaLLM service using Docker Compose. Use the --profile single flag for a basic setup. For guardrails, set the INSTALL_PRESIDIO environment variable.

```bash
docker compose --profile single up -d --build
```

```bash
INSTALL_PRESIDIO=true docker compose --profile single up -d --build
```

--------------------------------

### Copy Example Configuration File

Source: https://github.com/deltawi/deltallm/blob/main/docs/configuration/index.md

Command to copy the example configuration file to be used as the main config file.

```bash
cp config.example.yaml config.yaml
```

--------------------------------

### Install Backend Dependencies with pip

Source: https://github.com/deltawi/deltallm/blob/main/docs/getting-started/installation.md

Install backend dependencies using pip. This involves creating a virtual environment and installing from requirements.txt.

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

--------------------------------

### Copy Example Config and Set Path

Source: https://github.com/deltawi/deltallm/blob/main/docs/getting-started/installation.md

Copy the example configuration file and set the DELTALLM_CONFIG_PATH environment variable to point to it. This is the first step in setting up your local configuration.

```bash
cp config.example.yaml config.yaml
export DELTALLM_CONFIG_PATH=./config.yaml
```

--------------------------------

### Initialize MCP Gateway

Source: https://github.com/deltawi/deltallm/blob/main/docs/api/mcp.md

Use the 'initialize' method to get DeltaLLM's MCP gateway capabilities. This is a basic setup step.

```bash
curl http://localhost:8000/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/deltawi/deltallm/blob/main/CONTRIBUTING.md

Install all necessary Python development dependencies using uv.

```bash
uv sync --dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/deltawi/deltallm/blob/main/ui/README.md

Installs the necessary project dependencies using npm.

```bash
npm install
```

--------------------------------

### Install UI Dependencies

Source: https://github.com/deltawi/deltallm/blob/main/CONTRIBUTING.md

Install Node.js dependencies for the UI component.

```bash
cd ui
npm ci
cd ..
```

--------------------------------

### Alert Configuration Example

Source: https://github.com/deltawi/deltallm/blob/main/docs/internal/master-prd-outline.md

Example YAML configuration for setting up alerting thresholds, types, and arguments for various notifications like budget alerts and daily reports.

```yaml
general_settings:
  alerting: ["slack", "email", "webhook"]
  alerting_threshold: 80          # percentage of budget
  alert_types:
    - budget_alerts
    - daily_reports
    - llm_exceptions
    - llm_too_slow
    - cooldown_deployment
    - outage_alerts
    - db_exceptions
  alerting_args:
    slack_webhook_url: "https://hooks.slack.com/..."
    daily_report_frequency: 43200
    budget_alert_ttl: 86400
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/deltawi/deltallm/blob/main/README.md

Installs development dependencies using uv. Use the --extra flag to include guardrails-presidio if needed.

```bash
uv sync --dev
```

```bash
uv sync --dev --extra guardrails-presidio
```

--------------------------------

### Quick-start Install with Bundled PostgreSQL and Redis

Source: https://github.com/deltawi/deltallm/blob/main/README.md

Install DeltaLLM using the Helm chart with bundled PostgreSQL and Redis. This command sets up the necessary secrets and admin credentials.

```bash
helm install deltallm deltallm/deltallm \
  --version <chart-version> \
  --namespace deltallm \
  --create-namespace \
  -f https://deltawi.github.io/deltallm/values-eval-<chart-version>.yaml \
  --set secret.values.masterKey="$DELTALLM_MASTER_KEY" \
  --set secret.values.saltKey="$DELTALLM_SALT_KEY" \
  --set-string env[0].name=PLATFORM_BOOTSTRAP_ADMIN_EMAIL \
  --set-string env[0].value=admin@example.com \
  --set-string env[1].name=PLATFORM_BOOTSTRAP_ADMIN_PASSWORD \
  --set-string env[1].value='ChangeMe123!'
```

--------------------------------

### Provider Configuration Examples

Source: https://github.com/deltawi/deltallm/blob/main/docs/internal/master-prd-outline.md

Configuration examples for various providers including OpenAI, Azure OpenAI, and Anthropic. Specifies model names and LiteLLM parameters for API routing and key management.

```yaml
model_list:
  - model_name: gpt-4
    litellm_params:
      model: openai/gpt-4
      api_key: os.environ/OPENAI_API_KEY
  - model_name: gpt-4
    litellm_params:
      model: azure/gpt-4-deployment
      api_base: https://my-azure.openai.azure.com/
      api_key: os.environ/AZURE_API_KEY
      api_version: "2024-02-15-preview"
  - model_name: claude-3
    litellm_params:
      model: anthropic/claude-3-sonnet-20240229
      api_key: os.environ/ANTHROPIC_API_KEY
```

--------------------------------

### Install Presidio-enabled Variant

Source: https://github.com/deltawi/deltallm/blob/main/README.md

Install the Presidio-enabled variant of DeltaLLM using the Helm chart. This command is similar to the quick-start install but specifies the Presidio image tag.

```bash
helm install deltallm deltallm/deltallm \
  --version <chart-version> \
  --namespace deltallm \
  --create-namespace \
  -f https://deltawi.github.io/deltallm/values-eval-<chart-version>.yaml \
  --set secret.values.masterKey="$DELTALLM_MASTER_KEY" \
  --set secret.values.saltKey="$DELTALLM_SALT_KEY" \
  --set-string env[0].name=PLATFORM_BOOTSTRAP_ADMIN_EMAIL \
  --set-string env[0].value=admin@example.com \
  --set-string env[1].name=PLATFORM_BOOTSTRAP_ADMIN_PASSWORD \
  --set-string env[1].value='ChangeMe123!' \
  --set image.tag=v<chart-version>-presidio
```

--------------------------------

### Start Single Instance Docker Deployment

Source: https://github.com/deltawi/deltallm/blob/main/docs/getting-started/docker.md

Use Docker Compose to start a single instance of DeltaLLM. Ensure your config.yaml is edited with necessary API keys and settings before running.

```bash
# Edit config.yaml with your API keys and settings

docker compose --profile single up -d --build
```

--------------------------------

### Start Backend Development Server

Source: https://github.com/deltawi/deltallm/blob/main/CONTRIBUTING.md

Run the Uvicorn server for the DeltaLLM backend with hot-reloading enabled.

```bash
uv run uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
```

--------------------------------

### Example of Forwarded Header

Source: https://github.com/deltawi/deltallm/blob/main/docs/admin-ui/mcp.md

An example demonstrating how to format a caller-specific header for forwarding through DeltaLLM's MCP.

```text
x-deltallm-mcp-github-authorization: Bearer ...
```

--------------------------------

### Responses Example with MCP Tool

Source: https://github.com/deltawi/deltallm/blob/main/docs/api/mcp.md

This example demonstrates how to use an MCP tool definition within a responses API request. Verify your authentication and tool parameters before execution.

```bash
curl http://localhost:8000/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "input": "Search the docs for DeltaLLM.",
    "tools": [
      {
        "type": "mcp",
        "server": "docs",
        "allowed_tools": ["search"],
        "require_approval": "never"
      }
    ],
    "tool_choice": "required"
  }'
```

--------------------------------

### Valid Budget Duration Examples

Source: https://github.com/deltawi/deltallm/blob/main/docs/internal/20260428-issue106-monthly-budget-reset-plan.md

Examples of accepted budget duration strings for monthly resets.

```string
"1h"
```

```string
"7d"
```

```string
"30d"
```

```string
"1mo"
```

```string
"3mo"
```

--------------------------------

### Start Development Server

Source: https://github.com/deltawi/deltallm/blob/main/ui/README.md

Starts the Vite development server for the React application. The dashboard will be accessible at http://localhost:5000, with API requests proxied to the backend on port 8000.

```bash
npm run dev
```

--------------------------------

### Environment Variable Interpolation Example

Source: https://github.com/deltawi/deltallm/blob/main/docs/configuration/index.md

Example showing how to reference environment variables within the configuration file for sensitive values like master and database keys.

```yaml
general_settings:
  master_key: os.environ/DELTALLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL
```

--------------------------------

### Configure and Initialize Database

Source: https://github.com/deltawi/deltallm/blob/main/CONTRIBUTING.md

Copy the example configuration file and initialize the database schema using Prisma.

```bash
cp config.example.yaml config.yaml
uv run prisma generate --schema=./prisma/schema.prisma
uv run prisma db push --schema=./prisma/schema.prisma
```

--------------------------------

### Build UI and Serve with Backend

Source: https://github.com/deltawi/deltallm/blob/main/docs/getting-started/installation.md

Build the frontend UI and then start the backend server to serve both the API and the built frontend. This is useful for a single-process local preview.

```bash
cd ui
npm run build
cd ..
uv run uvicorn src.main:app --host 0.0.0.0 --port 5000
```

--------------------------------

### Minimal Starter Configuration

Source: https://github.com/deltawi/deltallm/blob/main/docs/configuration/general.md

This example shows a minimal configuration for general settings, emphasizing the use of environment variables for sensitive information like master keys, database URLs, and admin credentials. It also sets basic parameters for session duration, model deployment, and notification preferences.

```yaml
general_settings:
  master_key: os.environ/DELTALLM_MASTER_KEY
  salt_key: os.environ/DELTALLM_SALT_KEY
  database_url: os.environ/DATABASE_URL
  redis_url: os.environ/REDIS_URL
  platform_bootstrap_admin_email: os.environ/PLATFORM_BOOTSTRAP_ADMIN_EMAIL
  platform_bootstrap_admin_password: os.environ/PLATFORM_BOOTSTRAP_ADMIN_PASSWORD
  auth_session_ttl_hours: 12
  model_deployment_source: db_only
  model_deployment_bootstrap_from_config: true
  governance_notifications_enabled: false
  budget_notifications_enabled: false
  key_lifecycle_notifications_enabled: false
```

--------------------------------

### Get Spend Report

Source: https://github.com/deltawi/deltallm/blob/main/docs/internal/phase4-observability-spec.md

Retrieves a detailed spend report, allowing breakdown by model, provider, day, user, or team. Supports filtering by start and end dates.

```APIDOC
## GET /spend/report

### Description
Get detailed spend report with breakdown by specified category.

### Method
GET

### Endpoint
/spend/report

### Parameters
#### Query Parameters
- **start_date** (date) - Optional - Start date for the report.
- **end_date** (date) - Optional - End date for the report.
- **group_by** (string) - Optional - Category to group the report by. Allowed values: "model", "provider", "day", "user", "team". Defaults to "model".

### Response
#### Success Response (200)
- **group_by** (string) - The category used for grouping.
- **breakdown** (array) - An array of objects, each containing group key, total spend, request count, total tokens, and average spend per request.
```

--------------------------------

### Get Global Activity

Source: https://github.com/deltawi/deltallm/blob/main/docs/internal/phase4-observability-spec.md

Retrieves aggregated activity metrics including total requests, token usage, and cache hit rates. Supports filtering by start and end dates.

```APIDOC
## GET /activity

### Description
Retrieves aggregated activity metrics including total requests, token usage, and cache hit rates. Supports filtering by start and end dates.

### Method
GET

### Endpoint
/activity

### Parameters
#### Query Parameters
- **start_date** (date) - Optional - The start date for filtering activity metrics.
- **end_date** (date) - Optional - The end date for filtering activity metrics.

### Response
#### Success Response (200)
- **total_requests** (int) - The total number of requests.
- **total_tokens** (int) - The total number of tokens used.
- **prompt_tokens** (int) - The total number of prompt tokens.
- **completion_tokens** (int) - The total number of completion tokens.
- **cache_hits** (int) - The number of cache hits.
- **cache_misses** (int) - The number of cache misses.
- **cache_hit_rate** (float) - The cache hit rate as a percentage.

#### Response Example
{
  "total_requests": 1000,
  "total_tokens": 500000,
  "prompt_tokens": 300000,
  "completion_tokens": 200000,
  "cache_hits": 800,
  "cache_misses": 200,
  "cache_hit_rate": 80.0
}
```

--------------------------------

### Quick Path Configuration Example

Source: https://github.com/deltawi/deltallm/blob/main/docs/configuration/index.md

A minimal configuration for the simplest runtime model, relying on environment variables for secrets and specifying database and Redis connections.

```yaml
general_settings:
  master_key: os.environ/DELTALLM_MASTER_KEY
  salt_key: os.environ/DELTALLM_SALT_KEY
  database_url: os.environ/DATABASE_URL
  redis_url: os.environ/REDIS_URL
  model_deployment_source: db_only
  model_deployment_bootstrap_from_config: true
```

--------------------------------

### Get Spend Per Model

Source: https://github.com/deltawi/deltallm/blob/main/docs/internal/phase4-observability-spec.md

Retrieves the spend aggregated per model, including total spend, total tokens, and request count. Supports filtering by start and end dates.

```APIDOC
## GET /spend/models

### Description
Get spend per model.

### Method
GET

### Endpoint
/spend/models

### Parameters
#### Query Parameters
- **start_date** (date) - Optional - Start date for filtering.
- **end_date** (date) - Optional - End date for filtering.

### Response
#### Success Response (200)
- Returns a list of dictionaries, where each dictionary contains the model name, total spend, total tokens, and request count.
```

--------------------------------

### Get Spend Per End User

Source: https://github.com/deltawi/deltallm/blob/main/docs/internal/phase4-observability-spec.md

Retrieves the spend aggregated per end user, including total spend and request count. Supports filtering by start and end dates.

```APIDOC
## GET /spend/end_users

### Description
Get spend per end user.

### Method
GET

### Endpoint
/spend/end_users

### Parameters
#### Query Parameters
- **start_date** (date) - Optional - Start date for filtering.
- **end_date** (date) - Optional - End date for filtering.

### Response
#### Success Response (200)
- Returns a list of dictionaries, where each dictionary contains the end user ID, total spend, and request count.
```

--------------------------------

### Partitioning Strategy for Spend Logs

Source: https://github.com/deltawi/deltallm/blob/main/docs/internal/phase4-observability-spec.md

This SQL demonstrates how to set up partitioning for the `litellm_spendlogs` table by range on `start_time` to manage high-volume deployments. It includes creating a base partitioned table and an example of a monthly partition.

```sql
CREATE TABLE litellm_spendlogs_partitioned (
    LIKE litellm_spendlogs INCLUDING ALL
) PARTITION BY RANGE (start_time);

-- Create monthly partitions
CREATE TABLE litellm_spendlogs_y2024m01 
PARTITION OF litellm_spendlogs_partitioned
FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
```

--------------------------------

### Start High Availability Docker Deployment

Source: https://github.com/deltawi/deltallm/blob/main/docs/getting-started/docker.md

Deploy DeltaLLM in a high-availability configuration using Docker Compose. This setup includes two DeltaLLM instances behind an Nginx load balancer.

```bash
docker compose --profile ha up -d --build
```

--------------------------------

### Set Up Environment Variables

Source: https://github.com/deltawi/deltallm/blob/main/CONTRIBUTING.md

Configure essential environment variables for database connection, configuration path, and API keys.

```bash
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/deltallm"
export DELTALLM_CONFIG_PATH=./config.yaml
export DELTALLM_MASTER_KEY="$(python3 -c 'import secrets; print(\"sk-\" + secrets.token_hex(20) + \"A1\")')"
export DELTALLM_SALT_KEY="$(openssl rand -hex 32)"
export OPENAI_API_KEY="sk-your-openai-key"
```

--------------------------------

### Initialize Prisma and Database

Source: https://github.com/deltawi/deltallm/blob/main/README.md

Generates Prisma client, fetches Python dependencies for Prisma, and pushes the schema to the database.

```bash
uv run prisma generate --schema=./prisma/schema.prisma
uv run prisma py fetch
uv run prisma db push --schema=./prisma/schema.prisma
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/deltawi/deltallm/blob/main/CONTRIBUTING.md

Clone the DeltaLLM repository and navigate into the project directory.

```bash
git clone https://github.com/YOUR_USERNAME/deltallm.git
cd deltallm
```

--------------------------------

### Start Docker Compose

Source: https://github.com/deltawi/deltallm/blob/main/docs/deployment/docker.md

This command starts all services defined in the docker-compose.yml file in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Get Spend by Tags

Source: https://github.com/deltawi/deltallm/blob/main/docs/internal/phase4-observability-spec.md

Get spend aggregated by request tags within a specified date range.

```APIDOC
## GET /spend/tags

### Description
Get spend grouped by request tags.

### Method
GET

### Endpoint
/spend/tags

### Parameters
#### Query Parameters
- **start_date** (Optional[date]) - Optional - Start date (YYYY-MM-DD)
- **end_date** (Optional[date]) - Optional - End date (YYYY-MM-DD)

### Response
#### Success Response (200)
- **tags** (Dict[str, Any]) - Dictionary containing aggregated spend data by tag

### Response Example
```json
{
  "tags": [
    {
      "tag": "tag1",
      "total_spend": 15.50,
      "request_count": 100,
      "total_tokens": 50000
    },
    {
      "tag": "tag2",
      "total_spend": 10.20,
      "request_count": 80,
      "total_tokens": 40000
    }
  ]
}
```
```

--------------------------------

### Start DeltaLLM Gateway

Source: https://github.com/deltawi/deltallm/blob/main/docs/getting-started/quickstart.md

Starts the DeltaLLM gateway using uvicorn. Ensure Redis is running for optional caching and rate limiting.

```bash
redis-server --daemonize yes

python -m uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
```

--------------------------------

### Example Rate Limit Configuration

Source: https://github.com/deltawi/deltallm/blob/main/docs/features/rate-limiting.md

Demonstrates a common pattern for setting rate limits across different time windows and request types. Useful for balancing burst tolerance with cost control.

```json
{
  "rpm_limit": 60,
  "rph_limit": 500,
  "rpd_limit": 2000,
  "tpm_limit": 100000,
  "tpd_limit": 1000000
}
```

--------------------------------

### Install DeltaLLM with Helm

Source: https://github.com/deltawi/deltallm/blob/main/docs/deployment/kubernetes.md

Install or upgrade the DeltaLLM Helm chart using evaluation values and generated secrets. This command creates the namespace if it does not exist.

```bash
helm upgrade --install deltallm ./helm \
  --namespace deltallm \
  --create-namespace \
  -f helm/values-eval.yaml \
  --set secret.values.masterKey="$DELTALLM_MASTER_KEY" \
  --set secret.values.saltKey="$DELTALLM_SALT_KEY"
```

--------------------------------

### DeltaLLM CLI Quick Proxy Mode

Source: https://github.com/deltawi/deltallm/blob/main/docs/internal/master-prd-outline.md

Shows how to use the DeltaLLM CLI for a quick proxy to a single model without a full configuration file.

```bash
deltallm --model gpt-4  # Quick single-model proxy
```

--------------------------------

### Readiness Probe

Source: https://github.com/deltawi/deltallm/blob/main/docs/api/health.md

Checks that all dependencies are connected. Returns `200 OK` when ready to serve traffic, `503 Service Unavailable` otherwise.

```APIDOC
## GET /health/readiness

### Description
Checks that all dependencies are connected. Returns `200 OK` when ready to serve traffic, `503 Service Unavailable` otherwise.

### Method
GET

### Endpoint
/health/readiness
```

--------------------------------

### Example MCP Tool List Response

Source: https://github.com/deltawi/deltallm/blob/main/docs/api/mcp.md

A successful response to 'tools/list' includes an array of available tools with their names, descriptions, and input schemas.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "docs.search",
        "description": "Search docs",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {"type": "string"}
          },
          "required": ["query"]
        }
      }
    ]
  }
}
```

--------------------------------

### Helm Install: Production Mode

Source: https://github.com/deltawi/deltallm/blob/main/docs/deployment/kubernetes.md

Installs DeltaLLM in production mode using a downloaded production values file. This requires pre-configured external PostgreSQL and Redis, and existing secrets.

```bash
helm install deltallm deltallm/deltallm \
  --version <chart-version> \
  --namespace deltallm \
  --create-namespace \
  -f values-production.yaml \
  --set secret.existingSecret=deltallm-app-secrets
```

--------------------------------

### Recommended Upstream HTTP Defaults

Source: https://github.com/deltawi/deltallm/blob/main/docs/deployment/upstream-http.md

Set these general settings for conservative production starting points. Streaming-heavy deployments may require higher connection limits.

```yaml
general_settings:
  upstream_http_connect_timeout_seconds: 10
  upstream_http_read_timeout_seconds: 300
  upstream_http_write_timeout_seconds: 30
  upstream_http_pool_timeout_seconds: 10
  upstream_http_max_connections: 500
  upstream_http_max_keepalive_connections: 100
  upstream_http_keepalive_expiry_seconds: 60
```

--------------------------------

### Fallback Configuration Example

Source: https://github.com/deltawi/deltallm/blob/main/docs/configuration/router.md

Defines fallback chains for different scenarios, including general fallbacks, context window fallbacks, and content policy fallbacks. These are configured under deltallm_settings.

```yaml
deltallm_settings:
  fallbacks:
    - gpt-4o:
        - gpt-4o-mini
  context_window_fallbacks:
    - gpt-4o-mini:
        - gpt-4o
  content_policy_fallbacks:
    - gpt-4o:
        - claude-3-sonnet
```

--------------------------------

### Calendar-Month Calculation Examples

Source: https://github.com/deltawi/deltallm/blob/main/docs/internal/20260428-issue106-monthly-budget-reset-plan.md

Monthly resets must add calendar months, not days. Examples show how dates are advanced, accounting for varying month lengths and leap years.

```text
2026-01-15T00:00:00Z -> 2026-02-15T00:00:00Z
```

```text
2026-01-31T00:00:00Z -> 2026-02-28T00:00:00Z
```

```text
2028-01-31T00:00:00Z -> 2028-02-29T00:00:00Z
```

```text
2026-12-31T00:00:00Z -> 2027-01-31T00:00:00Z
```