swarm_sdk 2.7.14 → 3.0.0.alpha2

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.7.14
+  version: 3.0.0.alpha2
 platform: ruby
 authors:
 - Paulo Arruda
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -24,61 +24,75 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: async-http-faraday
+  name: faiss
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: 0.5.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: 0.5.2
 - !ruby/object:Gem::Dependency
-  name: faraday-follow_redirects
+  name: informers
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: 1.2.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: 1.2.1
 - !ruby/object:Gem::Dependency
-  name: ruby_llm
+  name: mcp
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: 0.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: 0.6.0
 - !ruby/object:Gem::Dependency
-  name: ruby_llm_swarm-mcp
+  name: rice
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.2
+        version: 4.8.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.2
+        version: 4.8.0
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -94,11 +108,11 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.6'
 description: |
-  SwarmSDK is a complete reimagining of Claude Swarm that runs all AI agents in a single process
-  using RubyLLM for LLM interactions. Define collaborative AI agents in simple Markdown files with
-  YAML frontmatter, and orchestrate them without the overhead of multiple processes or MCP
-  inter-process communication. Perfect for building lightweight, efficient AI agent teams with
-  specialized roles and capabilities.
+  SwarmSDK V3 is the next-generation agent primitive with built-in memory.
+  The core insight: the LLM's context window is a staging area, not the whole brain.
+  Older turns get consolidated into memory cards, and retrieval brings relevant
+  memory back into working context on demand. Single-process, lightweight, and
+  efficient AI agent development with RubyLLM.
 email:
 - parrudaj@gmail.com
 executables: []
@@ -106,76 +120,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
-- lib/swarm_sdk.rb
-- lib/swarm_sdk/agent/RETRY_LOGIC.md
-- lib/swarm_sdk/agent/builder.rb
-- lib/swarm_sdk/agent/chat.rb
-- lib/swarm_sdk/agent/chat_helpers/context_tracker.rb
-- lib/swarm_sdk/agent/chat_helpers/event_emitter.rb
-- lib/swarm_sdk/agent/chat_helpers/hook_integration.rb
-- lib/swarm_sdk/agent/chat_helpers/instrumentation.rb
-- lib/swarm_sdk/agent/chat_helpers/llm_configuration.rb
-- lib/swarm_sdk/agent/chat_helpers/logging_helpers.rb
-- lib/swarm_sdk/agent/chat_helpers/serialization.rb
-- lib/swarm_sdk/agent/chat_helpers/system_reminder_injector.rb
-- lib/swarm_sdk/agent/chat_helpers/system_reminders.rb
-- lib/swarm_sdk/agent/chat_helpers/token_tracking.rb
-- lib/swarm_sdk/agent/context.rb
-- lib/swarm_sdk/agent/context_manager.rb
-- lib/swarm_sdk/agent/definition.rb
-- lib/swarm_sdk/agent/llm_instrumentation_middleware.rb
-- lib/swarm_sdk/agent/system_prompt_builder.rb
-- lib/swarm_sdk/agent/tool_registry.rb
-- lib/swarm_sdk/agent_registry.rb
-- lib/swarm_sdk/builders/base_builder.rb
-- lib/swarm_sdk/claude_code_agent_adapter.rb
-- lib/swarm_sdk/concerns/cleanupable.rb
-- lib/swarm_sdk/concerns/snapshotable.rb
-- lib/swarm_sdk/concerns/validatable.rb
-- lib/swarm_sdk/config.rb
-- lib/swarm_sdk/configuration.rb
-- lib/swarm_sdk/configuration/parser.rb
-- lib/swarm_sdk/configuration/translator.rb
-- lib/swarm_sdk/context_compactor.rb
-- lib/swarm_sdk/context_compactor/metrics.rb
-- lib/swarm_sdk/context_compactor/token_counter.rb
-- lib/swarm_sdk/context_management/builder.rb
-- lib/swarm_sdk/context_management/context.rb
-- lib/swarm_sdk/custom_tool_registry.rb
-- lib/swarm_sdk/defaults.rb
-- lib/swarm_sdk/events_to_messages.rb
-- lib/swarm_sdk/hooks/adapter.rb
-- lib/swarm_sdk/hooks/context.rb
-- lib/swarm_sdk/hooks/definition.rb
-- lib/swarm_sdk/hooks/error.rb
-- lib/swarm_sdk/hooks/executor.rb
-- lib/swarm_sdk/hooks/registry.rb
-- lib/swarm_sdk/hooks/result.rb
-- lib/swarm_sdk/hooks/shell_executor.rb
-- lib/swarm_sdk/hooks/tool_call.rb
-- lib/swarm_sdk/hooks/tool_result.rb
-- lib/swarm_sdk/log_collector.rb
-- lib/swarm_sdk/log_stream.rb
-- lib/swarm_sdk/markdown_parser.rb
-- lib/swarm_sdk/model_aliases.json
-- lib/swarm_sdk/models.json
-- lib/swarm_sdk/models.rb
-- lib/swarm_sdk/node_context.rb
-- lib/swarm_sdk/observer/builder.rb
-- lib/swarm_sdk/observer/config.rb
-- lib/swarm_sdk/observer/manager.rb
-- lib/swarm_sdk/patterns/agent_observer.rb
-- lib/swarm_sdk/permissions/config.rb
-- lib/swarm_sdk/permissions/error_formatter.rb
-- lib/swarm_sdk/permissions/path_matcher.rb
-- lib/swarm_sdk/permissions/validator.rb
-- lib/swarm_sdk/permissions_builder.rb
-- lib/swarm_sdk/plugin.rb
-- lib/swarm_sdk/plugin_registry.rb
-- lib/swarm_sdk/proc_helpers.rb
-- lib/swarm_sdk/prompts/base_system_prompt.md.erb
-- lib/swarm_sdk/restore_result.rb
-- lib/swarm_sdk/result.rb
 - lib/swarm_sdk/ruby_llm_patches/chat_callbacks_patch.rb
 - lib/swarm_sdk/ruby_llm_patches/configuration_patch.rb
 - lib/swarm_sdk/ruby_llm_patches/connection_patch.rb
@@ -185,70 +129,65 @@ files:
 - lib/swarm_sdk/ruby_llm_patches/message_management_patch.rb
 - lib/swarm_sdk/ruby_llm_patches/responses_api_patch.rb
 - lib/swarm_sdk/ruby_llm_patches/tool_concurrency_patch.rb
-- lib/swarm_sdk/snapshot.rb
-- lib/swarm_sdk/snapshot_from_events.rb
-- lib/swarm_sdk/state_restorer.rb
-- lib/swarm_sdk/state_snapshot.rb
-- lib/swarm_sdk/swarm.rb
-- lib/swarm_sdk/swarm/agent_initializer.rb
-- lib/swarm_sdk/swarm/all_agents_builder.rb
-- lib/swarm_sdk/swarm/builder.rb
-- lib/swarm_sdk/swarm/executor.rb
-- lib/swarm_sdk/swarm/hook_triggers.rb
-- lib/swarm_sdk/swarm/lazy_delegate_chat.rb
-- lib/swarm_sdk/swarm/logging_callbacks.rb
-- lib/swarm_sdk/swarm/mcp_configurator.rb
-- lib/swarm_sdk/swarm/swarm_registry_builder.rb
-- lib/swarm_sdk/swarm/tool_configurator.rb
-- lib/swarm_sdk/swarm_loader.rb
-- lib/swarm_sdk/swarm_registry.rb
-- lib/swarm_sdk/tools/base.rb
-- lib/swarm_sdk/tools/bash.rb
-- lib/swarm_sdk/tools/clock.rb
-- lib/swarm_sdk/tools/delegate.rb
-- lib/swarm_sdk/tools/document_converters/base_converter.rb
-- lib/swarm_sdk/tools/document_converters/docx_converter.rb
-- lib/swarm_sdk/tools/document_converters/html_converter.rb
-- lib/swarm_sdk/tools/document_converters/pdf_converter.rb
-- lib/swarm_sdk/tools/document_converters/xlsx_converter.rb
-- lib/swarm_sdk/tools/edit.rb
-- lib/swarm_sdk/tools/glob.rb
-- lib/swarm_sdk/tools/grep.rb
-- lib/swarm_sdk/tools/image_extractors/docx_image_extractor.rb
-- lib/swarm_sdk/tools/image_extractors/pdf_image_extractor.rb
-- lib/swarm_sdk/tools/image_formats/tiff_builder.rb
-- lib/swarm_sdk/tools/mcp_tool_stub.rb
-- lib/swarm_sdk/tools/multi_edit.rb
-- lib/swarm_sdk/tools/path_resolver.rb
-- lib/swarm_sdk/tools/read.rb
-- lib/swarm_sdk/tools/registry.rb
-- lib/swarm_sdk/tools/scratchpad/scratchpad_list.rb
-- lib/swarm_sdk/tools/scratchpad/scratchpad_read.rb
-- lib/swarm_sdk/tools/scratchpad/scratchpad_write.rb
-- lib/swarm_sdk/tools/stores/read_tracker.rb
-- lib/swarm_sdk/tools/stores/scratchpad_storage.rb
-- lib/swarm_sdk/tools/stores/storage.rb
-- lib/swarm_sdk/tools/stores/todo_manager.rb
-- lib/swarm_sdk/tools/think.rb
-- lib/swarm_sdk/tools/todo_write.rb
-- lib/swarm_sdk/tools/web_fetch.rb
-- lib/swarm_sdk/tools/write.rb
-- lib/swarm_sdk/transcript_builder.rb
-- lib/swarm_sdk/utils.rb
-- lib/swarm_sdk/validation_result.rb
-- lib/swarm_sdk/version.rb
-- lib/swarm_sdk/workflow.rb
-- lib/swarm_sdk/workflow/agent_config.rb
-- lib/swarm_sdk/workflow/builder.rb
-- lib/swarm_sdk/workflow/executor.rb
-- lib/swarm_sdk/workflow/node_builder.rb
-- lib/swarm_sdk/workflow/transformer_executor.rb
+- lib/swarm_sdk/v3.rb
+- lib/swarm_sdk/v3/agent.rb
+- lib/swarm_sdk/v3/agent_builder.rb
+- lib/swarm_sdk/v3/agent_definition.rb
+- lib/swarm_sdk/v3/configuration.rb
+- lib/swarm_sdk/v3/debug_log.rb
+- lib/swarm_sdk/v3/event_stream.rb
+- lib/swarm_sdk/v3/hooks/context.rb
+- lib/swarm_sdk/v3/hooks/result.rb
+- lib/swarm_sdk/v3/hooks/runner.rb
+- lib/swarm_sdk/v3/mcp/connector.rb
+- lib/swarm_sdk/v3/mcp/mcp_error.rb
+- lib/swarm_sdk/v3/mcp/server_definition.rb
+- lib/swarm_sdk/v3/mcp/ssl_http_transport.rb
+- lib/swarm_sdk/v3/mcp/stdio_transport.rb
+- lib/swarm_sdk/v3/mcp/tool_proxy.rb
+- lib/swarm_sdk/v3/memory/adapters/base.rb
+- lib/swarm_sdk/v3/memory/adapters/faiss_support.rb
+- lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb
+- lib/swarm_sdk/v3/memory/adapters/sqlite_adapter.rb
+- lib/swarm_sdk/v3/memory/adapters/vector_utils.rb
+- lib/swarm_sdk/v3/memory/card.rb
+- lib/swarm_sdk/v3/memory/cluster.rb
+- lib/swarm_sdk/v3/memory/compressor.rb
+- lib/swarm_sdk/v3/memory/consolidator.rb
+- lib/swarm_sdk/v3/memory/context_builder.rb
+- lib/swarm_sdk/v3/memory/edge.rb
+- lib/swarm_sdk/v3/memory/embedder.rb
+- lib/swarm_sdk/v3/memory/exposure_tracker.rb
+- lib/swarm_sdk/v3/memory/ingestion_pipeline.rb
+- lib/swarm_sdk/v3/memory/retriever.rb
+- lib/swarm_sdk/v3/memory/store.rb
+- lib/swarm_sdk/v3/skills/loader.rb
+- lib/swarm_sdk/v3/skills/manifest.rb
+- lib/swarm_sdk/v3/sub_task_agent.rb
+- lib/swarm_sdk/v3/tools/base.rb
+- lib/swarm_sdk/v3/tools/bash.rb
+- lib/swarm_sdk/v3/tools/clock.rb
+- lib/swarm_sdk/v3/tools/document_converters/base.rb
+- lib/swarm_sdk/v3/tools/document_converters/docx_converter.rb
+- lib/swarm_sdk/v3/tools/document_converters/pdf_converter.rb
+- lib/swarm_sdk/v3/tools/document_converters/xlsx_converter.rb
+- lib/swarm_sdk/v3/tools/edit.rb
+- lib/swarm_sdk/v3/tools/glob.rb
+- lib/swarm_sdk/v3/tools/grep.rb
+- lib/swarm_sdk/v3/tools/message_teammate.rb
+- lib/swarm_sdk/v3/tools/message_user.rb
+- lib/swarm_sdk/v3/tools/read.rb
+- lib/swarm_sdk/v3/tools/read_tracker.rb
+- lib/swarm_sdk/v3/tools/registry.rb
+- lib/swarm_sdk/v3/tools/sub_task.rb
+- lib/swarm_sdk/v3/tools/think.rb
+- lib/swarm_sdk/v3/tools/write.rb
 homepage: https://github.com/parruda/swarm
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/parruda/swarm
-  changelog_uri: https://github.com/parruda/swarm/blob/main/docs/v2/CHANGELOG.swarm_sdk.md
+  changelog_uri: https://github.com/parruda/swarm/blob/main/docs/v3/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -265,5 +204,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Lightweight multi-agent AI orchestration using RubyLLM
+summary: Next-generation AI agent primitive with built-in memory
 test_files: []

data/lib/swarm_sdk/agent/RETRY_LOGIC.md

@@ -1,175 +0,0 @@
-# LLM Call Retry Logic
-
-## Feature
-
-SwarmSDK automatically retries failed LLM API calls to handle transient failures.
-
-## Configuration
-
-**Defaults:**
-- Max retries: 10
-- Delay: 10 seconds (fixed, no exponential backoff)
-- Retries ALL StandardError exceptions
-
-## Implementation
-
-**Location:** `lib/swarm_sdk/agent/chat.rb`
-
-The retry logic handles two categories of errors:
-
-1. **Transient failures** - Network issues, timeouts, rate limits
-2. **Orphan tool call errors** - Special recovery for malformed conversation history
-
-## Error Types Handled
-
-- `Faraday::ConnectionFailed` - Network connection issues
-- `Faraday::TimeoutError` - Request timeouts
-- `RubyLLM::APIError` - API errors (500s, etc.)
-- `RubyLLM::RateLimitError` - Rate limit errors
-- `RubyLLM::BadRequestError` - With special handling for orphan tool calls
-- Any other `StandardError` - Catches proxy issues, DNS failures, etc.
-
-## Orphan Tool Call Recovery
-
-**What are orphan tool calls?**
-
-Orphan tool calls occur when an assistant message contains `tool_use` blocks but the conversation lacks corresponding `tool_result` messages. This can happen when:
-- Tool execution is interrupted mid-stream
-- Session state restoration is incomplete
-- Network issues cause partial message delivery
-
-**How recovery works:**
-
-When a `RubyLLM::BadRequestError` (400) is received with tool-related error messages:
-
-1. Clears stale ephemeral content from the failed call
-2. The system scans message history for orphan tool calls
-3. For each assistant message with `tool_calls`:
-   - Checks if all `tool_call_id`s have matching `tool_result` messages
-   - Any missing results indicate orphan tool calls
-4. Orphan tool calls are pruned:
-   - If assistant message has content, keeps content but removes `tool_calls`
-   - If assistant message is empty, removes the entire message
-5. **System reminder is added** to inform the agent:
-   - Lists which tool calls were interrupted
-   - Tells agent they were never executed
-   - Suggests re-running them if still needed
-6. Retries the LLM call immediately (doesn't count as a retry)
-7. If no orphans found, falls through to normal retry logic
-
-**Tool-related error patterns detected:**
-- `tool_use`, `tool_result`, `tool_use_id`
-- `corresponding tool_result`
-- `must immediately follow`
-
-**Logging:**
-
-When orphan pruning occurs, emits `orphan_tool_calls_pruned` event:
-```json
-{
-  "type": "orphan_tool_calls_pruned",
-  "agent": "agent_name",
-  "pruned_count": 1,
-  "original_error": "tool_use block must have corresponding tool_result"
-}
-```
-
-**System Reminder Format:**
-
-The agent receives a system reminder about the pruned tool calls:
-```
-<system-reminder>
-The following tool calls were interrupted and removed from conversation history:
-
-- Read(file_path: "/important/file.rb")
-- Write(file_path: "/output.txt", content: "Hello...")
-
-These tools were never executed. If you still need their results, please run them again.
-</system-reminder>
-```
-
-## Usage
-
-**Automatic - No Configuration Needed:**
-
-```ruby
-swarm = SwarmSDK.build do
-  agent :my_agent do
-    model "gpt-4"
-    base_url "http://proxy.example.com/v1"  # Can fail
-  end
-end
-
-# Automatically retries on failure and recovers from orphan tool calls
-response = swarm.execute("Do something")
-```
-
-## Logging
-
-**On Retry:**
-```
-WARN: SwarmSDK: LLM call failed (attempt 1/10): Faraday::ConnectionFailed: Connection failed
-WARN: SwarmSDK: Retrying in 10 seconds...
-```
-
-**On Max Retries:**
-```
-ERROR: SwarmSDK: LLM call failed after 10 attempts: Faraday::ConnectionFailed: Connection failed
-```
-
-## Behavior
-
-**Scenario 1: Transient failure**
-```
-Attempt 1: ConnectionFailed
-  → Wait 10s
-Attempt 2: ConnectionFailed
-  → Wait 10s
-Attempt 3: Success
-  → Returns response
-```
-
-**Scenario 2: Persistent failure**
-```
-Attempt 1-10: All fail
-  → Raises original error after attempt 10
-```
-
-**Scenario 3: Immediate success**
-```
-Attempt 1: Success
-  → Returns response (no retry needed)
-```
-
-**Scenario 4: Orphan tool call recovery**
-```
-Attempt 1: BadRequestError (tool_use without tool_result)
-  → Detect orphan tool calls
-  → Prune orphan tool calls from message history
-  → Retry immediately (doesn't count as retry)
-Attempt 1: Success
-  → Returns response
-```
-
-## Why No Exponential Backoff
-
-**Design Decision:** Fixed 10-second delay
-
-**Rationale:**
-- Simpler implementation
-- Predictable retry duration (max 100 seconds)
-- Transient proxy/network issues typically resolve within seconds
-- Rate limit errors are caught by provider-specific handling
-- User explicitly requested fixed delays
-
-**Total max time:** 10 retries × 10 seconds = 100 seconds maximum
-
-## Future Enhancements (If Needed)
-
-- [ ] Configurable retry count per agent
-- [ ] Configurable delay per agent
-- [ ] Selective retry based on error type
-- [ ] Exponential backoff option
-- [ ] Circuit breaker pattern
-
-**Current State:** Production-ready with sensible defaults for proxy/network resilience and automatic orphan tool call recovery.