FICUS , home
Reflex Lab · Docs

Compiler service, CLI and API

What runs in your browser, what needs the FICUS compiler service, and how access works.

On this page

What executes where

Reflex Lab separates browser work from private compilation. Project metadata, CSV parsing and profiling, local baseline training, graph replay, scenario arithmetic and imported-record inspection can run locally. Dataset rows live in this browser unless you explicitly authorize their transfer. Saving a local project or changing a chart does not itself upload those rows.

BrowserNeeds connected service
Import/profile rows and assign rolesConsent-bound row transfer for a service session.
Bounded local baseline and replayPrivate search, supported compilation, distillation or composition jobs.
Integration examples and local exportsVerified new runtime/package generation and service signing.
Imported PPK2/decision diagnosticsHosted board queues, remote monitor ingest and scoped API tokens.

The repository contains executable private workflows, but the public v3 compiler connection is being completed. Needs service is an honest dependency, not a simulated queue. Signing in establishes account state; it does not prove a compiler or board lane is available. Check capability responses and the feature’s own state before attempting a job.

The compatible-source route sends the reviewed derived graph and project metadata, not raw CSV rows. Learned thresholds can still reveal information. A private learning session can require rows and a teacher, so it needs its own explicit consent. Consent binds to the exact payload hash; edits invalidate the prior approval and should require a new review.

The v3 contract is versioned, JSON-based and uses snake_case wire keys with SHA-256 content identifiers. CSV upload is a consent-bound multipart operation; package download is binary. Service calls go through the same-origin allow-listed proxy, not a browser-supplied upstream URL. Operator credentials and signing secrets remain server-only.

When connectivity fails, distinguish “request not sent” from “job status unknown”. Resume status checks for an existing job rather than blindly submitting another. A completed status must bind the source, project revision and archive; download bytes must match its digest. Authentication and content hashing are different checks.

CLI commands mapped to the contract

The FICUS CLI below is a planned interface, not an installed executable or current command reference. The endpoint registry is the integration contract, not a promise that every endpoint is deployed. M1, M2 and M3 are contract milestones, not dates. Existing private runtime/learning job routes require adapters to this unified surface.

Planned CLI — unavailable until service and CLI are connected
ficus capabilities
ficus session create --request reviewed-session.json
ficus session status SESSION_ID
ficus package create --request package.json
ficus package download PACKAGE_ID
ficus monitor ingest --request decision-records.json
Planned commandContract endpoint
ficus capabilitiesGET /v1/capabilities
ficus session create / statusPOST /v1/sessions; GET /v1/sessions/{session_id}
ficus package create / downloadPOST /v1/packages; GET /v1/packages/{package_id}/download
ficus monitor ingestPOST /v1/monitor/ingest

Use Request access for a private build workflow or sign in to restore account state. Do not install an unrelated executable called ficus or invent a service URL from these examples. A runnable REST example requires an actual origin, access mechanism and reviewed request schema.

REST registry and release limits

View the complete planned endpoint registry
Method / pathPurposeMilestone
GET /v1/capabilitiesService identity, enabled features, limits and targets.M1
POST /v1/datasetsConsent-bound CSV upload for one session.M1
DELETE /v1/datasets/{upload_id}Delete an upload immediately.M1
POST /v1/sessionsStart a search, compile, distil or compose session.M1
GET /v1/sessions/{session_id}Status, progress, candidates so far and result.M1
GET /v1/sessions/{session_id}/logIncremental log lines (cursor).M1
POST /v1/sessions/{session_id}/cancelCancel a queued or running session.M1
POST /v1/sessions/{session_id}/promoteMake a search candidate the session's Reflex (compiles and verifies it).M2
GET /v1/cards/{card_sha256}/explanationExact graph and receipts of a compiled Reflex.M1
GET /v1/cards/{card_sha256}/size?target={target}Linked size split for a target toolchain.M2
POST /v1/preprocessing/previewWindow/feature preview with the exact C front semantics.M2
POST /v1/board-runsQueue a measurement on a FICUS-operated nRF54LM20 DK + PPK2.M3
GET /v1/board-runs/{board_run_id}Queue position and measured result.M3
POST /v1/packagesBuild a C99, Zephyr module or Arduino package for a Reflex.M1
GET /v1/packages/{package_id}Package status.M1
GET /v1/packages/{package_id}/downloadPackage ZIP (application/zip).M1
POST /v1/evidence/signSign a browser-built evidence bundle.M2
POST /v1/monitor/ingestDevice decision records for the field monitor.M3
GET /v1/tokensCLI/CI tokens for the signed-in account.M3
POST /v1/tokensCreate a scoped token (secret shown once).M3
DELETE /v1/tokens/{token_id}Revoke a token.M3
GET /v1/cards/{card_sha256}/evidenceRetrieve the Reflex-bound service evidence bundle (never raw rows).M2

Capabilities govern enabled targets, package kinds, limits and feature flags. Service search can return candidates with estimated costs; estimates must not be presented as measured. Host object size remains a host compiler scope until a target-linked size report says otherwise. A board-run queue and remote monitoring are separate dependencies from successful graph compilation.

Exact releases do not automatically become production eligible. Require the declared quality cohort, linked firmware resources, target timing, voltage-qualified charge/energy evidence and project approval as appropriate. No new uploaded model inherits catalog accuracy or the Nordic campaign. Keep generated artifacts and receipts together, and keep API tokens out of source, URLs, screenshots and downloadable evidence bundles.

Last reviewed .

Source of truth: published facts in content/public.ts; CURRENT_MEASURED_RESULTS.md; CONNECTED_BUILD_WORKFLOW.md; standalone C emitter and v3 endpoint contract. Reference examples are not physical-board test receipts.

On this page