AgentSimilarRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cubi-estate/json-schema/cubi-estate-agent-similar-request-schema.json",
  "title": "AgentSimilarRequest",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cubi-estate-openapi.yml#/components/schemas/AgentSimilarRequest",
  "properties": {
    "chat_id": {
      "type": "integer",
      "title": "Chat Id",
      "description": "Chat id of the requesting user."
    },
    "seed_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Seed Id",
      "description": "Listing id of the seed (direct)."
    },
    "token": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Token",
      "description": "Carousel token (resolves seed via (token, index))."
    },
    "index": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 49.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Index",
      "description": "Index into carousel cache."
    },
    "mode": {
      "type": "string",
      "enum": [
        "in_city",
        "cross_city"
      ],
      "title": "Mode",
      "default": "in_city"
    },
    "other_city": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Other City",
      "description": "Required for mode='cross_city' — target city."
    },
    "limit": {
      "type": "integer",
      "maximum": 10.0,
      "minimum": 1.0,
      "title": "Limit",
      "description": "Max candidates to return.",
      "default": 5
    },
    "lang": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Lang",
      "default": "en"
    },
    "channel": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "telegram",
            "whatsapp"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Channel",
      "default": "telegram"
    },
    "telegram_chat_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Telegram Chat Id"
    },
    "whatsapp_chat_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Whatsapp Chat Id"
    },
    "embedding_source": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "pca",
            "search_doc",
            "hybrid"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Embedding Source",
      "description": "Per-request override for the pgvector NN embedding source. 'pca' = listing_concept_pca.embedding (50d, mig 078). 'search_doc' = listing_search_doc.embedding_v (384d, legacy). 'hybrid' = union of both pools (deduped by listing_id, max embed_sim wins on collision). None (default) follows SIMILARITY_USE_PCA_EMBEDDINGS env. Useful for in-request A/B without dyno restart."
    },
    "structural_pool": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Structural Pool",
      "description": "Per-request override for the structural-proximity pool (SIMILARITY_STRUCTURAL_POOL). True forces it on, False off; None (default) follows the env flag. in_city only — ignored for cross_city. Lets you A/B the structural branch against real chats without an app-wide config flip."
    }
  },
  "type": "object",
  "required": [
    "chat_id"
  ]
}