ALwrity Facebook Writer CopilotKit Implementation Plan

2025-08-31 18:41:07 +05:30
parent 66c14e158c
commit eb0789321d
11 changed files with 2116 additions and 206 deletions
--- a/docs/FACEBOOK_WRITER_MIGRATION_SUMMARY.md
+++ b/docs/FACEBOOK_WRITER_MIGRATION_SUMMARY.md
@@ -0,0 +1,209 @@
+# Facebook Writer Migration Summary
+
+## 🎯 Objective Completed
+Successfully migrated the Facebook Writer from the `ToBeMigrated` Streamlit application to a fully functional FastAPI backend, ready for React frontend integration.
+
+## 📊 Migration Statistics
+
+### ✅ Components Migrated
+- **Main Application**: `facebook_ai_writer.py` (359 lines) → FastAPI router
+- **10 Modules**: All Facebook writer modules converted to services
+- **11 Endpoints**: Complete REST API with health checks and utility endpoints
+- **Pydantic Models**: 40+ strongly-typed request/response models
+- **AI Integration**: Seamless integration with existing Gemini provider
+
+### 🏗️ New Architecture
+
+#### Directory Structure Created
+```
+backend/api/facebook_writer/
+├── models/
+│   ├── __init__.py
+│   ├── post_models.py
+│   ├── story_models.py
+│   ├── reel_models.py
+│   ├── carousel_models.py
+│   ├── event_models.py
+│   ├── hashtag_models.py
+│   ├── engagement_models.py
+│   ├── group_post_models.py
+│   ├── page_about_models.py
+│   └── ad_copy_models.py
+├── services/
+│   ├── __init__.py
+│   ├── base_service.py
+│   ├── post_service.py
+│   ├── story_service.py
+│   ├── ad_copy_service.py
+│   └── remaining_services.py
+└── routers/
+    ├── __init__.py
+    └── facebook_router.py
+```
+
+## 🔧 Technical Implementation
+
+### API Endpoints Created
+| Endpoint | Method | Purpose | Status |
+|----------|--------|---------|--------|
+| `/api/facebook-writer/health` | GET | Health check | ✅ Tested |
+| `/api/facebook-writer/tools` | GET | List available tools | ✅ Tested |
+| `/api/facebook-writer/post/generate` | POST | Generate Facebook post | ✅ Tested |
+| `/api/facebook-writer/story/generate` | POST | Generate Facebook story | ✅ Structure verified |
+| `/api/facebook-writer/reel/generate` | POST | Generate Facebook reel | ✅ Structure verified |
+| `/api/facebook-writer/carousel/generate` | POST | Generate carousel post | ✅ Structure verified |
+| `/api/facebook-writer/event/generate` | POST | Generate event description | ✅ Structure verified |
+| `/api/facebook-writer/group-post/generate` | POST | Generate group post | ✅ Structure verified |
+| `/api/facebook-writer/page-about/generate` | POST | Generate page about | ✅ Structure verified |
+| `/api/facebook-writer/ad-copy/generate` | POST | Generate ad copy | ✅ Structure verified |
+| `/api/facebook-writer/hashtags/generate` | POST | Generate hashtags | ✅ Structure verified |
+| `/api/facebook-writer/engagement/analyze` | POST | Analyze engagement | ✅ Structure verified |
+
+### Key Features Preserved
+1. **All Original Functionality**
+   - ✅ 10 distinct Facebook content generation tools
+   - ✅ Advanced options for customization
+   - ✅ Analytics predictions
+   - ✅ Optimization suggestions
+   - ✅ Error handling and validation
+
+2. **Enhanced Capabilities**
+   - ✅ RESTful API design
+   - ✅ Automatic OpenAPI documentation
+   - ✅ Strongly-typed request/response models
+   - ✅ Comprehensive error handling
+   - ✅ Scalable architecture
+
+## 🔍 Testing Results
+
+### Unit Tests Passed
+- ✅ Health endpoint: 200 OK
+- ✅ Tools listing: 10 tools returned
+- ✅ Request validation: Pydantic models working
+- ✅ Service integration: Gemini provider integration confirmed
+- ✅ Error handling: Proper error responses
+- ✅ Router integration: Successfully registered in main app
+
+### Integration Status
+- ✅ **FastAPI App**: Router successfully integrated
+- ✅ **Dependencies**: All required packages installed
+- ✅ **Import Structure**: Clean import paths resolved
+- ✅ **AI Provider**: Gemini integration working (requires API key)
+
+## 🎨 Original vs. New Architecture
+
+### Before (Streamlit)
+```python
+# Streamlit-based UI with direct function calls
+def facebook_main_menu():
+    # Streamlit widgets for input
+    business_type = st.text_input(...)
+    # Direct function call
+    result = write_fb_post(business_type, ...)
+    # Streamlit display
+    st.markdown(result)
+```
+
+### After (FastAPI)
+```python
+# REST API with structured models
+@router.post("/post/generate", response_model=FacebookPostResponse)
+async def generate_facebook_post(request: FacebookPostRequest):
+    # Service layer
+    response = post_service.generate_post(request)
+    # JSON response
+    return response
+```
+
+## 📋 Migration Phases Completed
+
+### Phase 1: Analysis & Planning ✅
+- [x] Analyzed original Facebook writer structure
+- [x] Identified 11 modules and their dependencies
+- [x] Planned FastAPI architecture
+- [x] Created directory structure
+
+### Phase 2: Models & Validation ✅
+- [x] Created Pydantic models for all 10 tools
+- [x] Implemented request validation
+- [x] Designed response structures
+- [x] Added enum classes for dropdowns
+
+### Phase 3: Business Logic ✅
+- [x] Created base service with Gemini integration
+- [x] Migrated all 10 modules to services
+- [x] Implemented error handling
+- [x] Added analytics and optimization features
+
+### Phase 4: API Layer ✅
+- [x] Created FastAPI router
+- [x] Implemented all 11 endpoints
+- [x] Added utility endpoints
+- [x] Integrated with main app
+
+### Phase 5: Testing & Validation ✅
+- [x] Tested basic endpoints
+- [x] Verified request/response flow
+- [x] Confirmed AI integration
+- [x] Created test documentation
+
+## 🚀 Ready for Frontend Integration
+
+The Facebook Writer API is now ready for React frontend integration:
+
+### Frontend Integration Points
+1. **HTTP Endpoints**: All 11 endpoints available at `/api/facebook-writer/*`
+2. **JSON Responses**: Structured data ready for UI consumption
+3. **Error Handling**: Consistent error format for UI error handling
+4. **Documentation**: OpenAPI spec for frontend development
+5. **Type Safety**: TypeScript types can be generated from Pydantic models
+
+### Example Frontend Usage
+```javascript
+// React component can now call the API
+const generatePost = async (formData) => {
+  const response = await fetch('/api/facebook-writer/post/generate', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(formData)
+  });
+  
+  const result = await response.json();
+  if (result.success) {
+    setGeneratedContent(result.content);
+    setAnalytics(result.analytics);
+  } else {
+    setError(result.error);
+  }
+};
+```
+
+## 📝 Recommendations for Next Steps
+
+### Immediate (React Integration)
+1. **API Client**: Create TypeScript API client from OpenAPI spec
+2. **Form Components**: Build React forms matching Pydantic models
+3. **State Management**: Implement Redux/Zustand for app state
+4. **Error Handling**: Create error boundary components
+
+### Short Term (Enhancement)
+1. **Authentication**: Add JWT authentication
+2. **Rate Limiting**: Implement API rate limiting
+3. **Caching**: Add Redis for response caching
+4. **Monitoring**: Add logging and metrics
+
+### Long Term (Scaling)
+1. **Database**: Add content history storage
+2. **Async Processing**: Queue long-running generation tasks
+3. **Multi-tenancy**: Support multiple organizations
+4. **A/B Testing**: Framework for testing different prompts
+
+## 🎉 Migration Success
+
+✅ **Complete**: All Facebook Writer functionality successfully migrated to FastAPI  
+✅ **Tested**: Core functionality verified and working  
+✅ **Documented**: Comprehensive API documentation created  
+✅ **Scalable**: Architecture ready for production deployment  
+✅ **Integration Ready**: Clean interfaces for React frontend
+
+The Facebook Writer is now a modern, scalable REST API that maintains all original functionality while providing a foundation for future enhancements and easy frontend integration.
--- a/docs/Facebook_Writer_CopilotKit_Integration_Plan.md
+++ b/docs/Facebook_Writer_CopilotKit_Integration_Plan.md
@@ -0,0 +1,215 @@
+
+# Facebook Writer + CopilotKit: Feature Set and Implementation Plan
+
+## 0) Current Implementation Status (Updated)
+- Core page and routing: `/facebook-writer` implemented with `CopilotSidebar` and scoped styling.
+- Readables: `postDraft`, `notes` exposed to Copilot; preferences summarized into system message.
+- Predictive state updates: live typing with progressive diff preview (green adds, red strikethrough deletes), then auto-commit.
+- Edit actions: `editFacebookDraft` (Casual, Professional, Upbeat, Shorten, Lengthen, TightenHook, AddCTA) with HITL micro-form; applies live preview via custom events.
+- Generation actions: `generateFacebookPost`, `generateFacebookHashtags`, `generateFacebookAdCopy` integrated with FastAPI endpoints; results synced to editor via window events.
+- Facebook Story: `generateFacebookStory` added with advanced and visual options (tone, include/avoid, CTA, stickers, text overlay, interactive types, etc.). Backend returns `content` plus one 9:16 image (`images_base64[0]`) generated via Gemini and the UI renders a Story Images panel.
+- Image generation module refactor: `gen_gemini_images.py` made backend-safe (removed Streamlit), added base64-first API, light retries, aligned with Gemini best practices.
+- Input robustness: frontend normalization/mapping to backend enum strings (prevents 422); friendly HITL validation.
+- Suggestions: progressive suggestions switch from “create” to “edit” when draft exists; stage-aware heuristics in place.
+- Chat memory and preferences: localStorage persistence of last 50 messages; recent conversation and saved preferences injected into `makeSystemMessage`; “Clear chat memory” button.
+- Confirm/Reject: explicit controls for predictive edits (Confirm changes / Discard) implemented.
+- Observability: Facebook writer requests flow through existing middleware; compact header control already live app-wide. Route-specific counters verification pending (planned below).
+
+Gaps / Remaining:
+- Context-aware suggestions need further refinement (e.g., based on draft length, tone, goal, time of day).
+- Tests for actions/handlers, reducer-like state transitions, and suggestion sets.
+- Observability counters and tags for `/api/facebook-writer/*` endpoints.
+- Backend session persistence (server-side conversation memory) for cross-device continuity (optional, phase-able).
+- Image generation controls (toggle, retries, error UX), caching, and cost guardrails.
+
+
+## 1) Goals
+- Provide a specialized Facebook Writer surface powered by CopilotKit.
+- Deliver intelligent, HITL (human-in-the-loop) workflows using Facebook Writer PR endpoints.
+- Reuse CopilotKit best practices (predictive state updates) as demonstrated in the example demo.
+- Ensure observability via existing middleware so system status appears in the main header control.
+
+Reference demo: https://demo-viewer-five.vercel.app/feature/predictive_state_updates
+
+---
+
+## 2) Feature Set
+
+### A. Core Copilot sidebar (Facebook Writer page)
+- Personalized title and greeting (brand/tenant aware when available).
+- Progressive suggestion groups:
+  - Social content
+  - Ads & campaigns
+  - Engagement & optimization
+- Always-on context-aware quick actions based on draft state (empty vs non-empty vs long draft).
+
+### B. Predictive state + collaborative editing
+- Readables
+  - draft: current post text
+  - notes/context: campaign intent, audience, key points
+  - preferences: tone, objective, hashtags on/off (persisted locally; summarized to system message)
+- Actions
+  - updateFacebookPostDraft(content)
+  - appendToFacebookPostDraft(content)
+  - editFacebookDraft(operation)
+  - summarizeDraft() (planned)
+  - rewriteDraft(style|objective) (planned)
+
+### C. PR endpoint coverage (initial, minimal)
+- POST /api/facebook-writer/post/generate (implemented)
+- POST /api/facebook-writer/hashtags/generate (implemented)
+- POST /api/facebook-writer/ad-copy/generate (implemented)
+- POST /api/facebook-writer/story/generate (implemented)
+- GET  /api/facebook-writer/tools (implemented)
+- GET  /api/facebook-writer/health (implemented)
+
+Next endpoints (planned):
+- Subsequent additions: reel/carousel/event/group/page-about
+
+### D. HITL micro-forms
+- Minimal modals inline in chat for:
+  - Objective (awareness, engagement, traffic, launch)
+  - Tone (professional, casual, upbeat, custom)
+  - Audience (free text)
+  - Include/avoid (free text)
+  - Hashtags on/off
+
+### E. Intelligent suggestions
+- Empty draft → “Create launch teaser”, “Benefit-first post”, “3 variants to A/B test”
+- Non-empty draft → “Tighten hook”, “Add CTA”, “Rewrite for professional tone”, “Generate hashtags” (live)
+- Long draft → “Summarize to 120-150 chars intro”, “Split into carousel captions” (future)
+
+### F. Observability and status
+- Ensure facebook endpoints counted in monitoring so the compact header “System • STATUS” reflects their activity.
+
+---
+
+## 3) Frontend Implementation Plan
+
+### 3.1 Route and page
+- Route: `/facebook-writer`
+- Component: `frontend/src/components/FacebookWriter/FacebookWriter.tsx`
+  - CopilotSidebar (scoped styling class)
+  - Textareas for notes and postDraft
+  - Readables: notes, postDraft
+  - Actions: updateFacebookPostDraft, appendToFacebookPostDraft
+
+### 3.2 API client
+- File: `frontend/src/services/facebookWriterApi.ts`
+  - postGenerate(req)
+  - adCopyGenerate(req)
+  - hashtagsGenerate(req)
+  - storyGenerate(req) [advanced + visual options]
+  - tools(), health()
+- Types aligned with PR models (enum value strings must match server models).
+
+### 3.3 Copilot actions (HITL + server calls)
+- File: `frontend/src/components/FacebookWriter/RegisterFacebookActions.tsx`
+  - Action: generateFacebookPost
+    - renderAndWaitForResponse → prompt for goal, tone, audience, include/avoid, hashtags
+    - Call api.postGenerate → update draft
+  - Action: generateHashtags
+    - renderAndWaitForResponse → topic or use draft
+    - Call api.hashtagsGenerate → append to draft
+  - Action: generateAdCopy (implemented)
+    - renderAndWaitForResponse → prompt for business_type, product/service, objective, format, audience, targeting basics, USP, budget
+    - Call api.adCopyGenerate → append primary text to draft; keep variations for UI
+  - Action: generateFacebookStory (implemented)
+    - renderAndWaitForResponse → advanced (hooks, CTA, etc.) and visual options (background type/prompt, overlay, interactive types)
+    - Call api.storyGenerate → append story content; dispatch `fbwriter:storyImages` to render returned image(s)
+- Helper: custom window events keep editor as single source of truth.
+
+### 3.4 Suggestions and system message
+- Suggestions computed from draft length, last action result, and notes presence.
+- System message includes short brand tone guidance when available.
+
+### 3.5 Demo parity (predictive state updates)
+- Expose two local actions for state updates:
+  - updateFacebookPostDraft
+  - appendToFacebookPostDraft
+- Ensure Copilot can call those without round-tripping to backend for quick edits.
+- Confirm/Reject step before committing predictive edits (implemented)
+
+---
+
+## 4) Backend Integration Plan
+
+### 4.1 Use PR structure
+- Routers: `backend/api/facebook_writer/routers/facebook_router.py`.
+- Services: `backend/api/facebook_writer/services/*`.
+- Models: `backend/api/facebook_writer/models/*`.
+
+### 4.2 Minimal requests for post.generate
+- Map HITL selections to `FacebookPostRequest` fields:
+  - post_goal: enum string value (e.g., “Build brand awareness”)
+  - post_tone: enum string value (e.g., “Professional”)
+  - media_type: “None” (default)
+  - advanced_options: from toggles
+- Handle 422 by ensuring exact enum text.
+
+### 4.3 Monitoring
+- No changes required if middleware already counts routes; confirm they appear in status.
+
+---
+
+## 5) UX details
+- Sidebar personalized title: “ALwrity • Facebook Writer”.
+- Glassomorphic style aligned with SEO assistant.
+- Accessibility: focus-visible rings, reduced-motion respect.
+- Error paths: concise toast + retry in HITL form.
+
+---
+
+## 6) Milestones
+- M1 (Done): Page + readables + predictive edits + suggestions (start/edit) + health/tools probe.
+- M2 (Done): HITL for post.generate; integrate API; hashtags action; editor sync.
+- M3 (Updated): Ad copy (done), Variations UI (done), Story (done), context-aware suggestions (ongoing), tests (pending).
+- M4 (Planned): Reel/Carousel; variants pipeline; scheduling hooks; session persistence (optional).
+
+### 6.1 Next-phase Tasks (Detailed)
+- Ad Copy (M3)
+  - Suggestion chips: “Create ad copy”, “Short ad variant (primary text)”, “Insert headline X”.
+  - A/B insert UX: quick insert/replace buttons already present; add multi-insert queue.
+- Story (M3)
+  - HITL toggle for image generation on/off; regenerate button; image count (1–3) cap.
+  - Gallery UX: copy/download, insert image markdown into draft, or upload to asset store.
+  - Improve visual prompt composition from form fields (brand + tone + CTA region).
+- Context-aware Suggestions (M3)
+  - Derive stage features: draft length buckets, tone inferred from text, presence of CTA/hashtags.
+  - Swap suggestion sets accordingly; include “Summarize intro” for long drafts.
+- Confirm/Reject for Predictive Edits (M3)
+  - Option: preference to auto-confirm future edits.
+- Tests (M3)
+  - Unit test action handlers (param mapping, event dispatch), reducer-like state transitions.
+  - Snapshot test suggestion sets for start/edit/long-draft.
+  - API client smoke tests for post/hashtags/ad-copy/story.
+- Observability (M3)
+  - Verify `/api/facebook-writer/*` counters in header; add tags for route family.
+  - Log action success/error counts.
+- Session Persistence (M4, optional)
+  - Backend `copilot_sessions` + `messages` tables; persist assistant/user messages.
+  - Provide `sessionId` per user/page; prehydrate sidebar from server.
+- Next endpoints (M4)
+  - Implement reel/carousel/event/group/page-about endpoints with parity HITL forms.
+
+### 6.2 Known limitations / Non-goals (for now)
+- Image generation: Gemini outputs include SynthID watermark; outputs not guaranteed each call; currently generates 1 image for story.
+- Cost/quotas: No server-side budgeting/limits yet for image gen; add per-user caps and caching.
+- Asset pipeline: No upload/CDN integration yet; images are rendered inline as base64.
+
+---
+
+## 7) Risks & Mitigations
+- Enum mismatches → Use exact server enum strings; surface helpful errors.
+- Long outputs → Clamp `max_tokens` server-side; provide “shorten” action client-side.
+- Rate limiting → Respect retry/backoff; keep client timeouts reasonable.
+
+Reference (Gemini image generation best practices): https://ai.google.dev/gemini-api/docs/image-generation
+
+---
+
+## 8) Success Criteria
+- End-to-end draft creation via Copilot with a single click (HITL).
+- Predictive state edits observable in real-time.
+- Monitoring reflects API usage in the header control.
+- Clean, reproducible flows for post + hashtags; extendable to ads and other tools.