MAY is a calm, supportive, and privacy-first AI companion that runs locally on your machine. It combines a lightweight FastAPI backend (model inference) with a modern React + TypeScript frontend and an optional Capacitor mobile wrapper.

• Backend: FastAPI (Python) serving a GPT-2 based persona model via PyTorch + Hugging Face Transformers.
• Frontend: React + TypeScript + Vite, styled with Tailwind CSS and DaisyUI.
• Mobile: Capacitor integration for Android (same web codebase).
• Local-first: Model weights are downloaded on first run; no cloud inference by default.

• Persistent persona injected into every session (see backend/may_persona.py).
• Context management to stay within GPT-2 token limits (sliding/window trimming).
• Safe defaults tuned for stability: temperature, repetition penalty, and n-gram blocking.
• Simple REST API (/chat, /reset) used by both web and mobile clients.

• Backend: Python, FastAPI, Uvicorn
• ML: PyTorch, Hugging Face Transformers (model: af1tang/personaGPT)
• Frontend: React (TSX), TypeScript, Vite, Tailwind CSS, DaisyUI, Lucide icons
• Client HTTP: Axios (frontend uses http://localhost:8000 as base URL)
• Mobile: Capacitor (Android)

may-personal-chatbot/
├─ backend/                # FastAPI server + persona + model loading
│  ├─ main.py
│  └─ may_persona.py
├─ frontend/               # React + TypeScript + Vite app
│  └─ src/
├─ mobile/                 # Capacitor wrapper for mobile builds (Android)
└─ README.md               # <-- this file

• Python 3.8+ (recommended 3.10+)
• Node.js 18+ / npm 8+ (for frontend & mobile)
• Optional: NVIDIA GPU with CUDA for faster model inference (PyTorch will use CUDA if available)
• Disk: model weights download ~200–1,000 MB depending on model and caching

# (Recommended) create and activate a venv
python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# or Windows CMD
.\.venv\Scripts\activate.bat

cd backend
# Install minimal requirements listed; add torch & transformers
pip install -r requirements.txt
pip install torch transformers

# Start the backend (or use uvicorn directly)
python main.py
# or
uvicorn main:app --reload --port 8000

Notes:

• The first run will download the model weights from Hugging Face (expect a sizeable download).
• Backend default address: http://localhost:8000.

cd frontend
npm install
npm run dev

• Vite dev server typically runs at http://localhost:5173 (frontend communicates with backend at http://localhost:8000 via Axios instance in src/api.ts).

To build the native Android application:

• Ensure Android Studio is installed.

• Update the API base URL in frontend/src/api.ts to your machine's local IP address if testing on a physical device.

cd mobile
npm install
# Sync with Capacitor and open Android Studio
npx cap sync android
npx cap open android

Build & run from Android Studio (use a device or emulator). The mobile app is a thin Capacitor wrapper around the same web code.

• GET / — health check
• POST /chat — body: { "text": "Hello", "session_id": "default" } → returns { response, session_id }
• POST /reset — body: { "session_id": "default" } → resets session history to persona

Example curl:

curl -X POST "http://localhost:8000/chat" -H "Content-Type: application/json" -d '{"text":"Hello","session_id":"dev"}'

• Persona is defined in backend/may_persona.py and injected at session start.
• Context trimming: model uses a sliding/trimming strategy to keep tokens under GPT-2 limits (1024 tokens).
• Generation parameters (tuned for stability): temperature=0.7, repetition_penalty=1.2, no_repeat_ngram_size=3, top_k/top_p sampling.
• In-memory session storage: memory_db is ephemeral (restart clears history). For persistent memory, consider SQLite, Redis, or a file-based store.

• Slow inference / OOM on CPU: try reducing max_length or run with a GPU.
• Model download fails: check network or Hugging Face access policies.
• Port conflicts: adjust uvicorn port or frontend VITE_PORT if needed.

Contributions welcome — open issues or PRs for:

• Persistent session storage
• Optional model variants (quantized or smaller for low-resource devices)
• Improved QA and test coverage

Author: Kaushik Tambe

Distributed under the MIT License. See LICENSE for more information.

Thank you for keeping MAY local, private, and calm.

If you want help running the app or adding features, open an issue or reach out via the repository contact info.