<!-- DO NOT EDIT — this file is generated by docs/generate_reference.py.
     Run `uv run python docs/generate_reference.py` to regenerate.
     CI will fail if this file is stale. -->

# Configuration Reference

This reference is generated from the pydantic schemas in `src/lgtmaybe/core/models.py`.

## ReviewConfig

The user-facing configuration model. Fields map directly to `.lgtmaybe.yml` keys and CLI flags.

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `api_base` | string / null | No | `null` | Api Base |
| `categories` | list[`complexity` / `correctness` / `deprecation` / `documentation` / `intent` / `performance` / `ponytail` / `security` / `tests`] | No | `['security', 'correctness', 'deprecation', 'tests', 'documentation', 'performance', 'complexity', 'intent', 'ponytail']` | Categories |
| `context_lines` | integer | No | `20` | Context Lines |
| `exclude_paths` | list[string] | No | `[]` | Exclude Paths |
| `extra_lenses` | list[CustomLens] | No | `[]` | Extra Lenses |
| `include_paths` | list[string] | No | `[]` | Include Paths |
| `max_files` | integer | No | `50` | Max Files |
| `max_input_tokens` | integer | No | `100000` | Max Input Tokens |
| `min_severity` | `critical` / `high` / `info` / `low` / `medium` | No | `info` |  |
| `model` | string | Yes | — | Model |
| `num_ctx` | integer / null | No | `null` | Num Ctx |
| `provider` | `anthropic` / `azure` / `bedrock` / `ollama` / `openai` / `openai-compatible` / `openrouter` / `vertex` | Yes | — |  |
| `reflect` | boolean | No | `True` | Reflect |
| `resolve_fixed` | boolean | No | `True` | Resolve Fixed |
| `structured_output` | boolean | No | `True` | Structured Output |
| `temperature` | number | No | `0.0` | Temperature |
| `timeout` | integer / null | No | `null` | Timeout |

## Enums

### Provider

LLM backend selected by `--provider`. Cloud providers (`bedrock`, `vertex`, `azure`) use ambient credentials — `azure` also needs the resource endpoint (`--api-base`) and accepts a key as an alternative. `openai-compatible` points at any server speaking the OpenAI `/v1` wire format (DeepSeek, llama.cpp, LM Studio, vLLM) via `--api-base`; the key is optional so keyless local servers work.

- `anthropic`
- `azure`
- `bedrock`
- `ollama`
- `openai`
- `openai-compatible`
- `openrouter`
- `vertex`

### Severity

Finding severity, ordered low to high. Use `min_severity` in config to suppress findings below a threshold.

- `critical`
- `high`
- `info`
- `low`
- `medium`

## ReviewFinding

The structured output the model must return for each inline comment. All fields are validated by pydantic before anything is posted to GitHub.

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `body` | string | Yes | — | Body |
| `line` | integer | Yes | — | Line |
| `path` | string | Yes | — | Path |
| `severity` | `critical` / `high` / `info` / `low` / `medium` | Yes | — |  |
| `side` | string | No | `RIGHT` | Side |
| `suggestion` | string / null | No | `null` | Suggestion |
| `title` | string | Yes | — | Title |

## ProviderResult

The normalised return value of one LLM completion, including usage and cost.

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `input_tokens` | integer | Yes | — | Input Tokens |
| `output_tokens` | integer | Yes | — | Output Tokens |
| `text` | string | Yes | — | Text |

## PRContext

Everything the engine needs about a pull request. Fetched via the GitHub REST API — PR code is never checked out.

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `base_sha` | string | Yes | — | Base Sha |
| `changed_files` | list[string] | Yes | — | Changed Files |
| `commit_messages` | list[string] | No | `[]` | Commit Messages |
| `description` | string | No | `` | Description |
| `diff` | string | Yes | — | Diff |
| `file_contents` | object | No | — | File Contents |
| `head_sha` | string | Yes | — | Head Sha |
| `pr_number` | integer | Yes | — | Pr Number |
| `repo` | string | Yes | — | Repo |
| `title` | string | No | `` | Title |

## Raw JSON schemas

The canonical machine-readable schemas. These are the source of truth for provider output validation.

### ReviewConfig

```json
{
  "$defs": {
    "CustomLens": {
      "additionalProperties": false,
      "description": "A user-defined review lens \u2014 a \"skill file\" run alongside the built-ins.\n\nThe engine fans it out as its own focused LLM call (same pipeline as a\nbuilt-in ``ReviewCategory``) and merges its findings with the rest. A lens is\ndeclared in **trusted** config (``.lgtmaybe.yml`` or a file referenced by\n``lens_paths``), never from PR-author content, so its text is safe to put in\nthe system prompt. Supplying a worked example (``example_diff`` +\n``example_finding``) is optional but sharply improves a small model's output.",
      "properties": {
        "example_diff": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Example Diff"
        },
        "example_finding": {
          "anyOf": [
            {
              "$ref": "#/$defs/ReviewFinding"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "id": {
          "title": "Id",
          "type": "string"
        },
        "instructions": {
          "title": "Instructions",
          "type": "string"
        },
        "title": {
          "default": "",
          "title": "Title",
          "type": "string"
        }
      },
      "required": [
        "id",
        "instructions"
      ],
      "title": "CustomLens",
      "type": "object"
    },
    "Provider": {
      "description": "The backend selected by the `--provider` flag.",
      "enum": [
        "openai",
        "openrouter",
        "anthropic",
        "bedrock",
        "vertex",
        "azure",
        "ollama",
        "openai-compatible"
      ],
      "title": "Provider",
      "type": "string"
    },
    "ReviewCategory": {
      "description": "A single review lens. The engine asks for each one in its own LLM call.\n\n``intent`` checks the diff against the PR's stated intent (title, description,\ncommit messages); it only runs when the context carries some stated intent.\n``ponytail`` is the \"lazy senior dev\" lens \u2014 the best code is the code you\nnever wrote \u2014 flagging code that needn't exist at all (YAGNI, reach for the\nstandard library, do it in fewer lines).",
      "enum": [
        "security",
        "correctness",
        "deprecation",
        "tests",
        "documentation",
        "performance",
        "complexity",
        "intent",
        "ponytail"
      ],
      "title": "ReviewCategory",
      "type": "string"
    },
    "ReviewFinding": {
      "additionalProperties": false,
      "description": "A single inline review comment the model wants to post.",
      "properties": {
        "body": {
          "title": "Body",
          "type": "string"
        },
        "line": {
          "title": "Line",
          "type": "integer"
        },
        "path": {
          "title": "Path",
          "type": "string"
        },
        "severity": {
          "$ref": "#/$defs/Severity"
        },
        "side": {
          "default": "RIGHT",
          "enum": [
            "LEFT",
            "RIGHT"
          ],
          "title": "Side",
          "type": "string"
        },
        "suggestion": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Suggestion"
        },
        "title": {
          "title": "Title",
          "type": "string"
        }
      },
      "required": [
        "path",
        "line",
        "severity",
        "title",
        "body"
      ],
      "title": "ReviewFinding",
      "type": "object"
    },
    "Severity": {
      "description": "Finding severity, ordered low \u2192 high for `min_severity` filtering.",
      "enum": [
        "info",
        "low",
        "medium",
        "high",
        "critical"
      ],
      "title": "Severity",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "How to run one review: provider/model, severity floor, filters, caps.",
  "properties": {
    "api_base": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Base"
    },
    "categories": {
      "default": [
        "security",
        "correctness",
        "deprecation",
        "tests",
        "documentation",
        "performance",
        "complexity",
        "intent",
        "ponytail"
      ],
      "items": {
        "$ref": "#/$defs/ReviewCategory"
      },
      "title": "Categories",
      "type": "array"
    },
    "context_lines": {
      "default": 20,
      "title": "Context Lines",
      "type": "integer"
    },
    "exclude_paths": {
      "items": {
        "type": "string"
      },
      "title": "Exclude Paths",
      "type": "array"
    },
    "extra_lenses": {
      "items": {
        "$ref": "#/$defs/CustomLens"
      },
      "title": "Extra Lenses",
      "type": "array"
    },
    "include_paths": {
      "items": {
        "type": "string"
      },
      "title": "Include Paths",
      "type": "array"
    },
    "max_files": {
      "default": 50,
      "title": "Max Files",
      "type": "integer"
    },
    "max_input_tokens": {
      "default": 100000,
      "title": "Max Input Tokens",
      "type": "integer"
    },
    "min_severity": {
      "$ref": "#/$defs/Severity",
      "default": "info"
    },
    "model": {
      "title": "Model",
      "type": "string"
    },
    "num_ctx": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Num Ctx"
    },
    "provider": {
      "$ref": "#/$defs/Provider"
    },
    "reflect": {
      "default": true,
      "title": "Reflect",
      "type": "boolean"
    },
    "resolve_fixed": {
      "default": true,
      "title": "Resolve Fixed",
      "type": "boolean"
    },
    "structured_output": {
      "default": true,
      "title": "Structured Output",
      "type": "boolean"
    },
    "temperature": {
      "default": 0.0,
      "title": "Temperature",
      "type": "number"
    },
    "timeout": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Timeout"
    }
  },
  "required": [
    "provider",
    "model"
  ],
  "title": "ReviewConfig",
  "type": "object"
}
```

### ReviewFinding

```json
{
  "$defs": {
    "Severity": {
      "description": "Finding severity, ordered low \u2192 high for `min_severity` filtering.",
      "enum": [
        "info",
        "low",
        "medium",
        "high",
        "critical"
      ],
      "title": "Severity",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "A single inline review comment the model wants to post.",
  "properties": {
    "body": {
      "title": "Body",
      "type": "string"
    },
    "line": {
      "title": "Line",
      "type": "integer"
    },
    "path": {
      "title": "Path",
      "type": "string"
    },
    "severity": {
      "$ref": "#/$defs/Severity"
    },
    "side": {
      "default": "RIGHT",
      "enum": [
        "LEFT",
        "RIGHT"
      ],
      "title": "Side",
      "type": "string"
    },
    "suggestion": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Suggestion"
    },
    "title": {
      "title": "Title",
      "type": "string"
    }
  },
  "required": [
    "path",
    "line",
    "severity",
    "title",
    "body"
  ],
  "title": "ReviewFinding",
  "type": "object"
}
```

### ProviderResult

```json
{
  "additionalProperties": false,
  "description": "The normalised return of one LLM completion, with token usage.",
  "properties": {
    "input_tokens": {
      "title": "Input Tokens",
      "type": "integer"
    },
    "output_tokens": {
      "title": "Output Tokens",
      "type": "integer"
    },
    "text": {
      "title": "Text",
      "type": "string"
    }
  },
  "required": [
    "text",
    "input_tokens",
    "output_tokens"
  ],
  "title": "ProviderResult",
  "type": "object"
}
```

### PRContext

```json
{
  "additionalProperties": false,
  "description": "Everything the engine needs about a PR \u2014 fetched via API, never checkout.",
  "properties": {
    "base_sha": {
      "title": "Base Sha",
      "type": "string"
    },
    "changed_files": {
      "items": {
        "type": "string"
      },
      "title": "Changed Files",
      "type": "array"
    },
    "commit_messages": {
      "items": {
        "type": "string"
      },
      "title": "Commit Messages",
      "type": "array"
    },
    "description": {
      "default": "",
      "title": "Description",
      "type": "string"
    },
    "diff": {
      "title": "Diff",
      "type": "string"
    },
    "file_contents": {
      "additionalProperties": {
        "type": "string"
      },
      "title": "File Contents",
      "type": "object"
    },
    "head_sha": {
      "title": "Head Sha",
      "type": "string"
    },
    "pr_number": {
      "title": "Pr Number",
      "type": "integer"
    },
    "repo": {
      "title": "Repo",
      "type": "string"
    },
    "title": {
      "default": "",
      "title": "Title",
      "type": "string"
    }
  },
  "required": [
    "diff",
    "changed_files",
    "base_sha",
    "head_sha",
    "repo",
    "pr_number"
  ],
  "title": "PRContext",
  "type": "object"
}
```
