Update docs

Author: danoan

docs/api-reference.rst

@@ -1,10 +1,30 @@
 API Reference
 ======
+
+Module: common
+------
+
+.. autosummary::
+
+    danoan.llm_assistant.common.config
+    danoan.llm_assistant.common.model
+    danoan.llm_assistant.common.exception
+
+
+Module: prompt
+------
+
+.. autosummary::
+
+    danoan.llm_assistant.prompt.core.api
+    danoan.llm_assistant.prompt.core.model
+    danoan.llm_assistant.prompt.core.utils
+
+
+Module: runner
+------
+
 .. autosummary::
-   :toctree generated
 
-    <danoan.llm_assistant.core.api
-    danoan.llm_assistant.core.cli_drawer
-    danoan.llm_assistant.core.exception
-    danoan.llm_assistant.core.model
-    danoan.llm_assistant.core.task_runner
+    danoan.llm_assistant.runner.core.api
+    danoan.llm_assistant.runner.core.exception

docs/getting-started.md

@@ -1,11 +1,177 @@
 # Getting started with LLM Assistant
 
-Collection of simple LLM applications
+Collection of tools to work with LLMs.
 
 ## Features
 
+- CLI for interactive prompt execution.
+- Prompt versioning tool.
+- Prompt definition format and general runner.
 
-## Examples
+
+## How to use
+
+### Configuring a LLM provider
+
+The first step is to create a `llm-assistannt-config.toml` file
+to hold runner and prompt settings.
+
+```toml
+[runner]
+openai_key = "<OPENAI_KEY>"
+model = "gpt-3.5-turbo"
+use_cache = true
+cache_path = "/home/user/.config/llm-assistant/cache.db"
+
+[prompt]
+git_user = "danoan-prompts"
+prompt_collection_folder = "/home/user/.config/llm-assistant/cache.db"
+
+[prompt.versioning]
+alternative-expression = "v2.0.0"
+word-definition = "v1.0.0"
+```
+
+**Configuration file search**: The application backtracks the current working directory searching for the
+`llm-assistant-config.toml` file starting from CWD. If not such file is found, it searches in the location
+specified by the environment variable `LLM_ASSISTANT_CONFIGURATION_FOLDER`.
+
+You can check which configuration file is being used by running
+
+```bash
+llm-assistant setup
+```
+
+
+### Running a prompt
+
+Consider the `alternative-expression` prompt configuration file:
+
+```toml
+name="Alternative Expressions"
+system_prompt='''
+You are fluent speaker of the {language} language and your task is to list at most five expressions that encodes the meaning of a sentence or a word enclosed by double angle brackets.
+
+Your response must be given as a json list and the items must be written in {language}.
+
+Examples
+--------
+
+Language: English.
+Sentence: <<It is an unusual day today.>>
+Response: [
+    "It is an odd day today",
+    "Today is quite unusual",
+    "It is an atypical day",
+    "Today feels out of the ordinary",
+    "Today stands out differently"
+]
+--
+
+Language: french
+Sentence: <<gentil>>
+Response: [
+    "aimable",
+    "doux"
+]
+--
+
+'''
+user_prompt='''
+Language: {language}
+Sentence: <<{message}>>
+Response:
+'''
+```
+
+It is possible to run the prompt in three different ways
+
+```bash
+echo "{}" | llm-assistant run alternative-expression --p language portuguese --p message "ganhar a vida"
+echo '{"message":"ganhar a vida"}' | llm-assistant run alternative-expression --p language portuguese
+echo '{"message":"ganhar a vida", "language":"portuguese"}' | llm-assistant run alternative-expression
+```
+
+### Starting an interactive session
+
+To start an interactive session, type:
+
+```bash
+llm-assistant session
+```
+
+You are invited to select one of the prompts located at `prompt.prompt_collection_folder` and then to load or
+create a new instance for the prompt.
+
+**Prompt Instance**: A prompt instance is a subset of pre-defined prompt variables. For example, in the alternative-expression
+prompt, we could have a french instance (language=french) and a portuguese instance (language=portuguese).
+
+```bash
+╭────────────────────────────────────────────────────────────────────────────────────────╮
+│ Select prompt                                                                          │
+╰────────────────────────────────────────────────────────────────────────────────────────╯
+1. Alternative Expressions 2. Word Definition
+
+Prompt index: 2
+╭────────────────────────────────────────────────────────────────────────────────────────╮
+│ Choose an option                                                                       │
+╰────────────────────────────────────────────────────────────────────────────────────────╯
+1. New instance 2. Load instance
+
+Option index: 1
+Enter the instance name: portuguese
+Enter variable assignment: language=portuguese
+╭─────────────────────────────────────── New Chat ───────────────────────────────────────╮
+│ Prompt: Word Definition                                                                │
+│ Instance:portuguese                                                                    │
+╰────────────────────────────────────────────────────────────────────────────────────────╯
+Enter messaó
+Enter message: $$
+╭───────────────────────────── Word Definition::portuguese ─────────────────────────────╮
+│ borogodó                                                                              │
+╰───────────────────────────────────────────────────────────────────────────────────────╯
+╭───────────────────────────── Word Definition::portuguese ─────────────────────────────╮
+│ [                                                                                     │
+│   "Encanto, atração irresistível e misteriosa; charme",                               │
+│   "Qualidade ou característica que atrai e seduz de maneira peculiar ou especial.",   │
+│   "Dom, habilidade natural para seduzir ou encantar as pessoas.",                     │
+│   "Magia, feitiço; algo que exerce influência sobre os outros de forma inexplicável." │
+│ ]                                                                                     │
+╰───────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+### Syncing prompts
+
+The `sync` feature allows to fetch the most recent updates from the remote prompt repository
+and to update the local view.
+
+```bash
+prompt-manager sync
+```
+
+The synchronization is done according with the `prompt.versioning` settings.
+
+```toml
+[prompt]
+git_user = "danoan-prompts"
+prompt_collection_folder = "/home/user/.config/llm-assistant/cache.db"
+
+[prompt.versioning]
+alternative-expression = "v2.0.0"
+word-definition = "v1.0.0"
+```
+
+For the settings above, the sync will seach for the repositories:
+
+- danoan-prompts/alternative-expression
+- danoan-prompts/word-definition
+
+on github and then fetch the specified version.
+
+### Push prompt version assistant
+
+The `prompt-manager versioning push` commands guides the user to the creation of a
+new prompt version.
 
 
 ## Contributing

docs/index.rst

@@ -17,7 +17,9 @@ How-to guides
 .. toctree::
    :maxdepth: 1
 
-   how-to/
+   how-to/setup-assistant
+   how-to/run-a-prompt
+   how-to/sync-and-push-prompts
 
 
 Reference guides

src/danoan/llm_assistant/common/config.py

@@ -1,14 +1,18 @@
-from danoan.llm_assistant.common import exception, model
-
+"""
+LLM-assistant configuration API.
+"""
 
-from functools import lru_cache
 import logging
 import os
-from pathlib import Path
 import sys
-import toml
+from functools import lru_cache
+from pathlib import Path
 from typing import Optional
 
+import toml
+
+from danoan.llm_assistant.common import exception, model
+
 logger = logging.getLogger(__file__)
 handler = logging.StreamHandler(sys.stderr)
 handler.setLevel(logging.DEBUG)
@@ -34,7 +38,6 @@ def _get_first_configuration_filepath_within_file_hierarchy(
     """
     visited = set()
     folders_to_visit = [base_dir]
-    print(base_dir)
     while len(folders_to_visit) > 0:
         cur_folder = folders_to_visit.pop()
         if cur_folder in visited:
@@ -79,6 +82,21 @@ def get_configuration_folder() -> Path:
     raise exception.EnvironmentVariableNotDefinedError()
 
 
+def get_environment_variable_value() -> Path:
+    f"""
+    Return the value stored by {LLM_ASSISTANT_ENV_VARIABLE}.
+
+    Raises:
+        EnvironmentVariableNotDefinedError: If the LLM_ASSISTANT_ENV_VARIABLE
+                                            is not defined and a configuration file
+                                            is not found in the file hierarchy
+    """
+    if LLM_ASSISTANT_ENV_VARIABLE in os.environ:
+        return Path(os.environ[LLM_ASSISTANT_ENV_VARIABLE]).expanduser()
+
+    raise exception.EnvironmentVariableNotDefinedError()
+
+
 def get_configuration_filepath() -> Path:
     """
     Return path to llm-assistant configuration file.
@@ -95,21 +113,29 @@ def get_configuration() -> model.LLMAssistantConfiguration:
         raise exception.ConfigurationFileDoesNotExistError()
 
     with open(config_filepath, "r") as f:
-        return model.LLMAssistantConfiguration(**toml.load(f))
+        return model.LLMAssistantConfiguration.from_dict(**toml.load(f))
 
 
 def get_prompt_configuration(prompt_name: str) -> model.PromptConfiguration:
     """
     Get prompt configuration object.
 
     It searches the prompt configuration file within the directory specified
-    by runner.local_folder setting.
+    by runner.prompt_collection_folder setting.
 
     Raises:
         FileNotFoundError: if prompt configuration file is not found.
     """
     config = get_configuration()
-    prompt_config_filepath = config.runner.local_folder / prompt_name / "config.toml"
+    if config.prompt:
+        prompt_config_filepath = (
+            config.prompt.prompt_collection_folder / prompt_name / "config.toml"
+        )
+    else:
+        raise FileNotFoundError(
+            2, "File not found", "prompt collection folder is not specified"
+        )
+
     if not prompt_config_filepath.exists():
         raise FileNotFoundError(2, "File not found", prompt_config_filepath)
     with open(prompt_config_filepath) as f:

src/danoan/llm_assistant/common/exception.py

@@ -1,3 +1,8 @@
+"""
+Shared exceptions between prompt and runner modules.
+"""
+
+
 class EnvironmentVariableNotDefinedError(Exception):
     pass