Skip to content

annotools.config

Defaults for every preview, grid, and overlay call. Library functions read these at call time whenever a parameter is None; the MCP server resolves them once at start-up so its tool schemas advertise concrete values.

config

Project-wide defaults, resolved once from CLI arguments, ANNOTOOLS_* environment variables, and code.

OutputFormat module-attribute 

OutputFormat = Literal['jpeg', 'png', 'webp']

Encodings a preview can be returned in.

GridMode module-attribute 

GridMode = Literal['ratio', 'fixed']

ratio: a fixed number of equal cells; fixed: cells of a given pixel size.

Settings

Bases: BaseSettings

Process-wide defaults for previews, grids, overlays, and encoding.

One object serves both audiences: the annotools command resolves it once from flags and ANNOTOOLS_* variables and bakes the values into the MCP tool schemas; library callers read it through get_settings at call time, so every None parameter falls back to these values.

Precedence: annotools command-line flags (--max-width), then ANNOTOOLS_<FIELD> environment variables (ANNOTOOLS_MAX_WIDTH), then the field defaults. Empty environment values are ignored; invalid values raise a pydantic.ValidationError naming the field.

Examples:

>>> from annotools import Settings
>>> Settings(max_width=768, grid_columns=8).grid_columns
8
References
  • Spec: .agents/knowledge/spec/mcp-overview.md (annotools repository), settings table.
  • 384 px default: Gemini bills an image up to 384x384 as one 258-token unit, https://ai.google.dev/gemini-api/docs/image-understanding (verified 2026-08-27); Claude and GPT bill by area, so pass 768+ for them (skills/mllm-multimodal-input).

get_settings 

get_settings() -> Settings

Return the process-wide Settings, resolving them from the environment on first use.

Library functions call this whenever a parameter is None; the result is cached until configure or reset_settings replaces it.

Returns:

Type Description
Settings

The active settings object (shared, not a copy).

Examples:

>>> from annotools import get_settings
>>> get_settings().max_width
384
Source code in src/annotools/config.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def get_settings() -> Settings:
    """Return the process-wide [`Settings`][annotools.Settings], resolving them from the environment on first use.

    Library functions call this whenever a parameter is ``None``; the result is cached until
    [`configure`][annotools.configure] or [`reset_settings`][annotools.reset_settings] replaces it.

    Returns:
        The active settings object (shared, not a copy).

    Examples:
        >>> from annotools import get_settings
        >>> get_settings().max_width
        384
    """
    global _settings
    if _settings is None:
        _settings = Settings()
    return _settings

configure 

configure(settings: Settings) -> None

Replace the process-wide settings.

Library functions read get_settings at call time, so the new values apply to every later call. The MCP tool schemas snapshot the settings when annotools.mcp.server is first imported; call this before that import (as annotools.mcp.cli does) to change the defaults the server advertises.

Parameters:

Name Type Description Default
settings Settings

The settings to install, typically built from flags or code.

 required

Examples:

>>> from annotools import Settings, configure, get_settings, reset_settings
>>> configure(Settings(max_width=200))
>>> get_settings().max_width
200
>>> reset_settings()
Source code in src/annotools/config.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def configure(settings: Settings) -> None:
    """Replace the process-wide settings.

    Library functions read [`get_settings`][annotools.get_settings] at call time, so the new values apply to every later
    call. The MCP tool schemas snapshot the settings when ``annotools.mcp.server`` is first imported;
    call this before that import (as ``annotools.mcp.cli`` does) to change the defaults the server
    advertises.

    Args:
        settings: The settings to install, typically built from flags or code.

    Examples:
        >>> from annotools import Settings, configure, get_settings, reset_settings
        >>> configure(Settings(max_width=200))
        >>> get_settings().max_width
        200
        >>> reset_settings()
    """
    global _settings
    _settings = settings

reset_settings 

reset_settings() -> None

Forget the resolved settings so the next get_settings reads the environment again.

Meant for tests and interactive sessions; production code calls configure instead.

Examples:

>>> from annotools import Settings, configure, get_settings, reset_settings
>>> configure(Settings(max_width=200))
>>> reset_settings()
>>> get_settings().max_width
384
Source code in src/annotools/config.py 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
def reset_settings() -> None:
    """Forget the resolved settings so the next [`get_settings`][annotools.get_settings] reads the environment again.

    Meant for tests and interactive sessions; production code calls [`configure`][annotools.configure] instead.

    Examples:
        >>> from annotools import Settings, configure, get_settings, reset_settings
        >>> configure(Settings(max_width=200))
        >>> reset_settings()
        >>> get_settings().max_width
        384
    """
    global _settings
    _settings = None