Repository Public
1// SP Wallet Core2// File: Sources/SPWalletCore/Domains/Ops/ResearchModels.swift3// Description: Models of the owner's research jobs (services/api/src/research/routes.ts, store.ts, evaluate.ts;4// packages/core/src/research-job.ts). A job asks an AI coding agent on another machine to develop a strategy;5// everything that comes back is UNTRUSTED until the server has re-computed it.6//7// NATURE OF EVERY RESULT. The server does not send a `nature` field: it labels by STRUCTURE — each part of a8// job's answer is a separate object with one author. This file keeps those objects apart and attaches the label9// the server's own code comments give them (`ResearchProvenance`):10// submission « written by the AI agent: statements, not measurements » → generated analysis, by the agent11// server « measured by this server on its own data » — a BACKTEST → simulation, by the server12// .deflatedSharpe / .sharpeCi statistics over trials / bootstrap resamples → estimate, by the server13// .comparison the agent's claimed number next to the server's measured one → both, never merged14// report the laboratory's full backtest report on the frozen data set → simulation, by the server15// holdout how the recorded candles were split (dates, bar counts) → observed data, by the server16// usage « what the runner measured from outside the agent » → observed data, by the runner17// No function here merges two natures into one figure, and no result is a live or real-money figure:18// `capitalUsd` is the VIRTUAL capital of the simulation.19//20// Author: Simon-Pierre Boucher21// Contact: contact@spboucher.ai22import Foundation2324/** What kind of thing a research figure is. Shown with it, always. */25public enum ResearchNature: String, Sendable, Codable, CaseIterable {26 /** Recorded facts: market candles and how they were split, resources consumed. */27 case observedData28 /** A statistic with uncertainty (deflated Sharpe ratio, bootstrap confidence interval). */29 case estimate30 /** The outcome of a backtest: what a strategy WOULD have done on recorded data. Not a result of trading. */31 case simulation32 /** Text and numbers written by the AI agent: statements, not measurements. */33 case generatedAnalysis34}3536public enum ResearchAuthor: String, Sendable, Codable, CaseIterable {37 /** The AI coding agent of the job: unverified. */38 case agent39 /** This wallet's API, on data the job never had. */40 case server41 /** The job runner, measuring the agent from outside. Stored by the API, trusted for no money decision. */42 case runner43}4445public struct ResearchProvenance: Sendable, Hashable, Codable {46 public let nature: ResearchNature47 public let author: ResearchAuthor48 /** True only for what the server itself computed. */49 public var isServerVerified: Bool { author == .server }50}5152public enum ResearchState: Sendable, Hashable, Codable {53 case queued, preparing, running, evaluating, submitted, failed, cancelled, overBudget54 case unknown(String)5556 private static let known: [(String, ResearchState)] = [("queued", .queued), ("preparing", .preparing), ("running", .running), ("evaluating", .evaluating),57 ("submitted", .submitted), ("failed", .failed), ("cancelled", .cancelled), ("over_budget", .overBudget)]58 public var rawValue: String { if case .unknown(let s) = self { return s }; return Self.known.first { $0.1 == self }!.0 }59 public init(rawValue: String) { self = Self.known.first { $0.0 == rawValue }?.1 ?? .unknown(rawValue) }60 public init(from decoder: Decoder) throws { self.init(rawValue: try decoder.singleValueContainer().decode(String.self)) }61 public func encode(to encoder: Encoder) throws { var c = encoder.singleValueContainer(); try c.encode(rawValue) }6263 /** Nothing moves the job again. `submitted` means "a strategy awaits the owner's approval", not "approved" and not "profitable". */64 public var isFinal: Bool { [.submitted, .failed, .cancelled, .overBudget].contains(self) }65 /** The server accepts a cancel in these states only (`evaluating` and the final states answer `bad_state`). */66 public var isCancellable: Bool { [.queued, .preparing, .running].contains(self) }67}6869/** Set by the owner per job, enforced by the runner from outside the agent process. */70public struct ResearchBudgets: Codable, Sendable, Hashable {71 public let wallSeconds: Int72 public let maxTrials: Int73 public let maxDiskMb: Int74 public let maxModelTokens: Int75 public let maxModelUsd: Double76}7778/** What the runner measured from outside the agent. Observed data, by the runner. */79public struct ResearchUsage: Codable, Sendable, Hashable {80 public static let provenance = ResearchProvenance(nature: .observedData, author: .runner)81 public let wallMs: Int82 public let trials: Int83 public let diskMb: Double84 public let modelTokens: Int85 public let modelRequests: Int?86 /** nil when the agent's CLI reported no cost. */87 public let modelUsd: Double?88 /** The agent's own ledger file was truncated or rewritten while the runner was copying it. */89 public let ledgerTampered: Bool90 /** `sandbox-exec` when the agent ran confined; `none` when the platform offered nothing (to be said on screen). */91 public let sandbox: String92 public let agent: String?93 public let labCommit: String?94 public let exitCode: Int?95 public let signal: String?96}9798/** A job as the list and every state change answer it (`view` in research/routes.ts). */99public struct ResearchJob: Codable, Sendable, Hashable, Identifiable {100 public let id: String101 public let agentId: String?102 /** `spot` or `perp`. */103 public let kind: String104 public let mission: String105 public let universe: [String]106 public let interval: String107 /** VIRTUAL starting capital of the simulation. Not funds. */108 public let capitalUsd: Double109 public let budgets: ResearchBudgets110 public let tools: [String]111 public let state: ResearchState112 public let reason: String?113 /** `<name>/<version>` of the job-scoped strategy. */114 public let strategy: String115 public let labCommit: String?116 public let runnerId: String?117 public let claimedAt: Date?118 public let heartbeatAt: Date?119 public let cancelRequested: Bool120 public let usage: ResearchUsage?121 public let versionId: String?122 public let createdAt: Date123 public let updatedAt: Date?124 public let finishedAt: Date?125126 // list only127 /** `ok` or `failed`: the outcome of the SERVER's evaluation; nil before it. */128 public let serverStatus: String?129 public let trialsTotal: Int?130 /** Estimate, by the server. */131 public let deflatedSharpe: Double?132 /** The agent's reported numbers differ from the server's. */133 public let claimsDiffer: Bool?134 // create only135 public let runnerConfigured: Bool?136}137138/** How the frozen data set was split: the agent saw bars before `devEnd` only; the server tests on [devEnd, end). Observed data, by the server. */139public struct ResearchHoldout: Codable, Sendable, Hashable {140 public static let provenance = ResearchProvenance(nature: .observedData, author: .server)141 public let start: String142 public let devEnd: String143 public let end: String144 public let devBars: Int145 public let testBars: Int146}147148/** total_return, sharpe, max_drawdown, trades of one data split; nil where the laboratory gave no number. */149public struct ResearchSplitMetrics: Codable, Sendable, Hashable {150 public let totalReturn: Double?151 public let sharpe: Double?152 public let maxDrawdown: Double?153 public let trades: Double?154 enum CodingKeys: String, CodingKey { case totalReturn = "total_return", sharpe, maxDrawdown = "max_drawdown", trades }155}156157/** What the AI agent claims (claims.json). Generated analysis, by the agent: shown NEXT TO what the server measured, never instead of it. */158public struct ResearchAgentClaims: Codable, Sendable, Hashable {159 public let train: ResearchSplitMetrics?160 public let validation: ResearchSplitMetrics?161 /** The agent's own inner test split — NOT the server's test split, which it never saw. */162 public let innerTest: ResearchSplitMetrics?163 public let trials: Int?164 public let summary: String?165 enum CodingKeys: String, CodingKey { case train, validation, innerTest = "inner_test", trials, summary }166}167168/** What the agent handed in. Generated analysis, by the agent — statements, not measurements. */169public struct ResearchSubmission: Codable, Sendable, Hashable {170 public static let provenance = ResearchProvenance(nature: .generatedAnalysis, author: .agent)171 /** SHA-256 of strategy.py as the server checked and installed it. */172 public let sha256: String173 public let path: String?174 /** `strategy.py`, `README.md`, optional `NOTES.md`: the agent's own text. */175 public let files: [String: String]176 public let claims: ResearchAgentClaims?177 /** Why claims.json was ignored, when it was. */178 public let claimsProblem: String?179 public let bytes: [String: Int]?180}181182/** One claimed metric next to the server's re-computation on the same data. Two numbers of two natures: kept as two fields. */183public struct ResearchClaimComparison: Codable, Sendable, Hashable {184 /** `train`, `validation`, `inner_test`. */185 public let split: String186 /** `total_return`, `sharpe`, `max_drawdown`, `trades`. */187 public let metric: String188 /** Generated analysis, by the agent. */189 public let claimed: Double?190 /** Simulation, by the server. */191 public let measured: Double?192 public let differs: Bool193}194195/** What THIS SERVER measured (`ServerSummary` of research/evaluate.ts): backtests it ran itself. Simulation, by the server. */196public struct ResearchServerReport: Codable, Sendable, Hashable {197 public static let provenance = ResearchProvenance(nature: .simulation, author: .server)198 /** `deflatedSharpe` and `sharpeCi` are statistics over the trials and over bootstrap resamples. */199 public static let estimateProvenance = ResearchProvenance(nature: .estimate, author: .server)200201 public struct Holdout: Codable, Sendable, Hashable { public let testStart: String; public let testEnd: String; public let bars: Int }202 public struct Trials: Codable, Sendable, Hashable {203 /** Trials the job consumed (the runner's append-only ledger). */204 public let job: Int205 public let server: Int206 public let total: Int207 public let ledgerTampered: Bool208 }209 public struct Metrics: Codable, Sendable, Hashable {210 public let train: ResearchSplitMetrics?211 public let validation: ResearchSplitMetrics?212 /** The out-of-sample split the job never had. */213 public let test: ResearchSplitMetrics?214 }215 public struct Replication: Codable, Sendable, Hashable {216 public let train: ResearchSplitMetrics?217 public let validation: ResearchSplitMetrics?218 public let innerTest: ResearchSplitMetrics?219 enum CodingKeys: String, CodingKey { case train, validation, innerTest = "inner_test" }220 }221 /** `ok` or `failed`. Kept as text. Without `ok` there is no server report: the strategy cannot be approved. */222 public let status: String223 public let reason: String?224 public let sha256: String?225 /** `sandbox-exec` or `none`. */226 public let sandbox: String?227 public let meta: JSONValue?228 public let holdout: Holdout?229 public let trials: Trials?230 /** Estimate. */231 public let deflatedSharpe: Double?232 /** Estimate: bootstrap confidence interval [low, high] of the Sharpe ratio; either bound may be missing. */233 public let sharpeCi: [Double?]?234 public let metrics: Metrics?235 /** Buy-and-hold (spot) or 1× long (perp) over the same test split. */236 public let benchmark: ResearchSplitMetrics?237 public let checks: [String: JSONValue]?238 /** The standard evaluation re-run by the server on the data the agent had. */239 public let replication: Replication?240 public let comparison: [ResearchClaimComparison]?241 public let claimsDiffer: Bool?242 public let claimsProblem: String?243244 public var isOK: Bool { status == "ok" }245}246247/** The laboratory's full backtest report as the server stored it (splits, config, metrics, benchmarks, robustness, checks, equity curve). Simulation, by the server. */248public struct ResearchLabReport: Codable, Sendable, Hashable {249 public static let provenance = ResearchProvenance(nature: .simulation, author: .server)250 public let splits: JSONValue?251 public let config: JSONValue?252 public let metrics: JSONValue?253 public let benchmarks: JSONValue?254 public let robustness: JSONValue?255 public let checks: JSONValue?256 /** SIMULATED equity of the backtest. Never drawn as an account's history. */257 public let equityCurve: JSONValue?258 public let researchJob: JSONValue?259 enum CodingKeys: String, CodingKey { case splits, config, metrics, benchmarks, robustness, checks, equityCurve = "equity_curve", researchJob = "research_job" }260}261262/** One labelled part of a job's result, for a screen that lists them. */263public enum ResearchResult: Sendable, Hashable {264 case holdout(ResearchHoldout)265 case usage(ResearchUsage)266 case submission(ResearchSubmission)267 case serverReport(ResearchServerReport)268 case labReport(ResearchLabReport)269270 public var provenance: ResearchProvenance {271 switch self {272 case .holdout: ResearchHoldout.provenance273 case .usage: ResearchUsage.provenance274 case .submission: ResearchSubmission.provenance275 case .serverReport: ResearchServerReport.provenance276 case .labReport: ResearchLabReport.provenance277 }278 }279}280281/** GET /research/jobs/:id — the job, and for a submission the agent's statements next to the server's measurements. */282public struct ResearchJobDetail: Codable, Sendable, Hashable, Identifiable {283 public struct Agent: Codable, Sendable, Hashable { public let id: String; public let name: String; public let state: String; public let kind: String? }284 /** The strategy version left as a DRAFT for the owner; approving it is another module's passkey flow. */285 public struct Version: Codable, Sendable, Hashable { public let id: String; public let status: String; public let notes: String?; public let approvedAt: Date?286 enum CodingKeys: String, CodingKey { case id, status, notes, approvedAt = "approved_at" } }287288 public let job: ResearchJob289 public let holdout: ResearchHoldout?290 /** nil while the data set is being frozen. */291 public let dataReady: Bool?292 public let dataError: String?293 public let agent: Agent?294 public let version: Version?295 public let submission: ResearchSubmission?296 public let server: ResearchServerReport?297 public let report: ResearchLabReport?298299 public var id: String { job.id }300301 enum CodingKeys: String, CodingKey { case holdout, dataReady, dataError, agent, version, submission, server, report }302 public init(from decoder: Decoder) throws {303 job = try ResearchJob(from: decoder) // the job's fields are served flat, next to the result objects304 let c = try decoder.container(keyedBy: CodingKeys.self)305 holdout = try c.decodeIfPresent(ResearchHoldout.self, forKey: .holdout)306 dataReady = try c.decodeIfPresent(Bool.self, forKey: .dataReady)307 dataError = try c.decodeIfPresent(String.self, forKey: .dataError)308 agent = try c.decodeIfPresent(Agent.self, forKey: .agent)309 version = try c.decodeIfPresent(Version.self, forKey: .version)310 submission = try c.decodeIfPresent(ResearchSubmission.self, forKey: .submission)311 server = try c.decodeIfPresent(ResearchServerReport.self, forKey: .server)312 report = try c.decodeIfPresent(ResearchLabReport.self, forKey: .report)313 }314 public func encode(to encoder: Encoder) throws {315 try job.encode(to: encoder)316 var c = encoder.container(keyedBy: CodingKeys.self)317 try c.encodeIfPresent(holdout, forKey: .holdout); try c.encodeIfPresent(dataReady, forKey: .dataReady); try c.encodeIfPresent(dataError, forKey: .dataError)318 try c.encodeIfPresent(agent, forKey: .agent); try c.encodeIfPresent(version, forKey: .version); try c.encodeIfPresent(submission, forKey: .submission)319 try c.encodeIfPresent(server, forKey: .server); try c.encodeIfPresent(report, forKey: .report)320 }321322 /** Every part of the result that exists, each with its nature and author. In the order a screen tells the story. */323 public var results: [ResearchResult] {324 var out: [ResearchResult] = []325 if let holdout { out.append(.holdout(holdout)) }326 if let u = job.usage { out.append(.usage(u)) }327 if let submission { out.append(.submission(submission)) }328 if let server { out.append(.serverReport(server)) }329 if let report { out.append(.labReport(report)) }330 return out331 }332}333334public struct ResearchStatus: Codable, Sendable, Hashable {335 /** False: no runner secret on the server — jobs stay queued. */336 public let runnerConfigured: Bool337 public let lastRunnerContact: Date?338 public let openJobs: Int339 public let maxOpenJobs: Int340 public let labCommit: String?341}342343/** POST /research/jobs. Fields left nil take the SERVER's defaults (this file duplicates none of them). */344public struct ResearchJobRequest: Encodable, Sendable, Equatable {345 public struct Budgets: Encodable, Sendable, Equatable {346 /** 30…86 400 */ public var wallSeconds: Int?347 /** 1…5 000 */ public var maxTrials: Int?348 /** 16…10 240 */ public var maxDiskMb: Int?349 /** 10 000…500 000 000 */ public var maxModelTokens: Int?350 /** 0.05…1 000 */ public var maxModelUsd: Double?351 public init(wallSeconds: Int? = nil, maxTrials: Int? = nil, maxDiskMb: Int? = nil, maxModelTokens: Int? = nil, maxModelUsd: Double? = nil) {352 self.wallSeconds = wallSeconds; self.maxTrials = maxTrials; self.maxDiskMb = maxDiskMb; self.maxModelTokens = maxModelTokens; self.maxModelUsd = maxModelUsd353 }354 }355 /** The agent the strategy is developed for (its kind, symbols and interval then replace the ones below); without it the result is a library draft. */356 public var agentId: String?357 /** `spot` or `perp`. */358 public var kind: String?359 /** The owner's own words, 10…2 000 characters. */360 public var mission: String361 /** 1…12 distinct symbols, each 2…10 characters of [A-Z0-9]. */362 public var universe: [String]363 /** `1h`, `4h`, `1d`. */364 public var interval: String?365 /** Virtual capital of the simulation, 10…10 000 000. */366 public var capitalUsd: Double?367 public var budgets: Budgets?368 /** Among `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash` (there is deliberately no web tool). */369 public var tools: [String]?370371 public init(mission: String, universe: [String], agentId: String? = nil, kind: String? = nil, interval: String? = nil, capitalUsd: Double? = nil, budgets: Budgets? = nil, tools: [String]? = nil) {372 self.mission = mission; self.universe = universe; self.agentId = agentId; self.kind = kind; self.interval = interval; self.capitalUsd = capitalUsd; self.budgets = budgets; self.tools = tools373 }374}375376public struct ResearchLogLine: Codable, Sendable, Hashable, Identifiable {377 public let id: Int64378 public let ts: Date379 /** `out` / `err` (the agent's process: untrusted text), `sys` (the runner), `api` (this server). */380 public let stream: String381 public let text: String382 enum CodingKeys: String, CodingKey { case id, ts, stream = "s", text = "t" }383 /** Only `api` lines are the server's own words. */384 public var isServerLine: Bool { stream == "api" }385}386387public struct ResearchLog: Codable, Sendable, Hashable {388 public let state: ResearchState389 public let lines: [ResearchLogLine]390 /** The `after` of the next read. */391 public var lastId: Int64? { lines.last?.id }392}393394/** One event of the job-log SSE stream (GET /research/jobs/:id/log/stream). */395public enum ResearchLogStreamEvent: Sendable, Equatable {396 case log(ResearchLogLine)397 case state(ResearchState, reason: String?)398 /** The job is final (or gone): the stream ends. */399 case end400401 public init?(_ e: ServerSentEvent) {402 let d = Data(e.data.utf8)403 switch e.event {404 case "log":405 guard let l = try? APICoding.decoder().decode(ResearchLogLine.self, from: d) else { return nil }406 self = .log(l)407 case "state":408 struct S: Decodable { let state: ResearchState; let reason: String? }409 guard let s = try? APICoding.decoder().decode(S.self, from: d) else { return nil }410 self = .state(s.state, reason: s.reason)411 case "end": self = .end412 default: return nil413 }414 }415}416