---
title: Velra Intelligent Dating
emoji: 💖
colorFrom: pink
colorTo: purple
sdk: docker
app_port: 7860
---

# 💖 Velra – AI Relationship Co-Pilot

Velra is an elite AI-powered psychological profiler for modern dating. It analyzes text conversations and chat screenshots, predicts emotional compatibility, detects contradictions, and provides actionable relationship advice without using generic therapy terminology.

---

## 🚀 Features

- 💬 **Chat + Screenshot Analysis:** Upload raw text or screenshots (powered by OCR)
- 🧠 **Elite Emotional Intelligence:** Extracts true intent, power dynamics, and emotional asymmetry.
- ⚠️ **Risk & Contradiction Detection:** Calls out discrepancies between what people say and what they do.
- 🎯 **Perspective-Aware Strategy:** Adjusts advice based on exactly what *you* want (casual, commitment, detachment).
- 💘 **Actionable Replies:** Generates exactly calibrated text messages to send.
- 🤖 **Multi-Agent System:** Powered by specialized AI agents for Analysis, Psychology, and Strategy.

---

## 📂 Project Structure

```text
velra/
│
├── frontend/
│   ├── app.py              # Main Streamlit UI entry point
│   ├── shared.py           # Shared UI components and logic
│   └── pages/
│       └── results.py      # Result visualization page
│
├── backend/
│   ├── app.py              # FastAPI server handling agent orchestration
│   ├── core/               # App configuration and logging
│   ├── llm/                # LLM factory and provider setup
│   ├── services/           # External services (OCR engine)
│   ├── utils.py            # JSON parsing and utilities
│   └── agents/             # Core AI Multi-Agent Architecture
│       ├── perspective.py  # Fast perspective and role identification
│       ├── analyst.py      # Behavioral analysis and screenshot grounding
│       ├── psychology.py   # Attachment, intent alignment, and dynamics
│       └── strategy.py     # High-value, objective-based action plans
│
├── requirements.txt        # Python dependencies
├── .env                    # Environment variables (Keys & Providers)
└── README.md               # Project documentation
```

---

## 🧠 Architecture Flow

`Frontend (Streamlit) → Backend (FastAPI) → OCR Engine (Tesseract) → Agents (Perspective → Analyst + Psychology → Strategy) → LLM Inference (AMD/OpenAI)`

---

## ⚙️ Setup & Local Development

### 1. Create Environment

```bash
python -m venv velra_env
# Windows:
velra_env\Scripts\activate
# Mac/Linux:
source velra_env/bin/activate
```

### 2. Install Dependencies

```bash
pip install -r requirements.txt
```

### 3. Setup Environment Variables

Create a `.env` file in the root directory:

```env
LLM_PROVIDER=openai
MODEL_NAME=gpt-4o-mini
OPENAI_API_KEY=your_api_key_here
```

### 4. Run the Backend (FastAPI)

```bash
uvicorn backend.app:app --reload
```

### 5. Run the Frontend (Streamlit)

Open a new terminal window, activate the environment, and run:

```bash
streamlit run frontend/app.py
```

---

*Note: If deploying to Hugging Face Spaces, the platform will automatically read the `app_file` parameter in the header and launch the Streamlit frontend. The backend FastAPI logic is currently separated; for a pure single-container HF Space, ensure both services run or migrate the backend logic into the Streamlit lifecycle if needed.*