nvflare.tool.agent.frameworks package

Submodules

• nvflare.tool.agent.frameworks.base module
  • DetectContext
    • DetectContext.evidence()
    • DetectContext.flare_call()
    • DetectContext.integration_signal()
  • FrameworkDetector
    • FrameworkDetector.evidence_weights
    • FrameworkDetector.family
    • FrameworkDetector.import_roots
    • FrameworkDetector.is_active_evidence()
    • FrameworkDetector.name
    • FrameworkDetector.new_file_state()
    • FrameworkDetector.on_call()
    • FrameworkDetector.on_class_base()
    • FrameworkDetector.on_import()
    • FrameworkDetector.on_import_from()
    • FrameworkDetector.promote_over_family()
    • FrameworkDetector.recommended_skill
• nvflare.tool.agent.frameworks.lightning module
  • LightningDetector
    • LightningDetector.evidence_weights
    • LightningDetector.family
    • LightningDetector.import_roots
    • LightningDetector.is_active_evidence()
    • LightningDetector.name
    • LightningDetector.new_file_state()
    • LightningDetector.on_call()
    • LightningDetector.on_class_base()
    • LightningDetector.on_import()
    • LightningDetector.on_import_from()
    • LightningDetector.promote_over_family()
    • LightningDetector.recommended_skill
• nvflare.tool.agent.frameworks.pytorch module
  • PyTorchDetector
    • PyTorchDetector.evidence_weights
    • PyTorchDetector.import_roots
    • PyTorchDetector.is_active_evidence()
    • PyTorchDetector.name
    • PyTorchDetector.new_file_state()
    • PyTorchDetector.on_call()
    • PyTorchDetector.on_class_base()
    • PyTorchDetector.on_import()
    • PyTorchDetector.on_import_from()
    • PyTorchDetector.recommended_skill
• nvflare.tool.agent.frameworks.registry module
  • detectors()
  • evidence_weights()
  • family_base_has_member()
  • framework_for_import()
  • is_active_evidence()
  • recommended_skill_for()
  • resolve_primary_framework()

Module contents

Per-framework static-detection plugins for the agent inspector.

The inspector engine (inspector.py) stays framework-agnostic: it walks each Python AST once and dispatches every node to the registered FrameworkDetector plugins. All framework-specific knowledge – import roots, symbols, evidence kinds and weights, the recommended conversion skill, and cross-framework family/promotion rules – lives in a detector module here.

Adding a framework (XGBoost, TensorFlow, Hugging Face, …) means adding a detector module and registering it in registry.py; the engine does not change.

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.

detectors() → list[FrameworkDetector]

evidence_weights() → dict[str, int]

family_base_has_member(base: str | None, evidence_by_framework: dict) → str | None

If base is a family base with a member present in evidence, return the member name.

framework_for_import(module: str) → str | None

Map an imported module to its framework bucket by top-level segment.

is_active_evidence(framework: str, evidence: dict) → bool

recommended_skill_for(framework: str | None) → str | None

resolve_primary_framework(primary: str, evidence_by_framework: dict, resolver) → str

Disambiguate a family conflict (e.g. PyTorch vs PyTorch Lightning).

Returns the framework that should be primary. Only overrides primary when it is part of a family whose base and member both have evidence; the member detector owns the promotion decision.