instagram-bot/CONTRIBUTING.md

Contributing to GramPilot

:+1:🎉 First off, thanks for taking the time to contribute! 🎉👍

The following is a set of guidelines for contributing to GramPilot. GramPilot has evolved significantly from its original roots into an AI-driven, autonomous Vision-Language-Action (VLA) agent.

Please follow these guidelines when submitting issues or pull requests.

Table Of Contents

• How Can I Contribute?
  • Reporting Bugs
  • Suggesting Enhancements
  • Pull Requests
• Development Paradigms
• Styleguides

---

How Can I Contribute?

Reporting Bugs

Before filing an issue, please ensure the bug relates to GramPilot's core framework (e.g. Qdrant cache issues, VLA compilation timeouts, Active Inference crashes). Because GramPilot synthesizes its own UI Locators using VLMs, do not open bugs about outdated Instagram UI Locators. The bot heals itself using the Dojo Engine automatically.

When filing an issue, please provide:

• The exact device or emulator and Instagram version.
• The error trace from logs/marisaundmarc.log containing the emojis (e.g. ⛩️ Dojo Engine traces or ⚖️ Active Inference states).
• Do not submit tickets without terminal output logs.

Suggesting Enhancements

We welcome architectural enhancements to the Cognitive Stack. If you want to contribute, focus on logic that makes the bot more human or resilient:

• Adding new sensors (like the Honeypot Radome) to evade IG protections.
• Expanding DopamineEngine parameters for better pacing.
• Enhancing the VLM Prompts in compiler_engine.py for more robust heuristics.

Pull Requests

1. All changes must be tested locally.
2. If you add a new Cognitive Engine, it must be properly integrated into the bot_flow.py loop without relying on hardcoded delays sleep(5). Use the thermodynamic delays derived from ActiveInference.
3. Do not re-introduce config.yml dependencies for deterministic actions (e.g. max_likes). We rely strictly on biological simulation.

---

Development Paradigms

1. NO HARDCODED XPATHS: Do not PR changes that look like device.xpath('//android.widget.Button...'). Use the semantic intents via _execute_transition.
2. NO HARDCODED PIXELS: Never use hardcoded pixel coordinates for scrolling or swiping (e.g. scroll(1000)). Screens vary drastically in pixel density. Always use human-scale dimensions (cm) via device.cm_to_pixels(4.5) to ensure deterministic physical interaction scaling.
3. ASYNCHRONOUS AUTO-LABELING: Blocking network calls during UI automation cause timing errors. Ensure heavy computation (VLM generation) happens in background threads (e.g., dojo_engine.py).
4. FAIL GRACEFULLY: Instead of wrapping UI lookups in try/except and crashing, utilize the Shadow Mode (predict_state) so the agent can naturally press "Back" if confused.

---

Styleguides

All Python code must be formatted with Black. Follow standard Git commit messages.