v1.4.0: Unified Agent Architecture

- Add unified agent mode (enabled by default)
- Reorganize tools into shared/legacy/unified folders
- Add step-by-step LLM reactions to autopost and mentions
- Add actions table for unified tracking
- New tools: get_twitter_profile, get_conversation_history
- New endpoint: POST /trigger-agent
- Tier-based daily limits (Free: 15/0, Basic: 50/50, Pro: 500/500)

Author: pippinlovesdot

.env.example

@@ -16,3 +16,7 @@ DATABASE_URL=postgresql://user:pass@host:5432/dbname
 POST_INTERVAL_MINUTES=30
 MENTIONS_INTERVAL_MINUTES=20
 ENABLE_IMAGE_GENERATION=true
+
+# Unified Agent mode (v1.4.0)
+USE_UNIFIED_AGENT=true
+AGENT_INTERVAL_MINUTES=30

ARCHITECTURE.md

@@ -41,6 +41,7 @@ config/
     instructions.py         # Communication style
   prompts/                  # LLM prompts
     agent_autopost.py       # Agent planning prompt
+    unified_agent.py        # Unified agent instructions (v1.4)
     mention_selector.py     # Mention handling prompt
 utils/
   __init__.py
@@ -49,15 +50,28 @@ services/
   __init__.py
   autopost.py               # Autoposting service (uses LLMClient)
   mentions.py               # Mention handling service
+  unified_agent.py          # Unified agent service (v1.4)
   tier_manager.py           # Twitter API tier detection and limits
   llm.py                    # LLM client (generate, generate_structured, chat)
   twitter.py                # Twitter API client
   database.py               # Database operations + metrics
 tools/
   __init__.py
-  registry.py               # Tool registry for function calling
-  web_search.py             # Web search via OpenRouter plugins
-  image_generation.py       # Image generation tool
+  registry.py               # Tool registry with auto-discovery
+  shared/                   # Tools for both legacy and unified modes
+    __init__.py
+    web_search.py           # Web search via OpenRouter
+    get_twitter_profile.py  # Get user profile info
+    get_conversation_history.py  # Get chat history with user
+  legacy/                   # Tools for legacy mode only
+    __init__.py
+    image_generation.py     # Image generation with references
+  unified/                  # Tools for unified agent only
+    __init__.py
+    create_post.py          # Create post with optional image
+    create_reply.py         # Reply to mention
+    get_mentions.py         # Fetch unread mentions
+    finish_cycle.py         # End agent cycle
 assets/                     # Reference images for generation
 .env.example                # Environment template
 requirements.txt            # Python dependencies
@@ -262,6 +276,53 @@ The agent operates in a continuous conversation, creating a plan and executing t
 - Tracks which tools were used for analytics
 - Plan validation (v1.3.2): max 3 tools, generate_image must be last
 
+### services/unified_agent.py (v1.4.0)
+`UnifiedAgent` class — new architecture that replaces separate autopost + mentions.
+
+**Key Features:**
+- Single agent that handles both posting and replying
+- Uses Structured Output (JSON Schema) for tool selection
+- Step-by-step execution with LLM deciding after each tool
+- Dynamic tool discovery from registry
+
+**Flow:**
+1. Load context (recent actions, rate limits, tier info)
+2. Build system prompt with available tools
+3. Loop (max 10 iterations):
+   a. LLM decides which tool to use via Structured Output
+   b. Execute tool (get_mentions, create_post, create_reply, etc.)
+   c. Add result to conversation
+   d. Repeat until LLM calls `finish_cycle`
+
+**Tool Decision Schema:**
+```json
+{
+  "thinking": "Reasoning about what to do next",
+  "tool": "get_mentions",
+  "params": {"limit": 10}
+}
+```
+
+**Available tools in unified mode:**
+- `get_mentions` — fetch unread Twitter mentions
+- `create_post` — post with optional image
+- `create_reply` — reply to mention with optional image
+- `web_search` — search the web
+- `get_twitter_profile` — get user profile info
+- `get_conversation_history` — get chat history with user
+- `finish_cycle` — end the agent cycle
+
+**Design decisions:**
+- Tools are auto-discovered from `tools/shared/` and `tools/unified/`
+- Each tool has a `TOOL_CONFIG` with name, description, params
+- Description is pulled into prompts automatically via registry
+- Tier-based filtering: some tools only available on Basic+ tier
+- Actions table tracks all posts and replies in one place
+
+**Mode switching:**
+- `USE_UNIFIED_AGENT=true` in env enables this mode
+- `USE_UNIFIED_AGENT=false` uses legacy autopost + mentions
+
 ### services/llm.py
 `LLMClient` class — async client for OpenRouter API.
 
@@ -345,49 +406,59 @@ TIER_FEATURES = {
 - `MentionHandler.process_mentions_batch()` calls `tier_manager.can_use_mentions()` before processing
 - Both services receive `tier_manager` instance via constructor
 
-### tools/registry.py
-Tool registry with **auto-discovery** (v1.3).
+### tools/registry.py (v1.4.0)
+Tool registry with **folder-based auto-discovery**.
 
 **How it works:**
-- Uses `pkgutil.iter_modules()` to scan all Python files in `tools/` directory
-- Each tool file that exports `TOOL_SCHEMA` is automatically registered
-- Tool function must have the same name as `schema["function"]["name"]`
+- Scans three folders: `shared/`, `legacy/`, `unified/`
+- Each tool file exports `TOOL_CONFIG` dict with name, description, params
+- Tool function must have the same name as `TOOL_CONFIG["name"]`
+- Mode-aware: different tools available for legacy vs unified modes
+
+**Folder structure:**
+- `tools/shared/` — available in both legacy and unified modes
+- `tools/legacy/` — only available in legacy mode (autopost.py, mentions.py)
+- `tools/unified/` — only available in unified agent mode
 
 **Exports:**
-- `TOOLS` — dict mapping tool names to async functions (auto-populated)
-- `TOOLS_SCHEMA` — list of JSON schemas in OpenAI function calling format (auto-populated)
-- `get_tools_description()` — generates human-readable tool descriptions for agent prompts
+- `ALL_TOOLS` — dict of all discovered tools
+- `TOOLS` — legacy compatibility dict for autopost.py
+- `get_tools_for_mode(mode, tier)` — get tools filtered by mode and tier
+- `get_tools_description_for_mode(mode, tier)` — human-readable tool descriptions
+- `get_tools_enum_for_mode(mode, tier)` — list of tool names for JSON schema
+- `get_tool_func(name)` — get tool function by name
 - `refresh_tools()` — re-scan tools at runtime
 
-**Available tools:**
-- `web_search` — real-time web search via OpenRouter plugins
-- `generate_image` — image generation using Gemini 3 Pro
+**Available tools by folder:**
+- **shared/**: `web_search`, `get_twitter_profile`, `get_conversation_history`
+- **legacy/**: `generate_image`
+- **unified/**: `create_post`, `create_reply`, `get_mentions`, `finish_cycle`
 
-**To add a new tool (zero registry changes needed):**
-1. Create `tools/my_tool.py`
-2. Add `TOOL_SCHEMA` constant with OpenAI function calling format
+**To add a new tool:**
+1. Create file in appropriate folder (e.g., `tools/shared/my_tool.py`)
+2. Add `TOOL_CONFIG` dict with name, description, params
 3. Create async function with matching name
 4. Done! Tool is auto-discovered on startup
 
 Example:
 ```python
-# tools/my_tool.py
-TOOL_SCHEMA = {
-    "type": "function",
-    "function": {
-        "name": "my_tool",
-        "description": "What this tool does",
-        "parameters": {
-            "type": "object",
-            "properties": {"query": {"type": "string", "description": "..."}},
-            "required": ["query"]
+# tools/shared/my_tool.py
+TOOL_CONFIG = {
+    "name": "my_tool",
+    "description": "What this tool does - used in prompts",
+    "params": {
+        "query": {
+            "type": "string",
+            "description": "Parameter description",
+            "required": True
         }
-    }
+    },
+    "tier": "all"  # or "basic+" for restricted
 }
 
-async def my_tool(query: str) -> dict:
-    # Implementation
-    return {"result": "..."}
+async def my_tool(query: str, **kwargs) -> str:
+    # kwargs contains: twitter, db, tier_manager
+    return "Result string"
 ```
 
 ### tools/web_search.py

README.md

@@ -113,7 +113,10 @@ Each layer feeds into the next. Your agent behaves consistently across thousands
 
 ## Architecture
 
-The system operates on **two autonomous agent triggers**:
+The system supports **two modes** of operation:
+
+### Legacy Mode (Default)
+Two separate autonomous agents running on different schedules:
 
 | Scheduled Posts (Agent) | Mention Responses (Agent) |
 |-------------------------|---------------------------|
@@ -122,11 +125,19 @@ The system operates on **two autonomous agent triggers**:
 | Dynamic tool usage (web search, image generation) | 3 LLM calls per mention (select → plan → reply) |
 | Posts to Twitter with optional media | Tracks tools used per reply |
 
-**Agent Architecture:** Both systems use autonomous agents that decide which tools to use based on context. The mention agent can process multiple mentions per batch, creating individual plans for each selected mention.
+### Unified Agent Mode (v1.4.0)
+A single agent that handles both posting and replying in one cycle:
+
+| Feature | Description |
+|---------|-------------|
+| Single cycle | Agent decides what to do (post, reply, or both) |
+| Tool-based actions | Uses tools like `get_mentions`, `create_post`, `create_reply` |
+| Step-by-step | LLM decides after each tool execution |
+| Rate limiting | Self-imposed daily limits for posts and replies |
 
-**Auto-Discovery Tools:** Tools are automatically discovered from the `tools/` directory. Add a new tool file with `TOOL_SCHEMA` and it's available to agents without any registry changes.
+**Enable with:** `USE_UNIFIED_AGENT=true` in environment variables.
 
-This separation keeps the codebase simple while enabling both proactive and reactive behavior.
+**Auto-Discovery Tools:** Tools are organized into folders (`shared/`, `legacy/`, `unified/`) and automatically discovered on startup. Each tool has a `TOOL_CONFIG` with description that's injected into prompts.
 
 ---
 
@@ -142,7 +153,7 @@ This separation keeps the codebase simple while enabling both proactive and reac
 
 🎨 **Image Generation** — Creates visuals matching agent's style and current context. Supports multiple providers.
 
-🔧 **Extensible Tools** — Plug in web search, external APIs, blockchain data, custom integrations. The tool system is designed for expansion.
+🔧 **Extensible Tools** — Plug in web search, profile lookup, conversation history, and more. Add custom tools to the appropriate folder and they're auto-discovered.
 
 📦 **Production-Ready** — Clean async Python with type hints. Add API keys and deploy — no additional setup required.
 
@@ -226,7 +237,7 @@ my-agent/
 │   │   └── instructions.py  # Communication style
 │   └── prompts/             # LLM prompts (modular)
 │       ├── agent_autopost.py         # Agent planning prompt
-│       ├── mention_selector.py       # Legacy mention selector (v1.2)
+│       ├── unified_agent.py          # Unified agent instructions (v1.4)
 │       ├── mention_selector_agent.py # Agent mention selection (v1.3)
 │       └── mention_reply_agent.py    # Agent reply planning (v1.3)
 │
@@ -236,15 +247,25 @@ my-agent/
 ├── services/
 │   ├── autopost.py          # Agent-based scheduled posting
 │   ├── mentions.py          # Mention/reply handler
+│   ├── unified_agent.py     # Unified agent (v1.4)
 │   ├── tier_manager.py      # Twitter API tier detection
 │   ├── llm.py               # OpenRouter client (generate, chat)
 │   ├── twitter.py           # Twitter API v2 integration
 │   └── database.py          # PostgreSQL for history + metrics
 │
 ├── tools/
-│   ├── registry.py          # Auto-discovery tool registry
-│   ├── web_search.py        # Web search via OpenRouter plugins
-│   └── image_generation.py  # Image generation with reference images
+│   ├── registry.py          # Auto-discovery from subfolders
+│   ├── shared/              # Tools for both modes
+│   │   ├── web_search.py    # Web search via OpenRouter
+│   │   ├── get_twitter_profile.py    # Get user profile info
+│   │   └── get_conversation_history.py # Chat history with user
+│   ├── legacy/              # Legacy mode only
+│   │   └── image_generation.py  # Image gen with references
+│   └── unified/             # Unified agent only
+│       ├── create_post.py   # Post with optional image
+│       ├── create_reply.py  # Reply to mention
+│       ├── get_mentions.py  # Fetch unread mentions
+│       └── finish_cycle.py  # End agent cycle
 │
 ├── main.py                  # FastAPI + APScheduler entry point
 ├── requirements.txt         # Dependencies
@@ -296,6 +317,33 @@ Agent thinks: "I want to post about crypto trends with a visual"
 - `POST_INTERVAL_MINUTES` — Time between auto-posts (default: 30)
 - `ENABLE_IMAGE_GENERATION` — Set to `false` to disable all image generation
 
+### Unified Agent (`services/unified_agent.py`) — v1.4.0
+
+A single agent that handles both posting and replying in one cycle.
+
+**How it works:**
+1. Agent loads context (recent actions, rate limits, tier info)
+2. Agent decides what to do using available tools
+3. Loop until `finish_cycle` is called:
+   - LLM decides next action via Structured Output
+   - Execute tool (get_mentions, create_post, create_reply, etc.)
+   - Add result to conversation
+4. Repeat next cycle after configured interval
+
+**Available tools:**
+- `get_mentions` — fetch unread Twitter mentions
+- `create_post` — post with optional image
+- `create_reply` — reply to mention with optional image
+- `web_search` — search the web for current info
+- `get_twitter_profile` — get user profile info
+- `get_conversation_history` — get chat history with user
+- `finish_cycle` — end the current cycle
+
+**Configuration:**
+- `USE_UNIFIED_AGENT` — Set to `true` to enable (default: true)
+- `AGENT_INTERVAL_MINUTES` — Time between agent cycles (default: 30)
+- Daily limits are tier-based (Free: 15/0, Basic: 50/50, Pro: 500/500)
+
 ### Mention Handler (`services/mentions.py`)
 
 Agent-based mention processing with 3 LLM calls per mention (v1.3).

config/prompts/unified_agent.py

@@ -0,0 +1,36 @@
+"""
+Unified Agent Prompt - Instructions for the autonomous agent.
+
+This prompt tells the agent how to use its tools and make decisions.
+Combined with SYSTEM_PROMPT (personality) to form full system message.
+"""
+
+AGENT_INSTRUCTIONS = """
+## HOW YOU WORK
+
+You are an autonomous agent that runs periodically. Each cycle, you:
+1. See your recent actions (posts and replies)
+2. See your rate limits
+3. Decide what to do using your tools
+4. Call finish_cycle when done
+
+## DECISION MAKING
+
+- Check mentions first with get_mentions
+- Reply to interesting mentions using create_reply
+- Create original posts when you have something to say
+- Use web_search to find current information
+- Use get_twitter_profile and get_conversation_history for context
+
+## POST QUALITY
+
+- Keep posts/replies under 280 characters
+- Be authentic to your personality
+- Use include_image=true when visual would enhance the message
+
+## RULES
+
+1. Respect rate limits shown in context
+2. finish_cycle is required - always call it when done
+3. Handle tool errors gracefully
+"""

config/schemas.py

@@ -220,3 +220,25 @@
         }
     }
 }
+
+# ==================== v1.4.0 Schemas ====================
+
+# Schema for agent reaction after tool execution (step-by-step)
+TOOL_REACTION_SCHEMA = {
+    "type": "json_schema",
+    "json_schema": {
+        "name": "tool_reaction",
+        "strict": True,
+        "schema": {
+            "type": "object",
+            "properties": {
+                "thinking": {
+                    "type": "string",
+                    "description": "Your thoughts about the tool result - what did you learn? how will this inform your post?"
+                }
+            },
+            "required": ["thinking"],
+            "additionalProperties": False
+        }
+    }
+}

config/settings.py

@@ -34,6 +34,10 @@ class Settings(BaseSettings):
     mentions_interval_minutes: int = 20
     enable_image_generation: bool = True
 
+    # Unified Agent (new architecture)
+    use_unified_agent: bool = True
+    agent_interval_minutes: int = 30
+
 
 # Global settings instance
 settings = Settings()