AgentCrossCitySearchRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cubi-estate/json-schema/cubi-estate-agent-cross-city-search-request-schema.json",
  "title": "AgentCrossCitySearchRequest",
  "description": "Demo-query helper: picks a representative seed in `city_a` matching\nthe filters, then finds its best analogue in `city_b`. Returns both as\na 2-card carousel + side-by-side comparison table.\n\nDistinct from /agent/similar (single-seed → 1..N similar) because the\nuser's query is symmetric: 'find ONE in A and ONE in B'.\n\n`preferences` carries soft constraints (parking, quiet, central, pool,\nviews) the seed picker biases by — see chat_manager → extract_cross_\ncity_args → /agent/cross-city-search route emission. First-pass policy\ndowngrades all musts to nice and emits `apply_strategy='apply_relax'`.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cubi-estate-openapi.yml#/components/schemas/AgentCrossCitySearchRequest",
  "properties": {
    "chat_id": {
      "type": "integer",
      "title": "Chat Id"
    },
    "city_a": {
      "type": "string",
      "minLength": 1,
      "title": "City A",
      "description": "Seed city (e.g. 'Lisboa')."
    },
    "city_b": {
      "type": "string",
      "minLength": 1,
      "title": "City B",
      "description": "Counterpart city (e.g. 'Madrid')."
    },
    "property_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Property Type"
    },
    "max_price": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Max Price"
    },
    "min_price": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Min Price"
    },
    "min_bedrooms": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Min Bedrooms"
    },
    "max_bedrooms": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Max Bedrooms"
    },
    "preferences": {
      "items": {
        "$ref": "#/$defs/ConceptConstraint"
      },
      "type": "array",
      "title": "Preferences"
    },
    "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"
    },
    "force_strict_musts": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Force Strict Musts",
      "default": false
    },
    "strict_axes": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Strict Axes"
    }
  },
  "type": "object",
  "required": [
    "chat_id",
    "city_a",
    "city_b"
  ],
  "$defs": {
    "ConceptConstraint": {
      "properties": {
        "concept_key": {
          "type": "string",
          "title": "Concept Key",
          "description": "Catalog concept_key OR derived axis (drive_time.airport / drive_time.town / drive_time.coast / drive_time.motorway)"
        },
        "op": {
          "type": "string",
          "enum": [
            "has",
            "not_has",
            "gte",
            "lte",
            "between",
            "eq"
          ],
          "title": "Op",
          "description": "Comparison operator",
          "default": "has"
        },
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Value",
          "description": "Value (or low end of range for op=between)"
        },
        "value_max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Value Max",
          "description": "High end of range for op=between"
        },
        "weight": {
          "type": "string",
          "enum": [
            "must",
            "nice"
          ],
          "title": "Weight",
          "description": "must = hard filter; nice = soft preference (boost only)",
          "default": "nice"
        },
        "or_group": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Or Group",
          "description": "Alternatives tag. Constraints that share the same or_group are ALTERNATIVES — satisfying ANY ONE of them is enough. Use it for \"either a pool or a sea view\": emit both with the same tag (e.g. 'a'). Constraints with no tag, and separate tags, are all required together. Only meaningful on weight='must'."
        }
      },
      "type": "object",
      "required": [
        "concept_key"
      ],
      "title": "ConceptConstraint",
      "description": "One soft or hard constraint outside the rigid PropertyFilter columns.\n\n`concept_key` is either a catalog concept (e.g. ``views.mountain_view``) or a\nderived axis from the fixed allowlist below — those map to non-catalog\nsources (currently `listing_nearest_drive` for commute times).\n\nUsed only when ``FILTER_PREFERENCES_MODE`` is ``log`` or ``apply``. The\nlegacy code path never instantiates these."
    }
  }
}