branch: externals/ellama
commit f8bbeef9f06ae5d1ea2dec842921591febf08f67
Author: Sergey Kostyaev <sskosty...@gmail.com>
Commit: Sergey Kostyaev <sskosty...@gmail.com>
Add context management documentation
Added detailed documentation and features for managing context in the Ellama
package. This includes transient menus for adding and managing context
elements,
a dedicated buffer for viewing and modifying the global context, and
considerations for effective context usage.
---
README.org | 60 +++++++++++++++++++
ellama.info | 191 +++++++++++++++++++++++++++++++++++++++++++++---------------
2 files changed, 204 insertions(+), 47 deletions(-)
diff --git a/README.org b/README.org
index eb46b331f6..c1d7ab2918 100644
--- a/README.org
+++ b/README.org
@@ -355,6 +355,66 @@ argument generated text string.
- ~ellama-reasoning-display-action-function~: Display action function for
reasoning.
- ~ellama-session-line-template~: Template for formatting the current session
line.
+* Context Management
+
+Ellama allows you to provide context to the Large Language Model (LLM) to
+improve the relevance and quality of responses. Context serves as background
+information, data, or instructions that guide the LLM's understanding of your
+prompt. Without context, the LLM relies solely on its pre-existing knowledge,
+which may not always be appropriate.
+
+A “global context” is maintained, which is a collection of text blocks
+accessible to the LLM when responding to prompts. This global context is
+prepened to your prompt before transmission to the LLM.
+
+** Transient Menus for Context Management
+
+Ellama provides a transient menu accessible through the main menu, offering a
+streamlined way to manage context elements. This menu is accessed via the
+“System” branch of the main transient menu, and then selecting "Context
+Commands."
+
+The Context Commands transient menu is structured as follows:
+
+Context Commands:
+
+- Add: Provides options for adding content to the global context.
+ - “b” "Add Buffer" ~ellama-context-add-buffer~
+ - “d” "Add Directory" ~ellama-context-add-directory~
+ - “f” "Add File" ~ellama-context-add-file~
+ - “s” "Add Selection" ~ellama-context-add-selection~
+ - “i” "Add Info Node" ~ellama-context-add-info-node~
+- Manage: Provides options for managing the global context.
+ - “m” "Manage context" ~ellama-context-manage~ - Opens the context
+ management buffer.
+ - “D” "Delete element" ~ellama-context-element-remove-by-name~ - Deletes an
+ element by name.
+ - “r” "Context reset" ~ellama-context-reset~ - Clears the entire global
+ context.
+- Quit: (“q” "Quit" ~transient-quit-one~) - Closes the context commands
+ transient menu.
+
+** Managing the Context
+
+~ellama-context-manage~ opens a dedicated buffer, the context management
buffer,
+where you can view, modify, and organize the global context. Within this
buffer:
+
++ ~n~: Move to the next context element.
++ ~p~: Move to the previous context element.
++ ~q~: Quit the context management buffer.
++ ~g~: Refresh the contents of the context management buffer.
++ ~a~: Add a new context element (similar to ~ellama-context-add-selection~).
++ ~RET~: Preview the content of the context element at the current point.
+
+** Considerations
+
+Large Language Models possess limited context window sizes, restricting the
+total amount of text they can process. Be mindful of the size of your context
to
+avoid truncation or performance degradation. Irrelevant context can dilute the
+information and hinder the LLM’s focus. Ensure context remains up-to-date for
+accurate information. Experimentation with different approaches to context
+management can optimize performance for specific use cases.
+
* Minor modes
The Ellama package for Emacs offers a suite of minor modes designed to enhance
diff --git a/ellama.info b/ellama.info
index be632e4302..229a9e8913 100644
--- a/ellama.info
+++ b/ellama.info
@@ -62,6 +62,7 @@ Assistant". Previous sentence was written by Ellama itself.
* Commands::
* Keymap::
* Configuration::
+* Context Management::
* Minor modes::
* Using Blueprints::
* Acknowledgments::
@@ -70,6 +71,12 @@ Assistant". Previous sentence was written by Ellama itself.
-- The Detailed Node Listing --
+Context Management
+
+* Transient Menus for Context Management::
+* Managing the Context::
+* Considerations::
+
Minor modes
* ellama-context-header-line-mode::
@@ -371,7 +378,7 @@ Keymap Function Description
"p s" ellama-provider-select Provider select
-File: ellama.info, Node: Configuration, Next: Minor modes, Prev: Keymap,
Up: Top
+File: ellama.info, Node: Configuration, Next: Context Management, Prev:
Keymap, Up: Top
4 Configuration
***************
@@ -469,9 +476,95 @@ argument generated text string.
session line.
-File: ellama.info, Node: Minor modes, Next: Using Blueprints, Prev:
Configuration, Up: Top
+File: ellama.info, Node: Context Management, Next: Minor modes, Prev:
Configuration, Up: Top
+
+5 Context Management
+********************
+
+Ellama allows you to provide context to the Large Language Model (LLM)
+to improve the relevance and quality of responses. Context serves as
+background information, data, or instructions that guide the LLM's
+understanding of your prompt. Without context, the LLM relies solely on
+its pre-existing knowledge, which may not always be appropriate.
+
+A “global context” is maintained, which is a collection of text blocks
+accessible to the LLM when responding to prompts. This global context
+is prepened to your prompt before transmission to the LLM.
+
+* Menu:
+
+* Transient Menus for Context Management::
+* Managing the Context::
+* Considerations::
+
+
+File: ellama.info, Node: Transient Menus for Context Management, Next:
Managing the Context, Up: Context Management
+
+5.1 Transient Menus for Context Management
+==========================================
+
+Ellama provides a transient menu accessible through the main menu,
+offering a streamlined way to manage context elements. This menu is
+accessed via the “System” branch of the main transient menu, and then
+selecting "Context Commands."
+
+The Context Commands transient menu is structured as follows:
+
+Context Commands:
+
+ • Add: Provides options for adding content to the global context.
+ • “b” "Add Buffer" ‘ellama-context-add-buffer’
+ • “d” "Add Directory" ‘ellama-context-add-directory’
+ • “f” "Add File" ‘ellama-context-add-file’
+ • “s” "Add Selection" ‘ellama-context-add-selection’
+ • “i” "Add Info Node" ‘ellama-context-add-info-node’
+ • Manage: Provides options for managing the global context.
+ • “m” "Manage context" ‘ellama-context-manage’ - Opens the
+ context management buffer.
+ • “D” "Delete element" ‘ellama-context-element-remove-by-name’ -
+ Deletes an element by name.
+ • “r” "Context reset" ‘ellama-context-reset’ - Clears the entire
+ global context.
+ • Quit: (“q” "Quit" ‘transient-quit-one’) - Closes the context
+ commands transient menu.
+
+
+File: ellama.info, Node: Managing the Context, Next: Considerations, Prev:
Transient Menus for Context Management, Up: Context Management
+
+5.2 Managing the Context
+========================
+
+‘ellama-context-manage’ opens a dedicated buffer, the context management
+buffer, where you can view, modify, and organize the global context.
+Within this buffer:
+
+ • ‘n’: Move to the next context element.
+ • ‘p’: Move to the previous context element.
+ • ‘q’: Quit the context management buffer.
+ • ‘g’: Refresh the contents of the context management buffer.
+ • ‘a’: Add a new context element (similar to
+ ‘ellama-context-add-selection’).
+ • ‘RET’: Preview the content of the context element at the current
+ point.
+
+
+File: ellama.info, Node: Considerations, Prev: Managing the Context, Up:
Context Management
+
+5.3 Considerations
+==================
+
+Large Language Models possess limited context window sizes, restricting
+the total amount of text they can process. Be mindful of the size of
+your context to avoid truncation or performance degradation. Irrelevant
+context can dilute the information and hinder the LLM’s focus. Ensure
+context remains up-to-date for accurate information. Experimentation
+with different approaches to context management can optimize performance
+for specific use cases.
+
+
+File: ellama.info, Node: Minor modes, Next: Using Blueprints, Prev: Context
Management, Up: Top
-5 Minor modes
+6 Minor modes
*************
The Ellama package for Emacs offers a suite of minor modes designed to
@@ -514,7 +607,7 @@ globally across all buffers or selectively within
individual buffers.
File: ellama.info, Node: ellama-context-header-line-mode, Next:
ellama-context-header-line-global-mode, Up: Minor modes
-5.1 ellama-context-header-line-mode
+6.1 ellama-context-header-line-mode
===================================
Description: Toggle the Ellama Context header line mode. This minor
@@ -536,7 +629,7 @@ When disabled, it removes the evaluation of ‘(:eval
File: ellama.info, Node: ellama-context-header-line-global-mode, Next:
ellama-context-mode-line-mode, Prev: ellama-context-header-line-mode, Up:
Minor modes
-5.2 ellama-context-header-line-global-mode
+6.2 ellama-context-header-line-global-mode
==========================================
Description: Globalized version of ‘ellama-context-header-line-mode’.
@@ -555,7 +648,7 @@ of the buffer being edited.
File: ellama.info, Node: ellama-context-mode-line-mode, Next:
ellama-context-mode-line-global-mode, Prev:
ellama-context-header-line-global-mode, Up: Minor modes
-5.3 ellama-context-mode-line-mode
+6.3 ellama-context-mode-line-mode
=================================
Description: Toggle the Ellama Context mode line mode. This minor mode
@@ -577,7 +670,7 @@ When disabled, it removes the evaluation of ‘(:eval
File: ellama.info, Node: ellama-context-mode-line-global-mode, Next: Ellama
Session Header Line Mode, Prev: ellama-context-mode-line-mode, Up: Minor modes
-5.4 ellama-context-mode-line-global-mode
+6.4 ellama-context-mode-line-global-mode
========================================
Description: Globalized version of ‘ellama-context-mode-line-mode’.
@@ -596,7 +689,7 @@ of the buffer being edited.
File: ellama.info, Node: Ellama Session Header Line Mode, Next: Ellama
Session Mode Line Mode, Prev: ellama-context-mode-line-global-mode, Up: Minor
modes
-5.5 Ellama Session Header Line Mode
+6.5 Ellama Session Header Line Mode
===================================
The ‘ellama-session-header-line-mode’ is a minor mode that allows you to
@@ -612,7 +705,7 @@ with, especially useful when managing multiple sessions.
File: ellama.info, Node: Enabling and Disabling, Next: Customization, Up:
Ellama Session Header Line Mode
-5.5.1 Enabling and Disabling
+6.5.1 Enabling and Disabling
----------------------------
To enable this mode, use the following command:
@@ -625,7 +718,7 @@ can also enable or disable it globally across all buffers
using:
File: ellama.info, Node: Customization, Prev: Enabling and Disabling, Up:
Ellama Session Header Line Mode
-5.5.2 Customization
+6.5.2 Customization
-------------------
The session ID is displayed with a customizable face called
@@ -634,7 +727,7 @@ The session ID is displayed with a customizable face called
File: ellama.info, Node: Ellama Session Mode Line Mode, Prev: Ellama Session
Header Line Mode, Up: Minor modes
-5.6 Ellama Session Mode Line Mode
+6.6 Ellama Session Mode Line Mode
=================================
The ‘ellama-session-mode-line-mode’ is a minor mode that allows you to
@@ -651,7 +744,7 @@ sessions.
File: ellama.info, Node: Enabling and Disabling (1), Next: Customization
(1), Up: Ellama Session Mode Line Mode
-5.6.1 Enabling and Disabling
+6.6.1 Enabling and Disabling
----------------------------
To enable this mode, use the following command:
@@ -664,7 +757,7 @@ can also enable or disable it globally across all buffers
using:
File: ellama.info, Node: Customization (1), Prev: Enabling and Disabling
(1), Up: Ellama Session Mode Line Mode
-5.6.2 Customization
+6.6.2 Customization
-------------------
The session ID is displayed with a customizable face called
@@ -673,7 +766,7 @@ The session ID is displayed with a customizable face called
File: ellama.info, Node: Using Blueprints, Next: Acknowledgments, Prev:
Minor modes, Up: Top
-6 Using Blueprints
+7 Using Blueprints
******************
Blueprints in Ellama refer to predefined templates or structures that
@@ -694,7 +787,7 @@ for interactions.
File: ellama.info, Node: Key Components of Ellama Blueprints, Next: Creating
and Managing Blueprints, Up: Using Blueprints
-6.1 Key Components of Ellama Blueprints
+7.1 Key Components of Ellama Blueprints
=======================================
1. Act: This is the primary identifier for a blueprint, representing
@@ -711,7 +804,7 @@ developers.
File: ellama.info, Node: Creating and Managing Blueprints, Next: Variable
Management, Prev: Key Components of Ellama Blueprints, Up: Using Blueprints
-6.2 Creating and Managing Blueprints
+7.2 Creating and Managing Blueprints
====================================
Ellama provides several functions to create, select, and manage
@@ -734,7 +827,7 @@ blueprints:
File: ellama.info, Node: Variable Management, Next: Keymap and Mode, Prev:
Creating and Managing Blueprints, Up: Using Blueprints
-6.3 Variable Management
+7.3 Variable Management
=======================
Blueprints can include variables that need to be filled before running
@@ -746,7 +839,7 @@ the chat session. Ellama provides command to fill these
variables:
File: ellama.info, Node: Keymap and Mode, Next: Transient Menus, Prev:
Variable Management, Up: Using Blueprints
-6.4 Keymap and Mode
+7.4 Keymap and Mode
===================
Ellama provides a local keymap ‘ellama-blueprint-mode-map’ for managing
@@ -770,7 +863,7 @@ available:
File: ellama.info, Node: Transient Menus, Next: Running Blueprints
programmatically, Prev: Keymap and Mode, Up: Using Blueprints
-6.5 Transient Menus
+7.5 Transient Menus
===================
Ellama includes transient menus for easy access to blueprint commands.
@@ -783,7 +876,7 @@ main menu, providing a comprehensive interface for all
Ellama commands.
File: ellama.info, Node: Running Blueprints programmatically, Prev:
Transient Menus, Up: Using Blueprints
-6.6 Running Blueprints programmatically
+7.6 Running Blueprints programmatically
=======================================
The ‘ellama-blueprint-run’ function initiates a chat session using a
@@ -800,7 +893,7 @@ arguments.
File: ellama.info, Node: Acknowledgments, Next: Contributions, Prev: Using
Blueprints, Up: Top
-7 Acknowledgments
+8 Acknowledgments
*****************
Thanks Jeffrey Morgan (https://github.com/jmorganca) for excellent
@@ -820,7 +913,7 @@ Without it only ‘ollama’ would be supported.
File: ellama.info, Node: Contributions, Next: GNU Free Documentation
License, Prev: Acknowledgments, Up: Top
-8 Contributions
+9 Contributions
***************
To contribute, submit a pull request or report a bug. This library is
@@ -1314,31 +1407,35 @@ their use in free software.
Tag Table:
Node: Top1379
-Node: Installation3482
-Node: Commands8490
-Node: Keymap14834
-Node: Configuration17667
-Node: Minor modes23001
-Node: ellama-context-header-line-mode24984
-Node: ellama-context-header-line-global-mode25809
-Node: ellama-context-mode-line-mode26529
-Node: ellama-context-mode-line-global-mode27377
-Node: Ellama Session Header Line Mode28081
-Node: Enabling and Disabling28650
-Node: Customization29097
-Node: Ellama Session Mode Line Mode29385
-Node: Enabling and Disabling (1)29970
-Node: Customization (1)30417
-Node: Using Blueprints30711
-Node: Key Components of Ellama Blueprints31330
-Node: Creating and Managing Blueprints31937
-Node: Variable Management32918
-Node: Keymap and Mode33387
-Node: Transient Menus34323
-Node: Running Blueprints programmatically34869
-Node: Acknowledgments35456
-Node: Contributions36169
-Node: GNU Free Documentation License36553
+Node: Installation3613
+Node: Commands8621
+Node: Keymap14965
+Node: Configuration17798
+Node: Context Management23139
+Node: Transient Menus for Context Management23932
+Node: Managing the Context25390
+Node: Considerations26165
+Node: Minor modes26758
+Node: ellama-context-header-line-mode28746
+Node: ellama-context-header-line-global-mode29571
+Node: ellama-context-mode-line-mode30291
+Node: ellama-context-mode-line-global-mode31139
+Node: Ellama Session Header Line Mode31843
+Node: Enabling and Disabling32412
+Node: Customization32859
+Node: Ellama Session Mode Line Mode33147
+Node: Enabling and Disabling (1)33732
+Node: Customization (1)34179
+Node: Using Blueprints34473
+Node: Key Components of Ellama Blueprints35092
+Node: Creating and Managing Blueprints35699
+Node: Variable Management36680
+Node: Keymap and Mode37149
+Node: Transient Menus38085
+Node: Running Blueprints programmatically38631
+Node: Acknowledgments39218
+Node: Contributions39931
+Node: GNU Free Documentation License40315
End Tag Table
