.. _auto_worker_graph_search:

*SEARCH WORKER GRAPH*
=====================

Discovers d3VIEW workers by navigating the structured alias index (parent_operation_outputEntity_relationship_inputEntity). Structured filters (parent, operation, relationship, output_entity, input_entity) compose with AND; use `query` for free-text fallback scoring; use `chain_from_output_entity` to find workers whose input is type-compatible with a given upstream output. Every response echoes a scoped `vocabulary` (parents, operations, relationships) so the caller can self-correct on the next call.

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

Tagged: ``agent_tool``, ``alias_index``, ``controlled_vocabulary``, ``graph_search``, ``pagination``, ``pipeline_chaining``, ``registry``, ``type_mapping``.

Inputs
------

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

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - Parent Domain
     - parent
     - text
     - —
     - 
     - Exact match against the controlled `parents` vocabulary (e.g., viz, simulation, curve, dataset, math); invalid values short-circuit with a helpful error and the full vocabulary echoed. Leave blank to search across all domains.
   * - Operation
     - operation
     - text
     - —
     - 
     - Exact match against the controlled `operations` vocabulary (e.g., create, render, compute, filter, submit). Leave blank to include all operation types.
   * - Relationship
     - relationship
     - text
     - —
     - 
     - Exact match against the controlled `relationships` vocabulary (from, using, to, by, for, with, on, of, at, between). Leave blank to skip relationship filtering.
   * - Output Entity
     - output_entity
     - text
     - —
     - 
     - Token/substring match against the alias output_entity field (e.g., scatter, loadcase, simulation); case-insensitive, splits on underscores. Leave blank to skip output-entity filtering.
   * - Input Entity
     - input_entity
     - text
     - —
     - 
     - Token/substring match against the alias input_entity field (e.g., dataset, curve, excel_file); case-insensitive, splits on underscores. Leave blank to skip input-entity filtering.
   * - Free-text Query
     - query
     - text
     - —
     - 
     - Natural-language fallback; tokenized and scored against the alias segments, worker_id, and the curated registry description. Use when structured filters are insufficient or unknown.
   * - Chain From Output Entity
     - chain_from_output_entity
     - text
     - —
     - 
     - Special chain mode: given an upstream worker's output_entity, returns all workers whose input_entity matches directly (score 3) or is canonical-type-compatible via type.mapping.json (score 1). Use to build downstream pipeline steps.
   * - Max Results
     - max_results
     - scalar
     - 10
     - 
     - Page size — maximum number of ranked matches to return per call; default 10, hard cap 50. Pair with `offset` to paginate through large result sets.
   * - Offset
     - offset
     - scalar
     - 0
     - 
     - Number of top matches to skip before returning results; default 0. Increase by `max_results` on successive calls; the `vocabulary` output's `pagination` block reports whether more pages exist and the correct next_offset value.

Outputs
-------

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

   * - Label
     - ID
     - Type
     - Description
   * - Search Results
     - results
     - json
     - Ranked JSON array of matched workers; each element contains {worker_id, alias, parent, operation, output_entity, relationship, input_entity, description, score}, where `description` is sourced from worker.registry.json (proposed_description) and `score` reflects match quality.
   * - Vocabulary
     - vocabulary
     - json
     - JSON context guide echoed on every response; when filters are active it scopes parents/operations/relationships/output_entities/input_entities to values present in the filtered pool (frequency-ranked), adds `miss_suggestion` on zero-hit entity/query filters, echoes valid applied filters under `applied`, and always includes a `pagination` block {total, offset, returned, has_more, next_offset}.
   * - Status
     - status
     - string
     - Human-readable summary of the search outcome (e.g., 'Found 7 results filtered by parent=viz, operation=render.') or a validation error message listing valid vocabulary values when an unrecognised filter value was supplied.

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

- ai_ml.agents
- ai_ml.domain_reasoning
- platform.ontology
- platform.workflow

.. raw:: html

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