mini-swe-agent 1.17.5__py3-none-any.whl → 2.0.0a1__py3-none-any.whl

minisweagent/agents/default.py

@@ -1,140 +1,155 @@
-"""Basic agent class. See https://mini-swe-agent.com/latest/advanced/control_flow/ for visual explanation."""
+"""Basic agent class. See https://mini-swe-agent.com/latest/advanced/control_flow/ for visual explanation
+or https://minimal-agent.com for a tutorial on the basic building principles.
+"""
 
-import re
-import subprocess
-import time
-from dataclasses import asdict, dataclass
+import json
+import logging
+import traceback
+from pathlib import Path
 
 from jinja2 import StrictUndefined, Template
+from pydantic import BaseModel
 
-from minisweagent import Environment, Model
-
-
-@dataclass
-class AgentConfig:
-    # The default settings are the bare minimum to run the agent. Take a look at the config files for improved settings.
-    system_template: str = "You are a helpful assistant that can do anything."
-    instance_template: str = (
-        "Your task: {{task}}. Please reply with a single shell command in triple backticks. "
-        "To finish, the first line of the output of the shell command must be 'COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT'."
-    )
-    timeout_template: str = (
-        "The last command <command>{{action['action']}}</command> timed out and has been killed.\n"
-        "The output of the command was:\n"
-        "{% if output | length < 10000 -%}\n"
-        "<output>\n{{output}}\n</output>\n"
-        "{%- else -%}\n"
-        "<warning>Output was too long and has been truncated.</warning>\n"
-        "<output_head>\n{{ output[:5000] }}\n</output_head>\n"
-        "<elided_chars>{{ output | length - 10000 }} characters elided</elided_chars>\n"
-        "<output_tail>\n{{ output[-5000:] }}\n</output_tail>\n"
-        "{%- endif %}\n"
-        "Please try another command and make sure to avoid those requiring interactive input."
-    )
-    format_error_template: str = "Please always provide EXACTLY ONE action in triple backticks."
-    action_observation_template: str = "Observation: {{output}}"
-    action_regex: str = r"```bash\s*\n(.*?)\n```"
-    step_limit: int = 0
-    cost_limit: float = 3.0
-
-
-class NonTerminatingException(Exception):
-    """Raised for conditions that can be handled by the agent."""
-
-
-class FormatError(NonTerminatingException):
-    """Raised when the LM's output is not in the expected format."""
-
-
-class ExecutionTimeoutError(NonTerminatingException):
-    """Raised when the action execution timed out."""
-
+from minisweagent import Environment, Model, __version__
+from minisweagent.exceptions import InterruptAgentFlow, LimitsExceeded
+from minisweagent.utils.serialize import recursive_merge
 
-class TerminatingException(Exception):
-    """Raised for conditions that terminate the agent."""
 
+class AgentConfig(BaseModel):
+    """Check the config files in minisweagent/config for example settings."""
 
-class Submitted(TerminatingException):
-    """Raised when the LM declares that the agent has finished its task."""
-
-
-class LimitsExceeded(TerminatingException):
-    """Raised when the agent has reached its cost or step limit."""
+    system_template: str
+    """Template for the system message (the first message)."""
+    instance_template: str
+    """Template for the first user message specifying the task (the second message overall)."""
+    step_limit: int = 0
+    """Maximum number of steps the agent can take."""
+    cost_limit: float = 3.0
+    """Stop agent after exceeding (!) this cost."""
+    output_path: Path | None = None
+    """Save the trajectory to this path."""
 
 
 class DefaultAgent:
     def __init__(self, model: Model, env: Environment, *, config_class: type = AgentConfig, **kwargs):
+        """See the `AgentConfig` class for permitted keyword arguments."""
         self.config = config_class(**kwargs)
         self.messages: list[dict] = []
         self.model = model
         self.env = env
         self.extra_template_vars = {}
-
-    def render_template(self, template: str, **kwargs) -> str:
-        template_vars = asdict(self.config) | self.env.get_template_vars() | self.model.get_template_vars()
-        return Template(template, undefined=StrictUndefined).render(
-            **kwargs, **template_vars, **self.extra_template_vars
+        self.logger = logging.getLogger("agent")
+        self.cost = 0.0
+        self.n_calls = 0
+
+    def get_template_vars(self, **kwargs) -> dict:
+        return recursive_merge(
+            self.config.model_dump(),
+            self.env.get_template_vars(),
+            self.model.get_template_vars(),
+            {"n_model_calls": self.n_calls, "model_cost": self.cost},
+            self.extra_template_vars,
+            kwargs,
         )
 
-    def add_message(self, role: str, content: str, **kwargs):
-        self.messages.append({"role": role, "content": content, "timestamp": time.time(), **kwargs})
+    def _render_template(self, template: str) -> str:
+        return Template(template, undefined=StrictUndefined).render(**self.get_template_vars())
+
+    def add_messages(self, *messages: dict) -> list[dict]:
+        self.logger.debug(messages)  # set log level to debug to see
+        self.messages.extend(messages)
+        return list(messages)
+
+    def handle_uncaught_exception(self, e: Exception) -> list[dict]:
+        return self.add_messages(
+            self.model.format_message(
+                role="exit",
+                content=str(e),
+                extra={
+                    "exit_status": type(e).__name__,
+                    "submission": "",
+                    "exception_str": str(e),
+                    "traceback": traceback.format_exc(),
+                },
+            )
+        )
 
-    def run(self, task: str, **kwargs) -> tuple[str, str]:
-        """Run step() until agent is finished. Return exit status & message"""
+    def run(self, task: str = "", **kwargs) -> dict:
+        """Run step() until agent is finished. Returns dictionary with exit_status, submission keys."""
         self.extra_template_vars |= {"task": task, **kwargs}
         self.messages = []
-        self.add_message("system", self.render_template(self.config.system_template))
-        self.add_message("user", self.render_template(self.config.instance_template))
+        self.add_messages(
+            self.model.format_message(role="system", content=self._render_template(self.config.system_template)),
+            self.model.format_message(role="user", content=self._render_template(self.config.instance_template)),
+        )
         while True:
             try:
                 self.step()
-            except NonTerminatingException as e:
-                self.add_message("user", str(e))
-            except TerminatingException as e:
-                self.add_message("user", str(e))
-                return type(e).__name__, str(e)
-
-    def step(self) -> dict:
-        """Query the LM, execute the action, return the observation."""
-        return self.get_observation(self.query())
+            except InterruptAgentFlow as e:
+                self.add_messages(*e.messages)
+            except Exception as e:
+                self.handle_uncaught_exception(e)
+                raise
+            finally:
+                self.save(self.config.output_path)
+            if self.messages[-1].get("role") == "exit":
+                break
+        return self.messages[-1].get("extra", {})
+
+    def step(self) -> list[dict]:
+        """Query the LM, execute actions."""
+        return self.execute_actions(self.query())
 
     def query(self) -> dict:
-        """Query the model and return the response."""
-        if 0 < self.config.step_limit <= self.model.n_calls or 0 < self.config.cost_limit <= self.model.cost:
-            raise LimitsExceeded()
-        response = self.model.query(self.messages)
-        self.add_message("assistant", **response)
-        return response
-
-    def get_observation(self, response: dict) -> dict:
-        """Execute the action and return the observation."""
-        output = self.execute_action(self.parse_action(response))
-        observation = self.render_template(self.config.action_observation_template, output=output)
-        self.add_message("user", observation)
-        return output
-
-    def parse_action(self, response: dict) -> dict:
-        """Parse the action from the message. Returns the action."""
-        actions = re.findall(self.config.action_regex, response["content"], re.DOTALL)
-        if len(actions) == 1:
-            return {"action": actions[0].strip(), **response}
-        raise FormatError(self.render_template(self.config.format_error_template, actions=actions))
-
-    def execute_action(self, action: dict) -> dict:
-        try:
-            output = self.env.execute(action["action"])
-        except (TimeoutError, subprocess.TimeoutExpired) as e:
-            output = e.output.decode("utf-8", errors="replace") if getattr(e, "output", None) else ""
-            raise ExecutionTimeoutError(
-                self.render_template(self.config.timeout_template, action=action, output=output)
+        """Query the model and return model messages. Override to add hooks."""
+        if 0 < self.config.step_limit <= self.n_calls or 0 < self.config.cost_limit <= self.cost:
+            raise LimitsExceeded(
+                {
+                    "role": "exit",
+                    "content": "LimitsExceeded",
+                    "extra": {"exit_status": "LimitsExceeded", "submission": ""},
+                }
             )
-        self.has_finished(output)
-        return output | {"action": action["action"]}
-
-    def has_finished(self, output: dict[str, str]):
-        """Raises Submitted exception with final output if the agent has finished its task."""
-        lines = output.get("output", "").lstrip().splitlines(keepends=True)
-        if lines and lines[0].strip() in ["MINI_SWE_AGENT_FINAL_OUTPUT", "COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT"]:
-            if output.get("returncode", 0) != 0:
-                return  # Command failed - let agent see error and retry
-            raise Submitted("".join(lines[1:]))
+        self.n_calls += 1
+        message = self.model.query(self.messages)
+        self.cost += message.get("extra", {}).get("cost", 0.0)
+        self.add_messages(message)
+        return message
+
+    def execute_actions(self, message: dict) -> list[dict]:
+        """Execute actions in message, add observation messages, return them."""
+        outputs = [self.env.execute(action) for action in message.get("extra", {}).get("actions", [])]
+        return self.add_messages(*self.model.format_observation_messages(message, outputs, self.get_template_vars()))
+
+    def serialize(self, *extra_dicts) -> dict:
+        """Serialize agent state to a json-compatible nested dictionary for saving."""
+        last_message = self.messages[-1] if self.messages else {}
+        last_extra = last_message.get("extra", {})
+        agent_data = {
+            "info": {
+                "model_stats": {
+                    "instance_cost": self.cost,
+                    "api_calls": self.n_calls,
+                },
+                "config": {
+                    "agent": self.config.model_dump(mode="json"),
+                    "agent_type": f"{self.__class__.__module__}.{self.__class__.__name__}",
+                },
+                "mini_version": __version__,
+                "exit_status": last_extra.get("exit_status", ""),
+                "submission": last_extra.get("submission", ""),
+            },
+            "messages": self.messages,
+            "trajectory_format": "mini-swe-agent-1.1",
+        }
+        return recursive_merge(agent_data, self.model.serialize(), self.env.serialize(), *extra_dicts)
+
+    def save(self, path: Path | None, *extra_dicts) -> dict:
+        """Save the trajectory of the agent to a file if path is given. Returns full serialized data.
+        You can pass additional dictionaries with extra data to be (recursively) merged into the output data.
+        """
+        data = self.serialize(*extra_dicts)
+        if path:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(json.dumps(data, indent=2))
+        return data

minisweagent/agents/interactive.py

@@ -7,31 +7,45 @@ There are three modes:
 """
 
 import re
-from dataclasses import dataclass, field
-from typing import Literal
+from typing import Literal, NoReturn
 
+from prompt_toolkit.formatted_text import HTML
 from prompt_toolkit.history import FileHistory
 from prompt_toolkit.shortcuts import PromptSession
 from rich.console import Console
 from rich.rule import Rule
 
 from minisweagent import global_config_dir
-from minisweagent.agents.default import AgentConfig, DefaultAgent, LimitsExceeded, NonTerminatingException, Submitted
+from minisweagent.agents.default import AgentConfig, DefaultAgent
+from minisweagent.exceptions import LimitsExceeded, Submitted, UserInterruption
+from minisweagent.models.utils.content_string import get_content_string
 
 console = Console(highlight=False)
-prompt_session = PromptSession(history=FileHistory(global_config_dir / "interactive_history.txt"))
+_history = FileHistory(global_config_dir / "interactive_history.txt")
+_prompt_session = PromptSession(history=_history)
+_multiline_prompt_session = PromptSession(history=_history, multiline=True)
 
 
-@dataclass
 class InteractiveAgentConfig(AgentConfig):
     mode: Literal["human", "confirm", "yolo"] = "confirm"
     """Whether to confirm actions."""
-    whitelist_actions: list[str] = field(default_factory=list)
+    whitelist_actions: list[str] = []
     """Never confirm actions that match these regular expressions."""
     confirm_exit: bool = True
     """If the agent wants to finish, do we ask for confirmation from user?"""
 
 
+def _multiline_prompt() -> str:
+    return _multiline_prompt_session.prompt(
+        "",
+        bottom_toolbar=HTML(
+            "Submit message: <b fg='yellow' bg='black'>Esc, then Enter</b> | "
+            "Navigate history: <b fg='yellow' bg='black'>Arrow Up/Down</b> | "
+            "Search history: <b fg='yellow' bg='black'>Ctrl+R</b>"
+        ),
+    )
+
+
 class InteractiveAgent(DefaultAgent):
     _MODE_COMMANDS_MAPPING = {"/u": "human", "/c": "confirm", "/y": "yolo"}
 
@@ -39,28 +53,34 @@ class InteractiveAgent(DefaultAgent):
         super().__init__(*args, config_class=config_class, **kwargs)
         self.cost_last_confirmed = 0.0
 
-    def add_message(self, role: str, content: str, **kwargs):
+    def add_messages(self, *messages: dict) -> list[dict]:
         # Extend supermethod to print messages
-        super().add_message(role, content, **kwargs)
-        if role == "assistant":
-            console.print(
-                f"\n[red][bold]mini-swe-agent[/bold] (step [bold]{self.model.n_calls}[/bold], [bold]${self.model.cost:.2f}[/bold]):[/red]\n",
-                end="",
-                highlight=False,
-            )
-        else:
-            console.print(f"\n[bold green]{role.capitalize()}[/bold green]:\n", end="", highlight=False)
-        console.print(content, highlight=False, markup=False)
+        for msg in messages:
+            role, content = msg.get("role") or msg.get("type", "unknown"), get_content_string(msg)
+            if role == "assistant":
+                console.print(
+                    f"\n[red][bold]mini-swe-agent[/bold] (step [bold]{self.n_calls}[/bold], [bold]${self.cost:.2f}[/bold]):[/red]\n",
+                    end="",
+                    highlight=False,
+                )
+            else:
+                console.print(f"\n[bold green]{role.capitalize()}[/bold green]:\n", end="", highlight=False)
+            console.print(content, highlight=False, markup=False)
+        return super().add_messages(*messages)
 
     def query(self) -> dict:
         # Extend supermethod to handle human mode
         if self.config.mode == "human":
-            match command := self._prompt_and_handle_special("[bold yellow]>[/bold yellow] "):
-                case "/y" | "/c":  # Just go to the super query, which queries the LM for the next action
+            match command := self._prompt_and_handle_slash_commands("[bold yellow]>[/bold yellow] "):
+                case "/y" | "/c":
                     pass
                 case _:
-                    msg = {"content": f"\n```bash\n{command}\n```"}
-                    self.add_message("assistant", msg["content"])
+                    msg = {
+                        "role": "user",
+                        "content": f"User command: \n```bash\n{command}\n```",
+                        "extra": {"actions": [{"command": command}]},
+                    }
+                    self.add_messages(msg)
                     return msg
         try:
             with console.status("Waiting for the LM to respond..."):
@@ -68,86 +88,127 @@ class InteractiveAgent(DefaultAgent):
         except LimitsExceeded:
             console.print(
                 f"Limits exceeded. Limits: {self.config.step_limit} steps, ${self.config.cost_limit}.\n"
-                f"Current spend: {self.model.n_calls} steps, ${self.model.cost:.2f}."
+                f"Current spend: {self.n_calls} steps, ${self.cost:.2f}."
             )
             self.config.step_limit = int(input("New step limit: "))
             self.config.cost_limit = float(input("New cost limit: "))
             return super().query()
 
-    def step(self) -> dict:
+    def step(self) -> list[dict]:
         # Override the step method to handle user interruption
         try:
             console.print(Rule())
             return super().step()
         except KeyboardInterrupt:
-            # We always add a message about the interrupt and then just proceed to the next step
-            interruption_message = self._prompt_and_handle_special(
+            interruption_message = self._prompt_and_handle_slash_commands(
                 "\n\n[bold yellow]Interrupted.[/bold yellow] "
                 "[green]Type a comment/command[/green] (/h for available commands)"
                 "\n[bold yellow]>[/bold yellow] "
             ).strip()
             if not interruption_message or interruption_message in self._MODE_COMMANDS_MAPPING:
                 interruption_message = "Temporary interruption caught."
-            raise NonTerminatingException(f"Interrupted by user: {interruption_message}")
+            raise UserInterruption(
+                {
+                    "role": "user",
+                    "content": f"Interrupted by user: {interruption_message}",
+                    "extra": {"interrupt_type": "UserInterruption"},
+                }
+            )
 
-    def execute_action(self, action: dict) -> dict:
-        # Override the execute_action method to handle user confirmation
-        if self.should_ask_confirmation(action["action"]):
-            self.ask_confirmation()
-        return super().execute_action(action)
+    def execute_actions(self, message: dict) -> list[dict]:
+        # Override to handle user confirmation and confirm_exit, with try/finally to preserve partial outputs
+        actions = message.get("extra", {}).get("actions", [])
+        commands = [action["command"] for action in actions]
+        outputs = []
+        try:
+            self._ask_confirmation_or_interrupt(commands)
+            for action in actions:
+                outputs.append(self.env.execute(action))
+        except Submitted as e:
+            self._check_for_new_task_or_submit(e)
+        finally:
+            result = self.add_messages(
+                *self.model.format_observation_messages(message, outputs, self.get_template_vars())
+            )
+        return result
+
+    def _add_observation_messages(self, message: dict, outputs: list[dict]) -> list[dict]:
+        return self.add_messages(*self.model.format_observation_messages(message, outputs, self.get_template_vars()))
+
+    def _check_for_new_task_or_submit(self, e: Submitted) -> NoReturn:
+        """Check if user wants to add a new task or submit."""
+        if self.config.confirm_exit:
+            message = (
+                "[bold yellow]Agent wants to finish.[/bold yellow] "
+                "[bold green]Type new task[/bold green] or [red][bold]Esc, then enter[/bold] to quit.[/red]\n"
+                "[bold yellow]>[/bold yellow] "
+            )
+            if new_task := self._prompt_and_handle_slash_commands(message, _multiline=True).strip():
+                raise UserInterruption(
+                    {
+                        "role": "user",
+                        "content": f"The user added a new task: {new_task}",
+                        "extra": {"interrupt_type": "UserNewTask"},
+                    }
+                )
+        raise e
 
-    def should_ask_confirmation(self, action: str) -> bool:
+    def _should_ask_confirmation(self, action: str) -> bool:
         return self.config.mode == "confirm" and not any(re.match(r, action) for r in self.config.whitelist_actions)
 
-    def ask_confirmation(self) -> None:
+    def _ask_confirmation_or_interrupt(self, commands: list[str]) -> None:
+        commands_needing_confirmation = [c for c in commands if self._should_ask_confirmation(c)]
+        if not commands_needing_confirmation:
+            return
+        n = len(commands_needing_confirmation)
         prompt = (
-            "[bold yellow]Execute?[/bold yellow] [green][bold]Enter[/bold] to confirm[/green], "
-            "or [green]Type a comment/command[/green] (/h for available commands)\n"
+            f"[bold yellow]Execute {n} action(s)?[/] [green][bold]Enter[/] to confirm[/], "
+            "[red]type [bold]comment[/] to reject[/], or [blue][bold]/h[/] to show available commands[/]\n"
             "[bold yellow]>[/bold yellow] "
         )
-        match user_input := self._prompt_and_handle_special(prompt).strip():
+        match user_input := self._prompt_and_handle_slash_commands(prompt).strip():
             case "" | "/y":
                 pass  # confirmed, do nothing
             case "/u":  # Skip execution action and get back to query
-                raise NonTerminatingException("Command not executed. Switching to human mode")
+                raise UserInterruption(
+                    {
+                        "role": "user",
+                        "content": "Commands not executed. Switching to human mode",
+                        "extra": {"interrupt_type": "UserRejection"},
+                    }
+                )
             case _:
-                raise NonTerminatingException(
-                    f"Command not executed. The user rejected your command with the following message: {user_input}"
+                raise UserInterruption(
+                    {
+                        "role": "user",
+                        "content": f"Commands not executed. The user rejected your commands with the following message: {user_input}",
+                        "extra": {"interrupt_type": "UserRejection"},
+                    }
                 )
 
-    def _prompt_and_handle_special(self, prompt: str) -> str:
+    def _prompt_and_handle_slash_commands(self, prompt: str, *, _multiline: bool = False) -> str:
         """Prompts the user, takes care of /h (followed by requery) and sets the mode. Returns the user input."""
         console.print(prompt, end="")
-        user_input = prompt_session.prompt("")
+        if _multiline:
+            return _multiline_prompt()
+        user_input = _prompt_session.prompt("")
+        if user_input == "/m":
+            return self._prompt_and_handle_slash_commands(prompt, _multiline=True)
         if user_input == "/h":
             console.print(
                 f"Current mode: [bold green]{self.config.mode}[/bold green]\n"
                 f"[bold green]/y[/bold green] to switch to [bold yellow]yolo[/bold yellow] mode (execute LM commands without confirmation)\n"
                 f"[bold green]/c[/bold green] to switch to [bold yellow]confirmation[/bold yellow] mode (ask for confirmation before executing LM commands)\n"
                 f"[bold green]/u[/bold green] to switch to [bold yellow]human[/bold yellow] mode (execute commands issued by the user)\n"
+                f"[bold green]/m[/bold green] to enter multiline comment",
             )
-            return self._prompt_and_handle_special(prompt)
+            return self._prompt_and_handle_slash_commands(prompt)
         if user_input in self._MODE_COMMANDS_MAPPING:
             if self.config.mode == self._MODE_COMMANDS_MAPPING[user_input]:
-                return self._prompt_and_handle_special(
+                return self._prompt_and_handle_slash_commands(
                     f"[bold red]Already in {self.config.mode} mode.[/bold red]\n{prompt}"
                 )
             self.config.mode = self._MODE_COMMANDS_MAPPING[user_input]
             console.print(f"Switched to [bold green]{self.config.mode}[/bold green] mode.")
             return user_input
         return user_input
-
-    def has_finished(self, output: dict[str, str]):
-        try:
-            return super().has_finished(output)
-        except Submitted as e:
-            if self.config.confirm_exit:
-                console.print(
-                    "[bold green]Agent wants to finish.[/bold green] "
-                    "[green]Type a comment to give it a new task or press enter to quit.\n"
-                    "[bold yellow]>[/bold yellow] ",
-                    end="",
-                )
-                if new_task := self._prompt_and_handle_special("").strip():
-                    raise NonTerminatingException(f"The user added a new task: {new_task}")
-            raise e

minisweagent/config/README.md

@@ -1,9 +1,8 @@
 # Configs
 
-* `mini.yaml` - Default config for `mini`/`agents/interactive.py` or `mini -v`/`agents/interactive_textual.py` agent.
+* `mini.yaml` - Default config for `mini`/`agents/interactive.py` agent.
 * `default.yaml` - Default config for the `default.py` agent.
-* `github_issue.yaml` - Config for the `run/github_issue.py` entry point.
 
-## Extras
+## Benchmarks
 
-* `extra/swebench.yaml` - Config for the `run/extra/swebench.py` entry point.
+* `benchmarks/swebench.yaml` - Config for the `run/benchmarks/swebench.py` entry point.

minisweagent/config/__init__.py

@@ -1,8 +1,11 @@
 """Configuration files and utilities for mini-SWE-agent."""
 
+import json
 import os
 from pathlib import Path
 
+import yaml
+
 builtin_config_dir = Path(__file__).parent
 
 
@@ -16,6 +19,7 @@ def get_config_path(config_spec: str | Path) -> Path:
         Path(os.getenv("MSWEA_CONFIG_DIR", ".")) / config_spec,
         builtin_config_dir / config_spec,
         builtin_config_dir / "extra" / config_spec,
+        builtin_config_dir / "benchmarks" / config_spec,
     ]
     for candidate in candidates:
         if candidate.exists():
@@ -24,4 +28,35 @@ def get_config_path(config_spec: str | Path) -> Path:
     raise FileNotFoundError(f"Could not find config file for {config_spec} (tried: {candidates})")
 
 
-__all__ = ["builtin_config_dir", "get_config_path"]
+def _key_value_spec_to_nested_dict(config_spec: str) -> dict:
+    """Interpret key-value specs from the command line.
+
+    Example:
+
+    "model.model_name=anthropic/claude-sonnet-4-5-20250929"   ->
+    {"model": {"model_name": "anthropic/claude-sonnet-4-5-20250929"}}
+    """
+    key, value = config_spec.split("=", 1)
+    try:
+        value = json.loads(value)
+    except json.JSONDecodeError:
+        pass
+    keys = key.split(".")
+    result = {}
+    current = result
+    for k in keys[:-1]:
+        current[k] = {}
+        current = current[k]
+    current[keys[-1]] = value
+    return result
+
+
+def get_config_from_spec(config_spec: str | Path) -> dict:
+    """Get a config from a config spec."""
+    if isinstance(config_spec, str) and "=" in config_spec:
+        return _key_value_spec_to_nested_dict(config_spec)
+    path = get_config_path(config_spec)
+    return yaml.safe_load(path.read_text())
+
+
+__all__ = ["builtin_config_dir", "get_config_path", "get_config_from_spec", "_key_value_spec_to_nested_dict"]