Add AD_AUTONOMY_BLUEPRINT.md - Phase 6 First Mission: Autonomous Meta Ads System

AD_AUTONOMY_BLUEPRINT.md

@@ -0,0 +1,240 @@
+# AD AUTONOMY BLUEPRINT
+## APEX OS Autonomous Advertising System
+
+### Prepared by: APEX OS Team
+- Research Analyst (Employee 4) - Market Research & API Analysis  
+- Marketing Strategist (Employee 5) - Strategy & Creative Framework
+- Engineer (Employee 1) - Technical Feasibility Review
+
+---
+
+## 1. EXECUTIVE SUMMARY
+
+This blueprint outlines how APEX OS can autonomously create, manage, and optimize advertising campaigns on Meta (Facebook/Instagram) using the Marketing API. The system leverages the existing APEX infrastructure (LiteLLM for AI, n8n for orchestration, Gitea for version control) to build a fully automated ad management pipeline.
+
+---
+
+## 2. META ADS API ANALYSIS (Research Analyst Findings)
+
+### 2.1 Current Capabilities
+- **Campaign Management API**: Full CRUD operations for campaigns, ad sets, and ads
+- **Creative API**: Upload and manage ad creatives (images, videos, carousels)
+- **Targeting API**: Detailed audience targeting (demographics, interests, behaviors, custom audiences)
+- **Insights API**: Real-time performance metrics and reporting
+- **Conversions API**: Server-side event tracking for optimization
+
+### 2.2 Authentication Requirements
+- **Meta Business Manager** account (mandatory)
+- **System User Access Token** (long-lived, recommended for automation)
+- **App Review** required for certain permissions (ads_management, ads_read)
+- **Business Verification** required for production access
+- **Required Permissions**: ads_management, ads_read, business_management, pages_read_engagement
+
+### 2.3 Rate Limits
+- **Standard**: 200 calls/hour per ad account (Business Use Case rate)
+- **Batch API**: Up to 50 requests per batch call
+- **Insights**: Rate limited separately, async reports recommended for large datasets
+- **Best Practice**: Implement exponential backoff and request queuing
+
+### 2.4 Compliance Requirements
+- All ads must comply with Meta Advertising Policies
+- Special Ad Categories (housing, employment, credit) have additional restrictions
+- Ad review process (automated + manual) before going live
+- Data privacy compliance (GDPR, CCPA) for audience data
+- Political/social issue ads require disclaimers
+
+### 2.5 Available Ad Formats
+- Single Image/Video ads
+- Carousel ads (up to 10 cards)
+- Collection ads (Instant Experience)
+- Stories ads (full-screen vertical)
+- Reels ads
+- Lead Generation ads (with instant forms)
+
+### 2.6 Recent Changes (2024-2025)
+- Graph API v18.0+ required (older versions deprecated)
+- Enhanced conversion tracking (server-side recommended)
+- AI-powered Advantage+ campaigns (automated targeting)
+- Restrictions on detailed targeting for sensitive categories
+- New creative format requirements for Reels and Stories
+
+---
+
+## 3. AUTONOMOUS AD WORKFLOW (Marketing Strategist Blueprint)
+
+### 3.1 System Architecture
+
+```
+CEO Brief -> n8n Webhook
+  |
+Research Analyst -> Market Analysis + Competitor Audit
+  |
+Marketing Strategist -> Ad Copy (3 variants) + Creative Brief
+  |  
+Engineer -> Technical Validation
+  |
+Meta Ads API -> Campaign Creation
+  |
+Performance Monitor -> Optimization Loop
+  |
+CEO Dashboard -> Results & Recommendations
+```
+
+### 3.2 Workflow Steps
+
+**Phase 1: Campaign Brief Intake**
+- CEO submits product/topic via Telegram or webhook
+- System logs brief in apex.tasks table
+- Research Analyst receives assignment automatically
+
+**Phase 2: Research & Intelligence**
+- Analyst queries mem0 for existing research
+- Performs web research: competitor ads, market trends, audience data
+- Compiles research report -> saves to Gitea + mem0
+- Identifies top-performing ad patterns in the niche
+
+**Phase 3: Creative Strategy**
+- Strategist reads research from mem0
+- Generates 3 ad variations per format:
+  - **Variation A**: Pain Point Hook (addresses problem directly)
+  - **Variation B**: Curiosity Hook (creates intrigue)
+  - **Variation C**: Social Proof Hook (leverages results/testimonials)
+- Each variation includes: Hook, Body, CTA, Target Audience spec
+- Creative brief for visual assets (image dimensions, style notes)
+
+**Phase 4: Asset Creation**
+- LiteLLM generates ad images via DALL-E/Stable Diffusion
+- Copy variants formatted for each placement (Feed, Stories, Reels)
+- A/B test matrix created (3 copy x 2 images = 6 combinations)
+
+**Phase 5: Campaign Deployment**
+- n8n workflow creates Meta campaign structure:
+  - Campaign -> Ad Set (targeting) -> Ads (creative variants)
+- Budget allocation: Equal split across variants initially
+- Targeting: Based on Analyst audience research
+- Scheduling: Immediate or scheduled launch
+
+**Phase 6: Optimization Loop**
+- Every 4 hours: Pull Insights API for performance data
+- AI analyzes: CTR, CPC, CPM, ROAS across variants
+- Auto-pause underperforming ads (CTR < threshold)
+- Reallocate budget to top performers
+- Generate optimization report -> CEO Telegram
+
+### 3.3 Ad Copy Framework
+
+**Template Structure:**
+```
+HOOK: [Attention-grabbing first line - max 40 characters]
+BODY: [Value proposition - 2-3 sentences addressing pain point and solution]
+CTA: [Clear action instruction with urgency element]
+TARGET: [Primary demographic, interests, behaviors]
+PLACEMENT: [Feed / Stories / Reels / All]
+```
+
+---
+
+## 4. TECHNICAL ARCHITECTURE (Engineer Assessment)
+
+### 4.1 Required New Components
+
+| Component | Purpose | Container | Priority |
+|-----------|---------|-----------|----------|
+| Meta Ads Service | API integration | Node.js/Express | HIGH |
+| Creative Generator | Image creation | Python/Pillow + LiteLLM | HIGH |
+| Performance Monitor | Insights polling | Python cron job | MEDIUM |
+| Budget Optimizer | Spend allocation | Python/n8n | MEDIUM |
+
+### 4.2 Implementation with Current Stack
+
+**Feasible with current infrastructure:**
+- n8n for workflow orchestration (already operational)
+- LiteLLM for AI-powered copy generation (operational)
+- Gitea for version control of campaigns (operational)
+- PostgreSQL for campaign data storage (operational)
+- Grafana for performance dashboards (operational)
+
+**Required additions:**
+- Meta Ads API service container (Node.js)
+- Creative asset generation pipeline (LiteLLM + image tools)
+- Vaultwarden entry for Meta API credentials (security)
+- Rate limiter middleware (Redis-based, Redis already available)
+
+### 4.3 Security Considerations
+- Meta System User Token stored in Vaultwarden (encrypted)
+- API calls routed through dedicated service container (not direct from n8n)
+- Spending limits enforced at both Meta level AND application level
+- All API credentials rotated every 60 days
+- Audit trail: every API call logged to apex.engineer_decisions
+
+### 4.4 Estimated Complexity
+- **Meta Ads Service Container**: 2-3 days (API wrapper + error handling)
+- **Creative Pipeline**: 1-2 days (LiteLLM image generation + formatting)
+- **n8n Campaign Workflow**: 1 day (orchestration logic)
+- **Performance Monitor**: 1 day (Insights API polling + dashboard)
+- **Total Estimated**: 5-7 working days for MVP
+
+### 4.5 Safety Guardrails
+
+| Guardrail | Implementation | Trigger |
+|-----------|---------------|---------|
+| Daily Spend Cap | Application-level check before API call | Budget > $X/day |
+| Content Review | CEO approval via Telegram before launch | All new campaigns |
+| Compliance Check | LiteLLM pre-screen for policy violations | Before ad submission |
+| Emergency Stop | n8n workflow to pause all campaigns | Manual trigger or anomaly |
+| Performance Floor | Auto-pause ads below minimum CTR | CTR < 0.5% after 1000 impressions |
+
+---
+
+## 5. IMPLEMENTATION ROADMAP
+
+### Phase A: Foundation (Week 1)
+1. Create Meta Business Manager account and System User
+2. Deploy Meta Ads API service container
+3. Store credentials in Vaultwarden
+4. Build basic campaign creation n8n workflow
+
+### Phase B: Intelligence (Week 2)  
+1. Connect Research Analyst to web scraping tools
+2. Build competitor ad analysis pipeline
+3. Implement mem0 research storage and retrieval
+4. Create audience targeting templates
+
+### Phase C: Creative (Week 3)
+1. Build creative asset generation pipeline
+2. Implement ad copy A/B testing framework
+3. Create performance monitoring dashboard in Grafana
+4. Build optimization loop (budget reallocation)
+
+### Phase D: Autonomy (Week 4)
+1. End-to-end testing with test campaigns
+2. CEO approval workflow via Telegram
+3. Emergency stop procedures
+4. Documentation and training
+
+---
+
+## 6. RISK ASSESSMENT
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| Meta API changes | Medium | High | Version pinning + monitoring |
+| Ad account suspension | Low | Critical | Compliance checks + spending limits |
+| Budget overspend | Low | High | Multi-layer caps (app + Meta level) |
+| Creative quality | Medium | Medium | CEO review before launch |
+| Rate limiting | Medium | Low | Request queuing + exponential backoff |
+
+---
+
+## 7. CONCLUSION
+
+APEX OS has the infrastructure foundation to support autonomous advertising. The current stack (n8n, LiteLLM, PostgreSQL, Grafana) provides 70% of the required components. The primary additions needed are a Meta Ads API service container and a creative asset pipeline. With the Employee Factory already operational, specialized agents can be created to handle each phase of the advertising lifecycle.
+
+**Recommendation**: Proceed with Phase A (Foundation) after CEO provides Meta Business Manager credentials.
+
+---
+
+*Blueprint Version: 1.0*  
+*Created by: APEX OS Research & Marketing Team*  
+*Reviewed by: Engineer (Employee 1)*  
+*Status: Ready for CEO Approval*