tools.feature_atlas.query_atlas module

Step 7: Interactive CLI for querying the Feature Interaction Atlas.

Provides commands for inspecting features, top risks/synergies, feature neighborhoods, and generating the Sarah demo report.

Style matches memory_search.py – ANSI terminal colors, clean formatting, designed for SSH access.

Usage:

python -m tools.feature_atlas.query_atlas stats python -m tools.feature_atlas.query_atlas list-features python -m tools.feature_atlas.query_atlas top-risks python -m tools.feature_atlas.query_atlas top-synergies python -m tools.feature_atlas.query_atlas feature-neighborhood CoreMemory python -m tools.feature_atlas.query_atlas explain-pair NCMStateEngine PersonaPrefillLayer python -m tools.feature_atlas.query_atlas missing-evidence python -m tools.feature_atlas.query_atlas sarah-demo python -m tools.feature_atlas.query_atlas –interactive

# fire skull spider – THE WITCH READS HER OWN X-RAY

class tools.feature_atlas.query_atlas.C

Bases: object

ANSI color/style escape codes for the Atlas CLI’s terminal output.

A namespace of raw SGR escape sequences (RESET, BOLD, DIM and the color constants) plus small staticmethod() helpers such as header() that wrap text in a style and reset it. Mirrors the palette in memory_search.py and is used by the cmd_* query functions and interactive_mode to colorize results when this module runs as a CLI.

RESET = '\x1b[0m'

BOLD = '\x1b[1m'

DIM = '\x1b[2m'

PURPLE = '\x1b[35m'

CYAN = '\x1b[36m'

GREEN = '\x1b[32m'

YELLOW = '\x1b[33m'

RED = '\x1b[31m'

MAGENTA = '\x1b[95m'

WHITE = '\x1b[97m'

static header(text)

Wrap text in bold-purple ANSI codes for a section header.

Prefixes the string with BOLD``+``PURPLE and appends RESET so the styling does not leak into subsequent output. Called by every cmd_* query function and interactive_mode in this module to render banner-style section titles.

Parameters:

text (str) – The header label to colorize.

Returns:

text wrapped in the bold-purple/reset escape sequence.

Return type:

str

static entity(text)

Wrap text in bold-cyan ANSI codes to highlight an entity name.

Used to make feature ids and interaction endpoints stand out in terminal output. Called by cmd_list_features, cmd_top_risks, cmd_top_synergies, cmd_feature_neighborhood, and cmd_explain_pair to style feature/interaction identifiers.

Parameters:

text (str) – The entity label (e.g. a feature id) to colorize.

Returns:

text wrapped in the bold-cyan/reset escape sequence.

Return type:

str

static score_color(score)

Pick an ANSI color for a 0-1 score using fixed risk thresholds.

Maps scores to a traffic-light scheme: red for >= 0.7 (high), yellow for >= 0.4 (medium), and green otherwise (low). Called by C.bar to color the filled portion of its meter; no other callers were found in the repository.

Parameters:

score (float) – A score in the [0.0, 1.0] range.

Returns:

The bare ANSI color escape (C.RED, C.YELLOW, or C.GREEN) corresponding to the score’s severity band.

Return type:

str

static bar(score, width=20)

Render a colored fixed-width text meter for a 0-1 score.

Fills int(score * width) cells with # and pads the remainder with dimmed . characters, coloring the filled run via C.score_color. Used throughout this module to visualize risk, synergy, weirdness, and confidence values in cmd_stats, cmd_list_features, cmd_top_risks, cmd_top_synergies, cmd_feature_neighborhood, and cmd_explain_pair.

Parameters:

• score (float) – A score in the [0.0, 1.0] range determining the fill fraction and color.

• width (int) – Total number of cells in the bar (default 20).

Returns:

The colored, reset-terminated meter string.

Return type:

str

async tools.feature_atlas.query_atlas.cmd_stats(graph)

Print summary counts and average scores for the atlas graph.

Renders a terminal overview of the Feature Interaction Atlas: node and edge tallies (features, CODE_INTERACTS_WITH edges, interaction prompts, completed analyses, pending prompts), a per-category feature breakdown, and average risk/synergy/weirdness/confidence scores across all InteractionAnalysis nodes. Each count comes from a read-only Cypher call to graph.ro_query against the FalkorDB atlas namespace (stargazer_feature_interaction_atlas); per-query failures are caught and printed in red rather than aborting the whole summary. Output goes to stdout via print using the ANSI helpers C.header and C.bar. Called by interactive_mode (the stats REPL command) and by async_main for the stats subcommand.

Parameters:

graph (Any) – The FalkorDB atlas graph handle exposing ro_query.

Return type:

None

Returns:

None. Results are written to stdout.

async tools.feature_atlas.query_atlas.cmd_list_features(graph)

Print every Feature node grouped by category.

Lists all features in the atlas, sorted by category then id, emitting a bold category header whenever the category changes and one line per feature with a confidence meter and human-readable name. The feature rows come from a single read-only graph.ro_query against the FalkorDB atlas; output is written to stdout via print using C.header, C.entity, and C.bar. When the graph holds no features it prints a dim “No features found” notice and returns early. Called by interactive_mode (the features/ls REPL command) and by async_main for the list-features subcommand.

Parameters:

graph (Any) – The FalkorDB atlas graph handle exposing ro_query.

Return type:

None

Returns:

None. Results are written to stdout.

async tools.feature_atlas.query_atlas.cmd_top_risks(graph, limit=10)

Print the highest-risk analyzed interactions, worst first.

Queries InteractionAnalysis nodes ordered by risk_score descending and prints up to limit of them, each as a source-to-target heading followed by risk, synergy, and weirdness meters and a word-wrapped summary. Data comes from a single read-only graph.ro_query against the FalkorDB atlas; output is written to stdout via print using C.header, C.entity, C.bar, and textwrap.fill. When no analyses exist it prints a dim notice and returns early. Called by interactive_mode (the risks REPL command, which parses an optional numeric argument) and by async_main for the top-risks subcommand (which passes args.limit).

Parameters:

• graph (Any) – The FalkorDB atlas graph handle exposing ro_query.

• limit (int) – Maximum number of interactions to display (default 10). This value is interpolated directly into the Cypher LIMIT clause.

Return type:

None

Returns:

None. Results are written to stdout.

async tools.feature_atlas.query_atlas.cmd_top_synergies(graph, limit=10)

Print the highest-synergy analyzed interactions, best first.

The synergy-ranked counterpart to cmd_top_risks: queries InteractionAnalysis nodes ordered by synergy_score descending and prints up to limit of them, each as a source-to-target heading followed by synergy, risk, and weirdness meters and a word-wrapped summary. Data comes from a single read-only graph.ro_query against the FalkorDB atlas; output is written to stdout via print using C.header, C.entity, C.bar, and textwrap.fill. When no analyses exist it prints a dim notice and returns early. Called by interactive_mode (the synergies REPL command, with an optional numeric argument) and by async_main for the top-synergies subcommand (which passes args.limit).

Parameters:

• graph (Any) – The FalkorDB atlas graph handle exposing ro_query.

• limit (int) – Maximum number of interactions to display (default 10). This value is interpolated directly into the Cypher LIMIT clause.

Return type:

None

Returns:

None. Results are written to stdout.

async tools.feature_atlas.query_atlas.cmd_feature_neighborhood(graph, feature_id)

Print a full profile of one feature and everything touching it.

Gives a 360-degree view of a single Feature: its metadata (name, category, confidence meter, description, and first ten source files), then its outgoing and incoming CODE_INTERACTS_WITH edges with mechanism, confidence, and a truncated evidence snippet, and finally up to ten InteractionAnalysis rows that name it as source or target. This issues four separate parameterized read-only graph.ro_query calls against the FalkorDB atlas (all keyed on feature_id via $id), and decodes the JSON files blob with json.loads. Output goes to stdout via print using C.header, C.entity, C.bar, and textwrap.fill; a missing feature prints a red notice and returns early. Called by interactive_mode (the hood/neighborhood REPL command) and by async_main for the feature-neighborhood subcommand.

Parameters:

• graph (Any) – The FalkorDB atlas graph handle exposing ro_query.

• feature_id (str) – The id of the feature to inspect, bound to the $id Cypher parameter.

Return type:

None

Returns:

None. Results are written to stdout.

async tools.feature_atlas.query_atlas.cmd_explain_pair(graph, source_id, target_id)

Print the complete stored analysis for one ordered feature pair.

Looks up the single InteractionAnalysis matching source_id -> target_id and renders every recorded field: the narrative sections (summary, direct and indirect interaction, shared state, memory, NCM, routing, and prompt-context effects), the JSON list fields (failure modes, security risks, recommended tests and constraints, source refs), and the four numeric scores with meters. The data comes from one parameterized read-only graph.ro_query against the FalkorDB atlas (bound via $s and $t); list fields are parsed with json.loads when stored as strings. Output is written to stdout via print using C.header, C.bar, and textwrap.fill; a missing pair prints a dim notice and returns early. Called by interactive_mode (the pair/explain REPL command) and by async_main for the explain-pair subcommand.

Parameters:

• graph (Any) – The FalkorDB atlas graph handle exposing ro_query.

• source_id (str) – The interaction source feature id, bound to $s.

• target_id (str) – The interaction target feature id, bound to $t.

Return type:

None

Returns:

None. Results are written to stdout.

async tools.feature_atlas.query_atlas.cmd_missing_evidence(graph)

Print features whose confidence is below 0.5, weakest first.

Surfaces under-evidenced features so a human can prioritize follow-up: selects every Feature with confidence < 0.5, ordered ascending, and prints each id in red alongside its confidence, its source-file count (derived by json.loads on the stored files blob), and its human name. Data comes from one read-only graph.ro_query against the FalkorDB atlas; output is written to stdout via print using C.header. When no feature falls below the threshold it prints a green “all features have confidence >= 0.5” message and returns early. Called by interactive_mode (the missing REPL command) and by async_main for the missing-evidence subcommand.

Parameters:

graph (Any) – The FalkorDB atlas graph handle exposing ro_query.

Return type:

None

Returns:

None. Results are written to stdout.

async tools.feature_atlas.query_atlas.cmd_sarah_demo(graph)

Build and print the curated “Sarah” demo report inline.

Lazily imports generate_demo_report from tools.feature_atlas.export_sarah_demo (kept inside the function so the rest of the CLI works even if that module is unavailable), awaits it against the live atlas graph to assemble the formatted demo string, and prints the result to stdout. The report itself runs further read-only queries against the FalkorDB atlas inside generate_demo_report. Called by interactive_mode (the demo/sarah REPL command) and by async_main for the sarah-demo subcommand.

Parameters:

graph (Any) – The FalkorDB atlas graph handle passed through to generate_demo_report.

Return type:

None

Returns:

None. The rendered report is written to stdout.

tools.feature_atlas.query_atlas.print_banner()

Print the boxed ASCII banner for the atlas query CLI.

Writes a purple/bold framed title block (“FEATURE INTERACTION ATLAS” / “Stargazer Bodygraph”) to stdout via print. Purely cosmetic with no graph or I/O side effects beyond the terminal write. Called by interactive_mode once at REPL startup and by async_main before each non-interactive subcommand so single-shot invocations are also branded. (Note: memory_search.py defines its own same-named banner; they are independent.)

Return type:

None

Returns:

None. The banner is written to stdout.

async tools.feature_atlas.query_atlas.interactive_mode(graph)

Run the blocking REPL loop that dispatches atlas query commands.

Prints the banner and a command cheat-sheet, then loops reading lines from stdin via the builtin input (so it blocks the event loop on terminal I/O), splitting each into a command plus arguments and awaiting the matching cmd_* coroutine: stats, features/ls, risks/synergies (with an optional numeric limit), hood, pair, missing, and demo. quit/exit/q and EOF or Ctrl-C break the loop; unknown commands and any exception raised by a handler are reported in red and the loop continues. All work flows through the shared graph handle into the FalkorDB atlas. Called by async_main when the --interactive flag is set or the command defaults to interactive.

Parameters:

graph (Any) – The FalkorDB atlas graph handle passed to each dispatched cmd_* coroutine.

Return type:

None

Returns:

None. Returns when the user quits or input ends.

async tools.feature_atlas.query_atlas.async_main()

Parse CLI arguments, open the atlas graph, and dispatch one command.

The asynchronous core of the CLI: it builds the argparse parser (positional command plus extra args, --limit/-n, and --interactive/-i), opens a connection to the FalkorDB atlas via get_atlas_graph (lazily imported from tools.feature_atlas.atlas_connection), then routes to the appropriate handler: interactive_mode for the interactive flag/command, or one of the cmd_* coroutines (preceded by print_banner) for a single-shot subcommand. feature-neighborhood and explain-pair validate that their positional ids are present and otherwise print a usage hint. The Redis connection returned alongside the graph is always closed via rc.aclose() in a finally block. Called by main through asyncio.run(async_main()).

Return type:

None

Returns:

None.

tools.feature_atlas.query_atlas.main()

Configure logging and run the async CLI to completion.

The synchronous process entry point: sets up basic WARNING-level logging and then drives the whole CLI via asyncio.run(async_main()), which parses arguments, opens the atlas graph, and dispatches the chosen command. Invoked from this module’s __main__ guard (e.g. python -m tools.feature_atlas.query_atlas ...); no other internal caller exists.

Return type:

None

Returns:

None.