Skip to content

Config

YAML config loader and Pydantic validation for Foreman.

All secrets are ${VAR} environment variable references — the config file itself never contains raw secret values.

CLASS DESCRIPTION
AgentAssignment

A single agent assigned to a repository.
ConfigError

Raised when config loading or validation fails.
ForemanConfig

Top-level Foreman runtime configuration.
IdentityConfig

Bot GitHub identity configuration.
LLMConfig

LLM backend configuration.
PollingConfig

GitHub polling configuration.
RepoConfig

Configuration for a single repository.
FUNCTION DESCRIPTION
load_config

Load and validate a Foreman YAML configuration file.

Classes

AgentAssignment pydantic-model

Bases: BaseModel

A single agent assigned to a repository.

PARAMETER DESCRIPTION
type

Agent type identifier (e.g. issue-triage).

TYPE: str

config

Agent-specific configuration options.

TYPE: dict[str, Any] DEFAULT: {}

allow_close

Whether this agent may close issues.

TYPE: bool DEFAULT: False

Show JSON schema: 
{
  "description": "A single agent assigned to a repository.",
  "properties": {
    "type": {
      "title": "Type",
      "type": "string"
    },
    "config": {
      "additionalProperties": true,
      "default": {},
      "title": "Config",
      "type": "object"
    },
    "allow_close": {
      "default": false,
      "title": "Allow Close",
      "type": "boolean"
    }
  },
  "required": [
    "type"
  ],
  "title": "AgentAssignment",
  "type": "object"
}

Fields:

Attributes

allow_close pydantic-field 
allow_close: bool = False

Whether this agent may close issues.

config pydantic-field 
config: dict[str, Any] = {}

Agent-specific configuration options.

type pydantic-field 
type: str

Agent type identifier (e.g. issue-triage).

ConfigError

Bases: Exception

Raised when config loading or validation fails.

ForemanConfig pydantic-model

Bases: BaseModel

Top-level Foreman runtime configuration.

PARAMETER DESCRIPTION
identity

Bot GitHub identity.

TYPE: IdentityConfig

llm

LLM backend configuration.

TYPE: LLMConfig

polling

GitHub polling settings.

TYPE: PollingConfig DEFAULT: PollingConfig(interval_seconds=60)

repos

Repositories to monitor.

TYPE: list[RepoConfig] DEFAULT: []

Show JSON schema: 
{
  "$defs": {
    "AgentAssignment": {
      "description": "A single agent assigned to a repository.",
      "properties": {
        "type": {
          "title": "Type",
          "type": "string"
        },
        "config": {
          "additionalProperties": true,
          "default": {},
          "title": "Config",
          "type": "object"
        },
        "allow_close": {
          "default": false,
          "title": "Allow Close",
          "type": "boolean"
        }
      },
      "required": [
        "type"
      ],
      "title": "AgentAssignment",
      "type": "object"
    },
    "IdentityConfig": {
      "description": "Bot GitHub identity configuration.",
      "properties": {
        "github_token": {
          "format": "password",
          "title": "Github Token",
          "type": "string",
          "writeOnly": true
        },
        "github_user": {
          "title": "Github User",
          "type": "string"
        }
      },
      "required": [
        "github_token",
        "github_user"
      ],
      "title": "IdentityConfig",
      "type": "object"
    },
    "LLMConfig": {
      "description": "LLM backend configuration.",
      "properties": {
        "provider": {
          "title": "Provider",
          "type": "string"
        },
        "model": {
          "title": "Model",
          "type": "string"
        },
        "api_key": {
          "anyOf": [
            {
              "format": "password",
              "type": "string",
              "writeOnly": true
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Api Key"
        }
      },
      "required": [
        "provider",
        "model"
      ],
      "title": "LLMConfig",
      "type": "object"
    },
    "PollingConfig": {
      "description": "GitHub polling configuration.",
      "properties": {
        "interval_seconds": {
          "default": 60,
          "title": "Interval Seconds",
          "type": "integer"
        }
      },
      "title": "PollingConfig",
      "type": "object"
    },
    "RepoConfig": {
      "description": "Configuration for a single repository.",
      "properties": {
        "owner": {
          "title": "Owner",
          "type": "string"
        },
        "name": {
          "title": "Name",
          "type": "string"
        },
        "agents": {
          "default": [],
          "items": {
            "$ref": "#/$defs/AgentAssignment"
          },
          "title": "Agents",
          "type": "array"
        }
      },
      "required": [
        "owner",
        "name"
      ],
      "title": "RepoConfig",
      "type": "object"
    }
  },
  "description": "Top-level Foreman runtime configuration.",
  "properties": {
    "identity": {
      "$ref": "#/$defs/IdentityConfig"
    },
    "llm": {
      "$ref": "#/$defs/LLMConfig"
    },
    "polling": {
      "$ref": "#/$defs/PollingConfig",
      "default": {
        "interval_seconds": 60
      }
    },
    "repos": {
      "default": [],
      "items": {
        "$ref": "#/$defs/RepoConfig"
      },
      "title": "Repos",
      "type": "array"
    }
  },
  "required": [
    "identity",
    "llm"
  ],
  "title": "ForemanConfig",
  "type": "object"
}

Fields:

Validators:

  • _check_required

Attributes

identity pydantic-field 
identity: IdentityConfig

Bot GitHub identity.

llm pydantic-field 
llm: LLMConfig

LLM backend configuration.

polling pydantic-field 
polling: PollingConfig

GitHub polling settings.

repos pydantic-field 
repos: list[RepoConfig] = []

Repositories to monitor.

IdentityConfig pydantic-model

Bases: BaseModel

Bot GitHub identity configuration.

PARAMETER DESCRIPTION
github_token

GitHub Personal Access Token for the bot account.

TYPE: SecretStr

github_user

GitHub username of the bot account.

TYPE: str

Show JSON schema: 
{
  "description": "Bot GitHub identity configuration.",
  "properties": {
    "github_token": {
      "format": "password",
      "title": "Github Token",
      "type": "string",
      "writeOnly": true
    },
    "github_user": {
      "title": "Github User",
      "type": "string"
    }
  },
  "required": [
    "github_token",
    "github_user"
  ],
  "title": "IdentityConfig",
  "type": "object"
}

Fields:

Attributes

github_token pydantic-field 
github_token: SecretStr

GitHub Personal Access Token for the bot account.

github_user pydantic-field 
github_user: str

GitHub username of the bot account.

LLMConfig pydantic-model

Bases: BaseModel

LLM backend configuration.

PARAMETER DESCRIPTION
provider

LLM provider identifier (e.g. anthropic, ollama).

TYPE: str

model

Model name / identifier.

TYPE: str

api_key

API key; omit for local providers such as Ollama.

TYPE: SecretStr | None DEFAULT: None

Show JSON schema: 
{
  "description": "LLM backend configuration.",
  "properties": {
    "provider": {
      "title": "Provider",
      "type": "string"
    },
    "model": {
      "title": "Model",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "format": "password",
          "type": "string",
          "writeOnly": true
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "provider",
    "model"
  ],
  "title": "LLMConfig",
  "type": "object"
}

Fields:

Attributes

api_key pydantic-field 
api_key: SecretStr | None = None

API key; omit for local providers such as Ollama.

model pydantic-field 
model: str

Model name / identifier.

provider pydantic-field 
provider: str

LLM provider identifier (e.g. anthropic, ollama).

PollingConfig pydantic-model

Bases: BaseModel

GitHub polling configuration.

PARAMETER DESCRIPTION
interval_seconds

How often to poll GitHub for new events (in seconds).

TYPE: int DEFAULT: 60

Show JSON schema: 
{
  "description": "GitHub polling configuration.",
  "properties": {
    "interval_seconds": {
      "default": 60,
      "title": "Interval Seconds",
      "type": "integer"
    }
  },
  "title": "PollingConfig",
  "type": "object"
}

Fields:

Attributes

interval_seconds pydantic-field 
interval_seconds: int = 60

How often to poll GitHub for new events (in seconds).

RepoConfig pydantic-model

Bases: BaseModel

Configuration for a single repository.

PARAMETER DESCRIPTION
owner

Repository owner (user or organization).

TYPE: str

name

Repository name.

TYPE: str

agents

Agents assigned to this repository.

TYPE: list[AgentAssignment] DEFAULT: []

Show JSON schema: 
{
  "$defs": {
    "AgentAssignment": {
      "description": "A single agent assigned to a repository.",
      "properties": {
        "type": {
          "title": "Type",
          "type": "string"
        },
        "config": {
          "additionalProperties": true,
          "default": {},
          "title": "Config",
          "type": "object"
        },
        "allow_close": {
          "default": false,
          "title": "Allow Close",
          "type": "boolean"
        }
      },
      "required": [
        "type"
      ],
      "title": "AgentAssignment",
      "type": "object"
    }
  },
  "description": "Configuration for a single repository.",
  "properties": {
    "owner": {
      "title": "Owner",
      "type": "string"
    },
    "name": {
      "title": "Name",
      "type": "string"
    },
    "agents": {
      "default": [],
      "items": {
        "$ref": "#/$defs/AgentAssignment"
      },
      "title": "Agents",
      "type": "array"
    }
  },
  "required": [
    "owner",
    "name"
  ],
  "title": "RepoConfig",
  "type": "object"
}

Fields:

Attributes

agents pydantic-field 
agents: list[AgentAssignment] = []

Agents assigned to this repository.

name pydantic-field 
name: str

Repository name.

owner pydantic-field 
owner: str

Repository owner (user or organization).

Functions

load_config 

load_config(path: Path | str) -> ForemanConfig

Load and validate a Foreman YAML configuration file.

Resolves ${VAR} environment variable references before validation. Fails fast with a :class:ConfigError if the file is missing, the YAML is malformed, a required field is absent, or a referenced environment variable is not set.

PARAMETER DESCRIPTION
path

Path to the YAML configuration file.

TYPE: Path | str

RETURNS DESCRIPTION
ForemanConfig

A validated :class:ForemanConfig instance.
RAISES DESCRIPTION
ConfigError

If anything goes wrong during loading or validation.