nvflare.tool.agent.frameworks.base module

Base contract for inspector framework detectors.

A FrameworkDetector encapsulates everything the inspector needs to know about one framework. The engine calls the on_* hooks once per relevant AST node, passing a per-file DetectContext the detector uses to record evidence and FLARE-integration signals. Detectors keep their own per-file scratch state (import aliases, imported symbols) via new_file_state; the engine treats it as opaque.

class DetectContext(emit_evidence, add_flare_call, add_integration_signal)

Bases: object

Per-file sink the engine hands to detector hooks.

The detector records framework evidence and FLARE-integration signals through this context instead of touching inspector internals directly, so the engine owns how those signals are stored and ranked.

evidence(framework: str, kind: str, value: str, lineno: int | None) → None

Record ranked framework evidence (import, class base, activity call).

flare_call(call_name: str) → None

Record a FLARE-integration call such as flare.patch.

integration_signal(framework: str, name: str) → None

Record a framework-specific FLARE conversion signal.

Used by conversion_state to tell a converted job apart from raw training code (for example, a Lightning flare.patch(trainer) call).

class FrameworkDetector

Bases: object

Static-detection plugin for a single framework.

Subclasses set the class attributes and override the on_* hooks they need. Every hook is optional; the base implementations do nothing.

evidence_weights: dict[str, int] = {}

Evidence-kind -> ranking weight contributed by this framework.

family: str | None = None

Family this framework belongs to for cross-framework disambiguation (e.g. Lightning declares "pytorch"). None means standalone.

import_roots: dict[str, str] = {}

Top-level import module names that map to this framework’s evidence bucket, e.g. {"torch": "pytorch"}. Used for ranked import evidence.

is_active_evidence(evidence: dict) → bool

Whether an evidence item counts as active (in-use) for this framework.

Used by family disambiguation to distinguish active use from an incidental import. Defaults to non-import evidence.

name: str = ''

Canonical framework name reported in inspector output (e.g. "pytorch").

new_file_state() → Any

Return fresh per-file scratch state (import aliases, symbols).

on_call(call_name: str, lineno: int | None, file_state: Any, ctx: DetectContext) → None

Handle a called name such as torch.optim.SGD or flare.patch.

on_class_base(base_name: str, lineno: int | None, file_state: Any, ctx: DetectContext) → None

Handle a base class name in a class X(Base): definition.

on_import(alias: alias, file_state: Any, ctx: DetectContext) → None

Handle import x / import x as y aliases.

on_import_from(module: str, aliases: list, file_state: Any, ctx: DetectContext) → None

Handle from module import ... symbols.

promote_over_family(family_base: str, resolver) → bool

For a family member, decide whether to win over the family base.

Only called for detectors that declare a family. resolver gives access to the collected evidence and entry-context helpers so the decision stays in the framework module. Default: never promote.

recommended_skill: str | None = None

Conversion skill recommended when this framework is primary, or None.