SPB Git

Repository Public

INTEGRATION.md 21.7 KB 353 lines markdown

1# Integrating VQuantKit into VQuant macOS and VQuant iOS (2.0 "VQuant Next")23Add the package as a local dependency (`../VQuantKit`) and link `VQuantKit` + `VQuantUI` to the app target4(`VQuantKitTesting` to the test targets only). The package does not depend on either app's `VQuantCore`.5Send `X-VQ-Client: vquant-macos/2.0.0` / `vquant-ios/2.0.0 (<build>)`: a 1.x header receives only the six legacy6tools and sees `cancelled` jobs as `interrupted`.78The adapters below were written from the apps' current sources but **not compiled against them** (the app9repositories were not modified).1011## 1. Adapt the app's APIClient to `VQTransport`1213The transport returns the response whatever its status (the kit reads 409 bodies, `Retry-After`, `x-vq-locked`).14`VQRequest.path` is already percent-encoded per segment; `query` values are raw; `body` is JSON bytes.1516### macOS (`Core/Networking/APIClient.swift`, `HTTPTransport`)1718`APIClient.request(_:_:query:body:authenticated:accept:)` is public and builds the authenticated `URLRequest`; the19`HTTPTransport` the client was built with does the I/O.2021```swift22import VQuantKit23import VQuantCore2425struct MacVQTransport: VQTransport {26    let client: APIClient          // builds the request: base URL, Bearer token, X-VQ-Client, no Origin27    let http: HTTPTransport        // the same instance the APIClient was created with2829    private func urlRequest(_ r: VQRequest) throws -> URLRequest {30        var req = try client.request(HTTPMethod(rawValue: r.method.rawValue)!, r.path,31                                     query: Dictionary(r.query.map { ($0.name, Optional($0.value)) }, uniquingKeysWith: { $1 }),32                                     accept: r.accept)33        req.httpBody = r.body                      // the kit's bytes, as they are34        if r.body != nil { req.setValue(r.contentType ?? "application/json", forHTTPHeaderField: "Content-Type") }   // multipart for the dataset upload35        req.timeoutInterval = r.timeout36        return req37    }38    func send(_ r: VQRequest) async throws -> VQResponse {39        let (data, response) = try await http.data(for: try urlRequest(r))40        return VQResponse(data: data, http: response)41    }42    func stream(_ r: VQRequest) async throws -> VQByteStream {43        let (lines, response) = try await http.lines(for: try urlRequest(r))44        // the app's reader yields lines: give each one back its line end45        let chunks = AsyncThrowingStream<Data, Error> { c in46            let task = Task { do { for try await l in lines { c.yield(Data((l + "\n").utf8)) }; c.finish() } catch { c.finish(throwing: error) } }47            c.onTermination = { _ in task.cancel() }48        }49        return VQByteStream(http: response, chunks: chunks)50    }51}52```5354The kit's SSE parser dispatches at each `data:` line, so the blank lines `URLSession.AsyncBytes.lines` drops are not55needed. Session death: the kit reports `VQError.isLocked` and the engine's status becomes `.locked`; call the same56sign-out path the app's `onUnauthorized` handler uses (or check `x-vq-locked` in the adapter and call it there).5758### iOS (`Core/Networking/APIClient.swift`)5960`APIClient.urlRequest(_:)` percent-encodes the path itself (`%` is not in its allowed set), so hand it the decoded path.6162```swift63struct IOSVQTransport: VQTransport {64    let client: APIClient6566    private func urlRequest(_ r: VQRequest) throws -> URLRequest {67        var a = APIRequest(method: r.method.rawValue, path: r.path.removingPercentEncoding ?? r.path,68                           query: Dictionary(r.query.map { ($0.name, $0.value) }, uniquingKeysWith: { $1 }),69                           body: r.body, timeout: r.timeout)70        a.accept = r.accept ?? "application/json"71        if let type = r.contentType { a.contentType = type }      // multipart for the dataset upload72        return try client.urlRequest(a)73    }74    func send(_ r: VQRequest) async throws -> VQResponse {75        let (data, response) = try await client.session.data(for: try urlRequest(r))76        guard let http = response as? HTTPURLResponse else { throw URLError(.badServerResponse) }77        if http.statusCode == 401 { try? client.check(response, data: data, hadToken: true) }   // runs the app's sign-out handler78        return VQResponse(data: data, http: http)79    }80    func stream(_ r: VQRequest) async throws -> VQByteStream {81        var req = try urlRequest(r); req.timeoutInterval = 9082        let (bytes, response) = try await client.session.bytes(for: req)83        guard let http = response as? HTTPURLResponse else { throw URLError(.badServerResponse) }84        let chunks = AsyncThrowingStream<Data, Error> { c in85            let task = Task {86                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() }87                catch { c.finish(throwing: error) }88            }89            c.onTermination = { _ in task.cancel() }90        }91        return VQByteStream(http: http, chunks: chunks)92    }93}94```9596Check before shipping: symbols with `^` (`/api/v2/data/bars/%5EGSPC`) round-trip through each app's encoder — the97kit's own `VQURLSessionTransport` is tested for it, the adapters are not. Simplest alternative on either platform:98`VQURLSessionTransport(baseURL:clientHeader:token:onLocked:)` with the Keychain reader as `token`.99100## 2. One entry point101102```swift103let vq = VQuantAPI(transport: MacVQTransport(client: api, http: transport))104try await vq.data.marketOverview()        // VQMarketOverview105try await vq.models.catalog()             // VQModelCatalog106try await vq.lab.catalog()                // 19 tools with a 2.x header107try await vq.research.bundle(project: id)108```109110Errors are `VQError` (`kind`, `status`, the server's `message`, `retryAfter`, `isLocked`, parsed `body`).111Models are read tolerantly: cache the raw `Data` in the app's `DiskCache` and decode with `T.decode(data)`.112113## 3. Wire the sync engine114115```swift116let storage = try VQFileSyncStorage(directory: appSupport.appendingPathComponent("sync/\(personId)"),117                                    cipher: AppCipher())          // VQSyncCipher: the sealing the DiskCache already uses118let engine = VQSyncEngine(client: vq.client, storage: storage)119await engine.start()                         // after sign-in; `await engine.stop()` when leaving, `reset()` at sign-out120```121122- One engine per signed-in person; the directory must be per person. iOS: an app-group container if widgets read it.123- `start()` loads the replica, opens `/api/v2/sync/stream`, pulls on `hello` and on each `change`, replays the queue,124  reconnects with back-off (1, 2, 4 … 60 s; `Retry-After` honoured). iOS suspends the stream in the background:125  call `try await engine.syncNow()` when the scene becomes active.126- Reads and writes from SwiftUI:127128```swift129@State private var watchlists = VQSyncedCollection<VQWatchlist>(engine: engine)130@State private var sync = VQSyncStatusStore(engine: engine)131132List(watchlists.items) { w in Text(w.data.name) }       // pending local writes included; watchlists.pendingIDs marks them133    .task { await watchlists.observe() }134    .task { await sync.observe() }                      // sync.status.connection / pendingWrites, sync.conflicts135136await watchlists.update(id) { $0.add("NVDA") }          // durable in the queue before it returns; shown at once137```138139- Typed kinds: `VQWatchlist`, `VQPortfolio` (id `main` is the agent's portfolio — never create it blindly: the engine140  merges with the bridged one on 409), `VQWorkspace` (`layout: VQLayoutNode`, `addPanel` / `removePanel`), `VQChart`,141  `VQProject`, `VQNote`, `VQPreference` (id `default`), `VQReview` (server-written; `put` throws `.forbidden`).142  Edit the typed properties and save the whole value: unknown keys travel with it.143- Conflicts: `sync.conflicts` lists `VQConflictRecord`s. Show those with `needsAttention` (both versions are in144  `local` / `remote`); "keep theirs" = `sync.keepRemote(id)`, otherwise `sync.dismiss(id)`.145- Hints: `for await hint in await engine.hints()` → refresh conversations (`sessions`), running analyses146  (`generations`), the job list (`quant_jobs`). This replaces polling those lists.147- Sync status dot: `.connected` and `pendingWrites == 0` → synced; `.reconnecting` → offline, writes are queued;148  `.locked` → sign in again (the queue is kept).149- Migrating 1.x local data (iOS watchlists in `LocalStores`): create objects once with `engine.put`, then drop the150  local store. The legacy portfolio is already bridged server-side to `portfolio/main`.151152## 4. Generations (additive to what the apps already decode)153154Keep the existing stream handling; pass each event's JSON to `VQGenerationEvent(json:)` as well:155`.modelRouted` (show model + reason when `auto` was asked), `.budget`, `.quantJob` (open the job with156`vq.lab.job(id)`), `.provenance`, `.done(sessionId:usage:)`; everything else is `.other` and stays yours.157Stored conversations: `VQMessageExtras.ofSession(json)` gives `provenance`, `model`, `generationId`, `usage` per158message (the route returns `messages` as an array or as a JSON string: both are read).159Trace sheet: `vq.models.trace(sessionId:)`.160161## 5. Quant Lab162163```swift164let catalog = try await vq.lab.catalog()165var form = VQLabForm(tool: catalog.tool("risk_lab")!)          // defaults filled in166form["symbols"] = "AAPL, MSFT, TLT"                             // text as typed, or structured values167switch form.validate() {                                        // the server's rules and wording, all issues at once168case .failure(let invalid): show(invalid.issues)                // [name, message]169case .success(let params):170    let job = try await vq.lab.start(tool: form.tool.id, params: params, projectId: projectId)171    for try await state in vq.lab.follow(job.id) { progress = state.progress }   // ends at the first finished state172}173try await vq.lab.cancel(job.id)                                 // .cancelled / .notCancellable (legacy) / .notRunning174```175176Build the form UI from `tool.groups` and `param.type` (`symbol, symbols, int, number, numbers, choice, bool, date,177text, json`; `help`, `min/max`, `minDate/maxDate`, `choices`, `maxLength`, `multiline`, `schemaHint`). A type this178version does not know is shown as a text field. `job.labResult` is non-nil for `lab/1` results; for the six legacy179tools keep the existing renderer on `job.result`.180181## 6. `LabResultView` and the design system182183```swift184import VQuantUI185186ScrollView { LabResultView(result).padding() }187    .background(VQTokens.Palette.ink0)188    .vqTheme(VQTheme(preference: preference))        // up/down pair, number format, reduce motion, language189```190191- `LabChartView(chart)` alone for a panel; value inspection is hover on macOS and touch-and-drag on iOS192  (`chartXSelection`), no platform code needed.193- Export: `VQExport.png(chart:)`, `VQExport.pdf(chart:)`, `VQExport.png(LabResultView(result), width:)`,194  `VQExport.csv(chart:)` — all `@MainActor` except CSV.195- Tokens: `VQTokens.Palette.ink0…`, `VQTokens.UpDown`, `.vqFont(VQTokens.Typography.title)` (scales with Dynamic196  Type). Replace the apps' ad-hoc colours with these; never write a hex colour.197- Components mirror the web primitives: `VQPanel`, `VQSectionHeader`, `VQMetricTile` / `VQMetricGrid`, `VQKindBadge`,198  `VQDelta` (use `VQDelta(percentPoints:)` for quotes' `changePct`), `VQProvenanceChip(freshness)` on every data199  surface, `VQDataTable`, `VQSegmentedControl`, `VQEmptyState`, `VQSkeleton*` inside `VQLoading`, `VQAIActivity`,200  `VQProviderLogo(provider:)`, `VQMarkdownText`.201- Numbers: always `VQFormat` with `theme.numberLocale`; `percent`/`bps` take fractions, `percentValue` takes percent202  units; nil is "—".203- Glass (`.bar`, `.regularMaterial`) on toolbars, tab bars and the palette only.204205## 7. Research agent (CONTRACT §9) — the heart of the product206207Send `mode: "research"` to `/api/chat` (`VQAnalysisMode.research`; `VQAnalysisMode.modes(ofConfig:)` reads the modes208the server announces). Everything below is in `VQuantKit/ResearchAgent` and `VQuantUI/Research`.209210### The store211212```swift213let agent = vq.researchAgent                                  // VQResearchAgentClient214@State private var study = VQResearchSessionStore(client: agent)215216// 1. while the analysis streams — in the app's existing stream loop, next to its own handling of each event:217study.apply(eventJSON, index: frame.id)                       // VQJSON of the event + the SSE id218//    (re-attaching with ?from=N, duplicates and unknown events are harmless; `beginGeneration()` before a new question)219220// 2. a finished conversation, or a study started on another device:221await study.reload(sessionId: conversationId, conversation: storedSessionJSON)   // GET /api/sessions/:id as VQJSON222//    also call it when the stream ends, and on the sync hint `generations` / `sessions`223```224225`eventJSON` is the app's own event converted to `VQJSON` (`try VQJSON.parse(data)` on the `data:` payload). The store226exposes `objective`, `plan`, `timeline`, `executions` (failed ones kept, with `output` / `error` / `durationMs`),227`installs`, `runs`, `experiments`, `gateFindings`, `figures`, `pendingApprovals`, `finalReport`, `counts`,228`isRunning`, plus `detail` (files, library, environment) and `sandbox` after a reload.229230Approvals: `await study.answer(approval, .approve)` / `.deny`. A request lives 15 minutes231(`approval.countdown(now:)`, `isAnswerable(now:)`); a 404 means it expired or was answered elsewhere and the store232marks it expired. Pending requests of the person across studies: `agent.approvals()` (badge on the app icon or tab).233234### The views235236Give them the workspace once, then compose:237238```swift239ResearchActivityView(store: study,                             // the convenience container: approvals, summary, sections240                     onExportFigure: { figure, format, data in save(data, suggestedName: figure.title, format) },241                     onDownload: { path, data in save(data, path) })242    .researchDataSource(ResearchDataSource(client: agent, workspaceId: study.workspaceId ?? VQResearchSession.reference(sessionId: id)))243    .vqTheme(theme)244```245246Or arrange the pieces yourself — none of them scrolls on its own, each takes plain values:247248| Piece | Takes | Typical place |249|---|---|---|250| `ResearchApprovalCard(approval, onApprove:, onRefuse:)` | one pending approval | above everything, and as a sheet / notification action |251| `ResearchPlanView(state)` | objective + plan | top of the inspector |252| `ResearchTimelineView(state, limit:, onSelect:)` | the decisions timeline | macOS inspector tab "Activity"; iPhone first segment |253| `ResearchExecutionList(executions, installs:, expanded:)` | cells with code, output, error | tab "Code" (`ResearchCodeView` alone for one script) |254| `ResearchExperimentsTable(experiments, onOpenArtifact:)` | the ledger | tab / iPad column |255| `ResearchFiguresGrid(figures, onExport:)` | figures, zoom, PNG / SVG / PDF | tab; the export closure receives the bytes |256| `ResearchRunsList(runs, onCancel:)` | background runs + log tail | tab |257| `ResearchFilesBrowser(files:, selection:, onDownload:)` / `ResearchFilePreview(path:)` | `store.detail?.files` | tab; on iPhone push the preview |258| `ResearchEnvironmentPanel(sandbox:, environment:, library:)` | `store.sandbox`, `store.detail` | tab; **shows plainly when the sandbox is not enforced** |259| `ResearchQualityGateView(findings)` | `store.gateFindings` | under the answer |260261macOS: an inspector with a `TabView` (or `Picker`) over `ResearchActivityView.Section.allCases`, each tab a262`ScrollView { activity.content(section) }` — or the pieces directly. iPad: `NavigationSplitView` with the timeline in263the middle column and the selected section in the detail. iPhone: `ResearchActivityView` as it is (segmented switch).264265The views load code, logs, images and dataset profiles through `\.researchDataSource`; `\.researchPreload` is an266optional in-memory cache read first (also what previews use). Buttons use `.buttonStyle(.vqPrimary / .vqSecondary)`.267268### Files, datasets, upload269270```swift271let files = try await agent.files(workspaceId)                 // flat; VQResearchFileTree.build(files) for a tree272let page = try await agent.textFile(workspaceId, path: "code/model.py", offset: 0, limit: 400)273let bytes = try await agent.fileData(workspaceId, path: figure.files!.pdf!)      // figures, datasets, anything to share274let profile = try await agent.inspect(workspaceId, path: "data/prices.csv")      // VQDatasetInspection275276let (session, sessionId) = try await agent.createSession(title: "Macro US")      // before the first message277let limit = try await agent.sandbox().uploadMaxBytes278if let refusal = VQDatasetUpload.validate(name: name, size: size, maxBytes: limit) { show(refusal.message()) }279let file = try await agent.upload(session.id, name: name, data: data, maxBytes: limit)   // checks the signature too; then chat with sessionId280```281282Upload errors: `VQDatasetUpload.Refusal` (thrown before sending) and `VQDatasetUpload.message(for: VQError)` (415,283413…). The upload is the one request whose body is not JSON: an adapter must send `request.contentType` when it is284set (see §1). For files above a few tens of MB prefer the app's own background `URLSession` with285`agent.fileRequest` / a multipart body from `VQDatasetUpload.multipart`.286287Stored conversations: `VQMessageResearch.ofSession(json)` gives each message's `research` summary (workspace,288experiments, executions total / failed, quality gate) for the conversation list and the answer footer.289290### 0.3 additions for the research agent291292- **Offer the mode** when `await agent.researchModeAvailability()` is non-nil (the sandbox route answers); it is not in293  `/api/config`. `vq.research.run(project:prompt:mode: "research")` starts a study inside a project.294- **Reopened studies have their plan and figure verdicts**: nothing to do — `reload` reads `generations`, `plan` and295  `figures`, plus the answered approvals of the workspace. `store.budgetApplied`, `store.generations` (a last296  generation `interrupted` = cut by a server restart: say so and let the person continue).297- **Times**: every timeline entry now has `at` when the server sent it; `ResearchTimelineView` shows it.298- **Figures**: `figure.lintStatus` is `passed | fixed | issues`. `fixed` is the ordinary case — the grid shows it as299  quietly as `passed`; only `issues` is flagged. `figure.caption` is the text to put under the figure.300- **Truncated code**: a cell whose stream text ends with "…" (`execution.codeIsTruncated`) is read in full from301  `execution.codePath` when its row is opened — `ResearchExecutionList` does it through the data source.302- **Budget**: `VQBudgetApplied(event: json)` on the first event of a generation (the reducer already keeps it).303- **Delete a file**: `try await agent.deleteFile(workspaceId, path:)` (400 for layout directories, 404 when absent).304305## 8. Quant Lab 0.3 (renderer rules)306307- **Forms**: build fields from `form.visibleGroups` (re-read after each change) and mark `form.isRequired(param)`;308  `form.validate()` now refuses a missing conditional field with the server's own sentence.309- **Currency**: `LabResultView` formats with the code the server gives (metric, column, per-row `currencyKey`, axis310  title). If you format a cell yourself: `table.cell(row, column, locale:)` or `table.currency(of: row, column)`.311- **Units**: use `VQFormat.byUnitName(value, metric.unitName, …)` rather than `byUnit(value, metric.unit)` — it also312  knows `years`.313- **Matrices**: `chart.cellAxis` (label, unit, currency) describes the cells (`z` when present, `y` before).314- **Bands / candles**: handled by `LabChartView` (`series.drawsCentreLine`, `series.hasCandles`).315- Old results keep rendering as before.316317## 9. Language (0.4)318319Nothing to do. Every string the package shows — section titles, statuses, counters, approval cards, lint statuses,320freshness and kind labels, form validation sentences — comes from one String Catalog inside the package321(`Sources/VQuantKit/Resources/Localizable.xcstrings`, English and French, with plural rules). The package speaks322**the language the app runs in**: `VQLanguage.preferred` reads `Bundle.main.preferredLocalizations`, so an323English-only app gets English components on a French device, and an app localised in French gets French ones.324Text written by the server (reports, engine titles, parameter labels, warnings, gate findings) is shown as it is.325326```swift327ResearchActivityView(store: store)                       // the app's language328    .vqLanguage(.fr)                                     // or force one for this hierarchy (nil: back to the default)329    .vqLanguage(locale: locale)                          // same from a Locale ("fr", "fr-CA" → French; else English)330331VQTheme(preference: preference, language: .en)           // unchanged: a theme can still carry a language;332                                                         // `.vqLanguage(_:)` wins over it333334form.validate(language: .fr)                             // kit sentences outside views take a language too335form.issue(for: "symbol", language: .fr)                 // (the no-argument forms use VQLanguage.preferred)336VQL10n.string("%lld defects left", .fr, 2)               // "2 défauts restants" — direct catalog access337```338339Number and date *formats* are not the language: they follow `VQTheme.numberLocale` (the person's preference) and the340`language:` argument of `VQFormat.date/time/asOf`. Adding a string: add the key (its English text) with both341translations to the catalog — `LocalizationTests` fails when a key lacks a translation, when the sources ask for a342key the catalog does not hold, when a key is unused, or when a view picks a language in code.343344## 10. Tests in the apps345346```swift347let server = VQFakeServer()348let engine = VQSyncEngine(transport: server.transport(device: "mac"), storage: VQMemorySyncStorage(), clock: VQManualClock())349```350351`VQFakeServer` follows the contract's rev/seq/tombstone rules and can drop connections, lose acknowledgements and352answer any other route with `stub`. See `Tests/VQuantKitTests/SyncEngineTests.swift` for patterns.353
Files main
Menu

Theme