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/faq.md DELETED
@@ -1,578 +0,0 @@
1
- <!-- Tocer[start]: Auto-generated, don't remove. -->
2
-
3
- ## Table of Contents
4
-
5
- - [Frequently Asked Questions](#frequently-asked-questions)
6
- - [Installation and Setup](#installation-and-setup)
7
- - [Q: What Ruby version is required for AIA?](#q-what-ruby-version-is-required-for-aia)
8
- - [Q: How do I install AIA?](#q-how-do-i-install-aia)
9
- - [Q: Where should I store my API keys?](#q-where-should-i-store-my-api-keys)
10
- - [Q: Can I use AIA without internet access?](#q-can-i-use-aia-without-internet-access)
11
- - [Q: How do I list available local models?](#q-how-do-i-list-available-local-models)
12
- - [Q: What's the difference between Ollama and LM Studio?](#q-whats-the-difference-between-ollama-and-lm-studio)
13
- - [Q: Can I mix local and cloud models?](#q-can-i-mix-local-and-cloud-models)
14
- - [Q: Why does my lms/ model show an error?](#q-why-does-my-lms-model-show-an-error)
15
- - [Basic Usage](#basic-usage)
16
- - [Q: How do I create my first prompt?](#q-how-do-i-create-my-first-prompt)
17
- - [Q: What's the difference between batch mode and chat mode?](#q-whats-the-difference-between-batch-mode-and-chat-mode)
18
- - [Q: How do I use fuzzy search for prompts?](#q-how-do-i-use-fuzzy-search-for-prompts)
19
- - [Configuration](#configuration)
20
- - [Q: Where is the configuration file located?](#q-where-is-the-configuration-file-located)
21
- - [Q: How do I change the default AI model?](#q-how-do-i-change-the-default-ai-model)
22
- - [Q: How do I set a custom prompts directory?](#q-how-do-i-set-a-custom-prompts-directory)
23
- - [Prompts and Directives](#prompts-and-directives)
24
- - [Q: What are directives and how do I use them?](#q-what-are-directives-and-how-do-i-use-them)
25
- - [Q: How do I include files in prompts?](#q-how-do-i-include-files-in-prompts)
26
- - [Q: Can I use Ruby code in prompts?](#q-can-i-use-ruby-code-in-prompts)
27
- - [Q: How do I create prompt workflows?](#q-how-do-i-create-prompt-workflows)
28
- - [Models and Performance](#models-and-performance)
29
- - [Q: Which AI model should I use?](#q-which-ai-model-should-i-use)
30
- - [Q: How do I use multiple models simultaneously?](#q-how-do-i-use-multiple-models-simultaneously)
31
- - [Q: How do I reduce token usage and costs?](#q-how-do-i-reduce-token-usage-and-costs)
32
- - [Q: What's consensus mode?](#q-whats-consensus-mode)
33
- - [Tools and Integration](#tools-and-integration)
34
- - [Q: What are RubyLLM tools?](#q-what-are-rubyllm-tools)
35
- - [Q: How do I use tools with AIA?](#q-how-do-i-use-tools-with-aia)
36
- - [Q: What's the difference between tools and MCP clients?](#q-whats-the-difference-between-tools-and-mcp-clients)
37
- - [Q: How do I create custom tools?](#q-how-do-i-create-custom-tools)
38
- - [Chat Mode](#chat-mode)
39
- - [Q: How do I start a chat session?](#q-how-do-i-start-a-chat-session)
40
- - [Q: How do I save chat conversations?](#q-how-do-i-save-chat-conversations)
41
- - [Q: Can I use tools in chat mode?](#q-can-i-use-tools-in-chat-mode)
42
- - [Q: How do I send a message to just one robot in a multi-model session?](#q-how-do-i-send-a-message-to-just-one-robot-in-a-multi-model-session)
43
- - [Q: Can I save my place in a conversation and return to it later?](#q-can-i-save-my-place-in-a-conversation-and-return-to-it-later)
44
- - [Q: How do I clear chat history?](#q-how-do-i-clear-chat-history)
45
- - [Troubleshooting](#troubleshooting)
46
- - [Q: "Command not found: aia"](#q-command-not-found-aia)
47
- - [Q: "No models available" error](#q-no-models-available-error)
48
- - [Q: "Permission denied" errors](#q-permission-denied-errors)
49
- - [Q: Prompts are slow or timing out](#q-prompts-are-slow-or-timing-out)
50
- - [Q: "Tool not found" errors](#q-tool-not-found-errors)
51
- - [Advanced Usage](#advanced-usage)
52
- - [Q: How do I use AIA for code review?](#q-how-do-i-use-aia-for-code-review)
53
- - [Q: Can I use AIA for data analysis?](#q-can-i-use-aia-for-data-analysis)
54
- - [Q: How do I integrate AIA into my development workflow?](#q-how-do-i-integrate-aia-into-my-development-workflow)
55
- - [Q: How do I backup my prompts?](#q-how-do-i-backup-my-prompts)
56
- - [Getting Help](#getting-help)
57
- - [Q: Where can I find more examples?](#q-where-can-i-find-more-examples)
58
- - [Q: How do I report bugs or request features?](#q-how-do-i-report-bugs-or-request-features)
59
- - [Q: Is there a community or forum?](#q-is-there-a-community-or-forum)
60
- - [Q: Where can I find the latest documentation?](#q-where-can-i-find-the-latest-documentation)
61
- - [Tips and Best Practices](#tips-and-best-practices)
62
- - [Q: What are some general best practices for prompts?](#q-what-are-some-general-best-practices-for-prompts)
63
- - [Q: How do I optimize for performance?](#q-how-do-i-optimize-for-performance)
64
- - [Q: Security considerations?](#q-security-considerations)
65
- - [Troubleshooting](#troubleshooting-1)
66
- - [Q: "Prompt not found" error](#q-prompt-not-found-error)
67
- - [Q: Model errors or "Model not available"](#q-model-errors-or-model-not-available)
68
- - [Q: Shell integration not working](#q-shell-integration-not-working)
69
- - [Q: Configuration issues](#q-configuration-issues)
70
- - [Q: Performance issues with slow responses](#q-performance-issues-with-slow-responses)
71
- - [Q: Large prompt processing issues](#q-large-prompt-processing-issues)
72
- - [Q: Debug mode - how to get more information?](#q-debug-mode---how-to-get-more-information)
73
- - [Q: Common error messages and solutions](#q-common-error-messages-and-solutions)
74
-
75
- <!-- Tocer[finish]: Auto-generated, don't remove. -->
76
-
77
- # Frequently Asked Questions
78
-
79
- Common questions and answers about using AIA.
80
-
81
- ## Installation and Setup
82
-
83
- ### Q: What Ruby version is required for AIA?
84
- **A:** AIA requires Ruby 3.2 or higher. You can check your Ruby version with `ruby --version`.
85
-
86
- ### Q: How do I install AIA?
87
- **A:** The easiest way is through RubyGems:
88
- ```bash
89
- gem install aia
90
- ```
91
-
92
- See the [Installation Guide](installation.md) for other installation methods.
93
-
94
- ### Q: Where should I store my API keys?
95
- **A:** Store API keys as environment variables in your shell profile (`.bashrc`, `.zshrc`, etc.):
96
- ```bash
97
- export OPENAI_API_KEY="your_key_here"
98
- export ANTHROPIC_API_KEY="your_key_here"
99
- ```
100
-
101
- ### Q: Can I use AIA without internet access?
102
- **A:** Yes! AIA supports two local model providers for complete offline operation:
103
-
104
- 1. **Ollama**: Run open-source models locally
105
- ```bash
106
- # Install and use Ollama
107
- brew install ollama
108
- ollama pull llama3.2
109
- aia --model ollama/llama3.2 --chat
110
- ```
111
-
112
- 2. **LM Studio**: GUI-based local model runner
113
- ```bash
114
- # Download from https://lmstudio.ai
115
- # Load a model and start local server
116
- aia --model lms/your-model-name --chat
117
- ```
118
-
119
- Both options provide full AI functionality without internet connection, perfect for:
120
- - 🔒 Private/sensitive data processing
121
- - ✈️ Offline/travel use
122
- - 💰 Zero API costs
123
- - 🏠 Air-gapped environments
124
-
125
- ### Q: How do I list available local models?
126
- **A:** Use the `/models` directive in a chat session or prompt:
127
-
128
- ```bash
129
- # Start chat with any local model
130
- aia --model ollama/llama3.2 --chat
131
-
132
- # In the chat session
133
- > /models
134
-
135
- # Output shows:
136
- # - Ollama models from local installation
137
- # - LM Studio models currently loaded
138
- # - Cloud models from RubyLLM database
139
- ```
140
-
141
- For Ollama specifically: `ollama list`
142
- For LM Studio: Check the Models tab in the LM Studio GUI
143
-
144
- ### Q: What's the difference between Ollama and LM Studio?
145
- **A:**
146
- - **Ollama**: Command-line focused, quick model switching, multiple models available
147
- - **LM Studio**: GUI application, visual model management, one model at a time
148
-
149
- Choose **Ollama** if you prefer CLI tools and automation.
150
- Choose **LM Studio** if you want a visual interface and easier model discovery.
151
-
152
- Both work great with AIA!
153
-
154
- ### Q: Can I mix local and cloud models?
155
- **A:** Absolutely! This is a powerful feature:
156
-
157
- ```bash
158
- # Compare local vs cloud responses
159
- aia --model ollama/llama3.2,gpt-4o-mini my_prompt
160
-
161
- # Get consensus across local and cloud models
162
- aia --model ollama/mistral,lms/qwen-coder,claude-3-sonnet --consensus decision
163
-
164
- # Use local for drafts, cloud for refinement
165
- aia --model ollama/llama3.2 --output draft.md initial_analysis
166
- aia --model gpt-4 --include draft.md final_report
167
- ```
168
-
169
- ### Q: Why does my lms/ model show an error?
170
- **A:** Common causes:
171
-
172
- 1. **Model not loaded in LM Studio**: Load a model first
173
- 2. **Wrong model name**: AIA validates against available models and shows the exact names to use
174
- 3. **Server not running**: Start the local server in LM Studio
175
- 4. **Wrong prefix**: Always use `lms/` prefix with full model name
176
-
177
- If you get an error, AIA will show you the exact model names to use:
178
- ```
179
- ❌ 'wrong-name' is not a valid LM Studio model.
180
-
181
- Available LM Studio models:
182
- - lms/qwen/qwen3-coder-30b
183
- - lms/llama-3.2-3b-instruct
184
- ```
185
-
186
- ## Basic Usage
187
-
188
- ### Q: How do I create my first prompt?
189
- **A:** Create a text file in your prompts directory:
190
- ```bash
191
- echo "Explain this code clearly:" > ~/.prompts/explain_code.md
192
- aia explain_code my_script.py
193
- ```
194
-
195
- ### Q: What's the difference between batch mode and chat mode?
196
- **A:**
197
- - **Batch mode** (default): Processes prompts once and exits
198
- - **Chat mode** (`--chat`): Interactive conversation that maintains context
199
-
200
- ### Q: How do I use fuzzy search for prompts?
201
- **A:** Install `fzf` and use the `--fuzzy` flag:
202
- ```bash
203
- # Install fzf (macOS)
204
- brew install fzf
205
-
206
- # Use fuzzy search
207
- aia --fuzzy
208
- ```
209
-
210
- ## Configuration
211
-
212
- ### Q: Where is the configuration file located?
213
- **A:** The main configuration file is at `~/.config/aia/aia.yml` (following XDG Base Directory Specification). You can create it if it doesn't exist.
214
-
215
- ### Q: How do I change the default AI model?
216
- **A:** Set it in your configuration file or use the command line:
217
- ```yaml
218
- # In config file (~/.config/aia/aia.yml)
219
- models:
220
- - name: gpt-4
221
- ```
222
-
223
- ```bash
224
- # Command line
225
- aia --model gpt-4 my_prompt
226
- ```
227
-
228
- ### Q: How do I set a custom prompts directory?
229
- **A:** Use the `--prompts-dir` option or set it in configuration:
230
- ```bash
231
- # Command line
232
- aia --prompts-dir /path/to/prompts my_prompt
233
-
234
- # Environment variable (uses nested naming convention)
235
- export AIA_PROMPTS__DIR="/path/to/prompts"
236
- ```
237
-
238
- ## Prompts and Directives
239
-
240
- ### Q: What are directives and how do I use them?
241
- **A:** Directives are special commands in prompts that start with `/`. Examples:
242
- ```markdown
243
- /config model gpt-4
244
- /include my_file.md
245
- /shell ls -la
246
- ```
247
-
248
- See the [Directives Reference](directives-reference.md) for all available directives.
249
-
250
- ### Q: How do I include files in prompts?
251
- **A:** Use the `/include` directive:
252
- ```markdown
253
- /include README.md
254
- /include /path/to/file.md
255
- ```
256
-
257
- ### Q: Can I use Ruby code in prompts?
258
- **A:** Yes, use the `/ruby` directive for one-liners:
259
- ```markdown
260
- /ruby puts "Hello, my name is#{ENV['USER']}"
261
-
262
- # Or for multi-line or conditional code use ERB
263
-
264
- <%=
265
- puts "Hello, my name is #{ENV['USER']}"
266
- puts "Today is #{Time.now.strftime('%Y-%m-%d')}"
267
- %>
268
- ```
269
-
270
- ### Q: How do I create prompt workflows?
271
- **A:** Use the `/pipeline` or `/next` directives:
272
- ```markdown
273
- /pipeline
274
- /next
275
- ```
276
-
277
- ## Models and Performance
278
-
279
- ### Q: Which AI model should I use?
280
- **A:** It depends on your needs:
281
- - **GPT-4o Mini**: Fast, cost-effective for simple tasks
282
- - **GPT-4**: Best quality for complex reasoning
283
- - **Claude-3 Sonnet**: Great for long documents and analysis
284
- - **Claude-3 Haiku**: Fast and economical
285
-
286
- ### Q: How do I use multiple models simultaneously?
287
- **A:** Use comma-separated model names:
288
- ```bash
289
- aia --model "gpt-4,claude-3-sonnet" my_prompt
290
- ```
291
-
292
- ### Q: How do I reduce token usage and costs?
293
- **A:**
294
- - Use shorter prompts when possible
295
- - Choose appropriate models (`gpt-4o-mini` for simple tasks)
296
- - Use temperature settings wisely
297
- - Clear chat context regularly with `/clear`
298
-
299
- ### Q: What's consensus mode?
300
- **A:** Consensus mode combines responses from multiple models into a single, refined answer:
301
- ```bash
302
- aia --model "gpt-4,claude-3-sonnet" --consensus my_prompt
303
- ```
304
-
305
- ## Tools and Integration
306
-
307
- ### Q: What are RubyLLM tools?
308
- **A:** Tools are Ruby classes that extend AI capabilities with custom functions like file operations, web requests, or data analysis.
309
-
310
- ### Q: How do I use tools with AIA?
311
- **A:** Use the `--tools` option:
312
- ```bash
313
- aia --tools my_tool.rb my_prompt
314
- aia --tools ./tools/ my_prompt
315
- ```
316
-
317
- ### Q: What's the difference between tools and MCP clients?
318
- **A:**
319
- - **Tools**: Ruby-based extensions that run in the same process
320
- - **MCP clients**: External services using Model Context Protocol
321
-
322
- ### Q: How do I create custom tools?
323
- **A:** Create a Ruby class inheriting from `RubyLLM::Tool`:
324
- ```ruby
325
- class MyTool < RubyLLM::Tool
326
- description "What this tool does"
327
-
328
- def my_method(param)
329
- # Implementation
330
- "Result"
331
- end
332
- end
333
- ```
334
-
335
- ## Chat Mode
336
-
337
- ### Q: How do I start a chat session?
338
- **A:** Use the `--chat` flag:
339
- ```bash
340
- aia --chat
341
- aia --chat --model gpt-4
342
- ```
343
-
344
- ### Q: How do I save chat conversations?
345
- **A:** Use the `--output` flag to save responses to a file:
346
- ```bash
347
- aia --chat --output conversation.md
348
- ```
349
-
350
- ### Q: Can I use tools in chat mode?
351
- **A:** Yes, enable tools when starting chat:
352
- ```bash
353
- aia --chat --tools ./tools/
354
- ```
355
-
356
- ### Q: How do I send a message to just one robot in a multi-model session?
357
- **A:** Use @mention syntax: prefix the robot's name with `@` (e.g., `@tobor explain this`). Use `/robots` to see the active robots and their names. Only the mentioned robot responds; others stay silent.
358
-
359
- ### Q: Can I save my place in a conversation and return to it later?
360
- **A:** Yes, use `/checkpoint name` to create a named checkpoint and `/restore name` to return to it. Use `/checkpoints` to list all checkpoints. `/clear` removes all history and checkpoints.
361
-
362
- ### Q: How do I clear chat history?
363
- **A:** Use the `/clear` command or `/clear` directive:
364
- ```
365
- You: /clear
366
- ```
367
-
368
- ## Troubleshooting
369
-
370
- ### Q: "Command not found: aia"
371
- **A:**
372
- 1. Make sure Ruby's bin directory is in your PATH
373
- 2. Try reinstalling: `gem uninstall aia && gem install aia`
374
- 3. Check if using `--user-install`: `gem install aia --user-install`
375
-
376
- ### Q: "No models available" error
377
- **A:**
378
- 1. Check your API keys are set correctly
379
- 2. Verify internet connection
380
- 3. Test with: `aia --available-models`
381
-
382
- ### Q: "Permission denied" errors
383
- **A:**
384
- 1. Check file permissions: `ls -la ~/.prompts/`
385
- 2. Ensure prompts directory is readable
386
- 3. Check tool file permissions if using custom tools
387
-
388
- ### Q: Prompts are slow or timing out
389
- **A:**
390
- 1. Try a faster model like `gpt-4o-mini`
391
- 2. Reduce prompt length or complexity
392
- 3. Check your internet connection
393
- 4. Use `--debug` to see what's happening
394
-
395
- ### Q: "Tool not found" errors
396
- **A:**
397
- 1. Verify tool file paths with `--tools`
398
- 2. Check Ruby syntax in tool files
399
- 3. Use `--debug` to see tool loading details
400
- 4. Ensure tools inherit from `RubyLLM::Tool`
401
-
402
- ## Advanced Usage
403
-
404
- ### Q: How do I use AIA for code review?
405
- **A:** Create a code review prompt:
406
- ```markdown
407
- /config model gpt-4
408
- /config temperature 0.3
409
-
410
- Review this code for bugs, security issues, and best practices:
411
- /include <%= file %>
412
- ```
413
-
414
- ### Q: Can I use AIA for data analysis?
415
- **A:** Yes, create data analysis tools and prompts:
416
- ```bash
417
- aia --tools data_analyzer.rb analyze_data dataset.csv
418
- ```
419
-
420
- ### Q: How do I integrate AIA into my development workflow?
421
- **A:**
422
- 1. Create project-specific prompts
423
- 2. Use tools for code analysis
424
- 3. Set up workflows with pipelines
425
- 4. Use chat mode for interactive development
426
-
427
- ### Q: How do I backup my prompts?
428
- **A:** Use version control:
429
- ```bash
430
- cd ~/.prompts
431
- git init
432
- git add .
433
- git commit -m "Initial prompt collection"
434
- git remote add origin your-repo-url
435
- git push -u origin main
436
- ```
437
-
438
- ## Getting Help
439
-
440
- ### Q: Where can I find more examples?
441
- **A:** Check the [Examples](examples/index.md) directory for real-world use cases and templates.
442
-
443
- ### Q: How do I report bugs or request features?
444
- **A:** Open an issue on GitHub: [https://github.com/MadBomber/aia/issues](https://github.com/MadBomber/aia/issues)
445
-
446
- ### Q: Is there a community or forum?
447
- **A:** Check the GitHub repository for discussions and community contributions.
448
-
449
- ### Q: Where can I find the latest documentation?
450
- **A:** The most up-to-date documentation is available in this docs site and the [GitHub repository](https://github.com/MadBomber/aia).
451
-
452
- ## Tips and Best Practices
453
-
454
- ### Q: What are some general best practices for prompts?
455
- **A:**
456
- 1. Be specific and clear in your instructions
457
- 2. Provide necessary context and examples
458
- 3. Use appropriate models for different tasks
459
- 4. Organize prompts logically in directories
460
- 5. Version control your prompt collection
461
-
462
- ### Q: How do I optimize for performance?
463
- **A:**
464
- 1. Choose the right model for each task
465
- 2. Use caching for expensive operations
466
- 3. Batch similar requests when possible
467
- 4. Monitor token usage and costs
468
- 5. Use shorter prompts when sufficient
469
-
470
- ### Q: Security considerations?
471
- **A:**
472
- 1. Don't commit API keys to version control
473
- 2. Use environment variables for secrets
474
- 3. Be cautious with shell commands in prompts
475
- 4. Review tool permissions and access
476
- 5. Use restricted tool access in shared environments
477
-
478
- ## Troubleshooting
479
-
480
- ### Q: "Prompt not found" error
481
- **A:** This usually means AIA can't locate your prompt file:
482
- ```bash
483
- # Check prompts directory
484
- ls $AIA_PROMPTS__DIR
485
-
486
- # Verify prompt file exists
487
- ls ~/.prompts/my_prompt.md
488
-
489
- # Use fuzzy search to find available prompts
490
- aia --fuzzy
491
- ```
492
-
493
- ### Q: Model errors or "Model not available"
494
- **A:** Check your model name and availability:
495
- ```bash
496
- # List available models
497
- aia --available-models
498
-
499
- # Check model name spelling
500
- aia --model gpt-4o-mini # Correct
501
- aia --model gpt4 # Incorrect
502
- ```
503
-
504
- ### Q: Shell integration not working
505
- **A:** Verify your shell patterns and permissions:
506
- ```bash
507
- # Test shell patterns separately
508
- echo "Test: $(date)" # Should show current date
509
- echo "Home: $HOME" # Should show home directory
510
-
511
- # Check if shell commands work in your environment
512
- which date
513
- which git
514
- ```
515
-
516
- ### Q: Configuration issues
517
- **A:** Debug your configuration setup:
518
- ```bash
519
- # Dump current configuration to a file for inspection
520
- aia --dump config_snapshot.yml
521
-
522
- # Test with verbose and debug output
523
- aia --debug --verbose my_prompt
524
- ```
525
-
526
- ### Q: Performance issues with slow responses
527
- **A:** Try these optimizations:
528
- ```bash
529
- # Use faster models
530
- aia --model gpt-4o-mini my_prompt
531
-
532
- # Reduce max tokens
533
- aia --max-tokens 1000 my_prompt
534
-
535
- # Lower temperature for faster responses
536
- aia --temperature 0.1 my_prompt
537
- ```
538
-
539
- ### Q: Large prompt processing issues
540
- **A:** Break down large prompts:
541
- ```bash
542
- # Use pipelines for multi-stage processing
543
- aia --pipeline "analyze,summarize,report" large_data.csv
544
-
545
- # Use selective file inclusion
546
- /include specific_section.md
547
-
548
- # Check model context limits
549
- aia --available-models | grep context
550
- ```
551
-
552
- ### Q: Debug mode - how to get more information?
553
- **A:** Enable debug output for detailed troubleshooting:
554
- ```bash
555
- # Basic debug mode
556
- aia --debug my_prompt
557
-
558
- # Maximum debugging output
559
- aia --debug --verbose my_prompt
560
-
561
- # Dump configuration for inspection
562
- aia --dump config_snapshot.yml
563
- ```
564
-
565
- ### Q: Common error messages and solutions
566
-
567
- | Error | Cause | Solution |
568
- |-------|-------|----------|
569
- | "Prompt not found" | Missing prompt file | Check file exists and spelling |
570
- | "Model not available" | Invalid model name | Use `--available-models` to list valid models |
571
- | "Shell command failed" | Invalid shell syntax | Test shell commands separately first |
572
- | "Configuration error" | Invalid config syntax | Check config file YAML syntax |
573
- | "API key missing" | No API key configured | Set environment variables for your models |
574
- | "Permission denied" | File/directory permissions | Check file permissions and ownership |
575
-
576
- ---
577
-
578
- Don't see your question here? Check the [documentation](index.md) or [open an issue](https://github.com/MadBomber/aia/issues) on GitHub!