Priority Pulse

An AI-powered email prioritization system with intelligent multi-agent learning, knowledge graphs, and personalized email management.

Overview

Priority Pulse is a full-stack application that helps users manage their email inbox more effectively by leveraging artificial intelligence to prioritize emails based on user preferences, context, and historical patterns. The system uses a sophisticated multi-agent architecture to analyze emails, extract criteria, evaluate priority, and provide actionable insights.

Key Features

Intelligent Email Prioritization: AI-driven ranking of emails based on learned user preferences
Multi-Agent System: Specialized agents handle different aspects of email processing:
- Gmail Agent: Email retrieval and management
- Calendar Agent: Integration with Google Calendar for context
- Docs Agent: Google Docs integration for document analysis
- Knowledge Graph Agent: Building and querying knowledge graphs
- Evaluation Agent: Prioritization and scoring
- Verification Agent: Quality assurance
Knowledge Graph: Automatically built knowledge graph from email content for semantic understanding
User Feedback Loop: Learns from user actions and feedback to improve prioritization over time
Memory Management: Persistent memory system using Mem0AI for contextual awareness
Vector Search: Chroma DB integration for semantic email search
Google Workspace Integration: Seamless integration with Gmail, Google Calendar, and Google Docs

Project Structure

Priority Pulse/
├── priorityPulseBackend/      # Python FastAPI backend
│   ├── agents/                # Multi-agent system implementation
│   │   ├── base_agent.py      # Base agent class
│   │   ├── gmail_agent.py     # Gmail operations
│   │   ├── calendar_agent.py  # Calendar integration
│   │   ├── docs_agent.py      # Google Docs integration
│   │   ├── kg_agent.py        # Knowledge graph operations
│   │   ├── criteria_agent.py  # Email criteria extraction
│   │   ├── evaluation_agent.py# Email evaluation and scoring
│   │   └── verifier_agent.py  # Result verification
│   ├── mcp_servers/           # Model Context Protocol servers
│   ├── models/                # Data models (Email, UserFeedback, etc.)
│   ├── storage/               # Persistent storage
│   │   └── chroma_db/         # Vector database
│   ├── api.py                 # FastAPI application
│   ├── agent_system.py        # Email prioritization system orchestrator
│   ├── auth_setup.py          # Authentication configuration
│   ├── firefox_auth.py        # Firebase authentication
│   ├── gmail_listener.py      # Gmail webhook listener
│   └── requirements.txt        # Python dependencies
├── priorityPulseFrontend/     # React + Vite frontend
│   ├── src/
│   │   ├── pages/             # Page components
│   │   │   ├── Dashboard.jsx
│   │   │   ├── Evaluate.jsx
│   │   │   ├── Feedback.jsx
│   │   │   ├── Login.jsx
│   │   │   ├── Memories.jsx
│   │   │   └── Setup.jsx
│   │   ├── components/        # Reusable components
│   │   │   ├── EmailCard.jsx
│   │   │   ├── EmailActions.jsx
│   │   │   ├── CalendarWidget.jsx
│   │   │   ├── KGWidget.jsx
│   │   │   └── Navbar.jsx
│   │   ├── hooks/             # Custom React hooks
│   │   │   ├── useAuth.js
│   │   │   ├── useDashboard.js
│   │   │   ├── useEmailActions.js
│   │   │   └── useKnowledgeGraph.js
│   │   ├── context/           # React context (Auth)
│   │   ├── api/               # API client
│   │   ├── App.jsx            # Main component
│   │   └── main.jsx           # Entry point
│   ├── package.json           # Node.js dependencies
│   └── vite.config.js         # Vite configuration
└── README.md                  # This file

Prerequisites

System Requirements

Python 3.10+
Node.js 16+
npm or yarn
A Google Cloud project with APIs enabled (Gmail, Calendar, Docs, Pub/Sub)
Firebase project

Required APIs

Enable the following APIs in your Google Cloud Console:

Gmail API
Google Calendar API
Google Docs API
Cloud Pub/Sub API
Cloud Credentials API

Installation

Backend Setup

Navigate to the backend directory:
```
cd priorityPulseBackend
```

Create a Python virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```

Set up environment variables: Create a .env file in priorityPulseBackend/:

JWT_SECRET=your-secret-key-here
GEMINI_API_KEY=your-google-generative-ai-key
FIREBASE_PROJECT_ID=your-firebase-project-id
GOOGLE_OAUTH_CLIENT_ID=your-oauth-client-id
GOOGLE_OAUTH_CLIENT_SECRET=your-oauth-client-secret

Configure Google Credentials:
- Place your service_account.json in the priorityPulseBackend/ directory
- Place your oAuthCredentials.json in the priorityPulseBackend/ directory

Frontend Setup

Navigate to the frontend directory:
```
cd priorityPulseFrontend
```
Install dependencies:
```
npm install
```
Configure Firebase: Update src/firebase.js with your Firebase project credentials

Set up environment variables: Create a .env file in priorityPulseFrontend/:

VITE_GOOGLE_CLIENT_ID=your-oauth-client-id
VITE_API_URL=http://localhost:8000

Running the Application

Start the Backend

cd priorityPulseBackend
python -m uvicorn api:app --reload --port 8000

The API will be available at http://localhost:8000

API Documentation: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Start the Frontend

cd priorityPulseFrontend
npm run dev

The frontend will be available at http://localhost:5173

Start the Gmail Listener (Optional)

In a separate terminal:

cd priorityPulseBackend
python gmail_listener.py

Architecture

Backend Architecture

The backend uses a multi-agent system pattern with specialized agents that communicate through a central orchestrator:

Agent System Orchestrator (agent_system.py): Coordinates all agents and manages email processing workflow
Specialized Agents:
- Gmail Agent: Retrieves emails, manages labels, executes actions
- Evaluation Agent: Scores and prioritizes emails
- Criteria Agent: Extracts prioritization criteria from user feedback
- Knowledge Graph Agent: Builds and queries semantic graphs
- Calendar Agent: Fetches calendar events for context
- Docs Agent: Accesses Google Docs for background information
- Verification Agent: Validates agent outputs

Frontend Architecture

The frontend is built with React and uses:

Context API for state management (Authentication)
Custom Hooks for business logic
Axios for API communication
React Router for navigation
Vite for fast development and building

API Endpoints

Core Endpoints

POST /auth/login - User authentication with Google OAuth
POST /emails/sync - Sync emails from Gmail
GET /emails - Get prioritized email list
POST /emails/{id}/evaluate - Get AI evaluation for an email
POST /emails/{id}/feedback - Submit user feedback
GET /emails/{id}/context - Get email context from knowledge graph
GET /dashboard/stats - Get dashboard statistics
POST /kg/query - Query knowledge graph

Configuration Files

config.json: Application configuration settings
config.py: Python configuration and constants
firebase.json: Firebase deployment configuration
vite.config.js: Vite build configuration
eslint.config.js: Code linting rules

Storage and Persistence

Vector Database: storage/chroma_db/ - Chroma DB for semantic embeddings
Criteria History: storage/criteria_history.json - User criteria evolution
Feedback Log: storage/feedback_log.json - User feedback history
Knowledge Graph: storage/kg_graph.json - Semantic knowledge graph

Development

Code Quality

Run linting:

# Frontend
cd priorityPulseFrontend
npm run lint

# Backend - using built-in checks
cd priorityPulseBackend
python _check_syntax.py

Authentication Verification

Verify authentication setup:

cd priorityPulseBackend
python _verify_auth.py

Deployment

Frontend Deployment (Firebase)

cd priorityPulseFrontend
npm run build
npm run deploy

Backend Deployment

The backend can be deployed to various platforms:

Google Cloud Run
AWS EC2/Lambda
Heroku
Local server

Environment Variables

Backend (.env)

JWT_SECRET=your-secret-key
GEMINI_API_KEY=your-api-key
FIREBASE_PROJECT_ID=your-project-id
GOOGLE_OAUTH_CLIENT_ID=your-client-id
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret

Frontend (.env)

VITE_GOOGLE_CLIENT_ID=your-client-id
VITE_API_URL=http://localhost:8000

Troubleshooting

Backend Issues

Gmail API errors: Ensure service account has appropriate permissions
Firebase authentication failures: Check Firebase credentials and project config
Agent communication issues: Verify all API keys are correctly set

Frontend Issues

CORS errors: Ensure backend CORS middleware is configured correctly
Authentication issues: Verify Google OAuth credentials
API connection failures: Check that backend is running on correct port

Contributing

Create a feature branch (git checkout -b feature/your-feature)
Commit your changes (git commit -am 'Add new feature')
Push to the branch (git push origin feature/your-feature)
Create a Pull Request

Technologies Used

Backend

FastAPI: Web framework
Uvicorn: ASGI server
Google Cloud APIs: Gmail, Calendar, Docs, Pub/Sub
Firebase: Authentication and hosting
Chroma DB: Vector database for semantic search
Mem0AI: Memory and context management
Google Generative AI: LLM for intelligent processing
PyJWT: Session token management

Frontend

React 19: UI library
Vite: Build tool and dev server
React Router: Client-side routing
Axios: HTTP client
Google OAuth: Authentication
Lucide React: Icon library

Last Updated: February 2026

Name		Name	Last commit message	Last commit date
priorityPulseBackend		priorityPulseBackend
priorityPulseFrontend		priorityPulseFrontend
README.md		README.md
vendor_monitoring_research.md		vendor_monitoring_research.md

Latest commit

History

Folders and files

Repository files navigation