aia 2.0.0.0.pre.beta2 → 2.0.1

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.
Files changed (227) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +152 -223
  3. data/README.md +41 -18
  4. data/bin/aia +8 -3
  5. data/lib/aia/aia_completion.bash +2 -3
  6. data/lib/aia/aia_completion.fish +6 -5
  7. data/lib/aia/aia_completion.zsh +2 -3
  8. data/lib/aia/chat_loop.rb +16 -14
  9. data/lib/aia/config/cli_parser.rb +123 -91
  10. data/lib/aia/config/defaults.yml +18 -40
  11. data/lib/aia/config/mcp_parser.rb +30 -36
  12. data/lib/aia/config/model_spec.rb +8 -14
  13. data/lib/aia/config/validator.rb +102 -103
  14. data/lib/aia/config/value_caster.rb +76 -0
  15. data/lib/aia/config.rb +70 -53
  16. data/lib/aia/crew.rb +29 -19
  17. data/lib/aia/debate_handler.rb +27 -10
  18. data/lib/aia/directives/configuration_directives.rb +55 -14
  19. data/lib/aia/directives/context_directives.rb +24 -12
  20. data/lib/aia/directives/execution_directives.rb +18 -23
  21. data/lib/aia/directives/model_directives.rb +41 -104
  22. data/lib/aia/directives/utility_directives.rb +16 -17
  23. data/lib/aia/directives/web_and_file_directives.rb +21 -14
  24. data/lib/aia/fact_asserter.rb +3 -3
  25. data/lib/aia/history_transfer.rb +64 -24
  26. data/lib/aia/logger.rb +14 -46
  27. data/lib/aia/mcp_config_normalizer.rb +27 -14
  28. data/lib/aia/mcp_connection_manager.rb +181 -184
  29. data/lib/aia/mcp_discovery.rb +43 -15
  30. data/lib/aia/mcp_grouper.rb +2 -1
  31. data/lib/aia/mcp_server_config.rb +20 -2
  32. data/lib/aia/mcp_utility.rb +24 -19
  33. data/lib/aia/mention_router.rb +15 -2
  34. data/lib/aia/modality_query.rb +36 -0
  35. data/lib/aia/model_alias_registry.rb +11 -11
  36. data/lib/aia/model_registry.rb +75 -0
  37. data/lib/aia/network_builder.rb +8 -7
  38. data/lib/aia/patches/mcp_stdio_stderr.rb +102 -0
  39. data/lib/aia/patches/ruby_llm_streaming_error.rb +21 -4
  40. data/lib/aia/patches/ruby_llm_tool_param_compat.rb +18 -0
  41. data/lib/aia/pipeline_orchestrator.rb +71 -38
  42. data/lib/aia/prompt_decomposer.rb +1 -1
  43. data/lib/aia/prompt_handler.rb +56 -29
  44. data/lib/aia/provider_registry.rb +105 -0
  45. data/lib/aia/robot_builder.rb +1 -1
  46. data/lib/aia/robot_factory.rb +67 -63
  47. data/lib/aia/robot_sync.rb +79 -0
  48. data/lib/aia/role_catalog.rb +89 -0
  49. data/lib/aia/session.rb +25 -11
  50. data/lib/aia/skill_utils.rb +60 -19
  51. data/lib/aia/spawn_handler.rb +16 -4
  52. data/lib/aia/spawn_spec_parser.rb +6 -7
  53. data/lib/aia/special_mode_handler.rb +28 -25
  54. data/lib/aia/speech.rb +70 -34
  55. data/lib/aia/startup_coordinator.rb +17 -92
  56. data/lib/aia/streaming_runner.rb +10 -2
  57. data/lib/aia/system_prompt_assembler.rb +12 -11
  58. data/lib/aia/task_board.rb +60 -0
  59. data/lib/aia/tool_approver.rb +205 -0
  60. data/lib/aia/tool_filter.rb +1 -10
  61. data/lib/aia/tool_filter_strategy.rb +12 -1
  62. data/lib/aia/tool_introspection.rb +9 -1
  63. data/lib/aia/tool_loader.rb +67 -33
  64. data/lib/aia/tool_utility.rb +6 -5
  65. data/lib/aia/tools/delegate_to_foreman_tool.rb +6 -4
  66. data/lib/aia/tools/recruit_robot_tool.rb +12 -12
  67. data/lib/aia/tools/reskill_robot_tool.rb +7 -7
  68. data/lib/aia/tools/task_board_tool.rb +16 -16
  69. data/lib/aia/trakflow_bridge.rb +14 -8
  70. data/lib/aia/turn_state.rb +31 -8
  71. data/lib/aia/ui_presenter.rb +16 -0
  72. data/lib/aia/utility.rb +6 -24
  73. data/lib/aia/variable_input_collector.rb +0 -3
  74. data/lib/aia/verification_network.rb +9 -10
  75. data/lib/aia/version.rb +1 -9
  76. data/lib/aia.rb +34 -8
  77. metadata +20 -161
  78. data/.better-commits.json +0 -150
  79. data/.config/tocer/configuration.yml +0 -6
  80. data/.envrc +0 -19
  81. data/.loki +0 -11
  82. data/.reek.yml +0 -160
  83. data/.rubocop.yml +0 -116
  84. data/.rubocop_strict.yml +0 -15
  85. data/.version +0 -1
  86. data/COMMITS.md +0 -196
  87. data/IMPLEMENTATION_PLAN.md +0 -506
  88. data/Rakefile +0 -47
  89. data/_typos.toml +0 -10
  90. data/aia.gemspec +0 -92
  91. data/architecture_review.md +0 -314
  92. data/config/aia.yml +0 -13
  93. data/docs/AGENTS.md +0 -40
  94. data/docs/advanced-prompting.md +0 -814
  95. data/docs/assets/images/aia.png +0 -0
  96. data/docs/cli-reference.md +0 -1241
  97. data/docs/configuration.md +0 -747
  98. data/docs/contributing.md +0 -386
  99. data/docs/directives-reference.md +0 -1145
  100. data/docs/examples/index.md +0 -277
  101. data/docs/examples/mcp/index.md +0 -475
  102. data/docs/examples/prompts/analysis/index.md +0 -78
  103. data/docs/examples/prompts/automation/index.md +0 -109
  104. data/docs/examples/prompts/development/index.md +0 -125
  105. data/docs/examples/prompts/index.md +0 -333
  106. data/docs/examples/prompts/learning/index.md +0 -127
  107. data/docs/examples/prompts/writing/index.md +0 -62
  108. data/docs/examples/tools/index.md +0 -282
  109. data/docs/faq.md +0 -578
  110. data/docs/guides/available-models.md +0 -366
  111. data/docs/guides/basic-usage.md +0 -478
  112. data/docs/guides/chat.md +0 -680
  113. data/docs/guides/crew.md +0 -239
  114. data/docs/guides/executable-prompts.md +0 -331
  115. data/docs/guides/first-prompt.md +0 -454
  116. data/docs/guides/getting-started.md +0 -455
  117. data/docs/guides/image-generation.md +0 -507
  118. data/docs/guides/index.md +0 -48
  119. data/docs/guides/local-models.md +0 -306
  120. data/docs/guides/migrate-prompts.md +0 -335
  121. data/docs/guides/models.md +0 -1017
  122. data/docs/guides/shared-tools.md +0 -254
  123. data/docs/guides/tools.md +0 -831
  124. data/docs/index.md +0 -259
  125. data/docs/installation.md +0 -274
  126. data/docs/mcp-integration.md +0 -603
  127. data/docs/prompt_management.md +0 -665
  128. data/docs/security.md +0 -674
  129. data/docs/special_projects_guide.md +0 -386
  130. data/docs/tools-and-mcp-examples.md +0 -1211
  131. data/docs/workflows-and-pipelines.md +0 -636
  132. data/examples/.gitignore +0 -2
  133. data/examples/00_setup_aia.sh +0 -111
  134. data/examples/01_basic_usage.sh +0 -23
  135. data/examples/02_frontmatter.sh +0 -33
  136. data/examples/03_shell_integration.sh +0 -55
  137. data/examples/04_erb_templating.sh +0 -56
  138. data/examples/05_shell_then_erb.sh +0 -38
  139. data/examples/06_prompt_chaining.sh +0 -59
  140. data/examples/07_pipeline.sh +0 -46
  141. data/examples/08_context_files.sh +0 -43
  142. data/examples/09_roles.sh +0 -67
  143. data/examples/10_stdin_piping.sh +0 -49
  144. data/examples/11_multi_model.sh +0 -65
  145. data/examples/12_token_usage.sh +0 -52
  146. data/examples/13_cost_tracking.sh +0 -68
  147. data/examples/14_output_file.sh +0 -91
  148. data/examples/15_parameters.sh +0 -68
  149. data/examples/16_directives.sh +0 -113
  150. data/examples/17_require_and_conditionals.sh +0 -68
  151. data/examples/18_tools.sh +0 -61
  152. data/examples/19_local_tools.sh +0 -34
  153. data/examples/20_mcp_servers.sh +0 -102
  154. data/examples/21_executable_prompts.sh +0 -78
  155. data/examples/22_chat_mode.sh +0 -217
  156. data/examples/23_verify.sh +0 -139
  157. data/examples/24_decompose.sh +0 -139
  158. data/examples/25_spawn.sh +0 -139
  159. data/examples/26_debate.sh +0 -97
  160. data/examples/27_mention_routing.sh +0 -157
  161. data/examples/28_model_switching.sh +0 -106
  162. data/examples/29_agent_harness.sh +0 -177
  163. data/examples/README.md +0 -321
  164. data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
  165. data/examples/aia_config.yml +0 -22
  166. data/examples/aia_config_orchestrator.yml +0 -45
  167. data/examples/aia_config_with_mcp.yml +0 -21
  168. data/examples/common.sh +0 -39
  169. data/examples/context/project_goals.md +0 -6
  170. data/examples/context/tech_stack.md +0 -7
  171. data/examples/directives/timestamp_directive.rb +0 -22
  172. data/examples/mcp/filesystem.json +0 -9
  173. data/examples/prompts_dir/analyze.md +0 -2
  174. data/examples/prompts_dir/brainstorm.md +0 -2
  175. data/examples/prompts_dir/conditional.md +0 -17
  176. data/examples/prompts_dir/creative.md +0 -4
  177. data/examples/prompts_dir/erbinfo.md +0 -5
  178. data/examples/prompts_dir/erbinfo_raw.md +0 -8
  179. data/examples/prompts_dir/evaluate.md +0 -2
  180. data/examples/prompts_dir/explain_joke.md +0 -1
  181. data/examples/prompts_dir/explain_recursion.md +0 -1
  182. data/examples/prompts_dir/fun_fact +0 -3
  183. data/examples/prompts_dir/greeting.md +0 -8
  184. data/examples/prompts_dir/greeting_required.md +0 -7
  185. data/examples/prompts_dir/hello.md +0 -1
  186. data/examples/prompts_dir/includes/ruby_facts.md +0 -4
  187. data/examples/prompts_dir/limerick.md +0 -1
  188. data/examples/prompts_dir/list_with_mcp.md +0 -3
  189. data/examples/prompts_dir/pick_best.md +0 -2
  190. data/examples/prompts_dir/project_summary +0 -12
  191. data/examples/prompts_dir/quiz_with_include.md +0 -6
  192. data/examples/prompts_dir/require_demo.md +0 -5
  193. data/examples/prompts_dir/roles/formal.md +0 -3
  194. data/examples/prompts_dir/roles/orchestrator.md +0 -21
  195. data/examples/prompts_dir/roles/pirate.md +0 -3
  196. data/examples/prompts_dir/shell_then_erb.md +0 -6
  197. data/examples/prompts_dir/sort_compare.md +0 -2
  198. data/examples/prompts_dir/summarize_context.md +0 -2
  199. data/examples/prompts_dir/sysinfo.md +0 -5
  200. data/examples/prompts_dir/sysinfo_raw.md +0 -8
  201. data/examples/prompts_dir/tagline.md +0 -1
  202. data/examples/prompts_dir/tell_joke.md +0 -1
  203. data/examples/prompts_dir/tell_joke_with_next.md +0 -4
  204. data/examples/prompts_dir/use_local_tool.md +0 -8
  205. data/examples/prompts_dir/use_tools.md +0 -8
  206. data/examples/prompts_dir/weather.md +0 -2
  207. data/examples/prompts_dir/whats_new.md +0 -2
  208. data/examples/prompts_dir/with_timestamp.md +0 -5
  209. data/examples/requirements/sinatra_taskflow_app.md +0 -139
  210. data/examples/rules/01_classify_ruby.rb +0 -16
  211. data/examples/rules/02_prefer_claude_for_code.rb +0 -19
  212. data/examples/rules/03_gate_prompt_length.rb +0 -19
  213. data/examples/rules/04_tool_selection.rb +0 -41
  214. data/examples/rules/README.md +0 -30
  215. data/examples/run_all.sh +0 -294
  216. data/examples/tools/word_count_tool.rb +0 -30
  217. data/lib/AGENTS.md +0 -57
  218. data/lib/aia/model_switch_handler.rb +0 -100
  219. data/mcp_servers/README.md +0 -110
  220. data/mcp_servers/apple-mcp.json +0 -8
  221. data/mcp_servers/filesystem.json +0 -9
  222. data/mcp_servers/mcp_server_chart.json +0 -11
  223. data/mcp_servers/playwright_one.json +0 -8
  224. data/mcp_servers/playwright_server_definition.json +0 -9
  225. data/mcp_servers/playwright_two.json +0 -8
  226. data/mcp_servers/tavily_mcp_server.json +0 -8
  227. data/mkdocs.yml +0 -169
@@ -1,1017 +0,0 @@
1
- # Working with Models
2
-
3
- AIA supports multiple AI models through the RubyLLM gem, allowing you to choose the best model for each task and even use multiple models simultaneously.
4
-
5
- ## Available Models
6
-
7
- ### List All Models
8
- ```bash
9
- # Show all available models
10
- aia --available-models
11
-
12
- # Filter by provider
13
- aia --available-models openai
14
- aia --available-models anthropic
15
- aia --available-models google
16
-
17
- # Filter by capability
18
- aia --available-models vision
19
- aia --available-models function_calling
20
- aia --available-models text_to_image
21
-
22
- # Complex filtering
23
- aia --available-models openai,gpt,4
24
- ```
25
-
26
- ### Model Information
27
- Each model listing includes:
28
- - **Model ID**: Exact name to use with `--model`
29
- - **Provider**: Company providing the model
30
- - **Context Window**: Maximum input/output length
31
- - **Input Cost**: Price per million input tokens
32
- - **Modalities**: Supported input/output types
33
- - **Capabilities**: Special features available
34
-
35
- ## Model Selection
36
-
37
- ### Single Model Usage
38
- ```bash
39
- # Use specific model
40
- aia --model gpt-4 my_prompt
41
- aia --model claude-3-sonnet code_review.py
42
- aia --model gemini-pro analyze_data.csv
43
-
44
- # Short model names (when unambiguous)
45
- aia --model gpt-4 my_prompt
46
- aia --model claude my_prompt
47
- aia --model gemini my_prompt
48
- ```
49
-
50
- ### Model Categories by Use Case
51
-
52
- #### Text Generation
53
- **Creative Writing**: High creativity, good with narratives
54
- - `gpt-4`: Excellent creative writing, good instruction following
55
- - `claude-3-sonnet`: Great for longer creative pieces
56
- - `gemini-pro`: Good balance of creativity and structure
57
-
58
- **Technical Writing**: Accuracy and precision focus
59
- - `gpt-4`: Strong technical accuracy
60
- - `claude-3-sonnet`: Excellent for documentation
61
- - `gpt-3.5-turbo`: Fast, cost-effective for simple technical tasks
62
-
63
- #### Code Analysis
64
- **Code Review**: Understanding existing code
65
- - `gpt-4`: Excellent code comprehension
66
- - `claude-3-sonnet`: Great at explaining complex code
67
- - `codellama-34b`: Specialized for code understanding
68
-
69
- **Code Generation**: Writing new code
70
- - `gpt-4`: High-quality code generation
71
- - `claude-3-sonnet`: Good at following coding standards
72
- - `codellama-7b`: Fast code completion
73
-
74
- #### Data Analysis
75
- **Statistical Analysis**: Working with numbers and data
76
- - `claude-3-sonnet`: Excellent analytical reasoning
77
- - `gpt-4`: Strong mathematical capabilities
78
- - `gemini-pro`: Good with structured data
79
-
80
- **Research**: Processing large amounts of information
81
- - `claude-3-sonnet`: Large context window, good summarization
82
- - `gpt-4`: Strong reasoning and synthesis
83
- - `claude-3-opus`: Highest quality analysis (more expensive)
84
-
85
- ## Multi-Model Operations
86
-
87
- ### Parallel Processing
88
- Run the same prompt with multiple models:
89
- ```bash
90
- # Compare outputs from different models
91
- aia --model "gpt-4,claude-3-sonnet,gemini-pro" my_prompt
92
-
93
- # Each model provides separate response
94
- ```
95
-
96
- ### Consensus Mode
97
- Get unified response from multiple models:
98
- ```bash
99
- # Enable consensus mode
100
- aia --model "gpt-4,claude-3-sonnet" --consensus my_prompt
101
-
102
- # Works in chat mode too
103
- aia --chat --model "gpt-4o-mini,gpt-3.5-turbo" --consensus
104
-
105
- # Models collaborate to provide single, refined response
106
- ```
107
-
108
- **Consensus Output Format:**
109
- ```
110
- from: gpt-4o-mini (consensus)
111
- Based on the insights from multiple AI models, here is a comprehensive answer that
112
- incorporates the best perspectives and resolves any contradictions...
113
- ```
114
-
115
- ### Individual Response Mode
116
-
117
- By default, each model provides its own separate response:
118
-
119
- ```bash
120
- # Default behavior - show individual responses
121
- aia --model "gpt-4o-mini,gpt-3.5-turbo,gpt-5-mini" my_prompt
122
-
123
- # Explicitly disable consensus
124
- aia --model "gpt-4o-mini,gpt-3.5-turbo" --no-consensus my_prompt
125
- ```
126
-
127
- **Individual Responses Output Format:**
128
- ```
129
- from: gpt-4o-mini
130
- Response from the first model...
131
-
132
- from: gpt-3.5-turbo
133
- Response from the second model...
134
-
135
- from: gpt-5-mini
136
- Response from the third model...
137
- ```
138
-
139
- ### Model Configuration Status
140
-
141
- View your current multi-model configuration using the `/model` directive:
142
-
143
- ```bash
144
- # In any prompt file or in chat session
145
- /model
146
- ```
147
-
148
- **Example Output:**
149
- ```
150
- Multi-Model Configuration:
151
- ==========================
152
- Model count: 3
153
- Primary model: gpt-4o-mini (used for consensus when --consensus flag is enabled)
154
- Consensus mode: false
155
-
156
- Model Details:
157
- --------------------------------------------------
158
- 1. gpt-4o-mini (primary)
159
- 2. gpt-3.5-turbo
160
- 3. gpt-5-mini
161
- ```
162
-
163
- **Multi-Model Features:**
164
- - **Primary Model**: The first model in the list serves as the consensus orchestrator
165
- - **Concurrent Processing**: All models run simultaneously for better performance
166
- - **Flexible Output**: Choose between individual responses or synthesized consensus
167
- - **Error Handling**: Invalid models are reported but don't prevent valid models from working
168
- - **Batch Mode Support**: Multi-model responses are properly formatted in output files
169
-
170
- ### Token Usage and Cost Tracking
171
-
172
- One of AIA's most powerful capabilities is real-time tracking of token usage and cost estimates across multiple models. This enables informed decisions about model selection based on both quality and cost.
173
-
174
- #### Enabling Token Tracking
175
-
176
- ```bash
177
- # Display token usage for each model
178
- aia my_prompt -m gpt-4o,claude-3-sonnet --tokens
179
-
180
- # Include cost estimates (automatically enables --tokens)
181
- aia my_prompt -m gpt-4o,claude-3-sonnet --cost
182
-
183
- # In chat mode with full tracking
184
- aia --chat -m gpt-4o,claude-3-sonnet,gemini-pro --cost
185
- ```
186
-
187
- #### Multi-Model Comparison with Metrics
188
-
189
- ```bash
190
- # Compare 3 models with cost tracking
191
- aia --chat -m gpt-4o,claude-3-5-sonnet,gemini-1.5-pro --cost
192
- ```
193
-
194
- **Example Output:**
195
- ```
196
- You: Explain the CAP theorem and its implications for distributed databases.
197
-
198
- from: gpt-4o
199
- The CAP theorem states that a distributed system can only guarantee two of three properties...
200
-
201
- from: claude-3-5-sonnet
202
- CAP theorem, proposed by Eric Brewer, describes fundamental trade-offs in distributed systems...
203
-
204
- from: gemini-1.5-pro
205
- The CAP theorem is a cornerstone principle in distributed computing that states...
206
-
207
- ┌─────────────────────────────────────────────────────────────────┐
208
- │ Model │ Input Tokens │ Output Tokens │ Cost │
209
- ├─────────────────────────────────────────────────────────────────┤
210
- │ gpt-4o │ 42 │ 287 │ $0.0068 │
211
- │ claude-3-5-sonnet │ 42 │ 312 │ $0.0053 │
212
- │ gemini-1.5-pro │ 42 │ 298 │ $0.0038 │
213
- └─────────────────────────────────────────────────────────────────┘
214
- Total: $0.0159
215
- ```
216
-
217
- #### Use Cases for Token/Cost Tracking
218
-
219
- | Use Case | Description |
220
- |----------|-------------|
221
- | **Budget Management** | Monitor API costs in real-time during development |
222
- | **Model Evaluation** | Compare quality vs. cost across different providers |
223
- | **Cost Optimization** | Identify the most cost-effective model for your tasks |
224
- | **Usage Auditing** | Track token consumption for billing and optimization |
225
- | **A/B Testing** | Compare model performance with objective metrics |
226
-
227
- #### Combining with Consensus Mode
228
-
229
- ```bash
230
- # Get consensus response with cost breakdown
231
- aia my_prompt -m gpt-4o,claude-3-sonnet,gemini-pro --consensus --cost
232
-
233
- # The consensus response shows combined metrics:
234
- # Tokens: input=126 (total), output=892 (consensus + individual)
235
- # Cost: $0.0189 (all models combined)
236
- ```
237
-
238
- #### Environment Variables
239
-
240
- ```bash
241
- # Enable token tracking by default
242
- export AIA_FLAGS__TOKENS=true
243
-
244
- # Enable cost tracking by default
245
- export AIA_FLAGS__COST=true
246
- ```
247
-
248
- ### Per-Model Roles
249
-
250
- Assign specific roles to each model in multi-model mode to get diverse perspectives on your prompts. Each model receives a prepended role prompt that shapes its perspective.
251
-
252
- #### Inline Role Syntax
253
-
254
- Use the `MODEL=ROLE` syntax to assign roles directly on the command line:
255
-
256
- ```bash
257
- # Single model with role
258
- aia --model gpt-4o=architect design_review.md
259
-
260
- # Multiple models with different roles
261
- aia --model gpt-4o=architect,claude=security,gemini=performance design_review.md
262
-
263
- # Mixed: some models with roles, some without
264
- aia --model gpt-4o=expert,claude analyze.md
265
- ```
266
-
267
- #### Multiple Perspectives
268
-
269
- Use the same model multiple times with different roles for diverse viewpoints:
270
-
271
- ```bash
272
- # Three instances of same model with different roles
273
- aia --model gpt-4o=optimist,gpt-4o=pessimist,gpt-4o=realist project_plan.md
274
-
275
- # AI provides three distinct perspectives on the same input
276
- ```
277
-
278
- **Output Format with Roles:**
279
- ```
280
- from: gpt-4o (optimist)
281
- I see great potential in this approach! The architecture is solid...
282
-
283
- from: gpt-4o #2 (pessimist)
284
- We need to consider several risks here. The design has some concerning...
285
-
286
- from: gpt-4o #3 (realist)
287
- Let's look at this pragmatically. The proposal has both strengths and...
288
- ```
289
-
290
- **Note**: When using duplicate models, AIA automatically numbers them (e.g., `gpt-4o`, `gpt-4o #2`, `gpt-4o #3`) and maintains separate conversation contexts for each instance.
291
-
292
- #### Role Discovery
293
-
294
- List all available roles in your prompts directory:
295
-
296
- ```bash
297
- # List all roles
298
- aia --list-roles
299
-
300
- # Output shows role IDs and descriptions
301
- Available roles in /Users/you/.prompts/roles:
302
- architect - Software architecture expert
303
- security - Security analysis specialist
304
- performance - Performance optimization expert
305
- optimist - Positive perspective analyzer
306
- pessimist - Critical risk analyzer
307
- realist - Balanced pragmatic analyzer
308
- ```
309
-
310
- #### Role Files
311
-
312
- Roles are stored as text files in your prompts directory:
313
-
314
- ```bash
315
- # Default location: ~/.prompts/roles/
316
- ~/.prompts/
317
- roles/
318
- architect.md
319
- security.md
320
- performance.md
321
- optimist.md
322
- pessimist.md
323
- realist.md
324
-
325
- # Nested role organization
326
- ~/.prompts/
327
- roles/
328
- software/
329
- architect.md
330
- developer.md
331
- analysis/
332
- optimist.md
333
- pessimist.md
334
- realist.md
335
- ```
336
-
337
- **Using Nested Roles:**
338
- ```bash
339
- # Specify full path from roles directory
340
- aia --model gpt-4o=software/architect,claude=analysis/pessimist design.md
341
- ```
342
-
343
- #### Configuration File Format
344
-
345
- Define model roles in your configuration file using array format:
346
-
347
- ```yaml
348
- # ~/.config/aia/aia.yml
349
- models:
350
- - name: gpt-4o
351
- role: architect
352
- - name: claude-3-sonnet
353
- role: security
354
- - name: gemini-pro
355
- role: performance
356
- ```
357
-
358
- ```yaml
359
- # Duplicate models with different roles
360
- models:
361
- - name: gpt-4o
362
- role: optimist
363
- - name: gpt-4o
364
- role: pessimist
365
- - name: gpt-4o
366
- role: realist
367
- ```
368
-
369
- **Note**: Models without roles work normally - simply set `role` to `~` (null).
370
-
371
- #### Environment Variable Usage
372
-
373
- Set model roles via environment variables using the same inline syntax:
374
-
375
- ```bash
376
- # Single model with role
377
- export AIA_MODEL="gpt-4o=architect"
378
-
379
- # Multiple models with roles
380
- export AIA_MODEL="gpt-4o=architect,claude=security,gemini=performance"
381
-
382
- # Duplicate models
383
- export AIA_MODEL="gpt-4o=optimist,gpt-4o=pessimist,gpt-4o=realist"
384
-
385
- # Then run AIA normally
386
- aia design_review.md
387
- ```
388
-
389
- #### Role Configuration Precedence
390
-
391
- When roles are specified in multiple places, the precedence order is:
392
-
393
- 1. **CLI inline syntax**: `--model gpt-4o=architect` (highest priority)
394
- 2. **CLI role flag**: `--role architect` (applies to all models)
395
- 3. **Environment variable**: `AIA_MODEL="gpt-4o=architect"`
396
- 4. **Configuration file**: `model: [{model: gpt-4o, role: architect}]`
397
-
398
- **Example of precedence:**
399
- ```bash
400
- # Config file specifies: model: [{model: gpt-4o, role: architect}]
401
- # Environment has: AIA_MODEL="claude=security"
402
- # Command line uses:
403
- aia --model gemini=performance my_prompt
404
-
405
- # Result: Uses gemini with performance role (CLI wins)
406
- ```
407
-
408
- #### Role Validation
409
-
410
- AIA validates role files exist at parse time and provides helpful error messages:
411
-
412
- ```bash
413
- # If role file doesn't exist
414
- $ aia --model gpt-4o=nonexistent my_prompt
415
-
416
- ERROR: Role file not found: ~/.prompts/roles/nonexistent.md
417
-
418
- Available roles:
419
- - architect
420
- - security
421
- - performance
422
- - optimist
423
- - pessimist
424
- - realist
425
- ```
426
-
427
- #### Creating Custom Roles
428
-
429
- Create new role files in your roles directory:
430
-
431
- ```bash
432
- # Create a new role
433
- cat > ~/.prompts/roles/debugger.md << 'EOF'
434
- You are an expert debugging assistant. When analyzing code:
435
- - Focus on identifying potential bugs and edge cases
436
- - Suggest specific debugging strategies
437
- - Explain the root cause of issues clearly
438
- - Provide actionable fix recommendations
439
- EOF
440
-
441
- # Use the new role
442
- aia --model gpt-4o=debugger analyze_bug.py
443
- ```
444
-
445
- ### Model Comparison in Prompts
446
- ```markdown
447
- Compare responses from multiple models:
448
- /compare "Explain quantum computing" --models gpt-4,claude-3-sonnet,gemini-pro
449
-
450
- Which explanation is most accessible?
451
- ```
452
-
453
- ## Model Configuration
454
-
455
- ### Model-Specific Settings
456
- Different models may work best with different parameters:
457
-
458
- #### GPT Models
459
- ```yaml
460
- # ~/.config/aia/models/gpt-4.yml
461
- llm:
462
- temperature: 0.7
463
- max_tokens: 4000
464
- top_p: 1.0
465
- frequency_penalty: 0.0
466
- presence_penalty: 0.0
467
- ```
468
-
469
- #### Claude Models
470
- ```yaml
471
- # ~/.config/aia/models/claude-3-sonnet.yml
472
- llm:
473
- temperature: 0.8
474
- max_tokens: 8000
475
- top_p: 0.9
476
- ```
477
-
478
- #### Gemini Models
479
- ```yaml
480
- # ~/.config/aia/models/gemini-pro.yml
481
- llm:
482
- temperature: 0.6
483
- max_tokens: 2000
484
- top_p: 0.95
485
- ```
486
-
487
- ### Dynamic Model Selection
488
- Choose models based on task characteristics:
489
-
490
- ```ruby
491
- # In prompt with Ruby directive
492
- /ruby
493
- task_type = '<%= task_type %>'
494
- model = case task_type
495
- when 'creative' then 'gpt-4'
496
- when 'analytical' then 'claude-3-sonnet'
497
- when 'code' then 'codellama-34b'
498
- else 'gpt-3.5-turbo'
499
- end
500
- puts "/config model #{model}"
501
- ```
502
-
503
- ## Model Performance Optimization
504
-
505
- ### Speed vs Quality Tradeoffs
506
-
507
- #### Fast Models (Lower Cost, Quicker Response)
508
- ```bash
509
- # Quick tasks, simple questions
510
- aia --model gpt-3.5-turbo simple_question
511
-
512
- # Code completion, basic analysis
513
- aia --model claude-3-haiku code_completion
514
-
515
- # Bulk processing
516
- for file in *.txt; do
517
- aia --model gpt-3.5-turbo --output "${file%.txt}_processed.md" process_file "$file"
518
- done
519
- ```
520
-
521
- #### Quality Models (Higher Cost, Better Results)
522
- ```bash
523
- # Complex analysis, important decisions
524
- aia --model gpt-4 strategic_analysis.md
525
-
526
- # Creative writing, nuanced tasks
527
- aia --model claude-3-opus --temperature 1.0 creative_writing
528
-
529
- # Critical code review
530
- aia --model gpt-4 --temperature 0.2 security_review.py
531
- ```
532
-
533
- ### Context Window Management
534
-
535
- #### Large Context Models
536
- For processing large documents:
537
- ```bash
538
- # Claude has the largest context window
539
- aia --model claude-3-sonnet large_document.pdf
540
-
541
- # GPT-4 Turbo for large contexts
542
- aia --model gpt-4-turbo comprehensive_analysis.md
543
- ```
544
-
545
- #### Context-Aware Processing
546
- ```bash
547
- # Check document size and choose appropriate model
548
- /ruby
549
- file_size = File.size('<%= file %>')
550
- model = file_size > 100000 ? 'claude-3-sonnet' : 'gpt-4'
551
- puts "/config model #{model}"
552
-
553
- # Process with selected model
554
- ```
555
-
556
- ## Model Capabilities
557
-
558
- ### Vision Models
559
- For image analysis and processing:
560
- ```bash
561
- # Analyze images
562
- aia --model gpt-4-vision image_analysis.jpg
563
-
564
- # Process screenshots
565
- aia --model gpt-4-vision --temperature 0.3 screenshot_analysis.png
566
-
567
- # Extract text from images
568
- aia --model gpt-4-vision extract_text_prompt image_with_text.jpg
569
- ```
570
-
571
- ### Function Calling Models
572
- For tool integration:
573
- ```bash
574
- # Models that support function calling
575
- aia --model gpt-4 --tools ./tools/ analysis_with_tools
576
-
577
- # Best function calling models
578
- aia --model gpt-3.5-turbo --tools ./tools/ tool_heavy_task
579
- ```
580
-
581
- ### Code Models
582
- Specialized for programming tasks:
583
- ```bash
584
- # Code-specific models
585
- aia --model codellama-34b code_generation_task
586
-
587
- # Programming assistance
588
- aia --model codellama-7b --temperature 0.1 debug_assistance
589
- ```
590
-
591
- ## Cost Management
592
-
593
- ### Model Pricing Considerations
594
-
595
- #### Monitor Usage
596
- ```bash
597
- # Enable verbose mode to see token usage
598
- aia --verbose --model gpt-4 expensive_task
599
-
600
- # Use debug mode for detailed cost tracking
601
- aia --debug --model claude-3-opus cost_analysis
602
- ```
603
-
604
- #### Cost-Effective Strategies
605
- ```bash
606
- # Use cheaper models for initial drafts
607
- aia --model gpt-3.5-turbo initial_draft
608
-
609
- # Refine with better models
610
- aia --model gpt-4 --include initial_draft.md refine_output
611
-
612
- # Batch processing with efficient models
613
- aia --model claude-3-haiku --pipeline "process,summarize" batch_files/
614
- ```
615
-
616
- ### Budget-Conscious Model Selection
617
- ```yaml
618
- # Cost-effective configuration
619
- budget_models:
620
- fast_tasks: gpt-3.5-turbo
621
- analysis: claude-3-haiku
622
- creative: gpt-3.5-turbo
623
-
624
- premium_models:
625
- critical_analysis: gpt-4
626
- creative_writing: claude-3-sonnet
627
- complex_reasoning: claude-3-opus
628
- ```
629
-
630
- ## Model-Specific Tips
631
-
632
- ### GPT Models
633
- - **GPT-4**: Best for complex reasoning, creative tasks
634
- - **GPT-3.5 Turbo**: Fast, cost-effective, good general model
635
- - **GPT-4 Vision**: Excellent for image analysis
636
- - **Best for**: Code generation, creative writing, general tasks
637
-
638
- ### Claude Models
639
- - **Claude-3 Opus**: Highest quality, most expensive
640
- - **Claude-3 Sonnet**: Great balance of quality and cost
641
- - **Claude-3 Haiku**: Fastest, most cost-effective
642
- - **Best for**: Long documents, analytical tasks, following instructions
643
-
644
- ### Gemini Models
645
- - **Gemini Pro**: Google's flagship model
646
- - **Gemini Pro Vision**: Multimodal capabilities
647
- - **Best for**: Structured data, mathematical reasoning
648
-
649
- ### Specialized Models
650
- - **CodeLlama**: Open-source code generation
651
- - **Llama 2**: Open-source general purpose
652
- - **Mixtral**: High-performance open model
653
-
654
- ## Local Model Providers
655
-
656
- ### Ollama
657
-
658
- [Ollama](https://ollama.ai) enables running open-source AI models locally.
659
-
660
- #### Setup
661
-
662
- ```bash
663
- # Install Ollama
664
- brew install ollama # macOS
665
- # or download from https://ollama.ai
666
-
667
- # Pull models
668
- ollama pull llama3.2
669
- ollama pull mistral
670
- ollama pull qwen2.5-coder
671
-
672
- # List available models
673
- ollama list
674
- ```
675
-
676
- #### Usage with AIA
677
-
678
- ```bash
679
- # Use Ollama model (prefix with 'ollama/')
680
- aia --model ollama/llama3.2 my_prompt
681
-
682
- # Chat mode
683
- aia --chat --model ollama/mistral
684
-
685
- # List Ollama models from AIA
686
- aia --model ollama/llama3.2 --chat
687
- > /models
688
-
689
- # Combine with cloud models for comparison
690
- aia --model ollama/llama3.2,gpt-4o-mini,claude-3-sonnet my_prompt
691
- ```
692
-
693
- #### Reasoning models and `--thinking`
694
-
695
- Reasoning models such as `qwen3` emit their chain-of-thought wrapped in
696
- `<think>...</think>` tags as part of the streamed response. By default AIA
697
- hides these blocks so you only see the final answer. Use `--thinking` to show
698
- the reasoning as well:
699
-
700
- ```bash
701
- # Hide reasoning (default)
702
- aia --chat --model ollama/qwen3:latest
703
-
704
- # Show the model's reasoning
705
- aia --chat --thinking --model ollama/qwen3:latest
706
- ```
707
-
708
- #### Configuration
709
-
710
- ```yaml
711
- # ~/.config/aia/aia.yml
712
- models:
713
- - name: ollama/llama3.2
714
- ```
715
-
716
- ```bash
717
- # Optional: Custom Ollama endpoint
718
- # Set via environment variable
719
- export OLLAMA_API_BASE=http://custom-host:11434
720
- ```
721
-
722
- #### Popular Ollama Models
723
-
724
- - **llama3.2**: Latest Llama model, good general purpose
725
- - **llama3.2:70b**: Larger version, better quality
726
- - **mistral**: Fast and efficient
727
- - **mixtral**: High-performance mixture of experts
728
- - **qwen2.5-coder**: Specialized for code
729
- - **codellama**: Code-focused model
730
-
731
- ### LM Studio
732
-
733
- [LM Studio](https://lmstudio.ai) provides a GUI for running local models with OpenAI-compatible API.
734
-
735
- #### Setup
736
-
737
- 1. Download LM Studio from https://lmstudio.ai
738
- 2. Install and launch the application
739
- 3. Browse and download models within LM Studio
740
- 4. Start the local server:
741
- - Click "Local Server" tab
742
- - Click "Start Server"
743
- - Default endpoint: http://localhost:1234/v1
744
-
745
- #### Usage with AIA
746
-
747
- ```bash
748
- # Use LM Studio model (prefix with 'lms/')
749
- aia --model lms/qwen/qwen3-coder-30b my_prompt
750
-
751
- # Chat mode
752
- aia --chat --model lms/llama-3.2-3b-instruct
753
-
754
- # List LM Studio models from AIA
755
- aia --model lms/any-loaded-model --chat
756
- > /models
757
-
758
- # Model validation
759
- # AIA validates model names against LM Studio's loaded models
760
- # If you specify an invalid model, you'll see:
761
- # ❌ 'model-name' is not a valid LM Studio model.
762
- #
763
- # Available LM Studio models:
764
- # - lms/qwen/qwen3-coder-30b
765
- # - lms/llama-3.2-3b-instruct
766
- ```
767
-
768
- #### Configuration
769
-
770
- ```yaml
771
- # ~/.config/aia/aia.yml
772
- models:
773
- - name: lms/qwen/qwen3-coder-30b
774
- ```
775
-
776
- ```bash
777
- # Optional: Custom LM Studio endpoint
778
- # Set via environment variable
779
- export LMS_API_BASE=http://localhost:1234/v1
780
- ```
781
-
782
- #### Tips for LM Studio
783
-
784
- - Use the model name exactly as shown in LM Studio
785
- - Prefix all model names with `lms/`
786
- - Ensure the local server is running before use
787
- - LM Studio supports one model at a time (unlike Ollama)
788
-
789
- ### Comparison: Ollama vs LM Studio
790
-
791
- | Feature | Ollama | LM Studio |
792
- |---------|--------|-----------|
793
- | **Interface** | Command-line | GUI + CLI |
794
- | **Model Management** | Via CLI (`ollama pull`) | GUI download |
795
- | **API Compatibility** | Custom + OpenAI-like | OpenAI-compatible |
796
- | **Multiple Models** | Yes (switch quickly) | One at a time |
797
- | **Platform** | macOS, Linux, Windows | macOS, Windows |
798
- | **Model Format** | GGUF, custom | GGUF |
799
- | **Best For** | CLI users, automation | GUI users, experimentation |
800
-
801
- ### Local + Cloud Model Workflows
802
-
803
- #### Privacy-First Workflow
804
- ```bash
805
- # Use local model for sensitive data
806
- aia --model ollama/llama3.2 --output draft.md process_private_data.txt
807
-
808
- # Use cloud model for final polish (on sanitized data)
809
- aia --model gpt-4 --include draft.md refine_output
810
- ```
811
-
812
- #### Cost-Optimization Workflow
813
- ```bash
814
- # Bulk processing with local model (free)
815
- for file in *.txt; do
816
- aia --model ollama/mistral --output "${file%.txt}_summary.md" summarize "$file"
817
- done
818
-
819
- # Final review with premium cloud model
820
- aia --model gpt-4 --include *_summary.md final_report
821
- ```
822
-
823
- #### Consensus with Mixed Models
824
- ```bash
825
- # Get consensus from local and cloud models
826
- aia --model ollama/llama3.2,ollama/mistral,gpt-4o-mini --consensus decision_prompt
827
-
828
- # Or individual responses to compare
829
- aia --model ollama/llama3.2,lms/qwen-coder,claude-3-sonnet --no-consensus code_review.py
830
- ```
831
-
832
- ## Troubleshooting Models
833
-
834
- ### Common Issues
835
-
836
- #### Model Not Available
837
- ```bash
838
- # Check if model exists
839
- aia --available-models | grep model_name
840
-
841
- # Try alternative model names
842
- aia --available-models anthropic
843
- ```
844
-
845
- #### Authentication Errors
846
- ```bash
847
- # Check API keys
848
- echo $OPENAI_API_KEY
849
- echo $ANTHROPIC_API_KEY
850
-
851
- # Test with working model
852
- aia --model gpt-3.5-turbo test_prompt
853
- ```
854
-
855
- #### Context Length Exceeded
856
- ```bash
857
- # Use model with larger context
858
- aia --model claude-3-sonnet large_document.pdf
859
-
860
- # Split large inputs
861
- split -l 1000 large_file.txt chunk_
862
- for chunk in chunk_*; do
863
- aia --model gpt-4 process_chunk "$chunk"
864
- done
865
- ```
866
-
867
- #### Rate Limiting
868
- ```bash
869
- # Add delays between requests
870
- sleep 1 && aia --model gpt-4 request1
871
- sleep 1 && aia --model gpt-4 request2
872
-
873
- # Use different model to avoid limits
874
- aia --model claude-3-sonnet alternative_processing
875
- ```
876
-
877
- ## Advanced Model Usage
878
-
879
- ### Model Switching Workflows
880
- ```bash
881
- # Start with fast model for initial processing
882
- aia --model gpt-3.5-turbo --output draft.md initial_analysis data.csv
883
-
884
- # Switch to quality model for refinement
885
- aia --model gpt-4 --include draft.md --output final.md refine_analysis
886
-
887
- # Use specialized model for specific tasks
888
- aia --model gpt-4-vision --include final.md image_analysis charts/
889
- ```
890
-
891
- ### Conditional Model Selection
892
- ```ruby
893
- # Dynamic model selection based on task complexity
894
- /ruby
895
- content_length = File.read('<%= input_file %>').length
896
- complexity = content_length > 10000 ? 'high' : 'low'
897
-
898
- model = case complexity
899
- when 'high' then 'claude-3-sonnet'
900
- when 'low' then 'gpt-3.5-turbo'
901
- end
902
-
903
- puts "/config model #{model}"
904
- puts "Selected #{model} for #{complexity} complexity task"
905
- ```
906
-
907
- ### Model Ensemble Techniques
908
- ```bash
909
- # Use different models for different aspects
910
- aia --model gpt-4 --output technical_analysis.md technical_review code.py
911
- aia --model claude-3-sonnet --output style_analysis.md style_review code.py
912
- aia --model gpt-3.5-turbo --include technical_analysis.md --include style_analysis.md synthesize_reviews
913
- ```
914
-
915
- ## Integration with Other Features
916
-
917
- ### Switching Models During a Chat Session
918
-
919
- AIA lets you change models — and even providers — mid-conversation without restarting. The switch takes effect immediately.
920
-
921
- #### Single Model Switch
922
-
923
- ```
924
- /model gpt-4o-mini
925
- ```
926
-
927
- The client is recreated on the spot. The next `/model` (no arguments) confirms the change:
928
-
929
- ```
930
- /model
931
- Current Model:
932
- ==============
933
- {id: "gpt-4o-mini", provider: "openai", ...}
934
- ```
935
-
936
- #### Cross-Provider Switch
937
-
938
- Move between providers seamlessly:
939
-
940
- ```
941
- /model claude-sonnet-4 # Anthropic
942
- /model gpt-4o # OpenAI
943
- /model gemini-2.0-flash # Google
944
- /model ollama/llama3.2 # Local (Ollama)
945
- ```
946
-
947
- #### Upgrade to Multi-Model Mid-Session
948
-
949
- Provide a comma-separated list to switch from a single model to multi-model mode:
950
-
951
- ```
952
- /model gpt-4o-mini, claude-sonnet-4
953
- ```
954
-
955
- Each model gets its own conversation context and responds independently. You can assign roles using the `model=role` syntax:
956
-
957
- ```
958
- /model gpt-4o=architect, claude-sonnet-4=security, gemini-pro=performance
959
- ```
960
-
961
- #### Return to Single Model
962
-
963
- Specify one model name to go back:
964
-
965
- ```
966
- /model claude-sonnet-4
967
- ```
968
-
969
- #### Adjust Parameters
970
-
971
- Fine-tune generation settings alongside model changes:
972
-
973
- ```
974
- /temperature 0.3 # More focused
975
- /top_p 0.9 # Nucleus sampling
976
- ```
977
-
978
- #### Compare Models in Chat
979
-
980
- ```
981
- /compare "Explain this concept" --models gpt-4,claude-3-sonnet
982
- ```
983
-
984
- ### Pipeline Model Configuration
985
- ```bash
986
- # Different models for different pipeline stages
987
- aia --config-file pipeline_config.yml --pipeline "extract,analyze,report"
988
-
989
- # pipeline_config.yml
990
- extract:
991
- model: gpt-3.5-turbo
992
- analyze:
993
- model: claude-3-sonnet
994
- report:
995
- model: gpt-4
996
- ```
997
-
998
- ### Tool Integration
999
- ```bash
1000
- # Use models optimized for function calling with tools
1001
- aia --model gpt-3.5-turbo --tools ./analysis_tools/ data_processing
1002
-
1003
- # Vision models with image processing tools
1004
- aia --model gpt-4-vision --tools ./image_tools/ visual_analysis
1005
- ```
1006
-
1007
- ## Related Documentation
1008
-
1009
- - [Available Models](available-models.md) - Complete model list
1010
- - [Configuration](../configuration.md) - Model configuration options
1011
- - [CLI Reference](../cli-reference.md) - Command-line model options
1012
- - [Chat Mode](chat.md) - Interactive model usage
1013
- - [Advanced Prompting](../advanced-prompting.md) - Model-specific prompting techniques
1014
-
1015
- ---
1016
-
1017
- Choosing the right model for each task is crucial for optimal results. Experiment with different models to find what works best for your specific use cases!