Adapter Discovery

Phase 4 introduces Python entry-point discovery for provider adapters. The goal is to prove how a companion package or native domain package can expose provider metadata to FreshForge without FreshForge importing real ecosystem tools directly.

Entry-Point Contract

Provider packages may expose factories through the freshforge.providers entry-point group:

[project.entry-points."freshforge.providers"]
example = "some_package.freshforge:provider_factory"

Each entry point must load to a callable factory. The factory must return an object that implements the FreshForge provider protocol: metadata() and validate_node(...). FreshForge registers the returned provider by ProviderMetadata.id.

Discovery Diagnostics

Discovery failures are reported as FreshForge diagnostics instead of Python tracebacks. Diagnostics cover:

  • entry-point load failures;

  • factory failures;

  • invalid provider objects;

  • invalid provider metadata;

  • duplicate provider IDs.

CLI commands use entry-point discovery by default. The Python API also supports explicit registration and can construct a registry without entry points for tests or tightly controlled applications.

Fixture Adapter

FreshForge ships a public-safe fixture adapter under provider ID freshforge.fixture. It is registered through FreshForge’s own freshforge.providers entry point so tests and docs exercise the same discovery path that a future companion package would use.

The fixture adapter is intentionally non-executing. Its node types declare FRESH-flavoured workflow steps such as inventory summary, yield table check, and scenario report declaration. Validation checks only broad declared keys and simple parameters; it does not read datasets, inspect artifacts, or call external tools.

Example

freshforge providers
freshforge validate examples/ecosystem_adapter_workflow.yaml
freshforge inspect examples/ecosystem_adapter_workflow.yaml --json
freshforge plan examples/ecosystem_adapter_workflow.yaml

Deferred Work

Phase 4 does not add real FEMIC, FHOPS, ws3, Modelwright, or Nemora adapters. Phase 6 later adds provider-owned node execution through freshforge run, but FreshForge core still does not add artifact materialization, caching, checkpoints, or real ecosystem adapters. FreshForge 0.1.0a5 keeps these boundaries for the first PyPI alpha release.