Isabella

📝 About

Isabella is an AI-powered chatbot with a terminal-style UI, featuring emotion detection capabilities. Built with React + TypeScript frontend and FastAPI backend, powered by LongCat API and advanced ML models for emotion analysis.

🔗 Quick Links

• Demo
• Documentation
• Issues
• Contributing
• Security

📑 Table of Contents

• About
• Quick Links
• Features
• Tech Stack
• Dependencies & Packages
• Installation
• Usage
• API Endpoints
• Folder Structure
• Development
• Environment Variables
• MongoDB Configuration
• Logging
• Contributing
• License
• Security
• Code of Conduct

✨ Features

• 🤖 AI-Powered Chat: Leverages LongCat API for intelligent conversations
• 🎨 Terminal Aesthetic: Black background, green text, monospace font for authentic CLI feel
• 🧠 Thinking Mode Toggle:
  • ON: Uses LongCat-Thinker model (deeper reasoning)
  • OFF: Uses LongCat-Flash-Chat model (faster responses)
• 😊 Emotion Detection: Advanced ML-based emotion analysis using PyTorch and Transformers
• 💾 MongoDB Integration: Persistent chat history storage
• 📜 Chat History: Loads last 50 messages on startup
• 🔄 Context Window: Sends last 10 messages to AI for conversation continuity
• 📊 Comprehensive Logging: Detailed server-side logs for all operations
• 📜 Auto-scroll: Chat window automatically scrolls to show new messages
• 🔊 Text-to-Speech: AI responses spoken using Piper TTS (local, offline)
• ⚡ Single-page Application: No routing, streamlined UX
• 🔒 Type-safe Implementation: Full TypeScript for frontend reliability

🛠 Tech Stack

Languages

Frameworks & Libraries

Databases

DevOps / CI / Tools

📦 Dependencies & Packages

Frontend Dependencies

Runtime Dependencies

• axios ^1.13.2 - Promise-based HTTP client for API requests
• react ^19.2.0 - Core React library
• react-dom ^19.2.0 - React DOM rendering
• react-markdown ^10.1.0 - Markdown rendering in React

Dev/Build/Test Dependencies

• @eslint/js ^9.39.1 - ESLint JavaScript configuration
• @types/node ^24.10.0 - TypeScript definitions for Node.js
• @types/react ^19.2.2 - TypeScript definitions for React
• @types/react-dom ^19.2.2 - TypeScript definitions for React DOM
• @vitejs/plugin-react ^5.1.0 - Vite plugin for React
• eslint ^9.39.1 - JavaScript/TypeScript linter
• eslint-plugin-react-hooks ^5.2.0 - ESLint rules for React Hooks
• eslint-plugin-react-refresh ^0.4.24 - ESLint plugin for React Fast Refresh
• globals ^16.5.0 - Global identifiers from different JavaScript environments
• typescript ~5.9.3 - TypeScript compiler
• typescript-eslint ^8.46.3 - TypeScript ESLint parser and plugin
• vite ^7.2.2 - Next-generation frontend build tool

Backend Dependencies

Runtime Dependencies

• fastapi 0.115.0 - Modern, fast web framework for building APIs
• uvicorn 0.32.0 - ASGI server implementation
• httpx 0.27.2 - Async HTTP client
• python-dotenv 1.0.1 - Environment variable management
• motor 3.3.2 - Async MongoDB driver
• pymongo 4.6.1 - MongoDB driver for Python
• torch >=2.0.0 - PyTorch machine learning framework
• transformers >=4.30.0 - Hugging Face transformers for NLP/ML

🚀 Installation

Prerequisites

• Node.js 18+ and npm
• Python 3.8+
• MongoDB 7.0+ (locally or via Docker)
• Git

Backend Setup

1. Install and start MongoDB:

   # Using Docker (recommended)
   docker run -d -p 27017:27017 --name mongodb mongo:7.0
   
   # Or install MongoDB locally and start it
   # mongod --dbpath /path/to/data

2. Navigate to the backend directory:

   cd backend

3. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

4. Install dependencies:

   pip install -r requirements.txt

5. Create a .env file with your LongCat API key:

   echo "LONGCAT_API_KEY=your_actual_api_key_here" > .env

6. Setup Piper TTS (Optional - for text-to-speech):

   a. Download Piper TTS binary for your platform:

   • Visit: https://github.com/rhasspy/piper/releases
   • Download the appropriate version for your OS
   • Extract and place the piper executable in backend/piper_tts/piper/

   b. Download the en_US-amy-medium voice model:

   • Visit: https://github.com/rhasspy/piper/releases/tag/2023.11.14-2
   • Download en_US-amy-medium.onnx and en_US-amy-medium.onnx.json
   • Place both files in backend/piper_tts/

   See backend/piper_tts/README.md for detailed instructions.

   Note: TTS is optional. The chatbot will work without it.

7. Start the FastAPI server:

   uvicorn main:app --reload --port 5000

   The backend will run at: http://localhost:5000

Frontend Setup

1. Install dependencies:

   npm install

2. Start the development server:

   npm run dev

   The frontend will run at: http://localhost:5173

⚡ Usage

1. Open the frontend in your browser (http://localhost:5173)
2. You'll see a terminal-style interface with:
   • A "Thinking Mode" checkbox at the top
   • A chat window showing conversation history
   • An input box at the bottom for typing messages
3. Toggle "Thinking Mode" to switch between AI models:
   • ✅ ON: Uses LongCat-Thinker (thoughtful, detailed responses)
   • ⬜ OFF: Uses LongCat-Flash-Chat (faster, concise responses)
4. Type your message and press Enter or click SEND
5. The AI response will appear in the terminal window
6. The chat window will automatically scroll to show new messages
7. If TTS is configured, AI responses will be spoken automatically
8. Audio controls appear below each AI message for manual playback

📡 API Endpoints

POST /chat

Send a message to the AI chatbot.

Request Body:

{
  "message": "Your question here",
  "thinking": true
}

Response:

{
  "reply": "AI response here",
  "audio_file": "speech_uuid.wav"
}

GET /messages

Fetch the last 50 messages from chat history.

Response:

{
  "messages": [
    {
      "_id": "...",
      "role": "user",
      "content": "Hello!",
      "timestamp": "2025-11-10T14:02:31.537000",
      "thinking": false,
      "model": "LongCat-Flash-Chat"
    }
  ]
}

POST /tts

Generate speech from text using Piper TTS.

Request Body:

{
  "text": "Text to convert to speech"
}

Response:

{
  "audio_file": "speech_uuid.wav"
}

GET /tts/audio/{filename}

Retrieve a generated audio file.

Response:

• Audio file in WAV format

📂 Folder Structure

Isabella/
├── src/                    # Frontend React application
│   ├── components/
│   │   ├── ChatWindow.tsx
│   │   ├── ThinkingToggle.tsx
│   │   └── IsolateToggle.tsx
│   ├── assets/
│   ├── App.tsx
│   ├── App.css
│   ├── main.tsx
│   └── index.css
├── backend/
│   ├── config/            # Configuration modules
│   │   └── database.py    # MongoDB connection
│   ├── models/            # Data models
│   │   └── chat.py
│   ├── routes/            # API routes
│   │   ├── chat.py
│   │   └── tts.py
│   ├── services/          # Business logic
│   │   ├── chat_service.py
│   │   └── tts_service.py
│   ├── ml_models/         # Machine learning models
│   │   └── emotion_detector_model/
│   ├── datasets/          # Training datasets
│   │   └── emotion_detection_dataset/
│   ├── tests/             # Backend tests
│   │   ├── test_emotion_integration.py
│   │   └── test_timestamp_context.py
│   ├── utils/             # Utilities
│   │   └── logger.py
│   ├── main.py            # FastAPI entry point
│   ├── requirements.txt
│   ├── ARCHITECTURE.md
│   ├── EMOTION_DETECTION.md
│   ├── QUICKSTART_EMOTION.md
│   └── README.md
├── public/
│   └── vite.svg
├── .github/               # GitHub configuration
│   ├── ISSUE_TEMPLATE/    # Issue templates
│   └── pull_request_template.md
├── package.json
├── package-lock.json
├── tsconfig.json
├── tsconfig.app.json
├── tsconfig.node.json
├── vite.config.ts
├── eslint.config.js
├── index.html
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── SECURITY.md
└── CODE_OF_CONDUCT.md

💻 Development

Build Frontend

npm run build

Lint Frontend

npm run lint

Preview Production Build

npm run preview

Run Backend Tests

cd backend
python -m pytest tests/

🔐 Environment Variables

Backend .env

• LONGCAT_API_KEY: Your LongCat API key (required)

🗄 MongoDB Configuration

The application uses MongoDB to store chat history:

• Connection URL: mongodb://127.0.0.1:27017/isabella
• Database: isabella
• Collection: chats

Database Schema

{
  "_id": ObjectId,
  "role": String,          // "user" or "assistant"
  "content": String,       // Message content
  "timestamp": ISODate,    // Message timestamp
  "thinking": Boolean,     // Thinking mode enabled
  "model": String          // AI model used
}

📊 Logging

The backend provides comprehensive logging for debugging and monitoring:

• MongoDB connection status
• All user messages and AI responses
• Context window contents (last 10 messages sent to AI)
• API calls and errors
• Database operations
• Emotion detection results

Check the server console for detailed logs of all operations.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details on:

• How to fork and contribute
• Code style and linting rules
• Bug reporting and feature requests
• Testing and documentation

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🛡 Security

Security is important to us. Please see our Security Policy for information on:

• Reporting vulnerabilities
• Security contact information
• Vulnerability handling process

📏 Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

📝 Notes

• The backend must be running on port 5000 for the frontend to connect properly
• MongoDB must be running on port 27017 (default)
• Update the API URL in App.tsx if deploying to production
• For production use, configure CORS properly in main.py with specific allowed origins
• The terminal styling uses monospace fonts and green (#0f0) text on black (#111) background
• Chat history is automatically loaded when the page loads
• The AI receives the last 10 messages as context for better conversation continuity

---

Made with ❤ by H0NEYP0T-466