This is a fledgling project. Expect lots of bugs and missing features.
Evedel is an extension to the GPTel Emacs package that enhances the workflow of interacting with large language models during programmer. Its primary aim is to shift workload from manually writing code to creating detailed, thoughtful instruction labels for the LLM models, leveraging references to provide contextual understanding of the working environment.
Evedel is versatile enough so that it can be utilized in various types of buffers, and isn’t limited to just programming buffers.
- Uses GPTel as a backend, so no extra setup is necessary if you already use it.
- Uses overlays for tracking instructions instead of raw text, which means that the instructions are not part of your file or buffer. The overlays are mostly intuitive and can be customized, and try not to interfere with the regular Emacs workflow.
- Can save your instruction overlays so you won’t have to restart the instruction labeling process every time you start a new Emacs session.
- Can categorize your references with tags, and use complex query expressions to determine what to sent to the model in directives.
- Can easily cycle through between instruction overlays across all buffers.
- GPTel
- Emacs version 29.1 or higher
Evedel’s function revolves around the creation and manipulation of references and directives within your Emacs buffers. Directives are prompts you send to the model, while references provide context to help complete these directives more accurately.
| Command | Command Description |
|---|---|
evedel-create-reference | Create or resize a reference instruction within a region. |
evedel-create-directive | Create or resize a directive instruction at point or within a region. |
evedel-modify-directive | Modify an existing directive instruction at point. |
evedel-delete-instructions | Remove instructions either at point or within the selected region. |
evedel-delete-all | Delete all Evedel instructions across all buffers. |
- If the region mark started from outside the reference/directive overlay and a part of it is within the selected region, the instruction will be “shrunk” to fit the new region boundaries.
- If the region mark started from inside the reference/directive overlay, the instruction will grow to include the entire new selection.
Below is an example of scaling existing instruction overlay (in this case, a reference) by invoking the evedel-create-reference command within a region that contains one:
| Command | Command Description |
|---|---|
evedel-save-instructions | Save current instruction overlays to a specified file. |
evedel-load-instructions | Load instruction overlays from a specified file. |
evedel-process-directives | Process directives by sending them to GPTel. |
evedel-convert-instructions | Convert between reference and directive types at point. |
evedel-instruction-count | Return the number of instructions currently loaded. |
evedel-preview-directive-prompt | Preview directive prompt at the current point. |
Here’s an example of previewing a directive prompt:
- For
evedel-process-directives:- If at point: sends the directive under the point.
- If a region is selected: sends all directives within the selected region.
- Otherwise, processes all directives in the current buffer.
| Command | Command Description |
|---|---|
evedel-next-instruction | Cycle through instructions in the forward direction. |
evedel-previous-instruction | Cycle through instructions in the backward direction. |
evedel-next-reference | Cycle through references in the forward direction. |
evedel-previous-reference | Cycle through references in the backward direction. |
evedel-next-directive | Cycle through directives in the forward direction. |
evedel-previous-directive | Cycle through directives in the backward direction. |
| Command | Description |
|---|---|
evedel-add-tags | Add tags to the reference under the point. |
evedel-remove-tags | Remove tags from the reference under the point. |
evedel-modify-directive-tag-query | Enter a tag search query for a directive under the current point. |
The categorization system in allows you to use tags to label and organize references. You can add or remove tags to a reference using the commands evedel-add-tags and evedel-remove-tags. Each tag is a symbolic label that helps identify the nature or purpose of the reference.
You can also modify the tag query for a directive, which is a way to filter and search for references by tags. The tag query uses an infix notation system, allowing complex expressions with the operators and, or, and not. For example, the query signature and function and doc means the directive should match references tagged with signature, function, and doc. You may use parentheses in these expressions.
| Custom Variable | Description |
|---|---|
evedel-empty-tag-query-matches-all | Determines matching behavior of queryless directives |
evedel-always-match-untagged-references | Determines matching behavior of untagged references |
evedel-empty-tag-query-matches-all: This custom variable determines the behavior of directives without a tag search query. If set tot, directives lacking a specific tag search query will use all available references. Alternatively, if set tonil, such directives will not use any references, leading to potentially narrower results.evedel-always-match-untagged-references: This custom variable controls the inclusion of untagged references in directive prompts. When set tot, untagged references are always incorporated into directive references, ensuring comprehensive coverage. Conversely, when set tonil, untagged references are ignored unlessevedel-empty-tag-query-matches-allis set tot.
| Custom Variable | Description |
|---|---|
evedel-reference-color | Tint color for reference overlays |
evedel-directive-color | Tint color for directive overlays |
evedel-directive-processing-color | Tint color for directives being processed |
evedel-directive-success-color | Tint color for successfully processed directives |
evedel-directive-fail-color | Tint color for failed directives |
evedel-instruction-bg-tint-intensity | Intensity for instruction background tint |
evedel-instruction-label-tint-intensity | Intensity for instruction label tint |
evedel-subinstruction-tint-intensity | Coefficient for adjusting subinstruction tints |
evedel-descriptive-mode-roles | Major modes to model roles association list |
Please refer to the custom variable documentation within the package for a more comprehensive description.
If you have added instructions to your files and saved them, make sure to load them before resuming work on your project. Failing to do so, and loading them after making changes to your files, will lead to mismatched instruction overlays.
To alleviate this until something more established is added, you could consult the project’s .dir-locals.el to see how auto-saving/loading is done in the project.
Before proceeding, make sure you have GPTel configured (see requirements). This package will not work without it. Clone the Evedel repository:
git clone https://github.com/daedsidog/evedel.gitAdd the path to the cloned repository in your Emacs configuration. You can do this by adding the following code to your init.el or config.el file:
(add-to-list 'load-path "/path/to/evedel")
Use =use-package= to configure Evedel as shown in the snippet below:
(use-package evedel
:config
(customize-set-variable 'evedel-empty-tag-query-matches-all nil)
:bind (("C-c e r" . evedel-create-reference)
("C-c e d" . evedel-create-directive)
("C-c e s" . evedel-save-instructions)
("C-c e l" . evedel-load-instructions)
("C-c e p" . evedel-process-directives)
("C-c e m" . evedel-modify-directive)
("C-c e k" . evedel-delete-instructions)
("C-c e c" . evedel-convert-instructions)
("C->" . evedel-next-instruction)
("C-<" . evedel-previous-instruction)
("C-c e t" . evedel-add-tags)
("C-c e T" . evedel-remove-tags)
("C-c e D" . evedel-modify-directive-tag-query)
("C-c e P" . evedel-preview-directive-prompt)))Make sure to replace "/path/to/evedel" with the actual path where you cloned the Evedel repository.
- [ ] Instruction navigation
- [X] Basic cyclic navigation between instruction across buffers
- [ ] Reference navigation based on a tag query
- [ ] Categorization
- [X] Reference tags
- [X] Filter references via tag query when sending directives
- [ ] Tag autocompletion when writing directive tag query
- [ ] Interface
- [ ] Auto-saving/loading. For now, you can consult the .dir-locals.el file that I use for the project to see how I handle automatic saving/loading of instructions for it.
- [ ] Persistence with version controls, e.g. switching branches should not mess up the instructions.
- [ ] Preservation of sub-instructions returned as part of a successful directive
- [ ] Instruction undoing/redoing history
- [ ] Better/more precise instruction selection resolution for tightly nested instructions
- [ ] Documentation
- [X] Ability to preview directive to be sent
- [ ] Instruction help tool-tips
- [ ] Directive tools
- [ ] Sequential execution of dependent directives
- [ ] Interactive directive result diff, i.e. being able to tell the model what to correct.
- Special thanks to Karthik Chikmagalur for the excellent GPTel package