mmintel/instagram-bot
1
0
Fork 0
Code Issues Pull Requests 4 Actions Packages Projects Releases Wiki Activity

refactor: purge localized hardcoded strings and enforce language agnosticism

Browse Source
This commit is contained in:
Marc Mintel
2026-05-04 14:17:05 +02:00
parent 49f82d467f
commit 3f778d46c9
317 changed files with 303 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
GramAddict/core/dm_engine.py
View File

@@ -14,20 +14,23 @@ MAX_REPLIES_PER_INBOX_VISIT = 3
_EMPTY_CONTEXT_SENTINELS = frozenset({"no previous context", "", "none", "n/a"})
# Structural resource-IDs that indicate a real "Send" button.
def _is_send_button(node: dict) -> bool:
"""Semantic verification: returns True if the node is identified as a Send button."""
desc = (node.get("description") or node.get("desc", "")).lower()
text = (node.get("text") or "").lower()
"""
Structural verification: returns True if the node is identified as a Send button.
NO hardcoded UI strings (no localized 'send' or 'absenden').
"""
rid = (node.get("id") or node.get("resource_id", "")).lower()
# Accept if semantic markers indicate sending
if any(m in rid for m in ["send", "composer_button"]):
# 1. Structural Resource IDs (Language agnostic)
if "send" in rid or "composer_button" in rid or "direct_send_button_text" in rid:
return True
if any(m in desc for m in ["send", "absenden"]):
return True
if text == "send" or text == "absenden":
# 2. Spatial Guard: The send button in a DM thread is ALWAYS on the far right side of the screen
# next to the composer input.
x = node.get("x", 0)
if int(x) > (1080 * 0.75):
return True
return False

4
GramAddict/core/perception/action_memory.py
View File

@@ -220,8 +220,8 @@ class ActionMemory:
)
if is_toggle:
prompt += (
"If the intent was 'follow', does the button now indicate 'Following' or 'Requested'? "
"If it was 'like', is the heart icon clearly active/red? "
"If the intent was 'follow', did the button change its visual state to indicate an active subscription? "
"If it was 'like', is the heart icon clearly active/filled? "
"If the screen shifted completely to a profile when you just wanted to like/follow from a feed, it FAILED. "
"If the tapped element does NOT sound like a like/follow button (e.g. it's a caption, comment field, or post content), it FAILED. "
)

44
GramAddict/core/perception/intent_resolver.py
View File

@@ -30,6 +30,11 @@ class IntentResolver:
bounding boxes around clickable candidates, sends the annotated image to the VLM,
and lets the VLM visually decide which box to tap.
CRITICAL ARCHITECTURE RULE: Language Agnosticism & Structural Determinism
- NO hardcoded localized UI strings (e.g. "follow", "message", "like") are permitted.
- All non-VLM resolution logic MUST rely strictly on spatial coordinates (e.g. center_x bounds)
or structural Android resource IDs.
Architecture:
1. Navigation tabs → structural zone guard (bottom 15%, resource-id)
2. Everything else → Visual Discovery (screenshot + numbered boxes + VLM)
@@ -137,8 +142,17 @@ class IntentResolver:
# This prevents the weak VLM from hallucinating bounding box numbers that point to "Comment".
interaction_suffixes = ["comment", "like", "share", "send", "save", "button_icon", "scrubber"]
is_interaction = any(s in rid for s in interaction_suffixes) or any(s in desc for s in interaction_suffixes)
node_text_lower = (node.text or "").lower()
is_follow = "follow" in rid or "follow" in node_text_lower or "follow" in desc
# SPATIAL GUARD (NO HARDCODED STRINGS): The post author (avatar/name) is always strictly on the left side of the screen.
# The "More options" (Report menu) button is strictly on the far right.
# We enforce a mathematical boundary to prevent LLM hallucinations from clicking the report menu.
if is_author_intent and node.center_x > (1080 * 0.75):
logger.debug(
f"🛡️ [Author Spatial Guard] Excluded far-right element '{node.resource_id}' "
f"(x={node.center_x}) for author intent '{intent_description}'"
)
continue
is_follow = "button_follow" in rid or "ufi_follow" in rid
is_media_intent = "media content" in intent_lower or "image" in intent_lower or "video" in intent_lower
if (is_author_intent or is_media_intent) and (is_interaction or is_follow):
@@ -309,10 +323,8 @@ class IntentResolver:
if ("send" in intent_lower or "share" in intent_lower) and "post" in intent_lower and "button" in intent_lower:
for node in candidates:
rid = (node.resource_id or "").lower()
desc = (node.content_desc or "").lower()
# Feed uses row_feed_button_share, POST_DETAIL may use direct_share_button or just desc "Send"
if "row_feed_button_share" in rid or "direct_share_button" in rid or "send" in desc or "share" in desc:
logger.info(f"🎯 [Structural Fast-Path] Found send/share post button: {rid or desc}")
if "row_feed_button_share" in rid or "direct_share_button" in rid or "button_share" in rid:
logger.info(f"🎯 [Structural Fast-Path] Found send/share post button: {rid}")
return node
if "add to story" in intent_lower:
@@ -708,14 +720,14 @@ class IntentResolver:
f"CRITICAL RULES:\n"
f"1. If the intent contains a word in quotes (e.g., 'Search', 'New Message'), you MUST look at the Box legend and pick the box that contains that word (case-insensitive). Do not pick anything else.\n"
f"2. For icons without text:\n"
f" - 'like button' = HEART-SHAPED ICON (♡/❤), usually has desc='Like'.\n"
f" - 'comment button' = SPEECH BUBBLE ICON, usually has desc='Comment'.\n"
f" - 'like button' = HEART-SHAPED ICON (♡/❤), look for id containing 'button_like' or 'ufi_heart'.\n"
f" - 'comment button' = SPEECH BUBBLE ICON, look for id containing 'button_comment' or 'ufi_comment'.\n"
f"3. Do NOT select text, captions, or view counts if looking for an icon.\n"
f"4. Ignore numbers inside the text itself. Do not confuse the text '19' with Box [19].\n"
f"5. If the intent contains 'following', you MUST pick the box containing 'following'. Do NOT pick 'followers' or 'Follow'.\n"
f"5. If the intent contains 'following', you MUST pick the box containing id 'button_following' or 'profile_header_following'. Do NOT pick 'followers' or 'Follow'.\n"
f"6. If the intent is to tap a 'post', 'first post', or 'grid item':\n"
f" - Look for boxes with descriptions containing 'photos by', 'Reel by', or 'row 1, column 1'.\n"
f" - Pick the FIRST matching box index (e.g. if [0] says '6 photos...', return 0, NOT 6).\n"
f" - Look for boxes with ids like 'image_button' inside a grid, or visual grid thumbnails.\n"
f" - Pick the FIRST matching box index.\n"
f" - Do NOT pick navigation buttons like 'Search'.\n"
f"7. If the intent is a bottom navigation tab (e.g. 'profile tab', 'home tab'):\n"
f" - These are always at the BOTTOM edge of the screen.\n"
@@ -724,17 +736,17 @@ class IntentResolver:
f" - 'explore tab' is the magnifying glass.\n"
f" - 'reels tab' is the video clapperboard.\n"
f"8. If the intent involves 'author username' or 'author profile':\n"
f" - Pick the profile picture (e.g. 'Profile picture of <username>') or the username text.\n"
f" - NEVER pick a 'Follow' button. Do NOT pick 'Follow <username>'.\n"
f" - Pick the profile picture or the username text.\n"
f" - NEVER pick a 'Follow' button. Do NOT pick 'button_follow'.\n"
f"9. If the intent is 'save post':\n"
f" - The save icon is the bookmark icon on the bottom right of the post image/video.\n"
f" - Usually has desc='Add to Saved' or 'Save'. Do NOT pick the post text or other action buttons.\n"
f" - Look for id containing 'button_save' or 'ufi_save'. Do NOT pick the post text or other action buttons.\n"
f"10. DISTINGUISHING BOTTOM TABS vs CONTENT BUTTONS:\n"
f" - Bottom Navigation Tabs (Home, Search, Reels, Profile) are ALWAYS at the very bottom (y > 2100).\n"
f" - Content Interaction Buttons (Like, Comment, Share, Reactions, Message Input) are attached to posts or threads, NOT the bottom nav bar.\n"
f" - If looking for 'message input' or 'type message', do NOT select 'reactions' or emoji icons. Look for an empty text box or 'Message...'.\n"
f" - If looking for 'message input' or 'type message', do NOT select 'reactions' or emoji icons. Look for an empty text box or id 'message_content'.\n"
f"11. If the intent is 'feed post content' or 'post media content':\n"
f" - Pick the largest box that contains the actual image or video, usually described as 'Photo', 'Video', or 'Carousel'.\n"
f" - Pick the largest box that contains the actual image or video. Look for id 'zoomable_view_container' or 'media_frame'.\n"
f"12. If the exact control is NOT visible, return null. Do NOT guess.\n\n"
f'Reply ONLY with a valid JSON object: {{"box": <number>}} or {{"box": null}}'
)

42
GramAddict/core/perception/screen_identity.py
View File

@@ -205,6 +205,12 @@ class ScreenIdentity:
logger.info("🛡️ [ScreenIdentity] Critical obstacle detected → DANGER_ACTION_BLOCKED")
return ScreenType.DANGER_ACTION_BLOCKED
# Menu Trap Detection (O(1) fast-path)
# Overrides hallucinated LLM cache using STRICTLY STRUCTURAL IDs (no localized strings).
if "bottom_sheet_container" in ids and "action_sheet_row_text_view" in ids:
logger.info("🛡️ [ScreenIdentity] Options/Report menu trap detected → MODAL")
return ScreenType.MODAL
# Priority 2: Structural Heuristics (100% Deterministic)
if "unified_follow_list_tab_layout" in ids or "follow_list_container" in ids:
return ScreenType.FOLLOW_LIST
@@ -367,42 +373,30 @@ class ScreenIdentity:
if tab_id in resource_ids:
actions.append(action)
# Screen-specific actions
desc_lower = " ".join(content_descs).lower()
text_lower = " ".join(texts).lower()
# Screen-specific actions (Purely structural, NO localized strings)
ids_str = " ".join(resource_ids).lower()
if "like" in desc_lower:
if "button_like" in ids_str or "ufi_heart" in ids_str:
actions.append("tap like button")
if "comment" in desc_lower:
if "button_comment" in ids_str or "ufi_comment" in ids_str:
actions.append("tap comment button")
if "share" in desc_lower:
if "button_share" in ids_str or "ufi_share" in ids_str or "direct_share" in ids_str:
actions.append("tap share button")
if "save" in desc_lower or "bookmark" in desc_lower:
if "button_save" in ids_str or "ufi_save" in ids_str:
actions.append("tap save button")
if "back" in desc_lower:
if "back" in ids_str or "action_bar_button_back" in ids_str:
actions.append("tap back button")
has_following = any(
"following" in e.get("text", "").lower() or "following" in e.get("desc", "").lower()
for e in clickable_elements
)
has_following = "button_following" in ids_str or "profile_header_following" in ids_str
if has_following:
actions.append("tap following button")
elif any(
"follow" in e.get("text", "").lower()
or "follow" in e.get("desc", "").lower()
or "follow" in e.get("id", "").lower()
for e in clickable_elements
):
elif "button_follow" in ids_str:
actions.append("tap follow button")
if screen_type == ScreenType.OWN_PROFILE or screen_type == ScreenType.OTHER_PROFILE:
if "message" in desc_lower:
if "button_message" in ids_str or "direct_message" in ids_str:
actions.append("tap message button")
if (
"following" in desc_lower
or "following" in text_lower
or "profile_header_following" in " ".join(resource_ids).lower()
):
if "profile_header_following" in ids_str:
actions.append("tap following list")
# Grid items

11
GramAddict/core/situational_awareness.py
View File

@@ -8,6 +8,11 @@ and learns from every episode — positive AND negative.
After initial learning, 95%+ of situations are handled from memory
alone with ZERO LLM calls. This is "Tesla fleet learning" for bots.
CRITICAL ARCHITECTURE RULE: Language Agnosticism & Structural Determinism
NO hardcoded localized UI strings (e.g. "Report", "OK", "Deny") are permitted.
All structural heuristic fallbacks must use O(1) Android `resource-id` bounds
to ensure the bot functions flawlessly regardless of the device language.
"""
import hashlib
@@ -536,12 +541,12 @@ class SituationalAwarenessEngine:
"- If you see a dismiss/close/cancel/skip/not now button, click it\n"
"- If the Situation type is obstacle_locked_screen, action must be 'unlock'\n"
"- If the Situation type is obstacle_foreign_app, action must be 'kill_foreign_apps'\n"
"- If the Situation type is obstacle_system, you MUST look for 'Deny', 'Don't allow', or 'Cancel' and click it. \n"
" NEVER click 'Allow', 'OK', or 'Confirm' on system permissions.\n"
"- If the Situation type is obstacle_system, you MUST look for the negative action (e.g. deny, block, do not allow, cancel) and click it. \n"
" NEVER click the positive action (allow, accept, confirm) on system permissions.\n"
" If no negative action button exists, action must be 'back'\n"
"- If there is NO obstacle and the screen is a normal Instagram view (false positive), action must be 'false_positive'\n"
"- If nothing else works, suggest 'app_start' to force-reopen Instagram\n"
"- NEVER click 'OK'/'Confirm'/'Accept' on surveys or prompts\n"
"- NEVER click the positive/accept button on surveys or prompts\n"
"- When you choose to click, you MUST use the EXACT coordinates provided in `center=(x,y)` for that element in the XML\n"
'- Return ONLY valid JSON: {"action": "click"|"back"|"app_start"|"unlock"|"kill_foreign_apps"|"false_positive", "x": N, "y": N, "reason": "..."}'
)

5
GramAddict/core/telepathic_engine.py
View File

@@ -93,6 +93,7 @@ class TelepathicEngine:
if not any(k in intent_lower for k in typing_keywords):
logger.warning("⌨️ [TelepathicEngine] Keyboard detected during non-typing intent! Auto-dismissing.")
import time
device.back()
time.sleep(1.0)
# Re-fetch UI state
@@ -129,8 +130,8 @@ class TelepathicEngine:
(best_node.text or "") + " " + (best_node.content_desc or "") + " " + (best_node.resource_id or "")
)
semantic = semantic.lower()
# Zero-Maintenance: Only English UI states. resource_id never changes with locale.
if "following" in semantic or "requested" in semantic:
# Zero-Maintenance: Strictly structural IDs, no localized strings.
if "button_following" in semantic or "profile_header_following" in semantic:
return {"skip": True, "semantic": "already_followed"}
# 4. Track action

12
GramAddict/core/unfollow_engine.py
View File

@@ -127,19 +127,23 @@ def _run_zero_latency_unfollow_loop(
extra={"color": Fore.YELLOW},
)
# Find 'Following' button on their profile
# Find the button that indicates active subscription (Following)
following_nodes = telepathic._extract_semantic_nodes(
profile_xml, "find 'Following' button", threshold=0.7
profile_xml,
"find the button indicating active subscription, look for id 'button_following' or 'profile_header_following'",
threshold=0.7,
)
if following_nodes and not following_nodes[0].get("skip"):
f_node = following_nodes[0]
_humanized_click(device, f_node["x"], f_node["y"])
random_sleep(1.0, 2.0)
# Find 'Unfollow' confirm
# Find the confirmation button
confirm_xml = device.dump_hierarchy()
confirm_nodes = telepathic._extract_semantic_nodes(
confirm_xml, "find 'Unfollow' confirmation button", threshold=0.8
confirm_xml,
"find the confirmation button to stop following, look for id 'follow_sheet_unfollow_row' or red warning text",
threshold=0.8,
)
if confirm_nodes and not confirm_nodes[0].get("skip"):