Configuration¶

aifred-tk uses a six-layer configuration chain. Layers are merged in ascending priority order — later layers override earlier ones.

Configuration layers¶

Priority	Source	Example path (Linux)
1 (lowest)	Package defaults	bundled `default_settings.yml`
2	System config	`/etc/xdg/aifred-tk/settings.yml`
3	User config	`~/.config/aifred-tk/settings.yml`
4	Local (CWD)	`.aifred-tk/settings.yml`
5	`--config` flag	any path passed at runtime
6 (highest)	Environment variables	`AIFRED_TK_*`

System and user paths follow platformdirs conventions and resolve to platform-appropriate locations on macOS and Windows as well.

Missing files at layers 2–5 are silently skipped.

Environment variables¶

All settings can be overridden with environment variables using the AIFRED_TK_ prefix and dynaconf's double-underscore nested key syntax:

# Set log level to DEBUG
AIFRED_TK_AIFRED_TK__LOG_LEVEL=DEBUG aifred-tk my_tool --option value

# Enable detailed LLM tracing
AIFRED_TK_AIFRED_TK__DEBUG=1 aifred-tk my_tool --option value

Settings file format¶

Settings files use YAML:

aifred_tk:
  log_level: INFO
  log_dir: logs/

tools:
  my_tool:
    enabled: true

Default settings¶

Key	Default	Description
`aifred_tk.log_level`	`INFO`	Logging verbosity
`aifred_tk.log_dir`	`.aifred-tk/logs`	Directory for log files
`aifred_tk.debug`	`false`	Enable detailed tracing of LLM interactions
`aifred_tk.elicitation.mode`	`auto`	Interaction mode for user choice prompts (`auto`, `interactive`, `numbered`) — see Elicitation

Per-tool settings¶

Tools can be enabled or disabled by tool ID:

tools:
  my_tool:
    enabled: false

Individual plugins may define additional settings under their own namespace. Refer to each plugin's documentation for available keys.

Bundled LLM default¶

The package ships a named LLM entry called default that points at OpenAI gpt-4o-mini. All LLM-backed built-in tools (commit, analyze_file, detect_prompt_injection) reference it via type: ref / ref: default out of the box. Override it by redefining llms.default in any higher-priority layer, or change the per-tool ref to point at a different entry.

Key	Default
`tools.commit.llm`	`ref: default`
`tools.analyze_file.llm`	`ref: default`
`tools.detect_prompt_injection.llm`	`ref: default`

LLMs¶

Named LLM configurations are declared under the top-level llms key. Each entry is a dictionary keyed by an arbitrary name. Plugins reference these entries by name, keeping connection details out of per-tool config.

llms:
  my-gemma:
    provider: ollama
    model: gemma4:e4b
    host: 127.0.0.1
    port: 11434
    context_size: 8192
    response_size: 4096

  gpt4o-mini:
    provider: openai
    model: gpt-4o-mini

Provider types¶

Provider	`provider` value	Required fields	Optional fields
Ollama	`ollama`	`model`	`host`, `port`, `context_size`, `response_size`
OpenAI	`openai`	`model`	`api_key`, `base_url`, `context_size`, `response_size`
Anthropic	`anthropic`	`model`	`api_key`, `context_size`, `response_size`
OpenAI-compatible	`openai-compatible`	`model`, `base_url`	`api_key`, `context_size`, `response_size`
Google	`google`	`model`	`api_key`, `context_size`, `response_size`
Fallback	`fallback`	`primary`, `fallback`	(None)

Ollama defaults to host: 127.0.0.1 and port: 11434. The Ollama server must be running and serving a Chat Completions-compatible endpoint at /v1.

Fallback chains¶

A fallback configuration uses the fallback provider to implement a "chain-of-responsibility" pattern. It attempts to run the primary agent first; if that agent raises a transport error (e.g., HTTP 4xx/5xx or connection failure), it automatically retries the identical call using the fallback agent.

Both primary and fallback accept any full LLM configuration (either by reference or inline). Chains can be arbitrarily deep by nesting fallback providers.

Example: Local-first with Cloud fallback

Try a local Ollama model first, falling back to OpenAI if the local server is down:

llms:
  local-first:
    provider: fallback
    primary:
      provider: ollama
      model: gemma:2b
    fallback:
      provider: openai
      model: gpt-4o-mini

Example: Deeply nested chain

llms:
  resilient-chain:
    provider: fallback
    primary: { type: ref, ref: my-ollama }
    fallback:
      provider: fallback
      primary: { type: ref, ref: my-openai }
      fallback: { type: ref, ref: my-anthropic }

OpenAI and Anthropic read their API keys from the OPENAI_API_KEY and ANTHROPIC_API_KEY environment variables respectively when api_key is not set in the config file. Do not store API keys in settings files tracked by version control.

Google reads its API key from the GOOGLE_API_KEY or GEMINI_API_KEY environment variable when api_key is not set. Obtain a key from Google AI Studio. Do not store API keys in settings files tracked by version control.

OpenAI-compatible covers any server that implements the OpenAI Chat Completions API, such as LM Studio, vLLM, or llama.cpp with an HTTP frontend.

Plugin LLM settings¶

A plugin tool references a named LLM or defines one inline under tools.<tool_id>.llm.

By reference — points to a named entry in the llms block:

tools:
  my_tool:
    llm:
      type: ref
      ref: my-gemma

Inline — defines the provider and model directly:

tools:
  my_tool:
    llm:
      type: custom
      provider: openai
      model: gpt-4o-mini

Inline definitions accept the same fields as the corresponding named entry. A reference is preferred when the same LLM is used by multiple tools.

Debugging and Tracing¶

aifred-tk includes a debugging feature that emits detailed traces of all LLM interactions. This is useful for troubleshooting agent behavior, inspecting prompt payloads, and monitoring token usage.

Enabling tracing¶

Tracing is disabled by default. You can enable it by setting aifred_tk.debug to true in your configuration file:

aifred_tk:
  debug: true

Alternatively, you can use the environment variable AIFRED_TK_AIFRED_TK__DEBUG=1.

Trace content¶

When enabled, aifred-tk emits logs at the DEBUG level to the configured log_dir. These traces capture:

Agent initialization — including the tool ID, model descriptor, and the full system prompt.
LLM request payloads — including the message history, output schemas, and output modes.
Model responses — including raw response parts, the specific model that handled the request, finish reasons, and token usage statistics.

Traces are transparently injected into all enabled tools, including both leaf agents and fallback chains.