README.md

---
license: mit
tags:
  - nextjs
  - multi-provider
  - openai
  - anthropic
  - huggingface
  - groq
  - gradio
  - character-ai
  - chat
  - roleplay
  - hugging-c-ai
---

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

> Forked & heavily upgraded from [Open Character AI](https://github.com/Anil-matcha/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](https://huggingface.co/blog/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

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

### 2. Configure environment

```bash
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

```bash
npx prisma db push
npx prisma generate
```

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

### 4. Run the dev server

```bash
npm run dev
```

Open [http://localhost:3000](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`:
   ```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`:
   ```js
   case "myprovider":
     return callMyProvider({ ... });
   ```

3. **Add models** to the catalog in `src/lib/ai/models.js`:
   ```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](https://github.com/Anil-matcha/open-character-ai).