tools.feature_atlas.detect_code_interactions module

Step 3: Detect code-grounded interactions between features.

Static analysis only: analyzes imports, shared files, shared data stores, and shared env vars between feature pairs using the repo symbol index.

Outputs outputs/code_interactions.json and loads CODE_INTERACTS_WITH edges into FalkorDB.

Usage:

python -m tools.feature_atlas.detect_code_interactions

# fire skull – FINDING THE NERVES BETWEEN ORGANS

tools.feature_atlas.detect_code_interactions.detect_static_interactions(features, symbols)

Detect code-grounded interactions between feature pairs via static analysis.

The first and only phase of the interaction detector: it cross-references the feature registry against the repo symbol index to surface edges that are evidenced purely by code structure, without any LLM or runtime inspection. For every ordered pair of features it emits an interaction when they share a file (mechanism shared_memory_layer), when one imports a file owned by the other (mechanism direct_import), when they share a declared data store (mechanism shared_falkordb_graph, shared_redis_db, or shared_vector_store depending on the store name), or when they reference the same environment variable (mechanism shared_env_var). Each edge carries a confidence score and human-readable evidence string. The results are deduplicated so that only the highest-confidence interaction survives per source, target, and mechanism triple, and the surviving and pre-dedup counts are logged.

Internally it builds its lookup structures by calling _build_file_to_features() and _build_import_graph(), and resolves imports back to owning files via _module_to_filepath(). It is a pure in-memory computation with no Redis, knowledge-graph, LLM, HTTP, or filesystem side effects of its own.

Invoked by async_main() in this module, which then persists the returned edges to FalkorDB; no other internal callers were found.

Parameters:

• features (list[dict[str, Any]]) – The feature registry records, each with an id, a files list, and an optional data_stores list.

• symbols (list[dict[str, Any]]) – The per-file symbol records used to derive imports and the environment variables referenced by each feature’s files.

Return type:

list[dict[str, Any]]

Returns:

A deduplicated list of interaction edge dictionaries, each describing a source feature, target feature, mechanism, confidence, supporting file and symbol references, an evidence string, and a direction label.

async tools.feature_atlas.detect_code_interactions.load_interactions_to_falkor(interactions)

Persist detected interactions as CODE_INTERACTS_WITH edges in FalkorDB.

Opens a connection to the atlas graph via tools.feature_atlas.atlas_connection.get_atlas_graph() and, for each interaction, upserts the corresponding CODE_INTERACTS_WITH relationship by calling tools.feature_atlas.atlas_connection.merge_code_interaction(). Individual failures are caught and logged so one bad edge does not abort the whole load, and the underlying Redis client is closed before returning. This mutates the FalkorDB stargazer_feature_interaction_atlas graph and holds a network connection for the duration of the load.

Invoked by async_main() in this module; no other internal callers were found.

Parameters:

interactions (list[dict[str, Any]]) – The interaction edge dictionaries produced by detect_static_interactions().

Return type:

int

Returns:

The number of edges that were successfully merged into the graph.

async tools.feature_atlas.detect_code_interactions.async_main()

Run the full code-interaction detection step end to end.

Orchestrates step 3 of the Feature Atlas pipeline: it loads the feature registry and symbol index from disk via _load_features() and _load_symbols(), runs detect_static_interactions() to compute the edges, writes them to outputs/code_interactions.json, then persists them to FalkorDB through load_interactions_to_falkor(). It finishes by printing a human-readable summary that breaks the edges down by mechanism and reports timing and the output path. Side effects therefore span the filesystem (the output JSON) and the FalkorDB atlas graph (via the load helper); it also logs progress at INFO level.

Invoked by main() in this module’s __main__ guard and imported as async_main by tools.feature_atlas.run_atlas.step_detect_interactions() (the detect-interactions step of the atlas runner); no other internal callers were found.

Return type:

None

Returns:

None.

tools.feature_atlas.detect_code_interactions.main()

Synchronous entry point for the code-interaction detection step.

Configures root logging at INFO level and drives the async pipeline by calling asyncio.run(async_main()), which loads the registry and symbol index, computes the interactions, writes outputs/code_interactions.json, and loads the edges into FalkorDB. All Redis, FalkorDB, and filesystem side effects happen transitively inside async_main(); this wrapper only sets up logging and starts the event loop.

Invoked from the module’s if __name__ == "__main__" guard via python -m tools.feature_atlas.detect_code_interactions; no other internal callers were found.

Return type:

None

Returns:

None.