openapi: 3.1.0
info:
  title: addrkit
  version: "2.0.0"
  description: >
    Детерминированный многогородской сервис нормализации и поиска адресов.
    Ответ всегда берётся из реестра; LLM не участвует в пути корректности.
    Сервис не знает ни про отключения, ни про другие события: это отдельная
    задача, которая может использовать addrkit как нормализатор.
servers:
  - url: http://localhost:6171
paths:
  /v1/resolve:
    post:
      summary: Разобрать и сопоставить адрес
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  maxLength: 512
                  example: "нск, 2-я Станционная улица 1/1 стр."
                city:
                  type: string
                  maxLength: 128
                  description: >
                    Необязательная подсказка. Переопределяет город, найденный
                    в тексте адреса.
                  example: "Новосибирск"
      responses:
        "200":
          description: Результат сопоставления
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResolveResult"
        "400":
          description: Некорректный запрос
  /v1/city:
    post:
      summary: Нормализовать только название города
      description: >
        Отдельный сценарий для проектов, которым нужны названия городов, а не
        улицы. Возвращает канонический город по имени или алиасу.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
                  maxLength: 128
                  example: "нск"
      responses:
        "200":
          description: Результат
          content:
            application/json:
              schema:
                type: object
                required: [status]
                properties:
                  status:
                    type: string
                    enum: [found, not_found]
                  city: { type: string }
        "400":
          description: Некорректный запрос
  /v1/cities:
    get:
      summary: Канонические города, присутствующие в индексе
      responses:
        "200":
          description: Список городов
          content:
            application/json:
              schema:
                type: object
                required: [cities]
                properties:
                  cities:
                    type: array
                    items: { type: string }
  /v1/healthz:
    get:
      summary: Живость
      responses:
        "200": { description: ok }
  /v1/readyz:
    get:
      summary: Готовность (индекс загружен)
      responses:
        "200": { description: ready }
        "503": { description: not ready }
  /v1/version:
    get:
      summary: Версия данных
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  data_version: { type: string }
components:
  schemas:
    Status:
      type: string
      enum: [found, partial, ambiguous, not_found]
    Candidate:
      type: object
      required: [address, score]
      properties:
        address: { type: string }
        city: { type: string }
        district: { type: string }
        house: { type: string }
        structure: { type: string }
        score: { type: number, format: double }
    ResolveResult:
      type: object
      required: [status, confidence]
      properties:
        status: { $ref: "#/components/schemas/Status" }
        address: { type: string }
        city: { type: string }
        district: { type: string }
        confidence: { type: number, format: double }
        candidates:
          type: array
          items: { $ref: "#/components/schemas/Candidate" }
        data_version: { type: string }