Loopback — Relationship Simulation System 🌀

Loopback is a premium, state-of-the-art full-stack web application designed to simulate, visualize, and analyze complex interpersonal communication dynamics between couples.

Powered by advanced clinical psychology frameworks (Attachment Theory, Big Five, conflict styles) and local Large Language Models via Ollama (preferring qwen2.5:7b), Loopback models romantic relationships through a multi-agentic system, allowing users to predict conversational outcomes, trace live emotional tension curves, and build a self-refining knowledge base.

---

🏗️ Project Architecture & Data Flow

Loopback uses a multi-layered agentic pattern to capture, model, and simulate relationships locally and privately:

graph TD
    A[User Inputs: Questionnaire & Socials] -->|POST /api/profile/build| B(Personality Builder)
    B -->|Ollama: qwen2.5:7b| C[Structured Personality Profile]
    C -->|POST /api/profile/analyze-pairing| D(Attachment Pairing Analyzer)
    C -->|POST /api/simulation/start| E(Simulation Engine)
    E -->|Server-Sent Events SSE| F[Live React UI & Tension Curve]
    E -->|Conversation Transcript| G(Conclusion Engine)
    G -->|Therapist Notes & Predicted Trajectory| H[Conclusion Dashboard]
    H -->|POST /api/feedback/submit| I(Knowledge Base Writer)
    I -->|Markdown + Semantic Indexing| J[ChromaDB Vector Store]
    J -->|Context Retrieval| E

Loading

---

📂 Repository Structure & Key Components

Loopback/
├── backend/
│   ├── agents/                   # Psychological Agent Engines
│   │   ├── agent_runner.py       # SimulationRunner & SimTurn model
│   │   ├── conclusion_engine.py  # Post-simulation transcript analysis
│   │   ├── emotional_state.py    # Arousal, valence, openness, defensiveness trackers
│   │   └── personality_builder.py# Dynamic LLM system prompt constructor
│   ├── classifier/               # Context classification & retrieval
│   │   ├── intent_classifier.py  # Decides relevant KB categories
│   │   └── kb_retriever.py       # Fetches relevant MD entries for LLM context
│   ├── knowledge_base/           # Localized psychological pattern database
│   │   ├── attachment-outcomes/  # Anxious-avoidant trapped dynamics
│   │   ├── communication-mismatches/# Literal vs. indirect speech research
│   │   ├── conflict-styles/      # Fight, flee, freeze, fawn pairings
│   │   ├── personality-patterns/ # MBTI / Big Five archetypes
│   │   └── skill-refinements/    # Date-prefixed simulation lessons
│   ├── models/                   # Pydantic schemas for request/response validation
│   ├── routers/                  # FastAPI Endpoints
│   │   ├── feedback.py           # Handles session reviews & KB writing
│   │   ├── knowledge.py          # Exposes KB statistics
│   │   ├── profile.py            # Profile build & pairing compatibility analysis
│   │   └── simulation.py         # Start & SSE streaming routers
│   ├── utils/                    # Core utilities
│   │   ├── kb_writer.py          # Commits dynamic feedback to Markdown files
│   │   ├── ollama_client.py      # Ollama API adapter with auto text-model selection
│   │   └── pattern_refiner.py    # Refines and deduplicates KB patterns
│   ├── main.py                   # FastAPI entrypoint
│   └── requirements.txt          # Python dependencies
│
├── frontend/
│   ├── src/
│   │   ├── api/                  # Axios-based backend communication
│   │   ├── components/           # Reusable UI Blocks (SimulationChat, Questionnaire)
│   │   ├── pages/                # Main screens (Home, BuildProfile, Simulate, Dashboard)
│   │   ├── store/                # Zustand client state management (with partialize filters)
│   │   ├── App.jsx               # Routes and layout
│   │   └── index.css             # Beautiful styles, gradients, glassmorphism config
│   ├── package.json              # Frontend Node dependencies
│   └── vite.config.js            # Vite bundler configuration
│
├── run_loopback.sh               # Single-click orchestration script
└── PROJECT_PLAN.md               # Original implementation specifications

---

🛠️ Step-by-Step Local Setup

1. Prerequisites

Before running the application, make sure you have the following installed on your machine:

• Ollama: Running locally with a dialogue model downloaded (e.g., ollama pull qwen2.5:7b)
• Node.js: v18.0.0 or higher (tested on v20.20.2)
• npm: v9.0.0 or higher
• Python: v3.11.0 or higher (or compatible v3.9+)

2. Local Model Pull (Ollama)

Loopback automatically queries Ollama, filters out vision/embedding models, and auto-selects the best available text-focused model:

ollama pull qwen2.5:7b

3. Backend Setup

Create a Python virtual environment, install the dependencies, and set up your environment variables:

# Navigate to backend
cd backend

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install requirements
pip install -r requirements.txt

Create a .env file in the backend/ directory:

OLLAMA_URL=http://127.0.0.1:11434
CHROMA_DB_PATH=./backend/chroma_db
KB_PATH=./backend/knowledge_base

4. Frontend Setup

Install the Node dependencies:

cd ../frontend
npm install

Create a .env file in the frontend/ directory:

VITE_API_URL=http://localhost:8000

---

🚦 Running the Application

The Simple Way (One-Command Orchestration)

You can boot both the FastAPI backend and the Vite frontend simultaneously using the included runner script in the workspace root:

chmod +x run_loopback.sh
./run_loopback.sh

Running Individually

Start the FastAPI Backend:

source backend/venv/bin/activate
uvicorn backend.main:app --reload --port 8000

Start the Vite Frontend:

cd frontend
npm run dev

Open http://localhost:5173 in your browser.

---

🧠 Core Features & Mechanics

1. Questionnaire & Social Data Parsing: Collects Big Five ratings and communication habits alongside simulated chat logs or social profiles to construct highly customized, attachment-labeled profiles.
2. Dynamic Turn-Phase Prompting: Divides dialogue into 4 phases (Opening, Escalation, Crisis, Turning Point) to emulate authentic escalation arcs instead of repetitive loops.
3. Double-Ended Emotional Tracker: Updates metric values (arousal, openness, valence, defensiveness) live with every speech turn, generating over 15+ rich psychological states (e.g., "vulnerable but uncertain", "cornered & lashing out").
4. Anti-Repetition Engine: Scans historical turns to track themes already discussed and strictly forbids agents from repeating previous arguments.
5. Real-time SSE Streaming: Emits live typing indicators, messages, inner monologues (subtexts), and current tension metrics directly to the React interface.
6. Self-Correcting Knowledge Base: Incorporates real user feedback into Markdown folders (/backend/knowledge_base/) dynamically. A background vector store index (ChromaDB) ensures lessons learned from previous simulations automatically shape subsequent agent behavior.