001/*
002 *  Copyright 2025 Anyware Services
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016
017package org.ametys.plugins.ai.provider;
018
019import java.nio.file.Path;
020import java.util.List;
021
022import org.ametys.runtime.i18n.I18nizableText;
023
024import dev.langchain4j.memory.ChatMemory;
025
026/**
027 * AI provider interface
028 */
029public interface AIProvider
030{
031    /**
032     * Get the id of the provider
033     * @return the id
034     */
035    public String getId();
036    
037    /**
038     * Get the label of the provider
039     * @return the label
040     */
041    public I18nizableText getLabel();
042    
043    /**
044     * Summarized a text
045     * @param text the text to summarize
046     * @param maxLength the max number of characters that will be generated
047     * @return the summarized text
048     * @throws Exception if an error occurred during summarize process
049     */
050    public String textToSummary(String text, int maxLength) throws Exception;
051    
052    /**
053     * Check if the image generation is supported
054     * @return boolean true if the generation is enabled, false otherwise
055     */
056    public boolean isImageGenerationSupported();
057    
058    /**
059     * Get the URL of the generated image
060     * @param text the prompt text
061     * @return the generated image
062     * @throws Exception if an error occurred during the image generation
063     */
064    public Path textToImage(String text) throws Exception;
065
066    /**
067     * Check if the embedding is supported
068     * @return boolean true if the embedding is supported, false otherwise
069     */
070    public boolean isEmbeddingSupported();
071
072    /**
073     * Get the response from the chatbot if embedding is supported
074     * @param memory the chat history message
075     * @return the response from the chatbot
076     */
077    public String askChatbot(ChatMemory memory);
078
079    /**
080     * Get the embedding of a text
081     * @param text The text to embed
082     * @return The embedding vector as a list of floats or null if an error occurred or if embedding is not supported
083     */
084    public List<Float> computeEmbedding(String text);
085    
086    /**
087     * Get the dimension of the embedding vector
088     * @return The embedding dimension or -1 if not supported
089     */
090    public int getEmbeddingDimension();
091
092    /**
093     * Get a string key identifying the embedding generator. Comparing this key between two calls allows to know if an existing embedding is still valid.
094     * @return The embedding generator key or null if embedding is not supported
095     */
096    public String getEmbeddingKey();
097}