001/*
002 * Copyright (c) 2026, Oracle and/or its affiliates.
003 *
004 * Licensed under the Universal Permissive License Version 1.0 as shown at
005 * https://oss.oracle.com/licenses/upl/
006 */
007package com.oracle.database.selectai.model;
008
009import com.fasterxml.jackson.annotation.JsonInclude;
010import com.fasterxml.jackson.annotation.JsonIgnore;
011import com.fasterxml.jackson.databind.ObjectMapper;
012import com.fasterxml.jackson.databind.PropertyNamingStrategies;
013
014/**
015 * Request parameters for the {@code params} CLOB argument of
016 * {@code DBMS_CLOUD_AI.GENERATE}.
017 * <p>This model currently supports conversation-bound generation through
018 * {@code conversation_id}. Instances are used by {@link com.oracle.database.selectai.Profile}
019 * generate overloads and by {@link com.oracle.database.selectai.Session} to keep a
020 * conversation identifier across related generate calls.</p>
021 *
022 * @see <a href="https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-ai-package.html">
023 *      DBMS_CLOUD_AI.GENERATE reference</a>
024 */
025public final class GenerateParams {
026
027    /** Conversation identifier passed to {@code DBMS_CLOUD_AI.GENERATE} params payload. */
028    private final String conversationId;
029
030    private GenerateParams(GenerateParams.Builder builder) {
031        this.conversationId = builder.conversationId;
032    }
033
034    /**
035     * Returns the conversation identifier.
036     *
037     * @return conversation ID
038     */
039    public String getConversationId() {
040        return conversationId;
041    }
042
043    /**
044     * Returns whether this instance contains no configured generate parameters.
045     *
046     * @return {@code true} when no generate parameters are configured
047     */
048    @JsonIgnore
049    public boolean isEmpty() {
050        return conversationId == null;
051    }
052
053    /**
054     * Creates a builder for generate parameters.
055     *
056     * @return new builder for constructing GenerateParams
057     */
058    public static GenerateParams.Builder builder() {
059        return new GenerateParams.Builder();
060    }
061
062    /**
063     * Builder for {@link GenerateParams}.
064     */
065    public static final class Builder {
066        /** Creates an empty builder. */
067        public Builder() {
068        }
069
070        /** Conversation identifier passed to {@code DBMS_CLOUD_AI.GENERATE} params payload. */
071        private String conversationId;
072
073        /**
074         * Sets the conversation identifier.
075         *
076         * @param conversationId conversation identifier
077         * @return this builder instance
078         */
079        public GenerateParams.Builder conversationId(String conversationId) {
080            if (conversationId == null || conversationId.isBlank()) {
081                throw new IllegalArgumentException("conversationId must be provided");
082            }
083            this.conversationId = conversationId;
084            return this;
085        }
086
087        /**
088         * Builds immutable generate parameters.
089         *
090         * @return immutable GenerateParams built from current builder state
091         */
092        public GenerateParams build() {
093            if (conversationId == null) {
094                throw new IllegalArgumentException("at least one generate parameter must be set");
095            }
096            return new GenerateParams(this);
097        }
098    }
099
100
101    /**
102     * Serializes the parameter payload using DBMS_CLOUD_AI snake_case names.
103     *
104     * @return JSON representation of this GenerateParams instance
105     */
106    public String toJson() {
107        try {
108            ObjectMapper mapper = new ObjectMapper();
109            mapper.setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);
110            mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
111            return mapper.writeValueAsString(this);
112        } catch (Exception e) {
113            throw new IllegalStateException("Failed to serialize GenerateParams", e);
114        }
115    }
116}