https://github.com/gabrielm3/customer-intelligence-hub
An intelligent Customer Relationship Management system powered by AI agents, designed to analyze customer data, create targeted marketing campaigns, and provide actionable business insights
https://github.com/gabrielm3/customer-intelligence-hub
docker docker-compose langgraph langsmith mcp-server python
Last synced: 15 days ago
JSON representation
An intelligent Customer Relationship Management system powered by AI agents, designed to analyze customer data, create targeted marketing campaigns, and provide actionable business insights
- Host: GitHub
- URL: https://github.com/gabrielm3/customer-intelligence-hub
- Owner: Gabrielm3
- Created: 2025-10-02T17:45:26.000Z (16 days ago)
- Default Branch: master
- Last Pushed: 2025-10-02T21:58:46.000Z (16 days ago)
- Last Synced: 2025-10-02T23:37:08.315Z (16 days ago)
- Topics: docker, docker-compose, langgraph, langsmith, mcp-server, python
- Language: Python
- Homepage:
- Size: 7.11 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Customer Intelligence Hub - CRM
An intelligent Customer Relationship Management system powered by AI agents, designed to analyze customer data, create targeted marketing campaigns, and provide actionable business insights.
## Overview
Customer Intelligence Hub is an AI-powered system that combines customer data analysis with automated marketing capabilities. It uses LangGraph for agent orchestration, PostgreSQL for data storage, and Model Context Protocol (MCP) for tool integration.
## Architecture
```mermaid
graph TB
A[👤 User] --> B[🤖 Neo AI Agent]
B --> C[🔧 MCP Tools Layer]
C --> D[🗄️ PostgreSQL Server]
C --> E[📧 Marketing Server]
C --> F[💬 Slack Server]
D --> G[(📊 Customer Database)]
G --> H[👥 Customers]
G --> I[💰 Transactions]
G --> J[📈 RFM Analysis]
G --> K[🎯 Campaigns]
E --> L[📝 Campaign Creation]
E --> M[✉️ Email Automation]
F --> N[🔔 Team Notifications]
F --> O[💡 Insights Sharing]
B --> P[📊 LangSmith Tracking]
```
## Key Features
- **AI-Powered Customer Analysis**: Automated RFM (Recency, Frequency, Monetary) analysis
- **Smart Marketing Campaigns**: Create and manage targeted campaigns based on customer segments
- **Real-time Data Queries**: Natural language interface to query customer and sales data
- **Slack Integration**: Share insights and updates with your team automatically
- **Comprehensive Tracking**: Full observability with LangSmith integration
## Benefits
- **🎯 Targeted Marketing**: Identify high-value customers and create personalized campaigns
- **📊 Data-Driven Insights**: Get instant answers about customer behavior and sales performance
- **⚡ Automation**: Reduce manual work with automated campaign creation and email sending
- **👥 Team Collaboration**: Keep everyone informed with Slack notifications
- **📈 Performance Tracking**: Monitor all AI interactions and decisions with LangSmith
- **🔄 Scalable Architecture**: Built with modern tools for enterprise-grade performance
## Quick Start
### Prerequisites
- Docker and Docker Compose
- OpenAI API Key
- LangSmith API Key (optional, for tracking)
- Slack Bot Token (optional, for Slack integration)
### Running with Docker (Recommended)
1. **Clone the repository**
```bash
git clone https://github.com/Gabrielm3/customer-intelligence-hub
cd customer-intelligence-hub
```
2. **Configure environment variables**
```bash
cp .env.example .env
# Edit .env with your API keys
```
3. **Start the system**
```bash
docker-compose up --build -d
```
4. **Generate and import sample data**
```bash
# Generate CSV files from raw data (run once)
docker-compose exec crm-agent bash -c "cd database && uv run python generate_data_tables.py"
# Import CSV files to database
docker-compose exec crm-agent bash -c "cd database && uv run python import_data.py"
```
5. **Start the interactive CLI**
```bash
docker-compose exec crm-agent uv run python cli/interactive_cli.py
```
### Running Locally
1. **Install dependencies**
```bash
uv sync
```
2. **Set up PostgreSQL database**
```bash
# Start PostgreSQL locally or use Docker
docker run -d --name postgres \
-e POSTGRES_DB=crm_database \
-e POSTGRES_USER=crm_user \
-e POSTGRES_PASSWORD=crm_password \
-p 5432:5432 postgres:15-alpine
```
3. **Configure environment**
```bash
cp .env.example .env
# Update DATABASE_URL for local PostgreSQL
```
4. **Initialize database**
```bash
cd database
# Generate CSV files from raw data
uv run python generate_data_tables.py
# Import to database
uv run python import_data.py
```
5. **Run the CLI**
```bash
uv run python cli/interactive_cli.py
```
## Usage Examples
Once the system is running, you can ask Neo (the AI agent) questions like:
- **Customer Analysis**: "How many customers do we have?" or "Show me the top 5 customers by spending"
- **Product Insights**: "What are our best-selling products?" or "Which products have the highest margins?"
- **Marketing Campaigns**: "Create a loyalty campaign for VIP customers" or "Send a re-engagement email to inactive customers"
- **RFM Analysis**: "Show me the RFM analysis of our customers" or "Who are our most valuable customers?"
## Configuration
### Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `OPENAI_API_KEY` | OpenAI API key for AI agent | Yes |
| `DATABASE_URL` | PostgreSQL connection string | Yes |
| `LANGSMITH_API_KEY` | LangSmith tracking (optional) | No |
| `SLACK_BOT_TOKEN` | Slack integration (optional) | No |
| `SLACK_TEAM_ID` | Slack team ID (optional) | No |
### MCP Servers
The system uses three MCP servers:
- **PostgreSQL**: For database queries and analytics
- **Marketing**: For campaign creation and email automation
- **Slack**: For team communication and notifications
## Project Structure
```
customer-intelligence-hub/
├── src/crm_agent/ # Core agent logic
│ ├── agent_graph.py # LangGraph workflow
│ ├── system_prompts.py # AI agent prompts
│ └── mcp_servers/ # MCP server configurations
├── cli/ # Interactive command-line interface
├── database/ # Database setup and sample data
├── docker-compose.yml # Docker orchestration
└── pyproject.toml # Python dependencies
```
## Troubleshooting
### Common Issues
**Database Connection Error**
```bash
# Check if PostgreSQL is running
docker-compose ps
# Restart if needed
docker-compose restart postgres
```
**Missing Dependencies**
```bash
# Rebuild containers
docker-compose down
docker-compose up --build
```
**Empty Database**
```bash
# Re-generate and import sample data
docker-compose exec crm-agent bash -c "cd database && uv run python generate_data_tables.py"
docker-compose exec crm-agent bash -c "cd database && uv run python import_data.py"
```
### Monitoring
- **LangSmith Dashboard**: https://smith.langchain.com/ (project: `customer-intelligence-hub`)
- **Database Status**: `docker-compose exec postgres psql -U crm_user -d crm_database -c "\dt"`
- **Container Logs**: `docker-compose logs crm-agent`
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.