chore: remove duplicate files (old Streamlit README, duplicate video)
Browse files- README_SPACE.md +0 -160
README_SPACE.md
DELETED
|
@@ -1,160 +0,0 @@
|
|
| 1 |
-
# Sentiment Evolution Tracker – Hugging Face Space Edition
|
| 2 |
-
|
| 3 |
-
MCP-powered customer sentiment monitoring packaged for Hugging Face Spaces and local demos.
|
| 4 |
-
|
| 5 |
-
> Nota: el dashboard Streamlit es opcional y no forma parte del entregable principal. Solo ejecútalo si quieres experimentar con la versión interactiva local.
|
| 6 |
-
|
| 7 |
-
## 🚀 Launch The Demo (Opcional)
|
| 8 |
-
|
| 9 |
-
```powershell
|
| 10 |
-
streamlit run app.py
|
| 11 |
-
```
|
| 12 |
-
|
| 13 |
-
Open `http://localhost:8501` for the interactive dashboard.
|
| 14 |
-
|
| 15 |
-
## 📊 Feature Set
|
| 16 |
-
|
| 17 |
-
### Interactive Dashboard
|
| 18 |
-
- Four KPIs (customers, analyses, sentiment, alerts).
|
| 19 |
-
- Two charts (churn risk vs. time, sentiment trend).
|
| 20 |
-
- Detailed customer table with statuses.
|
| 21 |
-
|
| 22 |
-
### Deep-Dive Panels
|
| 23 |
-
- Select any customer to view historical analyses.
|
| 24 |
-
- Inspect sentiment velocity and recommended actions.
|
| 25 |
-
- Highlight churn drivers automatically.
|
| 26 |
-
|
| 27 |
-
### Multi-Customer Trends
|
| 28 |
-
- Compare sentiment trajectories across clients.
|
| 29 |
-
- Identify shared risk signals.
|
| 30 |
-
|
| 31 |
-
### MCP Tooling (7 tools)
|
| 32 |
-
1. `analyze_sentiment_evolution`
|
| 33 |
-
2. `detect_risk_signals`
|
| 34 |
-
3. `predict_next_action`
|
| 35 |
-
4. `get_customer_history`
|
| 36 |
-
5. `get_high_risk_customers`
|
| 37 |
-
6. `get_database_statistics`
|
| 38 |
-
7. `save_analysis`
|
| 39 |
-
|
| 40 |
-
## 💻 Local Setup
|
| 41 |
-
|
| 42 |
-
Requirements: Python 3.10+, pip.
|
| 43 |
-
|
| 44 |
-
```powershell
|
| 45 |
-
git clone https://huggingface.co/spaces/MCP-1st-Birthday/sentiment-tracker
|
| 46 |
-
cd mcp-nlp-server
|
| 47 |
-
pip install -r requirements.txt
|
| 48 |
-
python init_db.py
|
| 49 |
-
python tools\populate_demo_data.py
|
| 50 |
-
python tools\dashboard.py
|
| 51 |
-
python tools\generate_report.py # opens data/reporte_clientes.html
|
| 52 |
-
streamlit run app.py
|
| 53 |
-
```
|
| 54 |
-
|
| 55 |
-
## 🔧 MCP Configuration
|
| 56 |
-
|
| 57 |
-
1. Edit `config/claude_desktop_config.json`.
|
| 58 |
-
2. Point the server entry to `src/mcp_server.py`.
|
| 59 |
-
3. Restart Claude Desktop and select the sentiment tracker server.
|
| 60 |
-
|
| 61 |
-
```json
|
| 62 |
-
{
|
| 63 |
-
"mcpServers": {
|
| 64 |
-
"sentiment-tracker": {
|
| 65 |
-
"command": "python",
|
| 66 |
-
"args": ["src/mcp_server.py"],
|
| 67 |
-
"cwd": "C:/path/to/mcp-nlp-server"
|
| 68 |
-
}
|
| 69 |
-
}
|
| 70 |
-
}
|
| 71 |
-
```
|
| 72 |
-
|
| 73 |
-
## 📈 Use Cases
|
| 74 |
-
|
| 75 |
-
### 1. Churn Prediction
|
| 76 |
-
```
|
| 77 |
-
Input → customer ID
|
| 78 |
-
Process → trend analysis + risk signals + alerts
|
| 79 |
-
Output → alert if risk > 70% with suggested actions
|
| 80 |
-
```
|
| 81 |
-
|
| 82 |
-
### 2. Real-Time Monitoring
|
| 83 |
-
```
|
| 84 |
-
Dashboard highlights:
|
| 85 |
-
- Critical accounts (red)
|
| 86 |
-
- At-risk accounts (orange)
|
| 87 |
-
- Healthy accounts (green)
|
| 88 |
-
Updated whenever new analyses are stored
|
| 89 |
-
```
|
| 90 |
-
|
| 91 |
-
### 3. Executive Reporting
|
| 92 |
-
```
|
| 93 |
-
Generate the HTML report to share daily:
|
| 94 |
-
- Risk charts
|
| 95 |
-
- Sentiment evolution
|
| 96 |
-
- Top 5 accounts needing attention
|
| 97 |
-
- Actionable recommendations
|
| 98 |
-
```
|
| 99 |
-
|
| 100 |
-
### 4. LLM Integration
|
| 101 |
-
```
|
| 102 |
-
Claude workflow:
|
| 103 |
-
→ get_high_risk_customers()
|
| 104 |
-
→ get_customer_history()
|
| 105 |
-
→ predict_next_action()
|
| 106 |
-
→ Respond with urgency, revenue at risk, and next steps
|
| 107 |
-
```
|
| 108 |
-
|
| 109 |
-
## 📊 Sample Dataset
|
| 110 |
-
|
| 111 |
-
- Five demo customers (manufacturing, tech, retail, healthcare, finance).
|
| 112 |
-
- Seventeen conversations across rising/declining/stable trends.
|
| 113 |
-
- Alerts triggered automatically when risk exceeds thresholds.
|
| 114 |
-
|
| 115 |
-
## 🎯 Architecture
|
| 116 |
-
|
| 117 |
-
```
|
| 118 |
-
User / Team Lead
|
| 119 |
-
↓
|
| 120 |
-
Claude Desktop (optional)
|
| 121 |
-
↓ MCP Protocol (stdio)
|
| 122 |
-
Sentiment Tracker Server (7 tools)
|
| 123 |
-
↓
|
| 124 |
-
SQLite Database (customer_profiles, conversations, risk_alerts)
|
| 125 |
-
```
|
| 126 |
-
|
| 127 |
-
## 🔑 Key Advantages
|
| 128 |
-
|
| 129 |
-
- **Local-first**: keep customer data on-prem.
|
| 130 |
-
- **Zero external APIs**: predictable cost, improved privacy.
|
| 131 |
-
- **Real-time**: sentiment scoring < 100 ms per request.
|
| 132 |
-
- **Predictive**: churn detection 5–7 days ahead.
|
| 133 |
-
- **Agentic**: Claude drives the workflow autonomously.
|
| 134 |
-
- **Scalable**: handles thousands of customers on commodity hardware.
|
| 135 |
-
|
| 136 |
-
## 📚 Documentation
|
| 137 |
-
|
| 138 |
-
- [Architecture](docs/ARCHITECTURE.md)
|
| 139 |
-
- [Quick Start](docs/QUICK_START.md)
|
| 140 |
-
- [Blog Post](../BLOG_POST.md)
|
| 141 |
-
|
| 142 |
-
## 🤝 Contributions
|
| 143 |
-
|
| 144 |
-
Suggestions are welcome—open an issue or submit a pull request.
|
| 145 |
-
|
| 146 |
-
## 📝 License
|
| 147 |
-
|
| 148 |
-
MIT License.
|
| 149 |
-
|
| 150 |
-
## 🙏 Acknowledgements
|
| 151 |
-
|
| 152 |
-
- Anthropic for MCP.
|
| 153 |
-
- Hugging Face for the hosting platform.
|
| 154 |
-
- TextBlob + NLTK for NLP utilities.
|
| 155 |
-
|
| 156 |
-
---
|
| 157 |
-
|
| 158 |
-
Built for the MCP 1st Birthday Hackathon 🎉
|
| 159 |
-
|
| 160 |
-
[GitHub](https://github.com) • [Blog](../BLOG_POST.md) • [Docs](docs/)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|