Odyssey Agent v2.1

Welcome to the Odyssey Agent, a sophisticated, fully autonomous agent for X, designed for intelligent, strategic, and dynamic interaction. Powered by Google's Gemini API and controlled by a comprehensive Flask-based web UI, this agent transcends simple automation.

Version 2.1 introduces an intelligent fallback system, making the agent more proactive and resilient than ever before. It's an extensible platform for executing targeted content strategies, building a presence, and analyzing performance with professional-grade tools.

Core Philosophy

The Odyssey Agent is designed as a strategic entity. Its architecture is built around a "brain" (the Action Template system) and a "body" (the backend execution engine), all overseen by a web-based "Command Center" that gives you complete, real-time control over every aspect of its operation. After the initial setup, every setting is managed entirely within the UI.

Key Features

🚀 Command & Control UI

A professional, responsive interface designed for clarity and complete control.

• Professional Dashboard: A modern layout presenting key performance indicators (KPIs), follower growth charts, and live activity/log feeds.
• Real-Time Bot Control: Start, pause, and stop the agent, or force it to start the next cycle immediately, with a live status indicator.
• Complete Live Configuration: Absolutely every setting is controllable via the UI.
  • API Plan Awareness: Select your X API plan ('Free' or 'Basic'). The agent automatically adapts its behavior to avoid rate-limit loops.
  • X Account Management: Add, edit, and delete multiple X accounts directly from the interface.
  • Persona Management: A dedicated page with a JSON editor to define all available AI personas.
  • Full Strategy Control: A dedicated page to fine-tune action weights, timing cooldowns, and ideal follower profiles.
• Campaign Management: A full CRUD interface for creating "Action Templates"—the core of the agent's content strategies.
• System Management: Provides options for both a full configuration export (including all secrets) for complete backups, and a "Strategy-Only" export that excludes sensitive keys, perfect for sharing.

🧠 Intelligent Engine (v2.1)

• Intelligent Fallback System: If no specific, keyword-matched opportunity is found, the agent doesn't go idle. It proactively seeks a general, high-engagement conversation to interact with, using a dedicated "Generic Engagement" template. This ensures constant activity and presence.
• Adaptive Logic: The agent's core scheduler is "plan-aware", changing its behavior based on the selected API tier to maximize uptime and performance.
• Diverse Actions: Beyond content creation, the agent can perform proactive growth actions like the "Like & Follow Wave", which targets users based on keywords in their bio.
• Action Template System: A powerful system for defining specific campaigns (Action Templates) that trigger based on keywords in live conversations.
• AI-Powered Content Generation: Utilizes Google's Gemini API to formulate natural, value-driven replies, quotes, and threads.

Setup & Installation

1. Clone the repository.
2. Create and activate a virtual environment.
3. Install dependencies: pip install -r requirements.txt.
4. Configure Initial Secrets:
   • Copy config.py.example to config.py.
   • Edit config.py and fill in your initial UI_USERS, FLASK_SECRET_KEY, at least one set of X_ACCOUNTS, and your GEMINI_API_KEY.
5. Initialize the Database & Agent:
   • Run flask --app ui.app init-db once to create the database and import initial settings.
   • Run flask --app ui.app init-users once to create your UI login accounts.
6. Crucial Final Setup:
   • Start the UI with flask --app ui.app run.
   • Go to Settings -> General and select your current X API Plan.
   • Go to Campaigns -> Action Templates and create the special "Generic Crypto Engagement" template as described in the project documentation. This is essential for the v2.1 fallback logic to work.

How to Run

1. Start the UI Command Center:

   flask --app ui.app run

   Access the UI in your browser (e.g., http://127.0.0.1:8080).

2. Start the Backend Agent:

   • Open a second terminal.
   • Activate the same virtual environment.
   • Start the agent:

     python main.py

   • The agent will start in a "paused" state.

3. Activate the Agent:

   • Go back to the UI dashboard.
   • Use the tactical controls to change the bot's status from "Paused" to "Running".

Disclaimer

This is a powerful automation tool. Use it responsibly, ethically, and at your own risk. Automating social media accounts can be against platform Terms of Service.