{"id":45374677,"url":"https://github.com/christopherkarani/swarm","last_synced_at":"2026-04-01T19:18:40.614Z","repository":{"id":328751563,"uuid":"1115043545","full_name":"christopherkarani/Swarm","owner":"christopherkarani","description":"🐦‍🔥 A Lightweight Agent Orchestration Framework written in pure Swift 6.2 ","archived":false,"fork":false,"pushed_at":"2026-02-20T06:12:50.000Z","size":2568,"stargazers_count":366,"open_issues_count":4,"forks_count":21,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-02-20T16:20:36.851Z","etag":null,"topics":["agent","agentic-ai","agentic-systems","agents","ai","ai-agents","foundation-models","ios","langchain","machine-learning","macos","memory","offline-first","server-side","swift","swift-agents","swift-library","swiftui","watchos"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/christopherkarani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-12T09:01:41.000Z","updated_at":"2026-02-20T07:43:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/christopherkarani/Swarm","commit_stats":null,"previous_names":["christopherkarani/swiftagents","christopherkarani/swarm"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/christopherkarani/Swarm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christopherkarani%2FSwarm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christopherkarani%2FSwarm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christopherkarani%2FSwarm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christopherkarani%2FSwarm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/christopherkarani","download_url":"https://codeload.github.com/christopherkarani/Swarm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christopherkarani%2FSwarm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29685018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T15:51:39.154Z","status":"ssl_error","status_checked_at":"2026-02-21T15:49:03.425Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agentic-ai","agentic-systems","agents","ai","ai-agents","foundation-models","ios","langchain","machine-learning","macos","memory","offline-first","server-side","swift","swift-agents","swift-library","swiftui","watchos"],"created_at":"2026-02-21T16:01:01.596Z","updated_at":"2026-02-21T16:01:03.275Z","avatar_url":"https://github.com/christopherkarani.png","language":"Swift","readme":"\u003cimg width=\"3168\" height=\"1344\" alt=\"Swarm — Swift Agent Framework\" src=\"https://github.com/user-attachments/assets/62b0d34a-a0d4-45a9-a289-0e384939839f\" /\u003e\n\n[![Swift 6.2](https://img.shields.io/badge/Swift-6.2-orange.svg)](https://swift.org)\n[![Platforms](https://img.shields.io/badge/Platforms-iOS%2026%2B%20%7C%20macOS%2026%2B%20%7C%20Linux-blue.svg)](https://swift.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![SPM](https://img.shields.io/badge/Swift%20Package%20Manager-compatible-brightgreen.svg)](https://swift.org/package-manager/)\n\n\u003e ⭐ If Swarm is useful to you, a star helps others find it.\n\n# Swarm\n\n**Multi-agent orchestration for Swift — built for production, not demos.**\n\n```swift\nlet result = try await (fetchAgent --\u003e reasonAgent --\u003e writerAgent)\n    .run(\"Summarize the WWDC session on Swift concurrency.\")\n\nprint(result.output)\n```\n\nThree agents. One line. Crash-resumable, data-race-safe, compiled to a DAG.\n\n---\n\n## Why Swarm\n\nMost agent frameworks are Python-first, stringly-typed, and assume every workflow completes in one shot. Swarm makes three different bets.\n\n### 1. Data races are compile errors\n\nSwift 6.2's `StrictConcurrency` is enabled across every Swarm target — agents, memory systems, orchestrators, macros, and tests. Non-`Sendable` types crossing actor boundaries is a **build failure**, not a 3 AM incident.\n\n```swift\n// ❌ Compile error under Swarm's StrictConcurrency — caught before it ships\nstruct BrokenAgent: AgentRuntime {\n    var cache: NSCache\u003cNSString, NSString\u003e\n    // error: stored property 'cache' of 'Sendable'-conforming struct\n    //        has non-Sendable type 'NSCache\u003cNSString, NSString\u003e'\n}\n\n// ✓ Actor isolation makes shared state safe by construction\nactor ResponseCache {\n    private var store: [String: String] = [:]\n    func set(_ value: String, for key: String) { store[key] = value }\n    func get(_ key: String) -\u003e String? { store[key] }\n}\n```\n\n### 2. Workflows survive crashes\n\nSwarm ships a `WorkflowCheckpointStore` protocol with two built-in implementations: `InMemoryWorkflowCheckpointStore` for tests and `FileSystemWorkflowCheckpointStore` for production. Each step boundary writes a snapshot. A pipeline that crashes on step 7 of 10 resumes from step 7 — not from the beginning.\n\n```swift\n// Crash-recovery checkpoint store — survives process restarts\nlet store = FileSystemWorkflowCheckpointStore(\n    directory: .applicationSupportDirectory.appending(path: \"workflow-checkpoints\")\n)\n\n// Snapshots are serialised JSON — human-readable, diff-friendly\n// { \"workflowID\": \"run-42\", \"stepIndex\": 3, \"intermediateOutput\": \"...\", \"timestamp\": \"...\" }\n```\n\n### 3. Orchestration is a DSL, not a switch statement\n\nEleven composable step types in a SwiftUI-style `@resultBuilder`. Sequential chains use `--\u003e`. Type-safe pipelines use `\u003e\u003e\u003e`. Dependency DAGs use `.dependsOn()`. Human review gates use a three-way response.\n\n```swift\n// Sequential chain\nfetchAgent --\u003e analyzeAgent --\u003e writerAgent\n\n// Type-safe pipeline (compiler enforces Input/Output types at each stage)\nlet pipeline = Pipeline\u003cString, [String]\u003e  { $0.components(separatedBy: \"\\n\") }\n             \u003e\u003e\u003e Pipeline\u003c[String], String\u003e { $0.filter { !$0.isEmpty }.joined(separator: \"• \") }\n\n// Dependency DAG — nodes run as soon as their dependencies complete\nDAGWorkflow(nodes: [\n    DAGNode(\"fetch\",   agent: fetchAgent),\n    DAGNode(\"refs\",    agent: refsAgent),\n    DAGNode(\"analyze\", agent: analyzeAgent).dependsOn(\"fetch\", \"refs\"),\n    DAGNode(\"write\",   agent: writerAgent).dependsOn(\"analyze\"),\n])\n\n// Human-in-the-loop: three-way response\nHumanApproval(\"Approve before publishing?\", handler: reviewerUI)\n// .approved          → workflow continues with current output\n// .rejected(reason)  → workflow throws OrchestrationError.humanApprovalRejected\n// .modified(newInput) → corrected value flows forward, replacing the agent's output\n```\n\n---\n\n## How Swarm Compares\n\n| | Swarm | LangChain (Python) | AutoGen |\n|---|---|---|---|\n| Language | Swift 6.2 | Python | Python |\n| Data race safety | Compile-time ✓ | Runtime | Runtime |\n| On-device LLM | Foundation Models ✓ | ❌ | ❌ |\n| DAG execution engine | Hive (compiled) ✓ | Loop-based | Loop-based |\n| Crash-resumable workflows | ✓ `FileSystemCheckpointStore` | ❌ | Partial |\n| Type-safe tool parameters | ✓ `@Tool` macro | Decorators (runtime) | Runtime |\n| Streaming | `AsyncThrowingStream` ✓ | Callbacks | Callbacks |\n| iOS support | ✓ iOS 26+ | ❌ | ❌ |\n\n---\n\n## Quick Start\n\n```swift\nimport Swarm\n\n// 1. Define a tool\n@Tool(\"Returns the current price of a stock\")\nstruct StockPriceTool {\n    @Parameter(\"Ticker symbol, e.g. AAPL\")\n    var ticker: String\n\n    func execute() async throws -\u003e String {\n        // call your price API here\n        return \"182.50\"\n    }\n}\n\n// 2. Define an agent blueprint\nstruct FinanceAgent: AgentBlueprint {\n    let analyst = Agent(\n        name: \"Analyst\",\n        tools: [StockPriceTool()],\n        instructions: \"Answer finance questions concisely using real data.\"\n    )\n\n    @OrchestrationBuilder var body: some OrchestrationStep {\n        Guard(.input) {\n            InputGuard(\"no_pii\") { input in\n                input.contains(\"SSN\") ? .tripwire(message: \"PII detected\") : .passed()\n            }\n        }\n        analyst\n    }\n}\n\n// 3. Run it\nlet result = try await FinanceAgent()\n    .environment(\\.inferenceProvider, .anthropic(key: \"YOUR_API_KEY\"))\n    .run(\"What is the current price of AAPL?\")\n\nprint(result.output)\n```\n\n---\n\n## Features\n\n| Capability | Detail |\n|---|---|\n| **Agents** | `Agent` (tool-calling), `ReActAgent` (thought→action→observation), `PlanAndExecuteAgent` (plan→execute→replan) |\n| **DSL** | `@OrchestrationBuilder`, `--\u003e` sequential chain, `\u003e\u003e\u003e` typed pipeline, `.dependsOn()` DAG |\n| **Step types** | Sequential, Parallel, DAGWorkflow, Router, RepeatWhile, Branch, Guard, Transform, Pipeline, SequentialChain, ParallelGroup |\n| **Memory** | Conversation (rolling buffer), VectorMemory (SIMD cosine via Accelerate), SummaryMemory (LLM-compressed), HybridMemory |\n| **Hive runtime** | Compiled DAG execution, channel checkpointing, deterministic retry (jitter stripped by `RetryPolicyBridge`) |\n| **Macros** | `@Tool` → full `AnyJSONTool` conformance + JSON schema; `@AgentActor` → boilerplate-free agent actors |\n| **Guardrails** | Input, output, tool-input, tool-output validators; tripwire and warning modes |\n| **Resilience** | Configurable retry backoff, circuit breaker, fallback agents, per-step timeouts |\n| **Observability** | `SwiftLogTracer`, `OSLogTracer`, span-based tracing, per-agent token metrics |\n| **MCP** | Model Context Protocol client + HTTP server |\n| **Providers** | Foundation Models (on-device), Anthropic, OpenAI, Ollama, Gemini, MLX via [Conduit](https://github.com/christopherkarani/Conduit) |\n| **Concurrency** | All public types `Sendable`; actors for all shared state; `StrictConcurrency` on every target |\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                      Your Application                        │\n│          iOS 26+ · macOS 26+ · Linux (Ubuntu 22.04+)        │\n├─────────────────────────────────────────────────────────────┤\n│          AgentBlueprint · Runner.run() · .stream()           │\n├──────────────────────┬──────────────────────────────────────┤\n│   Orchestration DSL  │  Step Types                          │\n│   @resultBuilder     │  Sequential · Parallel · DAGWorkflow │\n│   --\u003e · \u003e\u003e\u003e          │  Router · RepeatWhile · Branch       │\n│   .dependsOn()       │  Guard · Transform · HumanApproval   │\n├──────────────────────┴──────────────────────────────────────┤\n│     Agents              Memory              Tools            │\n│  Agent (tool-call)   Conversation        @Tool macro        │\n│  ReActAgent          VectorMemory        FunctionTool       │\n│  PlanAndExecute      SummaryMemory       AnyJSONTool ABI    │\n│  HiveBackedAgent     HybridMemory        Runtime toggling   │\n├─────────────────────────────────────────────────────────────┤\n│     Guardrails · Resilience · Observability · MCP           │\n├─────────────────────────────────────────────────────────────┤\n│                    Hive Runtime (HiveCore)                   │\n│   Compiled DAG · Channel checkpointing · Tool approval      │\n│   Deterministic retry · RetryPolicyBridge (jitter-free)     │\n├─────────────────────────────────────────────────────────────┤\n│              InferenceProvider (pluggable)                   │\n│   Foundation Models · Anthropic · OpenAI · Ollama · MLX     │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## More Examples\n\n### Parallel Fan-Out\n\nRun multiple agents on the same input concurrently. Each agent's metadata is automatically namespaced as `\"agentName.key\"` — no key collisions across concurrent results.\n\n```swift\nlet group = ParallelGroup(\n    agents: [\n        (name: \"primary\", agent: primaryAgent),\n        (name: \"backup\",  agent: backupAgent),\n        (name: \"expert\",  agent: expertAgent),\n    ],\n    mergeStrategy: MergeStrategies.Concatenate(\n        separator: \"\\n\\n---\\n\\n\",\n        shouldIncludeAgentNames: true\n    ),\n    maxConcurrency: 3\n)\n\nlet result = try await group.run(\"Analyze the Swift concurrency model.\")\n```\n\n### Semantic Memory (On-Device SIMD)\n\n`VectorMemory` uses Accelerate's `vDSP_dotpr` for cosine similarity — no network call, no cloud embedding API.\n\n```swift\nlet memory = VectorMemory(\n    embeddingProvider: myEmbedder,\n    similarityThreshold: 0.75,\n    maxResults: 8\n)\n\nawait memory.add(.user(\"The project deadline is March 15.\"))\nawait memory.add(.assistant(\"Noted. I will prioritise accordingly.\"))\n\n// Semantically retrieves the deadline entry despite different phrasing\nlet context = await memory.context(for: \"When is this due?\", tokenLimit: 1_200)\n```\n\n### Supervisor Routing\n\n```swift\nlet supervisor = SupervisorAgent(\n    agents: [\n        (name: \"math\",    agent: mathAgent,    description: mathDesc),\n        (name: \"weather\", agent: weatherAgent, description: weatherDesc),\n        (name: \"code\",    agent: codeAgent,    description: codeDesc),\n    ],\n    routingStrategy: LLMRoutingStrategy(inferenceProvider: provider),\n    fallbackAgent: Agent(instructions: \"I am a general assistant.\")\n)\n\nlet result = try await supervisor.run(\"What is 15% of $240?\")\n// Routes to mathAgent\n```\n\n### Resilience\n\n```swift\nlet agent = FinanceAgent()\n    .environment(\\.inferenceProvider, provider)\n    .withRetry(.exponentialBackoff(maxAttempts: 3, baseDelay: .seconds(1)))\n    .withCircuitBreaker(threshold: 5, resetTimeout: .seconds(60))\n    .withFallback(Agent(instructions: \"Service temporarily unavailable.\"))\n    .withTimeout(.seconds(30))\n```\n\n### Streaming\n\n```swift\nfor try await event in (fetchAgent --\u003e writerAgent).stream(\"Summarise the changelog.\") {\n    switch event {\n    case .outputToken(let token):  print(token, terminator: \"\")\n    case .toolCalling(let call):   print(\"\\n[tool: \\(call.toolName)]\")\n    case .completed(let result):   print(\"\\n\\nDone in \\(result.duration)\")\n    case .failed(let error):       print(\"\\nError: \\(error)\")\n    default: break\n    }\n}\n```\n\n### Session Continuity\n\n```swift\nlet session = InMemorySession(sessionId: \"user-42\")\n\ntry await agent.run(\"My portfolio has 100 AAPL shares.\", session: session)\nlet result = try await agent.run(\"What is my total value?\", session: session)\n// Agent recalls the earlier context\n```\n\n---\n\n## Installation\n\n### Swift Package Manager\n\n```swift\n// Package.swift\ndependencies: [\n    .package(url: \"https://github.com/christopherkarani/Swarm.git\", from: \"0.3.1\")\n],\ntargets: [\n    .target(name: \"YourApp\", dependencies: [\"Swarm\"])\n]\n```\n\n### Xcode\n\n**File → Add Package Dependencies →** `https://github.com/christopherkarani/Swarm.git`\n\n---\n\n## Documentation\n\n| Topic | Description |\n|---|---|\n| [Agents](docs/agents.md) | Agent types, configuration, `@AgentActor` macro |\n| [Tools](docs/tools.md) | `@Tool` macro, `FunctionTool`, `AnyJSONTool` ABI, runtime toggling |\n| [Memory](docs/memory.md) | Conversation, Vector (SIMD), Summary, Hybrid, SwiftData backends |\n| [Sessions](docs/sessions.md) | In-memory and persistent session management |\n| [Orchestration](docs/orchestration.md) | DAG, parallel, chains, handoffs, human-in-the-loop |\n| [Streaming](docs/streaming.md) | `AgentEvent` streaming and SwiftUI integration |\n| [Observability](docs/observability.md) | Span-based tracing, `OSLogTracer`, `SwiftLogTracer`, metrics |\n| [Resilience](docs/resilience.md) | Retry, circuit breakers, fallback agents, timeouts |\n| [Guardrails](docs/guardrails.md) | Input/output validation, tripwires, audit trails |\n| [MCP](docs/mcp.md) | Model Context Protocol client and server |\n| [Providers](docs/providers.md) | Configuring inference providers |\n\n---\n\n## Requirements\n\n| | Minimum |\n|---|---|\n| Swift | 6.2 |\n| iOS | 26.0 |\n| macOS | 26.0 |\n| Linux | Ubuntu 22.04 + Swift 6.2 |\n\n\u003e iOS 26 / macOS 26 are required for Apple's on-device Foundation Models. External providers (Anthropic, OpenAI, Ollama) work on any Swift 6.2 platform including Linux.\n\n---\n\n## Contributing\n\n1. Fork and create a branch: `git checkout -b feature/my-feature`\n2. All public types must be `Sendable` — `StrictConcurrency` will reject violations at build time\n3. Write tests first: `swift test`\n4. Format: `swift package plugin --allow-writing-to-package-directory swiftformat`\n5. Open a Pull Request — describe what changed and why it matters\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for agent registry conventions and TDD workflow.\n\n---\n\n## Support\n\n- **Issues** — [GitHub Issues](https://github.com/christopherkarani/Swarm/issues)\n- **Discussions** — [GitHub Discussions](https://github.com/christopherkarani/Swarm/discussions)\n- **X** — [@ckarani7](https://x.com/ckarani7)\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n\n---\n\n*Built in Swift for Apple platforms and Linux.*\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristopherkarani%2Fswarm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristopherkarani%2Fswarm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristopherkarani%2Fswarm/lists"}