openapi: 3.1.0
info:
  title: Agri-Access Scoring Adapter API
  version: 1.0.0
  description: |
    Internal contract between scoring-service and agri-access-worker.
    Not exposed to browser clients.

servers:
  - url: http://agri-access-worker:5001
    description: Internal worker (private subnet)

paths:
  /api/model-status:
    get:
      operationId: getModelStatus
      summary: Worker health and model readiness
      responses:
        "200":
          description: Model status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelStatusResponse"

  /api/analyze:
    post:
      operationId: analyzeCredit
      summary: Run Prithvi + ML + Basel III scoring
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgriAccessAnalyzeRequest"
      responses:
        "200":
          description: Scoring result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgriAccessAnalyzeResponse"
        "401":
          description: Missing or invalid bearer token
        "503":
          description: Worker unavailable

  /api/farmer/explain:
    post:
      operationId: explainScore
      summary: Gemini farmer explanation (uz/ru/en)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FarmerExplainRequest"
      responses:
        "200":
          description: Localized explanation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FarmerExplainResponse"

  /api/shap-visualization/{outputType}:
    post:
      operationId: shapVisualization
      summary: SHAP chart data for admin/deep-dive
      security:
        - bearerAuth: []
      parameters:
        - name: outputType
          in: path
          required: true
          schema:
            type: string
            enum: [bar, beeswarm, waterfall]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: Visualization payload
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  schemas:
    ModelStatusResponse:
      type: object
      properties:
        model_ready:
          type: boolean
        model_version:
          type: string
        country_profile:
          type: string
          example: UZ

    AgriAccessAnalyzeRequest:
      type: object
      required:
        - farmerName
        - latitude
        - longitude
        - farmSize
        - primaryCrop
        - loanAmount
        - loanTerm
        - countryCode
      properties:
        farmerName:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        farmSize:
          type: number
          description: Hectares
        primaryCrop:
          type: string
        loanAmount:
          type: number
          description: UZS
        loanTerm:
          type: integer
        loanPurpose:
          type: string
        collateralType:
          type: string
        monthlyIncome:
          type: number
        existingLoans:
          type: number
        repaymentHistory:
          type: string
        yearsFarming:
          type: integer
        farmerAge:
          type: integer
        ndviSnapshot:
          type: object
          additionalProperties: true
        countryCode:
          type: string
          enum: [UZ]
        consentCreditBureau:
          type: boolean

    AgriAccessAnalyzeResponse:
      type: object
      properties:
        success:
          type: boolean
        basel_iii_results:
          type: object
          properties:
            credit_score:
              type: number
              minimum: 300
              maximum: 850
            probability_of_default:
              type: number
            risk_rating:
              type: string
            ifrs9_stage:
              type: integer
              minimum: 1
              maximum: 3
            expected_credit_loss:
              type: number
        cbuClass:
          type: integer
          minimum: 1
          maximum: 5
          description: CBU collectibility class (replaces SLIK for UZ)
        shap_explanations:
          type: object
          properties:
            credit_score:
              type: object
              properties:
                features:
                  type: array
                  items:
                    type: object
                    properties:
                      feature:
                        type: string
                      shap_value:
                        type: number
                      value:
                        type: number
        satellite_analysis:
          type: object
          additionalProperties: true
        weather_analysis:
          type: object
          additionalProperties: true
        browseImages:
          type: array
          items:
            type: string
            format: uri

    FarmerExplainRequest:
      type: object
      required:
        - score
        - language
      properties:
        score:
          type: number
        language:
          type: string
          enum: [uz, ru, en]
        topFactors:
          type: array
          items:
            type: string
        farmerName:
          type: string

    FarmerExplainResponse:
      type: object
      properties:
        explanation:
          type: string
        language:
          type: string

    AgriAccessScoreRequest:
      type: object
      required:
        - onboardingSessionId
        - countryCode
        - farmer
        - parcel
        - finance
        - consent
      properties:
        onboardingSessionId:
          type: string
          format: uuid
        countryCode:
          type: string
          enum: [UZ]
        farmer:
          type: object
          properties:
            fullName:
              type: string
            dateOfBirth:
              type: string
              format: date
            yearsFarming:
              type: integer
            primaryLanguage:
              type: string
              enum: [uz, ru, en]
        parcel:
          type: object
          properties:
            latitude:
              type: number
            longitude:
              type: number
            areaHa:
              type: number
            primaryCrop:
              type: string
            ndviSnapshot:
              type: object
              additionalProperties: true
        finance:
          type: object
          properties:
            amountUzs:
              type: number
            termMonths:
              type: integer
            purpose:
              type: string
            monthlyIncomeUzs:
              type: number
            existingLoansUzs:
              type: number
            repaymentHistory:
              type: string
        collateral:
          type: object
          properties:
            assetType:
              type: string
        consent:
          type: object
          properties:
            creditBureau:
              type: boolean
            gisSatellite:
              type: boolean
        idempotencyKey:
          type: string

    ScoringJobAccepted:
      type: object
      properties:
        jobId:
          type: string
        status:
          type: string
          enum: [accepted, scoring]

    AgriAccessScoreResult:
      type: object
      properties:
        jobId:
          type: string
        status:
          type: string
          enum: [scoring, completed, failed]
        scoringPhase:
          type: string
          enum: [geo, documents, scoring, finalize]
        result:
          $ref: "#/components/schemas/AgriAccessAnalyzeResponse"
