Skip to content
This repository was archived by the owner on Aug 6, 2026. It is now read-only.
angelsbroodPublic archive

About

A Swift-native runtime for directing agentic ensembles. The SDK as it shipped in the Circuit v1 demo, archived.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

cascade-sdk

A Swift-native runtime for directing agentic ensembles.

Status

Archived January 2026. This is the SDK exactly as it shipped in the Circuit v1 demo — unmodified, with its history intact. It is not maintained.

Circuit v1 references this package locally, at ../cascade-sdk, so the two repositories must be cloned side by side:

parent/
├── Circuit/
└── cascade-sdk/

Development of the runtime continued inside Circuitv2, which absorbed this package into a monorepo on 2026-01-21 and evolved it there through March 2026. This repository is the last standalone point.

Overview

cascade-sdk provides infrastructure for multi-agent coordination where humans stay meaningfully in the loop. Rather than top-down orchestration, cascades flow through agent systems, surfacing decision moments through escalation.

Key concepts:

  • Cascade — The process you direct. Work flows through the system, agents execute in parallel, and when the system encounters ambiguity, it escalates to you.
  • Orchestrator — The AI actor that operates cascades. It decomposes prompts into work units, delegates to agents, integrates results, and knows when to escalate.
  • Director — You. The human who initiates cascades and shapes their trajectory through escalation responses.

This is distinct from cybernetic orchestration (Kubernetes, Airflow). Cascades are humanist—the human isn't a supervisor monitoring dashboards, but a director shaping a live process.

Features

  • Pluggable inference providers — Claude, OpenAI-compatible (Groq, Together, Ollama), CoreML, Apple Foundation Models
  • Complete tool suite — File operations (read, write, edit, glob, search), schema output
  • Parallel delegation — Work units execute concurrently across multiple agents
  • Integration with conflict resolution — Merge results, detect conflicts, generate diffs
  • Escalation system — Surface ambiguities, open questions, and drift to the director
  • Coherence validation — Ensure the assembled whole makes sense

Installation

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/angelsbrood/cascade-sdk", from: "1.0.0")
]

Then import:

import CascadeSDK

Quick Start

Single-agent mode (CircuitAgent)

For simple tasks without orchestration:

let provider = ClaudeProvider(apiKey: "sk-...")
let agent = CircuitAgent(
    provider: provider,
    projectRoot: projectURL,
    configuration: .init(maxIterations: 12)
)

let schema = try await agent.run(prompt: "Analyze this project")

Cascade mode (Orchestrator)

For complex tasks with decomposition, parallel execution, and escalation:

// Create orchestration provider (cloud or local)
let orchestrationProvider = CloudOrchestrationAdapter(
    provider: ClaudeProvider(apiKey: "sk-...")
)

// Create orchestrator with initial schema
let orchestrator = Orchestrator(
    orchestrationProvider: orchestrationProvider,
    localProvider: foundationModelsProvider,
    cloudProviders: ["claude": claudeProvider],
    initialSchema: schema,
    projectRoot: projectURL
)

// Set delegates for progress and escalation
await orchestrator.setDelegate(myDelegate)
await orchestrator.setEscalationDelegate(myEscalationDelegate)

// Process — this triggers the cascade
let result = try await orchestrator.process(prompt: "Add user authentication")

// Result contains successful units, failed units, and the updated schema

Handling escalations

The orchestrator surfaces decision moments through the escalation delegate:

class MyEscalationHandler: EscalationDelegate {
    func orchestrator(_ orchestrator: Orchestrator, needsAnswers questions: [OpenQuestion]) async {
        // Display questions to user, collect answers
        for question in questions {
            let answer = await presentQuestionToUser(question)
            try await orchestrator.answer(question.id, with: answer)
        }
    }

    func orchestrator(_ orchestrator: Orchestrator, needsResolution conflict: IntegrationConflict) async {
        // Present conflict, get user decision
        let resolution = await presentConflictToUser(conflict)
        try await orchestrator.resolveConflict(conflict.id, resolution: resolution)
    }
}

Architecture

Director (Human)
    │
    │ initiates, responds to escalations
    ▼
Cascade (the process)
    │
    │ operated by
    ▼
Orchestrator ─────────────────────────────┐
    │                                     │
    │ decomposes, delegates, integrates   │ escalates
    ▼                                     ▼
┌─────────┬─────────┬─────────┐    ┌─────────────┐
│ Agent A │ Agent B │ Agent C │    │  Director   │
│ (Claude)│ (Groq)  │ (Local) │    │  (Human)    │
└────┬────┴────┬────┴────┬────┘    └─────────────┘
     │         │         │
     ▼         ▼         ▼
  Results integrated into schema + codebase

Inference Providers

Provider Use Case
ClaudeProvider Anthropic Claude API
OpenAICompatibleProvider OpenAI, Groq, Together, Ollama, LM Studio
CoreMLProvider On-device models (Qwen Coder)
FoundationModelsProvider Apple Intelligence (macOS 26+)
MockProvider Unit testing
RecordingProvider Transcript capture

See also

License

MIT

About

A Swift-native runtime for directing agentic ensembles. The SDK as it shipped in the Circuit v1 demo, archived.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages