Configuration Reference

Use this page for exact config model fields. All config schemas are pydantic.BaseModel types. For examples and operational guidance, see Configuration Guide.

nomad.config.resolve_symbol(dotted_path)

Resolve a dotted path to a Python object.

Parameters:

dotted_path (str)

Return type:

Any

class nomad.config.TorchModuleConfig(*, model_class, name_or_path, tool_name=None, batch_size=None, **extra_data)

Configuration entry for a nomad.fm_base_tool.TorchModuleTool.

Parameters:

  • model_class (str)

  • name_or_path (str)

  • tool_name (str | None)

  • batch_size (int | None)

  • extra_data (Any)

model_class: str

Dotted import path for a class with a from_pretrained constructor.

name_or_path: str

Model weights URI or legacy source resolved by nomad.hub.RepoSpec.

tool_name: str | None

Optional public MCP tool name override.

batch_size: int | None

Optional maximum batch size override.

resolve_spec(*, base_dir=None)

Resolve name_or_path to a normalized model source specification.

Parameters:

base_dir (TypeAliasForwardRef('pathlib.Path') | None)

Return type:

RepoSpec

resolve_source(*, base_dir=None)

Resolve name_or_path to a loadable local path.

Parameters:

base_dir (TypeAliasForwardRef('pathlib.Path') | None)

Return type:

str | TypeAliasForwardRef(‘pathlib.Path’)

instantiate(*, base_dir=None, **overrides)

Instantiate the configured model class from its configured source.

Parameters:

base_dir (TypeAliasForwardRef('pathlib.Path') | None)

Return type:

TorchModuleTool

build_tool(*, base_dir=None, **overrides)

Instantiate the tool and apply name and batching overrides.

Parameters:

base_dir (TypeAliasForwardRef('pathlib.Path') | None)

Return type:

TorchModuleTool

add_to_fastmcp(server, *, base_dir=None)

Instantiate and register this model tool on a FastMCP server.

Parameters:

  • server (FastMCP)

  • base_dir (TypeAliasForwardRef('pathlib.Path') | None)

class nomad.config.ToolConfig(*, tool, name=None, tool_kwargs=None, **extra_data)

Configuration entry for a regular Python callable exposed as a tool.

Parameters:

  • tool (str)

  • name (str | None)

  • tool_kwargs (dict | None)

  • extra_data (Any)

tool: str

Dotted import path for the callable or callable factory.

name: str | None

Optional public MCP tool name.

tool_kwargs: dict | None

Optional keyword arguments used to instantiate callable factories.

property fn

Resolve and optionally instantiate the configured callable.

set_name()
classmethod simple_tool(tool)
Parameters:

tool (str | dict)

Return type:

dict

add_to_fastmcp(server)

Register this callable on a FastMCP server.

Parameters:

server (FastMCP)

class nomad.config.ToolManagerConfig(*, enabled=True, idle_seconds=300.0, max_pending_per_tool=None, max_devices_per_tool=None, gc_idle_seconds=300.0, disk_idle_seconds=600.0)

Configuration for the optional Torch model tool manager.

Parameters:

  • enabled (bool)

  • idle_seconds (float | None)

  • max_pending_per_tool (int | None)

  • max_devices_per_tool (int | None)

  • gc_idle_seconds (float | None)

  • disk_idle_seconds (float | None)

enabled: bool

Whether nomad serve should route model tools through the manager.

idle_seconds: float | None

Idle seconds before reducing a tool’s device allocation by one slot. None disables device-slot idle eviction.

max_pending_per_tool: int | None

Maximum queued requests per tool. None disables the queue limit.

max_devices_per_tool: int | None

Maximum device slots one tool may occupy. None uses all managed slots.

gc_idle_seconds: float | None

Server idle seconds before clearing unused Python and accelerator caches. None disables cache clearing.

disk_idle_seconds: float | None

Tool idle seconds after full offload before dropping the resident instance. None keeps resident instances loaded.

instantiate(*, device_provider=None, **overrides)

Create a nomad.torch_tool_manager.TorchModelToolManager.

class nomad.config.TelemetryConfig(*, enabled=None, service_name='nomad', otlp_endpoint=None)

OpenTelemetry exporter configuration for nomad serve.

Parameters:

  • enabled (bool | None)

  • service_name (str)

  • otlp_endpoint (str | None)

enabled: bool | None

Enable OTel exporter setup. None enables it when OTel env vars exist.

service_name: str

OpenTelemetry service.name for server spans and metrics.

otlp_endpoint: str | None

Optional OTLP/gRPC endpoint. Environment variables are used when unset.

class nomad.config.SearchWeights(*, tantivy_score=1.0, name_field=3.0, import_path_field=2.0, title_field=1.5, description_field=1.0, arguments_field=1.25, exact_name=12.0, prefix_name=8.0, suffix_name=4.0, substring_name=2.0)

Weights for tool search ranking.

Parameters:
tantivy_score: float
name_field: float
import_path_field: float
title_field: float
description_field: float
arguments_field: float
exact_name: float
prefix_name: float
suffix_name: float
substring_name: float
class nomad.config.SearchToolConfig(*, expose=False, candidate_limit=50, weights=<factory>)

Search behavior and ranking configuration.

Parameters:
expose: bool

Expose a search_tools tool when launched with nomad serve.

candidate_limit: int

Upper limit on Tantivy candidates retrieved during ranked search.

weights: SearchWeights

Factors controlling search result rankings.

class nomad.config.ServerConfig(*, context_dir=<factory>, fmod_models=<factory>, tools=<factory>, tool_manager=<factory>, search_tool=<factory>, telemetry=<factory>)

Top-level configuration consumed by nomad serve.

Parameters:
context_dir: Path

Directory used to resolve paths relative to the config file.

fmod_models: list[TorchModuleConfig]

Torch model tools to load and expose.

tools: list[ToolConfig]

Regular Python tools to import and expose.

tool_manager: ToolManagerConfig

Torch model scheduling and device management options.

search_tool: SearchToolConfig

Optional MCP tool discovery settings.

telemetry: TelemetryConfig

OpenTelemetry exporter settings for server metrics and tracing.

instantiate_model(fmod, **overrides)

Instantiate one model entry relative to this config file.

Parameters:

fmod (TorchModuleConfig)

Return type:

TorchModuleTool

build_tool(fmod, **overrides)

Instantiate one model entry and apply configured tool overrides.

Parameters:

fmod (TorchModuleConfig)

Return type:

TorchModuleTool

classmethod from_file(path)

Load a YAML or JSON server config from disk.

Parameters:

path (str | TypeAliasForwardRef('pathlib.Path'))

Return type:

ServerConfig

class nomad.gateway.config.SandboxLimits(*, timeout_seconds=30.0, stdout_limit=65536, stderr_limit=65536, result_limit=65536, workspace_root=<factory>)

Execution limits applied to sandboxed Python runs.

Parameters:

  • timeout_seconds (float)

  • stdout_limit (int)

  • stderr_limit (int)

  • result_limit (int)

  • workspace_root (Path | None)

timeout_seconds: float

Maximum sandbox run time in seconds.

stdout_limit: int

Maximum captured stdout size in bytes.

stderr_limit: int

Maximum captured stderr size in bytes.

result_limit: int

Maximum serialized RESULT size in bytes.

workspace_root: Path | None

Working directory used for sandboxed script execution.

class nomad.gateway.config.GatewayDefaults(*, timeout_seconds=30.0, stdout_limit=65536, stderr_limit=65536, result_limit=65536, workspace_root=<factory>, wrappers_package='mcp_tools')

Base defaults merged with per-request overrides.

Parameters:

  • timeout_seconds (float)

  • stdout_limit (int)

  • stderr_limit (int)

  • result_limit (int)

  • workspace_root (Path | None)

  • wrappers_package (str)

wrappers_package: str

Python package name used for generated MCP tool wrappers.

class nomad.gateway.config.MiddlewareConfig(*, kind, options=<factory>)

Generic middleware configuration entry.

Parameters:
kind: str

Middleware implementation name.

options: dict[str, Any]

Implementation-specific middleware options.

class nomad.gateway.config.AllowlistMiddlewareConfig(*, kind='allowlist', options=<factory>, allow=<factory>, deny=<factory>)

Allow or deny upstream tools by server:tool glob patterns.

Parameters:
kind: Literal['allowlist']

Middleware implementation name.

allow: Sequence[str]

Allowed server:tool patterns. Empty means allow all not denied.

deny: Sequence[str]

Denied server:tool patterns.

class nomad.gateway.config.LoggingMiddlewareConfig(*, kind='logging', options=<factory>, level='info')

Structured logging middleware configuration.

Parameters:
kind: Literal['logging']

Middleware implementation name.

level: Literal['debug', 'info', 'warning', 'error']

Log level used for upstream tool invocation records.

class nomad.gateway.config.RedactionMiddlewareConfig(*, kind='redaction', options=<factory>, mode='basic')

Response redaction middleware configuration.

Parameters:
kind: Literal['redaction']

Middleware implementation name.

mode: Literal['basic', 'none']

Redaction mode for upstream tool responses.

class nomad.gateway.config.TelemetryConfig(*, enabled=None, service_name='nomad-gateway', otlp_endpoint=None)

OpenTelemetry exporter configuration for the gateway process.

Parameters:

  • enabled (bool | None)

  • service_name (str)

  • otlp_endpoint (str | None)

enabled: bool | None

Enable OTel exporter setup. None enables it when OTel env vars exist.

service_name: str

OpenTelemetry service.name for gateway spans.

otlp_endpoint: str | None

Optional OTLP/gRPC endpoint. Environment variables are used when unset.

class nomad.gateway.config.GatewayConfig(*, servers=<factory>, defaults=<factory>, middleware=<factory>, telemetry=<factory>)

Top-level configuration for the MCP gateway.

Parameters:
servers: dict[str, ServerParameters | dict[str, Any]]

Upstream MCP servers keyed by local server ID.

defaults: GatewayDefaults

Default sandbox runtime options.

middleware: Sequence[MiddlewareEntry]

Middleware entries applied to upstream tool calls.

telemetry: TelemetryConfig

OpenTelemetry exporter settings for gateway tracing.

classmethod from_file(path)

Load a YAML, JSON, or TOML gateway config from disk.

Parameters:

path (str | TypeAliasForwardRef('pathlib.Path'))

Return type:

GatewayConfig

class nomad.gateway.config.GatewayRuntimeOptions(timeout_seconds, stdout_limit, stderr_limit, result_limit, workspace_root, wrappers_root, wrappers_package, python_executable)

Runtime options computed from config and request overrides.

Parameters:

  • timeout_seconds (float | None)

  • stdout_limit (int)

  • stderr_limit (int)

  • result_limit (int)

  • workspace_root (TypeAliasForwardRef('pathlib.Path') | None)

  • wrappers_root (pathlib.Path)

  • wrappers_package (str)

  • python_executable (pathlib.Path)

timeout_seconds: float | None
stdout_limit: int
stderr_limit: int
result_limit: int
workspace_root: Path | None
wrappers_root: Path
wrappers_package: str
python_executable: Path
classmethod from_defaults_and_overrides(defaults, overrides=None, *, wrappers_root)
Parameters:
Return type:

GatewayRuntimeOptions