Repository Public
1// SP Wallet Core2// File: Sources/SPWalletCore/Domains/Ops/ResearchAPI.swift3// Description: The OWNER's side of the research runtime (services/api/src/research/routes.ts): create a job, list, detail with4// its labelled results, cancel, read its log, runner status. The runner routes (/research/runner/*) accept the5// runner's shared secret only and are deliberately absent: they are not for clients.6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import Foundation1011public struct ResearchAPI: Sendable {12 let client: APIClient13 public init(_ client: APIClient) { self.client = client }1415 /** Is a runner configured, did one show up, how many jobs are open (at most `maxOpenJobs`). */16 public func status() async throws -> ResearchStatus { try await client.get("/research/status") }1718 /**19 Create a job. NOT idempotent on the server (no Idempotency-Key on this route): after a lost answer, read `jobs()` before20 sending again. Costs model tokens within the budgets given.21 */22 public func create(_ r: ResearchJobRequest) async throws -> ResearchJob { try await client.post("/research/jobs", body: r) }2324 /** Newest first; `limit` 1…200 (server default 50). */25 public func jobs(agentId: String? = nil, limit: Int? = nil) async throws -> [ResearchJob] {26 struct Answer: Decodable, Sendable { let jobs: [ResearchJob] }27 return try await client.get("/research/jobs", query: ["agentId": agentId, "limit": limit.map { String(min(max($0, 1), 200)) }], as: Answer.self).jobs28 }2930 /** The job with its submission (the agent's statements), the server's measurements and the laboratory report — see `ResearchJobDetail.results`. */31 public func job(_ id: String) async throws -> ResearchJobDetail { try await client.get("/research/jobs/\(APIClient.segment(id))") }3233 /**34 Ask to cancel. A queued job is cancelled at once; a running one is killed by the runner at its next report — the answer35 then still says `running` with `cancelRequested == true`. The state shown is the one the server returns, never an assumed one.36 */37 public func cancel(_ id: String) async throws -> ResearchJob { try await client.post("/research/jobs/\(APIClient.segment(id))/cancel") }3839 /** Log lines with an id above `after` (oldest first; `limit` 1…1000, server default 500), and the job's state. */40 public func log(_ id: String, after: Int64 = 0, limit: Int? = nil) async throws -> ResearchLog {41 try await client.get("/research/jobs/\(APIClient.segment(id))/log", query: ["after": String(max(after, 0)), "limit": limit.map { String(min(max($0, 1), 1000)) }])42 }4344 /**45 The request of the job-log SSE stream (at most 6 at once; ends with the job or after ten minutes — reconnect with the46 parser's `lastEventId`). To be run with a streaming loader and parsed with `ServerSentEventParser` → `ResearchLogStreamEvent`.47 */48 public func logStreamRequest(_ id: String, after: Int64 = 0, lastEventId: String? = nil) async -> URLRequest? {49 await client.eventStreamRequest("/research/jobs/\(APIClient.segment(id))/log/stream", query: ["after": String(max(after, 0))], lastEventId: lastEventId)50 }51}52