.. _auto_file_search:

*SEARCH FILE CONTENTS*
======================

Searches for regex or literal patterns within a file, returning matching lines annotated with line numbers and surrounding context — similar to `grep`. Accepts a file attachment ID, file path, or attachment name; streams large files line-by-line to avoid memory exhaustion. Use this worker inside agent or LLM-driven workflows to inspect CAE output files (e.g., d3hsp, messag, log) for warnings, errors, or keywords.

When to use
-----------

Tagged: ``file``, ``grep``, ``large_file``, ``llm_tool``, ``log``, ``regex``, ``search``, ``streaming``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - File
     - file
     - text
     - —
     - ✓
     - The file to search — accepts a numeric attachment ID, an absolute/relative file path, or an attachment name (string); required.
   * - Search Pattern
     - pattern
     - text
     - —
     - ✓
     - Regex or literal pattern to match against each line (e.g., 'Warning.*contact', '*PART', 'error/failure'); required — supports full PCRE syntax.
   * - Context Lines
     - context_lines
     - text
     - 2
     - 
     - Number of lines to show immediately before and after each matching line (integer 0–10); defaults to 2 — increase for more context around sparse matches.
   * - Case Sensitive
     - case_sensitive
     - select
     - false
     - 
     - Set to 'true' to perform a case-sensitive match; defaults to 'false' (case-insensitive), which is appropriate for most CAE log searches.
   * - Max Matches
     - max_matches
     - text
     - 50
     - 
     - Upper limit on the number of matching lines returned (integer 1–200); defaults to 50 — raise if the file is expected to contain many occurrences of the pattern.

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - Search Results
     - matches
     - text
     - Human-readable, grep-style formatted string of all matched lines with surrounding context: match lines are marked with ':', context lines with '-', and each entry is prefixed by its 1-based line number; nearby match groups are merged.
   * - Match Count
     - match_count
     - number
     - Integer count of lines that matched the pattern (capped at max_matches); 0 when no matches are found.
   * - Total Lines
     - total_lines
     - number
     - Total number of lines in the searched file; useful for gauging file size and normalising match frequency.
   * - Status
     - status
     - text
     - Short human-readable summary of the search outcome (e.g., 'Found 12 matches in messag'); suitable for display in a dashboard or agent response.

Disciplines
-----------

- ai_ml.agents
- data.io.file

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>file_search</code>. Schema hash: <code>28509b44a863</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>