Initial commit: Embedding service ready for Render deployment

.env.example

@@ -0,0 +1,7 @@
+# Embedding Service Configuration
+EMBEDDING_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+EMBEDDING_DIMENSIONS=384
+
+# Optional: OpenAI API (if using OpenAI embeddings)
+# OPENAI_API_KEY=your-api-key-here
+

.gitignore

@@ -0,0 +1,53 @@
+# Python
+.cache/
+models/
+# Model cache
+
+*.log
+# Logs
+
+Thumbs.db
+.DS_Store
+# OS
+
+.env.local
+.env
+# Environment variables
+
+*~
+*.swo
+*.swp
+.vscode/
+.idea/
+# IDEs
+
+.venv
+env/
+ENV/
+venv/
+# Virtual Environment
+
+MANIFEST
+*.egg
+.installed.cfg
+*.egg-info/
+share/python-wheels/
+pip-wheel-metadata/
+wheels/
+var/
+sdist/
+parts/
+lib64/
+lib/
+.eggs/
+eggs/
+downloads/
+dist/
+develop-eggs/
+build/
+.Python
+*.so
+*$py.class
+*.py[cod]
+__pycache__/
+

.python-version

@@ -0,0 +1,2 @@
+3.11.0
+

INTEGRATION.md

@@ -0,0 +1,363 @@
+# Интеграция Matching Service с Go Backend
+
+## Обзор
+
+Matching Service — это Python/FastAPI сервис для семантического поиска похожих объектов на основе эмбеддингов текста.
+
+## Архитектура
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
+│  Frontend   │────▶│  Go Backend │────▶│   PostgreSQL    │
+└─────────────┘     └──────┬──────┘     └─────────────────┘
+                           │
+                           │ HTTP calls
+                           ▼
+                    ┌─────────────────┐
+                    │ Embedding Service│
+                    │   (Python)       │
+                    └─────────────────┘
+```
+
+## Установка Go-клиента
+
+Клиент уже добавлен в `internal/lib/matching/client.go`.
+
+## Конфигурация
+
+Добавьте переменные окружения:
+
+```bash
+MATCHING_SERVICE_URL=http://localhost:8082  # URL сервиса матчинга
+MATCHING_ENABLED=true                        # Включить интеграцию
+MATCHING_TOP_K=10                            # Кол-во результатов по умолчанию
+MATCHING_MIN_SIMILARITY=0.1                  # Мин. порог схожести (0-1)
+```
+
+## Использование в коде
+
+### 1. Инициализация клиента
+
+```go
+import "lead_exchange/internal/lib/matching"
+
+// В app.go или при инициализации сервисов
+matchingClient := matching.NewClient(cfg.Matching.URL)
+
+// Проверка доступности
+health, err := matchingClient.Health(ctx)
+if err != nil {
+    log.Warn("Matching service unavailable", "error", err)
+}
+```
+
+### 2. Регистрация объекта при создании
+
+```go
+// В lead service при создании лида
+func (s *LeadService) CreateLead(ctx context.Context, lead *domain.Lead) error {
+    // Сохраняем в БД
+    err := s.repo.Create(ctx, lead)
+    if err != nil {
+        return err
+    }
+    
+    // Индексируем в matching service (асинхронно, не блокируем)
+    if s.matchingEnabled {
+        go func() {
+            text := s.prepareLeadText(lead)
+            metadata := map[string]interface{}{
+                "budget_min": lead.BudgetMin,
+                "budget_max": lead.BudgetMax,
+                "city":       lead.City,
+            }
+            if err := s.matchingClient.RegisterLead(context.Background(), lead.ID, text, metadata); err != nil {
+                log.Error("Failed to register lead in matching", "lead_id", lead.ID, "error", err)
+            }
+        }()
+    }
+    
+    return nil
+}
+
+func (s *LeadService) prepareLeadText(lead *domain.Lead) string {
+    // Объединяем все текстовые поля для эмбеддинга
+    return fmt.Sprintf("%s. %s. Бюджет: %d-%d", 
+        lead.Title, 
+        lead.Description, 
+        lead.BudgetMin, 
+        lead.BudgetMax,
+    )
+}
+```
+
+### 3. Аналогично для объектов недвижимости
+
+```go
+// В property service при создании объекта
+func (s *PropertyService) CreateProperty(ctx context.Context, prop *domain.Property) error {
+    err := s.repo.Create(ctx, prop)
+    if err != nil {
+        return err
+    }
+    
+    if s.matchingEnabled {
+        go func() {
+            text := s.preparePropertyText(prop)
+            metadata := map[string]interface{}{
+                "price":    prop.Price,
+                "rooms":    prop.Rooms,
+                "area":     prop.Area,
+                "city":     prop.City,
+            }
+            if err := s.matchingClient.RegisterProperty(context.Background(), prop.ID, text, metadata); err != nil {
+                log.Error("Failed to register property in matching", "property_id", prop.ID, "error", err)
+            }
+        }()
+    }
+    
+    return nil
+}
+```
+
+### 4. Поиск матчей для лида
+
+```go
+// Новый endpoint: GET /v1/leads/{id}/matches
+func (s *LeadService) FindMatches(ctx context.Context, leadID string) ([]MatchResult, error) {
+    // Получаем лид из БД
+    lead, err := s.repo.GetByID(ctx, leadID)
+    if err != nil {
+        return nil, err
+    }
+    
+    // Ищем похожие объекты
+    text := s.prepareLeadText(lead)
+    matches, err := s.matchingClient.FindPropertiesForLead(ctx, text, 10, 0.1)
+    if err != nil {
+        return nil, fmt.Errorf("matching failed: %w", err)
+    }
+    
+    return matches, nil
+}
+```
+
+### 5. Взвешенный по��ск с приоритетами (НОВОЕ)
+
+```go
+// Новый endpoint: POST /v1/leads/{id}/weighted-matches
+func (s *LeadService) FindWeightedMatches(ctx context.Context, leadID string, opts WeightedMatchOptions) ([]WeightedMatchResult, error) {
+    lead, err := s.repo.GetByID(ctx, leadID)
+    if err != nil {
+        return nil, err
+    }
+    
+    text := s.prepareLeadText(lead)
+    
+    // Формируем структурированные метаданные для фильтрации
+    request := matching.WeightedMatchRequest{
+        Text:       text,
+        EntityType: "properties",
+        TopK:       opts.TopK,
+        Weights: matching.ParameterWeights{
+            Price:    opts.PriceWeight,    // по умолчанию 0.30
+            District: opts.DistrictWeight, // по умолчанию 0.25
+            Rooms:    opts.RoomsWeight,    // по умолчанию 0.20
+            Area:     opts.AreaWeight,     // по умолчанию 0.10
+            Semantic: opts.SemanticWeight, // по умолчанию 0.15
+        },
+        HardFilters: matching.HardFilters{
+            Price: &matching.PriceFilter{
+                MaxPrice: float64(lead.BudgetMax) * 1.2,
+            },
+            Rooms: opts.AllowedRooms,
+        },
+        SoftCriteria: matching.SoftCriteria{
+            TargetPrice:    float64(lead.BudgetMax),
+            TargetRooms:    lead.Rooms,
+            TargetDistrict: lead.District,
+        },
+    }
+    
+    return s.matchingClient.FindWeightedMatches(ctx, request)
+}
+```
+
+### 6. Получение пресетов весов (НОВОЕ)
+
+```go
+// GET /v1/matching/presets
+func (s *MatchingService) GetWeightPresets(ctx context.Context) (map[string]WeightPreset, error) {
+    return s.matchingClient.GetWeightPresets(ctx)
+}
+```
+
+**Пресеты:**
+- `balanced` — равномерное распределение
+- `budget_first` — бюджет важнее всего
+- `location_first` — локация важнее всего  
+- `family` — важны комнаты и площадь
+- `semantic_heavy` — максимум семантики
+
+### 7. Удаление при удалении сущности
+
+```go
+func (s *LeadService) DeleteLead(ctx context.Context, leadID string) error {
+    err := s.repo.Delete(ctx, leadID)
+    if err != nil {
+        return err
+    }
+    
+    // Удаляем из индекса
+    if s.matchingEnabled {
+        go func() {
+            s.matchingClient.DeleteLead(context.Background(), leadID)
+        }()
+    }
+    
+    return nil
+}
+```
+
+## Добавление gRPC endpoint для матчинга
+
+### 1. Добавить в lead.proto
+
+```protobuf
+// Базовый поиск
+message FindMatchesRequest {
+  string lead_id = 1;
+  int32 top_k = 2;
+  float min_similarity = 3;
+}
+
+message MatchResult {
+  string property_id = 1;
+  float similarity = 2;
+  map<string, string> metadata = 3;
+}
+
+message FindMatchesResponse {
+  repeated MatchResult matches = 1;
+}
+
+// Взвешенный поиск (НОВОЕ)
+message ParameterWeights {
+  float price = 1;     // default 0.30
+  float district = 2;  // default 0.25
+  float rooms = 3;     // default 0.20
+  float area = 4;      // default 0.10
+  float semantic = 5;  // default 0.15
+}
+
+message PriceFilter {
+  optional double min_price = 1;
+  optional double max_price = 2;
+}
+
+message HardFilters {
+  optional PriceFilter price = 1;
+  repeated string districts = 2;
+  repeated int32 rooms = 3;
+  optional double min_area = 4;
+  optional double max_area = 5;
+}
+
+message SoftCriteria {
+  optional double target_price = 1;
+  optional string target_district = 2;
+  optional int32 target_rooms = 3;
+  optional double target_area = 4;
+  repeated string preferred_districts = 5;
+}
+
+message FindWeightedMatchesRequest {
+  string lead_id = 1;
+  int32 top_k = 2;
+  optional ParameterWeights weights = 3;
+  optional HardFilters hard_filters = 4;
+  optional SoftCriteria soft_criteria = 5;
+  float min_total_score = 6;
+}
+
+message WeightedMatchResult {
+  string property_id = 1;
+  float total_score = 2;
+  float price_score = 3;
+  float district_score = 4;
+  float rooms_score = 5;
+  float area_score = 6;
+  float semantic_score = 7;
+  map<string, string> metadata = 8;
+  string match_explanation = 9;
+}
+
+message FindWeightedMatchesResponse {
+  repeated WeightedMatchResult matches = 1;
+  int32 total_searched = 2;
+  int32 filtered_out = 3;
+  ParameterWeights weights_used = 4;
+}
+
+service LeadService {
+  // ... existing methods ...
+  rpc FindMatches(FindMatchesRequest) returns (FindMatchesResponse);
+  rpc FindWeightedMatches(FindWeightedMatchesRequest) returns (FindWeightedMatchesResponse);
+}
+```
+
+### 2. Реализовать handler
+
+```go
+func (s *serverAPI) FindMatches(ctx context.Context, req *pb.FindMatchesRequest) (*pb.FindMatchesResponse, error) {
+    matches, err := s.leadService.FindMatches(ctx, req.LeadId)
+    if err != nil {
+        return nil, status.Error(codes.Internal, err.Error())
+    }
+    
+    pbMatches := make([]*pb.MatchResult, len(matches))
+    for i, m := range matches {
+        pbMatches[i] = &pb.MatchResult{
+            PropertyId: m.EntityID,
+            Similarity: float32(m.Similarity),
+            // ... metadata
+        }
+    }
+    
+    return &pb.FindMatchesResponse{Matches: pbMatches}, nil
+}
+```
+
+## Деплой Embedding Service на Render
+
+1. Создайте новый Web Service на Render
+2. Подключите репозиторий
+3. Настройки:
+   - **Root Directory**: `matching/embedding-service`
+   - **Runtime**: Docker
+   - **Instance Type**: Standard (нужно минимум 1GB RAM для модели)
+
+4. После деплоя обновите `MATCHING_SERVICE_URL` в основном бэкенде
+
+## Миграция существующих данных
+
+Для индексации существующих объектов создайте скрипт:
+
+```go
+func MigrateToMatching(ctx context.Context, repo LeadRepository, client *matching.Client) error {
+    leads, err := repo.GetAll(ctx)
+    if err != nil {
+        return err
+    }
+    
+    for _, lead := range leads {
+        text := prepareLeadText(lead)
+        if err := client.RegisterLead(ctx, lead.ID, text, nil); err != nil {
+            log.Error("Failed to migrate lead", "id", lead.ID, "error", err)
+        }
+    }
+    
+    return nil
+}
+```
+

README.md

@@ -0,0 +1,524 @@
+# Matching Service
+
+Сервис для матчинга лидов с объектами недвижимости на основе семантического поиска с использованием эмбеддингов.
+
+
+### 1. Embedding Service (Python)
+FastAPI сервис для генерации эмбеддингов текста:
+
+**Базовые эндпоинты:**
+- `/embed` - генерация эмбеддинга для одного текста
+- `/embed-batch` - пакетная генерация эмбеддингов
+- `/similarity` - вычисление косинусной близости
+
+**Матчинг:**
+- `/match` - поиск похожих объектов по эмбеддингу
+- `/match-text` - поиск похожих объектов по тексту
+- `/match-weighted` - **НОВОЕ** взвешенный матчинг с настраиваемыми приоритетами
+
+**Регистрация:**
+- `/register` - регистрация объекта с автоматической генерацией эмбеддинга
+- `/register-vector` - регистрация объекта с готовым эмбеддингом
+
+**Индексация:**
+- `/index/bulk` - **НОВОЕ** массовая индексация объектов
+- `/index/sync` - получение списка проиндексированных ID
+- `DELETE /index/{entity_type}` - очистка индекса
+
+**Настройки:**
+- `/weights/presets` - **НОВОЕ** предустановленные наборы весов
+
+**Статистика:**
+- `/store/stats` - статистика хранилища эмбеддингов
+- `/store/{entity_type}` - список объектов в индексе
+
+Поддерживаемые модели:
+- `sentence-transformers/all-MiniLM-L6-v2` (локальная, бесплатная)
+- `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` (для русского языка)
+- OpenAI `text-embedding-3-small` (платная, высокое качество)
+
+### 2. PostgreSQL с pgvector
+Расширение pgvector позволяет хранить и искать векторы в PostgreSQL:
+- Косинусное расстояние (`<=>`)
+- L2 расстояние (`<->`)
+- Внутреннее произведение (`<#>`)
+
+### 3. Go Client
+HTTP-клиент для вызова Embedding API из Go backend.
+
+## Запуск
+
+```bash
+# Запуск всех сервисов
+docker-compose up -d
+
+# Только embedding service
+cd matching/embedding-service
+pip install -r requirements.txt
+uvicorn main:app --host 0.0.0.0 --port 8082
+```
+
+## API
+
+### GET /health
+Проверка здоровья сервиса.
+
+Response:
+```json
+{
+  "status": "healthy",
+  "model": "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
+  "dimensions": 384
+}
+```
+
+### POST /embed
+Генерация эмбеддинга для текста.
+
+Request:
+```json
+{
+  "text": "Ищу 3-комнатную квартиру в центре города"
+}
+```
+
+Response:
+```json
+{
+  "embedding": [0.123, -0.456, ...],
+  "model": "paraphrase-multilingual-MiniLM-L12-v2",
+  "dimensions": 384
+}
+```
+
+### POST /embed-batch
+Пакетная генерация эмбеддингов.
+
+Request:
+```json
+{
+  "texts": ["текст 1", "текст 2"]
+}
+```
+
+Response:
+```json
+{
+  "embeddings": [[0.123, ...], [0.456, ...]],
+  "model": "paraphrase-multilingual-MiniLM-L12-v2",
+  "dimensions": 384
+}
+```
+
+### POST /similarity
+Вычисление косинусной близости между двумя эмбеддингами.
+
+Request:
+```json
+{
+  "embedding1": [0.123, -0.456, ...],
+  "embedding2": [0.789, 0.012, ...]
+}
+```
+
+Response:
+```json
+{
+  "similarity": 0.85
+}
+```
+
+### POST /register
+Регистрация объекта с автоматической генерацией эмбеддинга.
+
+Request:
+```json
+{
+  "entity_id": "lead-123",
+  "entity_type": "leads",
+  "text": "Ищу 3-комнатную квартиру в центре города",
+  "metadata": {
+    "budget_min": 5000000,
+    "budget_max": 8000000,
+    "city": "Москва"
+  }
+}
+```
+
+Response:
+```json
+{
+  "success": true,
+  "entity_id": "lead-123",
+  "entity_type": "leads"
+}
+```
+
+### POST /register-vector
+Регистрация объекта с готовым эмбеддингом.
+
+Request:
+```json
+{
+  "entity_id": "property-456",
+  "entity_type": "properties",
+  "embedding": [0.123, -0.456, ...],
+  "metadata": {
+    "price": 6500000,
+    "rooms": 3,
+    "city": "Москва"
+  }
+}
+```
+
+### DELETE /register
+Удаление эмбеддинга объекта из хранилища.
+
+Request:
+```json
+{
+  "entity_id": "lead-123",
+  "entity_type": "leads"
+}
+```
+
+### POST /match
+Поиск похожих объектов по эмбеддингу.
+
+Request:
+```json
+{
+  "embedding": [0.123, -0.456, ...],
+  "entity_type": "properties",
+  "top_k": 5,
+  "min_similarity": 0.5
+}
+```
+
+Response:
+```json
+{
+  "matches": [
+    {
+      "entity_id": "property-456",
+      "similarity": 0.92,
+      "metadata": {
+        "price": 6500000,
+        "rooms": 3,
+        "city": "Москва"
+      }
+    },
+    {
+      "entity_id": "property-789",
+      "similarity": 0.78,
+      "metadata": {...}
+    }
+  ],
+  "total_searched": 150
+}
+```
+
+### POST /match-text
+Поиск похожих объектов по тексту (генерирует эмбеддинг автоматически).
+
+Request:
+```json
+{
+  "text": "Ищу 3-комнатную квартиру в центре города",
+  "entity_type": "properties",
+  "top_k": 5,
+  "min_similarity": 0.5
+}
+```
+
+Response: аналогично `/match`
+
+### GET /store/stats
+Статистика хранилища эмбеддингов.
+
+Response:
+```json
+{
+  "leads_count": 42,
+  "properties_count": 150,
+  "total_count": 192
+}
+```
+
+### GET /store/{entity_type}
+Список зарегистрированных объектов указанного типа.
+
+Response:
+```json
+{
+  "entity_type": "leads",
+  "count": 42,
+  "entities": [
+    {
+      "entity_id": "lead-123",
+      "metadata": {...},
+      "embedding_dimensions": 384
+    }
+  ]
+}
+```
+
+## Примеры использования
+
+### Сценарий матчинга лида с объектами недвижимости
+
+1. Бэкенд регистрирует объекты недвижимости:
+```bash
+curl -X POST http://localhost:8082/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "entity_id": "property-1",
+    "entity_type": "properties",
+    "text": "3-комнатная квартира в центре Москвы, 85 кв.м, евроремонт",
+    "metadata": {"price": 12000000, "rooms": 3}
+  }'
+```
+
+2. При создании лида делаем матчинг:
+```bash
+curl -X POST http://localhost:8082/match-text \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Ищу просторную квартиру в центре Москвы",
+    "entity_type": "properties",
+    "top_k": 10,
+    "min_similarity": 0.6
+  }'
+```
+
+---
+
+## Новые функции: Взвешенный матчинг
+
+### POST /match-weighted
+**Взвешенный матчинг с настраиваемыми приоритетами параметров.**
+
+Позволяет задать:
+- Веса для каждого параметра (цена, район, комнаты, площадь, семантика)
+- Жёсткие фильтры (объекты не прошедшие — исключаются полностью)
+- Мягкие критерии (влияют на ранжирование, но не исключают)
+
+Request:
+```json
+{
+  "text": "Ищу 2-комнатную квартиру в центре до 10 млн",
+  "entity_type": "properties",
+  "top_k": 10,
+  "weights": {
+    "price": 0.35,
+    "district": 0.30,
+    "rooms": 0.20,
+    "area": 0.05,
+    "semantic": 0.10
+  },
+  "hard_filters": {
+    "price": {
+      "min_price": null,
+      "max_price": 12000000
+    },
+    "districts": ["Центр", "Арбат", "Тверской"],
+    "rooms": [1, 2, 3],
+    "min_area": 40,
+    "max_area": 100
+  },
+  "soft_criteria": {
+    "target_price": 10000000,
+    "target_rooms": 2,
+    "target_district": "Центр",
+    "target_area": 55,
+    "preferred_districts": ["Центр", "Арбат"]
+  },
+  "min_total_score": 0.5
+}
+```
+
+Response:
+```json
+{
+  "matches": [
+    {
+      "entity_id": "prop-2",
+      "total_score": 0.9197,
+      "price_score": 0.925,
+      "district_score": 1.0,
+      "rooms_score": 1.0,
+      "area_score": 0.5,
+      "semantic_score": 0.7867,
+      "metadata": {
+        "price": 9500000,
+        "district": "Центр",
+        "rooms": 2,
+        "area": 55
+      },
+      "match_explanation": "цена 9,500,000₽ в бюджете; район 'Центр' подходит; 2-комн. как нужно"
+    }
+  ],
+  "total_searched": 7,
+  "filtered_out": 2,
+  "weights_used": {
+    "price": 0.35,
+    "district": 0.30,
+    "rooms": 0.20,
+    "area": 0.05,
+    "semantic": 0.10
+  }
+}
+```
+
+### GET /weights/presets
+Получить предустановленные наборы весов для разных сценариев.
+
+Response:
+```json
+{
+  "balanced": {
+    "name": "Сбалансированный",
+    "description": "Равномерное распределение приоритетов",
+    "weights": {"price": 0.25, "district": 0.25, "rooms": 0.20, "area": 0.15, "semantic": 0.15}
+  },
+  "budget_first": {
+    "name": "Бюджет важнее всего",
+    "description": "Максимальный приоритет на соответствие бюджету",
+    "weights": {"price": 0.45, "district": 0.20, "rooms": 0.15, "area": 0.10, "semantic": 0.10}
+  },
+  "location_first": {
+    "name": "Локация важнее всего",
+    "description": "Район и расположение - главный приоритет",
+    "weights": {"price": 0.20, "district": 0.40, "rooms": 0.15, "area": 0.10, "semantic": 0.15}
+  },
+  "family": {
+    "name": "Для семьи",
+    "description": "Важны комнаты и площадь",
+    "weights": {"price": 0.20, "district": 0.20, "rooms": 0.30, "area": 0.20, "semantic": 0.10}
+  },
+  "semantic_heavy": {
+    "name": "Умный поиск",
+    "description": "Максимальный приоритет на семантическое понимание запроса",
+    "weights": {"price": 0.15, "district": 0.15, "rooms": 0.15, "area": 0.10, "semantic": 0.45}
+  }
+}
+```
+
+---
+
+## Массовая индексация
+
+### POST /index/bulk
+Массовая индексация объектов (эффективнее чем по одному).
+
+Request:
+```json
+{
+  "entity_type": "properties",
+  "items": [
+    {
+      "entity_id": "prop-1",
+      "text": "3-комнатная квартира в центре, 80м²",
+      "metadata": {"price": 15000000, "district": "Центр", "rooms": 3, "area": 80}
+    },
+    {
+      "entity_id": "prop-2",
+      "text": "2-комнатная квартира у метро, 55м²",
+      "metadata": {"price": 9500000, "district": "Центр", "rooms": 2, "area": 55}
+    }
+  ],
+  "clear_existing": false
+}
+```
+
+Response:
+```json
+{
+  "total": 2,
+  "indexed": 2,
+  "failed": 0,
+  "results": [
+    {"entity_id": "prop-1", "success": true, "error": null},
+    {"entity_id": "prop-2", "success": true, "error": null}
+  ]
+}
+```
+
+### DELETE /index/{entity_type}
+Очистка индекса для указанного типа.
+
+```bash
+curl -X DELETE http://localhost:8082/index/properties
+```
+
+Response:
+```json
+{
+  "message": "Cleared 150 properties from index",
+  "deleted_count": 150
+}
+```
+
+### POST /index/sync
+Получение списка ID в индексе (для синхронизации с БД).
+
+Response:
+```json
+{
+  "leads": ["lead-1", "lead-2", "lead-3"],
+  "properties": ["prop-1", "prop-2"]
+}
+```
+
+---
+
+## Как работает приоритизация параметров
+
+### Иерархия важности (отраслевой стандарт недвижимости):
+
+| Приоритет | Параметр | Тип | Описание |
+|-----------|----------|-----|----------|
+| 🔴 1 | Цена/Бюджет | Жёсткий фильтр | Если не в бюджете — исключается |
+| 🔴 2 | Район/Локация | Жёсткий фильтр | Если не в нужном районе — исключается |
+| 🟡 3 | Количество комнат | Мягкий | ±1 комната = снижение score |
+| 🟡 4 | Площадь | Мягкий | ±15% = небольшое снижение |
+| 🟢 5 | Семантика | Мягкий | Для доп. критериев (парк, школа, метро) |
+
+### Формула расчёта score:
+
+```
+total_score = w_price × price_score + 
+              w_district × district_score + 
+              w_rooms × rooms_score + 
+              w_area × area_score + 
+              w_semantic × semantic_score
+```
+
+Где все веса нормализуются так, чтобы их сумма = 1.
+
+### Расчёт score по параметрам:
+
+**Price score:**
+- В пределах ±20% от целевой цены: 1.0 → 0.7 (линейно)
+- За пределами допуска: быстро падает до 0
+
+**District score:**
+- Точное совпадение: 1.0
+- В списке preferred: 0.7
+- Частичное совпадение: 0.6
+- Не совпадает: 0.3
+
+**Rooms score:**
+- Точное совпадение: 1.0
+- ±1 комната: 0.6
+- ±2 комнаты: 0.3
+- Больше: 0.1
+
+**Area score:**
+- В пределах ±15%: 1.0 → 0.7
+- За пределами: падает
+
+**Semantic score:**
+- Косинусная близость эмбеддингов (0-1)
+
+

WORKFLOW.md

@@ -0,0 +1,558 @@
+# Система матчинга лидов и объектов недвижимости
+
+## Общая схема работы
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                              FRONTEND                                         │
+│  ┌─────────────────┐              ┌─────────────────┐                        │
+│  │ Форма создания  │              │ Форма создания  │                        │
+│  │     ЛИДА        │              │    ОБЪЕКТА      │                        │
+│  └────────┬────────┘              └────────┬────────┘                        │
+└───────────┼────────────────────────────────┼─────────────────────────────────┘
+            │                                │
+            ▼                                ▼
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                           GO BACKEND (Render)                                 │
+│                                                                               │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │                         LeadService / PropertyService                    │ │
+│  │                                                                          │ │
+│  │  1. Валидация данных                                                     │ │
+│  │  2. Сохранение в PostgreSQL                                              │ │
+│  │  3. Вызов Matching Service для индексации ◄──── НОВЫЙ ШАГ               │ │
+│  │  4. Возврат результата                                                   │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+│                                    │                                          │
+│                                    │ HTTP POST /register                      │
+│                                    ▼                                          │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │                    Matching Client (internal/lib/matching)               │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+└────────────────────────────────────┼─────────────────────────────────────────┘
+                                     │
+                                     ▼
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                      EMBEDDING SERVICE (Python/FastAPI)                       │
+│                                                                               │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐          │
+│  │   ML Model      │    │  In-Memory      │    │   API Endpoints │          │
+│  │ (Transformers)  │───▶│   Store         │◄───│   /register     │          │
+│  │                 │    │   /match-text   │    │   /index/bulk   │          │
+│  └─────────────────┘    └─────────────────┘    └─────────────────┘          │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Что индексируем?
+
+**Индексируем ОБА типа сущностей:**
+
+| Сущность | Зачем индексировать |
+|----------|---------------------|
+| **Лиды** | Чтобы находить подходящие объекты ДЛЯ лида |
+| **Объекты** | Чтобы находить заинтересованных покупателей (лидов) ДЛЯ объекта |
+
+### Сценарии использования:
+
+1. **Риелтор создал лид** → система показывает "Рекомендуемые объекты" (топ-10 похожих)
+2. **Риелтор добавил объект** → система показывает "Потенциальные покупатели" (топ-10 лидов)
+3. **Покупатель ищет квартиру** → видит релевантные предложения
+
+---
+
+## Детальный Flow: Создание ЛИДА
+
+### Шаг 1: Frontend — заполнение формы
+
+```
+Пользователь заполняет форму:
+- Название: "Ищу 3-комнатную квартиру"
+- Описание: "В центре города, рядом с метро, бюджет до 15 млн"
+- Бюджет: 10 000 000 - 15 000 000 ₽
+- Город: Москва
+- Район: Центральный
+```
+
+### Шаг 2: Frontend → Go Backend
+
+```http
+POST /v1/leads
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "title": "Ищу 3-комнатную квартиру",
+  "description": "В центре города, рядом с метро, бюджет до 15 млн",
+  "budget_min": 10000000,
+  "budget_max": 15000000,
+  "city": "Москва",
+  "district": "Центральный"
+}
+```
+
+### Шаг 3: Go Backend — обработка
+
+```go
+// internal/services/lead/service.go
+
+func (s *LeadService) CreateLead(ctx context.Context, lead *domain.Lead) (*domain.Lead, error) {
+    // 1. Валидация
+    if err := s.validate(lead); err != nil {
+        return nil, err
+    }
+    
+    // 2. Сохранение в PostgreSQL
+    created, err := s.repo.Create(ctx, lead)
+    if err != nil {
+        return nil, err
+    }
+    
+    // 3. ИНДЕКСАЦИЯ в Matching Service (асинхронно, чтобы не блокировать ответ)
+    if s.matchingClient != nil && s.cfg.Matching.Enabled {
+        go s.indexLead(created)
+    }
+    
+    // 4. Возврат результата
+    return created, nil
+}
+
+func (s *LeadService) indexLead(lead *domain.Lead) {
+    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+    defer cancel()
+    
+    // Формируем текст для эмбеддинга
+    text := fmt.Sprintf("%s. %s. Бюджет: %d-%d руб. Город: %s", 
+        lead.Title,
+        lead.Description,
+        lead.BudgetMin,
+        lead.BudgetMax,
+        lead.City,
+    )
+    
+    // Метаданные для фильтрации
+    metadata := map[string]interface{}{
+        "budget_min": lead.BudgetMin,
+        "budget_max": lead.BudgetMax,
+        "city":       lead.City,
+        "user_id":    lead.UserID,
+    }
+    
+    err := s.matchingClient.RegisterLead(ctx, lead.ID.String(), text, metadata)
+    if err != nil {
+        s.log.Error("Failed to index lead", "lead_id", lead.ID, "error", err)
+    }
+}
+```
+
+### Шаг 4: Matching Service — индексация
+
+```
+POST /register
+{
+  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
+  "entity_type": "leads",
+  "text": "Ищу 3-комнатную квартиру. В центре города, рядом с метро. Бюджет: 10000000-15000000 руб. Город: Москва",
+  "metadata": {
+    "budget_min": 10000000,
+    "budget_max": 15000000,
+    "city": "Москва",
+    "user_id": "user-123"
+  }
+}
+```
+
+**Что происходит внутри:**
+1. ML-модель генерирует эмбеддинг (вектор 384 измерений)
+2. Вектор сохраняется в in-memory хранилище
+3. Возвращается `{"success": true}`
+
+---
+
+## Детальный Flow: Создание ОБЪЕКТА
+
+### Шаг 1: Frontend — заполнение формы
+
+```
+Пользователь заполняет форму:
+- Название: "3-комнатная квартира в ЖК Пресня"
+- Описание: "85 кв.м, евроремонт, вид на парк, 5 минут до метро"
+- Цена: 14 500 000 ₽
+- Площадь: 85 кв.м
+- Комнат: 3
+- Город: Москва
+```
+
+### Шаг 2: Frontend → Go Backend
+
+```http
+POST /v1/properties
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "title": "3-комнатная квартира в ЖК Пресня",
+  "description": "85 кв.м, евроремонт, вид на парк, 5 минут до метро",
+  "price": 14500000,
+  "area": 85,
+  "rooms": 3,
+  "city": "Москва"
+}
+```
+
+### Шаг 3: Go Backend — обработка
+
+```go
+// internal/services/property/service.go
+
+func (s *PropertyService) CreateProperty(ctx context.Context, prop *domain.Property) (*domain.Property, error) {
+    // 1. Валидация
+    if err := s.validate(prop); err != nil {
+        return nil, err
+    }
+    
+    // 2. Сохранение в PostgreSQL
+    created, err := s.repo.Create(ctx, prop)
+    if err != nil {
+        return nil, err
+    }
+    
+    // 3. ИНДЕКСАЦИЯ в Matching Service
+    if s.matchingClient != nil && s.cfg.Matching.Enabled {
+        go s.indexProperty(created)
+    }
+    
+    return created, nil
+}
+
+func (s *PropertyService) indexProperty(prop *domain.Property) {
+    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+    defer cancel()
+    
+    text := fmt.Sprintf("%s. %s. Цена: %d руб. Площадь: %d кв.м. Комнат: %d. Город: %s",
+        prop.Title,
+        prop.Description,
+        prop.Price,
+        prop.Area,
+        prop.Rooms,
+        prop.City,
+    )
+    
+    metadata := map[string]interface{}{
+        "price":   prop.Price,
+        "area":    prop.Area,
+        "rooms":   prop.Rooms,
+        "city":    prop.City,
+        "user_id": prop.UserID,
+    }
+    
+    err := s.matchingClient.RegisterProperty(ctx, prop.ID.String(), text, metadata)
+    if err != nil {
+        s.log.Error("Failed to index property", "property_id", prop.ID, "error", err)
+    }
+}
+```
+
+---
+
+## Детальный Flow: ПОИСК МАТЧЕЙ
+
+### Сценарий: Найти объекты для лида (базовый поиск)
+
+```
+Frontend: GET /v1/leads/{lead_id}/matches?top_k=10
+```
+
+```go
+// internal/services/lead/service.go
+
+func (s *LeadService) FindMatches(ctx context.Context, leadID uuid.UUID, topK int) ([]MatchedProperty, error) {
+    // 1. Получаем лид из БД
+    lead, err := s.repo.GetByID(ctx, leadID)
+    if err != nil {
+        return nil, err
+    }
+    
+    // 2. Формируем текст для поиска
+    text := fmt.Sprintf("%s. %s. Бюджет: %d-%d руб. Город: %s",
+        lead.Title, lead.Description, lead.BudgetMin, lead.BudgetMax, lead.City)
+    
+    // 3. Вызываем Matching Service
+    matches, err := s.matchingClient.FindPropertiesForLead(ctx, text, topK, 0.1)
+    if err != nil {
+        return nil, err
+    }
+    
+    // 4. Загружаем полные данные объектов из PostgreSQL
+    propertyIDs := make([]uuid.UUID, len(matches))
+    for i, m := range matches {
+        propertyIDs[i] = uuid.MustParse(m.EntityID)
+    }
+    
+    properties, err := s.propertyRepo.GetByIDs(ctx, propertyIDs)
+    if err != nil {
+        return nil, err
+    }
+    
+    // 5. Объединяем с similarity score
+    result := make([]MatchedProperty, len(matches))
+    for i, m := range matches {
+        result[i] = MatchedProperty{
+            Property:   properties[m.EntityID],
+            Similarity: m.Similarity,
+        }
+    }
+    
+    return result, nil
+}
+```
+
+### Сценарий: Взвешенный поиск с приоритетами (НОВОЕ)
+
+Для более точного матчинга используйте `/match-weighted`:
+
+```go
+// internal/services/lead/service.go
+
+func (s *LeadService) FindWeightedMatches(ctx context.Context, leadID uuid.UUID, opts MatchOptions) ([]WeightedMatchedProperty, error) {
+    lead, err := s.repo.GetByID(ctx, leadID)
+    if err != nil {
+        return nil, err
+    }
+    
+    // Формируем запрос с весами и фильтрами
+    request := matching.WeightedMatchRequest{
+        Text:       fmt.Sprintf("%s. %s", lead.Title, lead.Description),
+        EntityType: "properties",
+        TopK:       opts.TopK,
+        Weights: matching.ParameterWeights{
+            Price:    opts.PriceWeight,    // 0.35 - цена важнее
+            District: opts.DistrictWeight, // 0.30 - район важен
+            Rooms:    opts.RoomsWeight,    // 0.20 - комнаты
+            Area:     opts.AreaWeight,     // 0.05 - площадь менее важна
+            Semantic: opts.SemanticWeight, // 0.10 - семантика
+        },
+        HardFilters: matching.HardFilters{
+            Price: &matching.PriceFilter{
+                MaxPrice: float64(lead.BudgetMax) * 1.2, // +20% допуск
+            },
+            Districts: opts.AllowedDistricts,
+            Rooms:     opts.AllowedRooms,
+        },
+        SoftCriteria: matching.SoftCriteria{
+            TargetPrice:    float64(lead.BudgetMax),
+            TargetRooms:    lead.Rooms,
+            TargetDistrict: lead.District,
+        },
+    }
+    
+    matches, err := s.matchingClient.FindWeightedMatches(ctx, request)
+    if err != nil {
+        return nil, err
+    }
+    
+    // ... загрузка полных данных из БД
+    return result, nil
+}
+```
+
+### Пример вызова из Frontend:
+
+```http
+POST /v1/leads/{lead_id}/weighted-matches
+Content-Type: application/json
+
+{
+  "top_k": 10,
+  "preset": "budget_first",  // или свои веса
+  "weights": {
+    "price": 0.40,
+    "district": 0.25,
+    "rooms": 0.20,
+    "area": 0.05,
+    "semantic": 0.10
+  },
+  "hard_filters": {
+    "max_price": 12000000,
+    "districts": ["Центр", "Арбат"]
+  }
+}
+```
+```
+
+### Ответ клиенту
+
+```json
+{
+  "matches": [
+    {
+      "property": {
+        "id": "prop-123",
+        "title": "3-комнатная квартира в ЖК Пресня",
+        "price": 14500000,
+        "rooms": 3,
+        "area": 85
+      },
+      "similarity": 0.89
+    },
+    {
+      "property": {
+        "id": "prop-456",
+        "title": "3-комнатная квартира у метро Маяковская",
+        "price": 13000000,
+        "rooms": 3,
+        "area": 78
+      },
+      "similarity": 0.82
+    }
+  ]
+}
+```
+
+---
+
+## Полный список операций с индексом
+
+| Операция | Когда вызывать | Endpoint |
+|----------|----------------|----------|
+| Индексация лида | При создании/обновлении лида | `POST /register` |
+| Индексация объекта | При создании/обновлении объекта | `POST /register` |
+| Удаление из индекса | При удалении лида/объекта | `DELETE /register` |
+| Массовая индексация | При миграции/переиндексации | `POST /index/bulk` |
+| Очистка индекса | При сбросе данных | `DELETE /index/{type}` |
+| Базовый поиск матчей | По запросу пользователя | `POST /match-text` |
+| **Взвешенный поиск** | С настройкой приоритетов | `POST /match-weighted` |
+| **Получить пресеты** | Для UI выбора режима поиска | `GET /weights/presets` |
+
+---
+
+## Обновление и удаление
+
+### При обновлении лида/объекта
+
+```go
+func (s *LeadService) UpdateLead(ctx context.Context, lead *domain.Lead) error {
+    // 1. Обновляем в БД
+    err := s.repo.Update(ctx, lead)
+    if err != nil {
+        return err
+    }
+    
+    // 2. Переиндексируем (RegisterLead перезапишет старый эмбеддинг)
+    go s.indexLead(lead)
+    
+    return nil
+}
+```
+
+### При удалении
+
+```go
+func (s *LeadService) DeleteLead(ctx context.Context, leadID uuid.UUID) error {
+    // 1. Удаляем из БД
+    err := s.repo.Delete(ctx, leadID)
+    if err != nil {
+        return err
+    }
+    
+    // 2. Удаляем из индекса
+    go func() {
+        ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+        defer cancel()
+        s.matchingClient.DeleteLead(ctx, leadID.String())
+    }()
+    
+    return nil
+}
+```
+
+---
+
+## Первоначальная миграция данных
+
+Если в БД уже есть данные, нужно их проиндексировать:
+
+```go
+// cmd/migrate_to_matching/main.go
+
+func main() {
+    // Инициализация
+    cfg := config.MustLoad()
+    db := setupDB(cfg)
+    matchingClient := matching.NewClient(cfg.Matching.URL)
+    
+    // Проверяем доступность сервиса
+    _, err := matchingClient.Health(context.Background())
+    if err != nil {
+        log.Fatal("Matching service unavailable:", err)
+    }
+    
+    // Индексируем лиды
+    indexLeads(db, matchingClient)
+    
+    // Индексируем объекты
+    indexProperties(db, matchingClient)
+}
+
+func indexLeads(db *sql.DB, client *matching.Client) {
+    rows, _ := db.Query("SELECT id, title, description, budget_min, budget_max, city FROM leads")
+    defer rows.Close()
+    
+    var items []matching.BulkIndexItem
+    for rows.Next() {
+        var id, title, description, city string
+        var budgetMin, budgetMax int64
+        rows.Scan(&id, &title, &description, &budgetMin, &budgetMax, &city)
+        
+        items = append(items, matching.BulkIndexItem{
+            EntityID: id,
+            Text:     fmt.Sprintf("%s. %s. Бюджет: %d-%d. Город: %s", title, description, budgetMin, budgetMax, city),
+            Metadata: map[string]interface{}{
+                "budget_min": budgetMin,
+                "budget_max": budgetMax,
+                "city":       city,
+            },
+        })
+    }
+    
+    // Массовая индексация
+    resp, err := client.BulkIndexLeads(context.Background(), items, true)
+    if err != nil {
+        log.Fatal(err)
+    }
+    
+    log.Printf("Indexed %d leads, failed: %d", resp.Indexed, resp.Failed)
+}
+```
+
+---
+
+## Переменные окружения
+
+```bash
+# Go Backend
+MATCHING_SERVICE_URL=https://matching-service.onrender.com
+MATCHING_ENABLED=true
+MATCHING_TOP_K=10
+MATCHING_MIN_SIMILARITY=0.1
+
+# Embedding Service
+EMBEDDING_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+```
+
+---
+
+## Чек-лист для бэкенд-разработчика
+
+- [ ] Добавить `matchingClient` в сервисы Lead и Property
+- [ ] Добавить вызов `RegisterLead` в `CreateLead`
+- [ ] Добавить вызов `RegisterProperty` в `CreateProperty`
+- [ ] Добавить вызов `RegisterLead` в `UpdateLead`
+- [ ] Добавить вызов `RegisterProperty` в `UpdateProperty`
+- [ ] Добавить вызов `DeleteLead` в `DeleteLead`
+- [ ] Добавить вызов `DeleteProperty` в `DeleteProperty`
+- [ ] Создать endpoint `GET /v1/leads/{id}/matches`
+- [ ] Создать endpoint `GET /v1/properties/{id}/matches`
+- [ ] Написать скрипт миграции существующих данных
+- [ ] Задеплоить Embedding Service на Render
+- [ ] Добавить переменные окружения на Render
+

build.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+echo "Build completed successfully!"
+
+python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2')"
+echo "Pre-downloading embedding model to reduce cold start time..."
+
+pip install --no-cache-dir -r requirements.txt
+cd embedding-service
+echo "Installing Python dependencies..."
+
+# Render build script
+

embedding-service/Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application
+COPY main.py .
+
+# Pre-download model during build (faster cold starts)
+RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2')"
+
+# Expose port
+EXPOSE 8082
+
+# Run with uvicorn
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8082"]
+

embedding-service/main.py

@@ -0,0 +1,1126 @@
+"""
+Embedding Service - FastAPI сервис для генерации эмбеддингов текста.
+
+Используется для матчинга лидов с объектами недвижимости на основе семантической близости.
+"""
+
+import os
+from typing import List, Optional, Dict, Any
+from contextlib import asynccontextmanager
+from uuid import uuid4
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+from sentence_transformers import SentenceTransformer
+import numpy as np
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Конфигурация
+MODEL_NAME = os.getenv("EMBEDDING_MODEL", "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2")
+EMBEDDING_DIMENSIONS = int(os.getenv("EMBEDDING_DIMENSIONS", "384"))
+
+# Глобальная модель (загружается при старте)
+model: Optional[SentenceTransformer] = None
+
+# In-memory хранилище эмбеддингов (для прототипа, в продакшене используется pgvector)
+# Структура: {entity_type: {entity_id: {"embedding": [...], "metadata": {...}}}}
+embedding_store: Dict[str, Dict[str, Dict[str, Any]]] = {
+    "leads": {},
+    "properties": {}
+}
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Загрузка модели при старте приложения."""
+    global model
+    print(f"Loading embedding model: {MODEL_NAME}")
+    model = SentenceTransformer(MODEL_NAME)
+    print(f"Model loaded successfully. Embedding dimensions: {model.get_sentence_embedding_dimension()}")
+    yield
+    # Cleanup
+    model = None
+
+
+app = FastAPI(
+    title="Embedding Service",
+    description="Сервис для генерации эмбеддингов текста",
+    version="1.0.0",
+    lifespan=lifespan
+)
+
+# CORS для локальной разработки
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# --- Pydantic Models ---
+
+class EmbedRequest(BaseModel):
+    """Запрос на генерацию эмбеддинга для одного текста."""
+    text: str = Field(..., min_length=1, description="Текст для генерации эмбеддинга")
+
+
+class EmbedResponse(BaseModel):
+    """Ответ с эмбеддингом."""
+    embedding: List[float] = Field(..., description="Векторное представление текста")
+    model: str = Field(..., description="Название используемой модели")
+    dimensions: int = Field(..., description="Размерность вектора")
+
+
+class EmbedBatchRequest(BaseModel):
+    """Запрос на пакетную генерацию эмбеддингов."""
+    texts: List[str] = Field(..., min_length=1, description="Список текстов")
+
+
+class EmbedBatchResponse(BaseModel):
+    """Ответ с пакетными эмбеддингами."""
+    embeddings: List[List[float]] = Field(..., description="Список векторных представлений")
+    model: str = Field(..., description="Название используемой модели")
+    dimensions: int = Field(..., description="Размерность векторов")
+
+
+class SimilarityRequest(BaseModel):
+    """Запрос на вычисление косинусной близости."""
+    embedding1: List[float] = Field(..., description="Первый эмбеддинг")
+    embedding2: List[float] = Field(..., description="Второй эмбеддинг")
+
+
+class SimilarityResponse(BaseModel):
+    """Ответ с косинусной близостью."""
+    similarity: float = Field(..., description="Косинусная близость от -1 до 1")
+
+
+class HealthResponse(BaseModel):
+    """Ответ на health check."""
+    status: str
+    model: str
+    dimensions: int
+
+
+# --- Match Models ---
+
+class MatchRequest(BaseModel):
+    """Запрос на поиск похожих объектов по эмбеддингу."""
+    embedding: List[float] = Field(..., description="Эмбеддинг для поиска")
+    entity_type: str = Field(default="properties", description="Тип сущности для поиска (leads, properties)")
+    top_k: int = Field(default=5, ge=1, le=100, description="Количество результатов")
+    min_similarity: float = Field(default=0.0, ge=-1.0, le=1.0, description="Минимальный порог схожести")
+
+
+class MatchTextRequest(BaseModel):
+    """Запрос на поиск похожих объектов по тексту."""
+    text: str = Field(..., min_length=1, description="Текст для поиска")
+    entity_type: str = Field(default="properties", description="Тип сущности для поиска (leads, properties)")
+    top_k: int = Field(default=5, ge=1, le=100, description="Количество результатов")
+    min_similarity: float = Field(default=0.0, ge=-1.0, le=1.0, description="Минимальный порог схожести")
+
+
+class MatchResult(BaseModel):
+    """Результат матчинга."""
+    entity_id: str = Field(..., description="ID найденного объекта")
+    similarity: float = Field(..., description="Косинусная близость (0-1)")
+    metadata: Optional[Dict[str, Any]] = Field(default=None, description="Дополнительные данные объекта")
+
+
+class MatchResponse(BaseModel):
+    """Ответ с результатами матчинга."""
+    matches: List[MatchResult] = Field(..., description="Найденные объекты")
+    total_searched: int = Field(..., description="Количество проверенных объектов")
+
+
+class RegisterEmbeddingRequest(BaseModel):
+    """Запрос на регистрацию эмбеддинга объекта."""
+    entity_id: str = Field(..., description="ID объекта")
+    entity_type: str = Field(..., description="Тип сущности (leads, properties)")
+    text: str = Field(..., min_length=1, description="Текст для генерации эмбеддинга")
+    metadata: Optional[Dict[str, Any]] = Field(default=None, description="Дополнительные данные объекта")
+
+
+class RegisterEmbeddingFromVectorRequest(BaseModel):
+    """Запрос на регистрацию готового эмбеддинга."""
+    entity_id: str = Field(..., description="ID объекта")
+    entity_type: str = Field(..., description="Тип сущности (leads, properties)")
+    embedding: List[float] = Field(..., description="Готовый эмбеддинг")
+    metadata: Optional[Dict[str, Any]] = Field(default=None, description="Дополнительные данные объекта")
+
+
+class RegisterResponse(BaseModel):
+    """Ответ на регистрацию эмбеддинга."""
+    success: bool
+    entity_id: str
+    entity_type: str
+
+
+class DeleteEmbeddingRequest(BaseModel):
+    """Запрос на удаление эмбеддинга."""
+    entity_id: str = Field(..., description="ID объекта")
+    entity_type: str = Field(..., description="Тип сущности (leads, properties)")
+
+
+class StoreStatsResponse(BaseModel):
+    """Статистика хранилища эмбеддингов."""
+    leads_count: int
+    properties_count: int
+    total_count: int
+
+
+# --- Bulk Index Models ---
+
+class BulkIndexItem(BaseModel):
+    """Один элемент для массовой индексации."""
+    entity_id: str = Field(..., description="ID объекта")
+    text: str = Field(..., min_length=1, description="Текст для генерации эмбеддинга")
+    metadata: Optional[Dict[str, Any]] = Field(default=None, description="Дополнительные данные")
+
+
+class BulkIndexRequest(BaseModel):
+    """Запрос на массовую индексацию."""
+    entity_type: str = Field(..., description="Тип сущности (leads, properties)")
+    items: List[BulkIndexItem] = Field(..., description="Список объектов для индексации")
+    clear_existing: bool = Field(default=False, description="Очистить существующие данные перед индексацией")
+
+
+class BulkIndexResult(BaseModel):
+    """Результат индексации одного элемента."""
+    entity_id: str
+    success: bool
+    error: Optional[str] = None
+
+
+class BulkIndexResponse(BaseModel):
+    """Ответ на массовую индексацию."""
+    total: int = Field(..., description="Всего элементов в запросе")
+    indexed: int = Field(..., description="Успешно проиндексировано")
+    failed: int = Field(..., description="Ошибок")
+    results: List[BulkIndexResult] = Field(..., description="Детали по каждому элементу")
+
+
+class ReindexFromDBRequest(BaseModel):
+    """Запрос на переиндексацию из внешнего источника (вызывается Go Backend)."""
+    entity_type: str = Field(..., description="Тип сущности (leads, properties)")
+    db_url: Optional[str] = Field(default=None, description="URL базы данных (опционально)")
+
+
+# --- Weighted Matching Models ---
+
+class ParameterWeights(BaseModel):
+    """Веса для различных параметров матчинга."""
+    price: float = Field(default=0.30, ge=0.0, le=1.0, description="Вес цены (по умолчанию 0.30)")
+    district: float = Field(default=0.25, ge=0.0, le=1.0, description="Вес района (по умолчанию 0.25)")
+    rooms: float = Field(default=0.20, ge=0.0, le=1.0, description="Вес ��оличества комнат (по умолчанию 0.20)")
+    area: float = Field(default=0.10, ge=0.0, le=1.0, description="Вес площади (по умолчанию 0.10)")
+    semantic: float = Field(default=0.15, ge=0.0, le=1.0, description="Вес семантической близости (по умолчанию 0.15)")
+
+
+class PriceFilter(BaseModel):
+    """Фильтр по цене."""
+    min_price: Optional[float] = Field(default=None, description="Минимальная цена")
+    max_price: Optional[float] = Field(default=None, description="Максимальная цена")
+    tolerance_percent: float = Field(default=10.0, description="Допустимое отклонение в % (для мягкого фильтра)")
+
+
+class HardFilters(BaseModel):
+    """Жёсткие фильтры (объекты не прошедшие фильтр исключаются)."""
+    price: Optional[PriceFilter] = Field(default=None, description="Фильтр по цене")
+    districts: Optional[List[str]] = Field(default=None, description="Список допустимых районов")
+    rooms: Optional[List[int]] = Field(default=None, description="Список допустимого кол-ва комнат")
+    min_area: Optional[float] = Field(default=None, description="Минимальная площадь")
+    max_area: Optional[float] = Field(default=None, description="Максимальная площадь")
+
+
+class SoftCriteria(BaseModel):
+    """Мягкие критерии для ранжирования (влияют на score, но не исключают)."""
+    target_price: Optional[float] = Field(default=None, description="Желаемая цена")
+    target_district: Optional[str] = Field(default=None, description="Предпочтительный район")
+    target_rooms: Optional[int] = Field(default=None, description="Желаемое кол-во комнат")
+    target_area: Optional[float] = Field(default=None, description="Желаемая площадь")
+    metro_distance_km: Optional[float] = Field(default=None, description="Желаемое расстояние до метро (км)")
+    preferred_districts: Optional[List[str]] = Field(default=None, description="Список предпочтительных районов")
+
+
+class WeightedMatchRequest(BaseModel):
+    """Запрос на взвешенный матчинга с приоритетами."""
+    text: str = Field(..., min_length=1, description="Текст запроса (описание требований)")
+    entity_type: str = Field(default="properties", description="Тип сущности для поиска")
+    top_k: int = Field(default=10, ge=1, le=100, description="Количество результатов")
+
+    # Настройка весов
+    weights: Optional[ParameterWeights] = Field(default=None, description="Веса параметров")
+
+    # Фильтры
+    hard_filters: Optional[HardFilters] = Field(default=None, description="Жёсткие фильтры")
+    soft_criteria: Optional[SoftCriteria] = Field(default=None, description="Мягкие критерии")
+
+    # Минимальный порог
+    min_total_score: float = Field(default=0.0, ge=0.0, le=1.0, description="Минимальный общий score")
+
+
+class WeightedMatchResult(BaseModel):
+    """Результат взвешенного матчинга с детализацией."""
+    entity_id: str
+    total_score: float = Field(..., description="Общий взвешенный score (0-1)")
+
+    # Детализация по компонентам
+    price_score: float = Field(default=0.0, description="Score по цене (0-1)")
+    district_score: float = Field(default=0.0, description="Score по району (0-1)")
+    rooms_score: float = Field(default=0.0, description="Score по комнатам (0-1)")
+    area_score: float = Field(default=0.0, description="Score по площади (0-1)")
+    semantic_score: float = Field(default=0.0, description="Семантический score (0-1)")
+
+    metadata: Optional[Dict[str, Any]] = None
+    match_explanation: Optional[str] = Field(default=None, description="Объяснение почему объект подходит")
+
+
+class WeightedMatchResponse(BaseModel):
+    """Ответ взвешенного матчинга."""
+    matches: List[WeightedMatchResult]
+    total_searched: int
+    filtered_out: int = Field(..., description="Отфильтровано жёсткими фильтрами")
+    weights_used: ParameterWeights
+
+
+# --- Endpoints ---
+
+@app.get("/health", response_model=HealthResponse)
+async def health_check():
+    """Проверка здоровья сервиса."""
+    if model is None:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+    return HealthResponse(
+        status="healthy",
+        model=MODEL_NAME,
+        dimensions=model.get_sentence_embedding_dimension()
+    )
+
+
+@app.post("/embed", response_model=EmbedResponse)
+async def embed_text(request: EmbedRequest):
+    """
+    Генерация эмбеддинга для одного текста.
+
+    Используется для получения векторного представления лида или объекта недвижимости.
+    """
+    if model is None:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+
+    try:
+        embedding = model.encode(request.text, convert_to_numpy=True)
+        return EmbedResponse(
+            embedding=embedding.tolist(),
+            model=MODEL_NAME,
+            dimensions=len(embedding)
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Embedding generation failed: {str(e)}")
+
+
+@app.post("/embed-batch", response_model=EmbedBatchResponse)
+async def embed_batch(request: EmbedBatchRequest):
+    """
+    Пакетная генерация эмбеддингов.
+
+    Эффективнее для обработки нескольких текстов за раз.
+    """
+    if model is None:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+
+    try:
+        embeddings = model.encode(request.texts, convert_to_numpy=True)
+        return EmbedBatchResponse(
+            embeddings=[emb.tolist() for emb in embeddings],
+            model=MODEL_NAME,
+            dimensions=embeddings.shape[1] if len(embeddings.shape) > 1 else len(embeddings)
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Batch embedding generation failed: {str(e)}")
+
+
+@app.post("/similarity", response_model=SimilarityResponse)
+async def compute_similarity(request: SimilarityRequest):
+    """
+    Вычисление косинусной близости между двумя эмбеддингами.
+
+    Возвращает значение от -1 (противоположные) до 1 (идентичные).
+    """
+    if len(request.embedding1) != len(request.embedding2):
+        raise HTTPException(
+            status_code=400,
+            detail="Embeddings must have the same dimensions"
+        )
+
+    try:
+        vec1 = np.array(request.embedding1)
+        vec2 = np.array(request.embedding2)
+
+        # Косинусная близость
+        similarity = np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))
+
+        return SimilarityResponse(similarity=float(similarity))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Similarity computation failed: {str(e)}")
+
+
+@app.post("/prepare-text")
+async def prepare_text_for_embedding(
+    title: str = "",
+    description: str = "",
+    requirement: dict = None
+):
+    """
+    Подготовка текста для генерации эмбеддинга.
+
+    Объединяет title, description и requirement в один текст для эмбеддинга.
+    """
+    parts = []
+
+    if title:
+        parts.append(f"Название: {title}")
+
+    if description:
+        parts.append(f"Описание: {description}")
+
+    if requirement:
+        req_parts = []
+        for key, value in requirement.items():
+            req_parts.append(f"{key}: {value}")
+        if req_parts:
+            parts.append(f"Требования: {', '.join(req_parts)}")
+
+    combined_text = ". ".join(parts)
+
+    return {"prepared_text": combined_text}
+
+
+# --- Matching Endpoints ---
+
+def _cosine_similarity(vec1: np.ndarray, vec2: np.ndarray) -> float:
+    """Вычисление косинусной близости между двумя векторами."""
+    norm1 = np.linalg.norm(vec1)
+    norm2 = np.linalg.norm(vec2)
+    if norm1 == 0 or norm2 == 0:
+        return 0.0
+    return float(np.dot(vec1, vec2) / (norm1 * norm2))
+
+
+def _calculate_price_score(obj_price: Optional[float], target_price: Optional[float], tolerance_percent: float = 20.0) -> float:
+    """
+    Вычисление score по цене.
+
+    Если цена объекта в пределах допуска от целевой - высокий score.
+    Чем дальше - тем ниже score.
+    """
+    if obj_price is None or target_price is None:
+        return 0.5  # Нейтральный score если данных нет
+
+    if target_price == 0:
+        return 0.5
+
+    # Процентное отклонение
+    deviation_percent = abs(obj_price - target_price) / target_price * 100
+
+    if deviation_percent <= tolerance_percent:
+        # В пределах допуска - линейно от 1.0 до 0.7
+        return 1.0 - (deviation_percent / tolerance_percent) * 0.3
+    else:
+        # За пределами допуска - быстро падает
+        extra_deviation = deviation_percent - tolerance_percent
+        score = 0.7 - (extra_deviation / 100) * 0.7
+        return max(0.0, score)
+
+
+def _calculate_district_score(
+    obj_district: Optional[str],
+    target_district: Optional[str],
+    preferred_districts: Optional[List[str]] = None
+) -> float:
+    """
+    Вычисление score по району.
+
+    Точное совпадение = 1.0
+    В списке предпочтительных = 0.7
+    Иначе = 0.3
+    """
+    if obj_district is None:
+        return 0.3
+
+    obj_district_lower = obj_district.lower().strip()
+
+    # Точное совпадение с целевым
+    if target_district and obj_district_lower == target_district.lower().strip():
+        return 1.0
+
+    # Проверяем в списке предпочтительных
+    if preferred_districts:
+        for pref in preferred_districts:
+            if obj_district_lower == pref.lower().strip():
+                return 0.7
+            # Частичное совпадение (например "Центральный" в "Центральный район")
+            if pref.lower() in obj_district_lower or obj_district_lower in pref.lower():
+                return 0.6
+
+    return 0.3
+
+
+def _calculate_rooms_score(obj_rooms: Optional[int], target_rooms: Optional[int]) -> float:
+    """
+    Вычисление score по количеству комнат.
+
+    Точное совпадение = 1.0
+    ±1 комната = 0.6
+    ±2 комнаты = 0.3
+    Больше разницы = 0.1
+    """
+    if obj_rooms is None or target_rooms is None:
+        return 0.5
+
+    diff = abs(obj_rooms - target_rooms)
+
+    if diff == 0:
+        return 1.0
+    elif diff == 1:
+        return 0.6
+    elif diff == 2:
+        return 0.3
+    else:
+        return 0.1
+
+
+def _calculate_area_score(obj_area: Optional[float], target_area: Optional[float], tolerance_percent: float = 15.0) -> float:
+    """
+    Вычисление score по площади.
+
+    Аналогично цене, но с меньшим допуском.
+    """
+    if obj_area is None or target_area is None:
+        return 0.5
+
+    if target_area == 0:
+        return 0.5
+
+    deviation_percent = abs(obj_area - target_area) / target_area * 100
+
+    if deviation_percent <= tolerance_percent:
+        return 1.0 - (deviation_percent / tolerance_percent) * 0.3
+    else:
+        extra_deviation = deviation_percent - tolerance_percent
+        score = 0.7 - (extra_deviation / 50) * 0.7
+        return max(0.0, score)
+
+
+def _passes_hard_filters(metadata: Dict[str, Any], filters: Optional[HardFilters]) -> bool:
+    """Проверка прохождения жёстких фильтров."""
+    if filters is None:
+        return True
+
+    # Фильтр по цене
+    if filters.price:
+        obj_price = metadata.get("price")
+        if obj_price is not None:
+            if filters.price.min_price and obj_price < filters.price.min_price:
+                return False
+            if filters.price.max_price and obj_price > filters.price.max_price:
+                return False
+
+    # Фильтр по районам
+    if filters.districts:
+        obj_district = metadata.get("district", "").lower().strip()
+        allowed = [d.lower().strip() for d in filters.districts]
+        if obj_district and obj_district not in allowed:
+            # Проверяем частичное совпадение
+            if not any(a in obj_district or obj_district in a for a in allowed):
+                return False
+
+    # Фильтр по комнатам
+    if filters.rooms:
+        obj_rooms = metadata.get("rooms")
+        if obj_rooms is not None and obj_rooms not in filters.rooms:
+            return False
+
+    # Фильтр по площади
+    obj_area = metadata.get("area")
+    if obj_area is not None:
+        if filters.min_area and obj_area < filters.min_area:
+            return False
+        if filters.max_area and obj_area > filters.max_area:
+            return False
+
+    return True
+
+
+def _generate_match_explanation(
+    price_score: float,
+    district_score: float,
+    rooms_score: float,
+    area_score: float,
+    semantic_score: float,
+    metadata: Dict[str, Any]
+) -> str:
+    """Генерация человеко-читаемого объяснения матча."""
+    reasons = []
+
+    if price_score >= 0.7:
+        price = metadata.get("price")
+        if price:
+            reasons.append(f"цена {price:,.0f}₽ в бюджете")
+
+    if district_score >= 0.7:
+        district = metadata.get("district")
+        if district:
+            reasons.append(f"район '{district}' подходит")
+
+    if rooms_score >= 0.7:
+        rooms = metadata.get("rooms")
+        if rooms:
+            reasons.append(f"{rooms}-комн. как нужно")
+
+    if area_score >= 0.7:
+        area = metadata.get("area")
+        if area:
+            reasons.append(f"площадь {area}м² подходит")
+
+    if semantic_score >= 0.6:
+        reasons.append("описание похоже на запрос")
+
+    if not reasons:
+        return "Частичное совпадение по параметрам"
+
+    return "; ".join(reasons)
+
+
+@app.post("/match", response_model=MatchResponse)
+async def match_by_embedding(request: MatchRequest):
+    """
+    Поиск похожих объектов по эмбеддингу.
+
+    Возвращает top_k наиболее похожих объектов указанного типа.
+    """
+    if request.entity_type not in embedding_store:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown entity type: {request.entity_type}. Allowed: leads, properties"
+        )
+
+    store = embedding_store[request.entity_type]
+    if not store:
+        return MatchResponse(matches=[], total_searched=0)
+
+    query_vec = np.array(request.embedding)
+
+    # Вычисляем схожесть со всеми объектами
+    similarities = []
+    for entity_id, data in store.items():
+        stored_vec = np.array(data["embedding"])
+        similarity = _cosine_similarity(query_vec, stored_vec)
+        if similarity >= request.min_similarity:
+            similarities.append((entity_id, similarity, data.get("metadata")))
+
+    # Сортируем по убыванию схожести и берем top_k
+    similarities.sort(key=lambda x: x[1], reverse=True)
+    top_matches = similarities[:request.top_k]
+
+    matches = [
+        MatchResult(entity_id=eid, similarity=sim, metadata=meta)
+        for eid, sim, meta in top_matches
+    ]
+
+    return MatchResponse(matches=matches, total_searched=len(store))
+
+
+@app.post("/match-text", response_model=MatchResponse)
+async def match_by_text(request: MatchTextRequest):
+    """
+    Поиск похожих объектов по тексту.
+
+    Генерирует эмбеддинг для текста и ищет похожие объекты.
+    """
+    if model is None:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+
+    if request.entity_type not in embedding_store:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown entity type: {request.entity_type}. Allowed: leads, properties"
+        )
+
+    store = embedding_store[request.entity_type]
+    if not store:
+        return MatchResponse(matches=[], total_searched=0)
+
+    try:
+        # Генерируем эмбеддинг для текста запроса
+        query_embedding = model.encode(request.text, convert_to_numpy=True)
+        query_vec = np.array(query_embedding)
+
+        # Вычисляем схожесть со всеми объектами
+        similarities = []
+        for entity_id, data in store.items():
+            stored_vec = np.array(data["embedding"])
+            similarity = _cosine_similarity(query_vec, stored_vec)
+            if similarity >= request.min_similarity:
+                similarities.append((entity_id, similarity, data.get("metadata")))
+
+        # Сортируем по убыванию схожести и берем top_k
+        similarities.sort(key=lambda x: x[1], reverse=True)
+        top_matches = similarities[:request.top_k]
+
+        matches = [
+            MatchResult(entity_id=eid, similarity=sim, metadata=meta)
+            for eid, sim, meta in top_matches
+        ]
+
+        return MatchResponse(matches=matches, total_searched=len(store))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Match by text failed: {str(e)}")
+
+
+@app.post("/register", response_model=RegisterResponse)
+async def register_embedding(request: RegisterEmbeddingRequest):
+    """
+    Регистрация объекта с автоматической генерацией эмбеддинга.
+
+    Используется для добавления лидов или объектов недвижимости в хранилище.
+    """
+    if model is None:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+
+    if request.entity_type not in embedding_store:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown entity type: {request.entity_type}. Allowed: leads, properties"
+        )
+
+    try:
+        # Генерируем эмбеддинг
+        embedding = model.encode(request.text, convert_to_numpy=True)
+
+        # Сохраняем в хранилище
+        embedding_store[request.entity_type][request.entity_id] = {
+            "embedding": embedding.tolist(),
+            "metadata": request.metadata or {}
+        }
+
+        return RegisterResponse(
+            success=True,
+            entity_id=request.entity_id,
+            entity_type=request.entity_type
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Register embedding failed: {str(e)}")
+
+
+@app.post("/register-vector", response_model=RegisterResponse)
+async def register_embedding_from_vector(request: RegisterEmbeddingFromVectorRequest):
+    """
+    Регистрация объекта с готовым эмбед��ингом.
+
+    Используется когда эмбеддинг уже был сгенерирован ранее.
+    """
+    if request.entity_type not in embedding_store:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown entity type: {request.entity_type}. Allowed: leads, properties"
+        )
+
+    # Сохраняем в хранилище
+    embedding_store[request.entity_type][request.entity_id] = {
+        "embedding": request.embedding,
+        "metadata": request.metadata or {}
+    }
+
+    return RegisterResponse(
+        success=True,
+        entity_id=request.entity_id,
+        entity_type=request.entity_type
+    )
+
+
+@app.delete("/register", response_model=RegisterResponse)
+async def delete_embedding(request: DeleteEmbeddingRequest):
+    """
+    Удаление эмбеддинга объекта из хранилища.
+    """
+    if request.entity_type not in embedding_store:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown entity type: {request.entity_type}. Allowed: leads, properties"
+        )
+
+    store = embedding_store[request.entity_type]
+    if request.entity_id not in store:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Entity {request.entity_id} not found in {request.entity_type}"
+        )
+
+    del store[request.entity_id]
+
+    return RegisterResponse(
+        success=True,
+        entity_id=request.entity_id,
+        entity_type=request.entity_type
+    )
+
+
+@app.get("/store/stats", response_model=StoreStatsResponse)
+async def get_store_stats():
+    """
+    Получение статистики хранилища эмбеддингов.
+    """
+    leads_count = len(embedding_store.get("leads", {}))
+    properties_count = len(embedding_store.get("properties", {}))
+
+    return StoreStatsResponse(
+        leads_count=leads_count,
+        properties_count=properties_count,
+        total_count=leads_count + properties_count
+    )
+
+
+@app.get("/store/{entity_type}")
+async def list_registered_entities(entity_type: str):
+    """
+    Список зарегистрированных объектов указанного типа.
+    """
+    if entity_type not in embedding_store:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown entity type: {entity_type}. Allowed: leads, properties"
+        )
+
+    store = embedding_store[entity_type]
+    entities = [
+        {
+            "entity_id": eid,
+            "metadata": data.get("metadata", {}),
+            "embedding_dimensions": len(data.get("embedding", []))
+        }
+        for eid, data in store.items()
+    ]
+
+    return {"entity_type": entity_type, "count": len(entities), "entities": entities}
+
+
+# --- Bulk Indexing Endpoints ---
+
+@app.post("/index/bulk", response_model=BulkIndexResponse)
+async def bulk_index(request: BulkIndexRequest):
+    """
+    Массовая индексация объектов.
+
+    Позволяет за один запрос проиндексировать множество лидов или объектов.
+    Используется для первоначальной загрузки данных или переиндексации.
+
+    Пример:
+    ```
+    POST /index/bulk
+    {
+        "entity_type": "properties",
+        "items": [
+            {"entity_id": "prop-1", "text": "3-комнатная квартира в центре", "metadata": {"price": 10000000}},
+            {"entity_id": "prop-2", "text": "Студия у метро", "metadata": {"price": 5000000}}
+        ],
+        "clear_existing": false
+    }
+    ```
+    """
+    if model is None:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+
+    if request.entity_type not in embedding_store:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown entity type: {request.entity_type}. Allowed: leads, properties"
+        )
+
+    # Очистка если нужно
+    if request.clear_existing:
+        embedding_store[request.entity_type] = {}
+
+    results: List[BulkIndexResult] = []
+    indexed = 0
+    failed = 0
+
+    # Собираем все тексты для батчевой генерации эмбеддингов (быстрее)
+    texts = [item.text for item in request.items]
+
+    try:
+        # Генерируем все эмбеддинги за один вызов модели
+        embeddings = model.encode(texts, convert_to_numpy=True, show_progress_bar=True)
+
+        # Сохраняем каждый
+        for i, item in enumerate(request.items):
+            try:
+                embedding_store[request.entity_type][item.entity_id] = {
+                    "embedding": embeddings[i].tolist(),
+                    "metadata": item.metadata or {}
+                }
+                results.append(BulkIndexResult(entity_id=item.entity_id, success=True))
+                indexed += 1
+            except Exception as e:
+                results.append(BulkIndexResult(entity_id=item.entity_id, success=False, error=str(e)))
+                failed += 1
+    except Exception as e:
+        # Если батч не удался, пробуем по одному
+        for item in request.items:
+            try:
+                embedding = model.encode(item.text, convert_to_numpy=True)
+                embedding_store[request.entity_type][item.entity_id] = {
+                    "embedding": embedding.tolist(),
+                    "metadata": item.metadata or {}
+                }
+                results.append(BulkIndexResult(entity_id=item.entity_id, success=True))
+                indexed += 1
+            except Exception as item_error:
+                results.append(BulkIndexResult(entity_id=item.entity_id, success=False, error=str(item_error)))
+                failed += 1
+
+    return BulkIndexResponse(
+        total=len(request.items),
+        indexed=indexed,
+        failed=failed,
+        results=results
+    )
+
+
+@app.delete("/index/{entity_type}")
+async def clear_index(entity_type: str):
+    """
+    Очистка индекса для указанного типа сущностей.
+
+    Удаляет все эмбеддинги указанного типа.
+    """
+    if entity_type not in embedding_store:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown entity type: {entity_type}. Allowed: leads, properties"
+        )
+
+    count = len(embedding_store[entity_type])
+    embedding_store[entity_type] = {}
+
+    return {"message": f"Cleared {count} {entity_type} from index", "deleted_count": count}
+
+
+@app.post("/index/sync")
+async def sync_index_info():
+    """
+    Получение информации для синхронизации.
+
+    Возвращает список всех entity_id в индексе, чтобы Go Backend мог
+    определить какие объекты нужно добавить/удалить.
+    """
+    return {
+        "leads": list(embedding_store["leads"].keys()),
+        "properties": list(embedding_store["properties"].keys())
+    }
+
+
+# --- Weighted Matching Endpoint ---
+
+@app.post("/match-weighted", response_model=WeightedMatchResponse)
+async def match_weighted(request: WeightedMatchRequest):
+    """
+    Взвешенный матчинг с настраиваемыми приоритетами параметров.
+
+    Позволяет задать:
+    - Веса для каждого параметра (цена, район, комнаты, площадь, семантика)
+    - Жёсткие фильтры (объекты не прошедшие - исключаются)
+    - Мягкие критерии (влияют на ранжирование)
+
+    Пример использования:
+    ```json
+    {
+        "text": "Ищу 2-комнатную квартиру в центре до 10 млн",
+        "entity_type": "properties",
+        "top_k": 10,
+        "weights": {
+            "price": 0.35,      // Цена - главный приоритет
+            "district": 0.30,   // Район - второй по важности
+            "rooms": 0.20,      // Комнаты
+            "area": 0.05,       // Площадь менее важна
+            "semantic": 0.10    // Семантика для "мягких" критериев
+        },
+        "hard_filters": {
+            "price": {"max_price": 12000000},
+            "districts": ["Центральный", "Арбат", "Тверской"]
+        },
+        "soft_criteria": {
+            "target_price": 10000000,
+            "target_rooms": 2,
+            "target_district": "Центральный"
+        }
+    }
+    ```
+    """
+    if model is None:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+
+    if request.entity_type not in embedding_store:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown entity type: {request.entity_type}. Allowed: leads, properties"
+        )
+
+    store = embedding_store[request.entity_type]
+    if not store:
+        return WeightedMatchResponse(
+            matches=[],
+            total_searched=0,
+            filtered_out=0,
+            weights_used=request.weights or ParameterWeights()
+        )
+
+    # Используем переданные веса или значения по умолчанию
+    weights = request.weights or ParameterWeights()
+
+    # Нормализуем веса чтобы сумма = 1
+    total_weight = weights.price + weights.district + weights.rooms + weights.area + weights.semantic
+    if total_weight > 0:
+        w_price = weights.price / total_weight
+        w_district = weights.district / total_weight
+        w_rooms = weights.rooms / total_weight
+        w_area = weights.area / total_weight
+        w_semantic = weights.semantic / total_weight
+    else:
+        w_price = w_district = w_rooms = w_area = w_semantic = 0.2
+
+    # Генерируем эмбеддинг для текста запроса
+    try:
+        query_embedding = model.encode(request.text, convert_to_numpy=True)
+        query_vec = np.array(query_embedding)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to generate embedding: {str(e)}")
+
+    # Извлекаем soft criteria
+    soft = request.soft_criteria or SoftCriteria()
+
+    results = []
+    filtered_out = 0
+
+    for entity_id, data in store.items():
+        metadata = data.get("metadata", {})
+
+        # 1. Проверяем жёсткие фильтры
+        if not _passes_hard_filters(metadata, request.hard_filters):
+            filtered_out += 1
+            continue
+
+        # 2. Вычисляем score по каждому параметру
+
+        # Цена
+        price_score = _calculate_price_score(
+            metadata.get("price"),
+            soft.target_price,
+            tolerance_percent=20.0
+        )
+
+        # Район
+        district_score = _calculate_district_score(
+            metadata.get("district"),
+            soft.target_district,
+            soft.preferred_districts
+        )
+
+        # Комнаты
+        rooms_score = _calculate_rooms_score(
+            metadata.get("rooms"),
+            soft.target_rooms
+        )
+
+        # Площадь
+        area_score = _calculate_area_score(
+            metadata.get("area"),
+            soft.target_area
+        )
+
+        # Семантика
+        stored_vec = np.array(data["embedding"])
+        semantic_score = _cosine_similarity(query_vec, stored_vec)
+        # Нормализуем в 0-1 (косинусная близость может быть отрицательной)
+        semantic_score = (semantic_score + 1) / 2
+
+        # 3. Вычисляем взвешенный total score
+        total_score = (
+            w_price * price_score +
+            w_district * district_score +
+            w_rooms * rooms_score +
+            w_area * area_score +
+            w_semantic * semantic_score
+        )
+
+        # Пропускаем если ниже минимального порога
+        if total_score < request.min_total_score:
+            continue
+
+        # Генерируем объяснение
+        explanation = _generate_match_explanation(
+            price_score, district_score, rooms_score, area_score, semantic_score, metadata
+        )
+
+        results.append(WeightedMatchResult(
+            entity_id=entity_id,
+            total_score=round(total_score, 4),
+            price_score=round(price_score, 4),
+            district_score=round(district_score, 4),
+            rooms_score=round(rooms_score, 4),
+            area_score=round(area_score, 4),
+            semantic_score=round(semantic_score, 4),
+            metadata=metadata,
+            match_explanation=explanation
+        ))
+
+    # Сортируем по total_score и берём top_k
+    results.sort(key=lambda x: x.total_score, reverse=True)
+    top_results = results[:request.top_k]
+
+    return WeightedMatchResponse(
+        matches=top_results,
+        total_searched=len(store),
+        filtered_out=filtered_out,
+        weights_used=weights
+    )
+
+
+@app.get("/weights/presets")
+async def get_weight_presets():
+    """
+    Получить предустановленные наборы весов для разных сценариев.
+
+    Помогает фронтенду предложить пользователю готовые настройки.
+    """
+    return {
+        "balanced": {
+            "name": "Сбалансированный",
+            "description": "Равномерное распределение приоритетов",
+            "weights": {"price": 0.25, "district": 0.25, "rooms": 0.20, "area": 0.15, "semantic": 0.15}
+        },
+        "budget_first": {
+            "name": "Бюджет важнее всего",
+            "description": "Максимальный приоритет на соответствие бюджету",
+            "weights": {"price": 0.45, "district": 0.20, "rooms": 0.15, "area": 0.10, "semantic": 0.10}
+        },
+        "location_first": {
+            "name": "Локация важнее всего",
+            "description": "Район и расположение - главный приоритет",
+            "weights": {"price": 0.20, "district": 0.40, "rooms": 0.15, "area": 0.10, "semantic": 0.15}
+        },
+        "family": {
+            "name": "Для семьи",
+            "description": "Важны комнаты и площадь",
+            "weights": {"price": 0.20, "district": 0.20, "rooms": 0.30, "area": 0.20, "semantic": 0.10}
+        },
+        "semantic_heavy": {
+            "name": "Умный поиск",
+            "description": "Максимальный приоритет на семантическое понимание запроса",
+            "weights": {"price": 0.15, "district": 0.15, "rooms": 0.15, "area": 0.10, "semantic": 0.45}
+        }
+    }

embedding-service/requirements.txt

@@ -0,0 +1,8 @@
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+sentence-transformers>=2.2.2
+numpy>=1.24.0
+pydantic>=2.5.0
+python-dotenv>=1.0.0
+torch>=2.0.0
+

render.yaml

@@ -0,0 +1,17 @@
+services:
+  - type: web
+    name: matching-embedding-service
+    env: python
+    region: frankfurt
+    plan: free
+    buildCommand: chmod +x build.sh && ./build.sh
+    startCommand: cd embedding-service && uvicorn main:app --host 0.0.0.0 --port $PORT
+    healthCheckPath: /health
+    envVars:
+      - key: EMBEDDING_MODEL
+        value: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+      - key: EMBEDDING_DIMENSIONS
+        value: 384
+      - key: PYTHON_VERSION
+        value: 3.11.0
+