AI Video Generation Implementation
This commit is contained in:
ajaysi
@@ -5,10 +5,38 @@ ALwrity's Assistive Writing feature revolutionizes content creation by providing
|
||||
## Visuals
|
||||
|
||||
<p align="center">
|
||||
<img src="../../assets/assistive-1.png" alt="Assistive writing selection tools" width="45%">
|
||||
<img src="../../assets/assistive-2.png" alt="Inline fact checking and quick edits" width="45%">
|
||||
<img src="../../assests/assistive-1.png" alt="Assistive writing selection tools" width="45%">
|
||||
<img src="../../assests/assistive-2.png" alt="Inline fact checking and quick edits" width="45%">
|
||||
</p>
|
||||
|
||||
## Quick Reference
|
||||
|
||||
1. Enable: Toggle “Assistive Writing” in the LinkedIn Writer header
|
||||
2. Write: Type at least 5 words
|
||||
3. Wait: 5 seconds for the first automatic suggestion
|
||||
4. Accept/Dismiss: Use buttons in the suggestion card
|
||||
|
||||
### How It Works
|
||||
- First suggestion: Automatic (5 words + 5 seconds)
|
||||
- More suggestions: Click “Continue writing”
|
||||
- Daily limit: 50 suggestions (resets every 24 hours)
|
||||
|
||||
### Best Practices
|
||||
- Write specific, clear content
|
||||
- Review source links before accepting
|
||||
- Use manual “Continue writing” for additional suggestions
|
||||
- Don’t expect suggestions for very short text
|
||||
- Don’t ignore source verification
|
||||
|
||||
### Common Issues (Quick Table)
|
||||
|
||||
| Problem | Solution |
|
||||
| --- | --- |
|
||||
| No suggestions | Write 5+ words, then wait 5 seconds |
|
||||
| “API quota exceeded” | Wait 24 hours or upgrade plan |
|
||||
| “No relevant sources” | Be more specific in your writing |
|
||||
| Suggestions not relevant | Try different wording or topics |
|
||||
|
||||
## What is Assistive Writing?
|
||||
|
||||
Assistive Writing is an AI-powered feature that provides real-time writing assistance, suggestions, and enhancements to help you create compelling content. It combines advanced natural language processing with contextual understanding to offer intelligent recommendations that improve your writing quality and efficiency.
|
||||
@@ -160,6 +188,67 @@ Assistive Writing is an AI-powered feature that provides real-time writing assis
|
||||
- **Message Alignment**: Align with brand messaging
|
||||
- **Value Integration**: Incorporate brand values
|
||||
|
||||
## Workflow
|
||||
|
||||
```text
|
||||
1. ENABLE ASSISTIVE WRITING
|
||||
┌─────────────────────────┐
|
||||
│ Toggle "Assistive │
|
||||
│ Writing" ON (blue) │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
▼
|
||||
|
||||
2. START WRITING
|
||||
┌─────────────────────────┐
|
||||
│ Type at least 5 words │
|
||||
│ in the text area │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
▼
|
||||
|
||||
3. WAIT FOR AI ANALYSIS
|
||||
┌─────────────────────────┐
|
||||
│ Wait 5 seconds │
|
||||
│ AI analyzes your text │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
▼
|
||||
|
||||
4. RECEIVE FIRST SUGGESTION
|
||||
┌─────────────────────────┐
|
||||
│ Suggestion card appears │
|
||||
│ near your cursor │
|
||||
│ │
|
||||
│ [Accept] [Dismiss] │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
▼
|
||||
|
||||
5. AFTER FIRST SUGGESTION
|
||||
┌─────────────────────────┐
|
||||
│ "Continue writing" │
|
||||
│ prompt appears │
|
||||
│ │
|
||||
│ [Continue writing] │
|
||||
│ [Dismiss] │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
▼
|
||||
|
||||
6. MANUAL SUGGESTIONS
|
||||
┌─────────────────────────┐
|
||||
│ Click "Continue writing"│
|
||||
│ to get more suggestions │
|
||||
│ (saves costs) │
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
### Step-by-Step
|
||||
- Enable → Start writing (5+ words) → Wait 5s
|
||||
- First suggestion shows: suggested text, confidence score, source links, Accept/Dismiss
|
||||
- After first suggestion, trigger more via “Continue writing”
|
||||
|
||||
## Integration with Other Features
|
||||
|
||||
### Blog Writer Integration
|
||||
|
||||
@@ -5,13 +5,47 @@ ALwrity's Grounding UI feature provides AI-powered content verification and fact
|
||||
## Visuals
|
||||
|
||||
<p align="center">
|
||||
<img src="../../assets/assistive-2.png" alt="Inline fact checking with citations and claim statuses" width="60%">
|
||||
<img src="../../assests/assistive-2.png" alt="Inline fact checking with citations and claim statuses" width="60%">
|
||||
</p>
|
||||
|
||||
## What is Grounding UI?
|
||||
|
||||
Grounding UI is an intelligent content verification system that connects AI-generated content with real-world data sources, ensuring accuracy and reliability. It provides visual indicators, source citations, and verification status to help you create trustworthy, fact-checked content.
|
||||
|
||||
## Implementation Overview (Concise)
|
||||
|
||||
- Backend service: `backend/services/hallucination_detector.py` (claim extraction → evidence search → verification)
|
||||
- Models: `backend/models/hallucination_models.py`
|
||||
- API router: `backend/api/hallucination_detector.py` (registered in `backend/app.py`)
|
||||
- Frontend service: `frontend/src/services/hallucinationDetectorService.ts`
|
||||
- UI: LinkedIn Writer selection menu + FactCheckResults modal
|
||||
|
||||
### API Endpoints (Summary)
|
||||
- `POST /api/hallucination-detector/detect` – main fact-checking
|
||||
- `POST /api/hallucination-detector/extract-claims` – claims only
|
||||
- `POST /api/hallucination-detector/verify-claim` – single claim
|
||||
- `GET /api/hallucination-detector/health` – health check
|
||||
|
||||
### Minimal Setup
|
||||
- Backend env:
|
||||
- `EXA_API_KEY=...` (evidence search)
|
||||
- `OPENAI_API_KEY=...` (claim extraction + verification)
|
||||
- Frontend env:
|
||||
- `REACT_APP_API_URL=http://localhost:8000`
|
||||
|
||||
### Quick Usage (UI)
|
||||
1) In LinkedIn Writer, select a passage (10+ chars)
|
||||
2) Click “Check Facts” in the selection menu
|
||||
3) Review claims, assessments (supported/refuted/insufficient), confidence, and sources in the results modal
|
||||
|
||||
### Quick Usage (API)
|
||||
|
||||
```bash
|
||||
curl -X POST "$API_URL/api/hallucination-detector/detect" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"text":"The Eiffel Tower is in Paris and built in 1889.","include_sources":true,"max_claims":5}'
|
||||
```
|
||||
|
||||
### Key Benefits
|
||||
|
||||
- **Content Verification**: Verify facts and claims in real-time
|
||||
@@ -274,6 +308,11 @@ Grounding UI is an intelligent content verification system that connects AI-gene
|
||||
- **Display Problems**: Fix visual indicator issues
|
||||
- **Integration Errors**: Resolve integration problems
|
||||
|
||||
### Environment & Health
|
||||
- “EXA_API_KEY not found” → add key to backend `.env`, restart server
|
||||
- “OpenAI API key not found” → add `OPENAI_API_KEY`, verify credits
|
||||
- Health check: `GET /api/hallucination-detector/health`
|
||||
|
||||
### Getting Help
|
||||
|
||||
#### Support Resources
|
||||
|
||||
58
docs-site/docs/features/integrations/wix/api.md
Normal file
58
docs-site/docs/features/integrations/wix/api.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# API (Summary)
|
||||
|
||||
Short reference of Wix integration endpoints exposed by ALwrity’s backend.
|
||||
|
||||
## Authentication
|
||||
### Get Authorization URL
|
||||
```http
|
||||
GET /api/wix/auth/url?state=optional_state
|
||||
```
|
||||
|
||||
### OAuth Callback
|
||||
```http
|
||||
POST /api/wix/auth/callback
|
||||
Content-Type: application/json
|
||||
{
|
||||
"code": "authorization_code",
|
||||
"state": "optional_state"
|
||||
}
|
||||
```
|
||||
|
||||
## Connection
|
||||
### Status
|
||||
```http
|
||||
GET /api/wix/connection/status
|
||||
```
|
||||
|
||||
### Disconnect
|
||||
```http
|
||||
POST /api/wix/disconnect
|
||||
```
|
||||
|
||||
## Publishing
|
||||
### Publish blog post
|
||||
```http
|
||||
POST /api/wix/publish
|
||||
Content-Type: application/json
|
||||
{
|
||||
"title": "Blog Post Title",
|
||||
"content": "Markdown",
|
||||
"cover_image_url": "https://example.com/image.jpg",
|
||||
"category_ids": ["category_id"],
|
||||
"tag_ids": ["tag_id_1", "tag_id_2"],
|
||||
"publish": true
|
||||
}
|
||||
```
|
||||
|
||||
## Content Management
|
||||
### Categories
|
||||
```http
|
||||
GET /api/wix/categories
|
||||
```
|
||||
|
||||
### Tags
|
||||
```http
|
||||
GET /api/wix/tags
|
||||
```
|
||||
|
||||
|
||||
33
docs-site/docs/features/integrations/wix/overview.md
Normal file
33
docs-site/docs/features/integrations/wix/overview.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Wix Integration (Overview)
|
||||
|
||||
ALwrity’s Wix integration lets you publish AI‑generated blogs directly to your Wix site, including categories/tags and SEO metadata.
|
||||
|
||||
## What’s Included
|
||||
- OAuth connection (Headless OAuth – Client ID only)
|
||||
- Markdown → Wix Ricos JSON conversion
|
||||
- Image import to Wix Media Manager
|
||||
- Blog creation and publish (draft or published)
|
||||
- Categories/tags lookup + auto-create
|
||||
- SEO metadata posting (keywords, meta, OG, Twitter, canonical)
|
||||
|
||||
## High-level Flow
|
||||
1. Connect your Wix account (OAuth)
|
||||
2. Convert blog content to Ricos JSON
|
||||
3. Import images
|
||||
4. Create blog post
|
||||
5. Publish and return URL
|
||||
|
||||
## Benefits
|
||||
- One-click publishing from ALwrity
|
||||
- Preserves formatting and images
|
||||
- Posts complete SEO metadata
|
||||
- Clear error handling and feedback
|
||||
|
||||
See also:
|
||||
- Setup: setup.md
|
||||
- Publishing: publishing.md
|
||||
- API: api.md
|
||||
- SEO Metadata: seo-metadata.md
|
||||
- Testing (Bypass): testing-bypass.md
|
||||
|
||||
|
||||
28
docs-site/docs/features/integrations/wix/publishing.md
Normal file
28
docs-site/docs/features/integrations/wix/publishing.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# Publishing Flow
|
||||
|
||||
End‑to‑end flow for publishing a blog post to Wix.
|
||||
|
||||
## Steps
|
||||
1. Check connection (tokens + `memberId`)
|
||||
2. Convert markdown → Ricos JSON
|
||||
3. Import images to Wix Media Manager
|
||||
4. Create blog post via Wix Blog API
|
||||
5. Publish (or save draft)
|
||||
6. Return URL
|
||||
|
||||
## From the Blog Writer
|
||||
- Generate content in ALwrity
|
||||
- Use “Publish to Wix” action
|
||||
- The publisher will:
|
||||
- Verify connection
|
||||
- Convert content
|
||||
- Import images
|
||||
- Create & publish
|
||||
- Return published URL
|
||||
|
||||
## Notes
|
||||
- Categories and tags are looked up/created automatically
|
||||
- SEO metadata is posted with the blog (see SEO Metadata)
|
||||
- Errors are reported with actionable messages
|
||||
|
||||
|
||||
52
docs-site/docs/features/integrations/wix/seo-metadata.md
Normal file
52
docs-site/docs/features/integrations/wix/seo-metadata.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# SEO Metadata (Wix)
|
||||
|
||||
This page summarizes what ALwrity posts to Wix and what remains out of scope.
|
||||
|
||||
## Posted to Wix
|
||||
- Keywords (seoData.settings.keywords)
|
||||
- Main keyword: `focus_keyword` → `isMain: true`
|
||||
- Additional: `blog_tags`, `social_hashtags` → `isMain: false`
|
||||
- Meta Tags (seoData.tags)
|
||||
- `<meta name="description">` from `meta_description`
|
||||
- `<meta name="title">` from `seo_title`
|
||||
- Open Graph (seoData.tags)
|
||||
- `og:title`, `og:description`, `og:image`, `og:type=article`, `og:url`
|
||||
- Twitter Card (seoData.tags)
|
||||
- `twitter:title`, `twitter:description`, `twitter:image`, `twitter:card`
|
||||
- Canonical URL (seoData.tags)
|
||||
- `<link rel="canonical">`
|
||||
- Categories & Tags
|
||||
- Auto‑lookup/create and post as `categoryIds` and `tagIds`
|
||||
|
||||
## Not Posted (Limitations)
|
||||
- JSON‑LD structured data
|
||||
- Reason: Requires Wix site frontend (`@wix/site-seo`)
|
||||
- URL slug customization
|
||||
- Wix auto‑generates from title
|
||||
- Reading time / optimization score
|
||||
- Internal metadata, not part of Wix post
|
||||
|
||||
## Conversion
|
||||
- Markdown → Ricos JSON via official API (with custom parser fallback)
|
||||
- Supports headings, paragraphs, lists, images, basic formatting
|
||||
|
||||
## Example (structure excerpt)
|
||||
```json
|
||||
{
|
||||
"draftPost": {
|
||||
"title": "SEO optimized title",
|
||||
"memberId": "author-member-id",
|
||||
"richContent": { /* Ricos JSON */ },
|
||||
"excerpt": "First 200 chars...",
|
||||
"categoryIds": ["uuid1"],
|
||||
"tagIds": ["uuid1","uuid2"],
|
||||
"seoData": {
|
||||
"settings": { "keywords": [ { "term": "main", "isMain": true } ] },
|
||||
"tags": [ { "type": "meta", "props": { "name": "description", "content": "..." } } ]
|
||||
}
|
||||
},
|
||||
"publish": true
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
40
docs-site/docs/features/integrations/wix/setup.md
Normal file
40
docs-site/docs/features/integrations/wix/setup.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Wix Integration Setup
|
||||
|
||||
## Wix App Configuration
|
||||
1. Go to Wix Developers and create an app
|
||||
2. Set redirect URI: `http://localhost:3000/wix/callback` (dev)
|
||||
3. Scopes: `BLOG.CREATE-DRAFT`, `BLOG.PUBLISH`, `MEDIA.MANAGE`
|
||||
4. Note your Client ID (Headless OAuth uses Client ID only)
|
||||
|
||||
## Environment
|
||||
```bash
|
||||
# .env
|
||||
WIX_CLIENT_ID=your_wix_client_id_here
|
||||
WIX_REDIRECT_URI=http://localhost:3000/wix/callback
|
||||
```
|
||||
|
||||
## Database (tokens)
|
||||
Store tokens per user:
|
||||
```sql
|
||||
CREATE TABLE wix_tokens (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
user_id TEXT NOT NULL,
|
||||
access_token TEXT NOT NULL,
|
||||
refresh_token TEXT,
|
||||
expires_at TIMESTAMP,
|
||||
member_id TEXT,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
## Third‑Party App Requirement
|
||||
`memberId` is mandatory for third‑party blog creation. The OAuth flow retrieves and stores it and it is used when creating posts.
|
||||
|
||||
## Key Files
|
||||
- Backend service: `backend/services/wix_service.py`
|
||||
- API routes: `backend/api/wix_routes.py`
|
||||
- Test page: `frontend/src/components/WixTestPage/WixTestPage.tsx`
|
||||
- Blog publisher: `frontend/src/components/BlogWriter/Publisher.tsx`
|
||||
|
||||
|
||||
34
docs-site/docs/features/integrations/wix/testing-bypass.md
Normal file
34
docs-site/docs/features/integrations/wix/testing-bypass.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Testing (Bypass Guide)
|
||||
|
||||
Local testing options to exercise Wix integration without onboarding blockers.
|
||||
|
||||
## Routes
|
||||
| Option | URL | Purpose |
|
||||
| --- | --- | --- |
|
||||
| Primary | `http://localhost:3000/wix-test` | Main Wix test page |
|
||||
| Backup | `http://localhost:3000/wix-test-direct` | Direct route (no protections) |
|
||||
| Backend | `http://localhost:8000/api/wix/auth/url` | Direct API testing |
|
||||
|
||||
## How to Test
|
||||
1. Start backend: `python start_alwrity_backend.py`
|
||||
2. Start frontend: `npm start`
|
||||
3. Navigate to `/wix-test`, connect account, publish a test post
|
||||
|
||||
## Env (backend)
|
||||
```bash
|
||||
WIX_CLIENT_ID=your_wix_client_id_here
|
||||
WIX_REDIRECT_URI=http://localhost:3000/wix/callback
|
||||
```
|
||||
|
||||
## Restore After Testing
|
||||
- Re‑enable monitoring middleware in `backend/app.py` if disabled
|
||||
- Remove any temporary onboarding mocks
|
||||
- Restore `ProtectedRoute` for `/wix-test` if removed
|
||||
|
||||
## Expected Results
|
||||
- No onboarding redirect
|
||||
- Wix OAuth works
|
||||
- Blog posting works
|
||||
- No rate‑limit errors
|
||||
|
||||
|
||||
445
docs-site/docs/features/subscription/api-reference.md
Normal file
445
docs-site/docs/features/subscription/api-reference.md
Normal file
@@ -0,0 +1,445 @@
|
||||
# Subscription API Reference
|
||||
|
||||
Complete API endpoint documentation for the ALwrity subscription system.
|
||||
|
||||
## Base URL
|
||||
|
||||
All endpoints are prefixed with `/api/subscription`
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require user authentication. Include the user ID in the request path or headers as appropriate.
|
||||
|
||||
## Subscription Management Endpoints
|
||||
|
||||
### Get All Subscription Plans
|
||||
|
||||
Get a list of all available subscription plans.
|
||||
|
||||
```http
|
||||
GET /api/subscription/plans
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Free",
|
||||
"price": 0.0,
|
||||
"billing_cycle": "monthly",
|
||||
"limits": {
|
||||
"gemini_calls": 100,
|
||||
"tokens": 100000
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"name": "Basic",
|
||||
"price": 29.0,
|
||||
"billing_cycle": "monthly",
|
||||
"limits": {
|
||||
"gemini_calls": 1000,
|
||||
"openai_calls": 500,
|
||||
"tokens": 1500000,
|
||||
"monthly_cost": 50.0
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Get User Subscription
|
||||
|
||||
Get the current subscription details for a specific user.
|
||||
|
||||
```http
|
||||
GET /api/subscription/user/{user_id}/subscription
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `user_id` (path): The user's unique identifier
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"user_id": "user123",
|
||||
"plan_name": "Pro",
|
||||
"plan_id": 3,
|
||||
"status": "active",
|
||||
"started_at": "2025-01-01T00:00:00Z",
|
||||
"expires_at": "2025-02-01T00:00:00Z",
|
||||
"limits": {
|
||||
"gemini_calls": 5000,
|
||||
"openai_calls": 2500,
|
||||
"monthly_cost": 150.0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get API Pricing Information
|
||||
|
||||
Get current pricing configuration for all API providers.
|
||||
|
||||
```http
|
||||
GET /api/subscription/pricing
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"provider": "gemini",
|
||||
"model": "gemini-2.5-flash",
|
||||
"input_cost_per_1m": 0.125,
|
||||
"output_cost_per_1m": 0.375
|
||||
},
|
||||
{
|
||||
"provider": "tavily",
|
||||
"cost_per_request": 0.001
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Tracking Endpoints
|
||||
|
||||
### Get Current Usage Statistics
|
||||
|
||||
Get current usage statistics for a user.
|
||||
|
||||
```http
|
||||
GET /api/subscription/usage/{user_id}
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `user_id` (path): The user's unique identifier
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"billing_period": "2025-01",
|
||||
"total_calls": 1250,
|
||||
"total_tokens": 210000,
|
||||
"total_cost": 15.75,
|
||||
"usage_status": "active",
|
||||
"limits": {
|
||||
"gemini_calls": 5000,
|
||||
"monthly_cost": 150.0
|
||||
},
|
||||
"provider_breakdown": {
|
||||
"gemini": {
|
||||
"calls": 800,
|
||||
"tokens": 125000,
|
||||
"cost": 10.50
|
||||
},
|
||||
"openai": {
|
||||
"calls": 450,
|
||||
"tokens": 85000,
|
||||
"cost": 5.25
|
||||
}
|
||||
},
|
||||
"usage_percentages": {
|
||||
"gemini_calls": 16.0,
|
||||
"cost": 10.5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Usage Trends
|
||||
|
||||
Get historical usage trends over time.
|
||||
|
||||
```http
|
||||
GET /api/subscription/usage/{user_id}/trends?months=6
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `user_id` (path): The user's unique identifier
|
||||
- `months` (query, optional): Number of months to retrieve (default: 6)
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"periods": [
|
||||
{
|
||||
"period": "2024-07",
|
||||
"total_calls": 850,
|
||||
"total_cost": 12.50,
|
||||
"provider_breakdown": {
|
||||
"gemini": {"calls": 600, "cost": 8.00},
|
||||
"openai": {"calls": 250, "cost": 4.50}
|
||||
}
|
||||
}
|
||||
],
|
||||
"trends": {
|
||||
"calls_trend": "increasing",
|
||||
"cost_trend": "stable"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Dashboard Data
|
||||
|
||||
Get comprehensive dashboard data including usage, limits, projections, and alerts.
|
||||
|
||||
```http
|
||||
GET /api/subscription/dashboard/{user_id}
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `user_id` (path): The user's unique identifier
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"summary": {
|
||||
"total_api_calls_this_month": 1250,
|
||||
"total_cost_this_month": 15.75,
|
||||
"usage_status": "active",
|
||||
"unread_alerts": 2
|
||||
},
|
||||
"current_usage": {
|
||||
"billing_period": "2025-01",
|
||||
"total_calls": 1250,
|
||||
"total_cost": 15.75,
|
||||
"usage_status": "active",
|
||||
"provider_breakdown": {
|
||||
"gemini": {"calls": 800, "cost": 10.50, "tokens": 125000},
|
||||
"openai": {"calls": 450, "cost": 5.25, "tokens": 85000}
|
||||
},
|
||||
"usage_percentages": {
|
||||
"gemini_calls": 16.0,
|
||||
"openai_calls": 18.0,
|
||||
"cost": 10.5
|
||||
}
|
||||
},
|
||||
"limits": {
|
||||
"plan_name": "Pro",
|
||||
"limits": {
|
||||
"gemini_calls": 5000,
|
||||
"openai_calls": 2500,
|
||||
"monthly_cost": 150.0
|
||||
}
|
||||
},
|
||||
"projections": {
|
||||
"projected_monthly_cost": 47.25,
|
||||
"projected_usage_percentage": 31.5
|
||||
},
|
||||
"alerts": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "API Usage Notice - Gemini",
|
||||
"message": "You have used 800 of 5,000 Gemini API calls",
|
||||
"severity": "info",
|
||||
"created_at": "2025-01-15T10:30:00Z",
|
||||
"read": false
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Alerts & Notifications Endpoints
|
||||
|
||||
### Get Usage Alerts
|
||||
|
||||
Get usage alerts and notifications for a user.
|
||||
|
||||
```http
|
||||
GET /api/subscription/alerts/{user_id}?unread_only=false
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `user_id` (path): The user's unique identifier
|
||||
- `unread_only` (query, optional): Filter to only unread alerts (default: false)
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"user_id": "user123",
|
||||
"title": "API Usage Notice - Gemini",
|
||||
"message": "You have used 800 of 5,000 Gemini API calls",
|
||||
"severity": "info",
|
||||
"alert_type": "usage_threshold",
|
||||
"created_at": "2025-01-15T10:30:00Z",
|
||||
"read": false
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"user_id": "user123",
|
||||
"title": "Usage Warning",
|
||||
"message": "You have reached 90% of your monthly cost limit",
|
||||
"severity": "warning",
|
||||
"alert_type": "cost_threshold",
|
||||
"created_at": "2025-01-20T14:15:00Z",
|
||||
"read": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Mark Alert as Read
|
||||
|
||||
Mark a specific alert as read.
|
||||
|
||||
```http
|
||||
POST /api/subscription/alerts/{alert_id}/mark-read
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `alert_id` (path): The alert's unique identifier
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Alert marked as read"
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Get User Usage (cURL)
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:8000/api/subscription/usage/user123" \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
### Get Dashboard Data (cURL)
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:8000/api/subscription/dashboard/user123" \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
### Get Usage Trends (cURL)
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:8000/api/subscription/usage/user123/trends?months=6" \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
### JavaScript Example
|
||||
|
||||
```javascript
|
||||
// Get comprehensive usage data
|
||||
const response = await fetch(`/api/subscription/dashboard/${userId}`);
|
||||
const data = await response.json();
|
||||
|
||||
console.log(data.data.summary);
|
||||
// {
|
||||
// total_api_calls_this_month: 1250,
|
||||
// total_cost_this_month: 15.75,
|
||||
// usage_status: "active",
|
||||
// unread_alerts: 2
|
||||
// }
|
||||
|
||||
// Get current usage percentages
|
||||
const usage = data.data.current_usage;
|
||||
console.log(usage.usage_percentages);
|
||||
// {
|
||||
// gemini_calls: 16.0,
|
||||
// openai_calls: 18.0,
|
||||
// cost: 10.5
|
||||
// }
|
||||
```
|
||||
|
||||
### Python Example
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
# Get user usage statistics
|
||||
response = requests.get(
|
||||
f"http://localhost:8000/api/subscription/usage/{user_id}",
|
||||
headers={"Content-Type": "application/json"}
|
||||
)
|
||||
|
||||
data = response.json()
|
||||
usage = data["data"]
|
||||
|
||||
print(f"Total calls: {usage['total_calls']}")
|
||||
print(f"Total cost: ${usage['total_cost']}")
|
||||
print(f"Status: {usage['usage_status']}")
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints return consistent error responses:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "error_type",
|
||||
"message": "Human-readable error message",
|
||||
"details": "Additional error details",
|
||||
"user_id": "user123",
|
||||
"timestamp": "2025-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Common Error Codes
|
||||
|
||||
- `400 Bad Request`: Invalid request parameters
|
||||
- `401 Unauthorized`: Authentication required
|
||||
- `404 Not Found`: Resource not found
|
||||
- `429 Too Many Requests`: Usage limit exceeded
|
||||
- `500 Internal Server Error`: Server error
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
Usage limits are enforced automatically. When a limit is exceeded, the API returns a `429 Too Many Requests` response:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "UsageLimitExceededException",
|
||||
"message": "Usage limit exceeded for Gemini API calls",
|
||||
"details": {
|
||||
"provider": "gemini",
|
||||
"limit_type": "api_calls",
|
||||
"current_usage": 1000,
|
||||
"limit_value": 1000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Overview](overview.md) - System architecture and features
|
||||
- [Setup](setup.md) - Installation and configuration
|
||||
- [Pricing](pricing.md) - Subscription plans and API pricing
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: January 2025
|
||||
|
||||
339
docs-site/docs/features/subscription/frontend-integration.md
Normal file
339
docs-site/docs/features/subscription/frontend-integration.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# Frontend Integration Guide
|
||||
|
||||
Technical specifications and integration guide for implementing the billing dashboard in the ALwrity frontend.
|
||||
|
||||
## Overview
|
||||
|
||||
The billing dashboard provides enterprise-grade insights and cost transparency for all external API usage. It integrates with the subscription system's backend APIs to display real-time usage, costs, and system health.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Main Dashboard Integration Points
|
||||
|
||||
```
|
||||
Main Dashboard
|
||||
├── Header Section
|
||||
│ ├── System Health Indicator
|
||||
│ ├── Real-time Usage Summary
|
||||
│ └── Alert Notifications
|
||||
├── Billing Overview Section
|
||||
│ ├── Current Usage vs Limits
|
||||
│ ├── Cost Breakdown by Provider
|
||||
│ └── Monthly Projections
|
||||
├── API Monitoring Section
|
||||
│ ├── External API Performance
|
||||
│ ├── Cost per API Call
|
||||
│ └── Usage Trends
|
||||
└── Subscription Management
|
||||
├── Plan Comparison
|
||||
├── Usage Optimization Tips
|
||||
└── Upgrade/Downgrade Options
|
||||
```
|
||||
|
||||
## Service Layer
|
||||
|
||||
### Billing Service (`frontend/src/services/billingService.ts`)
|
||||
|
||||
Core functions to implement:
|
||||
|
||||
```typescript
|
||||
export const billingService = {
|
||||
// Get comprehensive dashboard data
|
||||
getDashboardData: (userId: string) => Promise<DashboardData>
|
||||
|
||||
// Get current usage statistics
|
||||
getUsageStats: (userId: string, period?: string) => Promise<UsageStats>
|
||||
|
||||
// Get usage trends over time
|
||||
getUsageTrends: (userId: string, months?: number) => Promise<UsageTrends>
|
||||
|
||||
// Get subscription plans
|
||||
getSubscriptionPlans: () => Promise<SubscriptionPlan[]>
|
||||
|
||||
// Get API pricing information
|
||||
getAPIPricing: (provider?: string) => Promise<APIPricing[]>
|
||||
|
||||
// Get usage alerts
|
||||
getUsageAlerts: (userId: string, unreadOnly?: boolean) => Promise<UsageAlert[]>
|
||||
|
||||
// Mark alert as read
|
||||
markAlertRead: (alertId: number) => Promise<void>
|
||||
}
|
||||
```
|
||||
|
||||
### Monitoring Service (`frontend/src/services/monitoringService.ts`)
|
||||
|
||||
Core functions to implement:
|
||||
|
||||
```typescript
|
||||
export const monitoringService = {
|
||||
// Get system health status
|
||||
getSystemHealth: () => Promise<SystemHealth>
|
||||
|
||||
// Get API performance statistics
|
||||
getAPIStats: (minutes?: number) => Promise<APIStats>
|
||||
|
||||
// Get lightweight monitoring stats
|
||||
getLightweightStats: () => Promise<LightweightStats>
|
||||
|
||||
// Get cache performance metrics
|
||||
getCacheStats: () => Promise<CacheStats>
|
||||
}
|
||||
```
|
||||
|
||||
## Type Definitions
|
||||
|
||||
### Core Data Structures (`frontend/src/types/billing.ts`)
|
||||
|
||||
```typescript
|
||||
interface DashboardData {
|
||||
current_usage: UsageStats
|
||||
trends: UsageTrends
|
||||
limits: SubscriptionLimits
|
||||
alerts: UsageAlert[]
|
||||
projections: CostProjections
|
||||
summary: UsageSummary
|
||||
}
|
||||
|
||||
interface UsageStats {
|
||||
billing_period: string
|
||||
usage_status: 'active' | 'warning' | 'limit_reached'
|
||||
total_calls: number
|
||||
total_tokens: number
|
||||
total_cost: number
|
||||
avg_response_time: number
|
||||
error_rate: number
|
||||
limits: SubscriptionLimits
|
||||
provider_breakdown: ProviderBreakdown
|
||||
alerts: UsageAlert[]
|
||||
usage_percentages: UsagePercentages
|
||||
last_updated: string
|
||||
}
|
||||
|
||||
interface ProviderBreakdown {
|
||||
gemini: ProviderUsage
|
||||
openai: ProviderUsage
|
||||
anthropic: ProviderUsage
|
||||
mistral: ProviderUsage
|
||||
tavily: ProviderUsage
|
||||
serper: ProviderUsage
|
||||
metaphor: ProviderUsage
|
||||
firecrawl: ProviderUsage
|
||||
stability: ProviderUsage
|
||||
}
|
||||
|
||||
interface ProviderUsage {
|
||||
calls: number
|
||||
tokens: number
|
||||
cost: number
|
||||
}
|
||||
```
|
||||
|
||||
## Component Architecture
|
||||
|
||||
### BillingOverview Component
|
||||
|
||||
**File**: `frontend/src/components/billing/BillingOverview.tsx`
|
||||
|
||||
**Key Features**:
|
||||
- Real-time usage display with animated counters
|
||||
- Progress bars for usage limits
|
||||
- Cost breakdown with interactive tooltips
|
||||
- Quick action buttons for plan management
|
||||
|
||||
**State Management**:
|
||||
```typescript
|
||||
const [usageData, setUsageData] = useState<UsageStats | null>(null)
|
||||
const [loading, setLoading] = useState(true)
|
||||
const [error, setError] = useState<string | null>(null)
|
||||
```
|
||||
|
||||
### CostBreakdown Component
|
||||
|
||||
**File**: `frontend/src/components/billing/CostBreakdown.tsx`
|
||||
|
||||
**Key Features**:
|
||||
- Interactive pie chart with provider breakdown
|
||||
- Hover effects showing detailed costs
|
||||
- Click to drill down into provider details
|
||||
- Cost per token calculations
|
||||
|
||||
### UsageTrends Component
|
||||
|
||||
**File**: `frontend/src/components/billing/UsageTrends.tsx`
|
||||
|
||||
**Key Features**:
|
||||
- Multi-line chart showing usage over time
|
||||
- Toggle between cost, calls, and tokens
|
||||
- Trend analysis with projections
|
||||
- Peak usage identification
|
||||
|
||||
### SystemHealthIndicator Component
|
||||
|
||||
**File**: `frontend/src/components/monitoring/SystemHealthIndicator.tsx`
|
||||
|
||||
**Key Features**:
|
||||
- Color-coded health status
|
||||
- Real-time performance metrics
|
||||
- Error rate monitoring
|
||||
- Response time tracking
|
||||
|
||||
## Design System
|
||||
|
||||
### Color Palette
|
||||
|
||||
```typescript
|
||||
const colors = {
|
||||
primary: {
|
||||
50: '#eff6ff',
|
||||
500: '#3b82f6',
|
||||
900: '#1e3a8a'
|
||||
},
|
||||
success: {
|
||||
50: '#f0fdf4',
|
||||
500: '#22c55e',
|
||||
900: '#14532d'
|
||||
},
|
||||
warning: {
|
||||
50: '#fffbeb',
|
||||
500: '#f59e0b',
|
||||
900: '#78350f'
|
||||
},
|
||||
danger: {
|
||||
50: '#fef2f2',
|
||||
500: '#ef4444',
|
||||
900: '#7f1d1d'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Responsive Design
|
||||
|
||||
**Breakpoints**:
|
||||
- Mobile: `640px`
|
||||
- Tablet: `768px`
|
||||
- Desktop: `1024px`
|
||||
- Large: `1280px`
|
||||
|
||||
## Real-Time Updates
|
||||
|
||||
### Polling Strategy
|
||||
|
||||
Intelligent polling based on user activity:
|
||||
|
||||
```typescript
|
||||
const useIntelligentPolling = (userId: string) => {
|
||||
const [isActive, setIsActive] = useState(true)
|
||||
|
||||
useEffect(() => {
|
||||
const interval = setInterval(() => {
|
||||
if (isActive) {
|
||||
fetchUsageData(userId)
|
||||
}
|
||||
}, isActive ? 30000 : 300000) // 30s when active, 5m when inactive
|
||||
|
||||
return () => clearInterval(interval)
|
||||
}, [isActive, userId])
|
||||
}
|
||||
```
|
||||
|
||||
## Chart Configuration
|
||||
|
||||
### Recharts Theme
|
||||
|
||||
```typescript
|
||||
const chartTheme = {
|
||||
colors: ['#3b82f6', '#22c55e', '#f59e0b', '#ef4444', '#8b5cf6'],
|
||||
grid: {
|
||||
stroke: '#e5e7eb',
|
||||
strokeWidth: 1,
|
||||
strokeDasharray: '3 3'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security Implementation
|
||||
|
||||
### API Security
|
||||
|
||||
Secure API calls with authentication:
|
||||
|
||||
```typescript
|
||||
const secureApiCall = async (endpoint: string, options: RequestInit = {}) => {
|
||||
const token = await getAuthToken()
|
||||
|
||||
return fetch(endpoint, {
|
||||
...options,
|
||||
headers: {
|
||||
...options.headers,
|
||||
'Authorization': `Bearer ${token}`,
|
||||
'Content-Type': 'application/json'
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Code Splitting
|
||||
|
||||
Lazy load heavy components:
|
||||
|
||||
```typescript
|
||||
const BillingDashboard = lazy(() => import('./BillingDashboard'))
|
||||
const UsageTrends = lazy(() => import('./UsageTrends'))
|
||||
```
|
||||
|
||||
### Memoization
|
||||
|
||||
Memoize expensive calculations:
|
||||
|
||||
```typescript
|
||||
const MemoizedCostBreakdown = memo(({ data }: { data: ProviderData[] }) => {
|
||||
const processedData = useMemo(() =>
|
||||
data.map(item => ({
|
||||
...item,
|
||||
percentage: (item.cost / totalCost) * 100
|
||||
}))
|
||||
, [data, totalCost])
|
||||
|
||||
return <CostBreakdownChart data={processedData} />
|
||||
})
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
Required packages:
|
||||
|
||||
```bash
|
||||
npm install recharts framer-motion lucide-react
|
||||
npm install @tanstack/react-query axios
|
||||
npm install zod
|
||||
```
|
||||
|
||||
## Integration Status
|
||||
|
||||
### ✅ Completed
|
||||
- Type definitions and validation schemas
|
||||
- Service layer with all API functions
|
||||
- Core components (BillingOverview, CostBreakdown, UsageTrends, UsageAlerts)
|
||||
- SystemHealthIndicator component
|
||||
- Main dashboard integration
|
||||
- Real-time data fetching with auto-refresh
|
||||
|
||||
### 🔄 Ready for Enhancement
|
||||
- WebSocket integration for instant updates
|
||||
- Advanced analytics and optimization suggestions
|
||||
- Export functionality for reports
|
||||
- Mobile app optimization
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [API Reference](api-reference.md) - Backend endpoint documentation
|
||||
- [Implementation Status](implementation-status.md) - Current features and metrics
|
||||
- [Roadmap](roadmap.md) - Future enhancements
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: January 2025
|
||||
|
||||
267
docs-site/docs/features/subscription/implementation-status.md
Normal file
267
docs-site/docs/features/subscription/implementation-status.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# Implementation Status
|
||||
|
||||
Current status of the ALwrity usage-based subscription system implementation.
|
||||
|
||||
## Overall Progress
|
||||
|
||||
**Phase 1 Complete** - Core billing dashboard integrated and functional
|
||||
|
||||
## Completed Components
|
||||
|
||||
### Backend Integration (100% Complete)
|
||||
|
||||
- **Database Setup**: ✅ All subscription tables created and initialized
|
||||
- **API Integration**: ✅ All subscription routes integrated in `app.py`
|
||||
- **Middleware Integration**: ✅ Enhanced monitoring middleware with usage tracking
|
||||
- **Critical Issues Fixed**: ✅ All identified issues resolved:
|
||||
- Fixed `billing_history` table detection in test suite
|
||||
- Resolved `NoneType + int` error in usage tracking service
|
||||
- Fixed middleware double request body consumption
|
||||
|
||||
### Frontend Foundation (100% Complete)
|
||||
|
||||
- **Dependencies**: ✅ All required packages installed
|
||||
- `recharts` - Data visualization
|
||||
- `framer-motion` - Animations
|
||||
- `lucide-react` - Icons
|
||||
- `@tanstack/react-query` - API caching
|
||||
- `axios` - HTTP client
|
||||
- `zod` - Type validation
|
||||
|
||||
### Type System (100% Complete)
|
||||
|
||||
- **File**: `frontend/src/types/billing.ts`
|
||||
- **Interfaces**: ✅ All core interfaces defined
|
||||
- `DashboardData`, `UsageStats`, `ProviderBreakdown`
|
||||
- `SubscriptionLimits`, `UsageAlert`, `CostProjections`
|
||||
- `UsageTrends`, `APIPricing`, `SubscriptionPlan`
|
||||
- **Zod Schemas**: ✅ All validation schemas implemented
|
||||
- **Type Safety**: ✅ Full TypeScript coverage with runtime validation
|
||||
|
||||
### Service Layer (100% Complete)
|
||||
|
||||
- **File**: `frontend/src/services/billingService.ts`
|
||||
- **API Functions**: ✅ All core functions implemented
|
||||
- `getDashboardData()`, `getUsageStats()`, `getUsageTrends()`
|
||||
- `getSubscriptionPlans()`, `getAPIPricing()`, `getUsageAlerts()`
|
||||
- `markAlertRead()`, `getUserSubscription()`
|
||||
- **Error Handling**: ✅ Comprehensive error handling and retry logic
|
||||
- **Data Coercion**: ✅ Raw API response sanitization and validation
|
||||
|
||||
- **File**: `frontend/src/services/monitoringService.ts`
|
||||
- **Monitoring Functions**: ✅ All monitoring APIs integrated
|
||||
- `getSystemHealth()`, `getAPIStats()`, `getLightweightStats()`, `getCacheStats()`
|
||||
|
||||
### Core Components (100% Complete)
|
||||
|
||||
- **File**: `frontend/src/components/billing/BillingDashboard.tsx`
|
||||
- ✅ Main container component with real-time data fetching
|
||||
- ✅ Loading states and error handling
|
||||
- ✅ Auto-refresh every 30 seconds
|
||||
- ✅ Responsive design
|
||||
|
||||
- **File**: `frontend/src/components/billing/BillingOverview.tsx`
|
||||
- ✅ Usage metrics display with animated counters
|
||||
- ✅ Progress bars for usage limits
|
||||
- ✅ Status indicators (active/warning/limit_reached)
|
||||
- ✅ Quick action buttons
|
||||
|
||||
- **File**: `frontend/src/components/billing/CostBreakdown.tsx`
|
||||
- ✅ Interactive pie chart with provider breakdown
|
||||
- ✅ Hover effects and detailed cost information
|
||||
- ✅ Provider-specific cost analysis
|
||||
- ✅ Responsive chart sizing
|
||||
|
||||
- **File**: `frontend/src/components/billing/UsageTrends.tsx`
|
||||
- ✅ Multi-line chart for usage trends over time
|
||||
- ✅ Time range selector (3m, 6m, 12m)
|
||||
- ✅ Metric toggle (cost/calls/tokens)
|
||||
- ✅ Trend analysis and projections
|
||||
|
||||
- **File**: `frontend/src/components/billing/UsageAlerts.tsx`
|
||||
- ✅ Alert management interface
|
||||
- ✅ Severity-based color coding
|
||||
- ✅ Read/unread status management
|
||||
- ✅ Alert filtering and actions
|
||||
|
||||
- **File**: `frontend/src/components/monitoring/SystemHealthIndicator.tsx`
|
||||
- ✅ Real-time system status display
|
||||
- ✅ Color-coded health indicators
|
||||
- ✅ Performance metrics (response time, error rate, uptime)
|
||||
- ✅ Auto-refresh capabilities
|
||||
|
||||
### Main Dashboard Integration (100% Complete)
|
||||
|
||||
- **File**: `frontend/src/components/MainDashboard/MainDashboard.tsx`
|
||||
- ✅ `BillingDashboard` component integrated
|
||||
- ✅ Positioned after `AnalyticsInsights` as requested
|
||||
- ✅ Seamless integration with existing dashboard layout
|
||||
|
||||
### Build System (100% Complete)
|
||||
|
||||
- **TypeScript Compilation**: ✅ All type errors resolved
|
||||
- **Schema Validation**: ✅ Zod schemas properly ordered and validated
|
||||
- **Import Resolution**: ✅ All module imports working correctly
|
||||
- **Production Build**: ✅ Successful build with optimized bundle
|
||||
|
||||
## Current Features
|
||||
|
||||
### Real-Time Monitoring
|
||||
- ✅ Live usage tracking with 30-second refresh
|
||||
- ✅ System health monitoring with color-coded status
|
||||
- ✅ API performance metrics (response time, error rate)
|
||||
- ✅ Cost tracking across all external APIs
|
||||
|
||||
### Cost Transparency
|
||||
- ✅ Detailed cost breakdown by provider (Gemini, OpenAI, Anthropic, etc.)
|
||||
- ✅ Interactive pie charts with hover details
|
||||
- ✅ Usage trends with 6-month historical data
|
||||
- ✅ Monthly cost projections and alerts
|
||||
|
||||
### User Experience
|
||||
- ✅ Enterprise-grade design with Tailwind CSS
|
||||
- ✅ Smooth animations with Framer Motion
|
||||
- ✅ Responsive design (mobile, tablet, desktop)
|
||||
- ✅ Loading states and error handling
|
||||
- ✅ Intuitive navigation and interactions
|
||||
|
||||
### Data Visualization
|
||||
- ✅ Interactive charts with Recharts
|
||||
- ✅ Provider cost breakdown (pie charts)
|
||||
- ✅ Usage trends over time (line charts)
|
||||
- ✅ Progress bars for usage limits
|
||||
- ✅ Status indicators with color coding
|
||||
|
||||
## Implementation Metrics
|
||||
|
||||
### Code Quality
|
||||
- **TypeScript Coverage**: 100% - All components fully typed
|
||||
- **Build Status**: ✅ Successful - No compilation errors
|
||||
- **Linting**: ⚠️ Minor warnings (unused imports) - Non-blocking
|
||||
- **Bundle Size**: 1.12 MB (within acceptable range)
|
||||
|
||||
### Component Architecture
|
||||
- **Total Components**: 6 billing + 1 monitoring = 7 components
|
||||
- **Service Functions**: 12 billing + 4 monitoring = 16 API functions
|
||||
- **Type Definitions**: 15+ interfaces with full Zod validation
|
||||
- **Integration Points**: 1 main dashboard integration
|
||||
|
||||
### API Integration
|
||||
- **Backend Endpoints**: 8 subscription + 4 monitoring = 12 endpoints
|
||||
- **Error Handling**: Comprehensive with retry logic
|
||||
- **Data Validation**: Runtime validation with Zod schemas
|
||||
- **Caching**: React Query for intelligent data caching
|
||||
|
||||
## Delivered Components
|
||||
|
||||
### Database Models
|
||||
- **SubscriptionPlan**: Defines subscription tiers (Free, Basic, Pro, Enterprise)
|
||||
- **UserSubscription**: Tracks user subscription details and billing
|
||||
- **APIUsageLog**: Detailed logging of every API call with cost tracking
|
||||
- **UsageSummary**: Aggregated usage statistics per user per billing period
|
||||
- **APIProviderPricing**: Configurable pricing for all API providers
|
||||
- **UsageAlert**: Automated alerts for usage thresholds
|
||||
- **BillingHistory**: Historical billing records
|
||||
|
||||
### Core Services
|
||||
- **Pricing Service**: Real-time cost calculation for all API providers
|
||||
- **Usage Tracking Service**: Comprehensive API usage tracking
|
||||
- **Exception Handler**: Robust error handling with detailed logging
|
||||
- **Enhanced Middleware**: Automatic API provider detection and usage tracking
|
||||
|
||||
### API Endpoints
|
||||
- `GET /api/subscription/plans` - Available subscription plans
|
||||
- `GET /api/subscription/usage/{user_id}` - Current usage statistics
|
||||
- `GET /api/subscription/usage/{user_id}/trends` - Usage trends over time
|
||||
- `GET /api/subscription/dashboard/{user_id}` - Comprehensive dashboard data
|
||||
- `GET /api/subscription/pricing` - API pricing information
|
||||
- `GET /api/subscription/alerts/{user_id}` - Usage alerts and notifications
|
||||
|
||||
## Success Criteria Met
|
||||
|
||||
### ✅ Functional Requirements
|
||||
- [x] Real-time usage monitoring
|
||||
- [x] Cost transparency and breakdown
|
||||
- [x] System health monitoring
|
||||
- [x] Usage alerts and notifications
|
||||
- [x] Responsive design
|
||||
- [x] Enterprise-grade UI/UX
|
||||
|
||||
### ✅ Technical Requirements
|
||||
- [x] TypeScript type safety
|
||||
- [x] Runtime data validation
|
||||
- [x] Error handling and recovery
|
||||
- [x] Performance optimization
|
||||
- [x] Code maintainability
|
||||
- [x] Integration with existing system
|
||||
|
||||
### ✅ User Experience Requirements
|
||||
- [x] Intuitive navigation
|
||||
- [x] Clear cost explanations
|
||||
- [x] Real-time updates
|
||||
- [x] Mobile responsiveness
|
||||
- [x] Professional design
|
||||
- [x] Smooth animations
|
||||
|
||||
## Business Impact
|
||||
|
||||
### Cost Transparency
|
||||
- **Before**: Users had no visibility into API costs
|
||||
- **After**: Complete cost breakdown with real-time tracking
|
||||
- **Impact**: Reduced surprise overages, better cost awareness
|
||||
|
||||
### System Monitoring
|
||||
- **Before**: Limited system health visibility
|
||||
- **After**: Real-time monitoring with performance metrics
|
||||
- **Impact**: Proactive issue detection, improved reliability
|
||||
|
||||
### User Experience
|
||||
- **Before**: Basic dashboard with limited insights
|
||||
- **After**: Enterprise-grade billing dashboard with advanced analytics
|
||||
- **Impact**: Professional appearance, increased user confidence
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Phase 2: Advanced Features (Optional)
|
||||
1. **Real-Time WebSocket Integration**
|
||||
- WebSocket connection for instant updates
|
||||
- Push notifications for usage alerts
|
||||
- Live cost tracking during API calls
|
||||
|
||||
2. **Advanced Analytics**
|
||||
- Cost optimization suggestions
|
||||
- Usage pattern analysis
|
||||
- Predictive cost modeling
|
||||
- Provider performance comparison
|
||||
|
||||
3. **Enhanced User Experience**
|
||||
- Interactive tooltips with detailed explanations
|
||||
- Advanced filtering and sorting options
|
||||
- Export functionality for reports
|
||||
- Mobile app optimization
|
||||
|
||||
4. **Subscription Management**
|
||||
- Plan comparison and upgrade flows
|
||||
- Billing history and invoice management
|
||||
- Payment method management
|
||||
- Usage-based plan recommendations
|
||||
|
||||
## Conclusion
|
||||
|
||||
The billing and subscription implementation is **100% complete** for Phase 1, successfully delivering:
|
||||
|
||||
1. **Complete Backend Integration** - All APIs, databases, and middleware working
|
||||
2. **Full Frontend Implementation** - All components built and integrated
|
||||
3. **Enterprise-Grade Design** - Professional UI with smooth animations
|
||||
4. **Real-Time Monitoring** - Live usage tracking and system health
|
||||
5. **Cost Transparency** - Detailed breakdowns and trend analysis
|
||||
6. **Production Ready** - Successful build with no critical issues
|
||||
|
||||
The system is now ready for production deployment and provides users with comprehensive visibility into their API usage, costs, and system performance.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: January 2025
|
||||
**Status**: ✅ Production Ready
|
||||
**Next Review**: Optional Phase 2 enhancements
|
||||
|
||||
157
docs-site/docs/features/subscription/overview.md
Normal file
157
docs-site/docs/features/subscription/overview.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# Subscription System Overview
|
||||
|
||||
ALwrity's usage-based subscription system provides comprehensive API cost tracking, usage limits, and real-time monitoring for all external API providers.
|
||||
|
||||
## Features
|
||||
|
||||
### Core Functionality
|
||||
- **Usage-Based Billing**: Track API calls, tokens, and costs across all providers
|
||||
- **Subscription Tiers**: Free, Basic, Pro, and Enterprise plans with different limits
|
||||
- **Real-Time Monitoring**: Live usage tracking and limit enforcement
|
||||
- **Cost Calculation**: Accurate pricing for Gemini, OpenAI, Anthropic, and other APIs
|
||||
- **Usage Alerts**: Automatic notifications at 80%, 90%, and 100% usage thresholds
|
||||
- **Robust Error Handling**: Comprehensive logging and exception management
|
||||
|
||||
### Supported API Providers
|
||||
- **Gemini API**: Google's AI models with latest pricing
|
||||
- **OpenAI**: GPT models and embeddings
|
||||
- **Anthropic**: Claude models
|
||||
- **Mistral AI**: Mistral models
|
||||
- **Tavily**: AI-powered search
|
||||
- **Serper**: Google search API
|
||||
- **Metaphor/Exa**: Advanced search
|
||||
- **Firecrawl**: Web content extraction
|
||||
- **Stability AI**: Image generation
|
||||
- **Hugging Face**: GPT-OSS-120B via Groq
|
||||
|
||||
## Architecture
|
||||
|
||||
### Database Schema
|
||||
|
||||
The system uses the following core tables:
|
||||
|
||||
- `subscription_plans`: Available subscription tiers and limits
|
||||
- `user_subscriptions`: User subscription information
|
||||
- `api_usage_logs`: Detailed log of every API call
|
||||
- `usage_summaries`: Aggregated usage per user per billing period
|
||||
- `api_provider_pricing`: Pricing configuration for all providers
|
||||
- `usage_alerts`: Usage notifications and warnings
|
||||
- `billing_history`: Historical billing records
|
||||
|
||||
### Service Structure
|
||||
|
||||
```
|
||||
backend/services/subscription/
|
||||
├── __init__.py # Package exports
|
||||
├── pricing_service.py # API pricing and cost calculations
|
||||
├── usage_tracking_service.py # Usage tracking and limits
|
||||
├── exception_handler.py # Exception handling
|
||||
└── monitoring_middleware.py # API monitoring middleware
|
||||
```
|
||||
|
||||
### Core Services
|
||||
|
||||
#### Pricing Service
|
||||
- Real-time cost calculation for all API providers
|
||||
- Subscription limit management
|
||||
- Usage validation and enforcement
|
||||
- Support for Gemini, OpenAI, Anthropic, Mistral, and search APIs
|
||||
|
||||
#### Usage Tracking Service
|
||||
- Comprehensive API usage tracking
|
||||
- Real-time usage statistics
|
||||
- Trend analysis and projections
|
||||
- Automatic alert generation at 80%, 90%, and 100% thresholds
|
||||
|
||||
#### Exception Handler
|
||||
- Robust error handling with detailed logging
|
||||
- Structured exception types for different scenarios
|
||||
- Automatic alert creation for critical errors
|
||||
- User-friendly error messages
|
||||
|
||||
### Enhanced Middleware
|
||||
|
||||
The system automatically tracks API usage through enhanced middleware:
|
||||
|
||||
- **Automatic API Provider Detection**: Identifies Gemini, OpenAI, Anthropic, etc.
|
||||
- **Token Estimation**: Estimates usage from request/response content
|
||||
- **Pre-Request Validation**: Enforces usage limits before processing
|
||||
- **Cost Tracking**: Real-time cost calculation and logging
|
||||
- **Usage Limit Enforcement**: Returns 429 errors when limits exceeded
|
||||
|
||||
## Key Capabilities
|
||||
|
||||
### Usage-Based Billing
|
||||
- ✅ **Real-time cost tracking** for all API providers
|
||||
- ✅ **Token-level precision** for LLM APIs (Gemini, OpenAI, Anthropic)
|
||||
- ✅ **Request-based pricing** for search APIs (Tavily, Serper, Metaphor)
|
||||
- ✅ **Automatic cost calculation** with configurable pricing
|
||||
|
||||
### Subscription Management
|
||||
- ✅ **4 Subscription Tiers**: Free, Basic ($29/mo), Pro ($79/mo), Enterprise ($199/mo)
|
||||
- ✅ **Flexible limits**: API calls, tokens, and monthly cost caps
|
||||
- ✅ **Usage enforcement**: Pre-request validation and blocking
|
||||
- ✅ **Billing cycle support**: Monthly and yearly options
|
||||
|
||||
### Monitoring & Analytics
|
||||
- ✅ **Real-time dashboard** with usage statistics
|
||||
- ✅ **Usage trends** and projections
|
||||
- ✅ **Provider-specific breakdowns** (Gemini, OpenAI, etc.)
|
||||
- ✅ **Performance metrics** (response times, error rates)
|
||||
|
||||
### Alert System
|
||||
- ✅ **Automatic notifications** at 80%, 90%, and 100% usage
|
||||
- ✅ **Multi-channel alerts** (database, logs, future email integration)
|
||||
- ✅ **Alert management** (mark as read, severity levels)
|
||||
- ✅ **Usage recommendations** and upgrade prompts
|
||||
|
||||
## Security & Privacy
|
||||
|
||||
### Data Protection
|
||||
- User usage data is encrypted at rest
|
||||
- API keys are never logged in usage tracking
|
||||
- Sensitive information is excluded from error logs
|
||||
- GDPR-compliant data handling
|
||||
|
||||
### Rate Limiting
|
||||
- Pre-request usage validation
|
||||
- Automatic limit enforcement
|
||||
- Graceful degradation when limits are reached
|
||||
- User-friendly error messages
|
||||
|
||||
## Exception Types
|
||||
|
||||
The system uses structured exception types:
|
||||
|
||||
- `UsageLimitExceededException`: When usage limits are reached
|
||||
- `PricingException`: Pricing calculation errors
|
||||
- `TrackingException`: Usage tracking failures
|
||||
- `SubscriptionException`: General subscription errors
|
||||
|
||||
## Customization
|
||||
|
||||
### Adding New API Providers
|
||||
1. Add provider to `APIProvider` enum
|
||||
2. Configure pricing in `api_provider_pricing` table
|
||||
3. Update detection patterns in middleware
|
||||
4. Add usage tracking logic
|
||||
|
||||
### Modifying Subscription Plans
|
||||
1. Update plans in database or via API
|
||||
2. Modify limits and pricing
|
||||
3. Add/remove features
|
||||
4. Update billing integration
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Setup Guide](setup.md) - Installation and configuration
|
||||
- [API Reference](api-reference.md) - Endpoint documentation
|
||||
- [Pricing](pricing.md) - Subscription plans and API pricing
|
||||
- [Frontend Integration](frontend-integration.md) - Technical specifications
|
||||
- [Implementation Status](implementation-status.md) - Current features and metrics
|
||||
|
||||
---
|
||||
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: January 2025
|
||||
|
||||
98
docs-site/docs/features/subscription/pricing.md
Normal file
98
docs-site/docs/features/subscription/pricing.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# Subscription Plans & API Pricing
|
||||
|
||||
End-to-end reference for ALwrity's usage-based subscription tiers, API cost configuration, and plan-specific limits. All data is sourced from `backend/services/subscription/pricing_service.py`.
|
||||
|
||||
## Subscription Plans
|
||||
|
||||
> **Legend**: `∞` = Unlimited. Limits reset at the start of each billing cycle.
|
||||
|
||||
| Plan | Price (Monthly / Yearly) | AI Text Generation Calls* | Token Limits (per provider) | Key API Limits | Video Generation | Monthly Cost Cap | Highlights |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| **Free** | `$0 / $0` | 100 Gemini • 50 Mistral (legacy enforcement) | 100K Gemini tokens | 20 Tavily • 20 Serper • 10 Metaphor • 10 Firecrawl • 5 Stability • 100 Exa | Not included | `$0` | Basic content generation & limited research |
|
||||
| **Basic** | `$29 / $290` | **10 unified LLM calls** (Gemini + OpenAI + Anthropic + Mistral combined) | 20K tokens each (Gemini, OpenAI, Anthropic, Mistral) | 200 Tavily • 200 Serper • 100 Metaphor • 100 Firecrawl • 5 Stability • 500 Exa | 20 videos/mo | `$50` | Full content generation, advanced research, basic analytics |
|
||||
| **Pro** | `$79 / $790` | 5K Gemini • 2.5K OpenAI • 1K Anthropic • 2.5K Mistral | 5M Gemini • 2.5M OpenAI • 1M Anthropic • 2.5M Mistral | 1K Tavily • 1K Serper • 500 Metaphor • 500 Firecrawl • 200 Stability • 2K Exa | 50 videos/mo | `$150` | Premium research, advanced analytics, priority support |
|
||||
| **Enterprise** | `$199 / $1,990` | ∞ across all LLM providers | ∞ | ∞ across every research/media API | ∞ | `$500` | White-label, dedicated support, custom integrations |
|
||||
|
||||
\*The Basic plan now enforces a **unified** `ai_text_generation_calls_limit` of 10 requests across all LLM providers. Legacy per-provider columns remain for analytics dashboards but do not control enforcement.
|
||||
|
||||
### Plan Feature Notes
|
||||
- **Video Generation**: Powered by Hugging Face `tencent/HunyuanVideo` ($0.10 per request). Plan limits are shown above.
|
||||
- **Image Generation**: Stability AI billed at $0.04/image. Limits shown under “Key API Limits”.
|
||||
- **Research APIs**: Tavily, Serper, Metaphor, Exa, and Firecrawl are individually rate-limited per plan.
|
||||
- **Cost Caps**: `monthly_cost_limit` hard stops spend at $50 / $150 / $500 for paid tiers. Enterprise caps are adjustable via support.
|
||||
|
||||
## Provider Pricing Matrix
|
||||
|
||||
### Gemini 2.5 & 1.5 (Google)
|
||||
- `gemini-2.5-pro` — $0.00000125 input / $0.00001 output per token ($1.25 / $10 per 1M tokens)
|
||||
- `gemini-2.5-pro-large` — $0.0000025 / $0.000015 per token (large context)
|
||||
- `gemini-2.5-flash` — $0.0000003 / $0.0000025 per token
|
||||
- `gemini-2.5-flash-audio` — $0.000001 / $0.0000025 per token
|
||||
- `gemini-2.5-flash-lite` — $0.0000001 / $0.0000004 per token
|
||||
- `gemini-2.5-flash-lite-audio` — $0.0000003 / $0.0000004 per token
|
||||
- `gemini-1.5-flash` — $0.000000075 / $0.0000003 per token
|
||||
- `gemini-1.5-flash-8b` — $0.0000000375 / $0.00000015 per token
|
||||
- `gemini-1.5-pro` — $0.00000125 / $0.000005 per token
|
||||
- `gemini-1.5-pro-large` — $0.0000025 / $0.00001 per token
|
||||
- `gemini-embedding` — $0.00000015 per input token
|
||||
- `gemini-grounding-search` — $35 per 1,000 requests after the free tier
|
||||
|
||||
### OpenAI (estimates — update when official pricing changes)
|
||||
- `gpt-4o` — $0.0000025 input / $0.00001 output per token
|
||||
- `gpt-4o-mini` — $0.00000015 input / $0.0000006 output per token
|
||||
|
||||
### Anthropic
|
||||
- `claude-3.5-sonnet` — $0.000003 input / $0.000015 output per token
|
||||
|
||||
### Hugging Face / Mistral (GPT-OSS-120B via Groq)
|
||||
Pricing is configurable through environment variables:
|
||||
```
|
||||
HUGGINGFACE_INPUT_TOKEN_COST=0.000001 # $1 per 1M tokens
|
||||
HUGGINGFACE_OUTPUT_TOKEN_COST=0.000003 # $3 per 1M tokens
|
||||
```
|
||||
Models covered: `openai/gpt-oss-120b:groq`, `gpt-oss-120b`, and `default` (fallback).
|
||||
|
||||
### Search, Image, and Video APIs
|
||||
- Tavily — $0.001 per search
|
||||
- Serper — $0.001 per search
|
||||
- Metaphor — $0.003 per search
|
||||
- Exa — $0.005 per search (1–25 results)
|
||||
- Firecrawl — $0.002 per crawled page
|
||||
- Stability AI — $0.04 per image
|
||||
- Video Generation (HunyuanVideo) — $0.10 per video request
|
||||
|
||||
## Updating Pricing & Plans
|
||||
|
||||
1. **Initial Seed** — `python backend/scripts/create_subscription_tables.py` creates plans and pricing.
|
||||
2. **Env Overrides** — Hugging Face pricing refreshes from `HUGGINGFACE_*` vars every boot.
|
||||
3. **Scripts & Maintenance** — Use `backend/scripts/` utilities (e.g., `update_basic_plan_limits.py`, `cap_basic_plan_usage.py`) to roll forward changes.
|
||||
4. **Direct DB Edits** — Modify `subscription_plans` or `api_provider_pricing` tables for emergency adjustments.
|
||||
|
||||
## Cost Examples
|
||||
|
||||
| Scenario | Calculation | Cost |
|
||||
| --- | --- | --- |
|
||||
| Gemini 2.5 Flash (1K input / 500 output tokens) | (1,000 × 0.0000003) + (500 × 0.0000025) | **$0.00155** |
|
||||
| Tavily Search | 1 request × $0.001 | **$0.001** |
|
||||
| Hugging Face GPT-OSS-120B (2K in / 1K out) | (2,000 × 0.000001) + (1,000 × 0.000003) | **$0.005** |
|
||||
| Video Generation (Basic plan) | 1 request × $0.10 | **$0.10** (counts toward 20-video quota) |
|
||||
|
||||
## Enforcement & Monitoring
|
||||
|
||||
1. Middleware estimates usage and calls `UsageTrackingService.track_api_usage`.
|
||||
2. `UsageService.enforce_usage_limits` validates the request before the downstream provider call.
|
||||
3. When a limit would be exceeded, the API returns `429` with upgrade guidance.
|
||||
4. The Billing Dashboard (`/billing`) shows real-time usage, cost projections, provider breakdowns, renewal history, and usage logs.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Billing Dashboard](billing-dashboard.md)
|
||||
- [API Reference](api-reference.md)
|
||||
- [Setup Guide](setup.md)
|
||||
- [Gemini Pricing](https://ai.google.dev/gemini-api/docs/pricing)
|
||||
- [OpenAI Pricing](https://openai.com/pricing)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: November 2025
|
||||
|
||||
232
docs-site/docs/features/subscription/roadmap.md
Normal file
232
docs-site/docs/features/subscription/roadmap.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# Subscription System Roadmap
|
||||
|
||||
Implementation phases and future enhancements for the ALwrity subscription system.
|
||||
|
||||
## Phase 1: Foundation & Core Components ✅ Complete
|
||||
|
||||
**Status**: ✅ **100% Complete**
|
||||
|
||||
### Completed Deliverables
|
||||
|
||||
#### Project Setup & Dependencies
|
||||
- ✅ Installed required packages (recharts, framer-motion, lucide-react, react-query, axios, zod)
|
||||
- ✅ Created folder structure for billing and monitoring components
|
||||
|
||||
#### Type Definitions
|
||||
- ✅ Defined core interfaces (DashboardData, UsageStats, ProviderBreakdown, etc.)
|
||||
- ✅ Created validation schemas with Zod
|
||||
- ✅ Exported all type definitions
|
||||
|
||||
#### Service Layer
|
||||
- ✅ Implemented billing service with all API client functions
|
||||
- ✅ Implemented monitoring service with monitoring API functions
|
||||
- ✅ Added error handling and retry logic
|
||||
- ✅ Implemented request/response interceptors
|
||||
|
||||
#### Core Components
|
||||
- ✅ BillingOverview component with usage metrics
|
||||
- ✅ SystemHealthIndicator component with health status
|
||||
- ✅ CostBreakdown component with interactive charts
|
||||
- ✅ UsageTrends component with time range selection
|
||||
- ✅ UsageAlerts component with alert management
|
||||
- ✅ BillingDashboard main container component
|
||||
|
||||
#### Dashboard Integration
|
||||
- ✅ Integrated BillingDashboard into MainDashboard
|
||||
- ✅ Added responsive grid layout
|
||||
- ✅ Implemented section navigation
|
||||
|
||||
## Phase 2: Data Visualization & Charts ✅ Complete
|
||||
|
||||
**Status**: ✅ **100% Complete**
|
||||
|
||||
### Completed Deliverables
|
||||
|
||||
#### Chart Components
|
||||
- ✅ Implemented pie chart with Recharts for cost breakdown
|
||||
- ✅ Added interactive tooltips and provider legend
|
||||
- ✅ Created line chart for usage trends
|
||||
- ✅ Implemented metric toggle (cost/calls/tokens)
|
||||
- ✅ Added trend analysis display
|
||||
|
||||
#### Dashboard Integration
|
||||
- ✅ Enhanced dashboard header with system health indicator
|
||||
- ✅ Added usage summary and alert notification badge
|
||||
- ✅ Created billing section wrapper
|
||||
- ✅ Implemented responsive grid layout
|
||||
|
||||
## Phase 3: Real-Time Updates & Animations ✅ Complete
|
||||
|
||||
**Status**: ✅ **100% Complete**
|
||||
|
||||
### Completed Deliverables
|
||||
|
||||
#### Real-Time Updates
|
||||
- ✅ Implemented intelligent polling (30s when active, 5m when inactive)
|
||||
- ✅ Added auto-refresh capabilities
|
||||
- ✅ Implemented loading states and error handling
|
||||
|
||||
#### Animations
|
||||
- ✅ Added Framer Motion animations for page transitions
|
||||
- ✅ Implemented card hover effects
|
||||
- ✅ Added number animations for metrics
|
||||
- ✅ Created skeleton loaders for loading states
|
||||
|
||||
#### Responsive Design
|
||||
- ✅ Implemented mobile-first responsive design
|
||||
- ✅ Added breakpoint-specific layouts
|
||||
- ✅ Optimized chart sizing for different screen sizes
|
||||
|
||||
## Phase 4: Advanced Features & Optimization 🔄 Optional
|
||||
|
||||
**Status**: 🔄 **Future Enhancements**
|
||||
|
||||
### Planned Features
|
||||
|
||||
#### Real-Time WebSocket Integration
|
||||
- [ ] WebSocket connection for instant updates
|
||||
- [ ] Push notifications for usage alerts
|
||||
- [ ] Live cost tracking during API calls
|
||||
- [ ] Real-time dashboard updates without polling
|
||||
|
||||
#### Advanced Analytics
|
||||
- [ ] Cost optimization suggestions
|
||||
- [ ] Usage pattern analysis
|
||||
- [ ] Predictive cost modeling
|
||||
- [ ] Provider performance comparison
|
||||
- [ ] Anomaly detection for unusual usage patterns
|
||||
|
||||
#### Enhanced User Experience
|
||||
- [ ] Interactive tooltips with detailed explanations
|
||||
- [ ] Advanced filtering and sorting options
|
||||
- [ ] Export functionality for reports (PDF, CSV)
|
||||
- [ ] Mobile app optimization
|
||||
- [ ] Dark mode support
|
||||
- [ ] Customizable dashboard layouts
|
||||
|
||||
#### Subscription Management
|
||||
- [ ] Plan comparison interface
|
||||
- [ ] Upgrade/downgrade flows
|
||||
- [ ] Billing history and invoice management
|
||||
- [ ] Payment method management
|
||||
- [ ] Usage-based plan recommendations
|
||||
- [ ] Automatic plan suggestions based on usage
|
||||
|
||||
#### Performance Optimizations
|
||||
- [ ] Code splitting for large components
|
||||
- [ ] Lazy loading for chart components
|
||||
- [ ] Data pagination for large datasets
|
||||
- [ ] Memoization for expensive calculations
|
||||
- [ ] Virtual scrolling for long lists
|
||||
|
||||
## Phase 5: Enterprise Features 🚀 Future
|
||||
|
||||
**Status**: 🚀 **Long-Term Roadmap**
|
||||
|
||||
### Planned Enterprise Features
|
||||
|
||||
#### Multi-Tenant Support
|
||||
- [ ] Organization-level usage tracking
|
||||
- [ ] Team usage allocation and limits
|
||||
- [ ] Department-level cost allocation
|
||||
- [ ] Budget management per team/department
|
||||
|
||||
#### Advanced Reporting
|
||||
- [ ] Custom report builder
|
||||
- [ ] Scheduled report generation
|
||||
- [ ] Email report delivery
|
||||
- [ ] Executive dashboards
|
||||
- [ ] Cost forecasting and budgeting
|
||||
|
||||
#### Integration Enhancements
|
||||
- [ ] Slack/Teams notifications
|
||||
- [ ] Webhook support for external integrations
|
||||
- [ ] API for third-party billing systems
|
||||
- [ ] SSO integration for enterprise customers
|
||||
- [ ] Audit log and compliance reporting
|
||||
|
||||
#### Advanced Monitoring
|
||||
- [ ] Custom alert rules
|
||||
- [ ] Alert escalation policies
|
||||
- [ ] Performance SLA tracking
|
||||
- [ ] Provider health monitoring
|
||||
- [ ] Cost anomaly detection
|
||||
|
||||
## Technical Debt & Optimizations
|
||||
|
||||
### Minor Issues (Non-Critical)
|
||||
- [ ] Remove unused imports (linting warnings)
|
||||
- [ ] Optimize bundle size with code splitting
|
||||
- [ ] Add React error boundaries for better error handling
|
||||
- [ ] Improve TypeScript strict mode compliance
|
||||
|
||||
### Performance Optimizations
|
||||
- [ ] Add React.memo for expensive components
|
||||
- [ ] Implement lazy loading for chart components
|
||||
- [ ] Add data pagination for large datasets
|
||||
- [ ] Optimize API response caching
|
||||
|
||||
## Testing Enhancements
|
||||
|
||||
### Recommended Testing
|
||||
- [ ] Component unit tests for React components
|
||||
- [ ] Integration testing for end-to-end billing flow
|
||||
- [ ] Visual regression testing for UI consistency
|
||||
- [ ] Performance testing for real-time updates
|
||||
- [ ] Load testing for high-traffic scenarios
|
||||
|
||||
## Documentation Updates
|
||||
|
||||
### Planned Documentation
|
||||
- [ ] Video tutorials for billing dashboard
|
||||
- [ ] Interactive API documentation
|
||||
- [ ] Best practices guide for cost optimization
|
||||
- [ ] Troubleshooting guide with common issues
|
||||
- [ ] Migration guide for existing users
|
||||
|
||||
## Timeline Estimates
|
||||
|
||||
### Phase 4 (Advanced Features)
|
||||
- **Estimated Duration**: 4-6 weeks
|
||||
- **Priority**: Medium
|
||||
- **Dependencies**: Phase 1-3 completion ✅
|
||||
|
||||
### Phase 5 (Enterprise Features)
|
||||
- **Estimated Duration**: 8-12 weeks
|
||||
- **Priority**: Low
|
||||
- **Dependencies**: Phase 4 completion, enterprise customer demand
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Phase 4 Success Criteria
|
||||
- [ ] WebSocket integration reduces polling overhead by 80%
|
||||
- [ ] Cost optimization suggestions reduce user costs by 15%
|
||||
- [ ] Export functionality used by 30% of users
|
||||
- [ ] Mobile app optimization increases mobile usage by 50%
|
||||
|
||||
### Phase 5 Success Criteria
|
||||
- [ ] Multi-tenant support enables 10+ enterprise customers
|
||||
- [ ] Advanced reporting reduces support tickets by 40%
|
||||
- [ ] Integration enhancements increase customer retention by 25%
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions to the subscription system roadmap. Please:
|
||||
|
||||
1. Review existing issues and feature requests
|
||||
2. Discuss major features before implementation
|
||||
3. Follow the established code standards
|
||||
4. Add comprehensive tests for new features
|
||||
5. Update documentation with changes
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Implementation Status](implementation-status.md) - Current features and metrics
|
||||
- [Frontend Integration](frontend-integration.md) - Technical specifications
|
||||
- [API Reference](api-reference.md) - Endpoint documentation
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: January 2025
|
||||
**Current Phase**: Phase 3 Complete, Phase 4 Planning
|
||||
|
||||
241
docs-site/docs/features/subscription/setup.md
Normal file
241
docs-site/docs/features/subscription/setup.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# Subscription System Setup
|
||||
|
||||
Complete guide for installing and configuring the ALwrity usage-based subscription system.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.8+
|
||||
- PostgreSQL database (or SQLite for development)
|
||||
- FastAPI backend environment
|
||||
- Required Python packages: `sqlalchemy`, `loguru`, `fastapi`
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Database Migration
|
||||
|
||||
Run the database setup script to create all subscription tables:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python scripts/create_subscription_tables.py
|
||||
```
|
||||
|
||||
This script will:
|
||||
- Create all subscription-related database tables
|
||||
- Initialize default subscription plans (Free, Basic, Pro, Enterprise)
|
||||
- Configure API pricing for all providers
|
||||
- Verify the setup
|
||||
|
||||
### 2. Verify Installation
|
||||
|
||||
Test the subscription system:
|
||||
|
||||
```bash
|
||||
python test_subscription_system.py
|
||||
```
|
||||
|
||||
This will verify:
|
||||
- Database table creation
|
||||
- Pricing calculations
|
||||
- Usage tracking
|
||||
- Limit enforcement
|
||||
- Error handling
|
||||
- API endpoints
|
||||
|
||||
### 3. Start the Server
|
||||
|
||||
```bash
|
||||
python start_alwrity_backend.py
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create or update your `.env` file with the following:
|
||||
|
||||
```env
|
||||
# Database Configuration
|
||||
DATABASE_URL=postgresql://user:password@localhost/alwrity
|
||||
# For development, you can use SQLite:
|
||||
# DATABASE_URL=sqlite:///./alwrity.db
|
||||
|
||||
# API Keys (required for usage tracking)
|
||||
GEMINI_API_KEY=your_gemini_key
|
||||
OPENAI_API_KEY=your_openai_key
|
||||
ANTHROPIC_API_KEY=your_anthropic_key
|
||||
# ... other API keys as needed
|
||||
|
||||
# HuggingFace Pricing (optional, for GPT-OSS-120B via Groq)
|
||||
HUGGINGFACE_INPUT_TOKEN_COST=0.000001
|
||||
HUGGINGFACE_OUTPUT_TOKEN_COST=0.000003
|
||||
```
|
||||
|
||||
### HuggingFace Pricing Configuration
|
||||
|
||||
HuggingFace API calls (specifically for GPT-OSS-120B model via Groq) are tracked and billed using configurable pricing.
|
||||
|
||||
#### Environment Variables
|
||||
|
||||
- `HUGGINGFACE_INPUT_TOKEN_COST`: Cost per input token (default: `0.000001` = $1 per 1M tokens)
|
||||
- `HUGGINGFACE_OUTPUT_TOKEN_COST`: Cost per output token (default: `0.000003` = $3 per 1M tokens)
|
||||
|
||||
#### Updating Pricing
|
||||
|
||||
The pricing is automatically initialized when the database is set up. To update pricing after changing environment variables:
|
||||
|
||||
1. **Option 1**: Restart the backend server (pricing will be updated on next initialization)
|
||||
2. **Option 2**: Run the database setup script again:
|
||||
```bash
|
||||
python backend/scripts/create_subscription_tables.py
|
||||
```
|
||||
|
||||
#### Verify Pricing
|
||||
|
||||
Check that pricing is correctly configured by:
|
||||
1. Checking the database `api_provider_pricing` table
|
||||
2. Making a test API call and checking the cost in usage logs
|
||||
3. Viewing the billing dashboard to see cost calculations
|
||||
|
||||
## Production Setup
|
||||
|
||||
### 1. Database
|
||||
|
||||
Use PostgreSQL for production:
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql://user:password@host:5432/alwrity_prod
|
||||
```
|
||||
|
||||
### 2. Caching
|
||||
|
||||
Set up Redis for caching (optional but recommended):
|
||||
|
||||
```env
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
```
|
||||
|
||||
### 3. Email Notifications
|
||||
|
||||
Configure email service for usage alerts:
|
||||
|
||||
```env
|
||||
SMTP_HOST=smtp.example.com
|
||||
SMTP_PORT=587
|
||||
SMTP_USER=alerts@alwrity.com
|
||||
SMTP_PASSWORD=your_password
|
||||
```
|
||||
|
||||
### 4. Monitoring and Alerting
|
||||
|
||||
Set up monitoring and alerting systems:
|
||||
- Configure log aggregation
|
||||
- Set up performance monitoring
|
||||
- Configure alert thresholds
|
||||
|
||||
### 5. Payment Processing
|
||||
|
||||
Implement payment processing integration:
|
||||
- Stripe integration
|
||||
- Payment gateway setup
|
||||
- Billing cycle management
|
||||
|
||||
## Middleware Integration
|
||||
|
||||
The subscription system automatically tracks API usage through enhanced middleware. The middleware:
|
||||
|
||||
- Detects API provider from request patterns
|
||||
- Estimates token usage from request/response content
|
||||
- Validates usage limits before processing
|
||||
- Calculates costs in real-time
|
||||
- Logs all API calls for tracking
|
||||
|
||||
No additional configuration is required - the middleware is automatically active once the subscription system is installed.
|
||||
|
||||
## Usage Limit Enforcement
|
||||
|
||||
The system enforces usage limits automatically:
|
||||
|
||||
```python
|
||||
# Usage limits are checked before processing requests
|
||||
can_proceed, message, usage_info = await usage_service.enforce_usage_limits(
|
||||
user_id=user_id,
|
||||
provider=APIProvider.GEMINI,
|
||||
tokens_requested=1000
|
||||
)
|
||||
|
||||
if not can_proceed:
|
||||
return JSONResponse(
|
||||
status_code=429,
|
||||
content={"error": "Usage limit exceeded", "message": message}
|
||||
)
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Run Tests
|
||||
|
||||
```bash
|
||||
python test_subscription_system.py
|
||||
```
|
||||
|
||||
### Test Coverage
|
||||
|
||||
The test suite covers:
|
||||
- Database table creation
|
||||
- Pricing calculations
|
||||
- Usage tracking
|
||||
- Limit enforcement
|
||||
- Error handling
|
||||
- API endpoints
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Database Connection Errors**
|
||||
- Check `DATABASE_URL` configuration
|
||||
- Verify database is running
|
||||
- Check network connectivity
|
||||
|
||||
2. **Missing API Keys**
|
||||
- Verify all required keys are set in `.env`
|
||||
- Check environment variable names match exactly
|
||||
|
||||
3. **Usage Not Tracking**
|
||||
- Verify middleware is integrated
|
||||
- Check database connection
|
||||
- Review logs for errors
|
||||
|
||||
4. **Pricing Errors**
|
||||
- Verify provider pricing configuration in database
|
||||
- Check `api_provider_pricing` table
|
||||
- Review pricing initialization logs
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging:
|
||||
|
||||
```python
|
||||
import logging
|
||||
logging.basicConfig(level=logging.DEBUG)
|
||||
```
|
||||
|
||||
### Support
|
||||
|
||||
For issues and questions:
|
||||
1. Check the logs in `logs/subscription_errors.log`
|
||||
2. Run the test suite to identify problems
|
||||
3. Review the error handling documentation
|
||||
4. Contact the development team
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [API Reference](api-reference.md) - Endpoint documentation and examples
|
||||
- [Pricing](pricing.md) - Subscription plans and API pricing details
|
||||
- [Frontend Integration](frontend-integration.md) - Technical specifications for frontend
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: January 2025
|
||||
|
||||
Reference in New Issue
Block a user