aia 2.0.0.0.pre.beta2 → 2.0.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/.version +1 -1
- data/CHANGELOG.md +146 -228
- data/README.md +41 -18
- data/bin/aia +8 -3
- data/lib/aia/aia_completion.bash +2 -3
- data/lib/aia/aia_completion.fish +6 -5
- data/lib/aia/aia_completion.zsh +2 -3
- data/lib/aia/chat_loop.rb +16 -14
- data/lib/aia/config/cli_parser.rb +123 -91
- data/lib/aia/config/defaults.yml +12 -39
- data/lib/aia/config/mcp_parser.rb +30 -36
- data/lib/aia/config/model_spec.rb +8 -14
- data/lib/aia/config/validator.rb +102 -103
- data/lib/aia/config/value_caster.rb +76 -0
- data/lib/aia/config.rb +70 -53
- data/lib/aia/crew.rb +29 -19
- data/lib/aia/debate_handler.rb +27 -10
- data/lib/aia/directives/configuration_directives.rb +55 -14
- data/lib/aia/directives/context_directives.rb +24 -12
- data/lib/aia/directives/execution_directives.rb +18 -23
- data/lib/aia/directives/model_directives.rb +41 -104
- data/lib/aia/directives/utility_directives.rb +16 -17
- data/lib/aia/directives/web_and_file_directives.rb +21 -14
- data/lib/aia/fact_asserter.rb +3 -3
- data/lib/aia/history_transfer.rb +64 -24
- data/lib/aia/logger.rb +10 -45
- data/lib/aia/mcp_config_normalizer.rb +27 -14
- data/lib/aia/mcp_connection_manager.rb +181 -184
- data/lib/aia/mcp_discovery.rb +43 -15
- data/lib/aia/mcp_grouper.rb +2 -1
- data/lib/aia/mcp_server_config.rb +20 -2
- data/lib/aia/mcp_utility.rb +24 -19
- data/lib/aia/mention_router.rb +15 -2
- data/lib/aia/modality_query.rb +36 -0
- data/lib/aia/model_alias_registry.rb +11 -11
- data/lib/aia/model_registry.rb +75 -0
- data/lib/aia/network_builder.rb +8 -7
- data/lib/aia/patches/ruby_llm_streaming_error.rb +21 -4
- data/lib/aia/patches/ruby_llm_tool_param_compat.rb +18 -0
- data/lib/aia/pipeline_orchestrator.rb +71 -38
- data/lib/aia/prompt_decomposer.rb +1 -1
- data/lib/aia/prompt_handler.rb +56 -29
- data/lib/aia/provider_registry.rb +105 -0
- data/lib/aia/robot_builder.rb +1 -1
- data/lib/aia/robot_factory.rb +67 -63
- data/lib/aia/robot_sync.rb +79 -0
- data/lib/aia/role_catalog.rb +89 -0
- data/lib/aia/session.rb +25 -11
- data/lib/aia/skill_utils.rb +60 -19
- data/lib/aia/spawn_handler.rb +16 -4
- data/lib/aia/spawn_spec_parser.rb +6 -7
- data/lib/aia/special_mode_handler.rb +28 -25
- data/lib/aia/speech.rb +70 -34
- data/lib/aia/startup_coordinator.rb +17 -92
- data/lib/aia/streaming_runner.rb +10 -2
- data/lib/aia/system_prompt_assembler.rb +12 -11
- data/lib/aia/task_board.rb +60 -0
- data/lib/aia/tool_approver.rb +205 -0
- data/lib/aia/tool_filter.rb +1 -10
- data/lib/aia/tool_filter_strategy.rb +12 -1
- data/lib/aia/tool_introspection.rb +9 -1
- data/lib/aia/tool_loader.rb +67 -33
- data/lib/aia/tool_utility.rb +6 -5
- data/lib/aia/tools/delegate_to_foreman_tool.rb +6 -4
- data/lib/aia/tools/recruit_robot_tool.rb +12 -12
- data/lib/aia/tools/reskill_robot_tool.rb +7 -7
- data/lib/aia/tools/task_board_tool.rb +16 -16
- data/lib/aia/trakflow_bridge.rb +14 -8
- data/lib/aia/turn_state.rb +31 -8
- data/lib/aia/ui_presenter.rb +16 -0
- data/lib/aia/utility.rb +6 -24
- data/lib/aia/variable_input_collector.rb +0 -3
- data/lib/aia/verification_network.rb +9 -10
- data/lib/aia.rb +33 -8
- metadata +19 -160
- data/.better-commits.json +0 -150
- data/.config/tocer/configuration.yml +0 -6
- data/.envrc +0 -19
- data/.loki +0 -11
- data/.reek.yml +0 -160
- data/.rubocop.yml +0 -116
- data/.rubocop_strict.yml +0 -15
- data/COMMITS.md +0 -196
- data/IMPLEMENTATION_PLAN.md +0 -506
- data/Rakefile +0 -47
- data/_typos.toml +0 -10
- data/aia.gemspec +0 -92
- data/architecture_review.md +0 -314
- data/config/aia.yml +0 -13
- data/docs/AGENTS.md +0 -40
- data/docs/advanced-prompting.md +0 -814
- data/docs/assets/images/aia.png +0 -0
- data/docs/cli-reference.md +0 -1241
- data/docs/configuration.md +0 -747
- data/docs/contributing.md +0 -386
- data/docs/directives-reference.md +0 -1145
- data/docs/examples/index.md +0 -277
- data/docs/examples/mcp/index.md +0 -475
- data/docs/examples/prompts/analysis/index.md +0 -78
- data/docs/examples/prompts/automation/index.md +0 -109
- data/docs/examples/prompts/development/index.md +0 -125
- data/docs/examples/prompts/index.md +0 -333
- data/docs/examples/prompts/learning/index.md +0 -127
- data/docs/examples/prompts/writing/index.md +0 -62
- data/docs/examples/tools/index.md +0 -282
- data/docs/faq.md +0 -578
- data/docs/guides/available-models.md +0 -366
- data/docs/guides/basic-usage.md +0 -478
- data/docs/guides/chat.md +0 -680
- data/docs/guides/crew.md +0 -239
- data/docs/guides/executable-prompts.md +0 -331
- data/docs/guides/first-prompt.md +0 -454
- data/docs/guides/getting-started.md +0 -455
- data/docs/guides/image-generation.md +0 -507
- data/docs/guides/index.md +0 -48
- data/docs/guides/local-models.md +0 -306
- data/docs/guides/migrate-prompts.md +0 -335
- data/docs/guides/models.md +0 -1017
- data/docs/guides/shared-tools.md +0 -254
- data/docs/guides/tools.md +0 -831
- data/docs/index.md +0 -259
- data/docs/installation.md +0 -274
- data/docs/mcp-integration.md +0 -603
- data/docs/prompt_management.md +0 -665
- data/docs/security.md +0 -674
- data/docs/special_projects_guide.md +0 -386
- data/docs/tools-and-mcp-examples.md +0 -1211
- data/docs/workflows-and-pipelines.md +0 -636
- data/examples/.gitignore +0 -2
- data/examples/00_setup_aia.sh +0 -111
- data/examples/01_basic_usage.sh +0 -23
- data/examples/02_frontmatter.sh +0 -33
- data/examples/03_shell_integration.sh +0 -55
- data/examples/04_erb_templating.sh +0 -56
- data/examples/05_shell_then_erb.sh +0 -38
- data/examples/06_prompt_chaining.sh +0 -59
- data/examples/07_pipeline.sh +0 -46
- data/examples/08_context_files.sh +0 -43
- data/examples/09_roles.sh +0 -67
- data/examples/10_stdin_piping.sh +0 -49
- data/examples/11_multi_model.sh +0 -65
- data/examples/12_token_usage.sh +0 -52
- data/examples/13_cost_tracking.sh +0 -68
- data/examples/14_output_file.sh +0 -91
- data/examples/15_parameters.sh +0 -68
- data/examples/16_directives.sh +0 -113
- data/examples/17_require_and_conditionals.sh +0 -68
- data/examples/18_tools.sh +0 -61
- data/examples/19_local_tools.sh +0 -34
- data/examples/20_mcp_servers.sh +0 -102
- data/examples/21_executable_prompts.sh +0 -78
- data/examples/22_chat_mode.sh +0 -217
- data/examples/23_verify.sh +0 -139
- data/examples/24_decompose.sh +0 -139
- data/examples/25_spawn.sh +0 -139
- data/examples/26_debate.sh +0 -97
- data/examples/27_mention_routing.sh +0 -157
- data/examples/28_model_switching.sh +0 -106
- data/examples/29_agent_harness.sh +0 -177
- data/examples/README.md +0 -321
- data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
- data/examples/aia_config.yml +0 -22
- data/examples/aia_config_orchestrator.yml +0 -45
- data/examples/aia_config_with_mcp.yml +0 -21
- data/examples/common.sh +0 -39
- data/examples/context/project_goals.md +0 -6
- data/examples/context/tech_stack.md +0 -7
- data/examples/directives/timestamp_directive.rb +0 -22
- data/examples/mcp/filesystem.json +0 -9
- data/examples/prompts_dir/analyze.md +0 -2
- data/examples/prompts_dir/brainstorm.md +0 -2
- data/examples/prompts_dir/conditional.md +0 -17
- data/examples/prompts_dir/creative.md +0 -4
- data/examples/prompts_dir/erbinfo.md +0 -5
- data/examples/prompts_dir/erbinfo_raw.md +0 -8
- data/examples/prompts_dir/evaluate.md +0 -2
- data/examples/prompts_dir/explain_joke.md +0 -1
- data/examples/prompts_dir/explain_recursion.md +0 -1
- data/examples/prompts_dir/fun_fact +0 -3
- data/examples/prompts_dir/greeting.md +0 -8
- data/examples/prompts_dir/greeting_required.md +0 -7
- data/examples/prompts_dir/hello.md +0 -1
- data/examples/prompts_dir/includes/ruby_facts.md +0 -4
- data/examples/prompts_dir/limerick.md +0 -1
- data/examples/prompts_dir/list_with_mcp.md +0 -3
- data/examples/prompts_dir/pick_best.md +0 -2
- data/examples/prompts_dir/project_summary +0 -12
- data/examples/prompts_dir/quiz_with_include.md +0 -6
- data/examples/prompts_dir/require_demo.md +0 -5
- data/examples/prompts_dir/roles/formal.md +0 -3
- data/examples/prompts_dir/roles/orchestrator.md +0 -21
- data/examples/prompts_dir/roles/pirate.md +0 -3
- data/examples/prompts_dir/shell_then_erb.md +0 -6
- data/examples/prompts_dir/sort_compare.md +0 -2
- data/examples/prompts_dir/summarize_context.md +0 -2
- data/examples/prompts_dir/sysinfo.md +0 -5
- data/examples/prompts_dir/sysinfo_raw.md +0 -8
- data/examples/prompts_dir/tagline.md +0 -1
- data/examples/prompts_dir/tell_joke.md +0 -1
- data/examples/prompts_dir/tell_joke_with_next.md +0 -4
- data/examples/prompts_dir/use_local_tool.md +0 -8
- data/examples/prompts_dir/use_tools.md +0 -8
- data/examples/prompts_dir/weather.md +0 -2
- data/examples/prompts_dir/whats_new.md +0 -2
- data/examples/prompts_dir/with_timestamp.md +0 -5
- data/examples/requirements/sinatra_taskflow_app.md +0 -139
- data/examples/rules/01_classify_ruby.rb +0 -16
- data/examples/rules/02_prefer_claude_for_code.rb +0 -19
- data/examples/rules/03_gate_prompt_length.rb +0 -19
- data/examples/rules/04_tool_selection.rb +0 -41
- data/examples/rules/README.md +0 -30
- data/examples/run_all.sh +0 -294
- data/examples/tools/word_count_tool.rb +0 -30
- data/lib/AGENTS.md +0 -57
- data/lib/aia/model_switch_handler.rb +0 -100
- data/mcp_servers/README.md +0 -110
- data/mcp_servers/apple-mcp.json +0 -8
- data/mcp_servers/filesystem.json +0 -9
- data/mcp_servers/mcp_server_chart.json +0 -11
- data/mcp_servers/playwright_one.json +0 -8
- data/mcp_servers/playwright_server_definition.json +0 -9
- data/mcp_servers/playwright_two.json +0 -8
- data/mcp_servers/tavily_mcp_server.json +0 -8
- data/mkdocs.yml +0 -169
data/docs/guides/local-models.md
DELETED
|
@@ -1,306 +0,0 @@
|
|
|
1
|
-
# Local Models Guide
|
|
2
|
-
|
|
3
|
-
Complete guide to using Ollama and LM Studio with AIA for local AI processing.
|
|
4
|
-
|
|
5
|
-
## Why Use Local Models?
|
|
6
|
-
|
|
7
|
-
### Benefits
|
|
8
|
-
|
|
9
|
-
- 🔒 **Privacy**: All processing happens on your machine
|
|
10
|
-
- 💰 **Cost**: No API fees
|
|
11
|
-
- 🚀 **Speed**: No network latency
|
|
12
|
-
- 📡 **Offline**: Works without internet
|
|
13
|
-
- 🔧 **Control**: Choose exact model and parameters
|
|
14
|
-
- 📦 **Unlimited**: No rate limits or quotas
|
|
15
|
-
|
|
16
|
-
### Use Cases
|
|
17
|
-
|
|
18
|
-
- Processing confidential business data
|
|
19
|
-
- Working with personal information
|
|
20
|
-
- Development and testing
|
|
21
|
-
- High-volume batch processing
|
|
22
|
-
- Air-gapped environments
|
|
23
|
-
- Learning and experimentation
|
|
24
|
-
|
|
25
|
-
## Ollama Setup
|
|
26
|
-
|
|
27
|
-
### Installation
|
|
28
|
-
|
|
29
|
-
```bash
|
|
30
|
-
# macOS
|
|
31
|
-
brew install ollama
|
|
32
|
-
|
|
33
|
-
# Linux
|
|
34
|
-
curl -fsSL https://ollama.ai/install.sh | sh
|
|
35
|
-
|
|
36
|
-
# Windows
|
|
37
|
-
# Download installer from https://ollama.ai
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
### Model Management
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
# List available models
|
|
44
|
-
ollama list
|
|
45
|
-
|
|
46
|
-
# Pull new models
|
|
47
|
-
ollama pull llama3.2
|
|
48
|
-
ollama pull mistral
|
|
49
|
-
ollama pull codellama
|
|
50
|
-
|
|
51
|
-
# Remove models
|
|
52
|
-
ollama rm model-name
|
|
53
|
-
|
|
54
|
-
# Show model info
|
|
55
|
-
ollama show llama3.2
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
### Using with AIA
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
# Basic usage - prefix with 'ollama/'
|
|
62
|
-
aia --model ollama/llama3.2 my_prompt
|
|
63
|
-
|
|
64
|
-
# Chat mode
|
|
65
|
-
aia --chat --model ollama/mistral
|
|
66
|
-
|
|
67
|
-
# Batch processing
|
|
68
|
-
for file in *.md; do
|
|
69
|
-
aia --model ollama/llama3.2 summarize "$file"
|
|
70
|
-
done
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
### Recommended Ollama Models
|
|
74
|
-
|
|
75
|
-
#### General Purpose
|
|
76
|
-
- `llama3.2` - Versatile, good quality
|
|
77
|
-
- `llama3.2:70b` - Higher quality, slower
|
|
78
|
-
- `mistral` - Fast, efficient
|
|
79
|
-
|
|
80
|
-
#### Code
|
|
81
|
-
- `qwen2.5-coder` - Excellent for code
|
|
82
|
-
- `codellama` - Code-focused
|
|
83
|
-
- `deepseek-coder` - Programming tasks
|
|
84
|
-
|
|
85
|
-
#### Specialized
|
|
86
|
-
- `mixtral` - High performance
|
|
87
|
-
- `phi3` - Small, efficient
|
|
88
|
-
- `gemma2` - Google's open model
|
|
89
|
-
|
|
90
|
-
## LM Studio Setup
|
|
91
|
-
|
|
92
|
-
### Installation
|
|
93
|
-
|
|
94
|
-
1. Download from https://lmstudio.ai
|
|
95
|
-
2. Install the application
|
|
96
|
-
3. Launch LM Studio
|
|
97
|
-
|
|
98
|
-
### Model Management
|
|
99
|
-
|
|
100
|
-
1. Click "🔍 Search" tab
|
|
101
|
-
2. Browse or search for models
|
|
102
|
-
3. Click download button
|
|
103
|
-
4. Wait for download to complete
|
|
104
|
-
|
|
105
|
-
### Starting Local Server
|
|
106
|
-
|
|
107
|
-
1. Click "💻 Local Server" tab
|
|
108
|
-
2. Select loaded model from dropdown
|
|
109
|
-
3. Click "Start Server"
|
|
110
|
-
4. Note the endpoint (default: http://localhost:1234/v1)
|
|
111
|
-
|
|
112
|
-
### Using with AIA
|
|
113
|
-
|
|
114
|
-
```bash
|
|
115
|
-
# Prefix model name with 'lms/'
|
|
116
|
-
aia --model lms/qwen/qwen3-coder-30b my_prompt
|
|
117
|
-
|
|
118
|
-
# Chat mode
|
|
119
|
-
aia --chat --model lms/llama-3.2-3b-instruct
|
|
120
|
-
|
|
121
|
-
# AIA validates model names
|
|
122
|
-
# Error shows available models if name is wrong
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
### Popular LM Studio Models
|
|
126
|
-
|
|
127
|
-
- `lmsys/vicuna-7b` - Conversation
|
|
128
|
-
- `TheBloke/Llama-2-7B-Chat-GGUF` - Chat
|
|
129
|
-
- `TheBloke/CodeLlama-7B-GGUF` - Code
|
|
130
|
-
- `qwen/qwen3-coder-30b` - Advanced coding
|
|
131
|
-
|
|
132
|
-
## Configuration
|
|
133
|
-
|
|
134
|
-
### Environment Variables
|
|
135
|
-
|
|
136
|
-
```bash
|
|
137
|
-
# Ollama custom endpoint
|
|
138
|
-
export OLLAMA_API_BASE=http://localhost:11434
|
|
139
|
-
|
|
140
|
-
# LM Studio custom endpoint
|
|
141
|
-
export LMS_API_BASE=http://localhost:1234/v1
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
### Config File
|
|
145
|
-
|
|
146
|
-
```yaml
|
|
147
|
-
# ~/.config/aia/aia.yml
|
|
148
|
-
models:
|
|
149
|
-
- name: ollama/llama3.2
|
|
150
|
-
|
|
151
|
-
# Or for LM Studio
|
|
152
|
-
models:
|
|
153
|
-
- name: lms/qwen/qwen3-coder-30b
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
### In Prompts
|
|
157
|
-
|
|
158
|
-
```
|
|
159
|
-
/config model = ollama/mistral
|
|
160
|
-
/config temperature = 0.7
|
|
161
|
-
|
|
162
|
-
Your prompt here...
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
## Listing Models
|
|
166
|
-
|
|
167
|
-
### In Chat Session
|
|
168
|
-
|
|
169
|
-
```bash
|
|
170
|
-
aia --model ollama/llama3.2 --chat
|
|
171
|
-
> /models
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
**Ollama Output:**
|
|
175
|
-
```
|
|
176
|
-
Local LLM Models:
|
|
177
|
-
|
|
178
|
-
Ollama Models (http://localhost:11434):
|
|
179
|
-
------------------------------------------------------------
|
|
180
|
-
- ollama/llama3.2:latest (size: 2.0 GB, modified: 2024-10-01)
|
|
181
|
-
- ollama/mistral:latest (size: 4.1 GB, modified: 2024-09-28)
|
|
182
|
-
|
|
183
|
-
2 Ollama model(s) available
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
**LM Studio Output:**
|
|
187
|
-
```
|
|
188
|
-
Local LLM Models:
|
|
189
|
-
|
|
190
|
-
LM Studio Models (http://localhost:1234/v1):
|
|
191
|
-
------------------------------------------------------------
|
|
192
|
-
- lms/qwen/qwen3-coder-30b
|
|
193
|
-
- lms/llama-3.2-3b-instruct
|
|
194
|
-
|
|
195
|
-
2 LM Studio model(s) available
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
## Advanced Usage
|
|
199
|
-
|
|
200
|
-
### Mixed Local/Cloud Models
|
|
201
|
-
|
|
202
|
-
```bash
|
|
203
|
-
# Compare local and cloud responses
|
|
204
|
-
aia --model ollama/llama3.2,gpt-4o-mini,claude-3-sonnet analysis_prompt
|
|
205
|
-
|
|
206
|
-
# Get consensus
|
|
207
|
-
aia --model ollama/llama3.2,ollama/mistral,gpt-4 --consensus decision_prompt
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
### Local-First Workflow
|
|
211
|
-
|
|
212
|
-
```bash
|
|
213
|
-
# 1. Process with local model (private)
|
|
214
|
-
aia --model ollama/llama3.2 --output draft.md sensitive_data.txt
|
|
215
|
-
|
|
216
|
-
# 2. Review and sanitize draft.md manually
|
|
217
|
-
|
|
218
|
-
# 3. Polish with cloud model
|
|
219
|
-
aia --model gpt-4 --include draft.md final_output
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
### Cost Optimization
|
|
223
|
-
|
|
224
|
-
```bash
|
|
225
|
-
# Bulk tasks with local model
|
|
226
|
-
for i in {1..1000}; do
|
|
227
|
-
aia --model ollama/mistral --output "result_$i.md" process "input_$i.txt"
|
|
228
|
-
done
|
|
229
|
-
|
|
230
|
-
# No API costs!
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
## Troubleshooting
|
|
234
|
-
|
|
235
|
-
### Ollama Issues
|
|
236
|
-
|
|
237
|
-
**Problem:** "Cannot connect to Ollama"
|
|
238
|
-
```bash
|
|
239
|
-
# Check if Ollama is running
|
|
240
|
-
ollama list
|
|
241
|
-
|
|
242
|
-
# Start Ollama service (if needed)
|
|
243
|
-
ollama serve
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
**Problem:** "Model not found"
|
|
247
|
-
```bash
|
|
248
|
-
# List installed models
|
|
249
|
-
ollama list
|
|
250
|
-
|
|
251
|
-
# Pull missing model
|
|
252
|
-
ollama pull llama3.2
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
### LM Studio Issues
|
|
256
|
-
|
|
257
|
-
**Problem:** "Cannot connect to LM Studio"
|
|
258
|
-
1. Ensure LM Studio is running
|
|
259
|
-
2. Check local server is started
|
|
260
|
-
3. Verify endpoint in settings
|
|
261
|
-
|
|
262
|
-
**Problem:** "Model validation failed"
|
|
263
|
-
- Check exact model name in LM Studio
|
|
264
|
-
- Ensure model is loaded (not just downloaded)
|
|
265
|
-
- Use full model path with `lms/` prefix
|
|
266
|
-
|
|
267
|
-
**Problem:** "Model not listed"
|
|
268
|
-
1. Load model in LM Studio
|
|
269
|
-
2. Start local server
|
|
270
|
-
3. Run `/models` directive
|
|
271
|
-
|
|
272
|
-
### Performance Issues
|
|
273
|
-
|
|
274
|
-
**Slow responses:**
|
|
275
|
-
- Use smaller models (7B instead of 70B)
|
|
276
|
-
- Reduce max_tokens
|
|
277
|
-
- Check system resources (CPU/RAM/GPU)
|
|
278
|
-
|
|
279
|
-
**High memory usage:**
|
|
280
|
-
- Close other applications
|
|
281
|
-
- Use quantized models (Q4, Q5)
|
|
282
|
-
- Try smaller model variants
|
|
283
|
-
|
|
284
|
-
## Best Practices
|
|
285
|
-
|
|
286
|
-
### Security
|
|
287
|
-
✅ Keep local models for sensitive data
|
|
288
|
-
✅ Use cloud models for general tasks
|
|
289
|
-
✅ Review outputs before sharing externally
|
|
290
|
-
|
|
291
|
-
### Performance
|
|
292
|
-
✅ Use appropriate model size for task
|
|
293
|
-
✅ Leverage GPU if available
|
|
294
|
-
✅ Cache common responses
|
|
295
|
-
|
|
296
|
-
### Cost Management
|
|
297
|
-
✅ Use local models for development/testing
|
|
298
|
-
✅ Use local models for high-volume processing
|
|
299
|
-
✅ Reserve cloud models for critical tasks
|
|
300
|
-
|
|
301
|
-
## Related Documentation
|
|
302
|
-
|
|
303
|
-
- [Models Guide](models.md)
|
|
304
|
-
- [Configuration](../configuration.md)
|
|
305
|
-
- [Chat Mode](chat.md)
|
|
306
|
-
- [CLI Reference](../cli-reference.md)
|
|
@@ -1,335 +0,0 @@
|
|
|
1
|
-
# Migrating Prompts
|
|
2
|
-
|
|
3
|
-
AIA includes a migration tool for converting prompt files from the legacy prompt_manager v0.5.8 format to the v1.0.0 format. This guide covers the migration process, what changes, and how to handle files that need manual attention.
|
|
4
|
-
|
|
5
|
-
## Why Migrate?
|
|
6
|
-
|
|
7
|
-
The prompt_manager gem moved from a two-file format (`.txt` + `.json`) with `[PLACEHOLDER]` syntax to a single `.md` file with YAML front matter and ERB parameters. The new format provides:
|
|
8
|
-
|
|
9
|
-
- **Self-contained prompts** — metadata, parameters, and body in one file
|
|
10
|
-
- **Standard ERB** — `<%= param %>` instead of custom `[PARAM]` syntax
|
|
11
|
-
- **YAML front matter** — structured configuration instead of `/` directives
|
|
12
|
-
- **Markdown body** — native rendering support in editors and documentation tools
|
|
13
|
-
|
|
14
|
-
## Format Comparison
|
|
15
|
-
|
|
16
|
-
### Old Format (v0.5.8)
|
|
17
|
-
|
|
18
|
-
Two files per prompt:
|
|
19
|
-
|
|
20
|
-
**`my_prompt.md`**
|
|
21
|
-
```
|
|
22
|
-
# ~/.prompts/my_prompt.md
|
|
23
|
-
# Desc: Summarize the given document
|
|
24
|
-
/config temperature 0.3
|
|
25
|
-
/include shared_context.md
|
|
26
|
-
|
|
27
|
-
Summarize the following [DOCUMENT_TYPE] document:
|
|
28
|
-
|
|
29
|
-
[CONTENT]
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
**`my_prompt.json`** (parameter history)
|
|
33
|
-
```json
|
|
34
|
-
{
|
|
35
|
-
"[DOCUMENT_TYPE]": ["report", "article", "paper"],
|
|
36
|
-
"[CONTENT]": ["..."]
|
|
37
|
-
}
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
### New Format (v1.0.0)
|
|
41
|
-
|
|
42
|
-
Single file:
|
|
43
|
-
|
|
44
|
-
**`my_prompt.md`** (same filename, single file now)
|
|
45
|
-
```markdown
|
|
46
|
-
---
|
|
47
|
-
name: my_prompt
|
|
48
|
-
description: Summarize the given document
|
|
49
|
-
temperature: 0.3
|
|
50
|
-
parameters:
|
|
51
|
-
document_type: paper
|
|
52
|
-
content: null
|
|
53
|
-
---
|
|
54
|
-
|
|
55
|
-
<%= include('shared_context.md') %>
|
|
56
|
-
|
|
57
|
-
Summarize the following <%= document_type %> document:
|
|
58
|
-
|
|
59
|
-
<%= content %>
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
## Running the Migration
|
|
63
|
-
|
|
64
|
-
The migration script is at `bin/migrate_prompts`. It requires no external dependencies beyond Ruby's standard library.
|
|
65
|
-
|
|
66
|
-
### Basic Usage
|
|
67
|
-
|
|
68
|
-
```bash
|
|
69
|
-
# Scan the entire prompts directory (uses $AIA_PROMPTS__DIR or ~/.prompts)
|
|
70
|
-
bin/migrate_prompts
|
|
71
|
-
|
|
72
|
-
# Preview changes without modifying files
|
|
73
|
-
bin/migrate_prompts --dry-run
|
|
74
|
-
|
|
75
|
-
# Migrate with detailed output
|
|
76
|
-
bin/migrate_prompts --verbose
|
|
77
|
-
|
|
78
|
-
# Migrate specific files or directories
|
|
79
|
-
bin/migrate_prompts ~/.prompts/development/
|
|
80
|
-
bin/migrate_prompts ~/.prompts/code_review.md ~/.prompts/debug_help.md
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
### CLI Options
|
|
84
|
-
|
|
85
|
-
| Option | Description |
|
|
86
|
-
|--------|-------------|
|
|
87
|
-
| `--dry-run` | Show what would change without modifying any files |
|
|
88
|
-
| `--verbose` | Show detailed transformation info for each file |
|
|
89
|
-
| `--force` | Overwrite existing `.md` files (default: skip if `.md` exists) |
|
|
90
|
-
| `--reprocess` | Re-examine `*.txt-review` files and recover those that now pass |
|
|
91
|
-
| `-h`, `--help` | Show usage help |
|
|
92
|
-
|
|
93
|
-
### Environment
|
|
94
|
-
|
|
95
|
-
The script uses `AIA_PROMPTS__DIR` to locate the prompts directory. If unset, it defaults to `~/.prompts`.
|
|
96
|
-
|
|
97
|
-
```bash
|
|
98
|
-
# Use a custom prompts directory
|
|
99
|
-
AIA_PROMPTS__DIR=~/my-prompts bin/migrate_prompts --dry-run
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
## What Gets Migrated
|
|
103
|
-
|
|
104
|
-
### Placeholders
|
|
105
|
-
|
|
106
|
-
Standard `[PLACEHOLDER]` tokens become ERB expressions:
|
|
107
|
-
|
|
108
|
-
| Old | New |
|
|
109
|
-
|-----|-----|
|
|
110
|
-
| `[TOPIC]` | `<%= topic %>` |
|
|
111
|
-
| `[FILE_NAME]` | `<%= file_name %>` |
|
|
112
|
-
| `[TECH STACK]` | `<%= tech_stack %>` (spaces normalized to underscores) |
|
|
113
|
-
|
|
114
|
-
### Directives
|
|
115
|
-
|
|
116
|
-
Prompt directives are migrated to YAML front matter or ERB calls:
|
|
117
|
-
|
|
118
|
-
| Old Directive | New Location |
|
|
119
|
-
|---------------|--------------|
|
|
120
|
-
| `/config temperature 0.3` | `temperature: 0.3` in YAML |
|
|
121
|
-
| `/config top_p 0.9` | `top_p: 0.9` in YAML |
|
|
122
|
-
| `/temp 0.5` | `temperature: 0.5` in YAML |
|
|
123
|
-
| `/topp 0.8` | `top_p: 0.8` in YAML |
|
|
124
|
-
| `/next follow_up` | `next: follow_up` in YAML |
|
|
125
|
-
| `/pipeline step1, step2` | `pipeline: [step1, step2]` in YAML |
|
|
126
|
-
| `/include file.md` | `<%= include('file.md') %>` in body |
|
|
127
|
-
| `/shell command` | `<%= system('command') %>` in body |
|
|
128
|
-
| `/ruby expression` | `<%= expression %>` in body |
|
|
129
|
-
| `/backend ...` | Silently removed (deprecated) |
|
|
130
|
-
|
|
131
|
-
### Comments
|
|
132
|
-
|
|
133
|
-
Lines beginning with `#` (outside of code fences and ERB blocks) are converted to HTML comments:
|
|
134
|
-
|
|
135
|
-
```
|
|
136
|
-
# Old format: this is a comment
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
Becomes:
|
|
140
|
-
|
|
141
|
-
```html
|
|
142
|
-
<!-- this is a comment -->
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
Multi-line comment blocks are grouped:
|
|
146
|
-
|
|
147
|
-
```html
|
|
148
|
-
<!--
|
|
149
|
-
First line of comment
|
|
150
|
-
Second line of comment
|
|
151
|
-
-->
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
Comments inside code fences (` ``` `) and multi-line ERB blocks (`<% ... %>`) are preserved as-is.
|
|
155
|
-
|
|
156
|
-
### Metadata
|
|
157
|
-
|
|
158
|
-
The script extracts metadata from the old format's header conventions:
|
|
159
|
-
|
|
160
|
-
- **File path comments** (`# ~/.prompts/name.md`) — removed
|
|
161
|
-
- **Description lines** (`# Desc: ...`) — moved to `description:` in YAML front matter
|
|
162
|
-
- **Prompt name** — derived from the filename (e.g., `code_review.md` → `name: code_review`)
|
|
163
|
-
|
|
164
|
-
### Parameter History
|
|
165
|
-
|
|
166
|
-
If a `.json` file exists alongside the `.md` file, the most recent value for each parameter is used as the default in the YAML `parameters:` block:
|
|
167
|
-
|
|
168
|
-
```yaml
|
|
169
|
-
parameters:
|
|
170
|
-
document_type: paper # last value from JSON history
|
|
171
|
-
content: null # no history available
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
### Content After `__END__`
|
|
175
|
-
|
|
176
|
-
Content below an `__END__` marker is wrapped in an HTML comment at the end of the `.md` file:
|
|
177
|
-
|
|
178
|
-
```html
|
|
179
|
-
<!--
|
|
180
|
-
Original content that was below __END__
|
|
181
|
-
-->
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
## Flagged Files
|
|
185
|
-
|
|
186
|
-
Files that contain constructs requiring manual review are renamed to `*.txt-review` instead of being migrated. The most common reasons a file gets flagged:
|
|
187
|
-
|
|
188
|
-
- **Code fences** (` ``` `) — the script cannot reliably distinguish between code fence content and prompt body text that might contain placeholders
|
|
189
|
-
- **Placeholders inside ERB blocks** — `[PARAM]` tokens within `<% ... %>` need manual conversion to Ruby variables
|
|
190
|
-
- **Ambiguous bracket expressions** — bracket content that looks like a placeholder but doesn't match the clean `[ALL_CAPS]` pattern
|
|
191
|
-
|
|
192
|
-
### Reviewing Flagged Files
|
|
193
|
-
|
|
194
|
-
After the initial migration, check the flagged files:
|
|
195
|
-
|
|
196
|
-
```bash
|
|
197
|
-
# List all flagged files
|
|
198
|
-
find ~/.prompts -name '*.txt-review'
|
|
199
|
-
|
|
200
|
-
# Preview what the migration would produce
|
|
201
|
-
bin/migrate_prompts --dry-run --verbose ~/.prompts/my_prompt.txt-review
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
For each flagged file, you have three options:
|
|
205
|
-
|
|
206
|
-
1. **Reprocess** — if the issue was transient, use `--reprocess` to try again
|
|
207
|
-
2. **Manual conversion** — create the `.md` file by hand following the new format
|
|
208
|
-
3. **Leave as-is** — flagged files don't affect AIA's operation with existing prompts
|
|
209
|
-
|
|
210
|
-
### Reprocessing Flagged Files
|
|
211
|
-
|
|
212
|
-
The `--reprocess` option re-examines all `*.txt-review` files. Files that now pass validation are renamed back to `*.txt` and migrated to `*.md`:
|
|
213
|
-
|
|
214
|
-
```bash
|
|
215
|
-
# Preview which files would be recovered
|
|
216
|
-
bin/migrate_prompts --reprocess --dry-run
|
|
217
|
-
|
|
218
|
-
# Recover files that now pass
|
|
219
|
-
bin/migrate_prompts --reprocess
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
The reprocess summary shows how many files were recovered versus still flagged:
|
|
223
|
-
|
|
224
|
-
```
|
|
225
|
-
Reprocess summary:
|
|
226
|
-
Recovered: 22 files (*.txt-review → *.txt → *.md)
|
|
227
|
-
Still flagged: 19 files (unchanged)
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
## Step-by-Step Migration Workflow
|
|
231
|
-
|
|
232
|
-
### 1. Preview the Migration
|
|
233
|
-
|
|
234
|
-
Start with a dry run to understand the scope of changes:
|
|
235
|
-
|
|
236
|
-
```bash
|
|
237
|
-
bin/migrate_prompts --dry-run --verbose
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
Review the output. Note how many files will be migrated, flagged, or skipped.
|
|
241
|
-
|
|
242
|
-
### 2. Run the Migration
|
|
243
|
-
|
|
244
|
-
```bash
|
|
245
|
-
bin/migrate_prompts --verbose
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
The script creates `.md` files alongside the original `.txt` files. It does not delete the originals.
|
|
249
|
-
|
|
250
|
-
### 3. Review the Results
|
|
251
|
-
|
|
252
|
-
```bash
|
|
253
|
-
# Check the summary counts
|
|
254
|
-
# Verify a few migrated files look correct
|
|
255
|
-
cat ~/.prompts/my_prompt.md
|
|
256
|
-
|
|
257
|
-
# List flagged files
|
|
258
|
-
find ~/.prompts -name '*.txt-review'
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
### 4. Reprocess Flagged Files
|
|
262
|
-
|
|
263
|
-
```bash
|
|
264
|
-
bin/migrate_prompts --reprocess --dry-run
|
|
265
|
-
bin/migrate_prompts --reprocess
|
|
266
|
-
```
|
|
267
|
-
|
|
268
|
-
### 5. Handle Remaining Flagged Files
|
|
269
|
-
|
|
270
|
-
For files still flagged after reprocessing, create `.md` versions manually. Common patterns:
|
|
271
|
-
|
|
272
|
-
**Files with outer ` ```markdown ` wrappers** — strip the outer fence, keep nested fences, extract metadata into YAML front matter.
|
|
273
|
-
|
|
274
|
-
**Files with placeholders inside ERB** — convert `[PARAM]` to Ruby variable references inside the ERB block:
|
|
275
|
-
|
|
276
|
-
```ruby
|
|
277
|
-
# Old
|
|
278
|
-
<% path = '[MODEL_FILENAME]' %>
|
|
279
|
-
|
|
280
|
-
# New
|
|
281
|
-
<% path = model_filename %>
|
|
282
|
-
```
|
|
283
|
-
|
|
284
|
-
**Files with `__END__` containing code fences** — wrap the post-`__END__` content in HTML comments or restructure as needed.
|
|
285
|
-
|
|
286
|
-
### 6. Clean Up Originals
|
|
287
|
-
|
|
288
|
-
Once you've verified the migration is correct, remove the old files:
|
|
289
|
-
|
|
290
|
-
```bash
|
|
291
|
-
# Remove original .txt files that have corresponding .md files
|
|
292
|
-
find ~/.prompts -name '*.txt' -exec sh -c '
|
|
293
|
-
for f; do
|
|
294
|
-
md="${f%.txt}.md"
|
|
295
|
-
[ -f "$md" ] && rm "$f"
|
|
296
|
-
done
|
|
297
|
-
' _ {} +
|
|
298
|
-
|
|
299
|
-
# Remove .json history files
|
|
300
|
-
find ~/.prompts -name '*.json' -delete
|
|
301
|
-
```
|
|
302
|
-
|
|
303
|
-
## Troubleshooting
|
|
304
|
-
|
|
305
|
-
### "No .txt files found"
|
|
306
|
-
|
|
307
|
-
The script couldn't find any `.txt` files in the prompts directory. Verify the path:
|
|
308
|
-
|
|
309
|
-
```bash
|
|
310
|
-
echo $AIA_PROMPTS__DIR
|
|
311
|
-
ls ~/.prompts/*.txt
|
|
312
|
-
```
|
|
313
|
-
|
|
314
|
-
### File skipped because .md already exists
|
|
315
|
-
|
|
316
|
-
By default, the script skips files that already have a corresponding `.md` file. Use `--force` to overwrite:
|
|
317
|
-
|
|
318
|
-
```bash
|
|
319
|
-
bin/migrate_prompts --force ~/.prompts/my_prompt.md
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
### Unrecognized directive warnings
|
|
323
|
-
|
|
324
|
-
Directives that the script doesn't know how to convert are preserved in the body as-is and reported as warnings. Review these manually after migration.
|
|
325
|
-
|
|
326
|
-
### Placeholder not converted
|
|
327
|
-
|
|
328
|
-
The script only converts clean placeholders matching `[ALL_CAPS_WITH_UNDERSCORES]`. Other bracket patterns (e.g., `[camelCase]`, `[with:colons]`) are left unchanged. This is intentional to avoid converting code that happens to contain brackets.
|
|
329
|
-
|
|
330
|
-
## Related Documentation
|
|
331
|
-
|
|
332
|
-
- [Prompt Management](../prompt_management.md) — organizing and managing your prompt collection
|
|
333
|
-
- [Advanced Prompting](../advanced-prompting.md) — ERB templates and dynamic prompts
|
|
334
|
-
- [Workflows & Pipelines](../workflows-and-pipelines.md) — multi-step prompt sequences
|
|
335
|
-
- [Configuration](../configuration.md) — AIA configuration reference
|