diff --git a/src/llm.jl b/src/llm.jl index 1fe86f7..3c00475 100644 --- a/src/llm.jl +++ b/src/llm.jl @@ -6,7 +6,9 @@ abstract type OpenAILLM <: AbstractLLM end """ GroqLLM + Structure encapsulating the parameters for accessing the Groq LLM API. + - `api_key`: an API key for accessing the Groq API (https://groq.com), read from the environmental variable GROQ_API_KEY. - `model_id`: a string identifier for the model to query. See https://console.groq.com/docs/models for the list of available models. - `url`: URL for chat completions. Defaults to "https://api.groq.com/openai/v1/chat/completions". @@ -27,10 +29,12 @@ end """ Google LLM + Structure encapsulating the parameters for accessing the Google LLM API. -- `api_key`: an API key for accessing the Google Gemini API (https://ai.google.dev/gemini-api/docs/), read from the environmental variable GOOGLE_API_KEY. -- `model_id`: a string identifier for the model to query. See https://ai.google.dev/gemini-api/docs/models/gemini for the list of available models. -- `url`: URL for chat completions. Defaults to ""https://generativelanguage.googleapis.com/v1beta/models/{{model_id}}". + +- `api_key`: an API key for accessing the Google Gemini API (`https://ai.google.dev/gemini-api/docs/`), read from the environmental variable `GOOGLE_API_KEY`. +- `model_id`: a string identifier for the model to query. See `https://ai.google.dev/gemini-api/docs/models/gemini` for the list of available models. +- `url`: URL for chat completions. Defaults to `https://generativelanguage.googleapis.com/v1beta/models/{{model_id}}`. """ struct GoogleLLM <: AbstractLLM api_key::String @@ -48,12 +52,14 @@ end """ LlamaCppLLM + Structure encapsulating the parameters for accessing the llama.cpp server API. + - `api_key`: an optional API key for accessing the server - `model_id`: a string identifier for the model to query. Unused, kept for API compatibility. - `url`: the URL of the llama.cpp server OpenAI API endpoint (e.g., http://localhost:8080) -NOTE: we do not apply the appropriate chat templates to the prompt. -This must be handled either in an external code path or by the server. + +NOTE: we do not apply the appropriate chat templates to the prompt. This must be handled either in an external code path or by the server. """ struct LlamaCppLLM <: OpenAILLM api_key::String @@ -68,6 +74,7 @@ end """ get_completion(llm::OpenAILLM, prompt::Prompt) + Returns a completion for the given prompt using an OpenAI API compatible LLM """ function get_completion(llm::OpenAILLM, prompt::Prompt) @@ -89,6 +96,7 @@ end """ get_completion(llm::GoogleLLM, prompt::Prompt) + Returns a completion for the given prompt using the Google Gemini LLM API. """ function get_completion(llm::GoogleLLM, prompt::Prompt) @@ -110,6 +118,7 @@ end """ stream_completion(llm::OpenAILLM, prompt::Prompt) + Returns a completion for the given prompt using an OpenAI API compatible model. The completion is streamed to the terminal as it is generated. """ @@ -166,6 +175,7 @@ end """ stream_completion(llm::GoogleLLM, prompt::Prompt) + Returns a completion for the given prompt using the Google Gemini LLM API. The completion is streamed to the terminal as it is generated. """ @@ -206,6 +216,7 @@ end """ stream_completion(llm::AbstractLLM, prompt::AbstractPrompt) + Returns a completion for a `prompt` using the `llm` model API. The completion is streamed to the terminal as it is generated. """ @@ -216,8 +227,9 @@ end """ get_completion(llm::AbstractLLM, prompt::AbstractPrompt) + Returns a completion for a `prompt` using the `llm` model API. """ -function get_completion(llm::AbstractLLM, prompt::AbstractPrompt) - error("Not implemented for this LLM and/or prompt type.") +function get_completion(::AbstractLLM, ::AbstractPrompt) + return error("Not implemented for this LLM and/or prompt type.") end diff --git a/src/parsing.jl b/src/parsing.jl index 24ddd68..dd998fe 100644 --- a/src/parsing.jl +++ b/src/parsing.jl @@ -1,5 +1,6 @@ """ parse_code(s::String) + Parse the code blocks in the input string `s` delimited by triple backticks and an optional language annotation. Returns a dictionary keyed by language. Code blocks from the same language are concatenated. """ @@ -32,7 +33,8 @@ end """ check_syntax_errors(s::String) -Parses the string `s` as Julia code. In the case of syntax errors, it returns the error + +Parses the string `s` as Julia code. In the case of syntax errors, it returns the error message of the parser as a string. Otherwise, it returns an empty string. """ function check_syntax_errors(s::String) @@ -47,6 +49,7 @@ end """ edit_in_vim(s::String) + Edits the input string `s` in a temporary file using the Vim editor. Returns the modified string after the editor is closed. """ diff --git a/src/prompt.jl b/src/prompt.jl index 1357381..7feabc3 100644 --- a/src/prompt.jl +++ b/src/prompt.jl @@ -2,6 +2,7 @@ abstract type AbstractPrompt end """ Prompt + Simple data structure encapsulating a system prompt and a user prompt for LLM generation. ## Fields diff --git a/src/template.jl b/src/template.jl index 595f9c6..c7531e6 100644 --- a/src/template.jl +++ b/src/template.jl @@ -19,6 +19,8 @@ struct MetadataMessage <: AbstractMessage end """ + SystemMessage + Represents the prompt template of a system message. The template can optionally contain string placeholders enclosed in double curly braces, e.g., `{{variable}}`. Placeholders must be replaced with actual values when generating prompts. @@ -33,6 +35,8 @@ struct SystemMessage <: AbstractMessage end """ + UserMessage + Represents the prompt template of a user message. The template can optionally contain string placeholders enclosed in double curly braces, e.g., `{{variable}}`. Placeholders must be replaced with actual values when generating prompts. @@ -47,6 +51,8 @@ struct UserMessage <: AbstractMessage end """ + PromptTemplate + Represents a complete prompt template, comprising metadata, system, and user messages. # Fields @@ -63,7 +69,7 @@ end """ read_template(data_path::String) -Reads a prompt template from a JSON file specified by `data_path`. +Reads a prompt template from a JSON file specified by `data_path`. The function parses the JSON data and constructs a `PromptTemplate` object containing metadata, system, and user messages. TODO: validate the JSON data against a schema to ensure it is valid before parsing. @@ -165,4 +171,4 @@ function format_template(template::PromptTemplate; kwargs...) end return Prompt(system, user) -end \ No newline at end of file +end diff --git a/src/translate.jl b/src/translate.jl index b7feaef..12d7df9 100644 --- a/src/translate.jl +++ b/src/translate.jl @@ -2,7 +2,8 @@ const MAX_RETRIES::Int = 3 """ extract_structure(model <: AbstractLLM, description <: AbstractString) -Extracts the parameters, decision variables and constraints of an optimization problem + +Extracts the parameters, decision variables and constraints of an optimization problem given a natural-language `description`. Returns a Markdown-formatted text containing the above information. """ @@ -51,8 +52,9 @@ end """ jumpify_model(model::AbstractLLM, description::AbstractString, examples::AbstractString) + Translates the natural language `description` of an optimization problem into a JuMP constraints -programming model to be solved with CBL by querying the Large Language Model `model`. +programming model to be solved with CBL by querying the Large Language Model `model`. The `examples` are snippets from `ConstraintModels.jl` used as in-context examples to the LLM. To work optimally, the model expects the `description` to be a structured Markdown-formatted description as the ones generated by `extract_structure`. @@ -126,6 +128,7 @@ end """ fix_syntax_errors(model::AbstractLLM, code::AbstractString, error::AbstractString) + Fixes syntax errors in the `code` by querying the Large Language Model `model`, based on an `error` produced by the Julia parser. Returns Markdown-formatted text containing the corrected code in a Julia code block. @@ -141,9 +144,10 @@ end """ translate(model::AbstractLLM, description::AbstractString; interactive::Bool = false) -Translate the natural-language `description` of an optimization problem into + +Translate the natural-language `description` of an optimization problem into a Constraint Programming model by querying the Large Language Model `model`. -If `interactive`, the user will be prompted via the command line to inspect the +If `interactive`, the user will be prompted via the command line to inspect the intermediate outputs of the LLM, and possibly modify them. """ function translate( diff --git a/src/utils.jl b/src/utils.jl index bc9a4e2..f60e3df 100644 --- a/src/utils.jl +++ b/src/utils.jl @@ -1,5 +1,6 @@ """ get_package_path() + Returns the absolute path of the root directory of `ConstraintsTranslator.jl`. """ function get_package_path() @@ -8,4 +9,4 @@ function get_package_path() error("The path of the package could not be found. This should never happen!") end return package_path -end \ No newline at end of file +end