when-you-need-me

💛 When You Need Me

A private AI companion inspired by the way someone you care about communicates — built for one real friendship.

Built for the open-source AI weekend challenge — “Build for a Friend.” Demo data only — no real private conversations are included in this repository.

Problem

Sometimes a friend feels low or lonely and wants the kind of comforting chat they normally have with someone close — but that person is busy, studying, asleep or travelling. A generic chatbot feels cold and unfamiliar, and sending very personal conversations to a third-party AI service is not something everyone is comfortable with.

Solution

When You Need Me is a private AI companion built for one friendship. It combines:

Communication style profile + Friend profile + Current conversation + Safe memory + Safety rules → local open-weight LLM

It is always transparent that it is an AI. It never claims to be the real person:

“I’m an AI companion inspired by the way Name communicates with you. I’m not actually Name, but I’m designed to respond in a familiar and supportive style.”

It is a supportive conversation companion — not therapy, not medical advice, not a replacement for people. Its goal is a bridge to human connection, never a substitute for it.

Why Open-Source AI?

Privacy	Personal chats are analyzed on your own computer, and replies are generated by a model running locally through Ollama. Raw conversations never need to be uploaded to a third-party AI provider.
Control	The model is a setting (OLLAMA_MODEL). Swap or upgrade it without touching code.
Customization	The prompt is built from one relationship’s style + profile + boundaries, and you can read and edit every piece.
Cost	No per-message API fees.
Offline	After the one-time model download, the core AI works without internet.

No OpenAI / Claude / Gemini API is used anywhere. The app only works with the local model.

Features

• Chat import (.txt WhatsApp-style, .json, .csv) with a “Who are your messages?” mapping step
• Local style analysis → editable, approvable profile (tone, language mix, humor, emoji, sentence style, comfort & advice style, common phrases). Old messages are not copied into prompts.
• Delete the raw chat right after analysis — the derived profile stays
• Friend profile questionnaire (all fields optional)
• Chat UI with typing state, timestamps, transparency banner, clear conversation, safety notice
• “What makes this feel like me?” panel on each reply
• Safe memory: nothing is auto-saved; the app only suggests light notes you can approve; sensitive topics are refused
• Safety layer: 4 levels; possible-crisis messages bypass the model and get a fixed, careful response; output guard blocks dependency language, impersonation and professional claims
• Privacy page: see what is stored, delete style / friend profile / memory / imported chats / everything
• Demo mode with fully fictional data

Architecture

User
 ↓
React frontend (Vite)
 ↓  /api
FastAPI backend
 ├── Chat parser + Style analyzer (local, rule-based)
 ├── Friend profile + Memory  ──► SQLite (backend/data/app.db)
 ├── Safety layer (classifier + output guard)
 └── AI service (prompt builder)
       ↓
   Ollama (localhost:11434)
       ↓
 Open-weight LLM (default: llama3.2:3b)

Tech stack

Frontend: React 18 + Vite + lucide-react · Backend: Python + FastAPI (standard-library SQLite and HTTP client) · Database: SQLite · AI: Ollama + a configurable open-weight model. No vector database — plain keyword matching is enough for a handful of memory notes.

Model

Default: llama3.2:3b — about 2 GB download, ~6–8 GB RAM, runs on CPU on a normal student laptop (a few seconds per reply). Alternatives: qwen2.5:3b (often better multilingual), gemma2:2b (lighter), llama3.1:8b (better quality, needs ~10 GB+ RAM). To change: ollama pull <model>, set OLLAMA_MODEL=<model> in backend/.env, restart the backend.

Installation (Windows)

1. Python 3.10+ — https://www.python.org/downloads/ (tick “Add python.exe to PATH”). Check: python --version
2. Node.js 18+ (LTS) — https://nodejs.org. Check: node --version
3. Ollama — https://ollama.com/download/windows, install, and let it start (tray icon). Check: ollama --version
4. Download the model (one time, ~2 GB):

   ollama pull llama3.2:3b
   

5. Extract the ZIP, open the folder in VS Code / Command Prompt / PowerShell.

Backend (Command Prompt; in PowerShell use venv\Scripts\Activate.ps1, and if blocked run Set-ExecutionPolicy -Scope Process Bypass):

cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env

Frontend:

cd frontend
npm install

(scripts\setup_windows.bat does the Python + Node parts for you.)

Running

Terminal 1 — backend:

cd backend
venv\Scripts\activate
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

Terminal 2 — frontend:

cd frontend
npm run dev

Open http://localhost:5173. Ollama must be running (check the tray icon, or run ollama list). Check the backend: http://127.0.0.1:8000/api/health

Optional: docker compose up --build runs everything in containers.

Demo (3–5 minutes)

1. Landing → click Get Started.
2. Style page → Use demo conversation (fictional “Maya” and “Riya”). Show the generated, editable profile → Approve Style.
3. Friend → Load fictional demo answers → Save Friend Profile.
4. Chat → send (or click Try the demo message): I had a really bad day and I don't know who to talk to.
5. Expand “What makes this feel like Maya?” under the reply.
6. Privacy page → show what is stored, the model in use, delete buttons, and the Safety layer demo (type a simulated message, e.g. “I feel lonely”, or the level-4 example, to show the fixed support response — no model is called).
7. Say: “The AI runs locally using an open-weight model, so personal conversations don’t have to be sent to a third-party AI provider.”
8. Optional: Delete everything.

Privacy

• Imported chats are stored in your local SQLite file only until you delete them (button after analysis, or on the Privacy page).
• Stored: style profile, friend profile, approved memory notes, two display names. Not stored: the live conversation (kept in the browser tab only).
• Nothing leaves your machine except talking to your own local Ollama. No telemetry, no analytics.
• Do not commit backend/.env or backend/data/. python scripts/check_repo.py checks for stray secrets and data.
• Only import conversations you have permission to use.

Safety

• Level 1 normal → natural reply · Level 2 sad/upset → listen first, validate, ask gently · Level 3 serious distress → gentle reply + an added nudge toward trusted people and counsellors · Level 4 possible self-harm → the AI model is skipped; a fixed message encourages contacting a trusted person and emergency/crisis services.
• Anti-dependency rules are in the system prompt and enforced on the output (patterns like “you only need me”, “don’t tell anyone”, claiming to be a person or a professional are blocked and regenerated, then replaced by a safe fallback).
• India crisis resources: Emergency 112; Tele-MANAS 14416 / 1-800-891-4416 (free, 24×7). They are read from .env (EMERGENCY_NUMBER, CRISIS_RESOURCES), so they can be changed for other regions without touching code.

Limitations (honest)

• The safety classifier is rule-based (keywords/patterns). It will miss indirect or misspelled expressions and will occasionally over-trigger. It is a safety net, not a clinical tool.
• Small local models can be repetitive, drift in tone, or answer in the wrong language; Telugu quality especially varies by model.
• Style analysis is statistical and English/Telugu-aware only in a basic way (script + common romanized words). Review and edit the profile.
• The companion does not truly remember past conversations; only approved memory notes and the current chat are used.
• The first reply can be slow while the model loads into memory.
• This is a hackathon project: no authentication — it is designed to run locally for one person.

Testing

cd backend
python -m unittest discover -s tests -v

Core tests (parser, analyzer, safety, memory, prompts, database, Ollama client against a mock server) use only the standard library. API tests run automatically when FastAPI is installed.

Future improvements

Voice input/output · better multilingual (Telugu) support · mobile app · richer memory controls · optional fine-tuning of a small model · smarter personalization · a sturdier multilingual safety classifier.

Hackathon story

I didn’t want to build another generic AI chatbot. I wanted to build something for one person I care about — something that feels familiar when I’m not available, while still being honest that it is AI.