openapi.yaml

openapi: 3.0.3

info:
  title: RoadSense AI — Insights API
  description: |
    **Civic Signal Intelligence System**

    RoadSense AI passively monitors public signals — Reddit posts, local news RSS,
    YouTube comments, and weather data — and uses a multi-agent AI pipeline to detect
    emerging road infrastructure damage before complaints are filed.

    ## How it works

    1. **Ingest** — Public signals arrive via scrapers (hourly) or direct POST
    2. **Translate** — AWS Translate auto-detects language and converts to English
    3. **Classify** — Amazon Nova Micro determines if signal is road-related
    4. **Context** — Amazon Nova Micro filters sarcasm, speculation; assigns urgency
    5. **Correlate** — Titan Embeddings V2 clusters signals by geo (500m) + time (7 days)
    6. **Infer** — Deterministic scoring produces confidence (0–100) and severity
    7. **Explain** — Amazon Nova Lite generates human-readable incident summary

    An incident is **created** when confidence > 60 and **archived** when confidence < 30.

    ## Authentication

    All endpoints require an API key passed via the `x-api-key` header.

    ## Rate Limits

    | Endpoint          | Limit             |
    |-------------------|--------------------|
    | POST /ingest-signal | 1,000 requests/hr |
    | GET endpoints       | 100 requests/min  |

  version: 1.0.0
  contact:
    name: Team Iceberg
    url: https://github.com/Sujith-RMD/RoadSense-AI
  license:
    name: MIT

servers:
  - url: https://api.roadsense.dev
    description: Development server (AWS API Gateway)

tags:
  - name: Signals
    description: Ingest multilingual road signals for AI processing
  - name: Incidents
    description: Retrieve AI-generated road damage incidents
  - name: Feedback
    description: Ground-truth validation from municipal authorities
  - name: Export
    description: Bulk data export


# ─── Security ─────────────────────────────────────────────────────────────────

security:
  - ApiKeyAuth: []


# ─── Paths ────────────────────────────────────────────────────────────────────

paths:

  # ── Signal Ingestion ──────────────────────────────────────────────────────

  /ingest-signal:
    post:
      operationId: ingestSignal
      tags: [Signals]
      summary: Ingest a new signal
      description: |
        Accepts a multilingual road signal and queues it for the AI pipeline.

        The signal passes through:
        - **PII anonymisation** — Reddit usernames, emails, phone numbers stripped
        - **Deduplication** — content-hash prevents re-processing identical signals
        - **Location normalisation** — coordinates normalised to `{lat, lon}` format
        - **AWS Translate** — auto-detect language, translate to English
        - **Classification → Intent → Correlation → Inference → Explanation**

        Signals in any language are accepted. Non-English content is translated
        automatically; the original text and detected language are preserved.

        Weather signals (`source: "weather"`) are pre-classified without calling
        Nova Micro — they skip directly to correlation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignalInput'
            examples:
              hindi_pothole:
                summary: Hindi pothole report
                value:
                  signal_id: "550e8400-e29b-41d4-a716-446655440000"
                  original_content: "MG Road par bahut bada gaddha hai, gaadi ka tyre fat gaya"
                  source: "reddit"
                  timestamp: "2026-02-15T10:30:00Z"
                  location:
                    latitude: 12.9752
                    longitude: 77.6063
                    address: "MG Road, Bangalore"
              english_flooding:
                summary: English flooding report
                value:
                  signal_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
                  original_content: "Silk Board junction completely waterlogged, cars stalling in knee-deep water"
                  translated_content: "Silk Board junction completely waterlogged, cars stalling in knee-deep water"
                  detected_language: "en"
                  source: "reddit"
                  timestamp: "2026-02-15T16:45:00Z"
                  location:
                    latitude: 12.9178
                    longitude: 77.6230
                    address: "Silk Board Junction, Bangalore"
              tamil_surface_wear:
                summary: Tamil surface damage report
                value:
                  signal_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                  original_content: "சாலை முழுவதும் விரிசல், வாகனம் ஓட்ட முடியவில்லை"
                  source: "youtube"
                  timestamp: "2026-02-14T08:20:00Z"
                  location:
                    latitude: 13.0827
                    longitude: 80.2707
                    address: "Anna Salai, Chennai"
              weather_alert:
                summary: Weather correlation signal
                value:
                  signal_id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                  original_content: "Heavy rainfall warning: 120mm expected in next 6 hours"
                  translated_content: "Heavy rainfall warning: 120mm expected in next 6 hours"
                  detected_language: "en"
                  source: "weather"
                  timestamp: "2026-02-15T06:00:00Z"
                  location:
                    latitude: 12.9716
                    longitude: 77.5946
                    address: "Bangalore"
              news_rss:
                summary: News RSS article
                value:
                  signal_id: "c3d4e5f6-a7b8-9012-cdef-123456789012"
                  original_content: "Pothole menace continues on Outer Ring Road; BBMP promises repair in 48 hours"
                  translated_content: "Pothole menace continues on Outer Ring Road; BBMP promises repair in 48 hours"
                  detected_language: "en"
                  source: "news"
                  timestamp: "2026-02-15T07:30:00Z"
                  location:
                    latitude: 12.9352
                    longitude: 77.6245
                    address: "Outer Ring Road, Bangalore"
      responses:
        '201':
          description: Signal accepted and queued for AI processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignalAccepted'
        '400':
          description: Invalid payload — missing required fields or malformed data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_content:
                  summary: Missing required field
                  value:
                    error: "validation_error"
                    message: "original_content is required"
                    status: 400
                invalid_source:
                  summary: Invalid source enum
                  value:
                    error: "validation_error"
                    message: "source must be one of: reddit, youtube, news, weather"
                    status: 400
        '409':
          description: Duplicate signal — already ingested (content-hash match)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "duplicate_signal"
                message: "Signal with identical content hash already exists"
                status: 409
        '429':
          description: Rate limit exceeded (1,000 requests/hr)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'


  # ── Incidents ─────────────────────────────────────────────────────────────

  /incidents:
    get:
      operationId: listIncidents
      tags: [Incidents]
      summary: List all incidents
      description: |
        Returns AI-generated road damage incidents, filtered by optional query parameters.

        Each incident is created when a cluster of correlated signals reaches a
        **confidence score > 60**. Incidents are auto-archived when confidence
        decays below **30** due to lack of new supporting signals.

        Results are sorted by `confidence_score` descending (highest confidence first).
      parameters:
        - name: status
          in: query
          required: false
          description: Filter by incident status
          schema:
            type: string
            enum: [active, confirmed, monitoring, archived]
            default: active
          example: active
        - name: severity
          in: query
          required: false
          description: Filter by minimum severity level
          schema:
            type: string
            enum: [low, medium, high, critical]
          example: high
        - name: city
          in: query
          required: false
          description: Filter by city name (case-insensitive partial match)
          schema:
            type: string
          example: bangalore
        - name: damage_type
          in: query
          required: false
          description: Filter by damage type
          schema:
            type: string
            enum: [pothole, surface_wear, flooding, general]
          example: pothole
        - name: min_confidence
          in: query
          required: false
          description: Minimum confidence score (0–100)
          schema:
            type: integer
            minimum: 0
            maximum: 100
          example: 60
        - name: limit
          in: query
          required: false
          description: Maximum number of incidents to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          example: 20
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
      responses:
        '200':
          description: List of incidents
          content:
            application/json:
              schema:
                type: object
                properties:
                  incidents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Incident'
                  total:
                    type: integer
                    description: Total number of incidents matching filters
                    example: 42
                  limit:
                    type: integer
                    example: 50
                  offset:
                    type: integer
                    example: 0
              example:
                incidents:
                  - incident_id: "INC-2026-001"
                    title: "Critical Road Collapse Cluster - Electronic City"
                    description: "High-density reports indicate road surface collapse near Electronic City Phase 1 flyover entry."
                    location:
                      latitude: 12.8401
                      longitude: 77.6772
                      address: "Electronic City Phase 1, Bengaluru"
                    damage_type: "pothole"
                    confidence_score: 92
                    severity_level: "critical"
                    status: "active"
                    signal_count: 23
                    affected_radius_meters: 165
                    explanation: "23 semantically similar road-damage signals clustered within 120m radius over 76 minutes."
                    first_reported_at: "2026-02-15T05:42:00Z"
                    last_updated_at: "2026-02-15T06:58:00Z"
                  - incident_id: "INC-2026-002"
                    title: "Severe Pothole Formation - MG Road"
                    description: "Multiple commuters report water-filled craters causing vehicle swerving near MG Road metro stretch."
                    location:
                      latitude: 12.9752
                      longitude: 77.6063
                      address: "MG Road, Bengaluru"
                    damage_type: "pothole"
                    confidence_score: 88
                    severity_level: "high"
                    status: "active"
                    signal_count: 19
                    affected_radius_meters: 130
                    explanation: "Spatial + temporal clustering of pothole-related signals validated by correlation agent."
                    first_reported_at: "2026-02-15T07:10:00Z"
                    last_updated_at: "2026-02-15T08:25:00Z"
                total: 42
                limit: 50
                offset: 0
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'


  # ── Confidence ────────────────────────────────────────────────────────────

  /confidence/{id}:
    get:
      operationId: getConfidence
      tags: [Incidents]
      summary: Get confidence details for an incident
      description: |
        Returns the current confidence score, scoring breakdown, and full
        confidence history for a specific incident.

        **Scoring breakdown** shows how each factor contributed:

        | Factor                   | Max Points |
        |--------------------------|-----------|
        | Source diversity          | 30        |
        | Signal count             | 20        |
        | Urgency level consensus  | 20        |
        | Classification confidence| 20        |
        | Recency                  | 10        |
        | Weather correlation      | 10        |
        | **Total (clamped)**      | **100**   |

        Confidence **decays** over time if no new signals arrive.
        - 24–48h without signals: −5 points
        - 48–72h: −10 points
        - 72–120h: −15 points
        - 120h+: −20 points
      parameters:
        - name: id
          in: path
          required: true
          description: Unique incident identifier
          schema:
            type: string
          example: "INC-2026-001"
      responses:
        '200':
          description: Confidence details with scoring breakdown and history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfidenceDetail'
              example:
                incident_id: "INC-2026-001"
                confidence_score: 92
                severity_level: "critical"
                scoring_breakdown:
                  source_diversity: 28.0
                  signal_count: 20.0
                  urgency: 20.0
                  classification_confidence: 18.4
                  recency: 10.0
                  weather_correlation: 10.0
                  raw_total: 106.4
                  clamped_total: 92
                confidence_history:
                  - timestamp: "2026-02-15T05:42:00Z"
                    score: 65
                    event: "incident_created"
                  - timestamp: "2026-02-15T06:10:00Z"
                    score: 78
                    event: "new_signals"
                  - timestamp: "2026-02-15T06:58:00Z"
                    score: 92
                    event: "new_signals"
                thresholds:
                  creation: 60
                  archive: 30
        '404':
          description: Incident not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "not_found"
                message: "No incident found with id: INC-9999-999"
                status: 404
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'


  # ── Feedback ──────────────────────────────────────────────────────────────

  /feedback:
    post:
      operationId: submitFeedback
      tags: [Feedback]
      summary: Submit ground-truth feedback
      description: |
        Municipal authorities use this endpoint to validate or dismiss
        AI-detected incidents based on field inspection.

        **Feedback directly adjusts confidence scores:**

        | Feedback Value   | Confidence Adjustment |
        |------------------|-----------------------|
        | `confirmed`      | **+20 points**        |
        | `false_positive`  | **−40 points**        |
        | `unsure`         | No change             |

        If `false_positive` drops confidence below the archive threshold (30),
        the incident is automatically archived.

        If `confirmed`, the incident status changes to `confirmed`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackInput'
            examples:
              confirmed:
                summary: Field inspection confirms pothole
                value:
                  incident_id: "INC-2026-001"
                  feedback_value: "confirmed"
                  resolution: "under_repair"
                  notes: "Pothole confirmed, ~2ft wide and 6in deep. BBMP crew dispatched."
                  submitted_by: "inspector_ward_42"
              false_positive:
                summary: No damage found on site
                value:
                  incident_id: "INC-2026-007"
                  feedback_value: "false_positive"
                  resolution: "not_found"
                  notes: "Visited location, road surface is fine. Signals appear to be about a different road."
                  submitted_by: "inspector_ward_15"
              unsure:
                summary: Inconclusive inspection
                value:
                  incident_id: "INC-2026-003"
                  feedback_value: "unsure"
                  notes: "Minor wear visible but unclear if it matches the reports. Will revisit after rain."
      responses:
        '200':
          description: Feedback accepted and confidence score updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackResult'
              example:
                incident_id: "INC-2026-001"
                feedback_value: "confirmed"
                score_before: 92
                score_after: 100
                adjustment: 20
                new_status: "confirmed"
                message: "Feedback recorded. Confidence adjusted from 92 to 100 (clamped)."
        '400':
          description: Invalid feedback payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_incident_id:
                  summary: Missing incident_id
                  value:
                    error: "validation_error"
                    message: "incident_id is required"
                    status: 400
                invalid_feedback_value:
                  summary: Invalid feedback_value
                  value:
                    error: "validation_error"
                    message: "feedback_value must be one of: confirmed, false_positive, unsure"
                    status: 400
        '404':
          description: Incident not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'


  # ── Export ────────────────────────────────────────────────────────────────

  /export:
    get:
      operationId: exportIncidents
      tags: [Export]
      summary: Export incident data
      description: |
        Bulk export of all incidents with full signal metadata.
        Intended for analytics, reporting, and integration with municipal GIS systems.
      parameters:
        - name: format
          in: query
          required: false
          description: Export format
          schema:
            type: string
            enum: [json, csv]
            default: json
          example: json
        - name: status
          in: query
          required: false
          description: Filter exported incidents by status
          schema:
            type: string
            enum: [active, confirmed, monitoring, archived]
        - name: since
          in: query
          required: false
          description: Export incidents created after this timestamp (ISO 8601)
          schema:
            type: string
            format: date-time
          example: "2026-02-01T00:00:00Z"
      responses:
        '200':
          description: Exported incident data
          content:
            application/json:
              schema:
                type: object
                properties:
                  exported_at:
                    type: string
                    format: date-time
                    example: "2026-02-15T12:00:00Z"
                  count:
                    type: integer
                    example: 10
                  incidents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Incident'
            text/csv:
              schema:
                type: string
                description: CSV with headers — incident_id, title, latitude, longitude, address, damage_type, confidence_score, severity_level, status, signal_count, first_reported_at, last_updated_at
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'


# ─── Components ───────────────────────────────────────────────────────────────

components:

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key provided by the RoadSense AI platform admin


  schemas:

    # ── Signal Input ──────────────────────────────────────────────────────

    SignalInput:
      type: object
      required:
        - signal_id
        - original_content
        - source
        - timestamp
      properties:
        signal_id:
          type: string
          format: uuid
          description: Unique identifier for the signal (UUID v4)
          example: "550e8400-e29b-41d4-a716-446655440000"
        original_content:
          type: string
          description: Raw text content in any language (Hindi, Tamil, Telugu, etc.)
          minLength: 1
          maxLength: 5000
          example: "MG Road par bahut bada gaddha hai, gaadi ka tyre fat gaya"
        translated_content:
          type: string
          nullable: true
          description: |
            English translation. If omitted, AWS Translate auto-translates
            from the detected language. If the signal is already in English,
            this should match original_content.
          example: "There is a large pothole on MG Road, car tyre burst"
        detected_language:
          type: string
          nullable: true
          description: |
            ISO 639-1 language code. Auto-detected by AWS Translate if omitted.
            Common values: en, hi, ta, te, kn, bn, mr, ml, gu, pa, ur
          example: "hi"
        source:
          type: string
          enum: [reddit, youtube, news, weather]
          description: |
            Origin of the signal:
            - `reddit` — scraped from Indian city subreddits via PRAW
            - `youtube` — video titles or comments via YouTube Data API v3
            - `news` — RSS feeds from Times of India, NDTV, The Hindu, Deccan Herald
            - `weather` — OpenWeatherMap rainfall/flooding alerts
          example: "reddit"
        timestamp:
          type: string
          format: date-time
          description: When the signal was originally posted/published (ISO 8601)
          example: "2026-02-15T10:30:00Z"
        location:
          $ref: '#/components/schemas/SignalLocation'
        metadata:
          type: object
          nullable: true
          description: Optional source-specific metadata
          properties:
            subreddit:
              type: string
              description: Reddit subreddit name (for reddit source)
              example: "r/bangalore"
            post_id:
              type: string
              description: Reddit post ID or YouTube video ID (for deduplication)
              example: "1abc2de"
            source_name:
              type: string
              description: Specific source name (e.g. times_of_india, ndtv, openweathermap)
              example: "times_of_india"
            city:
              type: string
              description: City extracted from source context
              example: "Bangalore"

    SignalLocation:
      type: object
      description: |
        Geographic location of the signal. At least `address` should be provided.
        Accepts both flat format (`latitude`/`longitude`) and nested format
        (`coordinates.lat`/`coordinates.lon`) — the system normalises internally.
      properties:
        latitude:
          type: number
          format: double
          description: Latitude in decimal degrees
          minimum: -90
          maximum: 90
          example: 12.9752
        longitude:
          type: number
          format: double
          description: Longitude in decimal degrees
          minimum: -180
          maximum: 180
          example: 77.6063
        accuracy_meters:
          type: integer
          nullable: true
          description: Location accuracy in meters (lower = more precise)
          example: 100
        address:
          type: string
          description: Human-readable address or landmark
          example: "MG Road, Bangalore"


    # ── Signal Accepted Response ──────────────────────────────────────────

    SignalAccepted:
      type: object
      properties:
        signal_id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        status:
          type: string
          enum: [accepted, duplicate_skipped]
          example: "accepted"
        detected_language:
          type: string
          nullable: true
          description: Language detected by AWS Translate
          example: "hi"
        message:
          type: string
          example: "Signal accepted and queued for AI processing"


    # ── Processed Signal (full) ───────────────────────────────────────────

    ProcessedSignal:
      type: object
      description: A signal after passing through the full AI pipeline
      properties:
        signal_id:
          type: string
          format: uuid
        original_content:
          type: string
        translated_content:
          type: string
          nullable: true
        detected_language:
          type: string
        source:
          type: string
          enum: [reddit, youtube, news, weather]
        timestamp:
          type: string
          format: date-time
        location:
          $ref: '#/components/schemas/SignalLocation'
        classification:
          $ref: '#/components/schemas/Classification'
        intent:
          $ref: '#/components/schemas/Intent'


    # ── Classification (Agent 1 output) ───────────────────────────────────

    Classification:
      type: object
      description: |
        Output of the Classification Agent (Amazon Nova Micro).
        Determines whether the signal describes a road infrastructure problem.
      properties:
        is_road_related:
          type: boolean
          description: Whether the signal describes a road/highway/street condition issue
          example: true
        damage_type:
          type: string
          nullable: true
          enum: [pothole, surface_wear, flooding, general]
          description: |
            Type of road damage detected:
            - `pothole` — holes, craters, depressions (gaddha, khada)
            - `surface_wear` — cracks, worn asphalt, uneven surface
            - `flooding` — waterlogging, road underwater
            - `general` — road-related but doesn't fit above
            - `null` — not road-related
          example: "pothole"
        confidence:
          type: number
          format: float
          minimum: 0.01
          maximum: 0.99
          description: |
            AI confidence in the classification (0.01–0.99).
            Sarcastic or speculative content receives 0.1–0.4.
            Clear, direct reports receive 0.7–0.99.
            Never exactly 0.0 or 1.0.
          example: 0.92
        reasoning:
          type: string
          description: One-sentence explanation from Nova Micro
          example: "Direct report of pothole with specific location and vehicle damage"


    # ── Intent (Agent 2 output) ───────────────────────────────────────────

    Intent:
      type: object
      description: |
        Output of the Intent & Context Agent (Amazon Nova Micro).
        Determines whether the signal is a genuine problem report vs. noise.
      properties:
        is_problem_report:
          type: boolean
          description: Whether this is a genuine problem report (vs. sarcasm, speculation)
          example: true
        urgency_level:
          type: string
          enum: [low, medium, high, critical]
          description: |
            Assessed urgency:
            - `critical` — immediate danger, accident, road blocked
            - `high` — significant damage, vehicle damage, multiple complaints
            - `medium` — noticeable damage, inconvenience
            - `low` — minor issue, old report, vague mention
          example: "high"
        context_type:
          type: string
          enum: [direct_report, indirect_mention, news_article, weather_alert, speculation, sarcasm, ambiguous]
          description: |
            Type of signal context:
            - `direct_report` — first-hand account
            - `indirect_mention` — heard from someone else
            - `news_article` — formal news reporting
            - `weather_alert` — weather-based road risk
            - `speculation` — guessing a problem might exist
            - `sarcasm` — sarcastic complaint
            - `ambiguous` — unclear intent
          example: "direct_report"
        confidence_modifier:
          type: number
          format: float
          minimum: -0.4
          maximum: 0.2
          description: |
            Adjustment applied to classification confidence:
            - +0.1 to +0.2 for direct first-hand reports with specifics
            - 0.0 for neutral/clear reports
            - −0.1 to −0.2 for indirect mentions, speculation
            - −0.3 to −0.4 for clear sarcasm or non-reports
          example: 0.1
        reasoning:
          type: string
          example: "First-hand account with specific location and damage description"


    # ── Incident ──────────────────────────────────────────────────────────

    Incident:
      type: object
      description: |
        An AI-detected road infrastructure problem, created when a cluster of
        correlated signals reaches confidence > 60.
      required:
        - incident_id
        - confidence_score
        - severity_level
        - status
      properties:
        incident_id:
          type: string
          description: Unique incident identifier (format INC-YYYY-NNN)
          example: "INC-2026-001"
        title:
          type: string
          description: Short descriptive title
          example: "Critical Road Collapse Cluster - Electronic City"
        description:
          type: string
          description: Brief description of the detected problem
          example: "High-density reports indicate road surface collapse near Electronic City Phase 1 flyover entry."
        location:
          type: object
          properties:
            latitude:
              type: number
              format: double
              example: 12.8401
            longitude:
              type: number
              format: double
              example: 77.6772
            address:
              type: string
              example: "Electronic City Phase 1, Bengaluru"
        damage_type:
          type: string
          enum: [pothole, surface_wear, flooding, general]
          description: Dominant damage type across clustered signals
          example: "pothole"
        confidence_score:
          type: integer
          minimum: 0
          maximum: 100
          description: |
            Composite confidence score (0–100).
            Created at > 60, archived at < 30.
            Computed from source diversity, signal count, urgency,
            classification confidence, recency, and weather correlation.
          example: 92
        severity_level:
          type: string
          enum: [low, medium, high, critical]
          description: |
            Severity classification:
            - `critical` — confidence ≥ 85 OR any signal has critical urgency
            - `high` — confidence ≥ 65 OR any signal has high urgency
            - `medium` — confidence ≥ 45
            - `low` — everything else
          example: "critical"
        status:
          type: string
          enum: [active, confirmed, monitoring, archived]
          description: |
            Incident lifecycle state:
            - `active` — confidence > 60, no feedback yet
            - `confirmed` — authority confirmed via POST /feedback
            - `monitoring` — confidence 30–60, watching for new signals
            - `archived` — confidence < 30 or marked false_positive
          example: "active"
        signal_count:
          type: integer
          description: Number of signals in the cluster
          example: 23
        affected_radius_meters:
          type: integer
          description: Radius of the signal cluster in meters (max 500m)
          example: 165
        explanation:
          type: string
          description: |
            Human-readable AI-generated summary (Amazon Nova Lite).
            Written for municipal officials — references source types,
            languages, and evidence chain.
          example: "23 semantically similar road-damage signals clustered within 120m radius over 76 minutes."
        signal_ids:
          type: array
          items:
            type: string
            format: uuid
          description: UUIDs of all contributing signals
        first_reported_at:
          type: string
          format: date-time
          description: Timestamp of the earliest signal in the cluster
          example: "2026-02-15T05:42:00Z"
        last_updated_at:
          type: string
          format: date-time
          description: Timestamp of the most recent update (new signal or feedback)
          example: "2026-02-15T06:58:00Z"
        confidence_history:
          type: array
          items:
            $ref: '#/components/schemas/ConfidenceHistoryEntry'
        latest_feedback:
          $ref: '#/components/schemas/FeedbackRecord'


    # ── Confidence Detail ─────────────────────────────────────────────────

    ConfidenceDetail:
      type: object
      properties:
        incident_id:
          type: string
          example: "INC-2026-001"
        confidence_score:
          type: integer
          minimum: 0
          maximum: 100
          example: 92
        severity_level:
          type: string
          enum: [low, medium, high, critical]
          example: "critical"
        scoring_breakdown:
          type: object
          description: How each factor contributed to the score
          properties:
            source_diversity:
              type: number
              description: Points from distinct source types (max 30)
              example: 28.0
            signal_count:
              type: number
              description: Points from number of signals (max 20)
              example: 20.0
            urgency:
              type: number
              description: Points from urgency level consensus (max 20)
              example: 20.0
            classification_confidence:
              type: number
              description: Points from average classification confidence (max 20)
              example: 18.4
            recency:
              type: number
              description: Points from signal freshness (max 10)
              example: 10.0
            weather_correlation:
              type: number
              description: Bonus for weather signal correlation (max 10)
              example: 10.0
            raw_total:
              type: number
              description: Sum before clamping (max theoretical 110)
              example: 106.4
            clamped_total:
              type: integer
              description: Final score clamped to 0–100
              example: 92
        confidence_history:
          type: array
          items:
            $ref: '#/components/schemas/ConfidenceHistoryEntry'
        thresholds:
          type: object
          description: System thresholds for reference
          properties:
            creation:
              type: integer
              description: Confidence required to create a new incident
              example: 60
            archive:
              type: integer
              description: Confidence below which incidents are archived
              example: 30

    ConfidenceHistoryEntry:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          example: "2026-02-15T05:42:00Z"
        score:
          type: integer
          minimum: 0
          maximum: 100
          example: 65
        event:
          type: string
          enum: [incident_created, new_signals, confidence_decay, feedback_adjustment]
          description: What caused this score change
          example: "incident_created"


    # ── Feedback ──────────────────────────────────────────────────────────

    FeedbackInput:
      type: object
      required:
        - incident_id
        - feedback_value
      properties:
        incident_id:
          type: string
          description: ID of the incident being validated
          example: "INC-2026-001"
        feedback_value:
          type: string
          enum: [confirmed, false_positive, unsure]
          description: |
            Ground-truth assessment:
            - `confirmed` — field inspection confirms the road damage (+20 confidence)
            - `false_positive` — no damage found at location (−40 confidence)
            - `unsure` — inconclusive inspection (no confidence change)
          example: "confirmed"
        resolution:
          type: string
          nullable: true
          enum: [repaired, under_repair, not_found, pending]
          description: |
            Current state of the road issue (optional):
            - `repaired` — damage has been fixed
            - `under_repair` — repair crew dispatched or in progress
            - `not_found` — no damage at reported location
            - `pending` — awaiting inspection or repair
          example: "under_repair"
        notes:
          type: string
          nullable: true
          maxLength: 2000
          description: Free-text notes from the authority inspector
          example: "Pothole confirmed, ~2ft wide and 6in deep. BBMP crew dispatched."
        submitted_by:
          type: string
          nullable: true
          description: Identifier of the authority submitting feedback
          example: "inspector_ward_42"

    FeedbackResult:
      type: object
      properties:
        incident_id:
          type: string
          example: "INC-2026-001"
        feedback_value:
          type: string
          enum: [confirmed, false_positive, unsure]
          example: "confirmed"
        score_before:
          type: integer
          description: Confidence score before feedback
          example: 92
        score_after:
          type: integer
          description: Confidence score after feedback (clamped 0–100)
          example: 100
        adjustment:
          type: integer
          description: Points added or removed
          example: 20
        new_status:
          type: string
          enum: [active, confirmed, archived]
          description: Incident status after feedback was applied
          example: "confirmed"
        message:
          type: string
          example: "Feedback recorded. Confidence adjusted from 92 to 100 (clamped)."

    FeedbackRecord:
      type: object
      nullable: true
      description: Most recent feedback applied to an incident
      properties:
        feedback_id:
          type: string
        feedback_value:
          type: string
          enum: [confirmed, false_positive, unsure]
        resolution:
          type: string
          nullable: true
          enum: [repaired, under_repair, not_found, pending]
        notes:
          type: string
          nullable: true
        submitted_by:
          type: string
          nullable: true
        submitted_at:
          type: string
          format: date-time
        score_before:
          type: integer
        score_after:
          type: integer
        adjustment:
          type: integer


    # ── Error ─────────────────────────────────────────────────────────────

    Error:
      type: object
      required:
        - error
        - message
        - status
      properties:
        error:
          type: string
          description: Machine-readable error code
          enum: [validation_error, not_found, duplicate_signal, rate_limited, internal_error]
          example: "validation_error"
        message:
          type: string
          description: Human-readable error description
          example: "original_content is required"
        status:
          type: integer
          description: HTTP status code
          example: 400