ox-ai-workers 0.9.3.1 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0e2cfa9b2f611dc00729dfff984e91b4b3977703d91f360f80ff4625013cccc
-  data.tar.gz: fe2e37c5fc822a1a661f36b421f511f24c4979962ab4d67e79912d0101ace732
+  metadata.gz: '09fdb6954c507cc0d70433141a70a4974b42feb625719c525d2b7c093d9e1ce5'
+  data.tar.gz: e93b4e8040e831c73d8dd0379466f70e48eafd07513d7e78fee3f19985ef4331
 SHA512:
-  metadata.gz: ab9b3e707484c1607ad46ba9cecaedc19d9e673aa4e3a17564402e5b80e8d63617a62842176eb01aea46e29e98b9b2c6e63861cb5ad82470581fc2ba379606a6
-  data.tar.gz: ceba0647dbbcc2a1cde6b34963d7f3a7f6d9d0c299826bd06891c03d6501c3edb6f3e9eecc3f84c155f61bc70deb613897c8c6ae7e62c41084784b3e5688c0b8
+  metadata.gz: c7b1f5a861cc8b4536fd22d6dbe479f0886ebb260317d585bf80ba19c0b1e5dbb6d9c5998ab1e25f367a112a5a7e3dce6bca1a48d2edecb9a6db8af3aa19b1bb
+  data.tar.gz: d7e64a09aa0351a62fdb74c52a25c99db79a4fd7c2765001cd715e8ac32deb6cd2b81aef5e385e57c66aa4b9fb3ef616145eb7953e5eefadc3321ae9678e697f

data/.cursor/rules/010-project-structure.mdc

@@ -0,0 +1,89 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Overview
+
+OxAiWorkers is a Ruby gem that implements a finite state machine (FSM, using the `state_machine` gem) to solve tasks using generative intelligence. This approach enhances the final result by utilizing internal monologue and external tools.
+
+## Core Components
+
+- `Request` and `DelayedRequest` - classes for executing API requests (immediate and delayed)
+- `ModuleRequest` - base class for all API requests with parsing and response handling ([module_request.rb](mdc:lib/oxaiworkers/module_request.rb))
+- `Iterator` - main class for iterative task execution with tools ([iterator.rb](mdc:lib/oxaiworkers/iterator.rb))
+- `Assistant::ModuleBase` - high-level wrappers over Iterator (Sysop, Coder, Localizer, etc.) ([module_base.rb](mdc:lib/oxaiworkers/assistant/module_base.rb))
+- `Tool` - tools that can be used during task execution (Eval, FileSystem, Database, Pixels, Pipeline)
+- `ToolDefinition` - module for declaring functions and methods for tools ([tool_definition.rb](mdc:lib/oxaiworkers/tool_definition.rb))
+- `StateTools` - base class for managing states and transitions ([state_tools.rb](mdc:lib/oxaiworkers/state_tools.rb))
+- `ContextualLogger` - logging system with contextual information support
+
+## Code Conventions
+
+- Use `snake_case` for method and variable names
+- All code comments, CHANGELOG, README, and other documentation must be written in English
+
+## Interaction Patterns
+
+- The system uses internal monologue (inner_monologue) for planning actions
+- External voice (outer_voice) is used for communication with the user
+- Execution flow management through finite state machine
+- Implementation of callback mechanisms for flexible event handling
+
+## Tools Architecture
+
+- Each tool should be a self-contained module
+- Tools are registered through the `define_function` interface
+- All tools should handle their own errors and return readable messages
+- Handle errors at the tool level, preventing them from interrupting the main execution flow
+
+## Finite State Machine Implementation
+
+- Core FSM based on `state_machine` gem with states: idle → prepared → requested → analyzed → finished → idle
+- State transitions managed by events: prepare, request, analyze, complete, iterate, end ([state_tools.rb](mdc:lib/oxaiworkers/state_tools.rb), [iterator.rb](mdc:lib/oxaiworkers/iterator.rb))
+- `StateTools` - base class for FSM implementation with event hooks and transition callbacks ([state_tools.rb](mdc:lib/oxaiworkers/state_tools.rb))
+- `StateBatch` - FSM extension for batch request processing with additional states
+- Automatic error recovery and retry mechanisms for failed API requests
+
+## Iterator Lifecycle
+
+- 3 core functions: inner_monologue, outer_voice, finish_it ([iterator.rb](mdc:lib/oxaiworkers/iterator.rb))
+- Configurable message queue for stateful conversation history
+- Callback system for processing each state transition
+- Context and milestone management for optimizing token usage
+- Support for custom steps and instruction templating
+
+## Assistants Details
+
+- `ModuleBase` - shared functionality for all assistant types ([module_base.rb](mdc:lib/oxaiworkers/assistant/module_base.rb))
+- `Sysop` - system administration and shell command execution ([sysop.rb](mdc:lib/oxaiworkers/assistant/sysop.rb), [file_system.rb](mdc:lib/oxaiworkers/tool/file_system.rb))
+- `Coder` - specialized for code generation and analysis ([coder.rb](mdc:lib/oxaiworkers/assistant/coder.rb), [eval.rb](mdc:lib/oxaiworkers/tool/eval.rb))
+- `Localizer` - translation and localization support ([localizer.rb](mdc:lib/oxaiworkers/assistant/localizer.rb))
+- `Orchestrator` - Coordinates multiple assistants to work together on complex tasks ([orchestrator.rb](mdc:lib/oxaiworkers/assistant/orchestrator.rb), [pipeline.rb](mdc:lib/oxaiworkers/tool/pipeline.rb))
+- `Painter` - Image generation and manipulation ([painter.rb](mdc:lib/oxaiworkers/assistant/painter.rb), [pixels.rb](mdc:lib/oxaiworkers/tool/pixels.rb))
+
+## Internationalization and Localization
+
+- All user-facing strings MUST be properly localized using I18n (config/locales/*.yml)
+- Use I18n.t for all text that will be shown to users or appears in assistant prompts
+- Store translations in YAML files within the config/locales directory
+- Follow the naming convention of language.namespace.key (e.g., en.oxaiworkers.assistant.role)
+- Use named parameters (%{variable}) instead of positional parameters (%s) in translation strings
+- Use the with_locale method to ensure proper locale context when processing localized text
+- Implement locale-aware classes by including the OxAiWorkers::LoadI18n module
+- Store the current locale on initialization and preserve it across method calls
+- Support multiple languages simultaneously through careful locale management
+- Default to English for developer-facing messages and logs
+- Ensure that all assistant classes properly handle localization in their format_role methods
+
+## LoadI18n Module Usage
+
+- The `OxAiWorkers::LoadI18n` module provides two key methods for localization:
+  - `store_locale` - saves the current locale at initialization time
+  - `with_locale` - executes a block of code in the context of the saved locale
+- Always include the `OxAiWorkers::LoadI18n` module in classes that need localization capabilities
+- Call `store_locale` in the initialization methods of locale-aware classes
+- Wrap all locale-dependent code in `with_locale` blocks
+- NEVER redefine the `with_locale` method in classes that include LoadI18n
+- All methods that produce user-visible text must use the locale context via `with_locale` blocks
+- Regular method calls from classes including LoadI18n do not require additional locale handling

data/.cursor/rules/998-clean-code.mdc

@@ -0,0 +1,52 @@
+---
+description: Guidelines for writing clean, maintainable, and human-readable code. Apply these rules when writing or reviewing code to ensure consistency and quality.
+globs: 
+alwaysApply: false
+---
+# Clean Code Guidelines
+
+## Constants Over Magic Numbers
+- Replace hard-coded values with named constants
+- Use descriptive constant names that explain the value's purpose
+- Keep constants at the top of the file or in a dedicated constants file
+
+## Meaningful Names
+- Variables, functions, and classes should reveal their purpose
+- Names should explain why something exists and how it's used
+- Avoid abbreviations unless they're universally understood
+
+## Smart Comments
+- Don't comment on what the code does - make the code self-documenting
+- Use comments to explain why something is done a certain way
+- Document APIs, complex algorithms, and non-obvious side effects
+
+## Single Responsibility
+- Each function should do exactly one thing
+- Functions should be small and focused
+- If a function needs a comment to explain what it does, it should be split
+
+## DRY (Don't Repeat Yourself)
+- Extract repeated code into reusable functions
+- Share common logic through proper abstraction
+- Maintain single sources of truth
+
+## Clean Structure
+- Keep related code together
+- Organize code in a logical hierarchy
+- Use consistent file and folder naming conventions
+
+## Encapsulation
+- Hide implementation details
+- Expose clear interfaces
+- Move nested conditionals into well-named functions
+
+## Code Quality Maintenance
+- Refactor continuously
+- Fix technical debt early
+- Leave code cleaner than you found it
+- Follow the "Fail fast" principle for early error detection
+
+## Version Control
+- Write clear commit messages
+- Make small, focused commits
+- Use meaningful branch names 

data/.cursor/rules/999-mdc-format.mdc

@@ -0,0 +1,132 @@
+---
+description: 
+globs: *.mdc,**/*.mdc
+alwaysApply: false
+---
+# MDC File Format Guide
+
+MDC (Markdown Configuration) files are used by Cursor to provide context-specific instructions to AI assistants. This guide explains how to create and maintain these files properly.
+
+## File Structure
+
+Each MDC file consists of two main parts:
+
+1. **Frontmatter** - Configuration metadata at the top of the file
+2. **Markdown Content** - The actual instructions in Markdown format
+
+### Frontmatter
+
+The frontmatter must be the first thing in the file and must be enclosed between triple-dash lines (`---`). Configuration should be based on the intended behavior:
+
+```
+---
+# Configure your rule based on desired behavior:
+
+description: Brief description of what the rule does
+globs: **/*.js, **/*.ts  # Optional: Comma-separated list, not an array
+alwaysApply: false       # Set to true for global rules
+---
+```
+
+> **Important**: Despite the appearance, the frontmatter is not strictly YAML formatted. The `globs` field is a comma-separated list and should NOT include brackets `[]` or quotes `"`.
+
+#### Guidelines for Setting Fields
+
+- **description**: Should be agent-friendly and clearly describe when the rule is relevant. Format as `<topic>: <details>` for best results.
+- **globs**: 
+  - If a rule is only relevant in very specific situations, leave globs empty so it's loaded only when applicable to the user request.
+  - If the only glob would match all files (like `**/*`), leave it empty and set `alwaysApply: true` instead.
+  - Otherwise, be as specific as possible with glob patterns to ensure rules are only applied with relevant files.
+- **alwaysApply**: Use sparingly for truly global guidelines.
+
+#### Glob Pattern Examples
+
+- **/*.js - All JavaScript files
+- src/**/*.jsx - All JSX files in the src directory
+- **/components/**/*.vue - All Vue files in any components directory
+
+### Markdown Content
+
+After the frontmatter, the rest of the file should be valid Markdown:
+
+```markdown
+# Title of Your Rule
+
+## Section 1
+- Guidelines and information
+- Code examples
+
+## Section 2
+More detailed information...
+```
+
+## Special Features
+
+### File References
+
+You can reference other files from within an MDC file using the markdown link syntax:
+
+```
+[rule-name.mdc](mdc:location/of/the/rule.mdc)
+```
+
+When this rule is activated, the referenced file will also be included in the context.
+
+### Code Blocks
+
+Use fenced code blocks for examples:
+
+````markdown
+```javascript
+// Example code
+function example() {
+  return "This is an example";
+}
+```
+````
+
+## Best Practices
+
+1. **Clear Organization**
+   - Use numbered prefixes (e.g., `01-workflow.mdc`) for sorting rules logically
+   - Place task-specific rules in the `tasks/` subdirectory
+   - Use descriptive filenames that indicate the rule's purpose
+
+2. **Frontmatter Specificity**
+   - Be specific with glob patterns to ensure rules are only applied in relevant contexts
+   - Use `alwaysApply: true` for truly global guidelines
+   - Make descriptions clear and concise so AI knows when to apply the rule
+
+3. **Content Structure**
+   - Start with a clear title (H1)
+   - Use hierarchical headings (H2, H3, etc.) to organize content
+   - Include examples where appropriate
+   - Keep instructions clear and actionable
+
+4. **File Size Considerations**
+   - Keep files focused on a single topic or closely related topics
+   - Split very large rule sets into multiple files and link them with references
+   - Aim for under 300 lines per file when possible
+
+## Usage in Cursor
+
+When working with files in Cursor, rules are automatically applied when:
+
+1. The file you're working on matches a rule's glob pattern
+2. A rule has `alwaysApply: true` set in its frontmatter
+3. The agent thinks the rule's description matches the user request
+4. You explicitly reference a rule in a conversation with Cursor's AI
+
+## Creating/Renaming/Removing Rules
+
+   - When a rule file is added/renamed/removed, update also the list under 010-workflow.mdc.
+   - When changs are made to multiple `mdc` files from a single request, review also [999-mdc-format]((mdc:.cursor/rules/999-mdc-format.mdc)) to consider whether to update it too.
+
+## Updating Rules
+
+When updating existing rules:
+
+1. Maintain the frontmatter format
+2. Keep the same glob patterns unless intentionally changing the rule's scope
+3. Update the description if the purpose of the rule changes
+4. Consider whether changes should propagate to related rules (e.g., CE versions)

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+
+## [0.9.6] - 2025-05-10
+
+- Added `add_file` for `Iterator` (only pdf for now)
+- Added `add_image` for `Iterator`
+- Added `add_file` and `add_image` for Assistants
+- Added `call_stack` for `Iterator` and `ModuleRequest`
+- Added `stop_double_calls` for `Iterator` and `ModuleRequest`
+
+## [0.9.4] - 2025-05-08
+
+- Added `stability_images` model
+- Added `openai_gpt_image` model
+- Added `openai_dalle3` model
+- Added `access_token_stability` for configuration
+
 ## [0.9.3] - 2025-05-06
 
 - Changed `max_tokens` to `max_completion_tokens` in `params`

data/README.md

@@ -154,14 +154,25 @@ steps << "Step 4. When the solution is ready, notify about it and wait for the u
 # To retain the locale if you have assistants in different languages in your project.
 store_locale # Optional
 
+tool = MyTool.new
+
 @iterator = OxAiWorkers::Iterator.new(
   worker: init_worker(delayed: delayed, model: model),
   role: 'You are a software agent inside my computer',
-  tools: [MyTool.new],
+  tools: [tool],
   locale: @locale || I18n.locale,
   steps: steps,
   # def_except: [:outer_voice], # It's except steps with that functions
   # def_only: [:inner_monologue, :outer_voice], # Use it only with your steps
+  # Forced Function: Uses call_stack parameter to force the model to call functions in this exact order, one at a time
+  # call_stack: [ 
+  #   OxAiWorkers::Iterator.full_function_name(:outer_voice),
+  #   tool.full_function_name(:func1)
+  # ],
+  # Stop Double Calls: Uses stop_double_calls parameter to prevent the model from calling the same function twice in a row
+  # stop_double_calls: [
+  #   tool.full_function_name(:func1)
+  # ],
   on_inner_monologue: ->(text:) { puts "monologue: #{text}".colorize(:yellow) },
   on_outer_voice: ->(text:) { puts "voice: #{text}".colorize(:green) }
 )
@@ -385,6 +396,34 @@ class MyTool
 end
 ```
 
+### Working with Files and Images
+
+You can easily add files and images to your assistants:
+
+```ruby
+# Add a PDF file
+iterator.add_file(
+  pdf: File.read('document.pdf'),
+  filename: 'document.pdf',
+  text: 'Here is the document you requested'
+)
+
+# Add image from URL
+iterator.add_image(
+  text: 'Here is the image',
+  url: 'https://example.com/image.jpg',
+  detail: 'auto' # 'auto', 'low', or 'high'
+)
+
+# Add image from binary data
+image_data = File.read('local_image.jpg')
+iterator.add_image(
+  text: 'Image from binary data',
+  binary: image_data,
+  mime_type: 'image/jpeg' # Defaults to 'image/jpeg'
+)
+```
+
 ### Handling State Transitions with Callbacks
 
 You can track and respond to state transitions with callbacks:
@@ -438,6 +477,159 @@ OxAiWorkers provides several specialized assistant types:
   localizer.task = "Translate my application's interface"
   ```
 
+- **Painter**: Image generation and manipulation
+
+  ```ruby
+  painter = OxAiWorkers::Assistant::Painter.new
+  # or Set working directory to save generated images as files
+  # painter = OxAiWorkers::Assistant::Painter.new(current_dir: Dir.pwd)
+  painter.task = "Create an image of a sunset over mountains"
+  ```
+
+- **Orchestrator**: Coordinates multiple assistants to work together on complex tasks
+
+  ```ruby
+  orchestrator = OxAiWorkers::Assistant::Orchestrator.new(
+    workflow: 'Development team creates an application and tests it.'
+  )
+  orchestrator.add_assistant(OxAiWorkers::Assistant::Coder.new)
+  orchestrator.add_assistant(OxAiWorkers::Assistant::Sysop.new)
+  orchestrator.add_assistant(OxAiWorkers::Assistant::Localizer.new)
+  orchestrator.task = "Create a hello world application in C, save it to hello_world.c, compile, run, and verify it works."
+  ```
+
+All assistants support working with files and images:
+
+```ruby
+# Add files and images to any assistant
+sysop.add_file(pdf: File.read('error_log.pdf'), filename: 'error_log.pdf', text: 'Error log file')
+sysop.add_image(text: 'Screenshot of the error', url: 'https://example.com/screenshot.png')
+```
+
+See the [Working with Files and Images](#working-with-files-and-images) section for full details.
+
+### Available Tools
+
+OxAiWorkers provides several specialized tools to extend functionality:
+
+- **Pixels**: Image generation and manipulation tool
+
+  ```ruby
+  # Initialize with worker and optional parameters
+  pixels = OxAiWorkers::Tool::Pixels.new(
+    worker: worker,                 # Required: Request or DelayedRequest instance
+    current_dir: Dir.pwd,           # Optional: Directory to save generated images
+    image_model: 'dall-e-3',        # Optional: 'dall-e-3' or 'gpt-image-1'
+    only: [:generate_image]         # Optional: Limit available functions
+  )
+  ```
+
+  Provides functions for generating images with customizable parameters like size and quality, with ability to save generated images to disk.
+
+- **Pipeline**: Assistant coordination and communication tool
+
+  ```ruby
+  # Initialize with optional parameters
+  pipeline = OxAiWorkers::Tool::Pipeline.new(
+    on_message: ->(text:) { puts text } # Optional: Message handler callback
+  )
+  
+  # Add assistants to the pipeline
+  pipeline.add_assistant(OxAiWorkers::Assistant::Coder.new)
+  pipeline.add_assistant(OxAiWorkers::Assistant::Sysop.new)
+  ```
+
+  Enables communication between multiple assistants, maintaining message context and facilitating collaborative problem-solving.
+
+- **Eval**: Code execution tool
+
+  ```ruby
+  # Initialize with optional parameters
+  eval_tool = OxAiWorkers::Tool::Eval.new(
+    only: [:ruby, :sh],             # Optional: Limit available functions
+    current_dir: Dir.pwd            # Optional: Directory to execute commands in
+  )
+  ```
+
+  Allows execution of Ruby code and shell commands, with directory context support.
+
+- **FileSystem**: File operations tool
+
+  ```ruby
+  # Initialize with optional parameters
+  file_system = OxAiWorkers::Tool::FileSystem.new(
+    current_dir: Dir.pwd,           # Optional: Base directory for operations
+    only: [:list_directory, :read_file, :write_to_file] # Optional: Limit available functions
+  )
+  ```
+
+  Provides functions for listing directory contents, reading from files, and writing to files with support for relative paths.
+
+Additional tools like Database and Converter are available for specialized tasks and can be integrated using the same pattern.
+
+### Function Control Mechanisms
+
+OxAiWorkers provides two powerful mechanisms to control function execution behavior in iterators:
+
+#### Call Stack
+
+The `call_stack` parameter allows you to force the model to call specific functions in a predetermined order:
+
+```ruby
+iterator = OxAiWorkers::Iterator.new(
+  worker: worker,
+  tools: [my_tool],
+  call_stack: [
+    my_tool.full_function_name(:process_data),
+    OxAiWorkers::Iterator.full_function_name(:outer_voice),
+  ]
+)
+```
+
+This feature is particularly useful when:
+
+- You need to ensure a specific sequence of operations
+- Certain functions must be called before others
+- You want to guide the model through a predefined workflow
+- Complex operations require strict ordering of function calls
+
+The `call_stack` is processed sequentially, with each function being removed from the stack after it's called.
+
+#### Stop Double Calls
+
+The `stop_double_calls` parameter prevents the model from calling the same function twice in consecutive operations:
+
+```ruby
+iterator = OxAiWorkers::Iterator.new(
+  worker: worker,
+  tools: [my_tool],
+  stop_double_calls: [
+    my_tool.full_function_name(:expensive_operation)
+  ]
+)
+```
+
+This feature is valuable for:
+
+- Preventing redundant operations that could waste resources
+- Avoiding duplicate processing of the same data
+- Ensuring that certain operations are executed only once in sequence
+- Protecting against potential infinite loops in function calls
+
+When a function is called, its name is stored as the `last_call`. If the next function call matches both the `last_call` and is included in the `stop_double_calls` list, it will be excluded from the available tools for that request.
+
+By default, `stop_double_calls` is applied to the `inner_monologue` and `outer_voice` functions to prevent reasoning loops and repetitive responses. This default behavior helps models avoid getting stuck in circular thinking patterns.
+
+If you need to override this default behavior (for example, when consecutive monologue or voice calls are required for your specific use case), you can reset the stop_double_calls list **after** the iterator is created:
+
+```ruby
+# Clear the default stop_double_calls constraints
+@iterator.stop_double_calls = []
+
+# Or set your own custom constraints
+@iterator.stop_double_calls = [my_tool.full_function_name(:specific_function)]
+```
+
 ### Implementing Your Own Assistant
 
 Create custom assistants by inheriting from existing ones or composing with the Iterator:

data/config/locales/en.oxaiworkers.tool.yml

@@ -40,8 +40,8 @@ en:
         assistant_info: "ID: **%{id}**, Title: %{title}\nRole: %{role}\nDescription: %{description}\nCapabilities: %{capabilities}"
       pixels:
         generate_image:
-          description: 'Image Generation Tool: Creates an image based on the provided text prompt. If a file name is provided, the image will be saved in png format. In any case, the url of the generated image will be returned.'
-          prompt: 'Text description of the image to generate'
-          size: 'Size of the generated image (1024x1792, 1792x1024, 1024x1024)'
-          quality: 'Quality of the generated image (standard, hd)'
+          description: 'Image Generation Tool: Creates an image based on the provided text prompt on **English language**.'
+          prompt: 'Text description of the image to generate on **English language**'
+          size: 'Size of the generated image'
+          quality: 'Quality of the generated image'
           file_name: 'File name for saving the generated image in png format. For example: image.png'

data/config/locales/ru.oxaiworkers.tool.yml

@@ -40,12 +40,12 @@ ru:
         assistant_info: "ID: **%{id}**, Название: %{title}\nРоль: %{role}\nОписание: %{description}\nВозможности: %{capabilities}"
       pixels:
         generate_image:
-          description: 'Инструмент генерации изображений: Создает изображение на основе предоставленного текстового запроса. Если указать имя файла, изображение будет сохранено в формате png. В любом случае будет возвращен url изображения.'
-          prompt: 'Текстовое описание изображения для генерации'
+          description: 'Инструмент генерации изображений: Создает изображение на основе предоставленного текстового запроса на **английском языке**.'
+          prompt: 'Текстовое описание изображения для генерации строго **на английском** языке'
           size: 'Размер генерируемого изображения'
           quality: 'Качество генерируемого изображения'
           file_name: 'Имя файла для сохранения изображения в формате png. Например: image.png'
         edit_image:
-          description: 'Инструмент редактирования изображений: Редактирует изображение на основе предоставленного текстового запроса. Если указать имя файла, изображение будет сохранено в формате png. В любом случае будет возвращен url изображения.'
+          description: 'Инструмент редактирования изображений: Редактирует изображение на основе предоставленного текстового запроса.'
           input_image: 'URL или путь к изображению для редактирования'
           prompt: 'Текстовое описание действий для редактирования изображения'

data/lib/ox-ai-workers.rb

@@ -36,12 +36,17 @@ require_relative 'oxaiworkers/assistant/localizer'
 require_relative 'oxaiworkers/assistant/orchestrator'
 require_relative 'oxaiworkers/assistant/painter'
 
-require_relative 'oxaiworkers/models/module_base'
+require_relative 'oxaiworkers/models/llm_base'
 require_relative 'oxaiworkers/models/openai_max'
 require_relative 'oxaiworkers/models/openai_mini'
 require_relative 'oxaiworkers/models/openai_nano'
 require_relative 'oxaiworkers/models/deepseek_max'
 
+require_relative 'oxaiworkers/models/images_base'
+require_relative 'oxaiworkers/models/stability_images'
+require_relative 'oxaiworkers/models/openai_gpt_image'
+require_relative 'oxaiworkers/models/openai_dalle3'
+
 require_relative 'oxaiworkers/engine' if defined?(Rails)
 
 module OxAiWorkers
@@ -52,7 +57,8 @@ module OxAiWorkers
   class ConfigurationError < Error; end
 
   class Configuration
-    attr_accessor :max_tokens, :temperature, :wait_for_complete, :access_token_deepseek, :access_token_openai
+    attr_accessor :max_tokens, :temperature, :wait_for_complete, :access_token_deepseek, :access_token_openai,
+                  :access_token_stability
 
     def initialize
       @max_tokens = DEFAULT_MAX_TOKEN
@@ -61,6 +67,7 @@ module OxAiWorkers
 
       @access_token_deepseek = nil
       @access_token_openai = nil
+      @access_token_stability = nil
 
       [Array, NilClass, String, Symbol, Hash].each do |c|
         c.send(:include, OxAiWorkers::PresentCompat) unless c.method_defined?(:present?)

data/lib/oxaiworkers/assistant/module_base.rb

@@ -34,6 +34,14 @@ module OxAiWorkers
         @iterator.clear_context
         @iterator.add_context context
       end
+
+      def add_file(pdf:, filename:, text:, role: :user)
+        @iterator.add_file(pdf:, filename:, text:, role:)
+      end
+
+      def add_image(text:, url: nil, binary: nil, role: :user, detail: 'auto', mime_type: 'image/jpeg')
+        @iterator.add_image(text:, url:, binary:, role:, detail:, mime_type:)
+      end
     end
   end
 end

data/lib/oxaiworkers/assistant/painter.rb

@@ -5,7 +5,7 @@ module OxAiWorkers
     class Painter
       include OxAiWorkers::Assistant::ModuleBase
 
-      def initialize(current_dir: nil, delayed: false, model: nil)
+      def initialize(current_dir: nil, delayed: false, model: nil, image_model: nil)
         store_locale
         @current_dir = current_dir
 
@@ -17,10 +17,13 @@ module OxAiWorkers
           @title = I18n.t('oxaiworkers.assistant.painter.title')
         end
 
+        worker = init_worker(delayed:, model:)
+        image_model ||= OxAiWorkers::Models::OpenaiDalle3.new
+
         @iterator = Iterator.new(
-          worker: init_worker(delayed:, model:),
+          worker:,
           role: @role,
-          tools: [Tool::Pixels.new(worker: init_worker(delayed: false, model:), current_dir:)],
+          tools: [Tool::Pixels.new(worker: image_model, current_dir:)],
           locale: @locale,
           on_inner_monologue: ->(text:) { puts "monologue: #{text}".colorize(:yellow) },
           on_outer_voice: ->(text:) { puts "voice: #{text}".colorize(:green) }

data/lib/oxaiworkers/iterator.rb

@@ -8,10 +8,12 @@ module OxAiWorkers
     include OxAiWorkers::LoadI18n
 
     attr_accessor :worker, :role, :messages, :context, :tools, :queue, :monologue, :tasks,
-                  :on_inner_monologue, :on_outer_voice, :on_finish, :def_except, :def_only
+                  :on_inner_monologue, :on_outer_voice, :on_finish, :def_except, :def_only,
+                  :call_stack, :stop_double_calls
 
     def initialize(worker:, role: nil, tools: [], on_inner_monologue: nil, on_outer_voice: nil,
-                   on_finish: nil, steps: nil, def_except: [], def_only: nil, locale: nil)
+                   on_finish: nil, steps: nil, def_except: [], def_only: nil, locale: nil,
+                   call_stack: nil, stop_double_calls: [])
 
       @locale = locale || I18n.locale
 
@@ -41,6 +43,18 @@ module OxAiWorkers
       @on_outer_voice = on_outer_voice
       @on_finish = on_finish
 
+      if call_stack&.any?
+        if available_defs.include?(:inner_monologue) && !call_stack.include?(OxAiWorkers::Iterator.full_function_name(:inner_monologue))
+          # Add inner_monologue first
+          @call_stack = [OxAiWorkers::Iterator.full_function_name(:inner_monologue)] + call_stack
+        end
+        # Add finish_it last
+        @call_stack = call_stack + [OxAiWorkers::Iterator.full_function_name(:finish_it)]
+      end
+
+      @stop_double_calls = [OxAiWorkers::Iterator.full_function_name(:inner_monologue),
+                            OxAiWorkers::Iterator.full_function_name(:outer_voice)] + stop_double_calls
+
       cleanup
 
       super()
@@ -99,17 +113,20 @@ module OxAiWorkers
     end
 
     def rebuild_worker
+      @worker.last_call = nil
+      @worker.call_stack = @call_stack.dup
+      @worker.stop_double_calls = @stop_double_calls
       @worker.messages = []
-      @worker.append(role: :system, content: @role) if @role.present?
+      @worker.append(role: :system, content: "<role>\n#{@role}\n</role>") if @role.present?
 
-      @tasks.each { |task| @worker.append(role: :user, content: task) }
-      @worker.append(role: :system, content: valid_monologue.join("\n"))
+      @worker.append(role: :system, content: "<instructions>\n#{valid_monologue.join("\n")}\n</instructions>")
+      @tasks.each { |task| @worker.append(role: :user, content: "<task>\n#{task}\n</task>") }
       @worker.append(messages: @context) if @context.present?
       @tools.each do |tool|
         @worker.append(role: :user, content: tool.context) if tool.respond_to?(:context) && tool.context.present?
       end
       @worker.append(messages: @messages)
-      @tasks.each { |task| @worker.append(role: :user, content: task) }
+      @tasks.each { |task| @worker.append(role: :user, content: "<task>\n#{task}\n</task>") }
       @worker.tools = function_schemas.to_openai_format(only: available_defs)
       return unless @tools.present?
 
@@ -235,6 +252,35 @@ module OxAiWorkers
       add_raw_context({ role:, content: text })
     end
 
+    def add_file(pdf:, filename:, text:, role: :user)
+      content = []
+      content << { type: 'text', text: } if text.present?
+      content << {
+        type: 'file',
+        file: {
+          filename:,
+          file_data: Base64.strict_encode64(pdf)
+        }
+      }
+
+      add_raw_context({ role:, content: })
+    end
+
+    def add_image(text:, url: nil, binary: nil, role: :user, detail: 'auto', mime_type: 'image/jpeg')
+      content = []
+      content << { type: 'text', text: } if text.present?
+
+      image_url = if binary.present?
+                    "data:#{mime_type};base64,#{Base64.strict_encode64(binary)}"
+                  else
+                    url
+                  end
+
+      content << { type: 'image_url', image_url: { url: image_url, detail: } }
+
+      add_raw_context({ role:, content: })
+    end
+
     def add_raw_context(c)
       @context << c
     end

data/lib/oxaiworkers/models/deepseek_max.rb

@@ -2,9 +2,7 @@
 
 module OxAiWorkers
   module Models
-    class DeepseekMax
-      include OxAiWorkers::Models::ModuleBase
-
+    class DeepseekMax < LLMBase
       def initialize(uri_base: nil, api_key: nil, model: nil, max_tokens: nil, temperature: nil, frequency_penalty: nil)
         @model = model || 'deepseek-chat'
         @uri_base = uri_base || 'https://api.deepseek.com/'

data/lib/oxaiworkers/models/images_base.rb

@@ -0,0 +1,11 @@
+module OxAiWorkers
+  module Models
+    class ImagesBase
+      attr_accessor :client, :options, :qualities, :sizes, :result
+
+      def initialize(options:)
+        @options = options
+      end
+    end
+  end
+end

data/lib/oxaiworkers/models/{module_base.rb → llm_base.rb}

@@ -2,7 +2,7 @@
 
 module OxAiWorkers
   module Models
-    module ModuleBase
+    class LLMBase
       attr_accessor :uri_base, :api_key, :model, :max_tokens, :temperature, :frequency_penalty
 
       def initialize(uri_base:, api_key:, model:, max_tokens: nil, temperature: nil, frequency_penalty: nil)

data/lib/oxaiworkers/models/openai_dalle3.rb

@@ -0,0 +1,47 @@
+module OxAiWorkers
+  module Models
+    class OpenaiDalle3 < ImagesBase
+      def initialize(api_key: nil, options: {})
+        @sizes = %w[1024x1024 1024x1792 1792x1024]
+        @qualities = %w[standard hd]
+        api_key ||= OxAiWorkers.configuration.access_token_openai
+
+        @client = OpenAI::Client.new(access_token: api_key)
+        super(options:)
+      end
+
+      def generate(prompt:, size: nil, quality: nil)
+        puts "OpenaiDalle3: #{prompt}"
+
+        size ||= @sizes.first
+        quality ||= @qualities.first
+
+        options = {
+          prompt:,
+          model: 'dall-e-3',
+          size:,
+          quality:
+        }
+        options.merge!(@options)
+
+        response = @client.images.generate(
+          parameters: options
+        )
+
+        url = response.dig('data', 0, 'url')
+        b64_json = response.dig('data', 0, 'b64_json')
+        revised_prompt = response.dig('data', 0, 'revised_prompt')
+
+        @result = "revised_prompt: #{revised_prompt}\n\n"
+        if url.present?
+          @result += "url: #{url}\n\n"
+          URI.open(url).read
+        elsif b64_json.present?
+          Base64.decode64(b64_json)
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/oxaiworkers/models/openai_gpt_image.rb

@@ -0,0 +1,37 @@
+module OxAiWorkers
+  module Models
+    class OpenaiGptImage < ImagesBase
+      def initialize(api_key: nil, options: {})
+        @sizes = %w[auto 1024x1024 1536x1024 1024x1536]
+        @qualities = %w[auto low medium high]
+        api_key ||= OxAiWorkers.configuration.access_token_openai
+
+        @client = OpenAI::Client.new(access_token: api_key)
+        super(options:)
+      end
+
+      def generate(prompt:, size: nil, quality: nil)
+        puts "OpenaiGptImage: #{prompt}"
+
+        size ||= @sizes.first
+        quality ||= @qualities.first
+
+        options = {
+          prompt:,
+          model: 'gpt-image-1',
+          size:,
+          quality:
+        }
+        options.merge!(@options)
+
+        response = @client.images.generate(
+          parameters: options
+        )
+
+        b64_json = response.dig('data', 0, 'b64_json')
+
+        Base64.decode64(b64_json)
+      end
+    end
+  end
+end

data/lib/oxaiworkers/models/openai_max.rb

@@ -2,9 +2,7 @@
 
 module OxAiWorkers
   module Models
-    class OpenaiMax
-      include OxAiWorkers::Models::ModuleBase
-
+    class OpenaiMax < LLMBase
       def initialize(uri_base: nil, api_key: nil, model: nil, max_tokens: nil, temperature: nil, frequency_penalty: nil)
         @model = model || 'gpt-4.1'
         @api_key = api_key || OxAiWorkers.configuration.access_token_openai

data/lib/oxaiworkers/models/stability_images.rb

@@ -0,0 +1,32 @@
+module OxAiWorkers
+  module Models
+    class StabilityImages < ImagesBase
+      def initialize(api_key: nil, timeout: 300, options: {})
+        @sizes = %w[auto]
+        @qualities = %w[auto]
+        api_key ||= OxAiWorkers.configuration.access_token_stability
+
+        @client = StabilitySDK::Client.new(api_key:, timeout:)
+        super(options:)
+      end
+
+      def generate(prompt:, size: nil, quality: nil)
+        puts "StabilityImages: #{prompt}"
+        options = {
+          engine_id: 'stable-diffusion-xl-1024-v1-0'
+        }
+        options.merge!(@options)
+        binary = nil
+        @client.generate(prompt, options) do |answer|
+          answer.artifacts.each do |artifact|
+            next unless artifact.type == :ARTIFACT_IMAGE
+
+            binary = artifact.binary
+          end
+        end
+
+        binary
+      end
+    end
+  end
+end

data/lib/oxaiworkers/module_request.rb

@@ -3,15 +3,17 @@
 module OxAiWorkers
   class ModuleRequest
     attr_accessor :result, :client, :messages, :model, :custom_id, :tools, :errors,
-                  :tool_calls_raw, :tool_calls, :is_truncated, :finish_reason, :on_stream_proc
+                  :tool_calls_raw, :tool_calls, :is_truncated, :finish_reason, 
+                  :on_stream_proc, :call_stack, :last_call, :stop_double_calls
 
-    def initialize_requests(model:, on_stream: nil)
+    def initialize_requests(model:, on_stream: nil, call_stack: nil)
       @custom_id = SecureRandom.uuid
       @model = model
       @client = nil
       @is_truncated = false
       @finish_reason = nil
       @on_stream_proc = on_stream
+      @call_stack = call_stack
 
       if @model.api_key.nil?
         error_text = "#{@model.model} access token missing!"
@@ -34,6 +36,7 @@ module OxAiWorkers
       @tool_calls_raw = nil
       @is_truncated = false
       @finish_reason = nil
+      @last_call = nil
     end
 
     def append(role: nil, content: nil, messages: nil)
@@ -50,8 +53,17 @@ module OxAiWorkers
         frequency_penalty: @model.frequency_penalty
       }
       if @tools.present?
-        parameters[:tools] = @tools
-        parameters[:tool_choice] = 'required'
+        parameters[:tools] = @tools.reject do |f|
+          tool_name = f[:function][:name]
+          tool_name == @last_call && @stop_double_calls.include?(tool_name)
+        end
+        if @call_stack&.any?
+          func1 = @call_stack.first
+          @call_stack = @call_stack.drop(1)
+          parameters[:tool_choice] = { type: 'function', function: { name: func1 } }
+        else
+          parameters[:tool_choice] = 'required'
+        end
       end
       if @on_stream_proc.present?
         parameters[:stream] = @on_stream_proc
@@ -134,6 +146,7 @@ module OxAiWorkers
           name: function['name'].split('__').last,
           args: args
         }
+        @last_call = function['name']
       end
     end
   end

data/lib/oxaiworkers/tool/pixels.rb

@@ -8,22 +8,9 @@ module OxAiWorkers
       include OxAiWorkers::DependencyHelper
       include OxAiWorkers::LoadI18n
 
-      attr_accessor :worker, :url, :current_dir, :image_model, :mask
-
-      MODELS = {
-        'dall-e-3' => {
-          'model' => 'dall-e-3',
-          'size' => %w[1024x1024 1024x1792 1792x1024],
-          'quality' => %w[standard hd]
-        },
-        'gpt-image-1' => {
-          'model' => 'gpt-image-1',
-          'size' => %w[1024x1024 1024x1792 1792x1024],
-          'quality' => %w[auto low medium high]
-        }
-      }
-
-      def initialize(worker:, current_dir: nil, only: nil, image_model: 'dall-e-3', mask: nil)
+      attr_accessor :worker, :current_dir
+
+      def initialize(worker:, current_dir: nil, only: nil)
         store_locale
 
         init_white_list_with only
@@ -31,15 +18,19 @@ module OxAiWorkers
         define_function :generate_image, description: I18n.t('oxaiworkers.tool.pixels.generate_image.description') do
           property :prompt, type: 'string', description: I18n.t('oxaiworkers.tool.pixels.generate_image.prompt'),
                             required: true
-          property :size, type: 'string', description: I18n.t('oxaiworkers.tool.pixels.generate_image.size'),
-                          enum: MODELS[image_model]['size']
+          if worker.sizes.length > 1
+            property :size, type: 'string', description: I18n.t('oxaiworkers.tool.pixels.generate_image.size'),
+                            enum: worker.sizes
+          end
           if current_dir.present?
             property :file_name, type: 'string',
                                  description: I18n.t('oxaiworkers.tool.pixels.generate_image.file_name'),
                                  required: true
           end
-          property :quality, type: 'string', description: I18n.t('oxaiworkers.tool.pixels.generate_image.quality'),
-                             enum: MODELS[image_model]['quality']
+          if worker.qualities.length > 1
+            property :quality, type: 'string', description: I18n.t('oxaiworkers.tool.pixels.generate_image.quality'),
+                               enum: worker.qualities
+          end
         end
 
         # define_function :edit_image, description: I18n.t('oxaiworkers.tool.pixels.edit_image.description') do
@@ -56,32 +47,18 @@ module OxAiWorkers
 
         @worker = worker
         @current_dir = current_dir
-        @image_model = MODELS[image_model]
-        @mask = mask
       end
 
       def generate_image(prompt:, file_name: nil, size: nil, quality: nil)
-        puts "generate_image: #{prompt}"
-
-        size ||= @image_model['size'].first
-        quality ||= @image_model['quality'].first
-
-        response = @worker.client.images.generate(
-          parameters: {
-            prompt:,
-            model: @image_model['model'],
-            size:,
-            quality:
-          }
-        )
+        binary = @worker.generate(prompt:, size:, quality:)
 
-        @url = response.dig('data', 0, 'url')
-        revised_prompt = response.dig('data', 0, 'revised_prompt')
         if file_name.present?
-          path = save_generated_image(file_name:)
-          "url: #{@url}\nfile_name: #{path}\n\nrevised_prompt: #{revised_prompt}"
+          path = save_generated_image(file_name:, binary:)
+          "Successfully generated image. file_name: #{path}\n\n#{@worker.result}"
+        elsif @worker.result.present?
+          @worker.result
         else
-          "url: #{@url}\n\nrevised_prompt: #{revised_prompt}"
+          'file_name not set for OxAiWorkers::Tool::Pixels. Please set file name first.'
         end
       end
 
@@ -109,20 +86,24 @@ module OxAiWorkers
         end
       end
 
-      def save_generated_image(file_name:)
+      def save_generated_image(file_name:, binary:)
         unless @current_dir.present?
           return 'Current directory not set for OxAiWorkers::Tool::Pixels. Please set current directory first.'
         end
 
+        return 'File name not set for OxAiWorkers::Tool::Pixels. Please set file name first.' unless file_name.present?
+
         # Ensure current_dir exists
         FileUtils.mkdir_p(@current_dir) unless Dir.exist?(@current_dir)
 
         path = File.join(@current_dir, file_name)
 
         File.open(path, 'wb') do |file|
-          file.write(URI.open(@url).read)
+          file.write(binary)
         end
 
+        puts "Successfully saved image. file_name: #{path}"
+
         file_name
       end
     end

data/lib/oxaiworkers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OxAiWorkers
-  VERSION = '0.9.3.1'
+  VERSION = '0.9.6'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ox-ai-workers
 version: !ruby/object:Gem::Version
-  version: 0.9.3.1
+  version: 0.9.6
 platform: ruby
 authors:
 - Denis Smolev
@@ -123,7 +123,9 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".cursorrules"
+- ".cursor/rules/010-project-structure.mdc"
+- ".cursor/rules/998-clean-code.mdc"
+- ".cursor/rules/999-mdc-format.mdc"
 - ".ruby-version"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
@@ -155,10 +157,14 @@ files:
 - lib/oxaiworkers/iterator.rb
 - lib/oxaiworkers/load_i18n.rb
 - lib/oxaiworkers/models/deepseek_max.rb
-- lib/oxaiworkers/models/module_base.rb
+- lib/oxaiworkers/models/images_base.rb
+- lib/oxaiworkers/models/llm_base.rb
+- lib/oxaiworkers/models/openai_dalle3.rb
+- lib/oxaiworkers/models/openai_gpt_image.rb
 - lib/oxaiworkers/models/openai_max.rb
 - lib/oxaiworkers/models/openai_mini.rb
 - lib/oxaiworkers/models/openai_nano.rb
+- lib/oxaiworkers/models/stability_images.rb
 - lib/oxaiworkers/module_request.rb
 - lib/oxaiworkers/present_compat.rb
 - lib/oxaiworkers/request.rb

data/.cursorrules

@@ -1,155 +0,0 @@
-# Overview
-
-OxAiWorkers is a Ruby gem that implements a finite state machine (using the `state_machine` gem) to solve tasks using generative intelligence (with the `ruby-openai` gem). This approach enhances the final result by utilizing internal monologue and external tools.
-
-## Architecture Principles
-
-- The library is built on the finite state machine (FSM) pattern using the 'state_machine' gem
-- Integration with generative models is implemented using the 'ruby-openai' gem
-- DRY (Don't Repeat Yourself) principle is applied throughout all components
-- Modular structure with clear separation of responsibilities between classes
-- Encapsulation of states and transitions in separate classes
-- Implementation of the "Composition" pattern for flexible tool integration
-
-## Core Components
-
-- `Request` and `DelayedRequest` - classes for executing API requests (immediate and delayed)
-- `Iterator` - main class for iterative task execution with tools
-- `Assistant` - high-level wrappers over Iterator (Sysop, Coder, Localizer, etc.)
-- `Tool` - tools that can be used during task execution (Eval, FileSystem, Database)
-- `ToolDefinition` - module for declaring functions and methods for tools
-- `StateTools` - base class for managing states and transitions
-- `ContextualLogger` - logging system with contextual information support
-
-## Code Conventions
-
-- Use `snake_case` for method and variable names
-- Functions for generative models should also be in `snake_case` (inner_monologue, outer_voice, etc.)
-- All public methods must have documentation with usage examples
-- Tests are mandatory for all new functions
-- All code comments, CHANGELOG, README, and other documentation must be written in English
-- Use YARD-style documentation for all public methods
-- Maintain a unified code formatting style (Rubocop is recommended)
-- Follow the "Fail fast" principle for early error detection
-
-## Interaction Patterns
-
-- The system uses internal monologue (inner_monologue) for planning actions
-- External voice (outer_voice) is used for communication with the user
-- Execution flow management through finite state machine
-- Implementation of callback mechanisms for flexible event handling
-- Isolation of error handling functions at the tool level
-
-## Integration
-
-- CLI interface through `oxaiworkers init` and `oxaiworkers run` commands
-- Rails support via ActiveRecord for storing delayed requests
-- Configuration through the `OxAiWorkers.configure` block
-- Multilingual support via standard I18n
-- Integration with external APIs through request client templates
-- Delayed execution mechanism via DelayedRequest
-- Support for various language models (OpenAI, Anthropic, Gemini)
-
-## Best Practices
-
-- Use callbacks to handle various states (on_inner_monologue, on_outer_voice)
-- Handle errors at the tool level, preventing them from interrupting the main execution flow
-- When creating new assistants, inherit from the base Assistant class
-- Use the white_list mechanism to restrict available functions
-- Separate language model requests from result processing logic
-- Practice dependency injection to improve code testability
-- Use localization mechanisms for multilingual support
-
-## Tools Architecture
-
-- Each tool should be a self-contained module
-- Tools are registered through the `define_function` interface
-- All tools should handle their own errors and return readable messages
-- Use parameter validation at the function definition level
-- Maintain a unified format for return values
-
-## Performance and Scaling
-
-- Cache API request results when possible
-- Use asynchronous processing for long operations
-- Apply backoff strategies for repeated requests
-- Break large tasks into atomic operations
-- Provide monitoring and profiling mechanisms
-
-## Finite State Machine Implementation
-
-- Core FSM based on `state_machine` gem with states: idle → prepared → requested → analyzed → finished → idle
-- State transitions managed by events: prepare, request, analyze, complete, iterate, end
-- `StateTools` - base class for FSM implementation with event hooks and transition callbacks
-- `StateBatch` - FSM extension for batch request processing with additional states
-- Automatic error recovery and retry mechanisms for failed API requests
-
-## Request Processing
-
-- `ModuleRequest` - base class for all API requests with parsing and response handling
-- Support for streaming responses with callback processing
-- Built-in token usage tracking and truncation detection
-- Error handling with automatic retries for server errors
-
-## Iterator Lifecycle
-
-- 3 core functions: inner_monologue, outer_voice, finish_it
-- Configurable message queue for stateful conversation history
-- Callback system for processing each state transition
-- Context and milestone management for optimizing token usage
-- Support for custom steps and instruction templating
-
-## Additional Tools
-
-- `Converter` - tools for data format conversion and transformation
-- Support for custom tool development through inheritance and composition
-- Automatic function name resolution and parameter validation
-
-## Assistants Details
-
-- `ModuleBase` - shared functionality for all assistant types
-- `Sysop` - system administration and shell command execution
-- `Coder` - specialized for code generation and analysis
-- `Localizer` - translation and localization support
-
-## Development Guidelines
-
-- Use dependency injection for testability
-- Follow the FSM pattern for all stateful operations
-- Implement proper error boundaries at the tool level
-- Use monologue for complex reasoning and planning
-- Apply callbacks for event-driven architecture
-- Utilize templates in the CLI for rapid prototyping
-- Extend the base classes rather than modifying them
-
-## Internationalization and Localization
-
-- All code comments, variable names, and documentation MUST be written in English
-- All user-facing strings MUST be properly localized using I18n
-- Use I18n.t for all text that will be shown to users or appears in assistant prompts
-- Store translations in YAML files within the config/locales directory
-- Follow the naming convention of language.namespace.key (e.g., en.oxaiworkers.assistant.role)
-- Use named parameters (%{variable}) instead of positional parameters (%s) in translation strings
-- Use the with_locale method to ensure proper locale context when processing localized text
-- Implement locale-aware classes by including the OxAiWorkers::LoadI18n module
-- Store the current locale on initialization and preserve it across method calls
-- Support multiple languages simultaneously through careful locale management
-- Default to English for developer-facing messages and logs
-- Ensure that all assistant classes properly handle localization in their format_role methods
-
-## LoadI18n Module Usage
-
-- The `OxAiWorkers::LoadI18n` module provides two key methods for localization:
-  - `store_locale` - saves the current locale at initialization time
-  - `with_locale` - executes a block of code in the context of the saved locale
-- Always include the `OxAiWorkers::LoadI18n` module in classes that need localization capabilities
-- Call `store_locale` in the initialization methods of locale-aware classes
-- Wrap all locale-dependent code in `with_locale` blocks
-- NEVER redefine the `with_locale` method in classes that include LoadI18n
-- All methods that produce user-visible text must use the locale context via `with_locale` blocks
-- Regular method calls from classes including LoadI18n do not require additional locale handling
-
-## Multi-Language Support
-
-- Use the store_locale and with_locale methods for consistent localization context
-- All error messages should be localized and retrieved via I18n.t