33 lines
2.8 KiB
Markdown
33 lines
2.8 KiB
Markdown
# GramPilot Architecture
|
|
|
|
Welcome to the internal workings of **GramPilot** (formerly GramAddict). This document outlines the radical shift from fixed-state deterministic scripting to our current **Vision-Language-Action (VLA)** architecture that powers our "Full Self-Driving" behavior.
|
|
|
|
## Core Design Philosophy
|
|
We treat the Instagram Android App like a dynamic, partially-observable environment. Instead of maintaining thousands of fragile XPaths, the bot relies on a **Cognitive Stack** to infer intent, learn layouts dynamically, and mathematically avoid detection.
|
|
|
|
---
|
|
|
|
## 1. The Telepathic Engine (3-Stage Resolution Cascade)
|
|
At the center of UI interactions is the `TelepathicEngine` which resolves semantic intent ("tap the like button") into precise screen coordinates via a strictly enforced performance cascade:
|
|
- **Stage 1.5: Deterministic Keyword Fast Path**. Over 90% of interactions are handled by a high-performance string matcher that costs 0 API tokens and executes in `<2ms`.
|
|
- **Stage 2: Vector Similarity Engine**. If keywords fail, an Ollama Semantic Embedding of the intent is generated and compared (Cosine Similarity) against cached UI vectors via Qdrant. Highly reliable for semantic synonyms.
|
|
- **Stage 3: Agentic Fallback**. The ultimate safety net. If visual confidence drops `<0.82`, it falls back to an OpenRouter LLM (e.g., `gemini-3.1-flash-lite-preview`) which parses the raw XML to structurally guarantee a hit without hallucination.
|
|
|
|
## 2. Telepathic Memory & Autonomy
|
|
When Stage 3 successfully resolves an unknown interaction, the bot records the semantic signature into its positive memory (`telepathic_memory.json`). The next time the bot requires this action, it is instantly resolved via the local cache, guaranteeing that expensive LLM operations are only ever performed once per UI permutation.
|
|
|
|
## 3. The Cognitive Stack
|
|
|
|
### ⚖️ Active Inference (Shadow Mode)
|
|
Found in `active_inference.py`. Based on the free-energy principle, the bot calculates "Surprise" (prediction errors).
|
|
- **Shadow Mode**: Before transitioning screens, the bot predicts the target UI. If it lands somewhere unexpected (a popup), it registers a prediction error, hits "Back", and averts a crash.
|
|
|
|
### 🛡️ Honeypot Radome
|
|
Found in `sensors/honeypot_radome.py`.
|
|
- Instagram deploys 1x1 pixel invisible traps to detect bots. The Radome parses the raw XML and topologically removes any nodes with `bounds="[0,0][0,0]"` *before* the bot's navigation engine evaluates it.
|
|
|
|
### 💉 Dopamine Engine & Resonance Oracle
|
|
Instead of hardcoding limits like `max_likes = 50`, the bot stops interacting based on **simulated boredom**.
|
|
- The `ResonanceEngine` calculates the aesthetic score of content.
|
|
- The `DopamineEngine` uses this score to modulate pace. High resonance = engagement. Low resonance over multiple posts = early session termination (simulating human fatigue).
|