serena.config.serena_config

Contents

serena.config.serena_config#

Source code: serena/config/serena_config.py

The Serena Model Context Protocol (MCP) Server

class ToolInclusionDefinition(excluded_tools=(), included_optional_tools=(), fixed_tools=())[source]#

Bases: object

Defines which tools to include/exclude in Serena’s operation. This can mean either

  • defining exclusions/inclusions to apply to an existing set of tools [incremental mode], or

  • defining a fixed set of tools to use [fixed mode].

Parameters:

  • excluded_tools (Sequence[str])

  • included_optional_tools (Sequence[str])

  • fixed_tools (Sequence[str])

excluded_tools: Sequence[str] = ()#

the names of tools to exclude from use [incremental mode]

included_optional_tools: Sequence[str] = ()#

the names of optional tools to include [incremental mode]

fixed_tools: Sequence[str] = ()#

the names of tools to use as a fixed set of tools [fixed mode]

class NamedToolInclusionDefinition(
excluded_tools: collections.abc.Sequence[str] = (),
included_optional_tools: collections.abc.Sequence[str] = (),
fixed_tools: collections.abc.Sequence[str] = (),
name: str | None = None,
)[source]#

Bases: ToolInclusionDefinition

Parameters:

  • excluded_tools (Sequence[str])

  • included_optional_tools (Sequence[str])

  • fixed_tools (Sequence[str])

  • name (str | None)

class ModeSelectionDefinition(default_modes: collections.abc.Sequence[str] | None = None)[source]#

Bases: object

Parameters:

default_modes (Sequence[str] | None)

class ModeSelectionDefinitionWithBaseModes(
default_modes: collections.abc.Sequence[str] | None = None,
base_modes: collections.abc.Sequence[str] | None = ('interactive', 'editing'),
)[source]#

Bases: ModeSelectionDefinition

Parameters:

  • default_modes (Sequence[str] | None)

  • base_modes (Sequence[str] | None)

base_modes: Sequence[str] | None = ('interactive', 'editing')#

the base modes to use, which are always guaranteed to be included

class ModeSelectionDefinitionWithAddedModes(
default_modes: collections.abc.Sequence[str] | None = None,
added_modes: collections.abc.Sequence[str] | None = None,
)[source]#

Bases: ModeSelectionDefinition

Parameters:

  • default_modes (Sequence[str] | None)

  • added_modes (Sequence[str] | None)

class LanguageBackend(
value,
names=<not given>,
*values,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)[source]#

Bases: Enum

LSP = 'LSP'#

Use the language server protocol (LSP), spawning freely available language servers via the SolidLSP library that is part of Serena

JETBRAINS = 'JetBrains'#

Use the Serena plugin in your JetBrains IDE. (requires the plugin to be installed and the project being worked on to be open in your IDE)

get_lsp_tool_class_replacements()[source]#
Returns:

mapping from LSP tool classes to replacement tool classes (functional replacements)

Return type:

dict[type[Tool], type[Tool]]

class LineEnding(
value,
names=<not given>,
*values,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)[source]#

Bases: Enum

Line ending convention for file writes.

property newline_str: str | None#

The newline parameter value for open() and Path.write_text().

Returns None for native mode (platform default).

classmethod from_str(value)[source]#

Parse a string value into a LineEnding.

Parameters:

value (str)

Return type:

LineEnding

class SharedConfig(
excluded_tools=(),
included_optional_tools=(),
fixed_tools=(),
symbol_info_budget=None,
language_backend=None,
line_ending=None,
read_only_memory_patterns=<factory>,
ignored_memory_patterns=<factory>,
ls_specific_settings=<factory>,
)[source]#

Bases: ToolInclusionDefinition, ToStringMixin

Shared between SerenaConfig and ProjectConfig, the latter used to override values in the form (same as in ModeSelectionDefinition). The defaults here shall be none and should be set to the global default values in SerenaConfig.

Parameters:

  • excluded_tools (Sequence[str])

  • included_optional_tools (Sequence[str])

  • fixed_tools (Sequence[str])

  • symbol_info_budget (float | None)

  • language_backend (LanguageBackend | None)

  • line_ending (LineEnding | None)

  • read_only_memory_patterns (list[str])

  • ignored_memory_patterns (list[str])

  • ls_specific_settings (dict)

ls_specific_settings: dict#

Advanced configuration option allowing to configure language server implementation specific options, see SolidLSPSettings for more info.

exception SerenaConfigError[source]#

Bases: Exception

DEFAULT_PROJECT_SERENA_FOLDER_LOCATION = '$projectDir/.serena'#

The default template for the project Serena folder location. Uses $projectDir and $projectFolderName as placeholders.

class ProjectConfigAutoGenerationMode(
value,
names=<not given>,
*values,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)[source]#

Bases: Enum

NONE = 'none'#

no auto-generation

SYNCHRONOUS = 'sync'#

synchronous auto-generation, i.e. the configuration is fully generated before returning from the function call

ASYNCHRONOUS = 'async'#

asynchronous auto-generation, where time-consuming configuration parts (currently only the list of programming languages) are determined in a background thread and initialised as empty

class ProjectConfig(default_modes: collections.abc.Sequence[str] | None = None, added_modes: collections.abc.Sequence[str] | None = None, excluded_tools: collections.abc.Sequence[str] = (), included_optional_tools: collections.abc.Sequence[str] = (), fixed_tools: collections.abc.Sequence[str] = (), symbol_info_budget: float | None = None, language_backend: serena.config.serena_config.LanguageBackend | None = None, line_ending: serena.config.serena_config.LineEnding | None = None, read_only_memory_patterns: list[str] = <factory>, ignored_memory_patterns: list[str] = <factory>, ls_specific_settings: dict = <factory>, *, project_name: str, language_servers: list[solidlsp.ls_config.LanguageServerId], ignored_paths: list[str] = <factory>, ls_workspace_folders: list[str] = <factory>, ls_additional_workspace_folders: list[str] = <factory>, read_only: bool = False, ignore_all_files_in_gitignore: bool = True, initial_prompt: str = '', encoding: str = 'utf-8', activation_command: str | None = None, activation_command_timeout: float = 180.0, _local_override_keys: list[str] = <factory>)[source]#

Bases: SharedConfig, ModeSelectionDefinitionWithAddedModes

Parameters:

  • default_modes (Sequence[str] | None)

  • added_modes (Sequence[str] | None)

  • excluded_tools (Sequence[str])

  • included_optional_tools (Sequence[str])

  • fixed_tools (Sequence[str])

  • symbol_info_budget (float | None)

  • language_backend (LanguageBackend | None)

  • line_ending (LineEnding | None)

  • read_only_memory_patterns (list[str])

  • ignored_memory_patterns (list[str])

  • ls_specific_settings (dict)

  • project_name (str)

  • language_servers (list[LanguageServerId])

  • ignored_paths (list[str])

  • ls_workspace_folders (list[str])

  • ls_additional_workspace_folders (list[str])

  • read_only (bool)

  • ignore_all_files_in_gitignore (bool)

  • initial_prompt (str)

  • encoding (str)

  • activation_command (str | None)

  • activation_command_timeout (float)

  • _local_override_keys (list[str])

YAML_COMMENT_NORMALISATION = 'leading'#

the comment normalisation strategy to use when loading/saving project configuration files. The template file must match this configuration (i.e. it must use leading comments if this is set to LEADING).

classmethod autogenerate(
project_root,
serena_config,
project_name=None,
languages=None,
save_to_disk=True,
interactive=False,
asynchronous=False,
)[source]#

Autogenerate a project configuration for a given project root.

Parameters:

  • project_root (str | Path) – the path to the project root

  • serena_config (SerenaConfig) – the global Serena configuration

  • project_name (str | None) – the name of the project; if None, the name of the project will be the name of the directory containing the project

  • languages (list[LanguageServerId] | None) – the languages of the project; if None, they will be determined automatically

  • save_to_disk (bool) – whether to save the project configuration to disk

  • interactive (bool) – whether to run in interactive CLI mode, asking the user for input where appropriate

  • asynchronous (bool) – whether to run in asynchronous mode, where time-consuming configuration parts (currently only the determination of the list of programming languages) are determined in a background thread and initialised as empty

Returns:

the project configuration

Return type:

Self

await_asynchronous_completion()[source]#

Wait for the asynchronous auto-generation of the configuration to complete (if applicable), ensuring that, in particular, the list of programming languages is complete, which may be determined asynchronously when first creating the project configuration.

classmethod default_project_yml_path(project_root)[source]#
Returns:

the default path to the project.yml file (inside $projectDir/.serena/). This is suitable as a fallback when no SerenaConfig is available to resolve a potentially customised location.

Parameters:

project_root (str | Path)

Return type:

str

classmethod load(
project_root,
serena_config,
autogen=ProjectConfigAutoGenerationMode.NONE,
)[source]#

Load a ProjectConfig instance from the path to the project root.

Parameters:

  • project_root (Path | str) – the path to the project root

  • serena_config (SerenaConfig) – the global Serena configuration

  • autogen (ProjectConfigAutoGenerationMode) – the auto-generation mode to apply if the project configuration does not yet exist

Return type:

Self

save(project_yml_path, save_project_local_yml=True)[source]#

Saves the project configuration to disk, updating both the project.yml file and, optionally, the project.local.yml file to reflect overridden keys.

Keys that are overridden by project.local.yml are not updated in project.yml. Only keys that are overridden are updated in project.local.yml.

Parameters:

  • project_yml_path (str) – the path to the project.yml file

  • save_project_local_yml (bool) – whether to also update the project.local.yml file to reflect overridden keys

Return type:

None

class RegisteredProject(project_root, project_config, project_instance=None)[source]#

Bases: ToStringMixin

Represents a registered project in the Serena configuration.

Parameters:

  • project_root (str) – the root directory of the project

  • project_config (ProjectConfig) – the configuration of the project

  • project_instance (Project | None) – an existing project instance (if already loaded)

classmethod from_project_root(
project_root,
serena_config,
autogen=ProjectConfigAutoGenerationMode.NONE,
)[source]#

Creates a RegisteredProject instance from a project root path, which must exist on disk.

Parameters:

  • project_root (str | Path) – path to an existing directory

  • serena_config (SerenaConfig) – the Serena configuration

  • autogen (ProjectConfigAutoGenerationMode) – the auto-generation mode to use for the project configuration if it does not yet exist

Returns:

the RegisteredProject instance

Return type:

RegisteredProject

matches_root_path(path)[source]#

Check if the given path matches the project root path.

Parameters:

path (str | Path) – the path to check

Returns:

True if the path matches the project root, False otherwise (including the case where this project’s root directory no longer exists, e.g. a removed git worktree)

Return type:

bool

get_project_instance(serena_config)[source]#

Returns the project instance for this registered project, loading it if necessary.

Parameters:

serena_config (SerenaConfig)

Return type:

Project

class SerenaConfig(
default_modes=None,
base_modes=('interactive',
'editing'),
excluded_tools=(),
included_optional_tools=(),
fixed_tools=(),
read_only_memory_patterns=<factory>,
ignored_memory_patterns=<factory>,
ls_specific_settings=<factory>,
*,
symbol_info_budget=10.0,
language_backend=LanguageBackend.LSP,
line_ending=LineEnding.NATIVE,
projects=<factory>,
gui_log_window=False,
log_level=20,
trace_lsp_communication=False,
web_dashboard=True,
web_dashboard_open_on_launch=True,
web_dashboard_interface=None,
web_dashboard_listen_address='127.0.0.1',
web_dashboard_trusted_hosts=<factory>,
jetbrains_plugin_server_address='127.0.0.1',
jetbrains_launch_command=None,
tool_timeout=240,
token_count_estimator='CHAR_COUNT',
default_max_tool_answer_chars=150000,
ignored_paths=<factory>,
project_serena_folder_location='$projectDir/.serena',
trusted_project_path_patterns=<factory>,
ls_priorities=None,
_loaded_commented_yaml=None,
_config_file_path=None,
)[source]#

Bases: SharedConfig, ModeSelectionDefinitionWithBaseModes

Holds the Serena agent configuration, which is typically loaded from a YAML configuration file (when instantiated via from_config_file()), which is updated when projects are added or removed. For testing purposes, it can also be instantiated directly with the desired parameters.

Parameters:

  • default_modes (Sequence[str] | None)

  • base_modes (Sequence[str] | None)

  • excluded_tools (Sequence[str])

  • included_optional_tools (Sequence[str])

  • fixed_tools (Sequence[str])

  • read_only_memory_patterns (list[str])

  • ignored_memory_patterns (list[str])

  • ls_specific_settings (dict)

  • symbol_info_budget (float)

  • language_backend (LanguageBackend)

  • line_ending (LineEnding)

  • projects (list[RegisteredProject])

  • gui_log_window (bool)

  • log_level (int)

  • trace_lsp_communication (bool)

  • web_dashboard (bool)

  • web_dashboard_open_on_launch (bool)

  • web_dashboard_interface (str | None)

  • web_dashboard_listen_address (str)

  • web_dashboard_trusted_hosts (list[str])

  • jetbrains_plugin_server_address (str)

  • jetbrains_launch_command (str | None)

  • tool_timeout (float)

  • token_count_estimator (str)

  • default_max_tool_answer_chars (int)

  • ignored_paths (list[str])

  • project_serena_folder_location (str)

  • trusted_project_path_patterns (list[str])

  • ls_priorities (dict[str, int] | None)

  • _loaded_commented_yaml (CommentedMap | None)

  • _config_file_path (str | None)

jetbrains_launch_command: str | None = None#

JetBrains IDE launch command, which can be used to auto-start an IDE instance on demand.

tool_timeout: float = 240#

timeout for tool calls in seconds; if a tool takes longer than this, it is aborted and an error is returned.

token_count_estimator: str = 'CHAR_COUNT'#

Only relevant if record_tool_usage is True; the name of the token count estimator to use for tool usage statistics. See the RegisteredTokenCountEstimator enum for available options.

Note: some token estimators (like tiktoken) may require downloading data files on the first run, which can take some time and require internet access. Others, like the Anthropic ones, may require an API key and rate limits may apply.

default_max_tool_answer_chars: int = 150000#

Used as default for tools where the apply method has a default maximal answer length. Even though the value of the max_answer_chars can be changed when calling the tool, it may make sense to adjust this default through the global configuration.

ignored_paths: list[str]#

List of paths to ignore across all projects. Same syntax as gitignore, so you can use * and **. These patterns are merged additively with each project’s own ignored_paths.

project_serena_folder_location: str = '$projectDir/.serena'#

Template for the location of the per-project .serena data folder (memories, caches, etc.). Supports the following placeholders:

  • $projectDir: the absolute path to the project root directory

  • $projectFolderName: the name of the project folder

Examples:

  • “$projectDir/.serena” (default, stores data inside the project)

  • “/projects-metadata/$projectFolderName/.serena” (stores data in a central location)

trusted_project_path_patterns: list[str]#

list of glob patterns for project root directories that are considered trusted. The default “**” considers all project roots as trusted, which is necessary for backward compatibility. The default will apply if a user does not yet have the setting, while new users will get the value defined in the configuration template file.

ls_priorities: dict[str, int] | None = None#

mapping from language server keys to their priority (higher number = higher priority).

language_backend: LanguageBackend = 'LSP'#

the language backend to use for code understanding features

symbol_info_budget: float = 10.0#

Time budget (seconds) for requests when tools request include_info (currently only supported for LSP-based tools).

If the budget is exceeded, Serena stops issuing further requests and returns partial info results. 0 disables the budget (no early stopping). Negative values are invalid.

classmethod get_config_file_creation_date()[source]#
Returns:

the creation date of the configuration file, or None if the configuration file does not exist

Return type:

datetime | None

classmethod from_config_file(generate_if_missing=True)[source]#

Static constructor to create SerenaConfig from the configuration file

Parameters:

generate_if_missing (bool)

Return type:

SerenaConfig

classmethod init(language_backend)[source]#

Supports the config initialisation CLI command, allowing the user to configure fundamental settings before the first launch.

Parameters:

language_backend (LanguageBackend) – the language backend to use

Returns:

the created SerenaConfig instance

Return type:

SerenaConfig

with_headless_mode_overrides()[source]#

Modifies this instance to apply overrides for headless mode, where any GUI/user interaction-based features are disabled. This is intended to be applied for cases where a SerenaConfig instance is needed to instantiate a SerenaAgent instance while the user is not expected to interact with the system (e.g. a CLI command or a test).

Returns:

the instance with overrides applied for headless mode

Return type:

SerenaConfig

get_registered_project(project_root_or_name, autoregister=False)[source]#
Parameters:

  • project_root_or_name (str) – path to the project root or the name of the project

  • autoregister (bool) – whether to auto-register projects that are not yet registered in Serena’s global configuration but have an existing project configuration file. Project configuration files are never auto-generated.

Returns:

the registered project, or None if not found

Return type:

RegisteredProject | None

add_registered_project(registered_project)[source]#

Adds a registered project, persisting the updated project list

Parameters:

registered_project (RegisteredProject)

Return type:

None

add_project_from_path(project_root, asynchronous_autogen=False)[source]#

Adds a new project to the Serena configuration from a given path, auto-generating the project with defaults if it does not exist. Will raise a FileExistsError if a project already exists at the path.

Parameters:

  • project_root (Path | str) – the path to the project to add

  • asynchronous_autogen (bool) – whether to use asynchronous auto-generation for the project configuration

Returns:

the project that was added

Return type:

Project

get_configured_project_serena_folder(project_root)[source]#

Returns the resolved absolute path to the .serena data folder for a project, applying placeholder substitution to project_serena_folder_location without any fallback logic.

Parameters:

project_root (str | Path) – the absolute path to the project root directory

Returns:

the resolved absolute path to the project’s .serena folder

Raises:

SerenaConfigError – if the template contains an unknown placeholder

Return type:

str

get_project_serena_folder(project_root)[source]#

Resolves the location of the project’s .serena data folder using fallback logic:

  1. If the folder exists at the configured path (project_serena_folder_location), use it.

  2. Otherwise, if it exists at the default location inside the project root, use that.

  3. If neither exists, return the configured path (for creation).

Parameters:

project_root (str | Path) – the absolute path to the project root directory

Returns:

the resolved absolute path to the .serena data folder

Raises:

SerenaConfigError – if the configured template contains an unknown placeholder

Return type:

str

get_project_yml_location(project_root)[source]#

Returns the resolved absolute path to the project.yml configuration file, based on the resolved .serena data folder (with fallback logic).

Parameters:

project_root (str | Path) – the absolute path to the project root directory

Returns:

the resolved absolute path to the project’s project.yml file

Return type:

str

propagate_settings()[source]#

Propagate settings from this configuration to individual components that are statically configured

Return type:

None

is_trusted_project_path(project_root)[source]#

Checks if the given project root path matches any of the trusted project root patterns.

Parameters:

project_root (str | Path) – the path to the project root directory

Returns:

True if the project root is trusted, False otherwise

Return type:

bool

get_ls_priority(ls_id)[source]#

Gets the priority value associated with a language server

Parameters:

ls_id (LanguageServerId) – identifies the language server

Returns:

the integer priority

Return type:

int