Spaces:
Sleeping
Sleeping
| title: SentimentAI | |
| emoji: 🎭 | |
| colorFrom: purple | |
| colorTo: blue | |
| sdk: docker | |
| app_file: app.py | |
| pinned: false | |
| license: apache-2.0 | |
| short_description: "3-class sentiment analysis API — airzipm" | |
| # 🎭 SentimentAI — RoBERTa Sentiment Analysis API | |
| A production-grade, high-concurrency sentiment analysis API built on | |
| [airzipm/sentiment-analysis-roberta](https://huggingface.co/airzipm/sentiment-analysis-roberta). | |
| Classifies text into **Positive**, **Neutral**, or **Negative** with confidence scores. | |
| --- | |
| ## 🚀 Quick Start | |
| ### Live Demo | |
| Open the Space URL in your browser — the frontend (`index.html`) loads automatically. | |
| ### Base URL | |
| ``` | |
| https://airzipm-sentimentai.hf.space | |
| ``` | |
| --- | |
| ## 📡 API Endpoints | |
| | Method | Path | Rate Limit | Description | | |
| |--------|------|-----------|-------------| | |
| | `GET` | `/` | — | Serve frontend `index.html` | | |
| | `GET` | `/health` | — | Model readiness & server stats | | |
| | `GET` | `/ping` | — | Lightweight liveness check | | |
| | `POST` | `/analyze` | 30/min per IP | Single text sentiment analysis | | |
| | `POST` | `/batch` | 10/min per IP | Batch analysis (up to 10 texts) | | |
| | `GET` | `/docs` | — | Interactive Swagger UI | | |
| | `GET` | `/redoc` | — | ReDoc API documentation | | |
| --- | |
| ## 🔍 Endpoint Reference | |
| ### `GET /ping` | |
| Ultra-lightweight liveness probe. No inference. Always < 5ms. | |
| Frontend pings this every 30 seconds to prevent the Space from sleeping. | |
| **Response:** | |
| ```json | |
| { | |
| "pong": true, | |
| "model_ready": true, | |
| "t": 1717500000.123 | |
| } | |
| ``` | |
| --- | |
| ### `GET /health` | |
| Model readiness check with server statistics. | |
| Always returns HTTP 200 — read the `status` field to check readiness. | |
| **Response:** | |
| ```json | |
| { | |
| "status": "ok", | |
| "model_loaded": true, | |
| "device": "cpu", | |
| "model_name": "airzipm/sentiment-analysis-roberta", | |
| "uptime_s": 342.7, | |
| "requests_served": 1284, | |
| "version": "1.0.0" | |
| } | |
| ``` | |
| | `status` value | Meaning | | |
| |---------------|---------| | |
| | `"ok"` | Model loaded, ready to serve | | |
| | `"loading"` | Model is still initializing (cold start) | | |
| | `"error"` | Model failed to load (check logs) | | |
| --- | |
| ### `POST /analyze` | |
| Analyze sentiment of a single text. HuggingFace Inference API compatible. | |
| **Rate limit:** 30 requests per IP per minute | |
| **Request body:** | |
| ```json | |
| { | |
| "inputs": "This movie was absolutely amazing!" | |
| } | |
| ``` | |
| **Successful response (200):** | |
| ```json | |
| { | |
| "label": "Positive", | |
| "score": 0.973241, | |
| "all_scores": [ | |
| {"label": "Positive", "score": 0.973241}, | |
| {"label": "Neutral", "score": 0.021034}, | |
| {"label": "Negative", "score": 0.005725} | |
| ], | |
| "response_ms": 87 | |
| } | |
| ``` | |
| **Error responses:** | |
| | Status | When | Body | | |
| |--------|------|------| | |
| | 400 | Text empty or > 2000 chars | `{"detail": "validation error..."}` | | |
| | 429 | Rate limit hit | `{"detail": "Rate limit exceeded"}` | | |
| | 503 | Model still loading | `{"detail": "Model is still loading..."}` | | |
| | 500 | Unexpected error | `{"detail": "Inference failed..."}` | | |
| --- | |
| ### `POST /batch` | |
| Analyze up to 10 texts in a single efficient request. | |
| All texts are processed in one RoBERTa forward pass (padded batch). | |
| **Rate limit:** 10 requests per IP per minute (batch is more expensive) | |
| **Request body:** | |
| ```json | |
| { | |
| "inputs": [ | |
| "I loved this product!", | |
| "The service was average.", | |
| "Absolutely terrible experience." | |
| ] | |
| } | |
| ``` | |
| **Successful response (200):** | |
| ```json | |
| { | |
| "results": [ | |
| { | |
| "label": "Positive", | |
| "score": 0.971203, | |
| "all_scores": [ | |
| {"label": "Positive", "score": 0.971203}, | |
| {"label": "Neutral", "score": 0.022411}, | |
| {"label": "Negative", "score": 0.006386} | |
| ], | |
| "response_ms": 134 | |
| }, | |
| { | |
| "label": "Neutral", | |
| "score": 0.683441, | |
| "all_scores": [ | |
| {"label": "Neutral", "score": 0.683441}, | |
| {"label": "Positive", "score": 0.201233}, | |
| {"label": "Negative", "score": 0.115326} | |
| ], | |
| "response_ms": 134 | |
| }, | |
| { | |
| "label": "Negative", | |
| "score": 0.941872, | |
| "all_scores": [ | |
| {"label": "Negative", "score": 0.941872}, | |
| {"label": "Neutral", "score": 0.042311}, | |
| {"label": "Positive", "score": 0.015817} | |
| ], | |
| "response_ms": 134 | |
| } | |
| ], | |
| "batch_size": 3, | |
| "total_ms": 148 | |
| } | |
| ``` | |
| --- | |
| ## 🖥️ Code Examples | |
| ### JavaScript (Fetch API) | |
| ```javascript | |
| const API = "https://airzipm-sentimentai.hf.space"; | |
| // ── Single analysis ────────────────────────────────────────────────────────── | |
| async function analyze(text) { | |
| const response = await fetch(`${API}/analyze`, { | |
| method : "POST", | |
| headers: { "Content-Type": "application/json" }, | |
| body : JSON.stringify({ inputs: text }), | |
| }); | |
| if (!response.ok) { | |
| const err = await response.json(); | |
| throw new Error(err.detail || "Request failed"); | |
| } | |
| return response.json(); | |
| // → { label: "Positive", score: 0.973, all_scores: [...], response_ms: 87 } | |
| } | |
| // ── Batch analysis ─────────────────────────────────────────────────────────── | |
| async function analyzeBatch(texts) { | |
| const response = await fetch(`${API}/batch`, { | |
| method : "POST", | |
| headers: { "Content-Type": "application/json" }, | |
| body : JSON.stringify({ inputs: texts }), | |
| }); | |
| return response.json(); | |
| // → { results: [...], batch_size: 3, total_ms: 148 } | |
| } | |
| // ── Keep-alive ping (prevents HF Space from sleeping) ───────────────────── | |
| setInterval(async () => { | |
| const { model_ready } = await fetch(`${API}/ping`).then(r => r.json()); | |
| console.log("Model ready:", model_ready); | |
| }, 30_000); | |
| ``` | |
| ### Python (httpx) | |
| ```python | |
| import httpx | |
| API = "https://airzipm-sentimentai.hf.space" | |
| # Single text | |
| response = httpx.post(f"{API}/analyze", json={"inputs": "This is great!"}) | |
| result = response.json() | |
| print(result["label"], result["score"]) # → Positive 0.973 | |
| # Batch | |
| batch_resp = httpx.post(f"{API}/batch", json={ | |
| "inputs": ["Loved it!", "Meh.", "Terrible."] | |
| }) | |
| for r in batch_resp.json()["results"]: | |
| print(r["label"], r["score"]) | |
| ``` | |
| ### cURL | |
| ```bash | |
| # Single analysis | |
| curl -X POST "https://airzipm-sentimentai.hf.space/analyze" \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"inputs": "This product completely exceeded my expectations!"}' | |
| # Batch analysis | |
| curl -X POST "https://airzipm-sentimentai.hf.space/batch" \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"inputs": ["Amazing!", "It was okay.", "Terrible experience."]}' | |
| # Health check | |
| curl "https://airzipm-sentimentai.hf.space/health" | |
| # Ping | |
| curl "https://airzipm-sentimentai.hf.space/ping" | |
| ``` | |
| --- | |
| ## ⚡ Architecture & Concurrency | |
| ### How it handles multiple simultaneous users | |
| ``` | |
| User 1 → acquires semaphore slot 1 → running inference (~100ms) | |
| User 2 → acquires semaphore slot 2 → running inference | |
| User 3 → acquires semaphore slot 3 → running inference | |
| User 4 → acquires semaphore slot 4 → running inference | |
| User 5 → WAITS in asyncio queue (non-blocking — event loop stays free) | |
| User 6 → WAITS in asyncio queue | |
| ... | |
| User 20 → WAITS in asyncio queue | |
| When User 1 finishes: | |
| → releases slot | |
| → User 5 immediately acquires it and begins inference | |
| ``` | |
| **No requests are dropped or rejected.** The asyncio event loop stays free to | |
| accept new connections and serve `/ping` responses while inferences run. | |
| ### Component Breakdown | |
| | Component | Role | | |
| |-----------|------| | |
| | **FastAPI** | Async request routing, Pydantic validation | | |
| | **Gunicorn + 4 UvicornWorkers** | Multi-process concurrency (~100+ connections) | | |
| | **asyncio.Semaphore(4)** | Caps simultaneous inferences to prevent OOM | | |
| | **loop.run_in_executor** | Runs CPU-bound inference off the event loop | | |
| | **slowapi** | Per-IP rate limiting (in-memory, no Redis) | | |
| | **RoBERTa (loaded once)** | Weights in RAM at startup — never reloaded per request | | |
| ### Response Headers | |
| Every response includes: | |
| | Header | Value | Use | | |
| |--------|-------|-----| | |
| | `X-Response-Time` | `87ms` | Frontend displays this | | |
| | `X-Model-Ready` | `true` / `false` | Frontend status bar | | |
| | `Access-Control-Allow-Origin` | `*` | CORS — any frontend domain | | |
| --- | |
| ## 🔧 Local Development | |
| ```bash | |
| # Clone and install | |
| git clone https://huggingface.co/spaces/airzipm/sentimentai | |
| cd sentimentai | |
| pip install -r requirements.txt | |
| # Run locally (single worker, port 7860) | |
| python app.py | |
| # Or with gunicorn (production-like, 4 workers) | |
| gunicorn app:app \ | |
| --workers 4 \ | |
| --worker-class uvicorn.workers.UvicornWorker \ | |
| --bind 0.0.0.0:7860 \ | |
| --timeout 120 | |
| # Visit: http://localhost:7860 | |
| # Swagger: http://localhost:7860/docs | |
| ``` | |
| --- | |
| ## ⚠️ Cold Start Note | |
| This Space runs on the **free tier**, which means: | |
| - The Space **sleeps** after ~5 minutes of inactivity | |
| - The first request after sleeping triggers a **cold start** (20–50 seconds) | |
| - The model is downloaded (~500MB) and loaded into RAM on first start | |
| - The frontend handles this gracefully with a "warming up" status bar | |
| --- | |
| ## 📄 License | |
| Apache 2.0 — see [LICENSE](LICENSE) | |
| Model: [airzipm/sentiment-analysis-roberta](https://huggingface.co/airzipm/sentiment-analysis-roberta) | |
| --- | |
| <!-- | |
| OPTION A — Gradio SDK wrapper (simpler, no Dockerfile needed) | |
| If you prefer not to use Docker, you can wrap FastAPI with Gradio: | |
| README frontmatter: | |
| sdk: gradio | |
| sdk_version: "4.36.1" | |
| Add to requirements.txt: | |
| gradio==4.36.1 | |
| Add to bottom of app.py (before uvicorn.run): | |
| import gradio as gr | |
| gr_app = gr.Blocks(title="SentimentAI") | |
| with gr_app: | |
| gr.HTML(""" | |
| <h2>🎭 SentimentAI API</h2> | |
| <p>REST API is running. Visit <a href="/docs">/docs</a> for Swagger UI | |
| or use the <a href="/">frontend</a>.</p> | |
| """) | |
| app = gr.mount_gradio_app(app, gr_app, path="/ui") | |
| Tradeoff: Option A is simpler but has Gradio overhead. | |
| Option B (Dockerfile, used above) is cleaner and production-grade. | |
| --> |