🤗 Hugging-c-ai — Multi-Provider AI Persona Chat Portal

Forked & heavily upgraded from Open Character AI. Replaces Google OAuth with HuggingFace OAuth, adds multi-provider LLM support (OpenAI, Anthropic, HuggingFace Inference, Groq, MuAPI, custom Gradio Servers), stores uploads in HF Dataset buckets, and supports real-time streaming responses.

🚀 What's New (vs upstream)

Area	Upstream	Hugging-c-ai
Auth	Google OAuth + MuAPI API key	HuggingFace OAuth (with repo:write scope) + multi-provider API key (auto-detected)
LLM providers	MuAPI gateway only	6 providers: OpenAI, Anthropic, HuggingFace, Groq, MuAPI, custom Gradio Servers
Streaming	❌ polling every 1.5s	✅ SSE streaming for OpenAI, Anthropic, HF, Groq
Storage	MuAPI CDN only	✅ HF Dataset bucket (HfFileSystem) — uploads save to user's own HF repo
Models	4 hardcoded options	✅ 17 models across 5 providers + custom Gradio endpoints
Database	PostgreSQL (requires Supabase/Neon)	✅ SQLite by default (zero setup) — switch to Postgres for prod
Credit cost	Flat 2 credits	✅ Per-model pricing from catalog (1c–15c)
Token tracking	❌	✅ Prompt + completion tokens logged per message
Marketplace	❌	✅ /explore page — browse all public custom characters
Deploy button	Vercel clone	✅ Duplicate to HF Space

---

✨ Core Features

💬 Multi-Provider Chat Studio (/[character_name]/[id])

• 17 LLM options grouped by provider in the model selector
• Real-time SSE streaming — watch tokens appear as they generate
• Custom Gradio endpoints — connect to any HF Space running a Gradio app
• Per-chat LLM tuning: temperature, max tokens, reasoning mode, streaming toggle
• Vision support for OpenAI GPT-4o, Claude 3.5, Gemini (via MuAPI)
• Token usage tracking (prompt + completion tokens per message)

🤗 HuggingFace Authentication

• OAuth2 flow with openid profile email repo:write read scopes
• The user's HF access token is reused for:
  • Writing uploads to their own HF dataset repo
  • Calling private/gated Gradio Spaces
  • HuggingFace Inference API calls
• Fallback: API key auth supports hf_*, sk-*, sk-ant*, gsk_*, mu_* prefixes — auto-detected

🗄️ HF Dataset Bucket Storage

• Uploads are written to a HF dataset repo (default: <hf-username>/hugging-c-ai-assets)
• Uses @huggingface/hub's uploadFile / listFiles / downloadFile / deleteFile
• The repo is created lazily on first upload if it doesn't exist
• Public resolve URLs (https://huggingface.co/datasets/<repo>/resolve/main/<path>) are stored in the DB
• Falls back to MuAPI upload if no HF token is available

🔌 Gradio Server Support

• Connect to any deployed Gradio app as a custom LLM endpoint
• Format: gradio:<space-url> or gradio:<space-url>::<api-name>
• Uses the user's HF OAuth token to authenticate (so private/gated Spaces work)
• Auto-tries common parameter shapes (chat, predict, single-message)
• Reference: Introducing Gradio Server

🎭 Character Builder & Marketplace

• 15 preset characters (Einstein, Jobs, Sherlock, etc.) ship out of the box
• Visual builder for custom personas — name, avatar, system prompt, greeting, visibility
• /explore page — browse all public custom characters created by the community
• Per-character public/private toggle (only visible to creator if private)

💳 Stripe Billing (optional)

• 4 credit pack plans ($5/$10/$20/$50)
• Pay-as-you-go credit balance, instantly updated via Stripe webhooks
• Per-model cost deducted per message; auto-refunded on generation failure

---

🛠️ Architecture

hugging-c-ai/
├── prisma/
│   └── schema.prisma                    # SQLite schema (User, Account, Character, Chat, Message, UserImage, Creation)
├── src/
│   ├── app/
│   │   ├── page.js                      # Dashboard / character selection & builder
│   │   ├── login/page.js                # HF OAuth + API key tabs
│   │   ├── explore/page.js              # Public character marketplace
│   │   ├── pricing/page.js              # Stripe credit packs
│   │   ├── [character_name]/[id]/page.js # Chat studio with streaming + multi-provider model selector
│   │   └── api/
│   │       ├── auth/[...nextauth]/      # NextAuth handler (HF + Credentials)
│   │       ├── characters/              # GET/POST/PATCH (15 defaults + custom)
│   │       ├── chats/                   # GET/POST chat threads
│   │       ├── chats/[id]/messages/     # GET/POST messages → calls provider registry (supports SSE streaming)
│   │       ├── models/                  # GET model catalog grouped by provider
│   │       ├── upload/                  # POST file → HF dataset bucket (or MuAPI fallback)
│   │       ├── images/                  # GET user's upload history
│   │       ├── hf/datasets/             # GET user's HF datasets + files in default repo
│   │       ├── gradio/                  # GET user's HF Spaces · POST probe a Gradio app's API
│   │       ├── user/apikey/             # POST/DELETE custom API key
│   │       ├── checkout/                # POST planId → Stripe checkout
│   │       └── stripe/                  # checkout + webhook (legacy inline)
│   ├── lib/
│   │   ├── auth.js                      # NextAuth config (HF OAuth + Credentials)
│   │   ├── prisma.js                    # PrismaClient + libsql adapter (SQLite)
│   │   ├── config.js                    # App config + provider key map + Stripe plans
│   │   ├── stripe.js                    # Lazy Stripe singleton
│   │   ├── providers/huggingface.js     # HF OAuth2 provider for NextAuth
│   │   ├── ai/
│   │   │   ├── models.js                # 17-model catalog + PROVIDER_META + getModelMeta()
│   │   │   ├── providers.js             # callLLM() — single entry point, routes to adapter
│   │   │   ├── openai.js                # OpenAI SDK + streaming + vision
│   │   │   ├── anthropic.js             # Anthropic SDK + streaming + vision
│   │   │   ├── huggingface.js           # HF Inference (chat-completion) + streaming
│   │   │   ├── groq.js                  # Groq SDK + streaming (ultra-low-latency)
│   │   │   ├── muapi.js                 # Legacy MuAPI gateway (polling-based)
│   │   │   └── gradio.js                # @gradio/client wrapper for custom Spaces
│   │   ├── storage/hf.js                # HFStorage class — wraps @huggingface/hub
│   │   └── services/                    # billing.js, user.js (credit ledger)
│   └── components/                      # Navbar (HF branding), Footer
├── prisma.config.ts                     # Prisma 7 config (datasource URL)
├── next.config.mjs                      # Image remotePatterns for HF + muapi CDN
├── Dockerfile                           # HF Space Docker build
├── .env.example                         # All required env vars
└── dev.db                               # SQLite DB (auto-created on first run)

---

🎯 Quick Start

1. Install dependencies

git clone https://huggingface.co/NeoPy/hugging-c-ai
cd hugging-c-ai
npm install

2. Configure environment

cp .env.example .env

Open .env and fill in:

• HuggingFace OAuth: create at https://huggingface.co/settings/applications/new (callback URL: http://localhost:3000/api/auth/callback/huggingface)
• At least one AI provider key (OpenAI, Anthropic, Groq, or HF_TOKEN)
• (Optional) Stripe keys if you want to sell credits

3. Initialize the database

npx prisma db push
npx prisma generate

This creates a SQLite file at ./dev.db. No external database required!

4. Run the dev server

npm run dev

Open http://localhost:3000, click Continue with HuggingFace, and start chatting.

---

🧩 Adding a New LLM Provider

The provider abstraction is in src/lib/ai/. To add a new provider:

1. Create the adapter at src/lib/ai/<provider>.js:

   export async function callMyProvider({ model, messages, systemPrompt, temperature, maxTokens, stream, apiKey, onToken }) {
     // ... call your LLM SDK
     return { text, usage: { promptTokens, completionTokens } };
   }
   

2. Register it in src/lib/ai/providers.js:

   case "myprovider":
     return callMyProvider({ ... });
   

3. Add models to the catalog in src/lib/ai/models.js:

   { id: "myprovider:my-model", label: "My Model", provider: "myprovider", cost: 1, supportsStreaming: true, contextWindow: 32_000 }
   

4. Add env var mapping in src/lib/ai/providers.js → resolveApiKey() and in src/lib/config.js.

That's it — the model appears in the UI selector automatically.

---

🎨 Themes

Five built-in dark themes via NEXT_PUBLIC_THEME:

• slate-indigo (default)
• cyberpunk (pink/cyan)
• emerald (green)
• sunset (orange)
• midnight (pure B/W)

---

🚀 Deploy to HuggingFace Spaces

1. Click Duplicate to HF Space in the navbar (top-right)
2. In your duplicated Space, set the following secrets:
   • DATABASE_URL — file:./dev.db for SQLite, or a Postgres URL
   • HF_CLIENT_ID, HF_CLIENT_SECRET — your HF OAuth app (callback URL must point to your Space)
   • NEXTAUTH_SECRET — openssl rand -base64 32
   • NEXTAUTH_URL — https://<your-space>.hf.space
   • Provider keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, HF_TOKEN (at least one)
3. Run npx prisma db push && npx prisma generate once (in the Space terminal)

For production at scale, swap SQLite for Postgres by setting DATABASE_URL to a postgresql:// URL and switching the Prisma adapter in src/lib/prisma.js to @prisma/adapter-pg.

---

📜 License

MIT. Upstream credit: Open Character AI.