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.
Files changed (225) hide show
  1. checksums.yaml +4 -4
  2. data/.version +1 -1
  3. data/CHANGELOG.md +146 -228
  4. data/README.md +41 -18
  5. data/bin/aia +8 -3
  6. data/lib/aia/aia_completion.bash +2 -3
  7. data/lib/aia/aia_completion.fish +6 -5
  8. data/lib/aia/aia_completion.zsh +2 -3
  9. data/lib/aia/chat_loop.rb +16 -14
  10. data/lib/aia/config/cli_parser.rb +123 -91
  11. data/lib/aia/config/defaults.yml +12 -39
  12. data/lib/aia/config/mcp_parser.rb +30 -36
  13. data/lib/aia/config/model_spec.rb +8 -14
  14. data/lib/aia/config/validator.rb +102 -103
  15. data/lib/aia/config/value_caster.rb +76 -0
  16. data/lib/aia/config.rb +70 -53
  17. data/lib/aia/crew.rb +29 -19
  18. data/lib/aia/debate_handler.rb +27 -10
  19. data/lib/aia/directives/configuration_directives.rb +55 -14
  20. data/lib/aia/directives/context_directives.rb +24 -12
  21. data/lib/aia/directives/execution_directives.rb +18 -23
  22. data/lib/aia/directives/model_directives.rb +41 -104
  23. data/lib/aia/directives/utility_directives.rb +16 -17
  24. data/lib/aia/directives/web_and_file_directives.rb +21 -14
  25. data/lib/aia/fact_asserter.rb +3 -3
  26. data/lib/aia/history_transfer.rb +64 -24
  27. data/lib/aia/logger.rb +10 -45
  28. data/lib/aia/mcp_config_normalizer.rb +27 -14
  29. data/lib/aia/mcp_connection_manager.rb +181 -184
  30. data/lib/aia/mcp_discovery.rb +43 -15
  31. data/lib/aia/mcp_grouper.rb +2 -1
  32. data/lib/aia/mcp_server_config.rb +20 -2
  33. data/lib/aia/mcp_utility.rb +24 -19
  34. data/lib/aia/mention_router.rb +15 -2
  35. data/lib/aia/modality_query.rb +36 -0
  36. data/lib/aia/model_alias_registry.rb +11 -11
  37. data/lib/aia/model_registry.rb +75 -0
  38. data/lib/aia/network_builder.rb +8 -7
  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.rb +33 -8
  76. metadata +19 -160
  77. data/.better-commits.json +0 -150
  78. data/.config/tocer/configuration.yml +0 -6
  79. data/.envrc +0 -19
  80. data/.loki +0 -11
  81. data/.reek.yml +0 -160
  82. data/.rubocop.yml +0 -116
  83. data/.rubocop_strict.yml +0 -15
  84. data/COMMITS.md +0 -196
  85. data/IMPLEMENTATION_PLAN.md +0 -506
  86. data/Rakefile +0 -47
  87. data/_typos.toml +0 -10
  88. data/aia.gemspec +0 -92
  89. data/architecture_review.md +0 -314
  90. data/config/aia.yml +0 -13
  91. data/docs/AGENTS.md +0 -40
  92. data/docs/advanced-prompting.md +0 -814
  93. data/docs/assets/images/aia.png +0 -0
  94. data/docs/cli-reference.md +0 -1241
  95. data/docs/configuration.md +0 -747
  96. data/docs/contributing.md +0 -386
  97. data/docs/directives-reference.md +0 -1145
  98. data/docs/examples/index.md +0 -277
  99. data/docs/examples/mcp/index.md +0 -475
  100. data/docs/examples/prompts/analysis/index.md +0 -78
  101. data/docs/examples/prompts/automation/index.md +0 -109
  102. data/docs/examples/prompts/development/index.md +0 -125
  103. data/docs/examples/prompts/index.md +0 -333
  104. data/docs/examples/prompts/learning/index.md +0 -127
  105. data/docs/examples/prompts/writing/index.md +0 -62
  106. data/docs/examples/tools/index.md +0 -282
  107. data/docs/faq.md +0 -578
  108. data/docs/guides/available-models.md +0 -366
  109. data/docs/guides/basic-usage.md +0 -478
  110. data/docs/guides/chat.md +0 -680
  111. data/docs/guides/crew.md +0 -239
  112. data/docs/guides/executable-prompts.md +0 -331
  113. data/docs/guides/first-prompt.md +0 -454
  114. data/docs/guides/getting-started.md +0 -455
  115. data/docs/guides/image-generation.md +0 -507
  116. data/docs/guides/index.md +0 -48
  117. data/docs/guides/local-models.md +0 -306
  118. data/docs/guides/migrate-prompts.md +0 -335
  119. data/docs/guides/models.md +0 -1017
  120. data/docs/guides/shared-tools.md +0 -254
  121. data/docs/guides/tools.md +0 -831
  122. data/docs/index.md +0 -259
  123. data/docs/installation.md +0 -274
  124. data/docs/mcp-integration.md +0 -603
  125. data/docs/prompt_management.md +0 -665
  126. data/docs/security.md +0 -674
  127. data/docs/special_projects_guide.md +0 -386
  128. data/docs/tools-and-mcp-examples.md +0 -1211
  129. data/docs/workflows-and-pipelines.md +0 -636
  130. data/examples/.gitignore +0 -2
  131. data/examples/00_setup_aia.sh +0 -111
  132. data/examples/01_basic_usage.sh +0 -23
  133. data/examples/02_frontmatter.sh +0 -33
  134. data/examples/03_shell_integration.sh +0 -55
  135. data/examples/04_erb_templating.sh +0 -56
  136. data/examples/05_shell_then_erb.sh +0 -38
  137. data/examples/06_prompt_chaining.sh +0 -59
  138. data/examples/07_pipeline.sh +0 -46
  139. data/examples/08_context_files.sh +0 -43
  140. data/examples/09_roles.sh +0 -67
  141. data/examples/10_stdin_piping.sh +0 -49
  142. data/examples/11_multi_model.sh +0 -65
  143. data/examples/12_token_usage.sh +0 -52
  144. data/examples/13_cost_tracking.sh +0 -68
  145. data/examples/14_output_file.sh +0 -91
  146. data/examples/15_parameters.sh +0 -68
  147. data/examples/16_directives.sh +0 -113
  148. data/examples/17_require_and_conditionals.sh +0 -68
  149. data/examples/18_tools.sh +0 -61
  150. data/examples/19_local_tools.sh +0 -34
  151. data/examples/20_mcp_servers.sh +0 -102
  152. data/examples/21_executable_prompts.sh +0 -78
  153. data/examples/22_chat_mode.sh +0 -217
  154. data/examples/23_verify.sh +0 -139
  155. data/examples/24_decompose.sh +0 -139
  156. data/examples/25_spawn.sh +0 -139
  157. data/examples/26_debate.sh +0 -97
  158. data/examples/27_mention_routing.sh +0 -157
  159. data/examples/28_model_switching.sh +0 -106
  160. data/examples/29_agent_harness.sh +0 -177
  161. data/examples/README.md +0 -321
  162. data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
  163. data/examples/aia_config.yml +0 -22
  164. data/examples/aia_config_orchestrator.yml +0 -45
  165. data/examples/aia_config_with_mcp.yml +0 -21
  166. data/examples/common.sh +0 -39
  167. data/examples/context/project_goals.md +0 -6
  168. data/examples/context/tech_stack.md +0 -7
  169. data/examples/directives/timestamp_directive.rb +0 -22
  170. data/examples/mcp/filesystem.json +0 -9
  171. data/examples/prompts_dir/analyze.md +0 -2
  172. data/examples/prompts_dir/brainstorm.md +0 -2
  173. data/examples/prompts_dir/conditional.md +0 -17
  174. data/examples/prompts_dir/creative.md +0 -4
  175. data/examples/prompts_dir/erbinfo.md +0 -5
  176. data/examples/prompts_dir/erbinfo_raw.md +0 -8
  177. data/examples/prompts_dir/evaluate.md +0 -2
  178. data/examples/prompts_dir/explain_joke.md +0 -1
  179. data/examples/prompts_dir/explain_recursion.md +0 -1
  180. data/examples/prompts_dir/fun_fact +0 -3
  181. data/examples/prompts_dir/greeting.md +0 -8
  182. data/examples/prompts_dir/greeting_required.md +0 -7
  183. data/examples/prompts_dir/hello.md +0 -1
  184. data/examples/prompts_dir/includes/ruby_facts.md +0 -4
  185. data/examples/prompts_dir/limerick.md +0 -1
  186. data/examples/prompts_dir/list_with_mcp.md +0 -3
  187. data/examples/prompts_dir/pick_best.md +0 -2
  188. data/examples/prompts_dir/project_summary +0 -12
  189. data/examples/prompts_dir/quiz_with_include.md +0 -6
  190. data/examples/prompts_dir/require_demo.md +0 -5
  191. data/examples/prompts_dir/roles/formal.md +0 -3
  192. data/examples/prompts_dir/roles/orchestrator.md +0 -21
  193. data/examples/prompts_dir/roles/pirate.md +0 -3
  194. data/examples/prompts_dir/shell_then_erb.md +0 -6
  195. data/examples/prompts_dir/sort_compare.md +0 -2
  196. data/examples/prompts_dir/summarize_context.md +0 -2
  197. data/examples/prompts_dir/sysinfo.md +0 -5
  198. data/examples/prompts_dir/sysinfo_raw.md +0 -8
  199. data/examples/prompts_dir/tagline.md +0 -1
  200. data/examples/prompts_dir/tell_joke.md +0 -1
  201. data/examples/prompts_dir/tell_joke_with_next.md +0 -4
  202. data/examples/prompts_dir/use_local_tool.md +0 -8
  203. data/examples/prompts_dir/use_tools.md +0 -8
  204. data/examples/prompts_dir/weather.md +0 -2
  205. data/examples/prompts_dir/whats_new.md +0 -2
  206. data/examples/prompts_dir/with_timestamp.md +0 -5
  207. data/examples/requirements/sinatra_taskflow_app.md +0 -139
  208. data/examples/rules/01_classify_ruby.rb +0 -16
  209. data/examples/rules/02_prefer_claude_for_code.rb +0 -19
  210. data/examples/rules/03_gate_prompt_length.rb +0 -19
  211. data/examples/rules/04_tool_selection.rb +0 -41
  212. data/examples/rules/README.md +0 -30
  213. data/examples/run_all.sh +0 -294
  214. data/examples/tools/word_count_tool.rb +0 -30
  215. data/lib/AGENTS.md +0 -57
  216. data/lib/aia/model_switch_handler.rb +0 -100
  217. data/mcp_servers/README.md +0 -110
  218. data/mcp_servers/apple-mcp.json +0 -8
  219. data/mcp_servers/filesystem.json +0 -9
  220. data/mcp_servers/mcp_server_chart.json +0 -11
  221. data/mcp_servers/playwright_one.json +0 -8
  222. data/mcp_servers/playwright_server_definition.json +0 -9
  223. data/mcp_servers/playwright_two.json +0 -8
  224. data/mcp_servers/tavily_mcp_server.json +0 -8
  225. data/mkdocs.yml +0 -169
data/docs/guides/chat.md DELETED
@@ -1,680 +0,0 @@
1
- # Chat Mode Guide
2
-
3
- AIA's chat mode provides interactive conversations with AI models, maintaining context and supporting advanced features like multi-model interactions, tool usage, and persistent sessions.
4
-
5
- ## Starting a Chat Session
6
-
7
- ### Basic Chat
8
- ```bash
9
- # Start an interactive chat session
10
- aia --chat
11
-
12
- # Start chat with a specific model
13
- aia --chat --model gpt-4
14
-
15
- # Start chat with initial context
16
- aia --chat --role assistant my_context.txt
17
- ```
18
-
19
- ### Chat with Initial Prompts
20
- ```bash
21
- # Begin chat after processing a prompt
22
- aia --chat my_initial_prompt
23
-
24
- # Chat with system prompt
25
- aia --chat --system-prompt helpful_assistant
26
-
27
- # Chat with role-based context
28
- aia --chat --role code_expert debugging_session
29
- ```
30
-
31
- ## Chat Interface
32
-
33
- ### Basic Commands
34
- Once in chat mode, you can use these commands:
35
-
36
- - **Regular messages**: Type normally and press Enter
37
- - **`/help`**: Show available chat commands
38
- - **`/exit`** or **`/quit`**: End the chat session
39
- - **`/clear`**: Clear conversation history
40
- - **`/save filename.md`**: Save conversation to file
41
- - **`/model model_name`**: Switch AI model
42
- - **`/temperature 0.8`**: Adjust creativity level
43
- - **`/tools`**: List available tools
44
- - **`/context`**: Show current context
45
- - **`/robots`**: List active robots and their `@mention` handles
46
-
47
- ### Special Features
48
-
49
- #### Multi-line Input
50
- ```
51
- You: ```
52
- This is a multi-line input.
53
- You can write code, long explanations,
54
- or complex queries across multiple lines.
55
- ```
56
-
57
- #### File Upload During Chat
58
- ```
59
- You: Please analyze this file:
60
- /include my_data.csv
61
-
62
- What patterns do you see?
63
- ```
64
-
65
- #### Code Execution
66
- ```
67
- The current date and time is:
68
- /ruby Time.now
69
-
70
- Files in the current directory are:
71
- /shell ls -la
72
-
73
- which files are over 1 week old?
74
- ```
75
-
76
- > **Security Warning**: The `/ruby` and `/shell` directives execute code directly on your machine with your user permissions. `/ruby` runs arbitrary Ruby via `eval()` and `/shell` invokes system commands. Only use these directives with trusted prompts. Never run prompts from untrusted sources that contain these directives without reviewing them first.
77
-
78
- ## Advanced Chat Features
79
-
80
- ### Multi-Model Conversations
81
-
82
- #### @mention Routing
83
- In a multi-model network, direct your message to a specific robot by prefixing its name with `@` (e.g., `@tobor What do you think?`). Use `/robots` to see active robot names and their `@mention` handles.
84
-
85
- #### Consensus Mode
86
- ```bash
87
- # Start chat with multiple models seeking consensus
88
- aia --chat --model "gpt-4,claude-3-sonnet,gemini-pro" --consensus
89
-
90
- # Models will collaborate to provide unified responses
91
- ```
92
-
93
- #### Parallel Responses
94
- ```bash
95
- # Get responses from multiple models simultaneously
96
- aia --chat --model "gpt-4,claude-3-sonnet" --no-consensus
97
-
98
- # You'll see separate responses from each model
99
- ```
100
-
101
- #### Model Comparison
102
- ```
103
- You: Compare these approaches to solving the problem:
104
- /compare "Explain recursion vs iteration" --models gpt-4,claude-3-sonnet
105
-
106
- Which explanation is clearer?
107
- ```
108
-
109
- ### Context Management
110
-
111
- #### Persistent Context
112
- AIA maintains conversation context automatically:
113
- ```
114
- You: I'm working on a Python web application using Flask.
115
- AI: Great! Flask is an excellent choice for web development...
116
-
117
- You: How do I handle user authentication?
118
- AI: For your Flask application, here are several authentication options...
119
- ```
120
-
121
- #### Context Checkpoints
122
- Create savepoints in your conversation to easily return to specific moments:
123
-
124
- ```
125
- You: Let's explore different authentication approaches for Flask.
126
- AI: I can help you explore various authentication methods...
127
-
128
- You: /checkpoint auth_start
129
-
130
- You: Tell me about JWT authentication.
131
- AI: JWT (JSON Web Tokens) authentication is a stateless approach...
132
-
133
- You: /checkpoint jwt_discussion
134
-
135
- You: What about OAuth integration?
136
- AI: OAuth provides a robust framework for authentication...
137
-
138
- You: Actually, let's go back to the JWT discussion
139
- You: /restore jwt_discussion
140
-
141
- You: /context
142
- === Chat Context ===
143
- Total messages: 6
144
- Checkpoints: auth_start, jwt_discussion
145
-
146
- 1. [System]: You are a helpful assistant
147
- 2. [User]: Let's explore different authentication approaches for Flask.
148
- 3. [Assistant]: I can help you explore various authentication methods...
149
-
150
- 📍 [Checkpoint: auth_start]
151
- ----------------------------------------
152
- 4. [User]: Tell me about JWT authentication.
153
- 5. [Assistant]: JWT (JSON Web Tokens) authentication is a stateless approach...
154
-
155
- 📍 [Checkpoint: jwt_discussion]
156
- ----------------------------------------
157
- === End of Context ===
158
- ```
159
-
160
- **Checkpoint Commands**:
161
- - `/checkpoint` - Create auto-numbered checkpoint (1, 2, 3...)
162
- - `/checkpoint name` - Create named checkpoint
163
- - `/restore` - Restore to last checkpoint
164
- - `/restore name` - Restore to specific checkpoint
165
- - `/cp name` - Short alias for checkpoint
166
-
167
- **Use Cases for Checkpoints**:
168
- - **Exploring alternatives**: Save before trying different approaches
169
- - **Debugging conversations**: Return to working state after errors
170
- - **Session branching**: Explore multiple conversation paths
171
- - **Learning sessions**: Bookmark important explanations
172
-
173
- #### Context Inspection
174
- ```
175
- You: /context
176
- # Shows current conversation history with checkpoint markers
177
-
178
- You: /review
179
- # Alternative command for context inspection
180
- ```
181
-
182
- #### Context Clearing
183
- ```
184
- You: /clear
185
- # Clears conversation history and all checkpoints while keeping session active
186
- ```
187
-
188
- ### Tool Integration in Chat
189
-
190
- #### Enabling Tools
191
- ```bash
192
- # Start chat with specific tools
193
- aia --chat --tools ./my_tools.rb
194
-
195
- # Start with tool directory
196
- aia --chat --tools ./tools/
197
-
198
- # Restrict tool access
199
- aia --chat --tools ./tools/ --allowed-tools "file_reader,calculator"
200
- ```
201
-
202
- #### Using Tools in Conversation
203
- ```
204
- You: Can you analyze the performance metrics in this log file?
205
- /tools performance_analyzer
206
- /include /var/log/app.log
207
-
208
- AI: I'll analyze the performance data using the performance analyzer tool...
209
- ```
210
-
211
- #### Tool Discovery
212
- ```
213
- You: /tools
214
- Available Tools:
215
- - file_analyzer: Analyze file contents and structure
216
- - web_scraper: Extract data from web pages
217
- - calculator: Perform complex mathematical calculations
218
- ```
219
-
220
- ## Chat Session Types
221
-
222
- ### Code Review Session
223
- ```bash
224
- # Start specialized code review chat
225
- aia --chat --role code_expert --system-prompt code_reviewer
226
-
227
- You: I need help reviewing this Python function:
228
- /include my_function.py
229
-
230
- AI: I'll review this code for bugs, performance issues, and best practices...
231
-
232
- You: What about security concerns?
233
- AI: Looking at the security aspects of your function...
234
-
235
- You: Can you suggest unit tests for this?
236
- AI: Here are comprehensive unit tests for your function...
237
- ```
238
-
239
- ### Data Analysis Session
240
- ```bash
241
- # Start data analysis chat with tools
242
- aia --chat --tools ./analysis_tools/ --model claude-3-sonnet
243
-
244
- You: I have a dataset I need to analyze:
245
- /include data.csv
246
-
247
- AI: I can help you analyze this dataset. Let me start by examining its structure...
248
-
249
- You: Focus on the correlation between sales and marketing spend
250
- AI: I'll analyze the correlation using statistical tools...
251
- ```
252
-
253
- ### Writing Session
254
- ```bash
255
- # Start creative writing session
256
- aia --chat --model gpt-4 --temperature 1.2 --role creative_writer
257
-
258
- You: Help me write a technical blog post about microservices
259
- AI: I'd be happy to help! Let's start by outlining the key points...
260
-
261
- You: Make it more engaging for developers
262
- AI: Here's how we can make it more engaging...
263
- ```
264
-
265
- ### Learning Session
266
- ```bash
267
- # Start educational chat
268
- aia --chat --role teacher --system-prompt patient_explainer
269
-
270
- You: Explain how blockchain works, but I'm completely new to this
271
- AI: Let me explain blockchain in simple terms, starting from the basics...
272
-
273
- You: Can you give me a practical example?
274
- AI: Absolutely! Let's use a simple example everyone can relate to...
275
- ```
276
-
277
- ## Voice and Audio Features
278
-
279
- ### Text-to-Speech
280
-
281
- `--speak` runs a three-stage pipeline after each AI response:
282
-
283
- 1. **Generation** — LLM streams text to the terminal (`Processing...`)
284
- 2. **Conversion** — text is converted to an audio file (`Converting to audio...`)
285
- 3. **Playback** — audio file is played (`Speaking...`)
286
-
287
- **Local TTS (default):** the macOS `say` command handles both conversion and
288
- playback in one step, so it shows a single `Speaking...` spinner.
289
-
290
- ```bash
291
- # Enable speech (uses macOS say, system default voice)
292
- aia --chat --speak
293
-
294
- # Choose a specific macOS voice (run `say -v '?'` to list available voices)
295
- aia --chat --speak --voice Samantha
296
- aia --chat --speak --voice Alex
297
- ```
298
-
299
- **OpenAI TTS:** point `speak_command` at `~/.config/aia/tts.sh` (installed with
300
- AIA). The script converts text to an audio file; AIA plays it with `afplay` and
301
- shows separate spinners for each stage.
302
-
303
- ```bash
304
- aia --chat --speak \
305
- --speak-command ~/.config/aia/tts.sh \
306
- --speech-model tts-1-hd \
307
- --voice nova \
308
- my_prompt
309
- ```
310
-
311
- ```yaml
312
- # ~/.config/aia/aia.yml
313
- audio:
314
- speak_command: ~/.config/aia/tts.sh
315
- speech_model: tts-1-hd # passed as SPEECH_MODEL env var to the script
316
- voice: nova # passed as AIA_AUDIO__VOICE env var
317
- ```
318
-
319
- ### Audio Input
320
- ```bash
321
- # Use speech-to-text for input
322
- aia --chat --transcription-model whisper-1 audio_input.wav
323
- ```
324
-
325
- ## Session Management
326
-
327
- ### Saving Conversations
328
- ```
329
- # Within chat
330
- You: /save project_discussion.md
331
- Conversation saved to project_discussion.md
332
-
333
- # Or with full path
334
- You: /save /path/to/conversations/analysis_session.md
335
- ```
336
-
337
- ### Loading Previous Context
338
- ```bash
339
- # Start chat with previous conversation
340
- aia --chat --include previous_session.md
341
-
342
- # This loads the conversation as context
343
- ```
344
-
345
- ### Switching Models and Providers Mid-Session
346
-
347
- One of AIA's most practical features is the ability to change models — and even providers — on the fly during a chat session. There is no need to restart; the switch takes effect immediately.
348
-
349
- #### Switch to a Different Model
350
-
351
- ```
352
- Follow up (cntl-D or 'exit' to end) #=>
353
- /model gpt-4o-mini
354
-
355
- Follow up (cntl-D or 'exit' to end) #=>
356
- /model
357
- Current Model:
358
- ==============
359
- {id: "gpt-4o-mini",
360
- name: "GPT-4o mini",
361
- provider: "openai",
362
- ...}
363
- ```
364
-
365
- #### Switch Providers
366
-
367
- The `/model` directive works across providers. Move from Anthropic to OpenAI to Google (or any supported provider) without leaving your session:
368
-
369
- ```
370
- Follow up (cntl-D or 'exit' to end) #=>
371
- /model claude-sonnet-4
372
- # Now using Anthropic
373
-
374
- Follow up (cntl-D or 'exit' to end) #=>
375
- /model gpt-4o
376
- # Now using OpenAI
377
-
378
- Follow up (cntl-D or 'exit' to end) #=>
379
- /model gemini-2.0-flash
380
- # Now using Google
381
- ```
382
-
383
- #### Go from Single Model to Multi-Model
384
-
385
- You can switch from a single model to a multi-model configuration by providing a comma-separated list. Each model gets its own conversation context and responds independently:
386
-
387
- ```
388
- Follow up (cntl-D or 'exit' to end) #=>
389
- /model gpt-4o-mini, claude-sonnet-4
390
-
391
- Follow up (cntl-D or 'exit' to end) #=>
392
- /model
393
- Multi-Model Configuration:
394
- ==========================
395
- Model count: 2
396
- Primary model: gpt-4o-mini (used for consensus when --consensus flag is enabled)
397
- ...
398
- ```
399
-
400
- You can also assign roles inline using the `model=role` syntax:
401
-
402
- ```
403
- Follow up (cntl-D or 'exit' to end) #=>
404
- /model gpt-4o=architect, claude-sonnet-4=security
405
- ```
406
-
407
- #### Go from Multi-Model Back to Single
408
-
409
- Specify just one model name to return to single-model mode:
410
-
411
- ```
412
- Follow up (cntl-D or 'exit' to end) #=>
413
- /model claude-sonnet-4
414
- ```
415
-
416
- #### View Current Model
417
-
418
- Use `/model` with no arguments to inspect the active model configuration:
419
-
420
- ```
421
- Follow up (cntl-D or 'exit' to end) #=>
422
- /model
423
- ```
424
-
425
- This shows the model ID, provider, context window, pricing, capabilities, and more.
426
-
427
- #### Adjust Generation Parameters
428
-
429
- Fine-tune how the active model responds:
430
-
431
- ```
432
- # Adjust creativity
433
- You: /temperature 0.3
434
-
435
- # Adjust nucleus sampling
436
- You: /top_p 0.9
437
- ```
438
-
439
- ## Chat Workflows
440
-
441
- ### Research and Analysis Workflow
442
- 1. **Information Gathering**: Load documents and data
443
- 2. **Initial Analysis**: Ask broad questions
444
- 3. **Deep Dive**: Focus on specific areas
445
- 4. **Synthesis**: Combine insights
446
- 5. **Documentation**: Save findings
447
-
448
- ```
449
- You: I'm researching market trends in AI development
450
- /include market_report.pdf
451
- /include competitor_analysis.csv
452
-
453
- AI: I'll help you analyze these market trends...
454
-
455
- You: What are the key growth drivers?
456
- AI: Based on the data, here are the main growth drivers...
457
-
458
- You: How do our competitors compare?
459
- AI: Looking at the competitive landscape...
460
-
461
- You: /save ai_market_research.md
462
- ```
463
-
464
- ### Development Workflow
465
- 1. **Code Review**: Analyze existing code
466
- 2. **Problem Solving**: Debug issues
467
- 3. **Implementation**: Write new features
468
- 4. **Testing**: Create test cases
469
- 5. **Documentation**: Generate docs
470
-
471
- ```
472
- You: Let's review and improve this API endpoint:
473
- /include api_endpoint.py
474
-
475
- AI: I'll review this endpoint for potential improvements...
476
-
477
- You: It's running slowly, can you identify bottlenecks?
478
- AI: I see several performance issues...
479
-
480
- You: Help me optimize the database queries
481
- AI: Here are optimized versions of your queries...
482
-
483
- You: Generate unit tests for the optimized version
484
- AI: Here are comprehensive unit tests...
485
- ```
486
-
487
- ## Customization and Configuration
488
-
489
- ### Chat-Specific Configuration
490
-
491
- Chat mode uses the same configuration as regular AIA usage. Relevant settings in `~/.config/aia/aia.yml`:
492
-
493
- ```yaml
494
- # Model selection
495
- models:
496
- - name: gpt-4o
497
-
498
- # LLM parameters
499
- llm:
500
- temperature: 0.7
501
- max_tokens: 2048
502
-
503
- # Audio for --speak and /say directive
504
- audio:
505
- voice: ~ # macOS system default; set e.g. "Samantha" to pick a voice
506
- speak_command: say # macOS local TTS; use ~/.config/aia/tts.sh for OpenAI TTS
507
- ```
508
-
509
- Start chat with specific options via CLI:
510
-
511
- ```bash
512
- aia --chat --model gpt-4o --tools ./tools/ my_system_prompt
513
- aia --chat --output conversation.md my_prompt # Save output
514
- ```
515
-
516
- ### Using Tools in Chat
517
-
518
- Load custom RubyLLM tools into chat sessions:
519
-
520
- ```bash
521
- # Load tools into a chat session
522
- aia --chat --tools ./tools/file_analyzer.rb my_prompt
523
-
524
- # Load tools from a directory
525
- aia --chat --tools ./tools/ my_prompt
526
- ```
527
-
528
- The AI model can call these tools during the conversation when relevant. See [Tools Guide](tools.md) for details on creating tools.
529
-
530
- ## Token Usage and Cost Tracking
531
-
532
- ### Displaying Token Usage
533
- Use the `--tokens` flag to see token usage after each response:
534
-
535
- ```bash
536
- # Enable token usage display
537
- aia --chat --tokens
538
-
539
- # Example output after a response:
540
- # AI: Here's my response to your question...
541
- #
542
- # Tokens: input=125, output=89, model=gpt-4o-mini
543
- ```
544
-
545
- ### Cost Estimation
546
- Use the `--cost` flag to include cost calculations with token usage:
547
-
548
- ```bash
549
- # Enable cost estimation (automatically enables --tokens)
550
- aia --chat --cost
551
-
552
- # Example output after a response:
553
- # AI: Here's my response to your question...
554
- #
555
- # Tokens: input=125, output=89, model=gpt-4o-mini
556
- # Cost: $0.0003 (input: $0.0002, output: $0.0001)
557
- ```
558
-
559
- ### Multi-Model Token Tracking
560
- When using multiple models, token usage is displayed for each model:
561
-
562
- ```bash
563
- aia --chat --tokens --model gpt-4,claude-3-sonnet
564
-
565
- # Example output:
566
- # from: gpt-4
567
- # Here's my response...
568
- #
569
- # from: claude-3-sonnet
570
- # Here's my alternative response...
571
- #
572
- # Model: gpt-4 - Tokens: input=125, output=89
573
- # Model: claude-3-sonnet - Tokens: input=125, output=112
574
- ```
575
-
576
- ## Troubleshooting Chat Mode
577
-
578
- ### Common Issues
579
-
580
- #### Context Too Long
581
- ```
582
- Error: Context exceeds maximum length
583
- ```
584
- **Solution**: Use `/clear` to clear history or `/context trim` to keep recent messages only.
585
-
586
- #### Model Not Responding
587
- ```
588
- Error: Model timeout or connection error
589
- ```
590
- **Solution**: Check your internet connection and API keys, try switching models.
591
-
592
- #### Tool Not Found
593
- ```
594
- Error: Tool 'my_tool' not found
595
- ```
596
- **Solution**: Verify tool paths with `/tools` and check tool file syntax.
597
-
598
- ### Performance Optimization
599
-
600
- #### Reduce Token Usage
601
- - Clear context regularly with `/clear`
602
- - Use shorter, more focused messages
603
- - Summarize long conversations periodically
604
-
605
- #### Improve Response Speed
606
- - Use faster models for simple queries
607
- - Cache frequently used context
608
- - Optimize tool implementations
609
-
610
- #### Memory Management
611
- ```bash
612
- # Monitor memory usage
613
- aia --chat --debug --verbose
614
-
615
- # Use memory-efficient models
616
- aia --chat --model gpt-3.5-turbo
617
- ```
618
-
619
- ## Best Practices
620
-
621
- ### Effective Chat Techniques
622
- 1. **Be Specific**: Clear, detailed questions get better responses
623
- 2. **Provide Context**: Include relevant information upfront
624
- 3. **Iterate**: Build on previous responses for deeper insights
625
- 4. **Use Tools**: Leverage tools for data processing and analysis
626
- 5. **Save Progress**: Regular saves prevent loss of valuable insights
627
-
628
- ### Security Considerations
629
- 1. **Code Execution Directives**: `/ruby` executes arbitrary Ruby code and `/shell` runs system commands with your user permissions. Only use trusted prompts containing these directives
630
- 2. **Sensitive Data**: Avoid sharing confidential information in prompts or chat
631
- 3. **Tool Access**: Restrict tool permissions with `--allowed-tools` and `--rejected-tools`
632
- 4. **MCP Servers**: Control which MCP servers can run with `--mcp-use` and `--mcp-skip`
633
- 5. **Session Management**: Clear sensitive conversations with `/clear`
634
- 6. **API Keys**: Keep credentials secure; never embed them in prompt files
635
-
636
- ### Productivity Tips
637
- 1. **Keyboard Shortcuts**: Learn and use available shortcuts
638
- 2. **Template Messages**: Create reusable message templates
639
- 3. **Model Selection**: Choose appropriate models for different tasks
640
- 4. **Batch Operations**: Process multiple items in single conversations
641
-
642
- ## Integration with Other AIA Features
643
-
644
- ### Pipeline Integration
645
- ```bash
646
- # Start chat after pipeline completion
647
- aia --pipeline "data_prep,analysis" --chat dataset.csv
648
-
649
- # Process results in chat mode
650
- ```
651
-
652
- ### Configuration Integration
653
- ```bash
654
- # Use predefined configurations in chat
655
- aia --config-file chat_setup.yml --chat
656
-
657
- # Override specific settings
658
- aia --chat --temperature 0.9 --max-tokens 3000
659
- ```
660
-
661
- ### Output Integration
662
- ```bash
663
- # Save chat output to file
664
- aia --chat --output discussion.md --markdown
665
-
666
- # Append to existing files
667
- aia --chat --output project_log.md --append
668
- ```
669
-
670
- ## Related Documentation
671
-
672
- - [Getting Started](getting-started.md) - Basic AIA usage
673
- - [Working with Models](models.md) - Model selection and configuration
674
- - [Tools Integration](tools.md) - Using and creating tools
675
- - [CLI Reference](../cli-reference.md) - Command-line options
676
- - [Configuration](../configuration.md) - Setup and customization
677
-
678
- ---
679
-
680
- Chat mode is one of AIA's most powerful features. Experiment with different models, tools, and workflows to find what works best for your use cases!