openapi: 3.0.0
info:
  title: SLOP API
  description: A SLOP pattern implementation with dynamic model endpoints, tools, memory, resources, and payment simulation, including casino games.
  version: 1.0.0

servers:
  - url: https://slop.unturf.com
    description: Production unturf SLOP server
  - url: http://localhost:31337
    description: Local development SLOP server

paths:
  /chat:
    post:
      summary: Send a message to an AI model
      tags:
        - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: Successful response with AI message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /models:
    get:
      summary: List available models
      tags:
        - Models
      responses:
        '200':
          description: List of model IDs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsResponse'
  /tools:
    get:
      summary: List available tools
      tags:
        - Tools
      responses:
        '200':
          description: List of tools
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolsResponse'
  /tools/{tool_id}:
    post:
      summary: Use a specific tool
      tags:
        - Tools
      parameters:
        - name: tool_id
          in: path
          required: true
          schema:
            type: string
            enum: [calculator, greet, slots, blackjack]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CalculatorToolRequest'
                - $ref: '#/components/schemas/GreetToolRequest'
                - $ref: '#/components/schemas/SlotsToolRequest'
                - $ref: '#/components/schemas/BlackjackToolRequest'
            examples:
              calculator:
                summary: Calculator tool request
                value:
                  expression: "2 + 2"
              greet:
                summary: Greet tool request
                value:
                  name: "Alice"
              slots:
                summary: Slots game request
                value:
                  bet: 50
                  agent_id: "player1"
              blackjackStart:
                summary: Start a new blackjack game
                value:
                  bet: 100
                  agent_id: "player1"
              blackjackHit:
                summary: Hit in an existing blackjack game
                value:
                  agent_id: "player1"
                  game_id: "550e8400-e29b-41d4-a716-446655440000"
                  action: "hit"
      responses:
        '200':
          description: Tool execution result
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CalculatorToolResponse'
                  - $ref: '#/components/schemas/GreetToolResponse'
                  - $ref: '#/components/schemas/SlotsToolResponse'
                  - $ref: '#/components/schemas/BlackjackToolResponse'
              examples:
                calculator:
                  summary: Calculator result
                  value:
                    result: 4
                greet:
                  summary: Greet result
                  value:
                    result: "Hello, Alice!"
                slots:
                  summary: Slots game result
                  value:
                    explanation: "Slot Machine Rules: Bet an amount to spin three reels once. Match all 3 symbols for 10x your bet, 2 symbols for 2x your bet, or lose your bet if no match. Symbols: ['🍒', '🍋', '🍊', '🍇', '🔔', '💎']. You (agent player1) bet 50. Reels: ['🍒', '🍒', '🍒']. Jackpot! You matched all three symbols."
                    game_state:
                      reels: ["🍒", "🍒", "🍒"]
                    payout: 500
                    bet: 50
                    agent_id: "player1"
                    new_balance: 1450
                    game_complete: true
                blackjackStart:
                  summary: Start of a blackjack game
                  value:
                    explanation: "Blackjack Rules: Bet to play against the dealer. Goal is to get closer to 21 without going over. Number cards = face value, Face cards = 10, Ace = 1 or 11 (adjusted automatically). Hit to draw cards, stand to finish. Dealer stands on 17+. Win pays 2x, tie returns bet, loss takes bet. You (agent player1) started a new game with bet 100. Your hand: [10, 7] (Total: 17). Dealer’s up card: [6]."
                    game_id: "550e8400-e29b-41d4-a716-446655440000"
                    game_state:
                      player_hand: [10, 7]
                      player_total: 17
                      dealer_hand: [6]
                      dealer_total: 6
                    bet: 100
                    agent_id: "player1"
                    new_balance: 1000
                    game_complete: false
                blackjackHitBust:
                  summary: Hit resulting in bust
                  value:
                    explanation: "Blackjack: You chose to hit. Your hand: [10, 7, 8] (Total: 25). Dealer’s up card: [6]. Bust! You went over 21 and lose."
                    game_id: "550e8400-e29b-41d4-a716-446655440000"
                    game_state:
                      player_hand: [10, 7, 8]
                      player_total: 25
                      dealer_hand: [6]
                      dealer_total: 6
                    bet: 100
                    agent_id: "player1"
                    new_balance: 900
                    game_complete: true
        '400':
          description: Missing required parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Tool not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /memory:
    get:
      summary: List all memory keys
      tags:
        - Memory
      responses:
        '200':
          description: List of memory keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryListResponse'
        '503':
          description: Memory lock timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Store a key-value pair in memory
      tags:
        - Memory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemoryStoreRequest'
      responses:
        '200':
          description: Successfully stored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryStoreResponse'
        '400':
          description: Missing key or value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Memory lock timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /memory/{key}:
    get:
      summary: Retrieve a value by key from memory
      tags:
        - Memory
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Retrieved value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryGetResponse'
        '503':
          description: Memory lock timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete a memory key
      tags:
        - Memory
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryStoreResponse'
        '404':
          description: Key not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Memory lock timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /resources:
    get:
      summary: List all available resources
      tags:
        - Resources
      responses:
        '200':
          description: List of resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourcesResponse'
  /resources/{resource_id}:
    get:
      summary: Get a specific resource or nested resources by prefix
      description: |
        Retrieves a resource by its exact ID. If no exact match is found, performs a prefix search 
        (e.g., `/resources/foo` returns all resources under `foo/` like `foo/bar` and `foo/baz`).
      tags:
        - Resources
      parameters:
        - name: resource_id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the resource or a prefix for nested resources (e.g., "foo" for "foo/bar").
      responses:
        '200':
          description: Resource content or list of nested resources
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ResourceResponse'  # Exact match
                  - $ref: '#/components/schemas/ResourcesResponse'  # Prefix search
              examples:
                exactMatch:
                  summary: Exact resource match
                  value:
                    id: "hello"
                    content: "Hello, SLOP!"
                prefixMatch:
                  summary: Nested resources via prefix search
                  value:
                    resources:
                      - id: "foo/bar"
                        content: "Nested Foo Bar"
                      - id: "foo/baz"
                        content: "Nested Foo Baz"
                blackjackGame:
                  summary: Blackjack game state
                  value:
                    id: "casino/blackjack/games/550e8400-e29b-41d4-a716-446655440000"
                    content:
                      agent_id: "player1"
                      bet: 100
                      player_hand: [10, 7]
                      player_total: 17
                      dealer_hand: [6]
                      dealer_total: 6
                      status: "active"
        '404':
          description: No resource or nested resources found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      summary: Update or create a resource
      description: Updates an existing resource or creates a new one if it doesn’t exist.
      tags:
        - Resources
      parameters:
        - name: resource_id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the resource to update or create.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourceUpdateRequest'
      responses:
        '200':
          description: Resource updated or created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceUpdateResponse'
        '400':
          description: Missing content field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pay:
    post:
      summary: Simulate a payment
      tags:
        - Pay
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayRequest'
      responses:
        '200':
          description: Payment simulation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayResponse'

components:
  schemas:
    ChatRequest:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        model:
          type: string
          nullable: true
      required:
        - messages
    Message:
      type: object
      properties:
        role:
          type: string
          enum: [user, assistant, system]
        content:
          type: string
      required:
        - role
        - content
    ChatResponse:
      type: object
      properties:
        choices:
          type: array
          items:
            type: object
            properties:
              message:
                type: object
                properties:
                  content:
                    type: string
            required:
              - message
      required:
        - choices
    ModelsResponse:
      type: object
      properties:
        models:
          type: array
          items:
            type: string
      required:
        - models
    ToolsResponse:
      type: object
      properties:
        tools:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              description:
                type: string
              arguments:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    type:
                      type: string
                    description:
                      type: string
                    optional:
                      type: boolean
                  required:
                    - name
                    - type
                    - description
            required:
              - id
              - description
              - arguments
      required:
        - tools
    CalculatorToolRequest:
      type: object
      properties:
        expression:
          type: string
          description: The math expression to evaluate (e.g., "2 + 2")
      required:
        - expression
    GreetToolRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the person to greet
      required:
        - name
    SlotsToolRequest:
      type: object
      properties:
        bet:
          type: integer
          minimum: 1
          description: Amount to bet on the slot spin
        agent_id:
          type: string
          description: Unique identifier for the agent/player
      required:
        - bet
        - agent_id
    BlackjackToolRequest:
      type: object
      properties:
        bet:
          type: integer
          minimum: 1
          description: Amount to bet (required to start a new game)
          nullable: true
        agent_id:
          type: string
          description: Unique identifier for the agent/player
        game_id:
          type: string
          description: UUID of an existing game (required for hit/stand actions)
          nullable: true
        action:
          type: string
          enum: [hit, stand]
          description: Action to take in an existing game (required if game_id is provided)
          nullable: true
      required:
        - agent_id
    CalculatorToolResponse:
      type: object
      properties:
        result:
          type: integer
          description: The result of the calculation
      required:
        - result
    GreetToolResponse:
      type: object
      properties:
        result:
          type: string
          description: The greeting message
      required:
        - result
    SlotsToolResponse:
      type: object
      properties:
        explanation:
          type: string
          description: Description of the game rules and outcome
        game_state:
          type: object
          properties:
            reels:
              type: array
              items:
                type: string
              description: The symbols on the slot reels
          required:
            - reels
        payout:
          type: integer
          description: Amount won from the spin (0 if lost)
        bet:
          type: integer
          description: The amount bet on the spin
        agent_id:
          type: string
          description: The agent/player identifier
        new_balance:
          type: integer
          description: Updated balance after the spin
        game_complete:
          type: boolean
          description: Indicates if the game is complete (always true for slots)
      required:
        - explanation
        - game_state
        - payout
        - bet
        - agent_id
        - new_balance
        - game_complete
    BlackjackToolResponse:
      type: object
      properties:
        explanation:
          type: string
          description: Description of the game rules and current action outcome
        game_id:
          type: string
          description: UUID of the blackjack game (returned when starting a new game)
          nullable: true
        game_state:
          type: object
          properties:
            player_hand:
              type: array
              items:
                type: integer
              description: Cards in the player's hand
            player_total:
              type: integer
              description: Total value of the player's hand
            dealer_hand:
              type: array
              items:
                type: integer
              description: Cards in the dealer's hand (partial view until game ends)
            dealer_total:
              type: integer
              description: Total value of the dealer's hand (partial until game ends)
          required:
            - player_hand
            - player_total
            - dealer_hand
            - dealer_total
        payout:
          type: integer
          description: Amount won (0 if ongoing or lost, set when game completes)
          nullable: true
        bet:
          type: integer
          description: The amount bet on the game
        agent_id:
          type: string
          description: The agent/player identifier
        new_balance:
          type: integer
          description: Updated balance (updated only when game completes)
        game_complete:
          type: boolean
          description: Indicates if the game is complete (true on bust or stand)
      required:
        - explanation
        - game_state
        - bet
        - agent_id
        - new_balance
        - game_complete
    MemoryStoreRequest:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
      required:
        - key
        - value
    MemoryStoreResponse:
      type: object
      properties:
        status:
          type: string
          enum: [stored, deleted]
      required:
        - status
    MemoryGetResponse:
      type: object
      properties:
        value:
          type: string
          nullable: true
      required:
        - value
    MemoryListResponse:
      type: object
      properties:
        keys:
          type: array
          items:
            type: string
      required:
        - keys
    ResourcesResponse:
      type: object
      properties:
        resources:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              content:
                type: object
                additionalProperties: true
            required:
              - id
              - content
      required:
        - resources
    ResourceResponse:
      type: object
      properties:
        id:
          type: string
        content:
          type: object
          additionalProperties: true
      required:
        - id
        - content
    ResourceUpdateRequest:
      type: object
      properties:
        content:
          type: string
          description: The content to set for the resource.
      required:
        - content
    ResourceUpdateResponse:
      type: object
      properties:
        status:
          type: string
          enum: [updated]
        resource:
          $ref: '#/components/schemas/ResourceResponse'
      required:
        - status
        - resource
    PayRequest:
      type: object
      properties:
        amount:
          type: number
          format: float
      required:
        - amount
    PayResponse:
      type: object
      properties:
        transaction_id:
          type: string
        status:
          type: string
          enum: [success]
      required:
        - transaction_id
        - status
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
      required:
        - error