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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +152 -223
- data/README.md +41 -18
- data/bin/aia +8 -3
- data/lib/aia/aia_completion.bash +2 -3
- data/lib/aia/aia_completion.fish +6 -5
- data/lib/aia/aia_completion.zsh +2 -3
- data/lib/aia/chat_loop.rb +16 -14
- data/lib/aia/config/cli_parser.rb +123 -91
- data/lib/aia/config/defaults.yml +18 -40
- data/lib/aia/config/mcp_parser.rb +30 -36
- data/lib/aia/config/model_spec.rb +8 -14
- data/lib/aia/config/validator.rb +102 -103
- data/lib/aia/config/value_caster.rb +76 -0
- data/lib/aia/config.rb +70 -53
- data/lib/aia/crew.rb +29 -19
- data/lib/aia/debate_handler.rb +27 -10
- data/lib/aia/directives/configuration_directives.rb +55 -14
- data/lib/aia/directives/context_directives.rb +24 -12
- data/lib/aia/directives/execution_directives.rb +18 -23
- data/lib/aia/directives/model_directives.rb +41 -104
- data/lib/aia/directives/utility_directives.rb +16 -17
- data/lib/aia/directives/web_and_file_directives.rb +21 -14
- data/lib/aia/fact_asserter.rb +3 -3
- data/lib/aia/history_transfer.rb +64 -24
- data/lib/aia/logger.rb +14 -46
- data/lib/aia/mcp_config_normalizer.rb +27 -14
- data/lib/aia/mcp_connection_manager.rb +181 -184
- data/lib/aia/mcp_discovery.rb +43 -15
- data/lib/aia/mcp_grouper.rb +2 -1
- data/lib/aia/mcp_server_config.rb +20 -2
- data/lib/aia/mcp_utility.rb +24 -19
- data/lib/aia/mention_router.rb +15 -2
- data/lib/aia/modality_query.rb +36 -0
- data/lib/aia/model_alias_registry.rb +11 -11
- data/lib/aia/model_registry.rb +75 -0
- data/lib/aia/network_builder.rb +8 -7
- data/lib/aia/patches/mcp_stdio_stderr.rb +102 -0
- data/lib/aia/patches/ruby_llm_streaming_error.rb +21 -4
- data/lib/aia/patches/ruby_llm_tool_param_compat.rb +18 -0
- data/lib/aia/pipeline_orchestrator.rb +71 -38
- data/lib/aia/prompt_decomposer.rb +1 -1
- data/lib/aia/prompt_handler.rb +56 -29
- data/lib/aia/provider_registry.rb +105 -0
- data/lib/aia/robot_builder.rb +1 -1
- data/lib/aia/robot_factory.rb +67 -63
- data/lib/aia/robot_sync.rb +79 -0
- data/lib/aia/role_catalog.rb +89 -0
- data/lib/aia/session.rb +25 -11
- data/lib/aia/skill_utils.rb +60 -19
- data/lib/aia/spawn_handler.rb +16 -4
- data/lib/aia/spawn_spec_parser.rb +6 -7
- data/lib/aia/special_mode_handler.rb +28 -25
- data/lib/aia/speech.rb +70 -34
- data/lib/aia/startup_coordinator.rb +17 -92
- data/lib/aia/streaming_runner.rb +10 -2
- data/lib/aia/system_prompt_assembler.rb +12 -11
- data/lib/aia/task_board.rb +60 -0
- data/lib/aia/tool_approver.rb +205 -0
- data/lib/aia/tool_filter.rb +1 -10
- data/lib/aia/tool_filter_strategy.rb +12 -1
- data/lib/aia/tool_introspection.rb +9 -1
- data/lib/aia/tool_loader.rb +67 -33
- data/lib/aia/tool_utility.rb +6 -5
- data/lib/aia/tools/delegate_to_foreman_tool.rb +6 -4
- data/lib/aia/tools/recruit_robot_tool.rb +12 -12
- data/lib/aia/tools/reskill_robot_tool.rb +7 -7
- data/lib/aia/tools/task_board_tool.rb +16 -16
- data/lib/aia/trakflow_bridge.rb +14 -8
- data/lib/aia/turn_state.rb +31 -8
- data/lib/aia/ui_presenter.rb +16 -0
- data/lib/aia/utility.rb +6 -24
- data/lib/aia/variable_input_collector.rb +0 -3
- data/lib/aia/verification_network.rb +9 -10
- data/lib/aia/version.rb +1 -9
- data/lib/aia.rb +34 -8
- metadata +20 -161
- data/.better-commits.json +0 -150
- data/.config/tocer/configuration.yml +0 -6
- data/.envrc +0 -19
- data/.loki +0 -11
- data/.reek.yml +0 -160
- data/.rubocop.yml +0 -116
- data/.rubocop_strict.yml +0 -15
- data/.version +0 -1
- data/COMMITS.md +0 -196
- data/IMPLEMENTATION_PLAN.md +0 -506
- data/Rakefile +0 -47
- data/_typos.toml +0 -10
- data/aia.gemspec +0 -92
- data/architecture_review.md +0 -314
- data/config/aia.yml +0 -13
- data/docs/AGENTS.md +0 -40
- data/docs/advanced-prompting.md +0 -814
- data/docs/assets/images/aia.png +0 -0
- data/docs/cli-reference.md +0 -1241
- data/docs/configuration.md +0 -747
- data/docs/contributing.md +0 -386
- data/docs/directives-reference.md +0 -1145
- data/docs/examples/index.md +0 -277
- data/docs/examples/mcp/index.md +0 -475
- data/docs/examples/prompts/analysis/index.md +0 -78
- data/docs/examples/prompts/automation/index.md +0 -109
- data/docs/examples/prompts/development/index.md +0 -125
- data/docs/examples/prompts/index.md +0 -333
- data/docs/examples/prompts/learning/index.md +0 -127
- data/docs/examples/prompts/writing/index.md +0 -62
- data/docs/examples/tools/index.md +0 -282
- data/docs/faq.md +0 -578
- data/docs/guides/available-models.md +0 -366
- data/docs/guides/basic-usage.md +0 -478
- data/docs/guides/chat.md +0 -680
- data/docs/guides/crew.md +0 -239
- data/docs/guides/executable-prompts.md +0 -331
- data/docs/guides/first-prompt.md +0 -454
- data/docs/guides/getting-started.md +0 -455
- data/docs/guides/image-generation.md +0 -507
- data/docs/guides/index.md +0 -48
- data/docs/guides/local-models.md +0 -306
- data/docs/guides/migrate-prompts.md +0 -335
- data/docs/guides/models.md +0 -1017
- data/docs/guides/shared-tools.md +0 -254
- data/docs/guides/tools.md +0 -831
- data/docs/index.md +0 -259
- data/docs/installation.md +0 -274
- data/docs/mcp-integration.md +0 -603
- data/docs/prompt_management.md +0 -665
- data/docs/security.md +0 -674
- data/docs/special_projects_guide.md +0 -386
- data/docs/tools-and-mcp-examples.md +0 -1211
- data/docs/workflows-and-pipelines.md +0 -636
- data/examples/.gitignore +0 -2
- data/examples/00_setup_aia.sh +0 -111
- data/examples/01_basic_usage.sh +0 -23
- data/examples/02_frontmatter.sh +0 -33
- data/examples/03_shell_integration.sh +0 -55
- data/examples/04_erb_templating.sh +0 -56
- data/examples/05_shell_then_erb.sh +0 -38
- data/examples/06_prompt_chaining.sh +0 -59
- data/examples/07_pipeline.sh +0 -46
- data/examples/08_context_files.sh +0 -43
- data/examples/09_roles.sh +0 -67
- data/examples/10_stdin_piping.sh +0 -49
- data/examples/11_multi_model.sh +0 -65
- data/examples/12_token_usage.sh +0 -52
- data/examples/13_cost_tracking.sh +0 -68
- data/examples/14_output_file.sh +0 -91
- data/examples/15_parameters.sh +0 -68
- data/examples/16_directives.sh +0 -113
- data/examples/17_require_and_conditionals.sh +0 -68
- data/examples/18_tools.sh +0 -61
- data/examples/19_local_tools.sh +0 -34
- data/examples/20_mcp_servers.sh +0 -102
- data/examples/21_executable_prompts.sh +0 -78
- data/examples/22_chat_mode.sh +0 -217
- data/examples/23_verify.sh +0 -139
- data/examples/24_decompose.sh +0 -139
- data/examples/25_spawn.sh +0 -139
- data/examples/26_debate.sh +0 -97
- data/examples/27_mention_routing.sh +0 -157
- data/examples/28_model_switching.sh +0 -106
- data/examples/29_agent_harness.sh +0 -177
- data/examples/README.md +0 -321
- data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
- data/examples/aia_config.yml +0 -22
- data/examples/aia_config_orchestrator.yml +0 -45
- data/examples/aia_config_with_mcp.yml +0 -21
- data/examples/common.sh +0 -39
- data/examples/context/project_goals.md +0 -6
- data/examples/context/tech_stack.md +0 -7
- data/examples/directives/timestamp_directive.rb +0 -22
- data/examples/mcp/filesystem.json +0 -9
- data/examples/prompts_dir/analyze.md +0 -2
- data/examples/prompts_dir/brainstorm.md +0 -2
- data/examples/prompts_dir/conditional.md +0 -17
- data/examples/prompts_dir/creative.md +0 -4
- data/examples/prompts_dir/erbinfo.md +0 -5
- data/examples/prompts_dir/erbinfo_raw.md +0 -8
- data/examples/prompts_dir/evaluate.md +0 -2
- data/examples/prompts_dir/explain_joke.md +0 -1
- data/examples/prompts_dir/explain_recursion.md +0 -1
- data/examples/prompts_dir/fun_fact +0 -3
- data/examples/prompts_dir/greeting.md +0 -8
- data/examples/prompts_dir/greeting_required.md +0 -7
- data/examples/prompts_dir/hello.md +0 -1
- data/examples/prompts_dir/includes/ruby_facts.md +0 -4
- data/examples/prompts_dir/limerick.md +0 -1
- data/examples/prompts_dir/list_with_mcp.md +0 -3
- data/examples/prompts_dir/pick_best.md +0 -2
- data/examples/prompts_dir/project_summary +0 -12
- data/examples/prompts_dir/quiz_with_include.md +0 -6
- data/examples/prompts_dir/require_demo.md +0 -5
- data/examples/prompts_dir/roles/formal.md +0 -3
- data/examples/prompts_dir/roles/orchestrator.md +0 -21
- data/examples/prompts_dir/roles/pirate.md +0 -3
- data/examples/prompts_dir/shell_then_erb.md +0 -6
- data/examples/prompts_dir/sort_compare.md +0 -2
- data/examples/prompts_dir/summarize_context.md +0 -2
- data/examples/prompts_dir/sysinfo.md +0 -5
- data/examples/prompts_dir/sysinfo_raw.md +0 -8
- data/examples/prompts_dir/tagline.md +0 -1
- data/examples/prompts_dir/tell_joke.md +0 -1
- data/examples/prompts_dir/tell_joke_with_next.md +0 -4
- data/examples/prompts_dir/use_local_tool.md +0 -8
- data/examples/prompts_dir/use_tools.md +0 -8
- data/examples/prompts_dir/weather.md +0 -2
- data/examples/prompts_dir/whats_new.md +0 -2
- data/examples/prompts_dir/with_timestamp.md +0 -5
- data/examples/requirements/sinatra_taskflow_app.md +0 -139
- data/examples/rules/01_classify_ruby.rb +0 -16
- data/examples/rules/02_prefer_claude_for_code.rb +0 -19
- data/examples/rules/03_gate_prompt_length.rb +0 -19
- data/examples/rules/04_tool_selection.rb +0 -41
- data/examples/rules/README.md +0 -30
- data/examples/run_all.sh +0 -294
- data/examples/tools/word_count_tool.rb +0 -30
- data/lib/AGENTS.md +0 -57
- data/lib/aia/model_switch_handler.rb +0 -100
- data/mcp_servers/README.md +0 -110
- data/mcp_servers/apple-mcp.json +0 -8
- data/mcp_servers/filesystem.json +0 -9
- data/mcp_servers/mcp_server_chart.json +0 -11
- data/mcp_servers/playwright_one.json +0 -8
- data/mcp_servers/playwright_server_definition.json +0 -9
- data/mcp_servers/playwright_two.json +0 -8
- data/mcp_servers/tavily_mcp_server.json +0 -8
- 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!
|