Add documentation for context, chapter, and interactive modules with …

…usage examples and error handling

docs/chapter.md

@@ -0,0 +1,75 @@
+# `chapter.py` Documentation
+
+This module provides functionality for generating a single chapter of a story using a Text User Interface (TUI). It leverages the `rich` library for a visually appealing terminal interface and integrates with the story generation utilities provided in the `utils` module.
+
+## Functions
+
+### `generate_chapter_tui()`
+
+This function provides a TUI for generating a single chapter of a story. It prompts the user for various inputs, including the story query, style, character, situation, and output file. It also offers advanced configuration options for more control over the generation process.
+
+#### Usage
+
+```python
+generate_chapter_tui()
+```
+
+#### Steps
+
+1. **Clear Console**: Clears the console for a fresh start.
+2. **Print Panel**: Displays a panel with the title "Generate a Single Chapter".
+3. **Load Configuration**: Loads the configuration settings from `config.yaml`.
+4. **Load API Key**: Loads the API key from the configuration or secrets file.
+5. **Prompt for Inputs**: Prompts the user for the story query, style, character, situation, and output file.
+6. **Advanced Options**: Optionally prompts the user for advanced configuration settings, including the number of relevant chunks (`top_n`), temperature, max tokens, max iterations, min quality score, and whether to force regeneration.
+7. **Set Log Level**: Sets the log level for the story generation process.
+8. **Live Progress**: Uses `rich.live.Live` to display a live progress bar during the story generation process.
+9. **Generate Story**: Calls the `generate_story` function with the provided inputs and configuration settings.
+10. **Print Completion Panel**: Displays a panel indicating the completion of the story generation and the location of the output file.
+11. **Error Handling**: Catches and prints any exceptions that occur during the story generation process.
+
+#### Example
+
+```python
+from chapter import generate_chapter_tui
+
+generate_chapter_tui()
+```
+
+## Dependencies
+
+- `logging`: For logging messages and errors.
+- `typing`: For type hints.
+- `pathlib`: For handling file paths.
+- `rich.console.Console`: For creating a rich console interface.
+- `rich.prompt.Prompt`: For prompting user inputs.
+- `rich.prompt.Confirm`: For confirming user inputs.
+- `rich.table.Table`: For displaying tables in the console.
+- `rich.progress.track`: For tracking progress.
+- `rich.panel.Panel`: For displaying panels in the console.
+- `rich.live.Live`: For live updates in the console.
+- `utils`: For utility functions such as `generate_story`, `load_config`, and `load_api_key`.
+
+## Example Usage
+
+To use the `generate_chapter_tui` function, simply import it and call it in your script:
+
+```python
+from chapter import generate_chapter_tui
+
+generate_chapter_tui()
+```
+
+This will launch the TUI and guide you through the process of generating a single chapter of a story.
+
+## Configuration
+
+The function relies on a configuration file (`config.yaml`) for various settings, including the default story style, temperature, max tokens, and more. Ensure that this file is properly set up before running the function.
+
+## Error Handling
+
+The function includes error handling to catch and display any exceptions that occur during the story generation process. Errors are logged using the `logging` module and displayed in the console using `rich`.
+
+## Conclusion
+
+The `chapter.py` module provides a user-friendly interface for generating a single chapter of a story. By leveraging the `rich` library, it offers a visually appealing and interactive experience. The function is highly configurable and integrates seamlessly with the story generation utilities provided in the `utils` module.

docs/context.md

@@ -0,0 +1,114 @@
+# `context.py` Documentation
+
+This module provides functionality for preparing context from relevant chunks of text. It is used to gather and format context information that will be used in the story generation process.
+
+## Functions
+
+### `prepare_context(embeddings_dict: Dict[str, Any], relevant_chunks: List[Tuple[str, int, float]]) -> str`
+
+Prepares context from relevant chunks of text based on their similarity scores.
+
+#### Parameters
+
+- `embeddings_dict` (Dict[str, Any]): A dictionary where keys are file paths and values are dictionaries containing 'content' and 'chunk_embeddings' (and optionally 'chunk_content').
+- `relevant_chunks` (List[Tuple[str, int, float]]): A list of tuples, each containing (file_path, chunk_index, similarity_score), as returned by semantic search.
+
+#### Returns
+
+- `str`: A string containing the formatted context.
+
+#### Usage
+
+```python
+context = prepare_context(embeddings_dict, relevant_chunks)
+```
+
+#### Steps
+
+1. **Initialize Context Parts**: Initializes an empty list to store parts of the context.
+2. **Iterate Over Relevant Chunks**: Iterates over the relevant chunks to extract and format the context.
+3. **Extract Content**: Extracts the content and chunks from the embeddings dictionary.
+4. **Validate Chunk Index**: Validates the chunk index and extracts the corresponding chunk.
+5. **Format Context**: Formats the context with source information and relevance score.
+6. **Join Context Parts**: Joins the context parts into a single string.
+
+#### Example
+
+```python
+from context import prepare_context
+
+embeddings_dict = {
+    "file1.txt": {
+        "content": "This is the content of file1.",
+        "chunk_embeddings": [
+            "This is the first chunk.",
+            "This is the second chunk."
+        ]
+    },
+    "file2.txt": {
+        "content": "This is the content of file2.",
+        "chunk_embeddings": [
+            "This is another chunk.",
+            "This is yet another chunk."
+        ]
+    }
+}
+
+relevant_chunks = [
+    ("file1.txt", 0, 0.95),
+    ("file2.txt", 1, 0.90)
+]
+
+context = prepare_context(embeddings_dict, relevant_chunks)
+print(context)
+```
+
+## Dependencies
+
+- `logging`: For logging messages and errors.
+- `typing`: For type hints.
+- `pathlib`: For handling file paths.
+- `text_processing`: For text processing utilities.
+
+## Example Usage
+
+To use the `prepare_context` function, simply import it and call it in your script:
+
+```python
+from context import prepare_context
+
+embeddings_dict = {
+    "file1.txt": {
+        "content": "This is the content of file1.",
+        "chunk_embeddings": [
+            "This is the first chunk.",
+            "This is the second chunk."
+        ]
+    },
+    "file2.txt": {
+        "content": "This is the content of file2.",
+        "chunk_embeddings": [
+            "This is another chunk.",
+            "This is yet another chunk."
+        ]
+    }
+}
+
+relevant_chunks = [
+    ("file1.txt", 0, 0.95),
+    ("file2.txt", 1, 0.90)
+]
+
+context = prepare_context(embeddings_dict, relevant_chunks)
+print(context)
+```
+
+This will prepare and print the context based on the relevant chunks provided.
+
+## Error Handling
+
+The function includes error handling to catch and log any exceptions that occur during the context preparation process. Errors are logged using the `logging` module.
+
+## Conclusion
+
+The `context.py` module provides a robust and efficient approach to preparing context from relevant chunks of text. By leveraging the embeddings dictionary and similarity scores, it ensures that the generated context is relevant and useful for the story generation process.

docs/interactive.md

@@ -0,0 +1,97 @@
+# `interactive.py` Documentation
+
+This module provides functionality for interactive story generation using a Text User Interface (TUI). It leverages the `rich` library for a visually appealing terminal interface and integrates with the story generation utilities provided in the `utils` module.
+
+## Functions
+
+### `interactive_loop(story_gen: StoryGenerator, plot_gen: PlotGenerator, embeddings_dict: dict, session_history: list, current_settings: dict)`
+
+This function provides the main loop for interactive story generation. It allows the user to generate a plot outline, create chapters based on user queries or plot points, and refine the generated story iteratively.
+
+#### Parameters
+
+- `story_gen` (StoryGenerator): An instance of the `StoryGenerator` class.
+- `plot_gen` (PlotGenerator): An instance of the `PlotGenerator` class.
+- `embeddings_dict` (dict): A dictionary containing embeddings for semantic search.
+- `session_history` (list): A list to store the history of the interactive session.
+- `current_settings` (dict): A dictionary to store the current settings for story generation.
+
+#### Usage
+
+```python
+interactive_loop(story_gen, plot_gen, embeddings_dict, session_history, current_settings)
+```
+
+#### Steps
+
+1. **Generate Plot Outline**: Optionally generates a plot outline based on a user-provided prompt.
+2. **Display World Details**: Displays the world details in a panel.
+3. **Main Loop**: Enters the main loop for interactive story generation.
+   - **User Query**: Prompts the user for a story query or command (e.g., 'exit', 'new chapter').
+   - **Use Previous Settings**: Optionally uses previous settings or prompts the user for new settings.
+   - **Generate Story**: Generates a story chapter based on the user query and settings.
+   - **Refine Story**: Allows the user to refine the generated story iteratively.
+   - **Save/Load/Export**: Provides options to save the session, load a session, or export the generated story.
+
+#### Example
+
+```python
+from interactive import interactive_loop
+from utils import StoryGenerator, load_config, load_api_key
+from plot import PlotGenerator
+
+config = load_config()
+api_key = load_api_key(config)
+story_gen = StoryGenerator(config)
+plot_gen = PlotGenerator(story_gen.model)
+embeddings_dict = {}  # Load your embeddings dictionary here
+session_history = []
+current_settings = {}
+
+interactive_loop(story_gen, plot_gen, embeddings_dict, session_history, current_settings)
+```
+
+## Dependencies
+
+- `logging`: For logging messages and errors.
+- `json`: For handling JSON data.
+- `pathlib`: For handling file paths.
+- `rich.console.Console`: For creating a rich console interface.
+- `rich.prompt.Prompt`: For prompting user inputs.
+- `rich.panel.Panel`: For displaying panels in the console.
+- `utils`: For utility functions such as `load_config`, `load_api_key`, and `StoryGenerator`.
+- `plot`: For the `PlotGenerator` class.
+
+## Example Usage
+
+To use the `interactive_loop` function, simply import it and call it in your script:
+
+```python
+from interactive import interactive_loop
+from utils import StoryGenerator, load_config, load_api_key
+from plot import PlotGenerator
+
+config = load_config()
+api_key = load_api_key(config)
+story_gen = StoryGenerator(config)
+plot_gen = PlotGenerator(story_gen.model)
+embeddings_dict = {}  # Load your embeddings dictionary here
+session_history = []
+current_settings = {}
+
+interactive_loop(story_gen, plot_gen, embeddings_dict, session_history, current_settings)
+```
+
+This will launch the interactive TUI and guide you through the process of generating and refining a story.
+
+## Configuration
+
+The function relies on a configuration file (`config.yaml`) for various settings, including the default story style, temperature, max tokens, and more. Ensure that this file is properly set up before running the function.
+
+## Error Handling
+
+The function includes error handling to catch and display any exceptions that occur during the story generation process. Errors are logged using the `logging` module and displayed in the console using `rich`.
+
+## Conclusion
+
+The `interactive.py` module provides a user-friendly interface for interactive story generation. By leveraging the `rich` library, it offers a visually appealing and interactive experience. The function is highly configurable and integrates seamlessly with the story generation utilities provided in the `utils` module.