tools.feature_atlas.load_features_to_falkor module

Step 2: Load Feature nodes into FalkorDB.

Reads outputs/feature_registry.json and MERGEs each feature as a node into the stargazer_feature_interaction_atlas graph.

Fully idempotent – safe to re-run.

Usage:

python -m tools.feature_atlas.load_features_to_falkor

# skull – BONES INTO THE GRAPH

tools.feature_atlas.load_features_to_falkor.load_feature_registry()

Read and parse the feature registry produced by the extraction swarm.

Loads the canonical list of features discovered upstream so the loader has something to MERGE into the graph. It is the single source of truth for “which features exist” at the start of Step 2, which is why it fails loudly rather than returning an empty list when the registry is absent.

This is a pure local-filesystem read with no service interactions: it opens outputs/feature_registry.json from the module-level _FEATURE_REGISTRY_PATH and returns the deserialized JSON list. Called by load_features() (as the default source when no features argument is supplied) and by async_main() (to obtain the total count for the summary report).

Returns:

One feature dict per registry entry, each typically carrying id, confidence, files and symbols keys consumed by merge_feature.

Return type:

list[dict[str, Any]]

Raises:

• FileNotFoundError – If _FEATURE_REGISTRY_PATH does not exist, signalling that extract_features_swarm.py has not been run yet.

• json.JSONDecodeError – If the registry file is not valid JSON.

async tools.feature_atlas.load_features_to_falkor.load_features(features=None)

MERGE every Feature into the atlas knowledge graph in FalkorDB.

This is Step 2 of the Feature Atlas pipeline: it turns the registry of discovered features into actual Feature nodes in the graph so later steps (interaction detection, prompt generation, querying) have vertices to attach edges and analyses to. The whole operation is idempotent and safe to re-run, which is the contract callers and the orchestrator rely on.

Opens a connection to the stargazer_feature_interaction_atlas graph via get_atlas_graph (FalkorDB over the shared Redis connection pool), then MERGEs each feature through merge_feature and logs a per-feature line with its confidence and file/symbol counts. When no features argument is supplied it falls back to load_feature_registry(), reading outputs/feature_registry.json from the local filesystem. Per-feature failures are logged and skipped rather than aborting the batch, and after the loop it runs a read-only count(Feature) query to log a verification total before closing the Redis client. Called by async_main() in this module, which is dispatched as Step 2 by run_atlas.py‘s step_load_features (imported there as async_main as run).

Parameters:

features (list[dict[str, Any]] | None) – Optional pre-loaded list of feature dicts. When None, the features are read from outputs/feature_registry.json via load_feature_registry().

Returns:

The number of features successfully MERGEd into the atlas graph (features that raised during the merge are excluded from the count).

Return type:

int

async tools.feature_atlas.load_features_to_falkor.async_main()

Run Step 2 end to end: load the registry and import features into FalkorDB.

This is the coroutine that actually performs the feature load for command-line and orchestrated runs. It reads the registry once for an accurate denominator, drives the FalkorDB import, and prints a human-readable summary so an operator can see how the step fared at a glance.

Reads outputs/feature_registry.json via load_feature_registry(), delegates the graph writes to load_features() (which connects to the stargazer_feature_interaction_atlas graph in FalkorDB), times the run, and writes a formatted report to stdout. It is invoked both by main() here (via asyncio.run) and by run_atlas.py‘s step_load_features, which imports it as async_main as run and awaits it directly.

Returns:

All output is side effects – the FalkorDB writes performed by load_features() and the summary printed to stdout.

Return type:

None

tools.feature_atlas.load_features_to_falkor.main()

Synchronous CLI entry point for the Step 2 feature load.

Provides the python -m tools.feature_atlas.load_features_to_falkor entry point so the feature load can be run standalone. It exists to bridge the synchronous shell invocation into the async pipeline and to make sure progress is visible on the console.

Configures root logging at INFO level (so the per-feature load lines and the verification count emitted under load_features() are shown), then runs async_main() to completion via asyncio.run. Called only from this module’s if __name__ == "__main__" guard; the orchestrated path in run_atlas.py awaits async_main() directly and does not go through this function.

Return type:

None

Returns:

None.