🤖 Intelligent Event Matchmaker

Intelligent matchmaking system for event attendees powered by AI, semantic search, and tool-based orchestration.

---

🏆 Overview

Intelligent Event Matchmaker helps event participants discover high-quality, relevant connections by understanding intent, analyzing profiles, and generating personalized introductions.

Unlike traditional filtering systems, this solution uses:

• AI-driven intent understanding
• Semantic similarity search
• Structured match scoring
• Automated outreach generation

---

🚀 Key Features

• 🤖 AI Agent with Tool Orchestration
• 🔍 Semantic Search (pgvector)
• 🧠 Hybrid Match Scoring Engine
• ✉️ Personalized Intro Message Generator
• ⚡ RESTful API (NestJS)
• 🧪 End-to-End Testing (Jest)
• 📊 Load Testing (k6)

---

🧱 Tech Stack

Layer	Technology
Backend	NestJS (Node.js 20)
Database	PostgreSQL + pgvector
ORM	TypeORM
AI	OpenAI API
Testing	Jest + Supertest
Load Testing	k6

---

🧠 System Architecture

🧠 Architecture Overview

This system follows a tool-based AI orchestration pattern, where the LLM is responsible for intent understanding and decision-making, while all business logic is handled by the backend.

🔁 Flow Summary

1. User Request

   • The user sends a message describing what they are looking for.

2. Concierge Service

   • Acts as the central orchestrator.
   • Sends the request to the LLM along with available tools.

3. LLM (Intent & Tool Selection)

   • Interprets user intent.
   • Decides which tools to call (e.g., search, scoring, intro generation).

4. Tool Execution

   • Search Tool → retrieves relevant attendees (semantic or DB query)
   • Score Tool → ranks candidates using deterministic logic
   • Intro Tool → generates personalized introduction messages

5. Data Layer

   • PostgreSQL stores attendees, conversations, and optional embeddings.
   • Semantic search (pgvector) is used when available.

6. Final Response

   • Results are aggregated into a structured JSON response.
   • Returned to the user via the API.

---

🎯 Design Principles

• LLM for reasoning, not logic Prevents hallucination and keeps behavior predictable.

• Backend-driven decisions Scoring and filtering are deterministic and explainable.

• Tool-based architecture Makes the system modular, testable, and extensible.

• Hybrid retrieval approach Combines semantic search with rule-based ranking for better relevance.

---

⚡ Why This Approach?

This architecture ensures that the system is:

• Reliable → no hidden AI logic affecting core decisions
• Explainable → every match can be justified
• Scalable → tools can be extended independently
• Production-ready → avoids over-reliance on LLM responses

🔄 AI Agent Flow

sequenceDiagram
    participant U as User
    participant API as NestJS API
    participant LLM as OpenAI
    participant Tool as Tools
    participant DB as Database

    U->>API: Send message
    API->>LLM: Understand intent

    LLM->>Tool: search_attendees
    Tool->>DB: Query
    DB-->>Tool: Candidates

    Tool-->>LLM: Results

    LLM->>Tool: score_match
    LLM->>Tool: draft_intro

    LLM-->>API: Structured output
    API-->>U: JSON response

Loading

---

🎯 Matching Strategy

The system uses a hybrid approach:

1. Semantic Retrieval

• Embedding-based similarity search
• Finds relevant candidates beyond keyword matching

2. Rule-Based Scoring

• Skill overlap
• Role alignment
• Intent compatibility

---

📦 Project Structure

src/
├── modules/
│   ├── attendee/
│   ├── event/
│   ├── conversation/
│   ├── concierge/
│   │   ├── tools/
│   │   ├── concierge.service.ts
│   │   └── utils/
│
├── scripts/
│   └── generate-embedding.ts

test/
├── *.e2e-spec.ts

---

⚙️ Setup & Installation

1. Install dependencies

npm install

---

2. Environment Configuration

Copy from .env.example using the following command:

cp .env.example .env

---

3. Database Setup

The database and required extensions are automatically initialized during the first run. No manual setup is required.

-- pgvector extension is enabled automatically

---

4. Run Migrations (only when necessary, or use revert)

npm run migration:run
# or rollback if needed
npm run migration:revert

---

5. Generate Embeddings (Optional)

npm run embed

Embeddings are used to enable semantic search, allowing the system to find relevant attendees based on meaning and intent rather than exact keyword matches.

---

7. Start Server

Option 1: Using Docker (Recommended)

docker-compose up --build

Option 2: Using npm (Ensure DB is configured)

npm run start:dev

---

📡 API Reference (Postman Collection Provided Separately)

Create Event

POST /events

{
  "title": "AI Conference",
  "location": "Jakarta"
}

---

Create Attendee

POST /events/:eventId/attendees

{
  "name": "John Doe",
  "role": "Backend Engineer",
  "skills": ["nodejs", "ai"],
  "lookingFor": "AI founder",
  "openToChat": true
}

---

Concierge API

POST /events/:eventId/concierge/messages

{
  "attendeeId": "1",
  "message": "Looking for AI co-founder"
}

---

Example Response

{
  "summary": "Found 3 strong matches",
  "matches": [
    {
      "name": "Sarah Lim",
      "role": "AI Founder",
      "score": 92,
      "shared_ground": ["AI"],
      "why_match": "Strong alignment in AI and startup interest",
      "intro_message": "Hi Sarah..."
    }
  ]
}

---

🧪 Testing

Run E2E tests:

npm run test:e2e

Coverage:

• Event API
• Attendee API
• Concierge API
• Edge cases

---

📊 Load Testing

Run:

k6 run k6/concierge-load-test.js

Summary output:

{
  "avg_duration": 320,
  "p95": 600,
  "error_rate": 0
}

---

⚠️ Limitations

• Depends on OpenAI API latency
• Embedding generation is batch-based
• No multi-turn conversation memory yet

---

🚀 Future Improvements

• Multi-turn conversation memory
• Real-time recommendation streaming
• Feedback loop (learning system)
• Embedding caching
• Advanced LLM ranking

---

🧠 Design Principles

• LLM handles intent, not business logic
• Backend ensures deterministic behavior
• Semantic search improves relevance
• Scoring ensures explainability

---

👨‍💻 Author

Built as part of AI Engineering Challenge.