aia 2.0.0.0.pre.beta2 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (227) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +152 -223
  3. data/README.md +41 -18
  4. data/bin/aia +8 -3
  5. data/lib/aia/aia_completion.bash +2 -3
  6. data/lib/aia/aia_completion.fish +6 -5
  7. data/lib/aia/aia_completion.zsh +2 -3
  8. data/lib/aia/chat_loop.rb +16 -14
  9. data/lib/aia/config/cli_parser.rb +123 -91
  10. data/lib/aia/config/defaults.yml +18 -40
  11. data/lib/aia/config/mcp_parser.rb +30 -36
  12. data/lib/aia/config/model_spec.rb +8 -14
  13. data/lib/aia/config/validator.rb +102 -103
  14. data/lib/aia/config/value_caster.rb +76 -0
  15. data/lib/aia/config.rb +70 -53
  16. data/lib/aia/crew.rb +29 -19
  17. data/lib/aia/debate_handler.rb +27 -10
  18. data/lib/aia/directives/configuration_directives.rb +55 -14
  19. data/lib/aia/directives/context_directives.rb +24 -12
  20. data/lib/aia/directives/execution_directives.rb +18 -23
  21. data/lib/aia/directives/model_directives.rb +41 -104
  22. data/lib/aia/directives/utility_directives.rb +16 -17
  23. data/lib/aia/directives/web_and_file_directives.rb +21 -14
  24. data/lib/aia/fact_asserter.rb +3 -3
  25. data/lib/aia/history_transfer.rb +64 -24
  26. data/lib/aia/logger.rb +14 -46
  27. data/lib/aia/mcp_config_normalizer.rb +27 -14
  28. data/lib/aia/mcp_connection_manager.rb +181 -184
  29. data/lib/aia/mcp_discovery.rb +43 -15
  30. data/lib/aia/mcp_grouper.rb +2 -1
  31. data/lib/aia/mcp_server_config.rb +20 -2
  32. data/lib/aia/mcp_utility.rb +24 -19
  33. data/lib/aia/mention_router.rb +15 -2
  34. data/lib/aia/modality_query.rb +36 -0
  35. data/lib/aia/model_alias_registry.rb +11 -11
  36. data/lib/aia/model_registry.rb +75 -0
  37. data/lib/aia/network_builder.rb +8 -7
  38. data/lib/aia/patches/mcp_stdio_stderr.rb +102 -0
  39. data/lib/aia/patches/ruby_llm_streaming_error.rb +21 -4
  40. data/lib/aia/patches/ruby_llm_tool_param_compat.rb +18 -0
  41. data/lib/aia/pipeline_orchestrator.rb +71 -38
  42. data/lib/aia/prompt_decomposer.rb +1 -1
  43. data/lib/aia/prompt_handler.rb +56 -29
  44. data/lib/aia/provider_registry.rb +105 -0
  45. data/lib/aia/robot_builder.rb +1 -1
  46. data/lib/aia/robot_factory.rb +67 -63
  47. data/lib/aia/robot_sync.rb +79 -0
  48. data/lib/aia/role_catalog.rb +89 -0
  49. data/lib/aia/session.rb +25 -11
  50. data/lib/aia/skill_utils.rb +60 -19
  51. data/lib/aia/spawn_handler.rb +16 -4
  52. data/lib/aia/spawn_spec_parser.rb +6 -7
  53. data/lib/aia/special_mode_handler.rb +28 -25
  54. data/lib/aia/speech.rb +70 -34
  55. data/lib/aia/startup_coordinator.rb +17 -92
  56. data/lib/aia/streaming_runner.rb +10 -2
  57. data/lib/aia/system_prompt_assembler.rb +12 -11
  58. data/lib/aia/task_board.rb +60 -0
  59. data/lib/aia/tool_approver.rb +205 -0
  60. data/lib/aia/tool_filter.rb +1 -10
  61. data/lib/aia/tool_filter_strategy.rb +12 -1
  62. data/lib/aia/tool_introspection.rb +9 -1
  63. data/lib/aia/tool_loader.rb +67 -33
  64. data/lib/aia/tool_utility.rb +6 -5
  65. data/lib/aia/tools/delegate_to_foreman_tool.rb +6 -4
  66. data/lib/aia/tools/recruit_robot_tool.rb +12 -12
  67. data/lib/aia/tools/reskill_robot_tool.rb +7 -7
  68. data/lib/aia/tools/task_board_tool.rb +16 -16
  69. data/lib/aia/trakflow_bridge.rb +14 -8
  70. data/lib/aia/turn_state.rb +31 -8
  71. data/lib/aia/ui_presenter.rb +16 -0
  72. data/lib/aia/utility.rb +6 -24
  73. data/lib/aia/variable_input_collector.rb +0 -3
  74. data/lib/aia/verification_network.rb +9 -10
  75. data/lib/aia/version.rb +1 -9
  76. data/lib/aia.rb +34 -8
  77. metadata +20 -161
  78. data/.better-commits.json +0 -150
  79. data/.config/tocer/configuration.yml +0 -6
  80. data/.envrc +0 -19
  81. data/.loki +0 -11
  82. data/.reek.yml +0 -160
  83. data/.rubocop.yml +0 -116
  84. data/.rubocop_strict.yml +0 -15
  85. data/.version +0 -1
  86. data/COMMITS.md +0 -196
  87. data/IMPLEMENTATION_PLAN.md +0 -506
  88. data/Rakefile +0 -47
  89. data/_typos.toml +0 -10
  90. data/aia.gemspec +0 -92
  91. data/architecture_review.md +0 -314
  92. data/config/aia.yml +0 -13
  93. data/docs/AGENTS.md +0 -40
  94. data/docs/advanced-prompting.md +0 -814
  95. data/docs/assets/images/aia.png +0 -0
  96. data/docs/cli-reference.md +0 -1241
  97. data/docs/configuration.md +0 -747
  98. data/docs/contributing.md +0 -386
  99. data/docs/directives-reference.md +0 -1145
  100. data/docs/examples/index.md +0 -277
  101. data/docs/examples/mcp/index.md +0 -475
  102. data/docs/examples/prompts/analysis/index.md +0 -78
  103. data/docs/examples/prompts/automation/index.md +0 -109
  104. data/docs/examples/prompts/development/index.md +0 -125
  105. data/docs/examples/prompts/index.md +0 -333
  106. data/docs/examples/prompts/learning/index.md +0 -127
  107. data/docs/examples/prompts/writing/index.md +0 -62
  108. data/docs/examples/tools/index.md +0 -282
  109. data/docs/faq.md +0 -578
  110. data/docs/guides/available-models.md +0 -366
  111. data/docs/guides/basic-usage.md +0 -478
  112. data/docs/guides/chat.md +0 -680
  113. data/docs/guides/crew.md +0 -239
  114. data/docs/guides/executable-prompts.md +0 -331
  115. data/docs/guides/first-prompt.md +0 -454
  116. data/docs/guides/getting-started.md +0 -455
  117. data/docs/guides/image-generation.md +0 -507
  118. data/docs/guides/index.md +0 -48
  119. data/docs/guides/local-models.md +0 -306
  120. data/docs/guides/migrate-prompts.md +0 -335
  121. data/docs/guides/models.md +0 -1017
  122. data/docs/guides/shared-tools.md +0 -254
  123. data/docs/guides/tools.md +0 -831
  124. data/docs/index.md +0 -259
  125. data/docs/installation.md +0 -274
  126. data/docs/mcp-integration.md +0 -603
  127. data/docs/prompt_management.md +0 -665
  128. data/docs/security.md +0 -674
  129. data/docs/special_projects_guide.md +0 -386
  130. data/docs/tools-and-mcp-examples.md +0 -1211
  131. data/docs/workflows-and-pipelines.md +0 -636
  132. data/examples/.gitignore +0 -2
  133. data/examples/00_setup_aia.sh +0 -111
  134. data/examples/01_basic_usage.sh +0 -23
  135. data/examples/02_frontmatter.sh +0 -33
  136. data/examples/03_shell_integration.sh +0 -55
  137. data/examples/04_erb_templating.sh +0 -56
  138. data/examples/05_shell_then_erb.sh +0 -38
  139. data/examples/06_prompt_chaining.sh +0 -59
  140. data/examples/07_pipeline.sh +0 -46
  141. data/examples/08_context_files.sh +0 -43
  142. data/examples/09_roles.sh +0 -67
  143. data/examples/10_stdin_piping.sh +0 -49
  144. data/examples/11_multi_model.sh +0 -65
  145. data/examples/12_token_usage.sh +0 -52
  146. data/examples/13_cost_tracking.sh +0 -68
  147. data/examples/14_output_file.sh +0 -91
  148. data/examples/15_parameters.sh +0 -68
  149. data/examples/16_directives.sh +0 -113
  150. data/examples/17_require_and_conditionals.sh +0 -68
  151. data/examples/18_tools.sh +0 -61
  152. data/examples/19_local_tools.sh +0 -34
  153. data/examples/20_mcp_servers.sh +0 -102
  154. data/examples/21_executable_prompts.sh +0 -78
  155. data/examples/22_chat_mode.sh +0 -217
  156. data/examples/23_verify.sh +0 -139
  157. data/examples/24_decompose.sh +0 -139
  158. data/examples/25_spawn.sh +0 -139
  159. data/examples/26_debate.sh +0 -97
  160. data/examples/27_mention_routing.sh +0 -157
  161. data/examples/28_model_switching.sh +0 -106
  162. data/examples/29_agent_harness.sh +0 -177
  163. data/examples/README.md +0 -321
  164. data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
  165. data/examples/aia_config.yml +0 -22
  166. data/examples/aia_config_orchestrator.yml +0 -45
  167. data/examples/aia_config_with_mcp.yml +0 -21
  168. data/examples/common.sh +0 -39
  169. data/examples/context/project_goals.md +0 -6
  170. data/examples/context/tech_stack.md +0 -7
  171. data/examples/directives/timestamp_directive.rb +0 -22
  172. data/examples/mcp/filesystem.json +0 -9
  173. data/examples/prompts_dir/analyze.md +0 -2
  174. data/examples/prompts_dir/brainstorm.md +0 -2
  175. data/examples/prompts_dir/conditional.md +0 -17
  176. data/examples/prompts_dir/creative.md +0 -4
  177. data/examples/prompts_dir/erbinfo.md +0 -5
  178. data/examples/prompts_dir/erbinfo_raw.md +0 -8
  179. data/examples/prompts_dir/evaluate.md +0 -2
  180. data/examples/prompts_dir/explain_joke.md +0 -1
  181. data/examples/prompts_dir/explain_recursion.md +0 -1
  182. data/examples/prompts_dir/fun_fact +0 -3
  183. data/examples/prompts_dir/greeting.md +0 -8
  184. data/examples/prompts_dir/greeting_required.md +0 -7
  185. data/examples/prompts_dir/hello.md +0 -1
  186. data/examples/prompts_dir/includes/ruby_facts.md +0 -4
  187. data/examples/prompts_dir/limerick.md +0 -1
  188. data/examples/prompts_dir/list_with_mcp.md +0 -3
  189. data/examples/prompts_dir/pick_best.md +0 -2
  190. data/examples/prompts_dir/project_summary +0 -12
  191. data/examples/prompts_dir/quiz_with_include.md +0 -6
  192. data/examples/prompts_dir/require_demo.md +0 -5
  193. data/examples/prompts_dir/roles/formal.md +0 -3
  194. data/examples/prompts_dir/roles/orchestrator.md +0 -21
  195. data/examples/prompts_dir/roles/pirate.md +0 -3
  196. data/examples/prompts_dir/shell_then_erb.md +0 -6
  197. data/examples/prompts_dir/sort_compare.md +0 -2
  198. data/examples/prompts_dir/summarize_context.md +0 -2
  199. data/examples/prompts_dir/sysinfo.md +0 -5
  200. data/examples/prompts_dir/sysinfo_raw.md +0 -8
  201. data/examples/prompts_dir/tagline.md +0 -1
  202. data/examples/prompts_dir/tell_joke.md +0 -1
  203. data/examples/prompts_dir/tell_joke_with_next.md +0 -4
  204. data/examples/prompts_dir/use_local_tool.md +0 -8
  205. data/examples/prompts_dir/use_tools.md +0 -8
  206. data/examples/prompts_dir/weather.md +0 -2
  207. data/examples/prompts_dir/whats_new.md +0 -2
  208. data/examples/prompts_dir/with_timestamp.md +0 -5
  209. data/examples/requirements/sinatra_taskflow_app.md +0 -139
  210. data/examples/rules/01_classify_ruby.rb +0 -16
  211. data/examples/rules/02_prefer_claude_for_code.rb +0 -19
  212. data/examples/rules/03_gate_prompt_length.rb +0 -19
  213. data/examples/rules/04_tool_selection.rb +0 -41
  214. data/examples/rules/README.md +0 -30
  215. data/examples/run_all.sh +0 -294
  216. data/examples/tools/word_count_tool.rb +0 -30
  217. data/lib/AGENTS.md +0 -57
  218. data/lib/aia/model_switch_handler.rb +0 -100
  219. data/mcp_servers/README.md +0 -110
  220. data/mcp_servers/apple-mcp.json +0 -8
  221. data/mcp_servers/filesystem.json +0 -9
  222. data/mcp_servers/mcp_server_chart.json +0 -11
  223. data/mcp_servers/playwright_one.json +0 -8
  224. data/mcp_servers/playwright_server_definition.json +0 -9
  225. data/mcp_servers/playwright_two.json +0 -8
  226. data/mcp_servers/tavily_mcp_server.json +0 -8
  227. data/mkdocs.yml +0 -169
@@ -1,747 +0,0 @@
1
- <!-- Tocer[start]: Auto-generated, don't remove. -->
2
-
3
- ## Table of Contents
4
-
5
- - [Configuration](#configuration)
6
- - [Configuration Precedence](#configuration-precedence)
7
- - [Configuration Files](#configuration-files)
8
- - [Primary Configuration File](#primary-configuration-file)
9
- - [Environment Variables](#environment-variables)
10
- - [Command Line Arguments](#command-line-arguments)
11
- - [Embedded Directives](#embedded-directives)
12
- - [Logger Configuration](#logger-configuration)
13
- - [Configuration File Settings](#configuration-file-settings)
14
- - [CLI Log Level Override](#cli-log-level-override)
15
- - [Environment Variables](#environment-variables-1)
16
- - [Log Levels](#log-levels)
17
- - [Example: File-Based Logging](#example-file-based-logging)
18
- - [Advanced Configuration](#advanced-configuration)
19
- - [Multi-Model Configuration](#multi-model-configuration)
20
- - [Tool Configuration](#tool-configuration)
21
- - [MCP Server Configuration](#mcp-server-configuration)
22
- - [Prompt Directory Structure](#prompt-directory-structure)
23
- - [Configuration Examples](#configuration-examples)
24
- - [Development Setup](#development-setup)
25
- - [Production Setup](#production-setup)
26
- - [Creative Writing Setup](#creative-writing-setup)
27
- - [Validation and Troubleshooting](#validation-and-troubleshooting)
28
- - [Check Configuration](#check-configuration)
29
- - [Validate Settings](#validate-settings)
30
- - [Common Issues](#common-issues)
31
- - [Model Not Found](#model-not-found)
32
- - [Permission Errors](#permission-errors)
33
- - [Tool Loading Errors](#tool-loading-errors)
34
- - [Configuration Migration](#configuration-migration)
35
- - [Updating from Older Versions](#updating-from-older-versions)
36
- - [Best Practices](#best-practices)
37
- - [Security Considerations](#security-considerations)
38
-
39
- <!-- Tocer[finish]: Auto-generated, don't remove. -->
40
-
41
- # Configuration
42
-
43
- AIA provides a flexible configuration system with multiple layers of precedence, allowing you to customize behavior at different levels.
44
-
45
- ## Configuration Precedence
46
-
47
- AIA follows a hierarchical configuration system (highest to lowest precedence):
48
-
49
- 1. **Embedded Directives** - `/config` directives in prompt files
50
- 2. **Command Line Arguments** - CLI flags and options
51
- 3. **Environment Variables** - Shell environment variables
52
- 4. **Configuration Files** - YAML configuration files
53
- 5. **Defaults** - Built-in default values
54
-
55
- ## Configuration Files
56
-
57
- ### Primary Configuration File
58
-
59
- The main configuration file is located at `~/.config/aia/aia.yml` (following XDG Base Directory Specification):
60
-
61
- ```yaml
62
- # ~/.config/aia/aia.yml - Main AIA configuration
63
- # Uses nested structure - environment variables use double underscore for nesting
64
-
65
- # Service identification
66
- service:
67
- name: aia
68
-
69
- # LLM Configuration
70
- # Access: AIA.config.llm.temperature, etc.
71
- # Env: AIA_LLM__TEMPERATURE, etc.
72
- llm:
73
- temperature: 0.7 # Creativity/randomness (0.0-2.0)
74
- max_tokens: 2048 # Maximum response length
75
- top_p: 1.0 # Nucleus sampling
76
- frequency_penalty: 0.0 # Repetition penalty (-2.0 to 2.0)
77
- presence_penalty: 0.0 # Topic penalty (-2.0 to 2.0)
78
-
79
- # Models Configuration
80
- # Access: AIA.config.models (array of ModelSpec objects)
81
- # Each model has: name, role, instance, internal_id
82
- models:
83
- - name: gpt-4o-mini
84
- role: ~ # Optional role assignment
85
-
86
- # Prompts Configuration
87
- # Access: AIA.config.prompts.dir, AIA.config.prompts.roles_prefix, etc.
88
- # Env: AIA_PROMPTS__DIR, AIA_PROMPTS__ROLES_PREFIX, etc.
89
- prompts:
90
- dir: ~/.prompts # Directory containing prompt files
91
- extname: .md # Prompt file extension
92
- roles_prefix: roles # Subdirectory name for role files
93
- roles_dir: ~/.prompts/roles # Full path to roles directory
94
- role: ~ # Default role
95
- skills: [] # Skill IDs to prepend to prompt (set by --skill/-s)
96
- skills_prefix: ~ # Subdirectory appended to skills base path (nil = unset)
97
- system_prompt: ~ # Default system prompt
98
- parameter_regex: ~ # Regex for parameter extraction
99
-
100
- # Roles Configuration
101
- # Access: AIA.config.roles.dir
102
- # Env: AIA_ROLES__DIR
103
- roles:
104
- dir: ~/.prompts/roles # Full path to roles directory
105
-
106
- # Skills Configuration
107
- # Access: AIA.config.skills.dir
108
- # Env: AIA_SKILLS__DIR
109
- #
110
- # Skills are subdirectories under skills.dir, each containing a SKILL.md
111
- # file with YAML front matter (name, description, and any custom fields).
112
- # Use --skill/-s to prepend skills to prompts, --list-skills to browse.
113
- skills:
114
- dir: ~/.prompts/skills # Directory containing skill subdirectories
115
-
116
- # Output Configuration
117
- # Access: AIA.config.output.file, AIA.config.output.append, etc.
118
- # Env: AIA_OUTPUT__FILE, AIA_OUTPUT__APPEND, etc.
119
- output:
120
- file: temp.md # Output file (null = no file output)
121
- append: false # Append to output file instead of overwriting
122
- markdown: true # Format output with Markdown
123
- history_file: ~/.prompts/_prompts.log # Reline chat input history (chat mode only; up to 50 entries)
124
-
125
- # Audio Configuration
126
- # Access: AIA.config.audio.voice, AIA.config.audio.speak_command, etc.
127
- # Env: AIA_AUDIO__VOICE, AIA_AUDIO__SPEAK_COMMAND, etc.
128
- audio:
129
- voice: ~ # Voice name (macOS say: e.g. Samantha; OpenAI: alloy/nova/echo/…)
130
- speak_command: say # TTS command; macOS default is `say`
131
- speech_model: ~ # Passed as SPEECH_MODEL env var to the speak command (unset = not passed)
132
- transcription_model: ~ # Default transcription model for RubyLLM (unset = RubyLLM default)
133
-
134
- # Image Configuration
135
- # Access: AIA.config.image.model, AIA.config.image.size, etc.
136
- # Env: AIA_IMAGE__MODEL, AIA_IMAGE__SIZE, etc.
137
- image:
138
- model: dall-e-3 # Image generation model
139
- size: 1024x1024 # Default image size
140
- quality: standard # Image quality (standard/hd)
141
- style: vivid # Image style (vivid/natural)
142
-
143
- # Embedding Configuration
144
- # Access: AIA.config.embedding.model
145
- # Env: AIA_EMBEDDING__MODEL
146
- embedding:
147
- model: text-embedding-ada-002 # Embedding model
148
-
149
- # Tools Configuration
150
- # Access: AIA.config.tools.paths, AIA.config.tools.allowed, etc.
151
- # Env: AIA_TOOLS__PATHS, AIA_TOOLS__ALLOWED, etc.
152
- tools:
153
- paths: [] # Paths to tool files/directories
154
- allowed: ~ # Whitelist of allowed tools
155
- rejected: ~ # Blacklist of rejected tools
156
-
157
- # Flags (Boolean Options)
158
- # Access: AIA.config.flags.chat, AIA.config.flags.debug, etc.
159
- # Env: AIA_FLAGS__CHAT=true, AIA_FLAGS__DEBUG=true, etc.
160
- flags:
161
- chat: false # Start in chat mode
162
- cost: false # Show cost calculations
163
- debug: false # Enable debug logging
164
- verbose: false # Show detailed output
165
- fuzzy: false # Enable fuzzy prompt searching
166
- tokens: false # Show token usage
167
- no_mcp: false # Disable MCP server processing
168
- speak: false # Convert text to speech
169
- shell: true # Enable shell integration
170
- erb: true # Enable ERB processing
171
- clear: false # Clear conversation history
172
- consensus: false # Enable consensus mode for multi-model
173
- thinking: false # Show raw <think> reasoning blocks from local models
174
-
175
- # Logger Configuration
176
- # Access: AIA.config.logger.aia.file, AIA.config.logger.llm.level, etc.
177
- # Env: AIA_LOGGER__AIA__FILE, AIA_LOGGER__LLM__LEVEL, etc.
178
- logger:
179
- aia: # AIA application logging
180
- file: STDOUT # STDOUT, STDERR, or a file path
181
- level: warn # debug, info, warn, error, fatal
182
- flush: true # Immediate write (no buffering)
183
- llm: # RubyLLM gem logging
184
- file: STDOUT
185
- level: warn
186
- flush: true
187
- mcp: # RubyLLM::MCP gem logging
188
- file: STDOUT
189
- level: warn
190
- flush: true
191
-
192
- # Pipeline/Workflow Configuration
193
- # Access: AIA.config.pipeline (array of prompt IDs)
194
- pipeline: []
195
-
196
- # Model Registry Configuration
197
- # Access: AIA.config.registry.refresh
198
- # Env: AIA_REGISTRY__REFRESH
199
- registry:
200
- refresh: 7 # Days between model database refreshes (0 = disable)
201
-
202
- # Required Ruby Libraries
203
- # Access: AIA.config.require_libs (array)
204
- require_libs: []
205
-
206
- # MCP Servers Configuration
207
- # Access: AIA.config.mcp_servers (array of server configs)
208
- mcp_servers: []
209
- # - name: my-server
210
- # command: /path/to/server
211
- # args: []
212
- # env: {}
213
- # timeout: 8000
214
-
215
- # Paths Configuration
216
- # Access: AIA.config.paths.aia_dir, AIA.config.paths.config_file
217
- # Env: AIA_PATHS__AIA_DIR, AIA_PATHS__CONFIG_FILE
218
- paths:
219
- aia_dir: ~/.config/aia
220
- config_file: ~/.config/aia/aia.yml
221
-
222
- # Context Files (set at runtime)
223
- # Access: AIA.config.context_files (array of file paths)
224
- context_files: []
225
-
226
- # Concurrency Configuration
227
- # Access: AIA.config.concurrency.auto, .independent_servers, .threshold
228
- # Controls automatic MCP server parallelization.
229
- concurrency:
230
- auto: false # Enable automatic MCP concurrency
231
- independent_servers: [] # Servers safe to run in parallel
232
- threshold: 2 # Minimum servers needed to trigger concurrency
233
-
234
- # Model Aliases (short name → full model ID)
235
- # Access: AIA.config.model_aliases
236
- # Example: { "gpt4": "gpt-4o", "sonnet": "claude-sonnet-4-20250514" }
237
- model_aliases: {}
238
-
239
- # MCP Server Filtering
240
- # Access: AIA.config.mcp_use, AIA.config.mcp_skip
241
- mcp_use: ~ # Array of MCP server names to activate (nil = all)
242
- mcp_skip: ~ # Array of MCP server names to skip
243
-
244
- # Tool Filter Flags
245
- # Access: AIA.config.flags.track_pipeline, AIA.config.flags.expert_routing
246
- # Env: AIA_FLAGS__TRACK_PIPELINE, AIA_FLAGS__EXPERT_ROUTING, etc.
247
- # (These belong under flags: but are shown here for reference)
248
- #
249
- # flags:
250
- # track_pipeline: false # Track which pipeline prompts are executed
251
- # expert_routing: false # Route chat turns to specialist robots
252
- #
253
- # Tool Filter Strategy Flags
254
- # auto_tool_filter: true # TF-IDF cosine similarity filter (on by default)
255
- # tool_filter_b: false # Zvec HNSW vector DB filter
256
- # tool_filter_c: false # SqliteVec filter
257
- # tool_filter_d: false # LSI (latent semantic indexing) filter
258
- # tool_filter_load: false # Load saved filter model from disk
259
- # tool_filter_save: false # Save filter model to disk after build
260
- ```
261
-
262
- ## Environment Variables
263
-
264
- All configuration options can be set via environment variables with the `AIA_` prefix.
265
- Use double underscore (`__`) for nested configuration sections:
266
-
267
- ```bash
268
- # LLM settings (nested under llm:)
269
- export AIA_LLM__TEMPERATURE="0.8"
270
- export AIA_LLM__MAX_TOKENS="2048"
271
- export AIA_LLM__TOP_P="1.0"
272
- export AIA_LLM__FREQUENCY_PENALTY="0.0"
273
- export AIA_LLM__PRESENCE_PENALTY="0.0"
274
-
275
- # Models (top-level, supports MODEL=ROLE syntax)
276
- export AIA_MODEL="gpt-4"
277
- export AIA_MODEL="gpt-4o=architect,claude=reviewer"
278
-
279
- # Prompts settings (nested under prompts:)
280
- export AIA_PROMPTS__DIR="/path/to/my/prompts"
281
- export AIA_PROMPTS__EXTNAME=".md"
282
- export AIA_PROMPTS__ROLES_PREFIX="roles"
283
- export AIA_PROMPTS__ROLES_DIR="~/.prompts/roles"
284
- export AIA_PROMPTS__ROLE="expert"
285
- # export AIA_PROMPTS__SKILLS_PREFIX="my-prefix" # No default — unset means use skills.dir directly
286
- export AIA_PROMPTS__SYSTEM_PROMPT="my_system_prompt"
287
- export AIA_PROMPTS__PARAMETER_REGEX='\{\{(\w+)\}\}'
288
-
289
- # Skills settings (nested under skills:)
290
- export AIA_SKILLS__DIR="~/.prompts/skills"
291
-
292
- # Output settings (nested under output:)
293
- export AIA_OUTPUT__FILE="/tmp/aia_output.md"
294
- export AIA_OUTPUT__APPEND="false"
295
- export AIA_OUTPUT__MARKDOWN="true"
296
- export AIA_OUTPUT__HISTORY_FILE="~/.prompts/_prompts.log"
297
-
298
- # Audio settings (nested under audio:)
299
- export AIA_AUDIO__VOICE="Samantha" # macOS say voice (see: say -v '?')
300
- export AIA_AUDIO__SPEAK_COMMAND="say" # default; swap for custom TTS script
301
- export AIA_AUDIO__SPEECH_MODEL="tts-1" # passed as SPEECH_MODEL to speak_command
302
- export AIA_AUDIO__TRANSCRIPTION_MODEL="whisper-1"
303
-
304
- # Image settings (nested under image:)
305
- export AIA_IMAGE__MODEL="dall-e-3"
306
- export AIA_IMAGE__SIZE="1024x1024"
307
- export AIA_IMAGE__QUALITY="standard"
308
- export AIA_IMAGE__STYLE="vivid"
309
-
310
- # Embedding settings (nested under embedding:)
311
- export AIA_EMBEDDING__MODEL="text-embedding-ada-002"
312
-
313
- # Tools settings (nested under tools:)
314
- export AIA_TOOLS__PATHS="/path/to/tools"
315
- export AIA_TOOLS__ALLOWED="calculator,file_reader"
316
- export AIA_TOOLS__REJECTED="dangerous_tool"
317
-
318
- # Flags (nested under flags:)
319
- export AIA_FLAGS__CHAT="true"
320
- export AIA_FLAGS__COST="false"
321
- export AIA_FLAGS__DEBUG="false"
322
- export AIA_FLAGS__VERBOSE="true"
323
- export AIA_FLAGS__FUZZY="false"
324
- export AIA_FLAGS__TOKENS="true"
325
- export AIA_FLAGS__NO_MCP="false"
326
- export AIA_FLAGS__SPEAK="false"
327
- export AIA_FLAGS__SHELL="true"
328
- export AIA_FLAGS__ERB="true"
329
- export AIA_FLAGS__CLEAR="false"
330
- export AIA_FLAGS__CONSENSUS="false"
331
- export AIA_FLAGS__THINKING="false"
332
-
333
- # Logger settings (nested under logger:)
334
- export AIA_LOGGER__AIA__FILE="~/.config/aia/aia.log"
335
- export AIA_LOGGER__AIA__LEVEL="debug"
336
- export AIA_LOGGER__AIA__FLUSH="true"
337
- export AIA_LOGGER__LLM__FILE="STDOUT"
338
- export AIA_LOGGER__LLM__LEVEL="info"
339
- export AIA_LOGGER__LLM__FLUSH="true"
340
- export AIA_LOGGER__MCP__FILE="STDERR"
341
- export AIA_LOGGER__MCP__LEVEL="warn"
342
- export AIA_LOGGER__MCP__FLUSH="true"
343
-
344
- # Registry settings (nested under registry:)
345
- export AIA_REGISTRY__REFRESH="7"
346
-
347
- # Paths settings (nested under paths:)
348
- export AIA_PATHS__AIA_DIR="~/.config/aia"
349
- export AIA_PATHS__CONFIG_FILE="~/.config/aia/aia.yml"
350
-
351
- # API Keys (handled by RubyLLM)
352
- export OPENAI_API_KEY="your_key_here"
353
- export ANTHROPIC_API_KEY="your_key_here"
354
- export GOOGLE_API_KEY="your_key_here"
355
- export OLLAMA_URL="http://localhost:11434"
356
- ```
357
-
358
- ## Command Line Arguments
359
-
360
- All options can be overridden via command line arguments. See [CLI Reference](cli-reference.md) for complete details.
361
-
362
- ## Embedded Directives
363
-
364
- Prompts can contain configuration directives that override all other settings:
365
-
366
- ```markdown
367
- /config model claude-3-sonnet
368
- /config temperature 0.9
369
- /config max_tokens 1500
370
-
371
- Write a creative story about...
372
- ```
373
-
374
- ## Logger Configuration
375
-
376
- AIA uses the Lumberjack gem for logging and manages three separate loggers:
377
-
378
- | Logger | Purpose |
379
- |--------|---------|
380
- | `aia` | Used within the AIA codebase for application-level logging |
381
- | `llm` | Passed to the RubyLLM gem's configuration (`RubyLLM.logger`) |
382
- | `mcp` | Passed to the RubyLLM::MCP process (`RubyLLM::MCP.logger`) |
383
-
384
- ### Configuration File Settings
385
-
386
- Each logger can be configured independently in your `~/.config/aia/aia.yml`:
387
-
388
- ```yaml
389
- logger:
390
- aia:
391
- file: STDOUT # STDOUT, STDERR, or a file path (e.g., ~/.config/aia/aia.log)
392
- level: warn # debug, info, warn, error, fatal
393
- flush: true # true = immediate write, false = buffered
394
- llm:
395
- file: STDOUT
396
- level: warn
397
- flush: true
398
- mcp:
399
- file: STDOUT
400
- level: warn
401
- flush: true
402
- ```
403
-
404
- **Note**: All three loggers can safely write to the same file path. AIA handles multi-process safe file writes with automatic log file rotation (daily).
405
-
406
- ### CLI Log Level Override
407
-
408
- Command-line log level options override the config file settings for ALL loggers:
409
-
410
- ```bash
411
- # Set all loggers to debug level
412
- aia --debug my_prompt
413
-
414
- # Set all loggers to info level
415
- aia --info my_prompt
416
-
417
- # Set all loggers to warn level (default)
418
- aia --warn my_prompt
419
-
420
- # Set all loggers to error level
421
- aia --error my_prompt
422
-
423
- # Set all loggers to fatal level
424
- aia --fatal my_prompt
425
- ```
426
-
427
- ### Environment Variables
428
-
429
- Logger settings can also be configured via environment variables:
430
-
431
- ```bash
432
- # AIA logger settings
433
- export AIA_LOGGER__AIA__FILE="~/.config/aia/aia.log"
434
- export AIA_LOGGER__AIA__LEVEL="debug"
435
- export AIA_LOGGER__AIA__FLUSH="true"
436
-
437
- # LLM logger settings
438
- export AIA_LOGGER__LLM__FILE="STDOUT"
439
- export AIA_LOGGER__LLM__LEVEL="info"
440
-
441
- # MCP logger settings
442
- export AIA_LOGGER__MCP__FILE="STDERR"
443
- export AIA_LOGGER__MCP__LEVEL="warn"
444
- ```
445
-
446
- ### Log Levels
447
-
448
- | Level | Description |
449
- |-------|-------------|
450
- | `debug` | Most verbose - all messages including detailed debugging info |
451
- | `info` | Informational messages and above |
452
- | `warn` | Warnings, errors, and fatal messages (default) |
453
- | `error` | Only errors and fatal messages |
454
- | `fatal` | Least verbose - only critical/fatal messages |
455
-
456
- ### Example: File-Based Logging
457
-
458
- ```yaml
459
- # ~/.config/aia/aia.yml - Log everything to files
460
- logger:
461
- aia:
462
- file: ~/.config/aia/logs/aia.log
463
- level: info
464
- flush: true
465
- llm:
466
- file: ~/.config/aia/logs/llm.log
467
- level: debug
468
- flush: false
469
- mcp:
470
- file: ~/.config/aia/logs/mcp.log
471
- level: warn
472
- flush: true
473
- ```
474
-
475
- ## Advanced Configuration
476
-
477
- ### Multi-Model Configuration
478
-
479
- Configure multiple models with role assignments:
480
-
481
- ```yaml
482
- # Configure multiple models with roles
483
- models:
484
- - name: gpt-4o
485
- role: architect # Design and architecture decisions
486
- - name: claude-3-sonnet
487
- role: reviewer # Code review and analysis
488
- - name: gpt-4o-mini
489
- role: ~ # No specific role (general use)
490
- ```
491
-
492
- Use with: `aia --model "gpt-4o=architect,claude=reviewer" my_prompt`
493
-
494
- Or use the `--consensus` flag to combine responses:
495
- ```bash
496
- aia --model "gpt-4,claude-3-sonnet" --consensus my_prompt
497
- ```
498
-
499
- ### Tool Configuration
500
-
501
- Configure tool paths and permissions:
502
-
503
- ```yaml
504
- # Tool settings (nested structure)
505
- tools:
506
- paths:
507
- - ~/.config/aia/tools
508
- - /usr/local/share/aia-tools
509
- - ./project-tools
510
- allowed:
511
- - file_reader
512
- - web_scraper
513
- - calculator
514
- rejected:
515
- - system_admin
516
- - file_writer
517
- ```
518
-
519
- ### MCP Server Configuration
520
-
521
- Configure Model Context Protocol servers:
522
-
523
- ```yaml
524
- # MCP servers (array of server configurations)
525
- mcp_servers:
526
- - name: github
527
- command: /path/to/github-mcp-server
528
- args: []
529
- env:
530
- GITHUB_TOKEN: "${GITHUB_TOKEN}"
531
- timeout: 8000
532
-
533
- - name: filesystem
534
- command: mcp-server-filesystem
535
- args:
536
- - /allowed/path1
537
- - /allowed/path2
538
- ```
539
-
540
- ### Prompt Directory Structure
541
-
542
- Configure how AIA organizes prompts:
543
-
544
- ```yaml
545
- # Prompts configuration (nested structure)
546
- prompts:
547
- dir: ~/.prompts
548
- extname: .md
549
- roles_prefix: roles # ~/.prompts/roles/
550
- roles_dir: ~/.prompts/roles
551
- role: ~ # Default role (null = none)
552
- skills_prefix: ~ # Prefix appended to skills base (nil = unset, uses skills.dir directly)
553
- skills: [] # Default skills (empty = none)
554
- system_prompt: ~ # Default system prompt
555
- parameter_regex: ~ # Custom parameter extraction regex
556
-
557
- # Top-level directory shortcuts (expand ~ automatically)
558
- roles:
559
- dir: ~/.prompts/roles
560
-
561
- skills:
562
- dir: ~/.prompts/skills
563
- ```
564
-
565
- **Prompt assembly order**:
566
-
567
- In **pipeline mode** (default), each prompt text is assembled as:
568
- 1. **Role content** — identity and personality (`--role`)
569
- 2. **Skill content** — capabilities and approach (`--skill`, in declaration order)
570
- 3. **User prompt** — the actual request
571
-
572
- In **chat mode** (`--chat`), the system prompt is assembled once at startup:
573
- 1. **System prompt** — guardrails and constraints (`--system-prompt`)
574
- 2. **Role content** — identity and personality (`--role`)
575
- 3. **Skill content** — injected here so it persists across all turns without repetition
576
-
577
- Follow-up chat turns carry role and skill context implicitly via conversation history.
578
-
579
- **Recommended directory layout**:
580
- ```
581
- ~/.prompts/
582
- ├── roles/
583
- │ ├── ruby_expert.md # "You are a senior Ruby developer..."
584
- │ └── teacher.md
585
- ├── skills/
586
- │ ├── testing/
587
- │ │ └── SKILL.md # Skill ID: "testing"
588
- │ ├── debugging/
589
- │ │ └── SKILL.md # Skill ID: "debugging"
590
- │ └── refactoring/
591
- │ └── SKILL.md # Skill ID: "refactoring"
592
- └── my_prompt.md
593
- ```
594
-
595
- Each skill is a **subdirectory** containing a `SKILL.md` file. The skill ID is the subdirectory name. Subdirectories without `SKILL.md` and plain `.md` files are ignored by `--list-skills`.
596
-
597
- ## Configuration Examples
598
-
599
- ### Development Setup
600
-
601
- ```yaml
602
- # ~/.config/aia/aia.yml - Development setup
603
- llm:
604
- temperature: 0.3
605
-
606
- models:
607
- - name: gpt-4
608
-
609
- prompts:
610
- dir: ./prompts
611
-
612
- output:
613
- file: ./dev_output.md
614
-
615
- tools:
616
- paths:
617
- - ./tools
618
-
619
- flags:
620
- verbose: true
621
- debug: true
622
- ```
623
-
624
- ### Production Setup
625
-
626
- ```yaml
627
- # ~/.config/aia/aia.yml - Production setup
628
- llm:
629
- temperature: 0.7
630
-
631
- models:
632
- - name: gpt-4o-mini
633
-
634
- prompts:
635
- dir: /etc/aia/prompts
636
-
637
- output:
638
- history_file: /var/log/aia_history.log
639
-
640
- tools:
641
- paths:
642
- - /usr/share/aia-tools
643
- allowed:
644
- - safe_calculator
645
- - file_reader
646
-
647
- flags:
648
- verbose: false
649
- debug: false
650
- ```
651
-
652
- ### Creative Writing Setup
653
-
654
- ```yaml
655
- # ~/.config/aia/aia.yml - Creative writing
656
- llm:
657
- temperature: 1.1
658
- max_tokens: 4000
659
-
660
- models:
661
- - name: gpt-4
662
-
663
- output:
664
- file: ~/writing/aia_output.md
665
- append: true
666
- markdown: true
667
-
668
- audio:
669
- voice: nova
670
-
671
- flags:
672
- speak: true
673
- ```
674
-
675
- ## Validation and Troubleshooting
676
-
677
- ### Check Configuration
678
-
679
- Dump current configuration:
680
-
681
- ```bash
682
- aia --dump config.yaml
683
- ```
684
-
685
- ### Validate Settings
686
-
687
- ```bash
688
- # Test model access
689
- aia --available-models
690
-
691
- # Test configuration
692
- aia --debug --verbose hello_world
693
-
694
- # Test tools
695
- aia --tools ./my_tools --debug test_prompt
696
- ```
697
-
698
- ### Common Issues
699
-
700
- #### Model Not Found
701
- - Check your API keys are set
702
- - Verify the model name: `aia --available-models`
703
- - Check network connectivity
704
-
705
- #### Permission Errors
706
- - Verify file permissions on config directory
707
- - Check tool file permissions
708
- - Ensure API keys are correctly set
709
-
710
- #### Tool Loading Errors
711
- - Verify tool paths exist and are readable
712
- - Check Ruby syntax in tool files
713
- - Use `--debug` to see detailed error messages
714
-
715
- ## Configuration Migration
716
-
717
- ### Updating from Older Versions
718
-
719
- If upgrading from an earlier version of AIA, back up and recreate your configuration:
720
-
721
- ```bash
722
- # Backup current config
723
- cp ~/.config/aia/aia.yml ~/.config/aia/aia.yml.backup
724
-
725
- # Dump current running configuration as a starting point
726
- aia --dump ~/.config/aia/aia.yml
727
- ```
728
-
729
- Review the dumped file and merge any custom settings from your backup.
730
-
731
- ## Best Practices
732
-
733
- 1. **Use Environment Variables** for sensitive data like API keys
734
- 2. **Use Configuration Files** for stable settings
735
- 3. **Use Command Line Arguments** for temporary overrides
736
- 4. **Use Embedded Directives** for prompt-specific settings
737
- 5. **Version Control** your configuration (excluding secrets)
738
- 6. **Test Changes** with `--debug` and `--verbose` flags
739
- 7. **Document Custom Configurations** for team sharing
740
-
741
- ## Security Considerations
742
-
743
- - Never commit API keys to version control
744
- - Use restrictive file permissions on config files: `chmod 600 ~/.config/aia/aia.yml`
745
- - Limit tool access with `tools.allowed` in production
746
- - Use separate configurations for different environments
747
- - Regularly rotate API keys