tools.feature_atlas.atlas_connection module
FalkorDB connection helper for the Feature Interaction Atlas.
Connects to the same Redis/FalkorDB instance as the production knowledge
graph but uses a completely separate graph namespace:
stargazer_feature_interaction_atlas.
Reuses the project’s config.Config.load() for Redis URL and TLS
kwargs, matching the pattern in memory_search.py.
# fire – SEPARATE GRAPH. SEPARATE KEYSPACE. ZERO RISK.
- async tools.feature_atlas.atlas_connection.get_redis()[source]
Open an async Redis connection configured from the project
Config.Loads
config.Configto reuse the production Redis URL and TLS settings, opens a decoded async client, and raises FalkorDB’sRESULTSET_SIZEcap so the large atlas graph queries are not truncated (best-effort, ignored if the command is unavailable). The Feature Interaction Atlas shares the Redis instance with the production knowledge graph but is isolated by graph namespace, not by connection.This performs a network connect and issues a
GRAPH.CONFIG SETcommand. It is called byget_atlas_graph()whenever no client is supplied; the various atlas scripts (load_features_to_falkor,detect_code_interactions,query_atlas, and others) reach it transitively through that function.- Returns:
A connected
redis.asyncioclient withdecode_responses=True.- Return type:
- async tools.feature_atlas.atlas_connection.get_atlas_graph(redis_client=None)[source]
Select the isolated atlas graph and return it with its Redis client.
Builds an async
FalkorDBover the Redis client’s connection pool and selects the dedicatedATLAS_GRAPH_NAME(stargazer_feature_interaction_atlas) namespace, keeping all atlas work off the production knowledge graph’s keyspace. When no client is passed it opens one throughget_redis().This connects to FalkorDB over Redis. It is the standard entry point for every atlas script –
load_features_to_falkor,detect_code_interactions,generate_interaction_prompts,import_interaction_analysis,query_atlas, andexport_sarah_demoeach call it to obtain a graph handle before running queries or merges.
- async tools.feature_atlas.atlas_connection.atlas_query(graph, cypher, params=None)[source]
Run a read-write Cypher query against the atlas graph with error logging.
Thin wrapper over the FalkorDB graph’s
querymethod that logs the exception and a truncated copy of the failing Cypher before re-raising, so write failures surface with enough context to debug. This is the mutating path (it allowsMERGE/SET), distinct from the read-onlyatlas_ro_query().It executes Cypher against FalkorDB. It is called by all of the MERGE helpers in this module –
merge_feature(),merge_code_interaction(),merge_interaction_prompt(), andmerge_interaction_analysis()(the last also using it for a follow-up status update).- Parameters:
- Returns:
The FalkorDB query result object.
- Return type:
- Raises:
Exception – Re-raises any error from the underlying
querycall after logging it.
- async tools.feature_atlas.atlas_connection.atlas_ro_query(graph, cypher, params=None)[source]
Run a read-only Cypher query against the atlas graph with error logging.
Mirrors
atlas_query()but routes through the FalkorDB graph’sro_querymethod, which the engine can fan out to replicas and which forbids mutations – the safe path for analytics and dashboards over the atlas. On failure it logs the error and a truncated copy of the Cypher before re-raising.It executes read-only Cypher against FalkorDB. No caller invokes this module-level wrapper today (the read paths in
query_atlasandatlas_query_toolcallgraph.ro_querydirectly); it is provided as the read-only counterpart toatlas_query()for atlas tooling.- Parameters:
- Returns:
The FalkorDB query result object.
- Return type:
- Raises:
Exception – Re-raises any error from the underlying
ro_querycall after logging it.
- async tools.feature_atlas.atlas_connection.merge_feature(graph, feature)[source]
Upsert a Feature node into the atlas graph, idempotently.
Runs a
MERGEon(:Feature {id})andSETof the descriptive properties (human name, category, description, plus the list-valued files, symbols, entrypoints, data stores, and external tools serialised to JSON strings, and a confidence score), stampingupdated_atevery time andcreated_atonly on first insert. Re-running with the same id refreshes the node in place rather than duplicating it.It writes to FalkorDB through
atlas_query(). It is called bytools/feature_atlas/load_features_to_falkor.pyin a loop over the feature registry.
- async tools.feature_atlas.atlas_connection.merge_code_interaction(graph, interaction)[source]
Upsert a CODE_INTERACTS_WITH edge between two existing Feature nodes.
Matches the source and target
(:Feature)nodes by id and merges aCODE_INTERACTS_WITHrelationship keyed on itsmechanism, then sets the confidence, the JSON-serialised file and symbol references, the free-text evidence, and the direction, stampingcreated_atonly on first insert. Because the merge is keyed on mechanism, two features can be linked by several distinct interaction edges. Both endpoint features must already exist (typically loaded bymerge_feature()first).It writes to FalkorDB through
atlas_query(). It is called bytools/feature_atlas/detect_code_interactions.pyfor each detected static interaction.
- async tools.feature_atlas.atlas_connection.merge_interaction_prompt(graph, source_id, target_id, prompt, status='pending')[source]
Upsert an InteractionPrompt node wired between two Feature nodes.
Matches the source and target
(:Feature)nodes and merges anInteractionPromptkeyed on the(source_id, target_id)pair, linking it as(src)-[:HAS_INTERACTION]->(prompt)-[:TARGETS]->(tgt)and storing the generated prompt text and a workflowstatus(defaultpending). These prompt nodes are the queue an offline LLM pass later consumes to produce analyses, so re-running updates the prompt without creating a duplicate.It writes to FalkorDB through
atlas_query(). It is called bytools/feature_atlas/generate_interaction_prompts.pyfor each candidate feature pair.- Parameters:
- Return type:
- async tools.feature_atlas.atlas_connection.merge_interaction_analysis(graph, analysis)[source]
Upsert an InteractionAnalysis node and mark its prompt completed.
Matches the
InteractionPromptfor the(source_id, target_id)pair and merges a(prompt)-[:PRODUCED]->(:InteractionAnalysis)node, storing the LLM-derived findings: the summary, the direct/indirect interaction and shared-state narratives, memory/NCM/routing/prompt-context effects, the JSON-serialised failure modes, security risks, recommended tests and constraints and source refs, and the synergy/risk/weirdness/confidence scores. After the upsert it issues a second query setting the originating prompt’sstatustocompletedso the analysis queue drains.It writes to FalkorDB via two
atlas_query()calls (the merge plus the status update). It is called bytools/feature_atlas/import_interaction_analysis.pyfor each completed analysis record.