skobkin/telegram-ollama-reply-bot

Fork 0

list_active_context_objects tool #98

New issue

Open

opened 2026-04-20 04:41:24 +03:00 by skobkin · 0 comments

skobkin commented

2026-04-20 04:41:24 +03:00

Owner

PRD: list_active_context_objects

Summary
Implement a deterministic tool that returns a compact list of currently active conversational objects for the current scope. “Active” does not mean “mentioned somewhere recently”; it means the object was explicitly touched by a meaningful bot/user interaction and is still relevant within a bounded TTL and scope. The purpose is to support safe follow-up flows without confusing the model with unrelated recent items.

Goal
Provide a compact, scoped snapshot of objects that are currently good candidates for follow-up actions or follow-up questions.

Non-goals

No attempt to identify one true target.
No full chat history retrieval.
No cross-chat listing.
No language-specific heuristics.
No persistence requirement beyond existing in-memory state.

Why
The bot will support active articles, media handling, reminders, polls, summaries, and similar flows. Follow-up interactions need a compact way to know what objects are “live” in the current conversational scope without scanning raw history.

Definition of active
An object becomes active only through explicit activation events, not by mere mention.

Examples of activation events

article summarized
URL fetched and discussed
media inspected / described / transcribed
poll created or listed
reminder created / listed / updated
summary generated and then reused
object explicitly resolved by resolve_reference_target
bot attached follow-up actions to it

Examples of non-activation

random old link in history
unrelated media from another topic
stale object with no recent interaction
object only mentioned in passing with no action around it

Supported object kinds

article
link
media.image
media.video
media.voice
media.document
media.pdf
poll
reminder
summary
bot_message
message

Scope rules
The listing must be scoped in this priority order:

current reply chain
current topic/thread
current chat fallback

The tool must strongly prefer same-topic activity in supergroups with topics.

Inputs
Conceptual request fields:

chat_id
topic_id (optional)
current_message_id
reply_to_message_id (optional)
sender_user_id
allowed_kinds (optional)
max_results (default 5)
include_inactive_debug (default false, test/dev only)

State model
The tool reads from in-memory indexed state only.
Each stored object should be associated with:

object_id
kind
chat_id
topic_id
source_message_id
created_at
last_touched_at
activation_reasons
created_by_user_id (optional)
created_by_bot
ttl_class
active_until or derived expiry policy

TTL guidance
Use per-kind TTLs so activity decays naturally:

article / summary: medium TTL
media follow-up: short-medium TTL
reminder management context: short TTL after listing or updating
poll: while open, plus short grace period after close
explicit resolver touch: refresh within its kind TTL, not indefinitely

The exact durations should be configurable, not hardcoded.

Output
Return a compact ordered list of active objects, not raw history.

Suggested output shape

objects: ordered list
scope_used: reply_chain | topic | chat
generated_at
truncated: bool

Each returned object should include:

object_id
kind
source_message_id
title_or_label (short, optional)
confidence
why_active: compact reason codes
created_at
last_touched_at
created_by_bot
owned_by_sender (bool, if known)

Ranking
Rank objects using deterministic rules:

same reply chain: highest
same topic: very high
recently touched: high
explicitly activated by bot/user action: high
still-open poll / future reminder: medium-high
exact kind filter match: high
sender-owned object when relevant: medium
chat-only fallback: penalty
near-expiry / stale: penalty

Reason codes
Examples:

touched_recently
activated_by_summary
activated_by_media_inspection
activated_by_poll_create
activated_by_reminder_list
activated_by_resolver
same_reply_chain
same_topic
open_poll
future_reminder
sender_owned
chat_scope_fallback

Behavior requirements

Must return only compact object summaries.
Must not invent activeness from plain recency alone.
Must degrade gracefully when no active objects exist.
Must be deterministic and cheap.
Must be safe in busy chats with multiple parallel topics.

Important design rule
This tool is for contextual awareness, not final target selection.
If the caller needs a single best target, it should call resolve_reference_target after or instead of this tool.

When to use
Good use cases:

“what are we currently discussing?”
follow-up after a summary or media analysis
reminder/poll/article continuation flows
giving the model compact awareness before deciding next step

Bad use cases:

replacing recent-history search
deciding the final target for an ambiguous command
broad recall over old chat material

Edge cases

No active objects: return empty list, not synthetic guesses.
Several active objects in same topic: return top N ordered by score.
Different topics have active objects: do not mix unless falling back from missing topic state.
Old active article plus newly created poll: both may appear if both remain valid in the same scope.
Reply to old message in active topic: reply-chain relevance may outrank general topic activeness.
Topicless chat: operate in chat scope only.

Implementation notes

Reuse the same object descriptor type as resolve_reference_target where practical.
Keep activation and ranking logic centralized to avoid drift across tools.
Make TTLs and score weights configurable.
Keep indexes cheap and explicit: by chat, topic, kind, source_message_id, created_by_user_id, and last_touched_at.

Observability
Log compactly:

request id
chat_id
topic_id
result count
scope_used
top object ids
whether truncation occurred

Tests
Must include focused tests for:

activation by summary/media/poll/reminder events
no activation from plain mention
topic isolation
reply-chain precedence
stale object expiry
mixed active object ordering
allowed_kinds filtering
empty result behavior

Acceptance criteria

The tool returns useful active objects without dragging in unrelated recent history.
Topic-aware chats do not get polluted by neighboring discussions.
The output is compact and stable enough for repeated tool-loop use.
The implementation is deterministic and covered by focused tests.

Caused by #92 and #95, related to #97

PRD: list_active_context_objects Summary Implement a deterministic tool that returns a compact list of currently active conversational objects for the current scope. “Active” does not mean “mentioned somewhere recently”; it means the object was explicitly touched by a meaningful bot/user interaction and is still relevant within a bounded TTL and scope. The purpose is to support safe follow-up flows without confusing the model with unrelated recent items. Goal Provide a compact, scoped snapshot of objects that are currently good candidates for follow-up actions or follow-up questions. Non-goals - No attempt to identify one true target. - No full chat history retrieval. - No cross-chat listing. - No language-specific heuristics. - No persistence requirement beyond existing in-memory state. Why The bot will support active articles, media handling, reminders, polls, summaries, and similar flows. Follow-up interactions need a compact way to know what objects are “live” in the current conversational scope without scanning raw history. Definition of active An object becomes active only through explicit activation events, not by mere mention. Examples of activation events - article summarized - URL fetched and discussed - media inspected / described / transcribed - poll created or listed - reminder created / listed / updated - summary generated and then reused - object explicitly resolved by resolve_reference_target - bot attached follow-up actions to it Examples of non-activation - random old link in history - unrelated media from another topic - stale object with no recent interaction - object only mentioned in passing with no action around it Supported object kinds - article - link - media.image - media.video - media.voice - media.document - media.pdf - poll - reminder - summary - bot_message - message Scope rules The listing must be scoped in this priority order: 1. current reply chain 2. current topic/thread 3. current chat fallback The tool must strongly prefer same-topic activity in supergroups with topics. Inputs Conceptual request fields: - chat_id - topic_id (optional) - current_message_id - reply_to_message_id (optional) - sender_user_id - allowed_kinds (optional) - max_results (default 5) - include_inactive_debug (default false, test/dev only) State model The tool reads from in-memory indexed state only. Each stored object should be associated with: - object_id - kind - chat_id - topic_id - source_message_id - created_at - last_touched_at - activation_reasons - created_by_user_id (optional) - created_by_bot - ttl_class - active_until or derived expiry policy TTL guidance Use per-kind TTLs so activity decays naturally: - article / summary: medium TTL - media follow-up: short-medium TTL - reminder management context: short TTL after listing or updating - poll: while open, plus short grace period after close - explicit resolver touch: refresh within its kind TTL, not indefinitely The exact durations should be configurable, not hardcoded. Output Return a compact ordered list of active objects, not raw history. Suggested output shape - objects: ordered list - scope_used: reply_chain | topic | chat - generated_at - truncated: bool Each returned object should include: - object_id - kind - source_message_id - title_or_label (short, optional) - confidence - why_active: compact reason codes - created_at - last_touched_at - created_by_bot - owned_by_sender (bool, if known) Ranking Rank objects using deterministic rules: - same reply chain: highest - same topic: very high - recently touched: high - explicitly activated by bot/user action: high - still-open poll / future reminder: medium-high - exact kind filter match: high - sender-owned object when relevant: medium - chat-only fallback: penalty - near-expiry / stale: penalty Reason codes Examples: - touched_recently - activated_by_summary - activated_by_media_inspection - activated_by_poll_create - activated_by_reminder_list - activated_by_resolver - same_reply_chain - same_topic - open_poll - future_reminder - sender_owned - chat_scope_fallback Behavior requirements - Must return only compact object summaries. - Must not invent activeness from plain recency alone. - Must degrade gracefully when no active objects exist. - Must be deterministic and cheap. - Must be safe in busy chats with multiple parallel topics. Important design rule This tool is for contextual awareness, not final target selection. If the caller needs a single best target, it should call resolve_reference_target after or instead of this tool. When to use Good use cases: - “what are we currently discussing?” - follow-up after a summary or media analysis - reminder/poll/article continuation flows - giving the model compact awareness before deciding next step Bad use cases: - replacing recent-history search - deciding the final target for an ambiguous command - broad recall over old chat material Edge cases - No active objects: return empty list, not synthetic guesses. - Several active objects in same topic: return top N ordered by score. - Different topics have active objects: do not mix unless falling back from missing topic state. - Old active article plus newly created poll: both may appear if both remain valid in the same scope. - Reply to old message in active topic: reply-chain relevance may outrank general topic activeness. - Topicless chat: operate in chat scope only. Implementation notes - Reuse the same object descriptor type as resolve_reference_target where practical. - Keep activation and ranking logic centralized to avoid drift across tools. - Make TTLs and score weights configurable. - Keep indexes cheap and explicit: by chat, topic, kind, source_message_id, created_by_user_id, and last_touched_at. Observability Log compactly: - request id - chat_id - topic_id - result count - scope_used - top object ids - whether truncation occurred Tests Must include focused tests for: - activation by summary/media/poll/reminder events - no activation from plain mention - topic isolation - reply-chain precedence - stale object expiry - mixed active object ordering - allowed_kinds filtering - empty result behavior Acceptance criteria - The tool returns useful active objects without dragging in unrelated recent history. - Topic-aware chats do not get polluted by neighboring discussions. - The output is compact and stable enough for repeated tool-loop use. - The implementation is deterministic and covered by focused tests. --- Caused by #92 and #95, related to #97

skobkin referenced this issue

2026-04-20 04:41:38 +03:00

resolve_reference_target tool #97

skobkin referenced this issue

2026-04-20 04:42:06 +03:00

Tool ideas #95