aia 2.0.0.0.pre.beta2 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (225) hide show
  1. checksums.yaml +4 -4
  2. data/.version +1 -1
  3. data/CHANGELOG.md +146 -228
  4. data/README.md +41 -18
  5. data/bin/aia +8 -3
  6. data/lib/aia/aia_completion.bash +2 -3
  7. data/lib/aia/aia_completion.fish +6 -5
  8. data/lib/aia/aia_completion.zsh +2 -3
  9. data/lib/aia/chat_loop.rb +16 -14
  10. data/lib/aia/config/cli_parser.rb +123 -91
  11. data/lib/aia/config/defaults.yml +12 -39
  12. data/lib/aia/config/mcp_parser.rb +30 -36
  13. data/lib/aia/config/model_spec.rb +8 -14
  14. data/lib/aia/config/validator.rb +102 -103
  15. data/lib/aia/config/value_caster.rb +76 -0
  16. data/lib/aia/config.rb +70 -53
  17. data/lib/aia/crew.rb +29 -19
  18. data/lib/aia/debate_handler.rb +27 -10
  19. data/lib/aia/directives/configuration_directives.rb +55 -14
  20. data/lib/aia/directives/context_directives.rb +24 -12
  21. data/lib/aia/directives/execution_directives.rb +18 -23
  22. data/lib/aia/directives/model_directives.rb +41 -104
  23. data/lib/aia/directives/utility_directives.rb +16 -17
  24. data/lib/aia/directives/web_and_file_directives.rb +21 -14
  25. data/lib/aia/fact_asserter.rb +3 -3
  26. data/lib/aia/history_transfer.rb +64 -24
  27. data/lib/aia/logger.rb +10 -45
  28. data/lib/aia/mcp_config_normalizer.rb +27 -14
  29. data/lib/aia/mcp_connection_manager.rb +181 -184
  30. data/lib/aia/mcp_discovery.rb +43 -15
  31. data/lib/aia/mcp_grouper.rb +2 -1
  32. data/lib/aia/mcp_server_config.rb +20 -2
  33. data/lib/aia/mcp_utility.rb +24 -19
  34. data/lib/aia/mention_router.rb +15 -2
  35. data/lib/aia/modality_query.rb +36 -0
  36. data/lib/aia/model_alias_registry.rb +11 -11
  37. data/lib/aia/model_registry.rb +75 -0
  38. data/lib/aia/network_builder.rb +8 -7
  39. data/lib/aia/patches/ruby_llm_streaming_error.rb +21 -4
  40. data/lib/aia/patches/ruby_llm_tool_param_compat.rb +18 -0
  41. data/lib/aia/pipeline_orchestrator.rb +71 -38
  42. data/lib/aia/prompt_decomposer.rb +1 -1
  43. data/lib/aia/prompt_handler.rb +56 -29
  44. data/lib/aia/provider_registry.rb +105 -0
  45. data/lib/aia/robot_builder.rb +1 -1
  46. data/lib/aia/robot_factory.rb +67 -63
  47. data/lib/aia/robot_sync.rb +79 -0
  48. data/lib/aia/role_catalog.rb +89 -0
  49. data/lib/aia/session.rb +25 -11
  50. data/lib/aia/skill_utils.rb +60 -19
  51. data/lib/aia/spawn_handler.rb +16 -4
  52. data/lib/aia/spawn_spec_parser.rb +6 -7
  53. data/lib/aia/special_mode_handler.rb +28 -25
  54. data/lib/aia/speech.rb +70 -34
  55. data/lib/aia/startup_coordinator.rb +17 -92
  56. data/lib/aia/streaming_runner.rb +10 -2
  57. data/lib/aia/system_prompt_assembler.rb +12 -11
  58. data/lib/aia/task_board.rb +60 -0
  59. data/lib/aia/tool_approver.rb +205 -0
  60. data/lib/aia/tool_filter.rb +1 -10
  61. data/lib/aia/tool_filter_strategy.rb +12 -1
  62. data/lib/aia/tool_introspection.rb +9 -1
  63. data/lib/aia/tool_loader.rb +67 -33
  64. data/lib/aia/tool_utility.rb +6 -5
  65. data/lib/aia/tools/delegate_to_foreman_tool.rb +6 -4
  66. data/lib/aia/tools/recruit_robot_tool.rb +12 -12
  67. data/lib/aia/tools/reskill_robot_tool.rb +7 -7
  68. data/lib/aia/tools/task_board_tool.rb +16 -16
  69. data/lib/aia/trakflow_bridge.rb +14 -8
  70. data/lib/aia/turn_state.rb +31 -8
  71. data/lib/aia/ui_presenter.rb +16 -0
  72. data/lib/aia/utility.rb +6 -24
  73. data/lib/aia/variable_input_collector.rb +0 -3
  74. data/lib/aia/verification_network.rb +9 -10
  75. data/lib/aia.rb +33 -8
  76. metadata +19 -160
  77. data/.better-commits.json +0 -150
  78. data/.config/tocer/configuration.yml +0 -6
  79. data/.envrc +0 -19
  80. data/.loki +0 -11
  81. data/.reek.yml +0 -160
  82. data/.rubocop.yml +0 -116
  83. data/.rubocop_strict.yml +0 -15
  84. data/COMMITS.md +0 -196
  85. data/IMPLEMENTATION_PLAN.md +0 -506
  86. data/Rakefile +0 -47
  87. data/_typos.toml +0 -10
  88. data/aia.gemspec +0 -92
  89. data/architecture_review.md +0 -314
  90. data/config/aia.yml +0 -13
  91. data/docs/AGENTS.md +0 -40
  92. data/docs/advanced-prompting.md +0 -814
  93. data/docs/assets/images/aia.png +0 -0
  94. data/docs/cli-reference.md +0 -1241
  95. data/docs/configuration.md +0 -747
  96. data/docs/contributing.md +0 -386
  97. data/docs/directives-reference.md +0 -1145
  98. data/docs/examples/index.md +0 -277
  99. data/docs/examples/mcp/index.md +0 -475
  100. data/docs/examples/prompts/analysis/index.md +0 -78
  101. data/docs/examples/prompts/automation/index.md +0 -109
  102. data/docs/examples/prompts/development/index.md +0 -125
  103. data/docs/examples/prompts/index.md +0 -333
  104. data/docs/examples/prompts/learning/index.md +0 -127
  105. data/docs/examples/prompts/writing/index.md +0 -62
  106. data/docs/examples/tools/index.md +0 -282
  107. data/docs/faq.md +0 -578
  108. data/docs/guides/available-models.md +0 -366
  109. data/docs/guides/basic-usage.md +0 -478
  110. data/docs/guides/chat.md +0 -680
  111. data/docs/guides/crew.md +0 -239
  112. data/docs/guides/executable-prompts.md +0 -331
  113. data/docs/guides/first-prompt.md +0 -454
  114. data/docs/guides/getting-started.md +0 -455
  115. data/docs/guides/image-generation.md +0 -507
  116. data/docs/guides/index.md +0 -48
  117. data/docs/guides/local-models.md +0 -306
  118. data/docs/guides/migrate-prompts.md +0 -335
  119. data/docs/guides/models.md +0 -1017
  120. data/docs/guides/shared-tools.md +0 -254
  121. data/docs/guides/tools.md +0 -831
  122. data/docs/index.md +0 -259
  123. data/docs/installation.md +0 -274
  124. data/docs/mcp-integration.md +0 -603
  125. data/docs/prompt_management.md +0 -665
  126. data/docs/security.md +0 -674
  127. data/docs/special_projects_guide.md +0 -386
  128. data/docs/tools-and-mcp-examples.md +0 -1211
  129. data/docs/workflows-and-pipelines.md +0 -636
  130. data/examples/.gitignore +0 -2
  131. data/examples/00_setup_aia.sh +0 -111
  132. data/examples/01_basic_usage.sh +0 -23
  133. data/examples/02_frontmatter.sh +0 -33
  134. data/examples/03_shell_integration.sh +0 -55
  135. data/examples/04_erb_templating.sh +0 -56
  136. data/examples/05_shell_then_erb.sh +0 -38
  137. data/examples/06_prompt_chaining.sh +0 -59
  138. data/examples/07_pipeline.sh +0 -46
  139. data/examples/08_context_files.sh +0 -43
  140. data/examples/09_roles.sh +0 -67
  141. data/examples/10_stdin_piping.sh +0 -49
  142. data/examples/11_multi_model.sh +0 -65
  143. data/examples/12_token_usage.sh +0 -52
  144. data/examples/13_cost_tracking.sh +0 -68
  145. data/examples/14_output_file.sh +0 -91
  146. data/examples/15_parameters.sh +0 -68
  147. data/examples/16_directives.sh +0 -113
  148. data/examples/17_require_and_conditionals.sh +0 -68
  149. data/examples/18_tools.sh +0 -61
  150. data/examples/19_local_tools.sh +0 -34
  151. data/examples/20_mcp_servers.sh +0 -102
  152. data/examples/21_executable_prompts.sh +0 -78
  153. data/examples/22_chat_mode.sh +0 -217
  154. data/examples/23_verify.sh +0 -139
  155. data/examples/24_decompose.sh +0 -139
  156. data/examples/25_spawn.sh +0 -139
  157. data/examples/26_debate.sh +0 -97
  158. data/examples/27_mention_routing.sh +0 -157
  159. data/examples/28_model_switching.sh +0 -106
  160. data/examples/29_agent_harness.sh +0 -177
  161. data/examples/README.md +0 -321
  162. data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
  163. data/examples/aia_config.yml +0 -22
  164. data/examples/aia_config_orchestrator.yml +0 -45
  165. data/examples/aia_config_with_mcp.yml +0 -21
  166. data/examples/common.sh +0 -39
  167. data/examples/context/project_goals.md +0 -6
  168. data/examples/context/tech_stack.md +0 -7
  169. data/examples/directives/timestamp_directive.rb +0 -22
  170. data/examples/mcp/filesystem.json +0 -9
  171. data/examples/prompts_dir/analyze.md +0 -2
  172. data/examples/prompts_dir/brainstorm.md +0 -2
  173. data/examples/prompts_dir/conditional.md +0 -17
  174. data/examples/prompts_dir/creative.md +0 -4
  175. data/examples/prompts_dir/erbinfo.md +0 -5
  176. data/examples/prompts_dir/erbinfo_raw.md +0 -8
  177. data/examples/prompts_dir/evaluate.md +0 -2
  178. data/examples/prompts_dir/explain_joke.md +0 -1
  179. data/examples/prompts_dir/explain_recursion.md +0 -1
  180. data/examples/prompts_dir/fun_fact +0 -3
  181. data/examples/prompts_dir/greeting.md +0 -8
  182. data/examples/prompts_dir/greeting_required.md +0 -7
  183. data/examples/prompts_dir/hello.md +0 -1
  184. data/examples/prompts_dir/includes/ruby_facts.md +0 -4
  185. data/examples/prompts_dir/limerick.md +0 -1
  186. data/examples/prompts_dir/list_with_mcp.md +0 -3
  187. data/examples/prompts_dir/pick_best.md +0 -2
  188. data/examples/prompts_dir/project_summary +0 -12
  189. data/examples/prompts_dir/quiz_with_include.md +0 -6
  190. data/examples/prompts_dir/require_demo.md +0 -5
  191. data/examples/prompts_dir/roles/formal.md +0 -3
  192. data/examples/prompts_dir/roles/orchestrator.md +0 -21
  193. data/examples/prompts_dir/roles/pirate.md +0 -3
  194. data/examples/prompts_dir/shell_then_erb.md +0 -6
  195. data/examples/prompts_dir/sort_compare.md +0 -2
  196. data/examples/prompts_dir/summarize_context.md +0 -2
  197. data/examples/prompts_dir/sysinfo.md +0 -5
  198. data/examples/prompts_dir/sysinfo_raw.md +0 -8
  199. data/examples/prompts_dir/tagline.md +0 -1
  200. data/examples/prompts_dir/tell_joke.md +0 -1
  201. data/examples/prompts_dir/tell_joke_with_next.md +0 -4
  202. data/examples/prompts_dir/use_local_tool.md +0 -8
  203. data/examples/prompts_dir/use_tools.md +0 -8
  204. data/examples/prompts_dir/weather.md +0 -2
  205. data/examples/prompts_dir/whats_new.md +0 -2
  206. data/examples/prompts_dir/with_timestamp.md +0 -5
  207. data/examples/requirements/sinatra_taskflow_app.md +0 -139
  208. data/examples/rules/01_classify_ruby.rb +0 -16
  209. data/examples/rules/02_prefer_claude_for_code.rb +0 -19
  210. data/examples/rules/03_gate_prompt_length.rb +0 -19
  211. data/examples/rules/04_tool_selection.rb +0 -41
  212. data/examples/rules/README.md +0 -30
  213. data/examples/run_all.sh +0 -294
  214. data/examples/tools/word_count_tool.rb +0 -30
  215. data/lib/AGENTS.md +0 -57
  216. data/lib/aia/model_switch_handler.rb +0 -100
  217. data/mcp_servers/README.md +0 -110
  218. data/mcp_servers/apple-mcp.json +0 -8
  219. data/mcp_servers/filesystem.json +0 -9
  220. data/mcp_servers/mcp_server_chart.json +0 -11
  221. data/mcp_servers/playwright_one.json +0 -8
  222. data/mcp_servers/playwright_server_definition.json +0 -9
  223. data/mcp_servers/playwright_two.json +0 -8
  224. data/mcp_servers/tavily_mcp_server.json +0 -8
  225. data/mkdocs.yml +0 -169
data/docs/guides/tools.md DELETED
@@ -1,831 +0,0 @@
1
- # Tools Integration
2
-
3
- AIA's tools system extends AI capabilities with custom Ruby functions, enabling AI models to perform actions, access external services, and process data beyond text generation.
4
-
5
- ## Understanding Tools
6
-
7
- ### What are Tools?
8
- Tools are Ruby classes that inherit from `RubyLLM::Tool` and provide specific capabilities to AI models:
9
- - **File operations**: Read, write, analyze files
10
- - **Web interactions**: HTTP requests, API calls, web scraping
11
- - **Data processing**: Analysis, transformation, calculations
12
- - **System integration**: Shell commands, external services
13
- - **Custom logic**: Business-specific operations
14
-
15
- ### Tool Architecture
16
- ```ruby
17
- class MyTool < RubyLLM::Tool
18
- description "Brief description of what this tool does"
19
-
20
- def tool_method(parameter1, parameter2 = nil)
21
- # Tool implementation
22
- "Result that gets returned to the AI"
23
- end
24
-
25
- private
26
-
27
- def helper_method
28
- # Internal helper methods
29
- end
30
- end
31
- ```
32
-
33
- ## Using Existing Tools
34
-
35
- ### Enabling Tools
36
- ```bash
37
- # Use tools from a specific file
38
- aia --tools my_tool.rb my_prompt
39
-
40
- # Use all tools in a directory
41
- aia --tools ./tools/ my_prompt
42
-
43
- # Use multiple tool sources
44
- aia --tools "./tools/,./custom_tools.rb,/shared/tools/" my_prompt
45
- ```
46
-
47
- ### Tool Security
48
- ```bash
49
- # Restrict to specific tools
50
- aia --tools ./tools/ --allowed-tools "file_reader,calculator" my_prompt
51
-
52
- # Block dangerous tools
53
- aia --tools ./tools/ --rejected-tools "file_writer,system_admin" my_prompt
54
-
55
- # Combine restrictions
56
- aia --tools ./tools/ --allowed-tools "safe_tools" --rejected-tools "dangerous_tools" my_prompt
57
- ```
58
-
59
- ### Discovering Available Tools
60
- ```bash
61
- # List available tools
62
- aia --tools ./tools/ tool_discovery_prompt
63
-
64
- # Or within a prompt
65
- /tools
66
- ```
67
-
68
- ## Creating Custom Tools
69
-
70
- ### Basic Tool Structure
71
- ```ruby
72
- # ~/.config/aia/tools/file_analyzer.rb
73
- class FileAnalyzer < RubyLLM::Tool
74
- description "Analyzes files for structure, content, and metadata"
75
-
76
- def analyze_file(file_path, analysis_type = "basic")
77
- return "File not found: #{file_path}" unless File.exist?(file_path)
78
-
79
- case analysis_type
80
- when "basic"
81
- basic_analysis(file_path)
82
- when "detailed"
83
- detailed_analysis(file_path)
84
- when "security"
85
- security_analysis(file_path)
86
- else
87
- "Unknown analysis type: #{analysis_type}"
88
- end
89
- end
90
-
91
- def file_stats(file_path)
92
- return "File not found: #{file_path}" unless File.exist?(file_path)
93
-
94
- stat = File.stat(file_path)
95
- {
96
- size: stat.size,
97
- created: stat.ctime,
98
- modified: stat.mtime,
99
- permissions: stat.mode.to_s(8),
100
- type: File.directory?(file_path) ? "directory" : "file"
101
- }.to_json
102
- end
103
-
104
- private
105
-
106
- def basic_analysis(file_path)
107
- content = File.read(file_path)
108
- lines = content.lines.count
109
- words = content.split.count
110
- chars = content.length
111
-
112
- "File: #{File.basename(file_path)}\nLines: #{lines}\nWords: #{words}\nCharacters: #{chars}"
113
- end
114
-
115
- def detailed_analysis(file_path)
116
- basic = basic_analysis(file_path)
117
- content = File.read(file_path)
118
-
119
- # Language detection
120
- ext = File.extname(file_path).downcase
121
- language = detect_language(ext, content)
122
-
123
- # Additional analysis
124
- encoding = content.encoding.to_s
125
- blank_lines = content.lines.count(&:strip.empty?)
126
-
127
- "#{basic}\nLanguage: #{language}\nEncoding: #{encoding}\nBlank lines: #{blank_lines}"
128
- end
129
-
130
- def security_analysis(file_path)
131
- content = File.read(file_path)
132
- issues = []
133
-
134
- # Check for potential security issues
135
- issues << "Contains potential passwords" if content.match?(/password\s*=\s*["'][^"']+["']/i)
136
- issues << "Contains API keys" if content.match?(/api[_-]?key\s*[:=]\s*["'][^"']+["']/i)
137
- issues << "Contains hardcoded URLs" if content.match?/https?:\/\/[^\s]+/
138
- issues << "Contains TODO/FIXME items" if content.match?/(TODO|FIXME|HACK)/i
139
-
140
- if issues.empty?
141
- "No obvious security issues found in #{File.basename(file_path)}"
142
- else
143
- "Security concerns in #{File.basename(file_path)}:\n- #{issues.join("\n- ")}"
144
- end
145
- end
146
-
147
- def detect_language(ext, content)
148
- case ext
149
- when '.rb' then 'Ruby'
150
- when '.py' then 'Python'
151
- when '.js' then 'JavaScript'
152
- when '.java' then 'Java'
153
- when '.cpp', '.cc', '.cxx' then 'C++'
154
- when '.c' then 'C'
155
- when '.go' then 'Go'
156
- when '.rs' then 'Rust'
157
- else
158
- # Simple heuristics based on content
159
- return 'Ruby' if content.match?(/def\s+\w+|class\s+\w+|require ['"]/)
160
- return 'Python' if content.match?(/def \w+\(|import \w+|from \w+ import/)
161
- return 'JavaScript' if content.match?(/function\s+\w+|const\s+\w+|let\s+\w+/)
162
- 'Unknown'
163
- end
164
- end
165
- end
166
- ```
167
-
168
- ### Web Integration Tool
169
- ```ruby
170
- # ~/.config/aia/tools/web_client.rb
171
- require 'net/http'
172
- require 'json'
173
- require 'uri'
174
-
175
- class WebClient < RubyLLM::Tool
176
- description "Performs HTTP requests and web API interactions"
177
-
178
- def get_url(url, headers = {})
179
- uri = URI(url)
180
- http = Net::HTTP.new(uri.host, uri.port)
181
- http.use_ssl = true if uri.scheme == 'https'
182
-
183
- request = Net::HTTP::Get.new(uri)
184
- headers.each { |key, value| request[key] = value }
185
-
186
- response = http.request(request)
187
-
188
- {
189
- status: response.code,
190
- headers: response.to_hash,
191
- body: response.body
192
- }.to_json
193
- end
194
-
195
- def post_json(url, data, headers = {})
196
- uri = URI(url)
197
- http = Net::HTTP.new(uri.host, uri.port)
198
- http.use_ssl = true if uri.scheme == 'https'
199
-
200
- request = Net::HTTP::Post.new(uri)
201
- request['Content-Type'] = 'application/json'
202
- headers.each { |key, value| request[key] = value }
203
- request.body = data.to_json
204
-
205
- response = http.request(request)
206
-
207
- {
208
- status: response.code,
209
- body: response.body
210
- }.to_json
211
- end
212
-
213
- def check_url_status(url)
214
- uri = URI(url)
215
- http = Net::HTTP.new(uri.host, uri.port)
216
- http.use_ssl = true if uri.scheme == 'https'
217
- http.open_timeout = 10
218
- http.read_timeout = 10
219
-
220
- begin
221
- response = http.head(uri.path.empty? ? '/' : uri.path)
222
- "#{url}: #{response.code} #{response.message}"
223
- rescue => e
224
- "#{url}: Error - #{e.message}"
225
- end
226
- end
227
-
228
- def fetch_api_data(endpoint, api_key = nil, params = {})
229
- uri = URI(endpoint)
230
-
231
- # Add query parameters
232
- unless params.empty?
233
- uri.query = params.map { |k, v| "#{k}=#{v}" }.join('&')
234
- end
235
-
236
- http = Net::HTTP.new(uri.host, uri.port)
237
- http.use_ssl = true if uri.scheme == 'https'
238
-
239
- request = Net::HTTP::Get.new(uri)
240
- request['Authorization'] = "Bearer #{api_key}" if api_key
241
- request['User-Agent'] = 'AIA-Tools/1.0'
242
-
243
- response = http.request(request)
244
-
245
- if response.code == '200'
246
- JSON.parse(response.body)
247
- else
248
- { error: "API request failed", status: response.code, message: response.body }
249
- end
250
- rescue JSON::ParserError
251
- { error: "Invalid JSON response", raw_body: response.body }
252
- rescue => e
253
- { error: e.message }
254
- end
255
- end
256
- ```
257
-
258
- ### Data Analysis Tool
259
- ```ruby
260
- # ~/.config/aia/tools/data_analyzer.rb
261
- require 'csv'
262
- require 'json'
263
-
264
- class DataAnalyzer < RubyLLM::Tool
265
- description "Analyzes CSV data, JSON files, and performs statistical calculations"
266
-
267
- def analyze_csv(file_path, delimiter = ',')
268
- return "File not found: #{file_path}" unless File.exist?(file_path)
269
-
270
- begin
271
- data = CSV.read(file_path, headers: true, col_sep: delimiter)
272
-
273
- analysis = {
274
- rows: data.length,
275
- columns: data.headers.length,
276
- headers: data.headers,
277
- sample_data: data.first(3).map(&:to_h),
278
- column_types: analyze_column_types(data),
279
- missing_values: count_missing_values(data)
280
- }
281
-
282
- JSON.pretty_generate(analysis)
283
- rescue => e
284
- "Error analyzing CSV: #{e.message}"
285
- end
286
- end
287
-
288
- def calculate_statistics(file_path, column_name)
289
- return "File not found: #{file_path}" unless File.exist?(file_path)
290
-
291
- begin
292
- data = CSV.read(file_path, headers: true)
293
- values = data[column_name].compact.map(&:to_f)
294
-
295
- return "Column not found or no numeric data" if values.empty?
296
-
297
- stats = {
298
- count: values.length,
299
- mean: values.sum / values.length.to_f,
300
- median: median(values),
301
- min: values.min,
302
- max: values.max,
303
- range: values.max - values.min,
304
- std_dev: standard_deviation(values)
305
- }
306
-
307
- JSON.pretty_generate(stats)
308
- rescue => e
309
- "Error calculating statistics: #{e.message}"
310
- end
311
- end
312
-
313
- def find_correlations(file_path, columns = nil)
314
- return "File not found: #{file_path}" unless File.exist?(file_path)
315
-
316
- begin
317
- data = CSV.read(file_path, headers: true)
318
-
319
- # Get numeric columns
320
- numeric_columns = columns || data.headers.select do |header|
321
- data[header].compact.all? { |value| numeric?(value) }
322
- end
323
-
324
- correlations = {}
325
-
326
- numeric_columns.combination(2) do |col1, col2|
327
- values1 = data[col1].compact.map(&:to_f)
328
- values2 = data[col2].compact.map(&:to_f)
329
-
330
- if values1.length == values2.length && values1.length > 1
331
- corr = correlation(values1, values2)
332
- correlations["#{col1} vs #{col2}"] = corr.round(4)
333
- end
334
- end
335
-
336
- JSON.pretty_generate(correlations)
337
- rescue => e
338
- "Error calculating correlations: #{e.message}"
339
- end
340
- end
341
-
342
- def json_summary(file_path)
343
- return "File not found: #{file_path}" unless File.exist?(file_path)
344
-
345
- begin
346
- data = JSON.parse(File.read(file_path))
347
-
348
- summary = {
349
- type: data.class.name,
350
- structure: analyze_json_structure(data),
351
- size: data.respond_to?(:length) ? data.length : 1,
352
- keys: data.is_a?(Hash) ? data.keys : nil
353
- }
354
-
355
- JSON.pretty_generate(summary)
356
- rescue JSON::ParserError => e
357
- "Invalid JSON file: #{e.message}"
358
- rescue => e
359
- "Error analyzing JSON: #{e.message}"
360
- end
361
- end
362
-
363
- private
364
-
365
- def analyze_column_types(data)
366
- types = {}
367
- data.headers.each do |header|
368
- sample_values = data[header].compact.first(100)
369
-
370
- if sample_values.all? { |v| numeric?(v) }
371
- types[header] = 'numeric'
372
- elsif sample_values.all? { |v| date_like?(v) }
373
- types[header] = 'date'
374
- else
375
- types[header] = 'text'
376
- end
377
- end
378
- types
379
- end
380
-
381
- def count_missing_values(data)
382
- missing = {}
383
- data.headers.each do |header|
384
- missing_count = data[header].count { |v| v.nil? || v.strip.empty? }
385
- missing[header] = missing_count if missing_count > 0
386
- end
387
- missing
388
- end
389
-
390
- def numeric?(value)
391
- Float(value) rescue false
392
- end
393
-
394
- def date_like?(value)
395
- Date.parse(value) rescue false
396
- end
397
-
398
- def median(values)
399
- sorted = values.sort
400
- len = sorted.length
401
- len.even? ? (sorted[len/2 - 1] + sorted[len/2]) / 2.0 : sorted[len/2]
402
- end
403
-
404
- def standard_deviation(values)
405
- mean = values.sum / values.length.to_f
406
- variance = values.sum { |v| (v - mean) ** 2 } / values.length.to_f
407
- Math.sqrt(variance)
408
- end
409
-
410
- def correlation(x, y)
411
- n = x.length
412
- sum_x = x.sum
413
- sum_y = y.sum
414
- sum_x2 = x.sum { |v| v ** 2 }
415
- sum_y2 = y.sum { |v| v ** 2 }
416
- sum_xy = x.zip(y).sum { |a, b| a * b }
417
-
418
- numerator = n * sum_xy - sum_x * sum_y
419
- denominator = Math.sqrt((n * sum_x2 - sum_x ** 2) * (n * sum_y2 - sum_y ** 2))
420
-
421
- denominator == 0 ? 0 : numerator / denominator
422
- end
423
-
424
- def analyze_json_structure(data, max_depth = 3, current_depth = 0)
425
- return "..." if current_depth >= max_depth
426
-
427
- case data
428
- when Hash
429
- sample_keys = data.keys.first(5)
430
- structure = {}
431
- sample_keys.each do |key|
432
- structure[key] = analyze_json_structure(data[key], max_depth, current_depth + 1)
433
- end
434
- structure["..."] = "#{data.keys.length - 5} more keys" if data.keys.length > 5
435
- structure
436
- when Array
437
- return [] if data.empty?
438
- [analyze_json_structure(data.first, max_depth, current_depth + 1)]
439
- else
440
- data.class.name
441
- end
442
- end
443
- end
444
- ```
445
-
446
- ## Advanced Tool Patterns
447
-
448
- ### Tool with Configuration
449
- ```ruby
450
- class ConfigurableTool < RubyLLM::Tool
451
- description "Tool that can be configured for different environments"
452
-
453
- def initialize
454
- super
455
- @config = load_config
456
- end
457
-
458
- def process_data(input, environment = 'development')
459
- config = @config[environment]
460
- # Use environment-specific configuration
461
- process_with_config(input, config)
462
- end
463
-
464
- private
465
-
466
- def load_config
467
- config_file = File.join(Dir.home, '.aia', 'tool_config.yml')
468
- if File.exist?(config_file)
469
- YAML.load_file(config_file)
470
- else
471
- default_config
472
- end
473
- end
474
-
475
- def default_config
476
- {
477
- 'development' => { 'api_endpoint' => 'http://localhost:3000', 'timeout' => 30 },
478
- 'production' => { 'api_endpoint' => 'https://api.example.com', 'timeout' => 10 }
479
- }
480
- end
481
- end
482
- ```
483
-
484
- ### Tool with Caching
485
- ```ruby
486
- class CachedTool < RubyLLM::Tool
487
- description "Tool with intelligent caching for expensive operations"
488
-
489
- def expensive_operation(input)
490
- cache_key = Digest::MD5.hexdigest(input)
491
- cache_file = "/tmp/tool_cache_#{cache_key}.json"
492
-
493
- if File.exist?(cache_file) && fresh_cache?(cache_file)
494
- JSON.parse(File.read(cache_file))
495
- else
496
- result = perform_expensive_operation(input)
497
- File.write(cache_file, result.to_json)
498
- result
499
- end
500
- end
501
-
502
- private
503
-
504
- def fresh_cache?(cache_file, max_age = 3600)
505
- (Time.now - File.mtime(cache_file)) < max_age
506
- end
507
-
508
- def perform_expensive_operation(input)
509
- # Simulate expensive operation
510
- sleep 2
511
- { result: "Processed: #{input}", timestamp: Time.now }
512
- end
513
- end
514
- ```
515
-
516
- ### Error-Resilient Tool
517
- ```ruby
518
- class ResilientTool < RubyLLM::Tool
519
- description "Tool with comprehensive error handling and recovery"
520
-
521
- def reliable_operation(input, max_retries = 3)
522
- attempts = 0
523
-
524
- begin
525
- attempts += 1
526
- perform_operation(input)
527
- rescue StandardError => e
528
- if attempts <= max_retries
529
- wait_time = 2 ** attempts # Exponential backoff
530
- sleep wait_time
531
- retry
532
- else
533
- {
534
- error: true,
535
- message: "Operation failed after #{max_retries} attempts",
536
- last_error: e.message,
537
- suggestion: "Try with simpler input or check system resources"
538
- }.to_json
539
- end
540
- end
541
- end
542
-
543
- def safe_file_operation(file_path)
544
- return "File path required" if file_path.nil? || file_path.empty?
545
- return "File not found: #{file_path}" unless File.exist?(file_path)
546
- return "Access denied: #{file_path}" unless File.readable?(file_path)
547
-
548
- begin
549
- File.read(file_path)
550
- rescue => e
551
- "Error reading file: #{e.message}"
552
- end
553
- end
554
-
555
- private
556
-
557
- def perform_operation(input)
558
- # Simulate operation that might fail
559
- raise "Random failure" if rand < 0.3
560
- { success: true, data: "Processed #{input}" }
561
- end
562
- end
563
- ```
564
-
565
- ## Tool Integration in Prompts
566
-
567
- ### Basic Tool Usage
568
- ```markdown
569
- # ~/.prompts/file_analysis.md
570
- /tools file_analyzer.rb
571
-
572
- # File Analysis Report
573
-
574
- Please analyze the following file:
575
- File path: <%= file_path %>
576
-
577
- Use the file_analyzer tool to:
578
- 1. Get basic file statistics
579
- 2. Perform detailed content analysis
580
- 3. Check for security issues
581
-
582
- Provide a comprehensive report with recommendations.
583
- ```
584
-
585
- ### Multi-Tool Workflows
586
- ```markdown
587
- # ~/.prompts/web_data_analysis.md
588
- /tools web_client.rb,data_analyzer.rb
589
-
590
- # Web Data Analysis Pipeline
591
-
592
- Data source URL: <%= api_url %>
593
- API key: <%= api_key %>
594
-
595
- ## Step 1: Fetch Data
596
- Use the web_client tool to retrieve data from the API endpoint.
597
-
598
- ## Step 2: Save and Analyze
599
- Save the data to a temporary CSV file and use data_analyzer to:
600
- - Generate summary statistics
601
- - Identify data patterns
602
- - Find correlations
603
-
604
- ## Step 3: Generate Insights
605
- Based on the analysis, provide actionable insights and recommendations.
606
- ```
607
-
608
- ### Conditional Tool Usage
609
- ```ruby
610
- # ~/.prompts/adaptive_analysis.md
611
- /ruby
612
- input_file = '<%= input_file %>'
613
- file_ext = File.extname(input_file).downcase
614
-
615
- case file_ext
616
- when '.csv'
617
- puts "/tools data_analyzer.rb"
618
- analysis_type = "CSV data analysis"
619
- when '.json'
620
- puts "/tools data_analyzer.rb"
621
- analysis_type = "JSON structure analysis"
622
- when '.rb', '.py', '.js'
623
- puts "/tools file_analyzer.rb"
624
- analysis_type = "Code analysis"
625
- else
626
- puts "/tools file_analyzer.rb"
627
- analysis_type = "General file analysis"
628
- end
629
-
630
- puts "Selected #{analysis_type} for #{file_ext} file"
631
- ```
632
-
633
- Perform #{analysis_type} on: <%= input_file %>
634
-
635
- Provide detailed insights appropriate for the file type.
636
- ```
637
-
638
- ## Tool Security and Best Practices
639
-
640
- ### Security Guidelines
641
- 1. **Input Validation**: Always validate tool inputs
642
- 2. **File System Access**: Limit file access to safe directories
643
- 3. **Network Requests**: Validate URLs and handle errors
644
- 4. **Resource Limits**: Implement timeouts and size limits
645
- 5. **Error Handling**: Never expose system details in errors
646
-
647
- ### Performance Considerations
648
- 1. **Caching**: Cache expensive operations appropriately
649
- 2. **Timeouts**: Set reasonable timeouts for external calls
650
- 3. **Memory Management**: Handle large data sets efficiently
651
- 4. **Async Operations**: Use async patterns for I/O operations
652
- 5. **Resource Cleanup**: Properly clean up resources
653
-
654
- ### Testing Tools
655
- ```ruby
656
- # test_tool.rb
657
- require 'minitest/autorun'
658
- require_relative 'my_tool'
659
-
660
- class TestMyTool < Minitest::Test
661
- def setup
662
- @tool = MyTool.new
663
- end
664
-
665
- def test_basic_functionality
666
- result = @tool.process_data("test input")
667
- assert_kind_of String, result
668
- refute_empty result
669
- end
670
-
671
- def test_error_handling
672
- result = @tool.process_data(nil)
673
- assert_includes result, "error"
674
- end
675
- end
676
- ```
677
-
678
- ## Tool Distribution and Sharing
679
-
680
- ### Tool Libraries
681
- ```bash
682
- # Organize tools in libraries
683
- ~/.config/aia/tools/
684
- ├── core/ # Essential tools
685
- │ ├── file_ops.rb
686
- │ ├── web_client.rb
687
- │ └── data_analysis.rb
688
- ├── development/ # Development tools
689
- │ ├── code_analyzer.rb
690
- │ ├── test_runner.rb
691
- │ └── deploy_helper.rb
692
- └── specialized/ # Domain-specific tools
693
- ├── finance_tools.rb
694
- ├── media_tools.rb
695
- └── science_tools.rb
696
- ```
697
-
698
- ### Tool Documentation
699
- ```ruby
700
- class DocumentedTool < RubyLLM::Tool
701
- description "Example of well-documented tool with usage examples"
702
-
703
- # Processes input data with specified options
704
- # @param input [String] The input data to process
705
- # @param format [String] Output format: 'json', 'csv', or 'text'
706
- # @param options [Hash] Additional processing options
707
- # @return [String] Processed data in specified format
708
- # @example
709
- # process_data("sample", "json", { detailed: true })
710
- def process_data(input, format = 'text', options = {})
711
- # Implementation
712
- end
713
- end
714
- ```
715
-
716
- ## Troubleshooting Tools
717
-
718
- ### Common Issues
719
- 1. **Tool Not Found**: Check tool file paths and syntax
720
- 2. **Permission Errors**: Verify file permissions and access rights
721
- 3. **Missing Dependencies**: Install required gems and libraries
722
- 4. **Method Errors**: Check method signatures and parameters
723
- 5. **Runtime Errors**: Add proper error handling and logging
724
-
725
- ### Debugging Tools
726
- ```ruby
727
- class DebuggingTool < RubyLLM::Tool
728
- description "Tool with extensive debugging capabilities"
729
-
730
- def debug_operation(input)
731
- debug_log("Starting operation with input: #{input}")
732
-
733
- begin
734
- result = process_input(input)
735
- debug_log("Operation successful: #{result}")
736
- result
737
- rescue => e
738
- debug_log("Operation failed: #{e.message}")
739
- debug_log("Backtrace: #{e.backtrace.first(5).join("\n")}")
740
- raise
741
- end
742
- end
743
-
744
- private
745
-
746
- def debug_log(message)
747
- timestamp = Time.now.strftime("%Y-%m-%d %H:%M:%S")
748
- puts "[DEBUG #{timestamp}] #{message}" if debug_mode?
749
- end
750
-
751
- def debug_mode?
752
- ENV['AIA_FLAGS__DEBUG'] == 'true'
753
- end
754
- end
755
- ```
756
-
757
- ## MCP Client Integration
758
-
759
- ### Model Context Protocol (MCP) Support
760
-
761
- AIA supports MCP clients for extended functionality through external services:
762
-
763
- #### GitHub MCP Server
764
- ```bash
765
- # Install GitHub MCP server
766
- brew install github-mcp-server
767
-
768
- # Set required environment variable
769
- export GITHUB_PERSONAL_ACCESS_TOKEN="your_token_here"
770
-
771
- # Use with AIA
772
- aia --tools examples/tools/mcp/github_mcp_server.rb --chat
773
- ```
774
-
775
- **Capabilities:**
776
- - Repository analysis and management
777
- - Issue tracking and manipulation
778
- - Pull request automation
779
- - Code review assistance
780
- - Project metrics and insights
781
-
782
- #### iMCP for macOS
783
- ```bash
784
- # Install iMCP (macOS only)
785
- brew install --cask loopwork/tap/iMCP
786
-
787
- # Use with AIA
788
- aia --tools examples/tools/mcp/imcp.rb --chat
789
- ```
790
-
791
- **Capabilities:**
792
- - Access to macOS Notes app
793
- - Calendar integration
794
- - Contacts management
795
- - System information access
796
- - File system operations
797
-
798
- ### MCP Client Requirements
799
-
800
- MCP clients require:
801
- - The `ruby_llm-mcp` gem (automatically included with AIA)
802
- - Proper MCP server installation and configuration
803
- - Required environment variables and permissions
804
- - Network access for external MCP servers
805
-
806
- ## Shared Tools Collection
807
-
808
- AIA can use the [shared_tools gem](https://github.com/madbomber/shared_tools) which provides a curated collection of ready-to-use tools for LLM-assisted workflows including calculators, web browsing, database access, file operations, DNS lookups, and more.
809
-
810
- ```bash
811
- # Load all shared tools
812
- aia --require shared_tools --chat
813
-
814
- # List available shared tools
815
- aia --require shared_tools --list-tools
816
- ```
817
-
818
- See the **[Shared Tools Guide](shared-tools.md)** for installation, usage, and a complete reference of all available tools.
819
-
820
- ## Related Documentation
821
-
822
- - [Chat Mode](chat.md) - Using tools in interactive mode
823
- - [Advanced Prompting](../advanced-prompting.md) - Complex tool integration patterns
824
- - [MCP Integration](../mcp-integration.md) - Model Context Protocol details
825
- - [Configuration](../configuration.md) - Tool configuration options
826
- - [CLI Reference](../cli-reference.md) - Tool-related command-line options
827
- - [Examples](../examples/tools/index.md) - Real-world tool examples
828
-
829
- ---
830
-
831
- Tools transform AIA from a text processor into a powerful automation platform. Start with simple tools and gradually build more sophisticated capabilities as your needs grow!