:class:`Backend` ================ .. py:class:: ansys.fluent.mcp.common.backend.Backend Bases: :py:obj:`abc.ABC` Common interface for all backends. Concrete subclasses override only the methods their product supports. Default implementations raise `BackendUnavailableError`. .. !! processed by numpydoc !! .. py:currentmodule:: Backend Overview -------- .. tab-set:: .. tab-item:: Abstract methods .. list-table:: :header-rows: 0 :widths: auto * - :py:attr:`~connect` - Connect to the configured backend or service. * - :py:attr:`~is_connected` - Return whether connected. .. tab-item:: Methods .. list-table:: :header-rows: 0 :widths: auto * - :py:attr:`~disconnect` - Override if the backend holds a persistent resource. * - :py:attr:`~status` - Return backend status information. * - :py:attr:`~list_named_objects` - List named objects entries. * - :py:attr:`~get_named_object_names` - Return the instance names for a single named-object collection. * - :py:attr:`~find_named_object` - Resolve a symbolic name across every named-object collection. * - :py:attr:`~get_state` - Return the state. * - :py:attr:`~get_active_status` - Return the active status. * - :py:attr:`~get_allowed_values` - Return the allowed values. * - :py:attr:`~get_node_attrs` - Batched per-node settings-attribute fetch. * - :py:attr:`~get_node_attrs_bulk` - Recursively fetch attributes for all children of ``parent_path``. * - :py:attr:`~probe_path` - Cheap pre-flight probe for a batch of settings paths. * - :py:attr:`~get_command_arguments` - Return the keyword-argument signature of a command path. * - :py:attr:`~get_help` - Return the help. * - :py:attr:`~solver_status` - Return solver status information from the backend. * - :py:attr:`~describe_named_object_template` - Describe the field shape of a fresh child of a named-object collection. * - :py:attr:`~list_fields` - Enumerate solver field/variable names available for reports/post. * - :py:attr:`~get_targeted_context` - Return the targeted context. * - :py:attr:`~mesh_adjacency_probe` - Return ``{cellzone -> [adjacent_face_zone_names]}``. * - :py:attr:`~find_api` - Retrieve candidate Fluent settings APIs for ``query``. * - :py:attr:`~run_code` - Execute Python code through the backend runtime. * - :py:attr:`~validate_code` - Default validation: AST parse + forbidden-call scan. * - :py:attr:`~mesh_counts` - Return live mesh element totals. * - :py:attr:`~mesh_quality` - Return live mesh-quality summary statistics. * - :py:attr:`~mesh_check` - Return Fluent's full ``mesh.check`` report as structured data. * - :py:attr:`~activate_component` - Start or resume the managed Fluids One component. * - :py:attr:`~deactivate_component` - Stop the managed Fluids One component. * - :py:attr:`~update_component` - Update the managed Fluids One component. * - :py:attr:`~refresh_component` - Refresh the managed Fluids One component. * - :py:attr:`~screenshot` - Capture a screenshot from the backend runtime. * - :py:attr:`~invalidate_mesh_cache` - Drop cached mesh-probe results. * - :py:attr:`~maybe_invalidate_mesh_cache` - Drop the mesh cache when ``code`` matches a mutation marker. * - :py:attr:`~invalidate_cache` - Clear cached backend state. * - :py:attr:`~invalidate_live_caches` - Drop caches that depend on solver state. .. tab-item:: Attributes .. list-table:: :header-rows: 0 :widths: auto * - :py:attr:`~kind` - * - :py:attr:`~label` - * - :py:attr:`~MESH_MUTATION_MARKERS` - Import detail ------------- .. code-block:: python from ansys.fluent.mcp.common.backend import Backend Attribute detail ---------------- .. py:attribute:: kind :type: str :value: 'unknown' .. py:attribute:: label :type: str :value: 'Unknown backend' .. py:attribute:: MESH_MUTATION_MARKERS :type: tuple[str, Ellipsis] :value: ('file.read_case', 'file.read_mesh', 'file.read_case_data', 'file.replace_mesh', 'mesh.replace',... Method detail ------------- .. py:method:: connect(**kwargs: Any) -> ansys.fluent.mcp.common.models.ConnectResult :abstractmethod: :async: Connect to the configured backend or service. :Parameters: **kwargs** : :obj:`Any` Keyword arguments forwarded to the callable. :Returns: :obj:`ConnectResult` ConnectResult produced by the operation. .. !! processed by numpydoc !! .. py:method:: disconnect() -> None :async: Override if the backend holds a persistent resource. :Returns: :data:`python:None` The function completes through its side effects. .. !! processed by numpydoc !! .. py:method:: is_connected() -> bool :abstractmethod: Return whether connected. :Returns: :ref:`bool ` Boolean result of the operation. .. !! processed by numpydoc !! .. py:method:: status(leaf: str) -> ansys.fluent.mcp.common.models.SessionStatus Return backend status information. :Parameters: **leaf** : :class:`python:str` Leaf MCP server instance under test. :Returns: :obj:`SessionStatus` SessionStatus produced by the operation. .. !! processed by numpydoc !! .. py:method:: list_named_objects() -> dict[str, Any] :async: List named objects entries. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: get_named_object_names(collection_path: str) -> list[str] :async: Return the instance names for a single named-object collection. Default implementation calls :meth:`list_named_objects` and filters. Backends with a direct ``get_object_names()`` accessor (e.g. PyFluent) should override this for a cheaper single-node round-trip. :Parameters: **collection_path** : :class:`python:str` Path to the named-object collection. :Returns: :class:`python:list`\[:class:`python:str`] Collection containing the operation results. .. !! processed by numpydoc !! .. py:method:: find_named_object(name: str) -> list[dict[str, Any]] :async: Resolve a symbolic name across every named-object collection. Accepts: * Literal identifiers (``"inlet-1"``) — exact and substring matches are returned, exact first. * Glob patterns (``"wall-*"``, ``"*bar*|*tabzone*"``) — every live name matching the pattern is returned with ``"exact": True`` (the pattern itself stands in for an exact intent against the matched key) and an ``"is_pattern": True`` flag on each entry plus a top-level ``pattern_source`` payload so callers know the source query was a pattern. Default implementation calls :meth:`list_named_objects` and filters; backends with a faster index may override. :Parameters: **name** : :class:`python:str` Name of the object, module, or setting being processed. :Returns: :class:`python:list`\[:class:`python:dict`\[:class:`python:str`, :obj:`Any`]] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: get_state(paths: list[str] | None = None) -> dict[str, Any] :async: Return the state. :Parameters: **paths** : :class:`python:list`\[:class:`python:str`] | :data:`python:None` Fluent object paths supplied to the operation. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: get_active_status(paths: list[str]) -> dict[str, bool] :async: Return the active status. :Parameters: **paths** : :class:`python:list`\[:class:`python:str`] Fluent object paths supplied to the operation. :Returns: :class:`python:dict`\[:class:`python:str`, :ref:`bool `] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: get_allowed_values(paths: list[str]) -> dict[str, list[Any]] :async: Return the allowed values. :Parameters: **paths** : :class:`python:list`\[:class:`python:str`] Fluent object paths supplied to the operation. :Returns: :class:`python:dict`\[:class:`python:str`, :class:`python:list`\[:obj:`Any`]] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: get_node_attrs(paths: list[str], attrs: list[str]) -> dict[str, dict[str, Any]] :async: Batched per-node settings-attribute fetch. Returns ``{path: {attr: value}}``. Backends with a live solver session should override; the default raises :class:`BackendUnavailableError` so callers can fall back to the per-attr accessors (``get_active_status``, ``get_allowed_values``). :Parameters: **paths** : :class:`python:list`\[:class:`python:str`] Fluent object paths supplied to the operation. **attrs** : :class:`python:list`\[:class:`python:str`] Attribute names requested from the backend object. :Returns: :class:`python:dict`\[:class:`python:str`, :class:`python:dict`\[:class:`python:str`, :obj:`Any`]] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: get_node_attrs_bulk(parent_path: str, attrs: list[str]) -> dict[str, dict[str, Any]] :async: Recursively fetch attributes for all children of ``parent_path``. Calls ``node.get_attrs(attrs, recursive=True)`` in a single Scheme RPC, replacing N per-field round-trips when the caller needs metadata for a whole subtree (e.g. validating every field in a ``set_named`` value dict). Returns ``{relative_child_path: {attr: value}}``. Attr spellings follow the Scheme convention (``"min"``, ``"max"``, ``"units-quantity"``, ``"allowed-values"``, ``"active?"``). The default returns ``{}`` so callers can fall back gracefully to per-path ``get_node_attrs`` calls. :Parameters: **parent_path** : :class:`python:str` Parent Fluent object path used for bulk lookup. **attrs** : :class:`python:list`\[:class:`python:str`] Attribute names requested from the backend object. :Returns: :class:`python:dict`\[:class:`python:str`, :class:`python:dict`\[:class:`python:str`, :obj:`Any`]] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: probe_path(paths: list[str]) -> dict[str, dict[str, Any]] :async: Cheap pre-flight probe for a batch of settings paths. Returns ``{path: {exists, is_active, is_user_creatable, kind}}`` in a single batched RPC. Live backends should override; the default raises :class:`BackendUnavailableError`. :Parameters: **paths** : :class:`python:list`\[:class:`python:str`] Fluent object paths supplied to the operation. :Returns: :class:`python:dict`\[:class:`python:str`, :class:`python:dict`\[:class:`python:str`, :obj:`Any`]] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: get_command_arguments(path: str) -> dict[str, Any] | None :async: Return the keyword-argument signature of a command path. Returns ``None`` if the backend cannot introspect commands or the path is not a command. The result shape is:: {"argument_names": ["type", "name"], "arguments": {"type": {...}, ...}} Backends with a live solver session should override. :Parameters: **path** : :class:`python:str` Fluent object path or file-system path to inspect. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] | :data:`python:None` Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: get_help(path: str) -> dict[str, Any] :async: Return the help. :Parameters: **path** : :class:`python:str` Filesystem path or API path to process. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: solver_status() -> dict[str, Any] :async: Return solver status information from the backend. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: describe_named_object_template(path: str) -> dict[str, Any] | None :async: Describe the field shape of a fresh child of a named-object collection. Returns ``None`` when the backend cannot introspect templates. Live backends should override. :Parameters: **path** : :class:`python:str` Fluent object path or file-system path to inspect. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] | :data:`python:None` Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: list_fields(*, scope: str = 'any') -> dict[str, Any] | None :async: Enumerate solver field/variable names available for reports/post. Returns ``None`` when unavailable. :Parameters: **scope** : :class:`python:str` Scope used to limit the field or API lookup. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] | :data:`python:None` Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: get_targeted_context(*, paths_to_check: list[str], named_object_types: list[str] | None = None, instance_state_fetch: list[str] | None = None) -> dict[str, Any] :async: Return the targeted context. :Parameters: **paths_to_check** : :class:`python:list`\[:class:`python:str`] Fluent object paths to validate or inspect. **named_object_types** : :class:`python:list`\[:class:`python:str`] | :data:`python:None` Named-object families that should be considered during lookup. **instance_state_fetch** : :class:`python:list`\[:class:`python:str`] | :data:`python:None` Whether named-object instance state should be fetched. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: mesh_adjacency_probe(cellzones: list[str], *, bc_filter: tuple[str, Ellipsis] | None = None) -> dict[str, list[str]] :async: Return ``{cellzone -> [adjacent_face_zone_names]}``. Implementations walk every BC family that exposes ``adjacent_cell_zone`` (wall, velocity_inlet, pressure_outlet, mass_flow_inlet, …) and invert the mapping. Coupled-wall ``shadow_face_zone`` entries are added to BOTH sides so cellzone↔cellzone neighbour queries (set-intersection on shared face names) find CHT solid–fluid pairs. ``bc_filter`` restricts the walk to the listed BC families (e.g. ``("wall",)`` to answer "walls adjacent to X", ``("velocity_inlet", "pressure_inlet")`` for inlets, ...). ``None`` (default) walks every supported family. The shadow traversal only contributes when ``"wall"`` is in scope (or the filter is None) — interior families have no shadow concept. Limitation: interior face zones are not enumerated — they are gated INACTIVE on ``boundary_conditions.interior[*]`` and the ``mesh.adjacency`` Command's argument-binding side-channel is broken on Fluent ≥ 27.1. Callers needing interior coverage must supplement with ``run_code``. Backends without a live solver session must raise :class:`BackendUnavailableError`. :Parameters: **cellzones** : :class:`python:list`\[:class:`python:str`] Cell zone names used for the mesh adjacency query. **bc_filter** : :class:`python:tuple`\[:class:`python:str`, ...] | :data:`python:None` Boundary-condition filter used to limit the probe. :Returns: :class:`python:dict`\[:class:`python:str`, :class:`python:list`\[:class:`python:str`]] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: find_api(query: str, *, top_k: int = 10, kinds: list[str] | None = None, under: str | None = None) -> list[dict[str, Any]] :async: Retrieve candidate Fluent settings APIs for ``query``. Uses the configured lexical :class:`ApiRetriever`, which performs BM25 ranking over the bundled Fluent API catalog and PyFluent class docstrings. Returns a list of ``{path, kind, score, ...}`` hits. Backends may override to add live cross-checks (e.g. filter out paths whose immediate parent does not exist on the connected solver). :Parameters: **query** : :class:`python:str` Search query supplied by the caller. **top_k** : :class:`python:int` Maximum number of search hits to return. **kinds** : :class:`python:list`\[:class:`python:str`] | :data:`python:None` Optional API object kinds used to filter search results. **under** : :class:`python:str` | :data:`python:None` Optional root path used to constrain API search results. :Returns: :class:`python:list`\[:class:`python:dict`\[:class:`python:str`, :obj:`Any`]] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: run_code(code: str, *, namespace: dict[str, Any] | None = None, filename: str = '') -> ansys.fluent.mcp.common.models.RunCodeResult :async: Execute Python code through the backend runtime. :Parameters: **code** : :class:`python:str` Python code or command text to execute or validate. **namespace** : :class:`python:dict`\[:class:`python:str`, :obj:`Any`] | :data:`python:None` Namespace used to resolve the backend object or route. **filename** : :class:`python:str` File name or path used by the backend operation. :Returns: :obj:`RunCodeResult` RunCodeResult produced by the operation. .. !! processed by numpydoc !! .. py:method:: validate_code(code: str) -> ansys.fluent.mcp.common.models.RunCodeResult :async: Default validation: AST parse + forbidden-call scan. Backends with a live solver session can override to add semantic checks against the connected model. :Parameters: **code** : :class:`python:str` Python code snippet to validate or execute. :Returns: :obj:`RunCodeResult` Result produced by the function. .. !! processed by numpydoc !! .. py:method:: mesh_counts() -> dict[str, int | None] :async: Return live mesh element totals. Output shape: ``{"cell_count", "face_count", "node_count"}`` — each value is an ``int`` when the underlying solver exposes the count, or ``None`` when the count is unavailable (no mesh loaded, partition pending, or the backend has no introspection path to mesh totals). Callers MUST treat ``None`` as ``unknown`` — never as zero. The default raises :class:`BackendUnavailableError` so backends that have no live solver (Fluids One geometry / mesh / post leaves) decline the probe; the smart-defaults wrapper catches this and falls back to an all-``None`` payload. Solve backends override this to query Fluent (e.g. via the Scheme variables ``tinfo/n-cells`` etc.). :Returns: :class:`python:dict`\[:class:`python:str`, :class:`python:int` | :data:`python:None`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: mesh_quality() -> dict[str, float | None] :async: Return live mesh-quality summary statistics. Output shape: ``{"min_orthogonal_quality", "max_ortho_skew", "max_aspect_ratio"}`` — each value is a ``float`` in its native Fluent range (orthogonal quality 0..1 where higher is better; ortho skew 0..1 where lower is better; aspect ratio ≥ 1) or ``None`` when the metric is not available (no mesh loaded, ``mesh.quality`` failed, or the report wording on the connected Fluent build doesn't match the parser). Callers MUST treat ``None`` as ``unknown`` — never as a passing score. Backends should cache the result (mesh quality is invariant between mutations) and invalidate on mesh-modifying operations (case load, scale, translate, rotate, adapt, repair). The default raises :class:`BackendUnavailableError`. Solve backends override this to invoke Fluent's ``mesh.quality`` settings command and parse the captured transcript. :Returns: :class:`python:dict`\[:class:`python:str`, :class:`python:float` | :data:`python:None`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: mesh_check() -> dict[str, Any] :async: Return Fluent's full ``mesh.check`` report as structured data. Output shape (all keys optional — a value is ``None`` when the corresponding line was not present in the captured transcript): .. code-block:: { "domain_extents": {"x": (min, max), "y": (min, max), "z": (min, max)}, "volume_min": float | None, "volume_max": float | None, "volume_total": float | None, "face_area_min": float | None, "face_area_max": float | None, "errors": list[str], # lines preceded by "Error:" "warnings": list[str], # lines preceded by "Warning:" "raw": str, # the verbatim transcript chunk } ``mesh.check`` is the right pre-flight diagnostic — it covers topology (left-handed cells, non-positive volumes, face handedness, periodic / boundary-pair sanity) on top of the bulk statistics. It does NOT print quality numbers in modern Fluent builds (see :meth:`mesh_quality` for those). The default raises :class:`BackendUnavailableError`. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: activate_component() -> dict[str, Any] :async: Start or resume the managed Fluids One component. Sends POST ``/api/session/components//activate``. Returns a status dict. Backends that do not talk to Fluids One raise :class:`BackendUnavailableError`. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: deactivate_component() -> dict[str, Any] :async: Stop the managed Fluids One component. Sends POST ``/api/session/components//deactivate``. Returns a status dict. Backends that do not talk to Fluids One raise :class:`BackendUnavailableError`. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: update_component() -> dict[str, Any] :async: Update the managed Fluids One component. Sends POST ``/api/session/components//update``. Returns a status dict. Backends that do not talk to Fluids One raise :class:`BackendUnavailableError`. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: refresh_component() -> dict[str, Any] :async: Refresh the managed Fluids One component. Sends POST ``/api/session/components//refresh``. Returns a status dict. Backends that do not talk to Fluids One raise :class:`BackendUnavailableError`. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: screenshot(*, view: Optional[str] = None) -> dict[str, Any] :async: Capture a screenshot from the backend runtime. :Parameters: **view** : :obj:`Optional`\[:class:`python:str`] Graphics view or camera preset requested by the caller. :Returns: :class:`python:dict`\[:class:`python:str`, :obj:`Any`] Mapping containing the operation result. .. !! processed by numpydoc !! .. py:method:: invalidate_mesh_cache() -> None Drop cached mesh-probe results. :Returns: :data:`python:None` The function completes through its side effects. .. !! processed by numpydoc !! .. py:method:: maybe_invalidate_mesh_cache(code: str) -> bool Drop the mesh cache when ``code`` matches a mutation marker. :Parameters: **code** : :class:`python:str` ``run_code`` snippet to inspect. :Returns: :ref:`bool ` ``True`` when the cache was cleared. .. !! processed by numpydoc !! .. py:method:: invalidate_cache() -> None Clear cached backend state. :Returns: :data:`python:None` The function completes through its side effects. .. !! processed by numpydoc !! .. py:method:: invalidate_live_caches() -> None Drop caches that depend on solver state. Called by the framework after every ``run_code`` and after ``connect``. The mesh-probe cache is preserved; use :meth:`invalidate_mesh_cache` or :meth:`maybe_invalidate_mesh_cache` to drop it explicitly. :Returns: :data:`python:None` The function completes through its side effects. .. !! processed by numpydoc !!