tools.user_variables module

Per-user per-channel variables (v3)

Variables are stored as Redis hashes and auto-injected into context for recent active users.

async tools.user_variables.get_user_variables_for_context(channel_id, user_id, *, redis_client=None, config=None)

Return a flat name-to-value map of a user’s variables in a channel.

This is the non-tool read path used to feed stored variables into the model’s context (and into the xray inspection tool), so it returns just the raw values keyed by name rather than the metadata-rich shape the list tool produces. Like the tool handlers it merges across the user’s linked identities.

It expands aliases via _get_user_aliases and runs hgetall on each alias’s hash (addressed by _var_key) using the supplied redis_client, loading non-active aliases first and the active alias last so the active identity’s value wins on collision. All errors are caught and logged, returning an empty map so a lookup failure never breaks prompt assembly. It is called by get_all_active_user_variables (this module) and by tools/xray_tool.py (to inspect a target user’s variables).

Parameters:

• channel_id (str) – The channel whose variables to read.

• user_id (str) – A raw or platform-prefixed user id whose aliases are merged.

• redis_client – The async Redis client to query; None yields an empty map.

• config – Optional config used for alias resolution.

Return type:

Dict[str, Any]

Returns:

A {name: value} dict of the user’s variables in the channel (empty on any error or when none are set).

async tools.user_variables.get_recent_active_users(channel_id, *, redis_client=None, limit=5)

Return the most recently active distinct users in a channel.

Identifies who has spoken recently so their stored variables can be surfaced to the model. It reads the channel’s message log and de-duplicates authors, preserving recency order, which is exactly the set the variable auto-injection targets.

It pulls the newest entries (up to 100) from the Redis sorted set stargazer_logs:{channel_id} via zrevrange on the supplied redis_client, JSON-decodes each message, skips sentinel/zero author ids, and collects unique {user_id, display_name} entries until limit is reached. All errors are caught and logged, returning an empty list so a failure never breaks context assembly. It is called by get_all_active_user_variables (this module) and, for timezone/context injection, by prompt_context.py and message_processor/context_injections.py.

Parameters:

• channel_id (str) – The channel whose recent authors to enumerate.

• redis_client – The async Redis client to query; None yields an empty list.

• limit (int) – Maximum number of distinct users to return (default 5).

Return type:

List[Dict[str, str]]

Returns:

A list of {"user_id", "display_name"} dicts in most-recent-first order (empty on any error or when the channel log is empty).

async tools.user_variables.get_all_active_user_variables(channel_id, *, redis_client=None, config=None, limit=5)

Collect stored variables for the most recently active users in a channel.

This is the aggregate the prompt layer wants: it answers “what variables should I inject for the people currently active here”. It first finds the recent speakers via get_recent_active_users, then for each pulls their merged variables via get_user_variables_for_context, keeping only users that actually have variables set.

Both reads go through the supplied redis_client; all errors are caught and logged, returning an empty list so context assembly is never broken. No callers exist in the repo today (it is a ready-to-use aggregation entry point for variable auto-injection).

Parameters:

• channel_id (str) – The channel whose active users’ variables to collect.

• redis_client – The async Redis client to query.

• config – Optional config used for alias resolution.

• limit (int) – Maximum number of recent users to consider (default 5).

Return type:

List[Dict[str, Any]]

Returns:

A list of {"user_id", "display_name", "variables"} dicts for each recent user that has at least one variable set (empty on error or when none qualify).