diff --git a/.gitignore b/.gitignore index f628062..c4d9188 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ .env .env.local .env.*.local +*.local # Python __pycache__/ @@ -13,6 +14,15 @@ venv/ ENV/ env/ .venv/ +.pytest_cache/ +.coverage +htmlcov/ +.mypy_cache/ +.ruff_cache/ +*.egg-info/ +.eggs/ +pip-log.txt +pip-delete-this-directory.txt # Node node_modules/ @@ -20,14 +30,47 @@ dist/ build/ *.log npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* +.npm/ +.yarn/ -# IDE +# Vite +.vite/ +*.tsbuildinfo + +# Test coverage +coverage/ +*.lcov + +# IDE / Editors .idea/ .vscode/ *.swp *.swo -.DS_Store +*.sublime-workspace +*.sublime-project +.project +.settings/ +.classpath +*.code-workspace -# Build outputs -*.egg-info/ -.eggs/ +# OS generated files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# Temporary files +*.tmp +*.temp +*.bak +*~ + +# Debug +.debug/ +*.pdb diff --git a/README.md b/README.md new file mode 100644 index 0000000..9a5b935 --- /dev/null +++ b/README.md @@ -0,0 +1,272 @@ +# Mod Comms + +An AI-powered proof review tool for Barclays marketing materials. Mod Comms uses a multi-agent AI system to analyze uploaded marketing assets for legal compliance, brand adherence, tone of voice, and channel suitability. + +## Features + +- **Multi-Agent Analysis** - Four specialist AI agents analyze proofs in parallel, with a lead agent synthesizing the final verdict +- **Real-Time Feedback** - WebSocket streaming provides live progress updates during analysis +- **Campaign Management** - Organize proofs by campaign with full version history +- **WIP Reviewer** - Get early-stage creative feedback on work-in-progress assets +- **Analytics Dashboard** - Track compliance metrics, status breakdowns, and trends +- **Auditing** - Full audit trail for flagged issues and resolutions +- **PDF Export** - Generate professional reports of analysis results + +## Architecture + +### Multi-Agent System + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Analysis Orchestrator │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Legal Agent │ │ Brand Agent │ │ Tone Agent │ │ +│ │ Compliance │ │ Visual ID │ │ Voice/Clarity│ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ ┌──────────────┐ ┌──────────────────────────────────┐ │ +│ │Channel Agent │ │ Lead Agent │ │ +│ │Platform Specs│ │ Synthesizes Final Verdict │ │ +│ └──────────────┘ └──────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +Each agent returns a RAG status (Red/Amber/Green) with detailed feedback: + +| Agent | Responsibility | +|-------|----------------| +| **Legal** | Advertising standards, disclaimers, financial promotion detection | +| **Brand** | Logo usage, color palette, typography, design principles | +| **Tone** | Copy clarity, brand voice, grammar, personality alignment | +| **Channel** | Platform-specific specs, accessibility, technical requirements | +| **Lead** | Synthesizes all feedback and determines overall pass/fail status | + +### Tech Stack + +**Frontend** +- React 19 with TypeScript +- Vite for build tooling +- TailwindCSS for styling +- jsPDF for report generation + +**Backend** +- FastAPI (Python) +- WebSocket for real-time communication +- Google Gemini 2.5 Flash for AI analysis +- Pydantic for data validation + +## Project Structure + +``` +barclays_modcomms/ +├── frontend/ # React web application +│ ├── components/ # UI components +│ ├── services/ # API integrations +│ ├── App.tsx # Main app with routing +│ └── types.ts # TypeScript definitions +│ +├── backend/ # FastAPI server +│ ├── app/ +│ │ ├── agents/ # AI agent implementations +│ │ ├── services/ # Gemini API, analysis orchestration +│ │ ├── websocket/ # Real-time communication +│ │ └── main.py # FastAPI entry point +│ └── requirements.txt +│ +├── reference_docs/ # Brand & channel guidelines +│ ├── brand/ # Barclays brand guidelines +│ └── channel/ # Digital channel specifications +│ +├── specs/ # Product requirements +└── test_files/ # Sample assets for testing +``` + +## Getting Started + +### Prerequisites + +- Node.js 18+ +- Python 3.8+ +- Google Gemini API key + +### Backend Setup + +```bash +cd backend + +# Create virtual environment +python -m venv venv +source venv/bin/activate # Windows: venv\Scripts\activate + +# Install dependencies +pip install -r requirements.txt + +# Configure environment +cp .env.example .env +# Edit .env and add your GEMINI_API_KEY + +# Start server +uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 +``` + +### Frontend Setup + +```bash +cd frontend + +# Install dependencies +npm install + +# Configure environment +cp .env.example .env.local # or create manually +# Add to .env.local: +# GEMINI_API_KEY=your_key +# VITE_BACKEND_WS_URL=ws://localhost:8000/ws/analyze +# VITE_BACKEND_URL=http://localhost:8000 + +# Start development server +npm run dev +``` + +The application will be available at `http://localhost:3000`. + +## Environment Variables + +### Backend (`backend/.env`) + +| Variable | Description | Default | +|----------|-------------|---------| +| `GEMINI_API_KEY` | Google Gemini API key | Required | +| `CORS_ORIGINS` | Allowed CORS origins | `http://localhost:3000` | +| `HOST` | Server host | `0.0.0.0` | +| `PORT` | Server port | `8000` | +| `REFERENCE_DOCS_PATH` | Path to reference docs | `../reference_docs` | + +### Frontend (`frontend/.env.local`) + +| Variable | Description | +|----------|-------------| +| `GEMINI_API_KEY` | Google Gemini API key | +| `VITE_BACKEND_WS_URL` | WebSocket URL for analysis | +| `VITE_BACKEND_URL` | Backend REST API URL | + +## Usage + +### Analyzing a Proof + +1. Log in to the application +2. Navigate to **Campaigns** and select or create a campaign +3. Upload a marketing asset (image or PDF) +4. Watch the real-time analysis progress as each agent processes the proof +5. Review the feedback report with RAG status for each agent +6. Flag any issues that need attention or mark items as resolved + +### Understanding RAG Status + +- **Green** - Compliant, no issues found +- **Amber** - Minor issues that should be addressed +- **Red** - Critical issues that must be fixed before approval + +### Overall Status Logic + +| Status | Condition | +|--------|-----------| +| **Passed** | All agents Green, or minor Amber issues | +| **Failed** | Any agent returns Red | +| **Requires Manual Legal Review** | Financial promotion detected | +| **Analysis Error** | Processing error occurred | + +## API Reference + +### WebSocket Endpoint + +**`/ws/analyze`** - Real-time proof analysis + +**Request:** +```json +{ + "type": "analyze", + "file_data": "", + "file_type": "image/png", + "is_wip": false +} +``` + +**Response Messages:** +```json +{ "type": "agent_started", "agent_name": "Brand Agent" } +{ "type": "agent_completed", "agent_name": "Brand Agent", "review": {...} } +{ "type": "summary" } +{ "type": "complete", "result": {...} } +``` + +### REST Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/health` | GET | Health check | +| `/info` | GET | Backend info and reference doc summary | + +## Development + +### Build for Production + +```bash +# Frontend +cd frontend +npm run build +npm run preview # Preview production build + +# Backend +cd backend +uvicorn app.main:app --host 0.0.0.0 --port 8000 +``` + +### Project Commands + +```bash +# Frontend +npm run dev # Start dev server +npm run build # Production build +npm run preview # Preview build + +# Backend +uvicorn app.main:app --reload # Dev server with hot reload +``` + +## Reference Documentation + +The `reference_docs/` directory contains brand and channel guidelines used by the AI agents: + +**Brand Guidelines:** +- Barclaycard core principles +- Barclays tone of voice +- Barclays expression core principles +- Brand architecture guidelines +- Brand design language principles + +**Channel Guidelines:** +- Barclaycard digital guidelines +- Digital guidelines +- Social media guidelines + +## User Roles + +| Role | Access | +|------|--------| +| **Admin** | Full access to all campaigns, Settings, Analytics, Auditing | +| **Basic User** | Limited to own agency's campaigns | + +## Data Persistence + +Application state is persisted to localStorage with the following keys: +- `barclays_modcomms_campaigns_v3` +- `barclays_modcomms_campaign_proofs_v3` +- `barclays_modcomms_flagged_items_v3` +- `barclays_modcomms_resolved_items_v3` +- `barclays_modcomms_error_items_v3` + +## License + +Proprietary - Barclays Internal Use Only