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
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!