Integrating VQuantKit into VQuant macOS and VQuant iOS (2.0 "VQuant Next")
Add the package as a local dependency (../VQuantKit) and link VQuantKit + VQuantUI to the app target
(VQuantKitTesting to the test targets only). The package does not depend on either app's VQuantCore.
Send X-VQ-Client: vquant-macos/2.0.0 / vquant-ios/2.0.0 (<build>): a 1.x header receives only the six legacy
tools and sees cancelled jobs as interrupted.
The adapters below were written from the apps' current sources but not compiled against them (the app repositories were not modified).
1. Adapt the app's APIClient to VQTransport
The transport returns the response whatever its status (the kit reads 409 bodies, Retry-After, x-vq-locked).
VQRequest.path is already percent-encoded per segment; query values are raw; body is JSON bytes.
macOS (Core/Networking/APIClient.swift, HTTPTransport)
APIClient.request(_:_:query:body:authenticated:accept:) is public and builds the authenticated URLRequest; the
HTTPTransport the client was built with does the I/O.
import VQuantKit
import VQuantCore
struct MacVQTransport: VQTransport {
let client: APIClient // builds the request: base URL, Bearer token, X-VQ-Client, no Origin
let http: HTTPTransport // the same instance the APIClient was created with
private func urlRequest(_ r: VQRequest) throws -> URLRequest {
var req = try client.request(HTTPMethod(rawValue: r.method.rawValue)!, r.path,
query: Dictionary(r.query.map { ($0.name, Optional($0.value)) }, uniquingKeysWith: { $1 }),
accept: r.accept)
req.httpBody = r.body // the kit's bytes, as they are
if r.body != nil { req.setValue(r.contentType ?? "application/json", forHTTPHeaderField: "Content-Type") } // multipart for the dataset upload
req.timeoutInterval = r.timeout
return req
}
func send(_ r: VQRequest) async throws -> VQResponse {
let (data, response) = try await http.data(for: try urlRequest(r))
return VQResponse(data: data, http: response)
}
func stream(_ r: VQRequest) async throws -> VQByteStream {
let (lines, response) = try await http.lines(for: try urlRequest(r))
// the app's reader yields lines: give each one back its line end
let chunks = AsyncThrowingStream<Data, Error> { c in
let task = Task { do { for try await l in lines { c.yield(Data((l + "\n").utf8)) }; c.finish() } catch { c.finish(throwing: error) } }
c.onTermination = { _ in task.cancel() }
}
return VQByteStream(http: response, chunks: chunks)
}
}The kit's SSE parser dispatches at each data: line, so the blank lines URLSession.AsyncBytes.lines drops are not
needed. Session death: the kit reports VQError.isLocked and the engine's status becomes .locked; call the same
sign-out path the app's onUnauthorized handler uses (or check x-vq-locked in the adapter and call it there).
iOS (Core/Networking/APIClient.swift)
APIClient.urlRequest(_:) percent-encodes the path itself (% is not in its allowed set), so hand it the decoded path.
struct IOSVQTransport: VQTransport {
let client: APIClient
private func urlRequest(_ r: VQRequest) throws -> URLRequest {
var a = APIRequest(method: r.method.rawValue, path: r.path.removingPercentEncoding ?? r.path,
query: Dictionary(r.query.map { ($0.name, $0.value) }, uniquingKeysWith: { $1 }),
body: r.body, timeout: r.timeout)
a.accept = r.accept ?? "application/json"
if let type = r.contentType { a.contentType = type } // multipart for the dataset upload
return try client.urlRequest(a)
}
func send(_ r: VQRequest) async throws -> VQResponse {
let (data, response) = try await client.session.data(for: try urlRequest(r))
guard let http = response as? HTTPURLResponse else { throw URLError(.badServerResponse) }
if http.statusCode == 401 { try? client.check(response, data: data, hadToken: true) } // runs the app's sign-out handler
return VQResponse(data: data, http: http)
}
func stream(_ r: VQRequest) async throws -> VQByteStream {
var req = try urlRequest(r); req.timeoutInterval = 90
let (bytes, response) = try await client.session.bytes(for: req)
guard let http = response as? HTTPURLResponse else { throw URLError(.badServerResponse) }
let chunks = AsyncThrowingStream<Data, Error> { c in
let task = Task {
do { var line = Data(); for try await b in bytes { line.append(b); if b == 0x0A { c.yield(line); line.removeAll(keepingCapacity: true) } }; c.finish() }
catch { c.finish(throwing: error) }
}
c.onTermination = { _ in task.cancel() }
}
return VQByteStream(http: http, chunks: chunks)
}
}Check before shipping: symbols with ^ (/api/v2/data/bars/%5EGSPC) round-trip through each app's encoder — the
kit's own VQURLSessionTransport is tested for it, the adapters are not. Simplest alternative on either platform:
VQURLSessionTransport(baseURL:clientHeader:token:onLocked:) with the Keychain reader as token.
2. One entry point
let vq = VQuantAPI(transport: MacVQTransport(client: api, http: transport))
try await vq.data.marketOverview() // VQMarketOverview
try await vq.models.catalog() // VQModelCatalog
try await vq.lab.catalog() // 19 tools with a 2.x header
try await vq.research.bundle(project: id)Errors are VQError (kind, status, the server's message, retryAfter, isLocked, parsed body).
Models are read tolerantly: cache the raw Data in the app's DiskCache and decode with T.decode(data).
3. Wire the sync engine
let storage = try VQFileSyncStorage(directory: appSupport.appendingPathComponent("sync/\(personId)"),
cipher: AppCipher()) // VQSyncCipher: the sealing the DiskCache already uses
let engine = VQSyncEngine(client: vq.client, storage: storage)
await engine.start() // after sign-in; `await engine.stop()` when leaving, `reset()` at sign-out- One engine per signed-in person; the directory must be per person. iOS: an app-group container if widgets read it.
start()loads the replica, opens/api/v2/sync/stream, pulls onhelloand on eachchange, replays the queue, reconnects with back-off (1, 2, 4 … 60 s;Retry-Afterhonoured). iOS suspends the stream in the background: calltry await engine.syncNow()when the scene becomes active.- Reads and writes from SwiftUI:
@State private var watchlists = VQSyncedCollection<VQWatchlist>(engine: engine)
@State private var sync = VQSyncStatusStore(engine: engine)
List(watchlists.items) { w in Text(w.data.name) } // pending local writes included; watchlists.pendingIDs marks them
.task { await watchlists.observe() }
.task { await sync.observe() } // sync.status.connection / pendingWrites, sync.conflicts
await watchlists.update(id) { $0.add("NVDA") } // durable in the queue before it returns; shown at once- Typed kinds:
VQWatchlist,VQPortfolio(idmainis the agent's portfolio — never create it blindly: the engine merges with the bridged one on 409),VQWorkspace(layout: VQLayoutNode,addPanel/removePanel),VQChart,VQProject,VQNote,VQPreference(iddefault),VQReview(server-written;putthrows.forbidden). Edit the typed properties and save the whole value: unknown keys travel with it. - Conflicts:
sync.conflictslistsVQConflictRecords. Show those withneedsAttention(both versions are inlocal/remote); "keep theirs" =sync.keepRemote(id), otherwisesync.dismiss(id). - Hints:
for await hint in await engine.hints()→ refresh conversations (sessions), running analyses (generations), the job list (quant_jobs). This replaces polling those lists. - Sync status dot:
.connectedandpendingWrites == 0→ synced;.reconnecting→ offline, writes are queued;.locked→ sign in again (the queue is kept). - Migrating 1.x local data (iOS watchlists in
LocalStores): create objects once withengine.put, then drop the local store. The legacy portfolio is already bridged server-side toportfolio/main.
4. Generations (additive to what the apps already decode)
Keep the existing stream handling; pass each event's JSON to VQGenerationEvent(json:) as well:
.modelRouted (show model + reason when auto was asked), .budget, .quantJob (open the job with
vq.lab.job(id)), .provenance, .done(sessionId:usage:); everything else is .other and stays yours.
Stored conversations: VQMessageExtras.ofSession(json) gives provenance, model, generationId, usage per
message (the route returns messages as an array or as a JSON string: both are read).
Trace sheet: vq.models.trace(sessionId:).
5. Quant Lab
let catalog = try await vq.lab.catalog()
var form = VQLabForm(tool: catalog.tool("risk_lab")!) // defaults filled in
form["symbols"] = "AAPL, MSFT, TLT" // text as typed, or structured values
switch form.validate() { // the server's rules and wording, all issues at once
case .failure(let invalid): show(invalid.issues) // [name, message]
case .success(let params):
let job = try await vq.lab.start(tool: form.tool.id, params: params, projectId: projectId)
for try await state in vq.lab.follow(job.id) { progress = state.progress } // ends at the first finished state
}
try await vq.lab.cancel(job.id) // .cancelled / .notCancellable (legacy) / .notRunningBuild the form UI from tool.groups and param.type (symbol, symbols, int, number, numbers, choice, bool, date, text, json; help, min/max, minDate/maxDate, choices, maxLength, multiline, schemaHint). A type this
version does not know is shown as a text field. job.labResult is non-nil for lab/1 results; for the six legacy
tools keep the existing renderer on job.result.
6. LabResultView and the design system
import VQuantUI
ScrollView { LabResultView(result).padding() }
.background(VQTokens.Palette.ink0)
.vqTheme(VQTheme(preference: preference)) // up/down pair, number format, reduce motion, languageLabChartView(chart)alone for a panel; value inspection is hover on macOS and touch-and-drag on iOS (chartXSelection), no platform code needed.- Export:
VQExport.png(chart:),VQExport.pdf(chart:),VQExport.png(LabResultView(result), width:),VQExport.csv(chart:)— all@MainActorexcept CSV. - Tokens:
VQTokens.Palette.ink0…,VQTokens.UpDown,.vqFont(VQTokens.Typography.title)(scales with Dynamic Type). Replace the apps' ad-hoc colours with these; never write a hex colour. - Components mirror the web primitives:
VQPanel,VQSectionHeader,VQMetricTile/VQMetricGrid,VQKindBadge,VQDelta(useVQDelta(percentPoints:)for quotes'changePct),VQProvenanceChip(freshness)on every data surface,VQDataTable,VQSegmentedControl,VQEmptyState,VQSkeleton*insideVQLoading,VQAIActivity,VQProviderLogo(provider:),VQMarkdownText. - Numbers: always
VQFormatwiththeme.numberLocale;percent/bpstake fractions,percentValuetakes percent units; nil is "—". - Glass (
.bar,.regularMaterial) on toolbars, tab bars and the palette only.
7. Research agent (CONTRACT §9) — the heart of the product
Send mode: "research" to /api/chat (VQAnalysisMode.research; VQAnalysisMode.modes(ofConfig:) reads the modes
the server announces). Everything below is in VQuantKit/ResearchAgent and VQuantUI/Research.
The store
let agent = vq.researchAgent // VQResearchAgentClient
@State private var study = VQResearchSessionStore(client: agent)
// 1. while the analysis streams — in the app's existing stream loop, next to its own handling of each event:
study.apply(eventJSON, index: frame.id) // VQJSON of the event + the SSE id
// (re-attaching with ?from=N, duplicates and unknown events are harmless; `beginGeneration()` before a new question)
// 2. a finished conversation, or a study started on another device:
await study.reload(sessionId: conversationId, conversation: storedSessionJSON) // GET /api/sessions/:id as VQJSON
// also call it when the stream ends, and on the sync hint `generations` / `sessions`eventJSON is the app's own event converted to VQJSON (try VQJSON.parse(data) on the data: payload). The store
exposes objective, plan, timeline, executions (failed ones kept, with output / error / durationMs),
installs, runs, experiments, gateFindings, figures, pendingApprovals, finalReport, counts,
isRunning, plus detail (files, library, environment) and sandbox after a reload.
Approvals: await study.answer(approval, .approve) / .deny. A request lives 15 minutes
(approval.countdown(now:), isAnswerable(now:)); a 404 means it expired or was answered elsewhere and the store
marks it expired. Pending requests of the person across studies: agent.approvals() (badge on the app icon or tab).
The views
Give them the workspace once, then compose:
ResearchActivityView(store: study, // the convenience container: approvals, summary, sections
onExportFigure: { figure, format, data in save(data, suggestedName: figure.title, format) },
onDownload: { path, data in save(data, path) })
.researchDataSource(ResearchDataSource(client: agent, workspaceId: study.workspaceId ?? VQResearchSession.reference(sessionId: id)))
.vqTheme(theme)Or arrange the pieces yourself — none of them scrolls on its own, each takes plain values:
| Piece | Takes | Typical place |
|---|---|---|
ResearchApprovalCard(approval, onApprove:, onRefuse:) |
one pending approval | above everything, and as a sheet / notification action |
ResearchPlanView(state) |
objective + plan | top of the inspector |
ResearchTimelineView(state, limit:, onSelect:) |
the decisions timeline | macOS inspector tab "Activity"; iPhone first segment |
ResearchExecutionList(executions, installs:, expanded:) |
cells with code, output, error | tab "Code" (ResearchCodeView alone for one script) |
ResearchExperimentsTable(experiments, onOpenArtifact:) |
the ledger | tab / iPad column |
ResearchFiguresGrid(figures, onExport:) |
figures, zoom, PNG / SVG / PDF | tab; the export closure receives the bytes |
ResearchRunsList(runs, onCancel:) |
background runs + log tail | tab |
ResearchFilesBrowser(files:, selection:, onDownload:) / ResearchFilePreview(path:) |
store.detail?.files |
tab; on iPhone push the preview |
ResearchEnvironmentPanel(sandbox:, environment:, library:) |
store.sandbox, store.detail |
tab; shows plainly when the sandbox is not enforced |
ResearchQualityGateView(findings) |
store.gateFindings |
under the answer |
macOS: an inspector with a TabView (or Picker) over ResearchActivityView.Section.allCases, each tab a
ScrollView { activity.content(section) } — or the pieces directly. iPad: NavigationSplitView with the timeline in
the middle column and the selected section in the detail. iPhone: ResearchActivityView as it is (segmented switch).
The views load code, logs, images and dataset profiles through \.researchDataSource; \.researchPreload is an
optional in-memory cache read first (also what previews use). Buttons use .buttonStyle(.vqPrimary / .vqSecondary).
Files, datasets, upload
let files = try await agent.files(workspaceId) // flat; VQResearchFileTree.build(files) for a tree
let page = try await agent.textFile(workspaceId, path: "code/model.py", offset: 0, limit: 400)
let bytes = try await agent.fileData(workspaceId, path: figure.files!.pdf!) // figures, datasets, anything to share
let profile = try await agent.inspect(workspaceId, path: "data/prices.csv") // VQDatasetInspection
let (session, sessionId) = try await agent.createSession(title: "Macro US") // before the first message
let limit = try await agent.sandbox().uploadMaxBytes
if let refusal = VQDatasetUpload.validate(name: name, size: size, maxBytes: limit) { show(refusal.message()) }
let file = try await agent.upload(session.id, name: name, data: data, maxBytes: limit) // checks the signature too; then chat with sessionIdUpload errors: VQDatasetUpload.Refusal (thrown before sending) and VQDatasetUpload.message(for: VQError) (415,
413…). The upload is the one request whose body is not JSON: an adapter must send request.contentType when it is
set (see §1). For files above a few tens of MB prefer the app's own background URLSession with
agent.fileRequest / a multipart body from VQDatasetUpload.multipart.
Stored conversations: VQMessageResearch.ofSession(json) gives each message's research summary (workspace,
experiments, executions total / failed, quality gate) for the conversation list and the answer footer.
0.3 additions for the research agent
- Offer the mode when
await agent.researchModeAvailability()is non-nil (the sandbox route answers); it is not in/api/config.vq.research.run(project:prompt:mode: "research")starts a study inside a project. - Reopened studies have their plan and figure verdicts: nothing to do —
reloadreadsgenerations,planandfigures, plus the answered approvals of the workspace.store.budgetApplied,store.generations(a last generationinterrupted= cut by a server restart: say so and let the person continue). - Times: every timeline entry now has
atwhen the server sent it;ResearchTimelineViewshows it. - Figures:
figure.lintStatusispassed | fixed | issues.fixedis the ordinary case — the grid shows it as quietly aspassed; onlyissuesis flagged.figure.captionis the text to put under the figure. - Truncated code: a cell whose stream text ends with "…" (
execution.codeIsTruncated) is read in full fromexecution.codePathwhen its row is opened —ResearchExecutionListdoes it through the data source. - Budget:
VQBudgetApplied(event: json)on the first event of a generation (the reducer already keeps it). - Delete a file:
try await agent.deleteFile(workspaceId, path:)(400 for layout directories, 404 when absent).
8. Quant Lab 0.3 (renderer rules)
- Forms: build fields from
form.visibleGroups(re-read after each change) and markform.isRequired(param);form.validate()now refuses a missing conditional field with the server's own sentence. - Currency:
LabResultViewformats with the code the server gives (metric, column, per-rowcurrencyKey, axis title). If you format a cell yourself:table.cell(row, column, locale:)ortable.currency(of: row, column). - Units: use
VQFormat.byUnitName(value, metric.unitName, …)rather thanbyUnit(value, metric.unit)— it also knowsyears. - Matrices:
chart.cellAxis(label, unit, currency) describes the cells (zwhen present,ybefore). - Bands / candles: handled by
LabChartView(series.drawsCentreLine,series.hasCandles). - Old results keep rendering as before.
9. Language (0.4)
Nothing to do. Every string the package shows — section titles, statuses, counters, approval cards, lint statuses,
freshness and kind labels, form validation sentences — comes from one String Catalog inside the package
(Sources/VQuantKit/Resources/Localizable.xcstrings, English and French, with plural rules). The package speaks
the language the app runs in: VQLanguage.preferred reads Bundle.main.preferredLocalizations, so an
English-only app gets English components on a French device, and an app localised in French gets French ones.
Text written by the server (reports, engine titles, parameter labels, warnings, gate findings) is shown as it is.
ResearchActivityView(store: store) // the app's language
.vqLanguage(.fr) // or force one for this hierarchy (nil: back to the default)
.vqLanguage(locale: locale) // same from a Locale ("fr", "fr-CA" → French; else English)
VQTheme(preference: preference, language: .en) // unchanged: a theme can still carry a language;
// `.vqLanguage(_:)` wins over it
form.validate(language: .fr) // kit sentences outside views take a language too
form.issue(for: "symbol", language: .fr) // (the no-argument forms use VQLanguage.preferred)
VQL10n.string("%lld defects left", .fr, 2) // "2 défauts restants" — direct catalog accessNumber and date formats are not the language: they follow VQTheme.numberLocale (the person's preference) and the
language: argument of VQFormat.date/time/asOf. Adding a string: add the key (its English text) with both
translations to the catalog — LocalizationTests fails when a key lacks a translation, when the sources ask for a
key the catalog does not hold, when a key is unused, or when a view picks a language in code.
10. Tests in the apps
let server = VQFakeServer()
let engine = VQSyncEngine(transport: server.transport(device: "mac"), storage: VQMemorySyncStorage(), clock: VQManualClock())VQFakeServer follows the contract's rev/seq/tombstone rules and can drop connections, lose acknowledgements and
answer any other route with stub. See Tests/VQuantKitTests/SyncEngineTests.swift for patterns.