config.schema.json

{
  "$defs": {
    "BudgetsConfig": {
      "additionalProperties": false,
      "description": "Where the `Budget` store (`inferrail.budgets.store.BudgetStore`)\nlives, and whether the gateway actually enforces it.\n\n`enabled` defaults to `False` so an operator who hasn't configured\nany budgets never pays for the enforcement path (and, more\nimportantly, so `inferrail serve`/`create_app` never touches\n`path` on disk at all unless budgets are explicitly turned on \u2014 see\ndocs/adr/0015-budget-enforcement.md). `inferrail budget set|list|rm`\nmanage the store's contents independently of this flag (via their\nown `--db`), so budgets can be authored before enforcement is\nswitched on.",
      "properties": {
        "allow_declared_budgets": {
          "default": true,
          "title": "Allow Declared Budgets",
          "type": "boolean"
        },
        "enabled": {
          "default": false,
          "title": "Enabled",
          "type": "boolean"
        },
        "path": {
          "default": "./inferrail-budgets.db",
          "title": "Path",
          "type": "string"
        },
        "per_work_default_usd": {
          "anyOf": [
            {
              "exclusiveMinimum": 0.0,
              "type": "number"
            },
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Per Work Default Usd"
        },
        "per_work_max_usd": {
          "anyOf": [
            {
              "exclusiveMinimum": 0.0,
              "type": "number"
            },
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Per Work Max Usd"
        }
      },
      "title": "BudgetsConfig",
      "type": "object"
    },
    "LongContextPrice": {
      "additionalProperties": false,
      "description": "Rates for a request whose input tokens exceed `above_input_tokens`.\nThey replace the base rates for the whole request, not only for the\ntokens past the threshold.",
      "properties": {
        "above_input_tokens": {
          "exclusiveMinimum": 0,
          "title": "Above Input Tokens",
          "type": "integer"
        },
        "cache_read_usd_per_million": {
          "anyOf": [
            {
              "exclusiveMinimum": 0.0,
              "type": "number"
            },
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Cache Read Usd Per Million"
        },
        "input_usd_per_million": {
          "anyOf": [
            {
              "exclusiveMinimum": 0.0,
              "type": "number"
            },
            {
              "type": "string"
            }
          ],
          "title": "Input Usd Per Million"
        },
        "output_usd_per_million": {
          "anyOf": [
            {
              "exclusiveMinimum": 0.0,
              "type": "number"
            },
            {
              "type": "string"
            }
          ],
          "title": "Output Usd Per Million"
        }
      },
      "required": [
        "above_input_tokens",
        "input_usd_per_million",
        "output_usd_per_million"
      ],
      "title": "LongContextPrice",
      "type": "object"
    },
    "PriceEntry": {
      "additionalProperties": false,
      "description": "A verified per-model price, with the provenance to audit it later.\n\nUsed both for the built-in catalog (`inferrail.pricing.builtin`) and\nfor operator overrides (`InferrailConfig.pricing`). `source` and\n`verified_date` are mandatory in both cases \u2014 Inferrail never persists\na price it can't explain the origin of. Values are `Decimal`, not\n`float`: money is never computed with binary floating point here.",
      "properties": {
        "cache_read_usd_per_million": {
          "anyOf": [
            {
              "exclusiveMinimum": 0.0,
              "type": "number"
            },
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Cache Read Usd Per Million"
        },
        "cache_write_1h_usd_per_million": {
          "anyOf": [
            {
              "exclusiveMinimum": 0.0,
              "type": "number"
            },
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Cache Write 1H Usd Per Million"
        },
        "cache_write_5m_usd_per_million": {
          "anyOf": [
            {
              "exclusiveMinimum": 0.0,
              "type": "number"
            },
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Cache Write 5M Usd Per Million"
        },
        "input_usd_per_million": {
          "anyOf": [
            {
              "exclusiveMinimum": 0.0,
              "type": "number"
            },
            {
              "type": "string"
            }
          ],
          "title": "Input Usd Per Million"
        },
        "long_context": {
          "anyOf": [
            {
              "$ref": "#/$defs/LongContextPrice"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "output_usd_per_million": {
          "anyOf": [
            {
              "exclusiveMinimum": 0.0,
              "type": "number"
            },
            {
              "type": "string"
            }
          ],
          "title": "Output Usd Per Million"
        },
        "source": {
          "title": "Source",
          "type": "string"
        },
        "verified_date": {
          "format": "date",
          "title": "Verified Date",
          "type": "string"
        }
      },
      "required": [
        "input_usd_per_million",
        "output_usd_per_million",
        "source",
        "verified_date"
      ],
      "title": "PriceEntry",
      "type": "object"
    },
    "ProviderConfig": {
      "additionalProperties": false,
      "description": "A named upstream inference provider.\n\n``type: openai`` and ``type: openai_compatible`` currently resolve to\nthe same adapter (:class:`inferrail.providers.openai.OpenAIProvider`);\nlikewise ``type: anthropic``/``anthropic_compatible`` both resolve to\n:class:`inferrail.providers.anthropic.AnthropicProvider` (see\ndocs/adr/0014-anthropic-messages-passthrough.md). The ``_compatible``\nvariants exist so config reads clearly and so a self-hosted or\nthird-party endpoint that merely shares a wire format is never\nconflated with the real, verifiably-operated vendor API for pricing\npurposes (see ``pricing.resolver.PricingResolver``).",
      "properties": {
        "api_key_env": {
          "title": "Api Key Env",
          "type": "string"
        },
        "base_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Base Url"
        },
        "price_as": {
          "anyOf": [
            {
              "enum": [
                "openai",
                "anthropic"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Price As"
        },
        "request_stream_usage": {
          "default": false,
          "title": "Request Stream Usage",
          "type": "boolean"
        },
        "type": {
          "enum": [
            "openai",
            "openai_compatible",
            "anthropic",
            "anthropic_compatible"
          ],
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "type",
        "api_key_env"
      ],
      "title": "ProviderConfig",
      "type": "object"
    },
    "ReceiptsConfig": {
      "additionalProperties": false,
      "description": "Where :class:`inferrail.receipts.schema.InferenceReceipt` records go.\n\nUnlike telemetry (default: console), receipts default to a local JSONL\nfile: the whole point of a receipt is to be aggregated later by\n``inferrail report``, and console-only receipts can't be read back. See\ndocs/adr/0005-privacy-preserving-economic-receipts.md.\n\n``sqlite`` (see docs/adr/0013-sqlite-receipts-store.md) is a first-class\nalternative to ``jsonl``, not a replacement for it \u2014 indexed queries and\na bounded file per receipt (vs. an ever-growing text file) at the cost\nof needing ``inferrail receipts export`` to get a plain-text copy back.\n``inferrail report``/``transaction``/``work`` work unchanged against\neither: they detect which one a given path actually is.",
      "properties": {
        "path": {
          "default": "./inferrail-receipts.jsonl",
          "title": "Path",
          "type": "string"
        },
        "sink": {
          "default": "jsonl",
          "enum": [
            "jsonl",
            "sqlite",
            "none"
          ],
          "title": "Sink",
          "type": "string"
        }
      },
      "title": "ReceiptsConfig",
      "type": "object"
    },
    "RouteConfig": {
      "additionalProperties": false,
      "description": "A named route: what a client selects via the request's ``model`` field.",
      "properties": {
        "max_retries": {
          "default": 0,
          "maximum": 5,
          "minimum": 0,
          "title": "Max Retries",
          "type": "integer"
        },
        "model": {
          "title": "Model",
          "type": "string"
        },
        "provider": {
          "title": "Provider",
          "type": "string"
        },
        "timeout_seconds": {
          "default": 30.0,
          "exclusiveMinimum": 0,
          "maximum": 600,
          "title": "Timeout Seconds",
          "type": "number"
        }
      },
      "required": [
        "provider",
        "model"
      ],
      "title": "RouteConfig",
      "type": "object"
    },
    "ServerConfig": {
      "additionalProperties": false,
      "properties": {
        "host": {
          "default": "127.0.0.1",
          "title": "Host",
          "type": "string"
        },
        "port": {
          "default": 8000,
          "exclusiveMinimum": 0,
          "maximum": 65535,
          "title": "Port",
          "type": "integer"
        }
      },
      "title": "ServerConfig",
      "type": "object"
    },
    "TelemetryConfig": {
      "additionalProperties": false,
      "properties": {
        "path": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Path"
        },
        "sink": {
          "default": "console",
          "enum": [
            "console",
            "jsonl",
            "none"
          ],
          "title": "Sink",
          "type": "string"
        }
      },
      "title": "TelemetryConfig",
      "type": "object"
    },
    "UsagePingConfig": {
      "additionalProperties": false,
      "description": "The anonymous usage/presence beacon\n(docs/adr/0020-quickstart-both-sdks-and-payload-free-verification.md,\nsuperseding docs/adr/0019-opt-in-usage-ping.md's \"default off\").\n\n**Opt-out by default** (`enabled: bool = True`) \u2014 a deliberate,\nexplicit reversal of ADR-0019's original \"default off\" decision, at\nthe founder's direction, recorded in ADR-0020 rather than silently\nchanged. Still fully inert with no `endpoint` configured regardless\nof `enabled` \u2014 there is no built-in default endpoint baked into this\npackage; an operator (or, for the desktop dashboard's toggle, the\nperson running `inferrail serve` on their own machine) must\nexplicitly point this at a real collector before anything can ever be\nsent. The payload is fixed and minimal (see\n`usage_ping.payload.build_payload`): a locally-generated random\ninstall id, event name, Inferrail version, OS, Python major.minor \u2014\nnever a prompt, response, model name, cost, work_id, project name,\nIP address, or anything about the traffic this install actually\nhandles. See `docs/privacy/usage-ping.md` for the full disclosure,\nand `INFERRAIL_TELEMETRY=0` / `--no-telemetry` / `DO_NOT_TRACK=1` /\nrunning under CI or the test suite for how to turn it off.\n\n`enabled` here is only the *config-file* default. Once\n`inferrail serve` has run once, the dashboard's Settings toggle (and\n`inferrail telemetry enable|disable`) control a separate, mutable\non/off state under the OS app-data directory that takes over from\nthis default \u2014 the same \"config seeds it, a store owns it after\nthat\" pattern `budgets`/`receipts` already use under `--app-mode`.",
      "properties": {
        "enabled": {
          "default": true,
          "title": "Enabled",
          "type": "boolean"
        },
        "endpoint": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Endpoint"
        }
      },
      "title": "UsagePingConfig",
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "budgets": {
      "$ref": "#/$defs/BudgetsConfig"
    },
    "default_anthropic_provider": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Default Anthropic Provider"
    },
    "default_provider": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Default Provider"
    },
    "pricing": {
      "additionalProperties": {
        "additionalProperties": {
          "$ref": "#/$defs/PriceEntry"
        },
        "type": "object"
      },
      "title": "Pricing",
      "type": "object"
    },
    "providers": {
      "additionalProperties": {
        "$ref": "#/$defs/ProviderConfig"
      },
      "title": "Providers",
      "type": "object"
    },
    "receipts": {
      "$ref": "#/$defs/ReceiptsConfig"
    },
    "routes": {
      "additionalProperties": {
        "$ref": "#/$defs/RouteConfig"
      },
      "title": "Routes",
      "type": "object"
    },
    "server": {
      "$ref": "#/$defs/ServerConfig"
    },
    "telemetry": {
      "$ref": "#/$defs/TelemetryConfig"
    },
    "usage_ping": {
      "$ref": "#/$defs/UsagePingConfig"
    },
    "work_id_headers": {
      "items": {
        "type": "string"
      },
      "title": "Work Id Headers",
      "type": "array"
    }
  },
  "required": [
    "providers"
  ],
  "title": "Inferrail configuration (inferrail.yaml)",
  "type": "object"
}