feat: config files for backend options

Signed-off-by: Paul S. Schweigert <paul@paulschweigert.com>

Author: psschwei

.gitignore

@@ -448,3 +448,7 @@ pyrightconfig.json
 .ionide
 
 # End of https://www.toptal.com/developers/gitignore/api/python,direnv,visualstudiocode,pycharm,macos,jetbrains
+
+# Mellea config files (may contain credentials)
+mellea.toml
+.mellea.toml

AGENTS.md

@@ -32,11 +32,55 @@ uv run ruff format . && uv run ruff check .  # Lint & format
 | `mellea/stdlib` | Core: Sessions, Genslots, Requirements, Sampling, Context |
 | `mellea/backends` | Providers: HF, OpenAI, Ollama, Watsonx, LiteLLM |
 | `mellea/helpers` | Utilities, logging, model ID tables |
-| `cli/` | CLI commands (`m serve`, `m alora`, `m decompose`, `m eval`) |
+| `mellea/config.py` | Configuration file support (TOML) |
+| `cli/` | CLI commands (`m serve`, `m alora`, `m decompose`, `m eval`, `m config`) |
 | `test/` | All tests (run from repo root) |
 | `scratchpad/` | Experiments (git-ignored) |
 
-## 3. Test Markers
+## 3. Configuration Files
+Mellea supports TOML configuration files for setting default backends, models, and credentials.
+
+**Config Locations (precedence order):**
+1. Project config: `./mellea.toml` (current dir and parents)
+2. User config: `~/.config/mellea/config.toml` (Linux/macOS) or `%APPDATA%\mellea\config.toml` (Windows)
+
+**Value Precedence:** Explicit params > Project config > User config > Defaults
+
+**CLI Commands:**
+```bash
+m config init              # Create user config
+m config init-project      # Create project config
+m config show              # Display effective config
+m config path              # Show loaded config file
+m config where             # Show all config locations
+```
+
+**Development Usage:**
+- Set your preferred backend/model in user config for convenience
+- Use project config for project-specific settings (safe to commit without credentials)
+- Store credentials in user config or environment variables (never commit)
+- Config files with credentials are git-ignored by default (`mellea.toml`, `.mellea.toml`)
+
+**Example User Config** (`~/.config/mellea/config.toml`):
+```toml
+[backend]
+name = "ollama"
+model_id = "llama3.2:1b"
+
+[backend.model_options]
+temperature = 0.7
+max_tokens = 2048
+
+[credentials]
+# openai_api_key = "sk-..."  # Better: use env vars
+```
+
+**Testing with Config:**
+- Tests use temporary config directories (see `test/config/test_config.py`)
+- Integration tests verify config precedence (see `test/config/test_config_integration.py`)
+- Clear config cache in tests with `clear_config_cache()` from `mellea.config`
+
+## 4. Test Markers
 All tests and examples use markers to indicate requirements. The test infrastructure automatically skips tests based on system capabilities.
 
 **Backend Markers:**

README.md

@@ -149,6 +149,66 @@ If you want to contribute, ensure that you install the precommit hooks:
 pre-commit install
 ```
 
+
+## Configuration
+
+Mellea supports configuration files to set default backends, models, and credentials without hardcoding them in your code.
+
+### Quick Start
+
+Create a user configuration file:
+
+```bash
+m config init
+```
+
+This creates `~/.config/mellea/config.toml` (Linux/macOS) or `%APPDATA%\mellea\config.toml` (Windows) with example settings.
+
+For project-specific settings:
+
+```bash
+m config init-project
+```
+
+### Example Configuration
+
+```toml
+# ~/.config/mellea/config.toml
+[backend]
+name = "ollama"
+model_id = "granite-4-micro:3b"
+
+[backend.model_options]
+temperature = 0.7
+max_tokens = 2048
+
+[credentials]
+# API keys (environment variables take precedence)
+# openai_api_key = "sk-..."
+
+context_type = "simple"  # or "chat"
+log_level = "INFO"
+```
+
+### Configuration Hierarchy
+
+Configuration files are searched in this order:
+1. Project config: `./mellea.toml` (current directory and parents)
+2. User config: `~/.config/mellea/config.toml`
+
+Values are applied with precedence: **explicit parameters > project config > user config > defaults**
+
+### CLI Commands
+
+```bash
+m config show          # Display current configuration
+m config path          # Show which config file is loaded
+m config where         # Show all config file locations
+```
+
+For detailed configuration options and security best practices, see the [Configuration Guide](docs/configuration.md).
+
+
 ### `conda`/`mamba`-based installation from source
 
 Fork and clone the repository:

cli/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration management commands for Mellea CLI."""
+
+from .commands import config_app
+
+__all__ = ["config_app"]

cli/config/commands.py

@@ -0,0 +1,207 @@
+"""CLI commands for Mellea configuration management."""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.syntax import Syntax
+from rich.table import Table
+
+from mellea.config import (
+    find_config_file,
+    get_config_path,
+    get_user_config_dir,
+    init_project_config,
+    init_user_config,
+    load_config,
+)
+
+config_app = typer.Typer(name="config", help="Manage Mellea configuration files")
+console = Console()
+
+
+@config_app.command("init")
+def init_user(
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Overwrite existing config file"
+    ),
+) -> None:
+    """Create a user configuration file at ~/.config/mellea/config.toml."""
+    try:
+        config_path = init_user_config(force=force)
+        console.print(f"[green]✓[/green] Created user config at: {config_path}")
+        console.print(
+            "\nEdit this file to set your default backend, model, and credentials."
+        )
+        console.print(
+            "Run [cyan]m config show[/cyan] to view the current configuration."
+        )
+    except FileExistsError as e:
+        console.print(f"[red]✗[/red] {e}")
+        console.print("Use [cyan]--force[/cyan] to overwrite the existing file.")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]✗[/red] Error creating config: {e}")
+        raise typer.Exit(1)
+
+
+@config_app.command("init-project")
+def init_project(
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Overwrite existing config file"
+    ),
+) -> None:
+    """Create a project configuration file at ./mellea.toml."""
+    try:
+        config_path = init_project_config(force=force)
+        console.print(f"[green]✓[/green] Created project config at: {config_path}")
+        console.print("\nThis config will override user settings for this project.")
+        console.print(
+            "Run [cyan]m config show[/cyan] to view the effective configuration."
+        )
+    except FileExistsError as e:
+        console.print(f"[red]✗[/red] {e}")
+        console.print("Use [cyan]--force[/cyan] to overwrite the existing file.")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]✗[/red] Error creating config: {e}")
+        raise typer.Exit(1)
+
+
+@config_app.command("show")
+def show_config() -> None:
+    """Display the current effective configuration."""
+    try:
+        config, config_path = load_config()
+
+        # Display config source
+        if config_path:
+            console.print(f"[bold]Configuration loaded from:[/bold] {config_path}\n")
+        else:
+            console.print(
+                "[yellow]No configuration file found. Using defaults.[/yellow]\n"
+            )
+
+        # Create a table for the configuration
+        table = Table(
+            title="Effective Configuration", show_header=True, header_style="bold cyan"
+        )
+        table.add_column("Setting", style="dim")
+        table.add_column("Value")
+
+        # Backend settings
+        table.add_row(
+            "Backend Name", config.backend.name or "[dim](default: ollama)[/dim]"
+        )
+        table.add_row(
+            "Model ID",
+            config.backend.model_id or "[dim](default: granite-4-micro:3b)[/dim]",
+        )
+
+        # Model options
+        if config.backend.model_options:
+            for key, value in config.backend.model_options.items():
+                table.add_row(f"  {key}", str(value))
+
+        # Backend kwargs
+        if config.backend.kwargs:
+            for key, value in config.backend.kwargs.items():
+                table.add_row(f"  backend.{key}", str(value))
+
+        # Credentials (masked)
+        if config.credentials.openai_api_key:
+            table.add_row("OpenAI API Key", "[dim]***configured***[/dim]")
+        if config.credentials.watsonx_api_key:
+            table.add_row("Watsonx API Key", "[dim]***configured***[/dim]")
+        if config.credentials.watsonx_project_id:
+            table.add_row("Watsonx Project ID", config.credentials.watsonx_project_id)
+        if config.credentials.watsonx_url:
+            table.add_row("Watsonx URL", config.credentials.watsonx_url)
+
+        # General settings
+        table.add_row(
+            "Context Type", config.context_type or "[dim](default: simple)[/dim]"
+        )
+        table.add_row("Log Level", config.log_level or "[dim](default: INFO)[/dim]")
+
+        console.print(table)
+
+        # Show search order
+        console.print("\n[bold]Configuration search order:[/bold]")
+        console.print("1. Project config: ./mellea.toml (current dir and parents)")
+        console.print(f"2. User config: {get_user_config_dir() / 'config.toml'}")
+        console.print(
+            "\n[dim]Explicit parameters in code override config file values.[/dim]"
+        )
+
+    except Exception as e:
+        console.print(f"[red]✗[/red] Error loading config: {e}")
+        raise typer.Exit(1)
+
+
+@config_app.command("path")
+def show_path() -> None:
+    """Show the path to the currently loaded configuration file."""
+    try:
+        config_path = find_config_file()
+
+        if config_path:
+            console.print(f"[green]✓[/green] Using config file: {config_path}")
+
+            # Show the file content
+            console.print("\n[bold]File contents:[/bold]")
+            with open(config_path) as f:
+                content = f.read()
+            syntax = Syntax(content, "toml", theme="monokai", line_numbers=True)
+            console.print(syntax)
+        else:
+            console.print("[yellow]No configuration file found.[/yellow]")
+            console.print("\nSearched locations:")
+            console.print("1. ./mellea.toml (current dir and parents)")
+            console.print(f"2. {get_user_config_dir() / 'config.toml'}")
+            console.print("\nRun [cyan]m config init[/cyan] to create a user config.")
+            console.print(
+                "Run [cyan]m config init-project[/cyan] to create a project config."
+            )
+    except Exception as e:
+        console.print(f"[red]✗[/red] Error: {e}")
+        raise typer.Exit(1)
+
+
+@config_app.command("where")
+def show_locations() -> None:
+    """Show all possible configuration file locations."""
+    user_config_dir = get_user_config_dir()
+    user_config_path = user_config_dir / "config.toml"
+    project_config_path = Path.cwd() / "mellea.toml"
+
+    console.print("[bold]Configuration file locations:[/bold]\n")
+
+    # User config
+    console.print(f"[cyan]User config:[/cyan] {user_config_path}")
+    if user_config_path.exists():
+        console.print("  [green]✓ exists[/green]")
+    else:
+        console.print("  [dim]✗ not found[/dim]")
+        console.print("  Run [cyan]m config init[/cyan] to create")
+
+    console.print()
+
+    # Project config
+    console.print(f"[cyan]Project config:[/cyan] {project_config_path}")
+    if project_config_path.exists():
+        console.print("  [green]✓ exists[/green]")
+    else:
+        console.print("  [dim]✗ not found[/dim]")
+        console.print("  Run [cyan]m config init-project[/cyan] to create")
+
+    console.print()
+
+    # Currently loaded
+    current = find_config_file()
+    if current:
+        console.print(f"[bold green]Currently loaded:[/bold green] {current}")
+    else:
+        console.print(
+            "[yellow]No config file currently loaded (using defaults)[/yellow]"
+        )

cli/eval/runner.py

@@ -76,7 +76,7 @@ def pass_rate(self) -> float:
 
 
 def create_session(
-    backend: str, model: str | None, max_tokens: int | None
+    backend: str | None, model: str | None, max_tokens: int | None
 ) -> mellea.MelleaSession:
     """Create a mellea session with the specified backend and model."""
     model_id = None
@@ -92,6 +92,11 @@ def create_session(
         model_id = mellea.model_ids.IBM_GRANITE_4_MICRO_3B
 
     try:
+        from mellea.core.backend import Backend
+
+        if backend is None:
+            raise ValueError("Backend must be specified")
+
         backend_lower = backend.lower()
         backend_instance: Backend
 

cli/m.py

@@ -3,6 +3,7 @@
 import typer
 
 from cli.alora.commands import alora_app
+from cli.config.commands import config_app
 from cli.decompose import app as decompose_app
 from cli.eval.commands import eval_app
 from cli.serve.app import serve
@@ -25,6 +26,7 @@ def callback() -> None:
 # Add new subcommand groups by importing and adding with `cli.add_typer()`
 # as documented: https://typer.tiangolo.com/tutorial/subcommands/add-typer/#put-them-together.
 cli.add_typer(alora_app)
+cli.add_typer(config_app)
 cli.add_typer(decompose_app)
 
 cli.add_typer(eval_app)