Spaces:
Running
Running
| title: CharacterChatBot | |
| emoji: 💬 | |
| colorFrom: yellow | |
| colorTo: purple | |
| sdk: gradio | |
| sdk_version: 6.12.0 | |
| app_file: app.py | |
| pinned: true | |
| hf_oauth: true | |
| hf_oauth_scopes: | |
| - inference-api | |
| short_description: A Character-Based Chatbot | |
| # CharacterChatBot | |
| A Gradio-based roleplay chatbot for immersive AI character conversations, built on HuggingFace Spaces. | |
| ## Features | |
| - **Character system** — Personalities, speech styles, and behaviors defined in JSON | |
| - **Three-layer memory** — Session-isolated history, rolling summary, and long-term facts per character | |
| - **Memory controls** — Remember, edit, and forget facts from the sidebar | |
| - **Relationship state** — Four independent axes shown as short phrases; romance and attraction are optional | |
| - **Edit last message** — Revise your last turn and send it again | |
| - **Reply suggestions** — 4 contextual suggestions on demand, using the selected language and persona | |
| - **User persona** — Define who you're playing in the roleplay | |
| - **Action & thought formatting** — `(actions)` and `*thoughts*` rendered distinctly in chat | |
| - **Multi-character support** — Switch characters via sidebar dropdown | |
| ## Project structure | |
| ``` | |
| CharacterChatBot/ | |
| ├── app.py # Gradio UI — layout, events, respond() | |
| ├── requirements.txt | |
| ├── characters/ # One JSON file per character | |
| │ └── jessica_jones.json | |
| ├── engine/ # Core logic (no UI dependencies) | |
| │ ├── chat.py # LLM streaming generator | |
| │ ├── prompt_builder.py # System prompt assembly | |
| │ ├── static_files.py # Bounded static JSON/text cache | |
| │ ├── memory.py # Three-layer memory system | |
| │ ├── memory_controls.py # Manual facts and source exclusions | |
| │ ├── memory_jobs.py # Bounded background extraction | |
| │ ├── parser.py # Action/thought response parser | |
| │ ├── suggestions.py # Reply suggestion generator | |
| │ ├── persona.py # User persona management | |
| │ └── relationship.py # Independent relationship axes | |
| ├── prompts/ # Prompt templates (plain text) | |
| │ ├── system_prompt.txt # Global roleplay + format rules | |
| │ ├── reply_suggestion.txt # Suggestion generation prompt | |
| │ └── memory_prompt.txt # Memory extraction prompt | |
| ├── memory/sessions/ # Auto-created; isolated by browser session | |
| │ └── {session_id}/ | |
| │ └── jessica_jones.json # Atomic snapshot of all memory layers | |
| └── assets/ | |
| └── characters/ | |
| └── jessica_jones/ | |
| └── avatar.png | |
| ``` | |
| ## Character categories | |
| The sidebar first selects a category, then lists characters assigned to it. Categories are configured in each character JSON file using a `categories` array. A character can belong to more than one category (for example, Luke Cage is listed under both Marvel and Marvel Defenders). | |
| To add a category to an existing character, edit `characters/{character_id}.json` and add or update the field at the top level: | |
| ```json | |
| "categories": ["Marvel", "Marvel Defenders"] | |
| ``` | |
| Category names are shown as written and grouped automatically. Use the same spelling and capitalization for characters that belong to the same category. To add a new character, create its JSON file as described below and include a `categories` array. The category appears in the UI automatically; no UI code change is needed. | |
| ## Adding a new character | |
| 1. Create `characters/{character_id}.json`: | |
| ```json | |
| { | |
| "id": "my_character", | |
| "name": "My Character", | |
| "categories": ["My Category"], | |
| "description": "One-line description shown in the selector.", | |
| "identity": { | |
| "role": "Their role or profession", | |
| "background": "Brief backstory" | |
| }, | |
| "personality": ["trait1", "trait2", "trait3"], | |
| "speech_style": { | |
| "tone": ["calm", "precise"], | |
| "formality": "formal", | |
| "sentence_style": "short_to_medium", | |
| "uses_humor": false, | |
| "uses_rhetorical_questions": false, | |
| "avoids_excessive_enthusiasm": true | |
| }, | |
| "behavior": { | |
| "shows_emotions": true, | |
| "deflects_uncomfortable_topics_with_humor": false | |
| }, | |
| "world": { | |
| "universe": "Original", | |
| "setting": "Where they live", | |
| "description": "World context for the LLM." | |
| }, | |
| "roleplay": { | |
| "action_format": "<action>{content}</action>", | |
| "thought_format": "<thought>{content}</thought>", | |
| "break_character": false | |
| }, | |
| "system_prompt": "Character-specific fine-tuning. This adds to global rules, not replaces them.", | |
| "greeting": "The character's opening line when the chat starts.", | |
| "example_dialogues": [ | |
| { | |
| "situation": "Optional context", | |
| "user": "Example user message", | |
| "character": "Example character response" | |
| } | |
| ], | |
| "visuals": { | |
| "avatar": "assets/characters/my_character/avatar.png" | |
| } | |
| } | |
| ``` | |
| 2. Add an avatar image under `assets/characters/{character_id}/`, for example `{character_id}.jpg` or `{character_id}_00.png`. PNG, JPG, JPEG, and WebP are supported. The first available image is used (PNG first, then JPG, JPEG, WebP; filenames sorted within each format). If no image is available, the portrait is hidden. Character images are stored directly in Git so they work in checkouts without Git LFS. | |
| 3. Restart the Space. The character will appear in the sidebar dropdown automatically. | |
| ## Local setup | |
| Requires Python 3.10+; Gradio is pinned to the Space SDK version (6.12.0). | |
| ```bash | |
| git clone https://huggingface.co/spaces/your-username/CharacterChatBot | |
| cd CharacterChatBot | |
| pip install -r requirements.txt | |
| export HF_TOKEN=hf_your_token_here | |
| python app.py | |
| ``` | |
| The app opens at `http://localhost:7860`. | |
| Keep the Gradio pin in `requirements.txt` and this README’s `sdk_version` aligned. | |
| Version 6.12.0 is browser-tested for replacing chatbot history on character changes | |
| and imports; 6.5.1 retained stale message views in these tests. | |
| ## HuggingFace Space deployment | |
| 1. Push your changes to the Space repository. | |
| 2. Go to **Settings → Variables and secrets → New secret**. | |
| 3. Name: `HF_TOKEN`, Value: your HuggingFace API token. | |
| 4. The Space restarts automatically and picks up the secret. | |
| ## Memory system | |
| Each browser session has its own per-character snapshot under | |
| `memory/sessions/{session_id}/{character_id}.json`. The session key is derived | |
| from Gradio's request context, never accepted from an uploaded save file. | |
| Switching characters restores that session's complete visible conversation. | |
| Clearing the chat clears its transcript, summary, facts, exclusions, and relationship state. Retry and | |
| undo update the same history the model uses; changing already-summarized content | |
| invalidates its derived memory. | |
| The complete transcript is retained for display and export. Once the unsummarized | |
| history exceeds 20 messages (not 20 user/assistant pairs), a batch of about 10 older | |
| messages is summarized **after the answer is displayed**. When extraction falls | |
| behind, a batch can grow to 40 messages (plus one to keep a reply with its user turn). This periodic model | |
| call also extracts long-term facts and relationship developments. Subsequent prompts | |
| contain the cumulative summary, up to 40 automatic facts plus 60 manually pinned | |
| facts, relationship context, and the remaining recent messages. | |
| Extraction runs in a background pool with at most two jobs across the app and | |
| one per conversation. The chat request completes without waiting for extraction. | |
| There is no growing job queue: if the pool is busy, messages remain intact and | |
| scheduling is tried after a later response. The same retry policy applies to | |
| extraction errors. | |
| Before committing, a worker checks a separate memory revision, its original | |
| transcript prefix, and the summary it started from. Appending completed turns | |
| does not invalidate extraction; only derived fields are merged into the newer | |
| conversation. Edits, resets, imports, and memory/relationship setting changes | |
| still invalidate pending work. | |
| Memory-only updates do not advance the transcript revision. A response being | |
| streamed can therefore append to the current snapshot without losing a summary | |
| that finished in the meantime. Recent model context has a fallback limit of 40 | |
| messages and 24,000 characters so a slow or failed summary cannot make it grow | |
| without bound. Older unsummarized turns can temporarily be omitted, and an | |
| oversized final message is clipped with an explicit marker. These limits apply | |
| to recent history, not the system prompt or current user input. The full transcript | |
| remains available for display, later summarization, and export. Invalid relationship | |
| observations are discarded without discarding an otherwise valid summary. | |
| Storage is isolated by browser session, not an authenticated user account. | |
| Refreshing the page or opening a new browser session starts fresh; use **Save / | |
| Load** to resume later. Legacy shared `memory/{character_id}` files are never | |
| loaded automatically because their owner is unknown. Existing version 1.0 and 2.0 save | |
| files can still be imported explicitly into the current session. | |
| Save files use version 3.0 and include the full visible transcript, persona, | |
| summary, facts and their sources, summary position, memory exclusions, and | |
| relationship options and events. Imports validate the entire file before | |
| writing: known character ID, supported version, text-only user/assistant | |
| messages, memory importance and provenance, relationship events, field lengths, | |
| and a 4 MB file limit. Exports have | |
| unique filenames. Each snapshot is replaced atomically; in-process revision | |
| checks protect concurrent writes in the standard single-process Gradio app. | |
| Deployments with multiple app processes would require a shared transactional | |
| store instead of this file backend. | |
| Translation is off by default in both the UI and backend. The main model streams | |
| in the selected language. If translation is enabled explicitly, the displayed | |
| translation is also the persisted conversation, so reload and subsequent context | |
| match what the user saw. | |
| Reply suggestions remain opt-in through the **Suggest replies** button. Their | |
| single model call receives the selected language and the applied user persona. | |
| On failure, four neutral fallback suggestions are returned in the selected UI | |
| language without another model call. Changing language, persona, character, or | |
| conversation clears the old suggestion buttons. | |
| ## Memory controls and editing | |
| Open **Memories** to add a fact with **Remember**, or select a saved fact to | |
| **Update selected** or **Forget selected**. Manual facts are pinned and automatic | |
| extraction cannot overwrite them. Editing or forgetting invalidates pending | |
| extraction, clears the summary for rebuilding, and excludes the fact's recorded | |
| source messages and verbatim echoes from future model context. The visible | |
| transcript remains unchanged. Other automatic facts and relationship events | |
| sharing those sources are removed too. | |
| Forgetting is source-based, not guaranteed semantic erasure: paraphrases elsewhere | |
| or separately pinned facts can still contain the information. Exact normalized | |
| re-extraction is blocked; explicitly remembering the same text removes that block. | |
| **Edit last message** removes the last user turn and its reply, puts that user's | |
| text back in the input, and rolls back derived memory from the removed portion. | |
| Edit the text and send it to generate a new answer. The existing retry action | |
| regenerates an answer without changing your message. Previous replies are not | |
| saved as alternate branches. | |
| ## Relationship state | |
| Trust, familiarity, romantic closeness, and sexual attraction develop independently. | |
| Romance and attraction are individually opt-in for each character in the session; | |
| disabling an axis clears its recorded developments. Low trust or familiarity does | |
| not prevent romance or attraction, and no fixed relationship route is enforced. | |
| The state describes the character's attitude toward the user persona and does not | |
| assume reciprocal feelings or override the character's personality and motivations. | |
| The sidebar shows short phrases rather than scores (Turkish and English labels; | |
| other languages currently use English). Changes are extracted with the periodic | |
| summary call, so they appear after batches of older messages are processed, not | |
| after every turn. The panel checks local state every ten seconds without making | |
| model calls. Source-linked events allow edits and retries to roll back affected | |
| developments and prevent counting the same extraction twice. Save / Load preserves | |
| this state; older saves begin with optional axes disabled. | |
| ## Static file cache | |
| Character JSON and the system, reply-suggestion, and memory-extraction prompt | |
| files are cached in process RAM (up to 64 entries, least recently used eviction). | |
| Each access checks file metadata; edits and atomic replacements refresh the | |
| entry. Missing or invalid files raise errors instead of silently reusing old | |
| content. Character data is deep-copied for each caller to avoid shared mutations. | |
| The cache is protected by a lock for chat and background worker access. | |
| Conversation history, personas, summaries, and user memories are not cached here. | |
| This saves local file reads and JSON parsing only; model calls and token usage | |
| remain unchanged. Restarting the process clears the cache. | |
| ## Tests | |
| ```bash | |
| python -m unittest discover -s tests -v | |
| ``` | |
| Tests use temporary storage and fake inference clients; they make no model calls. | |
| They cover session isolation, import validation, full-history roundtrips, | |
| summary extraction and failures, stale writes, translation, and Gradio event | |
| processing for character switching and streaming, manual memory controls, | |
| independent relationship axes, source rollback, and last-message editing. | |
| ## Configuration | |
| In `app.py`, two constants control the active character and model: | |
| ```python | |
| DEFAULT_CHARACTER = "hermione_granger" # must match a file in characters/ | |
| DEFAULT_MODEL = MODELS[4][1] # selected initial model | |
| ``` | |
| Supported models include anything available on the HuggingFace Serverless Inference API — for example `openai/gpt-4o-mini`, `deepseek-ai/DeepSeek-V3`, or `mistralai/Mistral-7B-Instruct-v0.3`. | |