prompt_navigator 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +119 -92
- data/lib/prompt_navigator/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: e274278632397e1855b526f972b2fefe465b3fdb1d98aa58e21a66e4760f9ada
|
|
4
|
+
data.tar.gz: 23b2c261efe6a2b83a3762891dd6e45c91c1df977820202a751de8f2f3a9d83b
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: e61e66a4a8cb9dfdffccd40ea81a490e8d2bf79a174ecf9506988d4bc19dc000f3122dbce58c7b3021b5a0812286e863fb1a85da1bb4a061c65a97abc458b8d1
|
|
7
|
+
data.tar.gz: 7c7d01998defac44429f0ced473d477c3aa33781af07ec5787f5f87a4d0b7c75c88fd50cac61512b350ce38781ab6add6c25ef0862032d5d84ce7ad20c3baa57
|
data/README.md
CHANGED
|
@@ -1,16 +1,22 @@
|
|
|
1
1
|
# PromptNavigator
|
|
2
2
|
|
|
3
|
-
Rails engine for managing prompt execution history
|
|
3
|
+
A Rails engine for managing and visualizing LLM prompt execution history. It provides a visual history stack UI with interactive SVG arrow connections between parent-child prompt executions, enabling users to navigate conversation trees.
|
|
4
4
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
7
|
-
-
|
|
8
|
-
-
|
|
9
|
-
- Stimulus-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
7
|
+
- **PromptExecution model** - Self-referencing tree structure for tracking prompt executions with UUID identifiers
|
|
8
|
+
- **Visual history stack** - Card-based UI displaying prompt history with parent-child relationships
|
|
9
|
+
- **Arrow visualization** - Straight arrows (`↑`) for adjacent cards; curved SVG arrows (via Stimulus) for non-adjacent parent-child connections
|
|
10
|
+
- **Active state highlighting** - Blue border and glow effect on the currently selected card
|
|
11
|
+
- **Responsive design** - Hover effects with lift animation; arrows redraw on window resize
|
|
12
|
+
- **Automatic integration** - Controller concern, view helpers, and assets are auto-registered by the engine
|
|
13
|
+
- **Rails generator** - `prompt_navigator:modeling` generator for creating the required migration
|
|
14
|
+
|
|
15
|
+
## Requirements
|
|
16
|
+
|
|
17
|
+
- Ruby >= 3.2.0
|
|
18
|
+
- Rails >= 8.1.2
|
|
19
|
+
- Stimulus ([Hotwire](https://hotwired.dev/))
|
|
14
20
|
|
|
15
21
|
## Installation
|
|
16
22
|
|
|
@@ -33,21 +39,23 @@ $ rails generate prompt_navigator:modeling
|
|
|
33
39
|
$ rails db:migrate
|
|
34
40
|
```
|
|
35
41
|
|
|
36
|
-
This
|
|
42
|
+
This creates the `prompt_navigator_prompt_executions` table with the following columns:
|
|
37
43
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
44
|
+
| Column | Type | Description |
|
|
45
|
+
|--------|------|-------------|
|
|
46
|
+
| `execution_id` | string | Unique identifier (UUID), auto-generated on create |
|
|
47
|
+
| `prompt` | text | The prompt text sent to the LLM |
|
|
48
|
+
| `llm_platform` | string | The LLM platform (e.g., `"openai"`, `"anthropic"`) |
|
|
49
|
+
| `model` | string | The model name (e.g., `"gpt-4"`, `"claude-3"`) |
|
|
50
|
+
| `configuration` | string | Model configuration as JSON |
|
|
51
|
+
| `response` | text | The LLM response text |
|
|
52
|
+
| `previous_id` | integer | Foreign key to the parent execution (for building history tree) |
|
|
45
53
|
|
|
46
54
|
## Usage
|
|
47
55
|
|
|
48
|
-
###
|
|
56
|
+
### Layout Setup
|
|
49
57
|
|
|
50
|
-
In your application
|
|
58
|
+
In your application layout (`app/views/layouts/application.html.erb`), add `<%= yield :head %>` in the `<head>` section to load the engine's stylesheets:
|
|
51
59
|
|
|
52
60
|
```erb
|
|
53
61
|
<head>
|
|
@@ -62,38 +70,23 @@ In your application's layout file (`app/views/layouts/application.html.erb`), ma
|
|
|
62
70
|
</head>
|
|
63
71
|
```
|
|
64
72
|
|
|
65
|
-
Include the history partial in your view:
|
|
66
|
-
|
|
67
|
-
```erb
|
|
68
|
-
<%= render 'prompt_navigator/history', locals: { active_uuid: @current_execution_id, card_path: ->(execution_id) { my_path(execution_id) } } %>
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
### Asset Pipeline Configuration
|
|
72
|
-
|
|
73
|
-
The engine automatically configures the asset pipeline to include:
|
|
74
|
-
- `prompt_navigator/history.css` - Styles for the history component
|
|
75
|
-
- `controllers/history_controller.js` - Stimulus controller for arrow drawing
|
|
76
|
-
|
|
77
|
-
The assets are automatically precompiled and made available to your application. For Rails 7+ with importmap, the CSS will be loaded via `stylesheet_link_tag` when you render the history partial, and the Stimulus controller will be automatically registered.
|
|
78
|
-
|
|
79
73
|
### Controller Setup
|
|
80
74
|
|
|
81
|
-
|
|
75
|
+
The `HistoryManageable` concern is automatically included in all controllers by the engine. It provides three methods:
|
|
76
|
+
|
|
77
|
+
- `initialize_history(history)` - Sets the `@history` instance variable (converts to array)
|
|
78
|
+
- `set_active_message_uuid(uuid)` - Sets the `@active_message_uuid` instance variable
|
|
79
|
+
- `push_to_history(new_state)` - Appends a new state to `@history`
|
|
82
80
|
|
|
83
81
|
```ruby
|
|
84
82
|
class MyController < ApplicationController
|
|
85
|
-
include HistoryManageable
|
|
86
|
-
|
|
87
83
|
def index
|
|
88
|
-
#
|
|
89
|
-
initialize_history(PromptNavigator::PromptExecution.
|
|
90
|
-
|
|
91
|
-
# Set the active execution ID (optional)
|
|
84
|
+
# History must be ordered newest-first for arrow visualization to work correctly
|
|
85
|
+
initialize_history(PromptNavigator::PromptExecution.order(id: :desc))
|
|
92
86
|
set_active_message_uuid(params[:execution_id])
|
|
93
87
|
end
|
|
94
88
|
|
|
95
89
|
def create
|
|
96
|
-
# Add new execution to history
|
|
97
90
|
new_execution = PromptNavigator::PromptExecution.create(
|
|
98
91
|
prompt: params[:prompt],
|
|
99
92
|
llm_platform: "openai",
|
|
@@ -107,56 +100,93 @@ class MyController < ApplicationController
|
|
|
107
100
|
end
|
|
108
101
|
```
|
|
109
102
|
|
|
110
|
-
###
|
|
103
|
+
### Rendering the History Component
|
|
104
|
+
|
|
105
|
+
The `history_list` helper is automatically available in all views. It renders the history stack:
|
|
106
|
+
|
|
107
|
+
```erb
|
|
108
|
+
<%= history_list(
|
|
109
|
+
->(execution_id) { my_item_path(execution_id) },
|
|
110
|
+
active_uuid: @active_message_uuid
|
|
111
|
+
) %>
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Parameters:
|
|
115
|
+
|
|
116
|
+
- `card_path` (first argument) - A Proc/Lambda that takes an `execution_id` and returns a URL path for the card link
|
|
117
|
+
- `active_uuid:` - The `execution_id` of the currently active card (highlighted with blue border)
|
|
118
|
+
|
|
119
|
+
Alternatively, you can render the partial directly:
|
|
120
|
+
|
|
121
|
+
```erb
|
|
122
|
+
<%= render "prompt_navigator/history",
|
|
123
|
+
locals: {
|
|
124
|
+
active_uuid: @active_message_uuid,
|
|
125
|
+
card_path: ->(execution_id) { my_item_path(execution_id) }
|
|
126
|
+
}
|
|
127
|
+
%>
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### PromptExecution Model
|
|
111
131
|
|
|
112
|
-
The `PromptNavigator::PromptExecution` model
|
|
132
|
+
The `PromptNavigator::PromptExecution` model stores prompt execution records with a self-referencing association for building conversation trees:
|
|
113
133
|
|
|
114
134
|
```ruby
|
|
135
|
+
# Create an execution
|
|
115
136
|
execution = PromptNavigator::PromptExecution.create(
|
|
116
|
-
prompt: "
|
|
137
|
+
prompt: "Explain Ruby blocks",
|
|
117
138
|
llm_platform: "openai",
|
|
118
139
|
model: "gpt-4",
|
|
119
|
-
configuration:
|
|
120
|
-
response: "
|
|
121
|
-
previous: parent_execution # Optional: for building history tree
|
|
140
|
+
configuration: '{"temperature": 0.7}',
|
|
141
|
+
response: "Ruby blocks are..."
|
|
122
142
|
)
|
|
123
143
|
|
|
124
|
-
#
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
execution
|
|
131
|
-
|
|
132
|
-
```
|
|
144
|
+
# Create a follow-up execution linked to the parent
|
|
145
|
+
follow_up = PromptNavigator::PromptExecution.create(
|
|
146
|
+
prompt: "Give me an example",
|
|
147
|
+
llm_platform: "openai",
|
|
148
|
+
model: "gpt-4",
|
|
149
|
+
response: "Here is an example...",
|
|
150
|
+
previous: execution # Sets previous_id to link as child
|
|
151
|
+
)
|
|
133
152
|
|
|
134
|
-
|
|
153
|
+
# Access attributes
|
|
154
|
+
execution.execution_id # => "a1b2c3d4-..." (auto-generated UUID)
|
|
155
|
+
execution.previous # => nil (root execution)
|
|
156
|
+
follow_up.previous # => execution (parent)
|
|
157
|
+
```
|
|
135
158
|
|
|
136
|
-
|
|
159
|
+
## Architecture
|
|
137
160
|
|
|
138
|
-
```
|
|
139
|
-
|
|
161
|
+
```
|
|
162
|
+
PromptNavigator (Rails Engine)
|
|
163
|
+
├── Model
|
|
164
|
+
│ └── PromptExecution # Self-referencing tree model with UUID
|
|
165
|
+
├── Controller Concern
|
|
166
|
+
│ └── HistoryManageable # Provides initialize_history, set_active_message_uuid, push_to_history
|
|
167
|
+
├── View Helper
|
|
168
|
+
│ └── Helpers#history_list # Renders the history partial
|
|
169
|
+
├── Partials
|
|
170
|
+
│ ├── _history.html.erb # Main container with Stimulus controller
|
|
171
|
+
│ └── _history_card.html.erb # Individual card with link and arrow logic
|
|
172
|
+
├── JavaScript
|
|
173
|
+
│ └── history_controller.js # Stimulus controller for SVG curved arrows
|
|
174
|
+
├── Stylesheets
|
|
175
|
+
│ └── history.css # Modern nested CSS for cards, arrows, hover effects
|
|
176
|
+
└── Generator
|
|
177
|
+
└── modeling # Creates migration for prompt_executions table
|
|
140
178
|
```
|
|
141
179
|
|
|
142
|
-
###
|
|
180
|
+
### Arrow Visualization
|
|
143
181
|
|
|
144
|
-
The
|
|
182
|
+
The history component uses two types of arrows to show parent-child relationships:
|
|
145
183
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
locals: {
|
|
149
|
-
active_uuid: @current_execution_id,
|
|
150
|
-
card_path: ->(execution_id) { my_item_path(execution_id) }
|
|
151
|
-
}
|
|
152
|
-
%>
|
|
153
|
-
```
|
|
184
|
+
1. **Straight arrows** (`↑`) - Rendered as HTML when a card's parent is the immediately adjacent card below it in the list
|
|
185
|
+
2. **Curved SVG arrows** - Drawn by the Stimulus controller (`history_controller.js`) when a card's parent is further away (vertical gap >= 80px). These bezier curves arc to the left of the stack
|
|
154
186
|
|
|
155
|
-
|
|
187
|
+
**Note:** Arrow visualization requires the history to be ordered newest-first (e.g., `order(id: :desc)`). If the history is in ascending order, parent-child adjacency detection will not work correctly.
|
|
156
188
|
|
|
157
|
-
|
|
158
|
-
<%= history_list(->(execution_id) { my_item_path(execution_id) }, active_uuid: @current_execution_id) %>
|
|
159
|
-
```
|
|
189
|
+
The Stimulus controller automatically redraws SVG arrows on window resize.
|
|
160
190
|
|
|
161
191
|
## Troubleshooting
|
|
162
192
|
|
|
@@ -168,43 +198,40 @@ Make sure you have `<%= yield :head %>` in your application layout's `<head>` se
|
|
|
168
198
|
|
|
169
199
|
The arrow visualization requires:
|
|
170
200
|
1. Stimulus to be properly configured in your application
|
|
171
|
-
2. The `history_controller.js` to be loaded (automatic with
|
|
172
|
-
3. Parent-child relationships to be
|
|
201
|
+
2. The `history_controller.js` to be loaded (automatic with the asset pipeline)
|
|
202
|
+
3. Parent-child relationships to be set using the `previous` association on PromptExecution records
|
|
173
203
|
|
|
174
204
|
### History not displaying
|
|
175
205
|
|
|
176
206
|
Ensure that:
|
|
177
|
-
1. `@history`
|
|
178
|
-
2.
|
|
179
|
-
3. The `card_path` callable
|
|
180
|
-
|
|
181
|
-
## Requirements
|
|
207
|
+
1. `@history` is set in your controller using `initialize_history`
|
|
208
|
+
2. PromptExecution records have `execution_id` values (automatically generated on create)
|
|
209
|
+
3. The `card_path` callable returns valid paths
|
|
182
210
|
|
|
183
|
-
|
|
184
|
-
- Stimulus (Hotwired)
|
|
211
|
+
## Development
|
|
185
212
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
Add this line to your application's Gemfile:
|
|
213
|
+
After checking out the repo, run:
|
|
189
214
|
|
|
190
|
-
```
|
|
191
|
-
|
|
215
|
+
```bash
|
|
216
|
+
$ bundle install
|
|
192
217
|
```
|
|
193
218
|
|
|
194
|
-
|
|
219
|
+
Run the tests:
|
|
195
220
|
|
|
196
221
|
```bash
|
|
197
|
-
$
|
|
222
|
+
$ bin/rails test
|
|
198
223
|
```
|
|
199
224
|
|
|
200
|
-
|
|
225
|
+
Run the linter:
|
|
201
226
|
|
|
202
227
|
```bash
|
|
203
|
-
$
|
|
228
|
+
$ bundle exec rubocop
|
|
204
229
|
```
|
|
205
230
|
|
|
206
231
|
## Contributing
|
|
207
|
-
|
|
232
|
+
|
|
233
|
+
Bug reports and pull requests are welcome on [GitHub](https://github.com/dhq-boiler/prompt_manager).
|
|
208
234
|
|
|
209
235
|
## License
|
|
236
|
+
|
|
210
237
|
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: prompt_navigator
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.2.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- dhq_boiler
|
|
@@ -86,7 +86,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
86
86
|
- !ruby/object:Gem::Version
|
|
87
87
|
version: '0'
|
|
88
88
|
requirements: []
|
|
89
|
-
rubygems_version:
|
|
89
|
+
rubygems_version: 4.0.3
|
|
90
90
|
specification_version: 4
|
|
91
91
|
summary: A Rails engine for managing and visualizing LLM prompt execution history.
|
|
92
92
|
test_files: []
|