agent99 0.0.4 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. checksums.yaml +4 -4
  2. data/A2A_SPEC-dev.md +1829 -0
  3. data/CHANGELOG.md +31 -0
  4. data/COMMITS.md +196 -0
  5. data/DOCS.md +96 -0
  6. data/README.md +200 -78
  7. data/Rakefile +62 -0
  8. data/docs/AI/htm.md +215 -0
  9. data/docs/AI/htm.rb +141 -0
  10. data/docs/AI/htm_demo.db +0 -0
  11. data/docs/AI/notes_on_htm_implementation.md +1319 -0
  12. data/docs/AI/some_code.rb +692 -0
  13. data/docs/advanced-topics/a2a-protocol.md +13 -0
  14. data/docs/{control_actions.md → advanced-topics/control-actions.md} +2 -0
  15. data/docs/advanced-topics/model-context-protocol.md +4 -0
  16. data/docs/advanced-topics/multi-agent-processing.md +674 -0
  17. data/docs/agent-development/request-response-handling.md +512 -0
  18. data/docs/api-reference/agent99-base.md +463 -0
  19. data/docs/api-reference/message-clients.md +495 -0
  20. data/docs/api-reference/registry-client.md +470 -0
  21. data/docs/api-reference/schemas.md +518 -0
  22. data/docs/assets/css/custom.css +27 -0
  23. data/docs/assets/images/agent-lifecycle.svg +73 -0
  24. data/docs/assets/images/agent-registry-process.svg +86 -0
  25. data/docs/assets/images/agent-registry-processes.svg +114 -0
  26. data/docs/assets/images/agent-types-overview.svg +51 -0
  27. data/docs/assets/images/agent99-architecture.svg +85 -0
  28. data/docs/assets/images/agent99_logo.png +0 -0
  29. data/docs/assets/images/control-actions-state.svg +83 -0
  30. data/docs/assets/images/knowledge-graph.svg +77 -0
  31. data/docs/assets/images/message-processing-flow.svg +148 -0
  32. data/docs/assets/images/multi-agent-system.svg +66 -0
  33. data/docs/assets/images/proxy-pattern-sequence.svg +48 -0
  34. data/docs/assets/images/request-flow.svg +97 -0
  35. data/docs/assets/images/request-processing-lifecycle.svg +50 -0
  36. data/docs/assets/images/request-response-sequence.svg +39 -0
  37. data/docs/{agent_lifecycle.md → core-concepts/agent-lifecycle.md} +2 -0
  38. data/docs/core-concepts/agent-types.md +255 -0
  39. data/docs/{architecture.md → core-concepts/architecture.md} +5 -5
  40. data/docs/{what_is_an_agent.md → core-concepts/what-is-an-agent.md} +1 -1
  41. data/docs/diagrams/message-flow-sequence.svg +198 -0
  42. data/docs/diagrams/p2p-network-topology.svg +181 -0
  43. data/docs/diagrams/smart-transport-routing.svg +165 -0
  44. data/docs/diagrams/three-layer-architecture.svg +77 -0
  45. data/docs/diagrams/transport-extension-api.svg +309 -0
  46. data/docs/diagrams/transport-extension-architecture.svg +234 -0
  47. data/docs/diagrams/transport-selection-flowchart.svg +264 -0
  48. data/docs/examples/advanced-examples.md +951 -0
  49. data/docs/examples/basic-examples.md +268 -0
  50. data/docs/{agent_registry_processes.md → framework-components/agent-registry.md} +1 -1
  51. data/docs/{message_processing.md → framework-components/message-processing.md} +3 -1
  52. data/docs/getting-started/basic-example.md +306 -0
  53. data/docs/getting-started/installation.md +160 -0
  54. data/docs/getting-started/overview.md +64 -0
  55. data/docs/getting-started/quick-start.md +179 -0
  56. data/docs/index.md +97 -0
  57. data/examples/DEMO.md +148 -0
  58. data/examples/README.md +50 -0
  59. data/examples/bad_agent.rb +32 -0
  60. data/examples/registry.rb +0 -8
  61. data/examples/run_demo.rb +433 -0
  62. data/lib/agent99/amqp_message_client.rb +2 -2
  63. data/lib/agent99/base.rb +1 -1
  64. data/lib/agent99/message_processing.rb +6 -12
  65. data/lib/agent99/registry_client.rb +4 -1
  66. data/lib/agent99/version.rb +1 -1
  67. data/lib/agent99.rb +1 -1
  68. data/mkdocs.yml +195 -0
  69. data/p2p_plan.md +533 -0
  70. data/p2p_roadmap.md +299 -0
  71. data/registry_plan.md +1818 -0
  72. metadata +89 -32
  73. data/docs/README.md +0 -57
  74. data/docs/diagrams/agent_registry_processes.dot +0 -42
  75. data/docs/diagrams/agent_registry_processes.png +0 -0
  76. data/docs/diagrams/high_level_architecture.dot +0 -26
  77. data/docs/diagrams/high_level_architecture.png +0 -0
  78. data/docs/diagrams/request_flow.dot +0 -42
  79. data/docs/diagrams/request_flow.png +0 -0
  80. /data/docs/{advanced_features.md → advanced-topics/advanced-features.md} +0 -0
  81. /data/docs/{extending_the_framework.md → advanced-topics/extending-the-framework.md} +0 -0
  82. /data/docs/{custom_agent_implementation.md → agent-development/custom-agent-implementation.md} +0 -0
  83. /data/docs/{error_handling_and_logging.md → agent-development/error-handling-and-logging.md} +0 -0
  84. /data/docs/{schema_definition.md → agent-development/schema-definition.md} +0 -0
  85. /data/docs/{api_reference.md → api-reference/overview.md} +0 -0
  86. /data/docs/{agent_discovery.md → framework-components/agent-discovery.md} +0 -0
  87. /data/docs/{messaging_system.md → framework-components/messaging-system.md} +0 -0
  88. /data/docs/{breaking_change_v0.0.4.md → operations/breaking-changes.md} +0 -0
  89. /data/docs/{configuration.md → operations/configuration.md} +0 -0
  90. /data/docs/{preformance_considerations.md → operations/performance-considerations.md} +0 -0
  91. /data/docs/{security.md → operations/security.md} +0 -0
  92. /data/docs/{troubleshooting.md → operations/troubleshooting.md} +0 -0
data/p2p_roadmap.md ADDED
@@ -0,0 +1,299 @@
1
+ # Agent99 P2P Implementation Roadmap
2
+
3
+ This roadmap tracks the implementation progress of the P2P plan outlined in [p2p_plan.md](./p2p_plan.md). Each phase contains detailed checklists to ensure systematic implementation of the enhanced BunnyFarm + SmartMessage + Lanet integration.
4
+
5
+ ---
6
+
7
+ ## Phase 1: Enhanced BunnyFarm Foundation (Weeks 1-4)
8
+
9
+ ### 1.1 BunnyFarm + SmartMessage Integration
10
+ - [ ] **Research & Analysis**
11
+ - [ ] Deep dive into BunnyFarm's current message handling architecture
12
+ - [ ] Analyze SmartMessage's transport abstraction patterns
13
+ - [ ] Document integration points and potential conflicts
14
+ - [ ] Create migration strategy document
15
+
16
+ - [ ] **Core Integration Development**
17
+ - [ ] Replace `BunnyFarm::Message` base class with `SmartMessage::Base`
18
+ - [ ] Migrate BunnyFarm's workflow methods (`process`, `success`, `failure`) to SmartMessage pattern
19
+ - [ ] Maintain BunnyFarm's automatic routing (`ClassName.action`) compatibility
20
+ - [ ] Implement enhanced BunnyFarm configuration system
21
+ - [ ] Create backward compatibility layer for existing BunnyFarm code
22
+
23
+ - [ ] **Testing Framework**
24
+ - [ ] Set up test suite for enhanced BunnyFarm
25
+ - [ ] Create unit tests for message workflow preservation
26
+ - [ ] Test automatic routing functionality with SmartMessage
27
+ - [ ] Validate configuration flexibility across transport plugins
28
+ - [ ] Performance benchmarks: enhanced vs original BunnyFarm
29
+
30
+ ### 1.2 Multi-Transport Support Infrastructure
31
+ - [ ] **SmartMessage Transport Plugin Architecture**
32
+ - [ ] Design and implement `SmartMessage::Transport::Base` interface
33
+ - [ ] Create plugin registration system for auto-discovery
34
+ - [ ] Implement transport factory pattern for dynamic selection
35
+ - [ ] Add transport health monitoring and connection management
36
+ - [ ] Design configuration system for transport-specific settings
37
+
38
+ - [ ] **Core Transport Implementations**
39
+ - [ ] Enhance existing Memory transport for in-process communication
40
+ - [ ] Create Named Pipes transport for high-performance same-machine IPC
41
+ - [ ] Enhance existing Redis transport for multi-process pub/sub scenarios
42
+ - [ ] Create AMQP transport plugin using existing BunnyFarm patterns
43
+ - [ ] Implement transport failover and retry mechanisms
44
+ - [ ] Add transport performance metrics collection
45
+
46
+ - [ ] **Named Pipes Transport Development**
47
+ - [ ] Create `smart_message-transport-named_pipes` gem structure
48
+ - [ ] Implement unidirectional pipe creation with naming convention
49
+ - [ ] Add pipe discovery and registry integration
50
+ - [ ] Implement secure permissions (0600) and cleanup mechanisms
51
+ - [ ] Create configuration system with namespace support
52
+ - [ ] Add deadlock prevention for bidirectional communication
53
+ - [ ] Test performance vs Redis for same-machine scenarios
54
+
55
+ - [ ] **Enhanced Workflow System**
56
+ - [ ] Extend BunnyFarm's process/success/failure pattern across all transports
57
+ - [ ] Implement SmartMessage entity addressing (FROM/TO/REPLY_TO)
58
+ - [ ] Create workflow state tracking across transport boundaries
59
+ - [ ] Add workflow error handling and recovery mechanisms
60
+ - [ ] Maintain BunnyFarm's K.I.S.S. design philosophy
61
+
62
+ ### 1.3 Documentation & Community Preparation
63
+ - [ ] **Documentation**
64
+ - [ ] Create enhanced BunnyFarm API documentation
65
+ - [ ] Write transport plugin development guide
66
+ - [ ] Document migration path from original BunnyFarm
67
+ - [ ] Create performance comparison benchmarks
68
+ - [ ] Write configuration and setup guides
69
+
70
+ - [ ] **Community & Ecosystem**
71
+ - [ ] Prepare enhanced BunnyFarm gem for release
72
+ - [ ] Create example applications demonstrating multi-transport workflows
73
+ - [ ] Set up CI/CD pipeline for enhanced BunnyFarm
74
+ - [ ] Plan backward compatibility strategy for existing users
75
+ - [ ] Prepare deprecation timeline for original BunnyFarm patterns
76
+
77
+ ---
78
+
79
+ ## Phase 2: Agent99 Integration (Weeks 5-6)
80
+
81
+ ### 2.1 Replace Agent99's AMQP Client
82
+ - [ ] **Current State Analysis**
83
+ - [ ] Audit Agent99's existing AMQP message client implementation
84
+ - [ ] Map Agent99 message patterns to enhanced BunnyFarm workflows
85
+ - [ ] Identify Agent99-specific message routing requirements
86
+ - [ ] Document current Agent99 API surface that must be maintained
87
+
88
+ - [ ] **Integration Implementation**
89
+ - [ ] Replace `Agent99::AmqpMessageClient` with enhanced BunnyFarm
90
+ - [ ] Map Agent99 message headers to SmartMessage entity addressing
91
+ - [ ] Implement Agent99 message types as enhanced BunnyFarm workflow classes
92
+ - [ ] Maintain existing Agent99 public API compatibility
93
+ - [ ] Update Agent99's message dispatcher to use enhanced BunnyFarm
94
+
95
+ - [ ] **Message Pattern Migration**
96
+ - [ ] Convert Agent99 request messages to workflow pattern
97
+ - [ ] Convert Agent99 response messages to workflow pattern
98
+ - [ ] Convert Agent99 control messages to workflow pattern
99
+ - [ ] Implement Agent99-specific routing logic in enhanced BunnyFarm
100
+ - [ ] Add Agent99 message validation using enhanced BunnyFarm patterns
101
+
102
+ ### 2.2 Workflow Integration & Enhancement
103
+ - [ ] **Agent Lifecycle Integration**
104
+ - [ ] Integrate enhanced BunnyFarm workflows with Agent99 lifecycle
105
+ - [ ] Add success/failure handling to Agent99 message processing
106
+ - [ ] Implement automatic routing for agent-to-agent communication
107
+ - [ ] Add workflow state tracking to Agent99 agent instances
108
+ - [ ] Integrate enhanced BunnyFarm configuration with Agent99 settings
109
+
110
+ - [ ] **Registry Integration**
111
+ - [ ] Update Agent99 registry integration to work with enhanced BunnyFarm
112
+ - [ ] Implement agent discovery using enhanced BunnyFarm workflows
113
+ - [ ] Add registry communication through SmartMessage transport abstraction
114
+ - [ ] Update agent registration/withdrawal to use workflow patterns
115
+ - [ ] Maintain Agent99's existing registry API compatibility
116
+
117
+ - [ ] **Testing & Validation**
118
+ - [ ] Create comprehensive test suite for Agent99 + enhanced BunnyFarm
119
+ - [ ] Test all Agent99 message types with new workflow system
120
+ - [ ] Validate Agent99 multi-agent scenarios with enhanced BunnyFarm
121
+ - [ ] Performance testing: Agent99 with enhanced vs original messaging
122
+ - [ ] Integration testing with Agent99 registry and discovery systems
123
+
124
+ ---
125
+
126
+ ## Phase 3: Lanet P2P Integration (Weeks 7-8)
127
+
128
+ ### 3.1 Lanet Transport Plugin Development
129
+ - [ ] **SmartMessage-Transport-Lanet Gem Creation**
130
+ - [ ] Create new gem: `smart_message-transport-lanet`
131
+ - [ ] Implement `SmartMessage::Transport::Lanet` class
132
+ - [ ] Add Lanet-specific configuration and connection management
133
+ - [ ] Implement BunnyFarm workflow patterns over Lanet P2P
134
+ - [ ] Create auto-registration system for Lanet transport
135
+
136
+ - [ ] **Lanet Integration Implementation**
137
+ - [ ] Integrate Lanet's network discovery with Agent99 registry
138
+ - [ ] Implement IP resolution for agent UUIDs using Lanet scanning
139
+ - [ ] Add Lanet P2P message routing with BunnyFarm workflows
140
+ - [ ] Implement Lanet encryption/decryption in transport layer
141
+ - [ ] Add Lanet connection health monitoring and failover
142
+
143
+ - [ ] **P2P Workflow Support**
144
+ - [ ] Ensure BunnyFarm workflows work over direct P2P connections
145
+ - [ ] Implement P2P-specific success/failure handling
146
+ - [ ] Add P2P message acknowledgment and retry mechanisms
147
+ - [ ] Create P2P network topology discovery and mapping
148
+ - [ ] Handle P2P connection failures and transport failover
149
+
150
+ ### 3.2 Intelligent Transport Selection
151
+ - [ ] **Smart Routing Implementation**
152
+ - [ ] Implement intelligent transport selection algorithm
153
+ - [ ] Add `same_process?()` detection for Memory transport
154
+ - [ ] Add `same_machine?()` detection for Named Pipes vs Redis selection
155
+ - [ ] Add `same_lan?()` detection logic for Lanet routing
156
+ - [ ] Create transport preference configuration system
157
+ - [ ] Implement automatic fallback when connections fail
158
+ - [ ] Add transport selection based on message type and requirements
159
+ - [ ] Implement performance-based transport selection
160
+
161
+ - [ ] **Network Discovery & Topology**
162
+ - [ ] Integrate Lanet network scanning with Agent99 registry
163
+ - [ ] Implement automatic agent network topology mapping
164
+ - [ ] Add LAN segment detection and agent grouping
165
+ - [ ] Create network health monitoring and reporting
166
+ - [ ] Implement dynamic transport selection based on network conditions
167
+
168
+ - [ ] **Hybrid P2P System Completion**
169
+ - [ ] Complete integration of all transport layers (Memory, Named Pipes, Redis, AMQP, Lanet)
170
+ - [ ] Implement comprehensive transport selection decision tree
171
+ - [ ] Add transport performance monitoring and optimization
172
+ - [ ] Create transport usage analytics and reporting
173
+ - [ ] Validate complete hybrid P2P system functionality
174
+ - [ ] Document transport selection hierarchy and use cases
175
+
176
+ ---
177
+
178
+ ## Phase 4: Production Readiness (Weeks 9-10)
179
+
180
+ ### 4.1 System Integration & Testing
181
+ - [ ] **End-to-End Integration**
182
+ - [ ] Complete system testing: Agent99 + Enhanced BunnyFarm + All Transports
183
+ - [ ] Multi-scenario testing across all transport combinations
184
+ - [ ] Test transport hierarchy: Memory → Named Pipes → Redis → Lanet → AMQP/NATS
185
+ - [ ] Load testing with multiple agents across different network topologies
186
+ - [ ] Stress testing transport failover and recovery mechanisms
187
+ - [ ] Security testing for P2P encryption and message integrity
188
+ - [ ] Performance validation: Named Pipes vs Redis for same-machine scenarios
189
+
190
+ - [ ] **Performance Optimization**
191
+ - [ ] Profile and optimize transport selection algorithms
192
+ - [ ] Implement connection pooling and message batching optimizations
193
+ - [ ] Add caching for agent discovery and network topology
194
+ - [ ] Optimize memory usage across all transport implementations
195
+ - [ ] Benchmark complete system against original Agent99 performance
196
+
197
+ - [ ] **Monitoring & Observability**
198
+ - [ ] Implement comprehensive logging across all system components
199
+ - [ ] Add metrics collection for transport usage and performance
200
+ - [ ] Create health check endpoints for all system components
201
+ - [ ] Implement alerting for transport failures and performance issues
202
+ - [ ] Add debugging tools for multi-transport message flows
203
+
204
+ ### 4.2 Documentation & Migration
205
+ - [ ] **Production Documentation**
206
+ - [ ] Complete API documentation for enhanced Agent99 system
207
+ - [ ] Create deployment guides for different network configurations
208
+ - [ ] Write troubleshooting guides for common issues
209
+ - [ ] Document performance tuning and optimization recommendations
210
+ - [ ] Create monitoring and maintenance guides
211
+
212
+ - [ ] **Migration Support**
213
+ - [ ] Create automated migration tools for existing Agent99 deployments
214
+ - [ ] Write step-by-step migration guides with examples
215
+ - [ ] Develop backward compatibility testing framework
216
+ - [ ] Create rollback procedures for failed migrations
217
+ - [ ] Prepare support documentation for migration issues
218
+
219
+ - [ ] **Community & Ecosystem**
220
+ - [ ] Prepare all gems for public release (enhanced BunnyFarm, transport extensions)
221
+ - [ ] Create example applications showcasing P2P capabilities
222
+ - [ ] Write blog posts and tutorials about the new architecture
223
+ - [ ] Prepare conference talks and presentations
224
+ - [ ] Set up community support channels and documentation sites
225
+
226
+ ---
227
+
228
+ ## Phase 5: Advanced Features & NATS Integration (Weeks 11-12)
229
+
230
+ ### 5.1 NATS Transport Plugin
231
+ - [ ] **SmartMessage-Transport-NATS Gem Creation**
232
+ - [ ] Create new gem: `smart_message-transport-nats`
233
+ - [ ] Implement `SmartMessage::Transport::NATS` class
234
+ - [ ] Add NATS-specific configuration and clustering support
235
+ - [ ] Implement BunnyFarm workflows over NATS messaging
236
+ - [ ] Create auto-registration system for NATS transport
237
+
238
+ - [ ] **NATS Integration Features**
239
+ - [ ] Map Agent99 capability routing to NATS subject patterns
240
+ - [ ] Implement NATS clustering for high availability
241
+ - [ ] Add NATS monitoring integration with Agent99 health checks
242
+ - [ ] Create NATS-specific performance optimizations
243
+ - [ ] Implement NATS subject-based message filtering
244
+
245
+ ### 5.2 Advanced System Features
246
+ - [ ] **Load Balancing & Auto-Scaling**
247
+ - [ ] Implement load balancing across multiple agent instances
248
+ - [ ] Add auto-scaling triggers based on message load
249
+ - [ ] Create agent deployment automation tools
250
+ - [ ] Implement dynamic agent discovery and registration
251
+ - [ ] Add capacity planning and resource management tools
252
+
253
+ - [ ] **Advanced Security & Authentication**
254
+ - [ ] Implement end-to-end message encryption across all transports
255
+ - [ ] Add agent authentication and authorization framework
256
+ - [ ] Create secure key management and distribution system
257
+ - [ ] Implement message signing and verification
258
+ - [ ] Add audit logging for security compliance
259
+
260
+ ---
261
+
262
+ ## Progress Tracking
263
+
264
+ ### Overall Progress
265
+ - [ ] **Phase 1 Complete** (0/4 weeks) - Enhanced BunnyFarm + Named Pipes
266
+ - [ ] **Phase 2 Complete** (0/2 weeks) - Agent99 Integration
267
+ - [ ] **Phase 3 Complete** (0/2 weeks) - Lanet P2P Integration
268
+ - [ ] **Phase 4 Complete** (0/2 weeks) - Production Readiness
269
+ - [ ] **Phase 5 Complete** (0/2 weeks) - NATS + Advanced Features
270
+
271
+ ### Key Milestones
272
+ - [ ] Enhanced BunnyFarm with SmartMessage integration released
273
+ - [ ] Named Pipes transport implemented and benchmarked
274
+ - [ ] Agent99 successfully migrated to enhanced BunnyFarm
275
+ - [ ] Lanet P2P transport fully integrated and tested
276
+ - [ ] Complete transport hierarchy operational (6 transport layers)
277
+ - [ ] Production-ready system with full documentation
278
+ - [ ] NATS transport and advanced features completed
279
+
280
+ ### Risk Mitigation
281
+ - [ ] Backward compatibility maintained throughout migration
282
+ - [ ] Performance benchmarks meet or exceed original system
283
+ - [ ] Security audit completed and vulnerabilities addressed
284
+ - [ ] Community adoption and feedback incorporated
285
+ - [ ] Production deployments successful and stable
286
+
287
+ ---
288
+
289
+ ## Notes
290
+ - Each checklist item should be treated as an atomic unit of work
291
+ - Items can be worked on in parallel where dependencies allow
292
+ - Regular milestone reviews should be conducted at the end of each week
293
+ - Community feedback should be incorporated throughout the development process
294
+ - Performance benchmarks should be maintained and monitored continuously
295
+
296
+ ---
297
+
298
+ *Last Updated: 2025-01-03*
299
+ *Status: Ready for Implementation*