import SocraticEngine.

01Install — three lines into Package.swift

Add the dependency, then the product. SocraticEngine vends a single library product and pulls MLX, swift-huggingface, and swift-transformers transitively.

// 1. add the package
.package(url: "https://github.com/Two-Weeks-Team/he-was-socrates", from: "1.0.0"),

// 2. depend on the product from your target
.product(name: "SocraticEngine", package: "he-was-socrates"),

// 3. that's it. no network entitlement required by the package itself.

02Quick start — a 10-line consumer

Instantiate EngineCoordinator as @MainActor, observe Phase, push audio in, get TurnOutput out. No UI required — this snippet is enough to run a full turn.

import SocraticEngine

@MainActor
func runOneTurn() async throws {
    let engine = EngineCoordinator(mode: .real)   // or .stub for tests
    try await engine.bootstrap()                  // loads Gemma 4 E4B 4-bit weights
    for await phase in engine.phaseStream {     // bootstrapping → idle → … → speaking
        print("phase:", phase)
    }
    try await engine.beginListening()             // push-to-talk start
    let turn: TurnOutput = try await engine.endListening()
    print(turn.koreanResponse, turn.mode)        // 평어체 text + Mode enum
}

03API surface — public types you compose against

Stable surface per runs/2026-05-05-spec/spec/SPEC.md. Shape changes only via delta documents at the same path.

04Example consumers — three host apps, one engine

The same Swift Package powers all three. The only thing that changes across consumers is presentation; the turn loop, abstention rules, and Korean tone travel with the package.

import SocraticEngine
import SwiftUI

@main struct App: App {
  @State var e = EngineCoordinator(.real)
  var body: some Scene {
    WindowGroup { ContentView(engine: e) }
  }
}

import SocraticEngine

@main struct Repl {
  static func main() async throws {
    let e = EngineCoordinator(.real)
    try await e.bootstrap()
    while let line = readLine() {
      let t = try await e.runText(line)
      print(t.koreanResponse)
    }
  }
}

// Planned: same EngineCoordinator,
// RealityKit halftone material instead
// of NSImageView swap.

import SocraticEngine
import RealityKit

// platform floor blocks shipping today;
// API surface is already compatible.

05What every embedder inherits — automatically

These are properties of the package, not of the example app. Any host that depends on SocraticEngine gets them for free.

06Locked Korean prompt — non-localizable on purpose

SystemPrompt.swift is embedded at compile time. Embedders inherit the tone whether they want it or not — this is the contract, not a default.