hati-operation 0.1.1 → 0.1.2
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/README.md +146 -41
- data/hati-operation.gemspec +3 -3
- data/lib/hati/operation.rb +4 -0
- data/lib/hati_operation/version.rb +1 -1
- metadata +13 -9
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 73b82b192da770f14757614c7b9f9306194f8206c5862832321052d57c3924d7
|
|
4
|
+
data.tar.gz: 25ead6772134193b23798c2b9d66d672cee7352cbd6f192b474757c5bf17a908
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 93519bbc076b861db35320a2cc44295c2d9cd61085a00540394658bb5595db3b1c8c2d908ec608e9db0db0b4acde8cd44da9ec8ae58444936182756376e66798
|
|
7
|
+
data.tar.gz: b7b0d7aad9ee508e91ea8244b4ecbfe16f8778aef6c3d034211f046451d55227c0cde115c8091a960c8553da483aa88fd0e024dc076447bc833a4428b0cec864
|
data/README.md
CHANGED
|
@@ -3,9 +3,11 @@
|
|
|
3
3
|
[](https://rubygems.org/gems/hati_operation)
|
|
4
4
|
[](#license)
|
|
5
5
|
|
|
6
|
-
HatiOperation is a
|
|
6
|
+
HatiOperation is a next-generation Ruby toolkit that combines powerful service orchestration with modern AI-ready architecture. Built on top of [hati-command](https://github.com/hackico-ai/ruby-hati-command), it serves as both a traditional **service aggregator** and an **AI-enhanced orchestrator**, making it perfect for building modern applications that blend business logic with AI capabilities.
|
|
7
7
|
|
|
8
|
-
##
|
|
8
|
+
## Key Features
|
|
9
|
+
|
|
10
|
+
### Core Orchestration
|
|
9
11
|
|
|
10
12
|
- **Step-based execution** – write each unit of work as a small service object and compose them with `step`
|
|
11
13
|
- **Implicit result propagation** – methods return `Success(...)` or `Failure(...)` and are automatically unpacked
|
|
@@ -14,37 +16,82 @@ HatiOperation is a lightweight Ruby toolkit that helps you compose domain logic
|
|
|
14
16
|
- **Macro DSL** – declaratively configure validation, error mapping, transactions and more
|
|
15
17
|
- **Service aggregation** – orchestrate multiple services into cohesive business operations
|
|
16
18
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
19
|
+
### AI-Ready Architecture
|
|
20
|
+
|
|
21
|
+
- **Tool Integration** – seamlessly integrate AI services and LLM tools
|
|
22
|
+
- **Safety Boundaries** – built-in guardrails for AI operations
|
|
23
|
+
- **Action Composition** – chain multiple AI actions safely
|
|
24
|
+
- **State Management** – track and manage AI agent state
|
|
25
|
+
|
|
26
|
+
### Development Acceleration
|
|
27
|
+
|
|
28
|
+
- **Structured Patterns** – clear patterns for both human and AI comprehension
|
|
29
|
+
- **Predictable Flow** – consistent operation structure for better maintainability
|
|
30
|
+
- **Self-Documenting** – clear step definitions aid both human and AI understanding
|
|
31
|
+
- **Context Awareness** – easy access to operation context for all services
|
|
32
|
+
|
|
33
|
+
## Table of Contents
|
|
34
|
+
|
|
35
|
+
1. [Key Features](#key-features)
|
|
36
|
+
- [Core Orchestration](#core-orchestration)
|
|
37
|
+
- [AI-Ready Architecture](#ai-ready-architecture)
|
|
38
|
+
- [Development Acceleration](#development-acceleration)
|
|
39
|
+
2. [Architecture](#architecture)
|
|
40
|
+
3. [Installation](#installation)
|
|
41
|
+
4. [Quick Start](#quick-start)
|
|
42
|
+
- [Traditional Business Operation](#traditional-business-operation)
|
|
43
|
+
- [AI-Enhanced Operation](#ai-enhanced-operation)
|
|
44
|
+
- [Base Operation Configuration](#base-operation-configuration)
|
|
45
|
+
5. [Step DSL](#step-dsl)
|
|
46
|
+
6. [Dependency Injection](#dependency-injection)
|
|
47
|
+
7. [Alternative DSL Styles](#alternative-dsl-styles)
|
|
48
|
+
8. [Testing](#testing)
|
|
49
|
+
9. [Authors](#authors)
|
|
50
|
+
10. [Development](#development)
|
|
51
|
+
11. [Contributing](#contributing)
|
|
52
|
+
12. [License](#license)
|
|
53
|
+
13. [Code of Conduct](#code-of-conduct)
|
|
54
|
+
|
|
55
|
+
## Architecture
|
|
56
|
+
|
|
57
|
+
HatiOperation builds on top of [hati-command](https://github.com/hackico-ai/ruby-hati-command) and implements a versatile architecture that supports both traditional service aggregation and AI-enhanced operations:
|
|
20
58
|
|
|
21
59
|
```
|
|
22
60
|
┌─────────────────────────────────────────────────────────────┐
|
|
23
61
|
│ HatiOperation │
|
|
24
|
-
│
|
|
62
|
+
│ (Universal Service Orchestrator) │
|
|
25
63
|
├─────────────────────────────────────────────────────────────┤
|
|
26
|
-
│
|
|
27
|
-
│
|
|
28
|
-
│ │
|
|
29
|
-
│
|
|
64
|
+
│ │
|
|
65
|
+
│ Traditional Services AI/ML Services │
|
|
66
|
+
│ ┌─────────────┐ ┌─────────────┐ │
|
|
67
|
+
│ │ Business │ │ LLM │ │
|
|
68
|
+
│ │ Logic │ │ Tools │ │
|
|
69
|
+
│ └─────────────┘ └─────────────┘ │
|
|
70
|
+
│ │
|
|
71
|
+
│ ┌─────────────┐ ┌─────────────┐ │
|
|
72
|
+
│ │ Data │ │ Agent │ │
|
|
73
|
+
│ │ Services │ │ Actions │ │
|
|
74
|
+
│ └─────────────┘ └─────────────┘ │
|
|
75
|
+
│ │
|
|
76
|
+
│ ┌─────────────┐ ┌─────────────┐ │
|
|
77
|
+
│ │ External │ │ Safety │ │
|
|
78
|
+
│ │ APIs │ │ Guards │ │
|
|
79
|
+
│ └─────────────┘ └─────────────┘ │
|
|
80
|
+
│ │
|
|
30
81
|
├─────────────────────────────────────────────────────────────┤
|
|
31
82
|
│ hati-command │
|
|
32
83
|
│ (Foundation Layer) │
|
|
33
84
|
└─────────────────────────────────────────────────────────────┘
|
|
34
85
|
```
|
|
35
86
|
|
|
36
|
-
|
|
87
|
+
This dual-purpose architecture allows you to:
|
|
37
88
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
5. [Alternative DSL Styles](#alternative-dsl-styles)
|
|
43
|
-
6. [Testing](#testing)
|
|
44
|
-
7. [Contributing](#contributing)
|
|
45
|
-
8. [License](#license)
|
|
89
|
+
- Compose traditional business services with robust error handling and transactions
|
|
90
|
+
- Integrate AI capabilities with built-in safety mechanisms
|
|
91
|
+
- Mix and match both paradigms in the same operation
|
|
92
|
+
- Maintain clean separation of concerns while sharing common infrastructure
|
|
46
93
|
|
|
47
|
-
##
|
|
94
|
+
## Installation
|
|
48
95
|
|
|
49
96
|
Add HatiOperation to your Gemfile and bundle:
|
|
50
97
|
|
|
@@ -63,16 +110,17 @@ Alternatively:
|
|
|
63
110
|
gem install hati_operation
|
|
64
111
|
```
|
|
65
112
|
|
|
66
|
-
##
|
|
113
|
+
## Quick Start
|
|
114
|
+
|
|
115
|
+
HatiOperation can be used for both traditional business operations and AI-enhanced services. Here are examples of both:
|
|
67
116
|
|
|
68
|
-
|
|
117
|
+
### Traditional Business Operation
|
|
69
118
|
|
|
70
119
|
```ruby
|
|
71
120
|
# app/controllers/api/v1/withdrawal_controller.rb
|
|
72
121
|
class Api::V1::WithdrawalController < ApplicationController
|
|
73
122
|
def create
|
|
74
123
|
result = Withdrawal::Operation::Create.call(params: params.to_unsafe_h)
|
|
75
|
-
|
|
76
124
|
run_and_render(result)
|
|
77
125
|
end
|
|
78
126
|
|
|
@@ -87,11 +135,7 @@ class Api::V1::WithdrawalController < ApplicationController
|
|
|
87
135
|
end
|
|
88
136
|
end
|
|
89
137
|
end
|
|
90
|
-
```
|
|
91
138
|
|
|
92
|
-
### 🔧 Defining the Operation
|
|
93
|
-
|
|
94
|
-
```ruby
|
|
95
139
|
# app/operations/withdrawal/operation/create.rb
|
|
96
140
|
class Withdrawal::Operation::Create < HatiOperation::Base
|
|
97
141
|
# Wrap everything in DB transaction
|
|
@@ -116,17 +160,68 @@ class Withdrawal::Operation::Create < HatiOperation::Base
|
|
|
116
160
|
end
|
|
117
161
|
```
|
|
118
162
|
|
|
119
|
-
###
|
|
163
|
+
### AI-Enhanced Operation
|
|
164
|
+
|
|
165
|
+
```ruby
|
|
166
|
+
# app/operations/ai/content_generation.rb
|
|
167
|
+
class AI::Operation::ContentGeneration < HatiOperation::Base
|
|
168
|
+
# Register safety boundaries
|
|
169
|
+
safety_guard :content_filter
|
|
170
|
+
rate_limit max_tokens: 1000
|
|
171
|
+
|
|
172
|
+
step validator: ContentValidator
|
|
173
|
+
step generator: LLMService
|
|
174
|
+
step filter: ContentFilter
|
|
175
|
+
step formatter: OutputFormatter
|
|
176
|
+
|
|
177
|
+
def call(params:)
|
|
178
|
+
# Validate input and prepare prompt
|
|
179
|
+
input = step validator.call(params[:prompt])
|
|
180
|
+
|
|
181
|
+
# Generate content with safety checks
|
|
182
|
+
content = step generator.call(input), err: AIErr.call(503)
|
|
183
|
+
filtered = step filter.call(content), err: AIErr.call(422)
|
|
184
|
+
|
|
185
|
+
# Format and return
|
|
186
|
+
step formatter.call(filtered)
|
|
187
|
+
end
|
|
188
|
+
end
|
|
189
|
+
|
|
190
|
+
# Usage in controller
|
|
191
|
+
class Api::V1::ContentController < ApplicationController
|
|
192
|
+
def create
|
|
193
|
+
result = AI::Operation::ContentGeneration.call(params: params.to_unsafe_h) do
|
|
194
|
+
# Override services for different models/providers
|
|
195
|
+
step generator: OpenAIService
|
|
196
|
+
step filter: CustomContentFilter
|
|
197
|
+
end
|
|
198
|
+
|
|
199
|
+
render_result(result)
|
|
200
|
+
end
|
|
201
|
+
end
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### Base Operation Configuration
|
|
120
205
|
|
|
121
206
|
```ruby
|
|
207
|
+
# Common configuration for API operations
|
|
122
208
|
class ApiOperation < HatiOperation::Base
|
|
123
209
|
operation do
|
|
124
210
|
unexpected_err ApiErr.call(500)
|
|
125
211
|
end
|
|
126
212
|
end
|
|
213
|
+
|
|
214
|
+
# Common configuration for AI operations
|
|
215
|
+
class AIOperation < HatiOperation::Base
|
|
216
|
+
operation do
|
|
217
|
+
unexpected_err AIErr.call(500)
|
|
218
|
+
safety_guard :content_filter
|
|
219
|
+
rate_limit true
|
|
220
|
+
end
|
|
221
|
+
end
|
|
127
222
|
```
|
|
128
223
|
|
|
129
|
-
##
|
|
224
|
+
## Step DSL
|
|
130
225
|
|
|
131
226
|
The DSL gives you fine-grained control over every stage of the operation:
|
|
132
227
|
|
|
@@ -139,14 +234,14 @@ The DSL gives you fine-grained control over every stage of the operation:
|
|
|
139
234
|
|
|
140
235
|
### Extended Configuration
|
|
141
236
|
|
|
142
|
-
>
|
|
237
|
+
> **See:** [hati-command](https://github.com/hackico-ai/ruby-hati-command) for all configuration options
|
|
143
238
|
|
|
144
239
|
- `ar_transaction` – execute inside database transaction
|
|
145
240
|
- `fail_fast` – configure fail-fast behavior
|
|
146
241
|
- `failure` – set default failure handling
|
|
147
242
|
- `unexpected_err` – configure generic error behavior
|
|
148
243
|
|
|
149
|
-
##
|
|
244
|
+
## Dependency Injection
|
|
150
245
|
|
|
151
246
|
At runtime you can swap out any step for testing, feature-flags, or different environments:
|
|
152
247
|
|
|
@@ -157,7 +252,7 @@ result = Withdrawal::Operation::Create.call(params) do
|
|
|
157
252
|
end
|
|
158
253
|
```
|
|
159
254
|
|
|
160
|
-
##
|
|
255
|
+
## Alternative DSL Styles
|
|
161
256
|
|
|
162
257
|
### Declarative Style
|
|
163
258
|
|
|
@@ -206,7 +301,7 @@ class Api::V2::WithdrawalController < ApiController
|
|
|
206
301
|
end
|
|
207
302
|
```
|
|
208
303
|
|
|
209
|
-
###
|
|
304
|
+
### Full-Stack DI Example
|
|
210
305
|
|
|
211
306
|
```ruby
|
|
212
307
|
class Api::V2::WithdrawalController < ApplicationController
|
|
@@ -220,7 +315,7 @@ class Api::V2::WithdrawalController < ApplicationController
|
|
|
220
315
|
end
|
|
221
316
|
```
|
|
222
317
|
|
|
223
|
-
##
|
|
318
|
+
## Testing
|
|
224
319
|
|
|
225
320
|
Run the test-suite with:
|
|
226
321
|
|
|
@@ -230,14 +325,24 @@ bundle exec rspec
|
|
|
230
325
|
|
|
231
326
|
HatiOperation is fully covered by RSpec. See `spec/` for reference examples including stubbed services and DI.
|
|
232
327
|
|
|
233
|
-
##
|
|
328
|
+
## Authors
|
|
329
|
+
|
|
330
|
+
- [Marie Giy](https://github.com/mariegiy)
|
|
331
|
+
|
|
332
|
+
## Development
|
|
333
|
+
|
|
334
|
+
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
|
335
|
+
|
|
336
|
+
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
|
|
337
|
+
|
|
338
|
+
## Contributing
|
|
339
|
+
|
|
340
|
+
Bug reports and pull requests are welcome on GitHub at https://github.com/hackico-ai/hati-command. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/hackico-ai/hati-command/blob/main/CODE_OF_CONDUCT.md).
|
|
234
341
|
|
|
235
|
-
|
|
342
|
+
## License
|
|
236
343
|
|
|
237
|
-
|
|
238
|
-
2. Run `bundle exec rspec` to ensure tests pass
|
|
239
|
-
3. Submit a pull request with a clear description of your changes
|
|
344
|
+
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
|
|
240
345
|
|
|
241
|
-
##
|
|
346
|
+
## Code of Conduct
|
|
242
347
|
|
|
243
|
-
|
|
348
|
+
Everyone interacting in the HatCommand project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/hackico-ai/hati-command/blob/main/CODE_OF_CONDUCT.md).
|
data/hati-operation.gemspec
CHANGED
|
@@ -12,8 +12,8 @@ Gem::Specification.new do |spec|
|
|
|
12
12
|
spec.email = %w[giy.mariya@gmail.com]
|
|
13
13
|
spec.license = 'MIT'
|
|
14
14
|
|
|
15
|
-
spec.summary = '
|
|
16
|
-
spec.description = '
|
|
15
|
+
spec.summary = 'Ruby gem designed to seamlessly merge classic services with AI intelligence, enabling developers to build autonomous, agentic-ready operations that think, act, and integrate with ease.'
|
|
16
|
+
spec.description = 'Modern service orchestration framework designed for the AI era. Enables rapid development of both traditional and AI-powered applications through composable, testable operations. Features agent-oriented architecture, AI-friendly patterns, and robust service composition.'
|
|
17
17
|
spec.homepage = "https://github.com/hackico-ai/#{spec.name}"
|
|
18
18
|
|
|
19
19
|
spec.required_ruby_version = '>= 3.0.0'
|
|
@@ -33,5 +33,5 @@ Gem::Specification.new do |spec|
|
|
|
33
33
|
|
|
34
34
|
spec.metadata['rubygems_mfa_required'] = 'true'
|
|
35
35
|
|
|
36
|
-
spec.add_dependency 'hati-command'
|
|
36
|
+
spec.add_dependency 'hati-command', '~> 0.1'
|
|
37
37
|
end
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: hati-operation
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.1.
|
|
4
|
+
version: 0.1.2
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Mariya Giy
|
|
@@ -13,18 +13,20 @@ dependencies:
|
|
|
13
13
|
name: hati-command
|
|
14
14
|
requirement: !ruby/object:Gem::Requirement
|
|
15
15
|
requirements:
|
|
16
|
-
- - "
|
|
16
|
+
- - "~>"
|
|
17
17
|
- !ruby/object:Gem::Version
|
|
18
|
-
version: '0'
|
|
18
|
+
version: '0.1'
|
|
19
19
|
type: :runtime
|
|
20
20
|
prerelease: false
|
|
21
21
|
version_requirements: !ruby/object:Gem::Requirement
|
|
22
22
|
requirements:
|
|
23
|
-
- - "
|
|
23
|
+
- - "~>"
|
|
24
24
|
- !ruby/object:Gem::Version
|
|
25
|
-
version: '0'
|
|
26
|
-
description:
|
|
27
|
-
|
|
25
|
+
version: '0.1'
|
|
26
|
+
description: Modern service orchestration framework designed for the AI era. Enables
|
|
27
|
+
rapid development of both traditional and AI-powered applications through composable,
|
|
28
|
+
testable operations. Features agent-oriented architecture, AI-friendly patterns,
|
|
29
|
+
and robust service composition.
|
|
28
30
|
email:
|
|
29
31
|
- giy.mariya@gmail.com
|
|
30
32
|
executables: []
|
|
@@ -34,6 +36,7 @@ files:
|
|
|
34
36
|
- LICENSE
|
|
35
37
|
- README.md
|
|
36
38
|
- hati-operation.gemspec
|
|
39
|
+
- lib/hati/operation.rb
|
|
37
40
|
- lib/hati_operation.rb
|
|
38
41
|
- lib/hati_operation/base.rb
|
|
39
42
|
- lib/hati_operation/step_configs_container.rb
|
|
@@ -65,6 +68,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
65
68
|
requirements: []
|
|
66
69
|
rubygems_version: 3.6.9
|
|
67
70
|
specification_version: 4
|
|
68
|
-
summary:
|
|
69
|
-
|
|
71
|
+
summary: Ruby gem designed to seamlessly merge classic services with AI intelligence,
|
|
72
|
+
enabling developers to build autonomous, agentic-ready operations that think, act,
|
|
73
|
+
and integrate with ease.
|
|
70
74
|
test_files: []
|