SPB Git

Repository Public

ResearchModels.swift 20.7 KB 416 lines swift

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
Files main
Menu

Theme