Base code

docs-site/docs/features/subscription/pricing.md

@@ -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
+