SPB Git

Repository Public

INTEGRATION.md 21.7 KB

# 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.

swift
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.

swift
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

swift
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

swift
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 on hello and on each change, replays the queue, reconnects with back-off (1, 2, 4 … 60 s; Retry-After honoured). iOS suspends the stream in the background: call try await engine.syncNow() when the scene becomes active.
  • Reads and writes from SwiftUI:
swift
@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 (id main is 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 (id default), VQReview (server-written; put throws .forbidden). Edit the typed properties and save the whole value: unknown keys travel with it.
  • Conflicts: sync.conflicts lists VQConflictRecords. Show those with needsAttention (both versions are in local / remote); "keep theirs" = sync.keepRemote(id), otherwise sync.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: .connected and pendingWrites == 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 with engine.put, then drop the local store. The legacy portfolio is already bridged server-side to portfolio/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

swift
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) / .notRunning

Build 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

swift
import VQuantUI

ScrollView { LabResultView(result).padding() }
    .background(VQTokens.Palette.ink0)
    .vqTheme(VQTheme(preference: preference))        // up/down pair, number format, reduce motion, language
  • LabChartView(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 @MainActor except 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 (use VQDelta(percentPoints:) for quotes' changePct), VQProvenanceChip(freshness) on every data surface, VQDataTable, VQSegmentedControl, VQEmptyState, VQSkeleton* inside VQLoading, VQAIActivity, VQProviderLogo(provider:), VQMarkdownText.
  • Numbers: always VQFormat with theme.numberLocale; percent/bps take fractions, percentValue takes 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

swift
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:

swift
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

swift
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 sessionId

Upload 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 — reload reads generations, plan and figures, plus the answered approvals of the workspace. store.budgetApplied, store.generations (a last generation interrupted = cut by a server restart: say so and let the person continue).
  • Times: every timeline entry now has at when the server sent it; ResearchTimelineView shows it.
  • Figures: figure.lintStatus is passed | fixed | issues. fixed is the ordinary case — the grid shows it as quietly as passed; only issues is flagged. figure.caption is the text to put under the figure.
  • Truncated code: a cell whose stream text ends with "…" (execution.codeIsTruncated) is read in full from execution.codePath when its row is opened — ResearchExecutionList does 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 mark form.isRequired(param); form.validate() now refuses a missing conditional field with the server's own sentence.
  • Currency: LabResultView formats with the code the server gives (metric, column, per-row currencyKey, axis title). If you format a cell yourself: table.cell(row, column, locale:) or table.currency(of: row, column).
  • Units: use VQFormat.byUnitName(value, metric.unitName, …) rather than byUnit(value, metric.unit) — it also knows years.
  • Matrices: chart.cellAxis (label, unit, currency) describes the cells (z when present, y before).
  • 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.

swift
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 access

Number 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

swift
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.

Files main
Menu

Theme