AI Matchmaker：学习型 AI 相亲代理人平台

Language: English | 中文

Competition Materials / 比赛材料

• 项目提案 Specs
• 复赛提交检查清单
• 复赛原型说明
• 项目说明
• 初赛提交材料

---

English

A learning AI dating proxy agent platform for the social/matchmaking domain. Each user gets an AI agent that learns their personality, preferences, values, and relationship goals over time, participates in agent-to-agent matchmaking simulations, identifies knowledge gaps, and produces explainable compatibility reports.

Quick Demo (Wave 2 Submission)

The standalone submission package requires no database or LLM API key:

cd wave2_submission_final
py server.py
# Open http://127.0.0.1:7860

Run smoke tests:

py smoke_test.py

Core Concept

AI Matchmaker is not a simple chatbot or tag-based matching tool. It creates a learning dating proxy agent for each user that:

• Learns the user's personality, preferences, values, communication style, boundaries, and relationship goals through conversation
• Participates in agent-to-agent simulated matchmaking on the user's behalf
• Identifies knowledge gaps during matchmaking and generates targeted follow-up questions
• Writes user answers back into a structured memory database
• Produces explainable compatibility reports with match reasons, risk points, suggested questions, and next steps

Skills (S1-S7)

The project implements 7 core Skills required by the competition:

Skill	Description	Implementation
S1	Create AI dating proxy from user profile	create_agent() / UserAvatarAgent
S2	Extract structured memory from natural language	extract_memory() / LLM-based extraction
S3	Agent-to-agent simulated matchmaking	simulate_agent_match() / ConversationOrchestrationService
S4	Select and simulate relationship scenarios	select_relationship_scenario() + simulate_relationship_scenario()
S5	Identify profile gaps and generate follow-up questions	identify_knowledge_gaps() / knowledge gap tracking
S6	Write user answers into long-term memory	update_memory_from_answer() / UserMemoryFact
S7	Output explainable compatibility report	generate_compatibility_report() / CompatibilityService

Features

• Interactive Personality Assessment: Comprehensive questionnaire with 7 trait dimensions
• Learning Dating Proxy Agents: AI representatives learn from user conversations and agent-to-agent simulations
• Adaptive User Memory: Continuously refine user preferences, values, boundaries, and relationship goals
• Agent-Generated Follow-up Questions: Agents identify missing profile details and ask targeted questions
• Relationship Scenario Simulation: AI agents navigate realistic scenarios (financial, family, conflict resolution)
• Live Matching Theater: Real-time visualization of agent-to-agent conversations
• Explainable Compatibility Reports: Match reasons, risk points, suggested questions, and next steps
• Real-time Communication: WebSocket-powered live updates and notifications
• Internationalization: 6 languages (English, Spanish, French, German, Chinese, Japanese)
• Modern Web Interface: Responsive React application with Material-UI

Architecture

Frontend

• React 18 with TypeScript
• Vite for fast development and building
• Material-UI (MUI) for component library
• Redux Toolkit for state management
• Socket.IO for real-time communication
• i18next for internationalization (6 languages)

Backend

• FastAPI with Python 3.11+
• PostgreSQL for relational data
• Redis for caching and sessions
• SQLAlchemy 2.0 with async support
• WebSocket for real-time features
• JWT authentication

AI & Agents

• AgentScope framework for multi-agent orchestration
• Anthropic Claude API as primary LLM (configurable endpoint)
• Mem0 for advanced memory management
• ChromaDB for vector storage
• User Memory Database for continuously improving each user's dating proxy agent

Development Setup

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL database
• Redis

Quick Start (Windows)

1. Clone and set up:

   git clone <repository-url>
   cd matchmaking
   scripts\setup-dev.bat
   

2. Configure environment:

   • Copy .env.example to .env
   • Set DATABASE_URL, REDIS_URL, and ANTHROPIC_API_KEY

3. Start development servers:

   scripts\start-dev.bat
   

4. Access:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Docs: http://localhost:8000/docs

Manual Setup

# Backend
py -m venv venv && venv\Scripts\activate && pip install -r requirements.txt
cd backend && py -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Frontend (another terminal)
cd frontend && npm install && npm run dev

Docker

docker-compose up -d                        # Development
docker-compose -f docker-compose.prod.yml up -d  # Production

Project Structure

matchmaking/
├── frontend/                    # React TypeScript frontend
│   └── src/
│       ├── components/          # ~40+ reusable UI components
│       ├── pages/               # 18 page components
│       ├── store/               # Redux store and slices
│       ├── hooks/               # Custom React hooks
│       └── i18n/                # 6 language translations
├── backend/                     # FastAPI backend
│   ├── app/
│   │   ├── api/v1/endpoints/    # 12 API route modules
│   │   ├── core/                # Config, database, LLM client, security
│   │   ├── models/              # SQLAlchemy models
│   │   ├── services/            # 12 service modules
│   │   └── websocket/           # WebSocket manager and events
│   └── main.py
├── wave2_submission_final/      # Standalone Wave 2 submission (no DB/LLM needed)
│   ├── server.py                # Interactive demo server
│   ├── index.html               # Demo UI
│   ├── ai_matchmaker/           # Skills implementation (S1-S7)
│   └── smoke_test.py            # Smoke tests
├── config/                      # Mem0 configuration
├── scripts/                     # Setup and deployment scripts
├── tests/                       # Test suites
├── docker-compose.yml           # Development Docker Compose
├── docker-compose.prod.yml      # Production Docker Compose
├── SPECS.md                     # Competition Specs
└── .env.example                 # Environment variable template

Testing

make test             # All tests
make test-frontend    # Frontend tests (Vitest)
make test-backend     # Backend tests (pytest)

License

MIT License - see LICENSE for details.

中文

一个面向社交/婚恋匹配场景的学习型 AI 相亲代理人平台。系统为每个用户创建 AI 代理，代理通过用户对话、代理间模拟相亲和关系场景模拟持续学习用户偏好、价值观、边界感和关系目标。当代理发现画像缺口时，会主动生成追问并将用户回答写入记忆数据库，最终输出可解释的兼容性报告。

快速演示（复赛提交包）

独立提交包，无需数据库和 LLM API Key 即可运行：

cd wave2_submission_final
py server.py
# 打开 http://127.0.0.1:7860

运行冒烟测试：

py smoke_test.py

核心理念

AI Matchmaker 不是简单的聊天机器人或标签匹配工具，而是一个会学习的相亲代理人：

• 通过对话逐步学习用户的人格特征、择偶偏好、价值观、沟通方式、边界感和关系目标
• 代表用户参与代理间模拟相亲
• 在匹配过程中发现画像缺口，主动生成针对性追问
• 将用户回答写入结构化记忆数据库
• 输出可解释的兼容性报告，包含匹配理由、风险点、建议问题和下一步建议

Skills 技能 (S1-S7)

项目实现了比赛要求的 7 个核心 Skills：

Skill	说明	实现
S1	基础画像生成 AI 相亲代理人	create_agent() / UserAvatarAgent
S2	自然语言画像抽取为结构化记忆	extract_memory() / LLM 抽取
S3	双代理模拟相亲对话	simulate_agent_match() / ConversationOrchestrationService
S4	关系场景选择与模拟	select_relationship_scenario() + simulate_relationship_scenario()
S5	识别画像缺口并生成追问	identify_knowledge_gaps() / knowledge gap tracking
S6	用户回答写入长期记忆	update_memory_from_answer() / UserMemoryFact
S7	输出可解释兼容性报告	generate_compatibility_report() / CompatibilityService

功能特性

• 交互式人格测评：7 维度人格特征评估
• 学习型相亲代理人：AI 代理从用户对话和代理间模拟中持续学习
• 自适应用户记忆：长期沉淀用户偏好、价值观、边界感和关系目标
• 代理生成追问：代理发现画像缺口后向用户提出针对性问题
• 关系情景模拟：AI 代理在真实场景（财务、家庭、冲突解决）中推演兼容性
• 实时匹配剧场：可视化展示代理间实时对话过程
• 可解释兼容性报告：匹配理由、风险点、建议问题和下一步建议
• 实时通信：基于 WebSocket 的实时更新和通知
• 国际化：支持 6 种语言（英/西/法/德/中/日）
• 现代 Web 界面：React + Material-UI 响应式前端

技术架构

前端

• React 18 + TypeScript
• Vite：快速开发和构建
• Material-UI (MUI)：组件库
• Redux Toolkit：状态管理
• Socket.IO：实时通信
• i18next：国际化（6 种语言）

后端

• FastAPI + Python 3.11+
• PostgreSQL：关系型数据存储
• Redis：缓存和会话
• SQLAlchemy 2.0：异步数据库访问
• WebSocket：实时功能支持
• JWT：身份认证

AI 与智能体

• AgentScope：多智能体编排框架
• Anthropic Claude API：主要 LLM（可配置端点）
• Mem0：高级记忆管理
• ChromaDB：向量存储
• 用户记忆数据库：持续完善每个用户的相亲代理人

开发环境搭建

前置要求

• Python 3.11+
• Node.js 18+
• PostgreSQL 数据库
• Redis

快速开始（Windows）

1. 克隆并初始化：

   git clone <repository-url>
   cd matchmaking
   scripts\setup-dev.bat
   

2. 配置环境变量：

   • 复制 .env.example 为 .env
   • 填入 DATABASE_URL、REDIS_URL 和 ANTHROPIC_API_KEY

3. 启动开发服务：

   scripts\start-dev.bat
   

4. 访问应用：

   • 前端：http://localhost:3000
   • 后端 API：http://localhost:8000
   • API 文档：http://localhost:8000/docs

手动启动

# 后端
py -m venv venv && venv\Scripts\activate && pip install -r requirements.txt
cd backend && py -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 前端（另一个终端）
cd frontend && npm install && npm run dev

Docker 部署

docker-compose up -d                        # 开发环境
docker-compose -f docker-compose.prod.yml up -d  # 生产环境

项目结构

matchmaking/
├── frontend/                    # React TypeScript 前端
│   └── src/
│       ├── components/          # 40+ 可复用 UI 组件
│       ├── pages/               # 18 个页面组件
│       ├── store/               # Redux store 和 slices
│       ├── hooks/               # 自定义 React hooks
│       └── i18n/                # 6 种语言翻译
├── backend/                     # FastAPI 后端
│   ├── app/
│   │   ├── api/v1/endpoints/    # 12 个 API 路由模块
│   │   ├── core/                # 配置、数据库、LLM 客户端、安全
│   │   ├── models/              # SQLAlchemy 模型
│   │   ├── services/            # 12 个服务模块
│   │   └── websocket/           # WebSocket 管理器和事件
│   └── main.py
├── wave2_submission_final/      # 独立复赛提交包（无需数据库/LLM）
│   ├── server.py                # 交互式演示服务
│   ├── index.html               # 演示 UI
│   ├── ai_matchmaker/           # Skills 实现 (S1-S7)
│   └── smoke_test.py            # 冒烟测试
├── config/                      # Mem0 配置
├── scripts/                     # 部署脚本
├── tests/                       # 测试套件
├── docker-compose.yml           # 开发 Docker Compose
├── docker-compose.prod.yml      # 生产 Docker Compose
├── SPECS.md                     # 比赛提案 Specs
└── .env.example                 # 环境变量模板

测试

make test             # 全部测试
make test-frontend    # 前端测试 (Vitest)
make test-backend     # 后端测试 (pytest)

许可证

MIT License - 详情请查看 LICENSE。