search_model_files

Search file contents in a Bridge Town model for a text or regex pattern — grep-style, so you can answer ‘where does this string appear in this model?’ without reading full files one at a time. pattern is a literal, case-insensitive substring by default; set regex=True to treat it as a Python regular expression, and case_sensitive=True for case-sensitive matching either way.

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model.')]	Yes	—
pattern	Annotated[str, Field(description='Text to search for. A literal, case-insensitive substring by default; set regex=True to treat it as a Python regular expression.')]	Yes	—
path	Annotated[str, Field(description="Optional subtree path to scope the search to (e.g. 'model' to search only model files). A single harmless trailing slash (e.g. 'model/') is stripped automatically. Omit to search the whole model.")]	No	''
file_glob	Annotated[str, Field(description="Optional glob to filter which files are searched (e.g. '*.py', 'model/**/*.py'), same syntax as list_files' pattern parameter.")]	No	''
branch	`Annotated[str	None, Field(description=“Branch to search. Defaults to the model’s default branch when omitted or null.”)]`	No	None
context_lines	Annotated[int, Field(description=f'Number of lines of context to include before/after each match. Defaults to {_SEARCH_DEFAULT_CONTEXT_LINES}, max {_SEARCH_MAX_CONTEXT_LINES}.')]	No	2
max_matches	Annotated[int, Field(description=f'Maximum number of matches to return across all files. Defaults to {_SEARCH_DEFAULT_MAX_MATCHES}, max {_SEARCH_MAX_MATCHES_CAP}.')]	No	200
max_files	Annotated[int, Field(description=f'Maximum number of files to scan. Defaults to {_SEARCH_DEFAULT_MAX_FILES}, max {_SEARCH_MAX_FILES_CAP}.')]	No	200
regex	Annotated[bool, Field(description='Treat pattern as a Python regular expression. Defaults to False.')]	No	False
case_sensitive	Annotated[bool, Field(description='Case-sensitive matching. Defaults to False (case-insensitive).')]	No	False
workspace_id	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	None

Returns

Returns a structured object. Top-level fields:

• model (string)
• path (string)
• branch (null)
• matches (array<object>)
• count (integer)
• files_scanned (integer)
• files_with_matches (integer)
• skipped_files (array)
• truncated (boolean)
• files_truncated (boolean)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "search_model_files",
  "arguments": {
    "model_name": "forecasts",
    "pattern": "growth_rate",
    "file_glob": "*.py"
  }
}

Response

{
  "model": "forecasts",
  "path": "",
  "branch": null,
  "matches": [
    {
      "path": "model/revenue.py",
      "line_number": 4,
      "column_start": 5,
      "column_end": 16,
      "line_text": "    growth_rate = 0.10",
      "context_before": [
        "def run(inputs):",
        "    df = load_actuals()"
      ],
      "context_after": [
        "    return {'revenue': df * (1 + growth_rate)}"
      ]
    }
  ],
  "count": 1,
  "files_scanned": 3,
  "files_with_matches": 1,
  "skipped_files": [],
  "truncated": false,
  "files_truncated": false
}

Notes

• Module: Files
• Requires authentication via API token or Auth0 JWT.