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;
008
009import com.oracle.database.selectai.model.SelectAIException;
010
011/**
012 * Represents a Select AI chat session that reuses conversation context across
013 * multiple profile generation calls.
014 * <p>
015 * A session is created from {@link Profile#chatSession(Conversation)} or
016 * {@link Profile#chatSession(Conversation, boolean)}. Each session call sends
017 * the same conversation ID to {@code DBMS_CLOUD_AI.GENERATE} so later prompts
018 * can use prior conversation context.
019 * <p>
020 * Closing a session does not close the {@link SelectAI} client, the
021 * {@link Profile}, or the underlying JDBC connection. If the session was
022 * created with {@code deleteOnClose=true}, closing the session drops the
023 * associated conversation.
024 */
025public interface Session extends AutoCloseable {
026
027    /**
028     * Sends the prompt as a chat-style request using the session conversation.
029     * <p>
030     * For a complete runnable sample source, see
031     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/profile/ChatSessionProfileSample.html">
032     * ChatSessionProfileSample source</a>.
033     *
034     * @param prompt natural language prompt
035     * @return chat response
036     * @throws IllegalArgumentException when {@code prompt} is null or blank
037     * @throws IllegalStateException when this Session is already closed
038     * @throws SelectAIException when generation fails
039     */
040    String chat(String prompt) throws SelectAIException;
041
042    /**
043     * Generates and runs SQL, then asks the model to narrate the result using
044     * the session conversation.
045     * <p>
046     * For a complete runnable sample source, see
047     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/profile/SessionNarrateSample.html">
048     * SessionNarrateSample source</a>.
049     *
050     * @param prompt natural language prompt
051     * @return narrative response
052     * @throws IllegalArgumentException when {@code prompt} is null or blank
053     * @throws IllegalStateException when this Session is already closed
054     * @throws SelectAIException when generation fails
055     */
056    String narrate(String prompt) throws SelectAIException;
057
058    /**
059     * Generates SQL from the prompt and runs it using the session conversation.
060     * <p>
061     * For a complete runnable sample source, see
062     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/profile/SessionRunSqlSample.html">
063     * SessionRunSqlSample source</a>.
064     *
065     * @param prompt natural language prompt
066     * @return generated SQL execution result/content
067     * @throws IllegalArgumentException when {@code prompt} is null or blank
068     * @throws IllegalStateException when this Session is already closed
069     * @throws SelectAIException when generation fails
070     */
071    String runsql(String prompt) throws SelectAIException;
072
073    /**
074     * Generates SQL and returns a natural-language explanation using the
075     * session conversation.
076     * <p>
077     * For a complete runnable sample source, see
078     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/profile/SessionExplainSqlSample.html">
079     * SessionExplainSqlSample source</a>.
080     *
081     * @param prompt natural language prompt
082     * @return explanation of generated SQL
083     * @throws IllegalArgumentException when {@code prompt} is null or blank
084     * @throws IllegalStateException when this Session is already closed
085     * @throws SelectAIException when generation fails
086     */
087    String explainsql(String prompt) throws SelectAIException;
088
089    /**
090     * Generates SQL from the prompt without running it using the session
091     * conversation.
092     * <p>
093     * For a complete runnable sample source, see
094     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/profile/SessionShowSqlSample.html">
095     * SessionShowSqlSample source</a>.
096     *
097     * @param prompt natural language prompt
098     * @return generated SQL text
099     * @throws IllegalArgumentException when {@code prompt} is null or blank
100     * @throws IllegalStateException when this Session is already closed
101     * @throws SelectAIException when generation fails
102     */
103    String showsql(String prompt) throws SelectAIException;
104
105    /**
106     * Returns the augmented prompt that Select AI would send to the provider
107     * using the session conversation.
108     * <p>
109     * For a complete runnable sample source, see
110     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/profile/SessionShowPromptSample.html">
111     * SessionShowPromptSample source</a>.
112     *
113     * @param prompt natural language prompt
114     * @return rewritten/provider-facing prompt
115     * @throws IllegalArgumentException when {@code prompt} is null or blank
116     * @throws IllegalStateException when this Session is already closed
117     * @throws SelectAIException when generation fails
118     */
119    String showprompt(String prompt) throws SelectAIException;
120
121    /**
122     * Closes this session.
123     * <p>
124     * This does not close the SDK client or JDBC connection. When the session
125     * was created with {@code deleteOnClose=true}, this method drops the
126     * associated conversation. Calling this method more than once has no
127     * additional effect.
128     * For a complete runnable sample source, see
129     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/profile/SessionCloseSample.html">
130     * SessionCloseSample source</a>.
131     *
132     * @throws SelectAIException when delete-on-close conversation cleanup fails
133     */
134    @Override
135    void close() throws SelectAIException;
136}