Lightweight launcher for PCCX-oriented local LLM workflows.
The user-facing launcher track for PCCX. It is intended to grow into a guided local LLM workflow that runs on supported edge devices (target: Xilinx Kria KV260) without requiring users to assemble a kernel / RTL stack themselves.
This repo is not the inference engine, not the RTL, and not the verification lab. Those live in their own PCCX repositories (see Related below). This repo is where the install / connect / launch flow will be wired up once the hardware side ships verified bring-up.
Currently a planning skeleton bootstrapped from a curated snapshot of the
upstream llm-lite launcher era. There is no working KV260 inference
path yet, and no model is actually executed by anything in this
repository today. See docs/PROVENANCE.md for the
exact source commit and what was / was not imported.
Clone the public repository and run the local scripts directly:
git clone https://github.com/pccxai/pccx-launcher.git
cd pccx-launcher
bash scripts/check.shNo model weights, board credentials, provider keys, or runtime daemon are required for the public scaffold.
Run the checked status and readiness surfaces:
bash scripts/status-stub.sh
bash scripts/runtime-readiness-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-surface-preview.sh --model gemma3n-e4b --target kv260For a short first-run path, see QUICKSTART.md.
Run the repository smoke test before opening a pull request or cutting a release:
bash scripts/smoke.shThe smoke test is local and deterministic. It verifies the checked shell surfaces and contract fixtures; it does not execute a model, contact hardware, call providers, upload data, or publish artifacts.
This repository is Apache-2.0 licensed. See LICENSE, CONTRIBUTING.md, SECURITY.md, and docs/RELEASE.md.
- Install supporting packages on the host or KV260-class device.
- Run a connection / status check against the target device.
- Pick a target model (initially Gemma 3N E4B) and a precision mode.
- Hand control to the launcher to start the local inference flow and surface logs / diagnostics.
Steps 3–4 will only become real once the PCCX FPGA / KV260 bring-up publishes a verified end-to-end path.
- Owns or uses a supported edge device such as Xilinx Kria KV260.
- Wants a guided launcher workflow rather than a hand-built kernel stack.
- Does not want to work directly on kernel / RTL internals.
- Wants a path toward local model execution and, later, local assistant workflows.
- KV260-oriented setup path.
- Gemma 3N E4B as a target model, not a current working claim.
- Button-driven launch flow.
- Connection / status checks.
- Guided logs and diagnostics.
- Local assistant mode (controlled local workflow with a reviewed tool boundary). The later-track plan is tracked in docs/LOCAL_WORKFLOW_MODE_PLAN.md.
- VS Code and other editor bridge planning for guided launches and log inspection.
- Additional target models beyond Gemma 3N E4B and additional edge devices beyond KV260. The later-track plan is tracked in docs/MULTI_MODEL_DEVICE_SUPPORT_PLAN.md.
- Integration with
pccx-labdiagnostics so device / kernel state can be surfaced through the launcher UI.
Runtime readiness depends on verification evidence published by
pccxai/pccx-FPGA-NPU-LLM-kv260 (RTL bring-up, simulation, timing
closure). Public source releases keep the runtime path blocked until that
evidence lands.
- No current KV260 inference claim — wait for the FPGA repo to publish verified bring-up logs before claiming an end-to-end run.
- No benchmark overclaim.
- No kernel development requirement for normal users.
- This repo is not labelled as stable or as ready for unattended use.
The current scripts are all probe / preview helpers — none of them runs inference, contacts a remote device, or installs anything. They exist so contributors can see the planned shape of the launcher flow and verify host-side prerequisites before the real engine lands.
| Script | What it does |
|---|---|
scripts/check.sh |
Probe host info, tooling availability, edge-device hints. Always exits 0. |
scripts/check-device-stub.sh |
Narrowly scoped device-tree / FPGA-node probe (KV260 / Kria detection only). Always exits 0. |
scripts/install-stub.sh |
Preview of the planned install flow; reports which host runtime pieces are present, lists device-side pieces as future deliverables. Always exits 0. |
scripts/status-stub.sh |
Launcher state summary. Default mode: local scaffold output, always exits 0. With --include-chat-action-bar, adds read-only disabled chat action-bar data. With --include-chat-clipboard-policy, adds read-only disabled chat clipboard-policy data. With --include-chat-redaction-policy, adds read-only disabled chat redaction-policy data. With --include-chat-attachment-policy, adds read-only disabled chat attachment-policy data. With --include-chat-shortcut-map, adds read-only disabled chat shortcut-map data. With --include-chat-accessibility, adds read-only chat accessibility metadata. With --include-chat-status-summary, adds read-only aggregate chat status-summary data. With --include-chat-review-packet, adds read-only chat review-packet data over existing checked fixture references. With --include-chat-gap-matrix, adds read-only chat implementation gap-matrix data over existing checked fixture references. With --include-chat-evidence-manifest, adds read-only chat evidence-manifest data over existing checked fixture references. With --include-chat-message-list, adds read-only empty chat message-list data. With --include-chat-response-stream, adds read-only blocked chat response stream data. With --include-chat-error-taxonomy, adds read-only chat error taxonomy data. With --include-chat-audit-event, adds read-only blocked chat audit-event metadata. With --include-chat-surface-layout, adds read-only chat surface layout data. With --include-chat-empty-state, adds read-only display-only chat empty-state data. With --include-chat-local-only-policy, adds read-only local-only/cloud-block policy data. With --include-chat-preferences, adds read-only chat preferences/settings data. With --include-chat-session-index, adds read-only empty chat session index data. With --include-chat-session-store-policy, adds read-only disabled chat session-store policy data. With --include-chat-session-title-policy, adds read-only placeholder session-title policy data. With --include-chat-transcript-policy, adds read-only chat transcript retention/export policy data. With --include-chat-send-result, adds read-only blocked chat send-result data. With --include-chat-composer, adds read-only chat composer/input-control data. With --include-chat-model-status, adds read-only blocked chat model-status display data. With --include-chat-model-selection-policy, adds read-only disabled chat model-selection data. With --include-chat-context-policy, adds read-only disabled chat context-window/tokenization policy data. With --include-chat-model-load-request, adds read-only disabled chat model-load request data. With --include-chat-session, adds read-only blocked chat/session and lifecycle summaries. With --include-chat-readiness, adds read-only chat readiness checks and recovery actions. With --include-device-session, adds a read-only device/session status panel. With --include-runtime-readiness, adds a read-only runtime readiness summary. With --backend pccx-lab, calls pccx-lab status --format json and forwards the run-status envelope (exits non-zero if binary is missing or output is invalid). |
scripts/device-session-status-stub.sh |
Data-only device/session status JSON for the Gemma 3N E4B + KV260 target. Reports connection, model load, session, diagnostics, readiness, discovery paths, flow steps, and error taxonomy as placeholder / blocked. |
scripts/runtime-readiness-stub.sh |
Data-only runtime readiness JSON for the Gemma 3N E4B + KV260 target. Reports blocked / not yet evidence-backed. |
scripts/chat-session-stub.sh |
Data-only standalone chat/session JSON for the Gemma 3N E4B + KV260 target. Reports disabled send controls, inactive session state, no prompt/response persistence, and readiness handoff references. |
scripts/chat-session-lifecycle-stub.sh |
Data-only chat session lifecycle JSON for the Gemma 3N E4B + KV260 target. Reports create, restore, clear, close, and export-summary operations as disabled, blocked, inactive, or unavailable. |
scripts/chat-surface-layout-stub.sh |
Data-only chat surface layout JSON for the Gemma 3N E4B + KV260 target. Reports planned shell regions and navigation items as local metadata without prompt/response/transcript/session-store reads or runtime actions. |
scripts/chat-empty-state-stub.sh |
Data-only chat empty-state JSON for the Gemma 3N E4B + KV260 target. Reports static placeholder display slots and disabled hints without prompts, responses, transcripts, session-store reads, command dispatch, model loads, runtime execution, target access, or provider calls. |
scripts/chat-local-only-policy-stub.sh |
Data-only chat local-only policy JSON for the Gemma 3N E4B + KV260 target. Reports cloud/provider/network dependency and fallback paths as not used, disabled, or blocked while local runtime evidence remains gated. |
scripts/chat-preferences-stub.sh |
Data-only chat preferences JSON for the Gemma 3N E4B + KV260 target. Reports planned settings panels and disabled controls without reading configuration, provider settings, model paths, session stores, prompts, transcripts, or artifacts. |
scripts/chat-session-index-stub.sh |
Data-only chat session index JSON for the Gemma 3N E4B + KV260 target. Reports an empty, not-configured session list/sidebar boundary without reading a store, session titles, prompts, responses, transcripts, or summaries. |
scripts/chat-session-store-policy-stub.sh |
Data-only chat session-store policy JSON for the Gemma 3N E4B + KV260 target. Reports disabled store configuration, path, manifest, read, write, delete, retention, and migration gates without reading config, paths, manifests, session records, transcripts, titles, prompts, responses, summaries, model paths, runtime logs, or artifacts. |
scripts/chat-session-title-policy-stub.sh |
Data-only chat session-title policy JSON for the Gemma 3N E4B + KV260 target. Reports static placeholder display names and disabled title read, generation, rename, and persistence controls without reading stores, transcripts, prompts, responses, summaries, titles, or paths. |
scripts/chat-model-status-stub.sh |
Data-only chat model-status JSON for the Gemma 3N E4B + KV260 target. Reports descriptor, asset, load, runtime, context, and response display rows as blocked, disabled, or unavailable. |
scripts/chat-model-selection-policy-stub.sh |
Data-only chat model-selection policy JSON for the Gemma 3N E4B + KV260 target. Reports a static placeholder model option and disabled catalog, picker, asset discovery, provider fallback, persistence, and load-request gates without reading config, catalogs, model paths, assets, prompts, responses, transcripts, runtime logs, or artifacts. |
scripts/chat-context-policy-stub.sh |
Data-only chat context-policy JSON for the Gemma 3N E4B + KV260 target. Reports disabled context-window, tokenization, token-counting, transcript, summary, truncation, context assembly, and runtime handoff gates without reading prompts, transcripts, summaries, tokenizers, model paths, runtime logs, or artifacts. |
scripts/chat-model-load-request-stub.sh |
Data-only chat model-load request JSON for the Gemma 3N E4B + KV260 target. Reports disabled model asset path, validation, runtime preflight, load, warmup, unload, and persistence gates without reading config, environment values, model paths, asset paths, weights, tokenizers, checksum manifests, prompts, responses, transcripts, runtime logs, or artifacts. |
scripts/chat-readiness-stub.sh |
Data-only chat readiness JSON for the Gemma 3N E4B + KV260 target. Reports readiness checks, error categories, and recovery actions as blocked, disabled, or local data only. |
scripts/chat-composer-stub.sh |
Data-only chat composer JSON for the Gemma 3N E4B + KV260 target. Reports input buffer, send, attachment, validation, and privacy states without reading, echoing, storing, or persisting prompt text. |
scripts/chat-send-result-stub.sh |
Data-only blocked chat send-result JSON for the Gemma 3N E4B + KV260 target. Reports disabled send state, no accepted input, no prompt echo, no generated response, and no runtime/model handoff. |
scripts/chat-response-stream-stub.sh |
Data-only blocked chat response stream JSON for the Gemma 3N E4B + KV260 target. Reports disabled response streaming, progress, token counter, and stop-control state without opening transport, generating chunks, counting tokens, or writing transcripts. |
scripts/chat-message-list-stub.sh |
Data-only empty chat message-list JSON for the Gemma 3N E4B + KV260 target. Reports an empty conversation viewport without reading a session store, transcript, prompt, response, summary, model path, runtime log, or artifact. |
scripts/chat-action-bar-stub.sh |
Data-only disabled chat action-bar JSON for the Gemma 3N E4B + KV260 target. Reports new, clear, export, retry, copy, stop, and attach controls without reading stores, transcripts, message bodies, files, clipboard data, model paths, runtime logs, or artifacts. |
scripts/chat-clipboard-policy-stub.sh |
Data-only disabled chat clipboard-policy JSON for the Gemma 3N E4B + KV260 target. Reports clipboard read, write, paste, copy, import, export, transcript-copy, message-copy, and clipboard-backed attachment gates without reading or writing clipboard, prompt, response, transcript, message, file, model, runtime, or artifact data. |
scripts/chat-redaction-policy-stub.sh |
Data-only disabled chat redaction-policy JSON for the Gemma 3N E4B + KV260 target. Reports redaction rule, content scan, PII, secret, prompt, response, transcript, message, attachment, clipboard, audit, and persistence gates without loading rules, scanning content, applying redactions, reading files, or starting model/runtime paths. |
scripts/chat-attachment-policy-stub.sh |
Data-only disabled chat attachment-policy JSON for the Gemma 3N E4B + KV260 target. Reports disabled file picker, file read, upload, import, preview, and persistence gates without reading file names, paths, metadata, contents, clipboard data, transcripts, generated artifacts, model paths, runtime logs, or artifacts. |
scripts/chat-shortcut-map-stub.sh |
Data-only disabled chat shortcut-map JSON for the Gemma 3N E4B + KV260 target. Reports planned keyboard accelerator and focus metadata without installing listeners, capturing key events, dispatching commands, changing focus, reading prompts, sessions, transcripts, messages, files, or clipboard data, or starting runtime paths. |
scripts/chat-accessibility-stub.sh |
Data-only chat accessibility JSON for the Gemma 3N E4B + KV260 target. Reports planned landmarks, labels, focus order, live-region gates, contrast review, and motion review metadata without implementing UI behavior, changing focus, capturing input, reading prompt/session content, starting runtime paths, or touching hardware. |
scripts/chat-status-summary-stub.sh |
Data-only chat status-summary JSON for the Gemma 3N E4B + KV260 target. Aggregates existing checked chat surface references into blocked/disabled display cards without reading prompts, session stores, configuration, model paths, runtime logs, artifacts, provider state, or hardware state. |
scripts/chat-review-packet-stub.sh |
Data-only chat review-packet JSON for the Gemma 3N E4B + KV260 target. Collects existing checked chat fixture references and review gates without approving prompt capture, session-store reads, model loading, runtime execution, provider calls, or hardware access. |
scripts/chat-gap-matrix-stub.sh |
Data-only chat implementation gap-matrix JSON for the Gemma 3N E4B + KV260 target. Tracks remaining standalone chat blockers over existing checked fixture references without closing gaps, reading prompts, reading session stores, loading models, executing runtime paths, calling providers, reading files or clipboard data, invoking pccx-lab or IDE paths, touching hardware, or reading artifacts. |
scripts/chat-evidence-manifest-stub.sh |
Data-only chat evidence-manifest JSON for the Gemma 3N E4B + KV260 target. Lists checked fixture references, including the model-selection policy, context-policy, empty-state, model-load request, session-store policy, accessibility, shortcut-map, clipboard-policy, and attachment-policy fixtures, and missing evidence gates without accepting evidence, closing gaps, approving review gates, reading model catalogs, reading context inputs, reading prompts or transcripts, reading model assets, reading stores, reading artifacts, loading models, executing runtime paths, calling providers, invoking pccx-lab or IDE paths, touching hardware, or enabling standalone chat. |
scripts/chat-transcript-policy-stub.sh |
Data-only chat transcript policy JSON for the Gemma 3N E4B + KV260 target. Reports retention, export, storage, and privacy policy state without reading, generating, storing, persisting, summarizing, or exporting prompt/response/transcript content. |
scripts/chat-audit-event-stub.sh |
Data-only chat audit-event JSON for the Gemma 3N E4B + KV260 target. Reports blocked send metadata, redaction policy, absent prompt/response/transcript content, and disabled audit persistence. |
scripts/chat-error-taxonomy-stub.sh |
Data-only chat error taxonomy JSON for the Gemma 3N E4B + KV260 target. Groups blocked readiness, model/runtime, session, and policy errors without reading prompts, providers, configs, model paths, logs, stores, or artifacts. |
scripts/chat-surface-preview.sh |
Read-only terminal preview of the standalone chat surface. Renders the checked chat/session contract as blocked UI state without accepting prompts, executing a model, or writing artifacts. |
scripts/launch-stub.sh |
Dry-run preview of the intended launch sequence. Requires --dry-run; exits 1 without it. |
scripts/chat-stub.sh |
Dry-run chat stub. Requires --dry-run; exits 1 without it. Accepts --prompt "..." or stdin. No model is executed. |
bash scripts/check.sh
bash scripts/check-device-stub.sh
bash scripts/install-stub.sh
bash scripts/status-stub.sh
bash scripts/status-stub.sh --include-chat-model-status
bash scripts/status-stub.sh --include-chat-model-selection-policy
bash scripts/status-stub.sh --include-chat-context-policy
bash scripts/status-stub.sh --include-chat-model-load-request
bash scripts/status-stub.sh --include-chat-session
bash scripts/status-stub.sh --include-chat-surface-layout
bash scripts/status-stub.sh --include-chat-empty-state
bash scripts/status-stub.sh --include-chat-local-only-policy
bash scripts/status-stub.sh --include-chat-preferences
bash scripts/status-stub.sh --include-chat-session-index
bash scripts/status-stub.sh --include-chat-session-store-policy
bash scripts/status-stub.sh --include-chat-session-title-policy
bash scripts/status-stub.sh --include-chat-readiness
bash scripts/status-stub.sh --include-chat-composer
bash scripts/status-stub.sh --include-chat-send-result
bash scripts/status-stub.sh --include-chat-transcript-policy
bash scripts/status-stub.sh --include-chat-audit-event
bash scripts/status-stub.sh --include-chat-error-taxonomy
bash scripts/status-stub.sh --include-chat-response-stream
bash scripts/status-stub.sh --include-chat-message-list
bash scripts/status-stub.sh --include-chat-action-bar
bash scripts/status-stub.sh --include-chat-clipboard-policy
bash scripts/status-stub.sh --include-chat-redaction-policy
bash scripts/status-stub.sh --include-chat-attachment-policy
bash scripts/status-stub.sh --include-chat-shortcut-map
bash scripts/status-stub.sh --include-chat-accessibility
bash scripts/status-stub.sh --include-chat-status-summary
bash scripts/status-stub.sh --include-chat-review-packet
bash scripts/status-stub.sh --include-chat-gap-matrix
bash scripts/status-stub.sh --include-chat-evidence-manifest
bash scripts/status-stub.sh --include-device-session
bash scripts/status-stub.sh --include-runtime-readiness
bash scripts/device-session-status-stub.sh --model gemma3n-e4b --target kv260
bash scripts/runtime-readiness-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-model-status-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-model-selection-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-context-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-model-load-request-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-session-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-session-lifecycle-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-surface-layout-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-empty-state-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-local-only-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-preferences-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-session-index-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-session-store-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-session-title-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-readiness-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-composer-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-send-result-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-transcript-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-audit-event-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-error-taxonomy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-response-stream-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-message-list-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-action-bar-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-clipboard-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-redaction-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-attachment-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-shortcut-map-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-accessibility-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-status-summary-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-review-packet-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-gap-matrix-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-evidence-manifest-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-surface-preview.sh --model gemma3n-e4b --target kv260
bash scripts/launch-stub.sh --dry-run
bash scripts/chat-stub.sh --dry-run --prompt "hello"The --dry-run scripts exit 1 without the flag as a deliberate guard —
there is no real inference engine to hand off to. They will be replaced
by real implementations only after pccxai/pccx-FPGA-NPU-LLM-kv260
publishes verified bring-up evidence.
scripts/status-stub.sh can call the pccx-lab status --format json
controlled CLI/core boundary and forward the run-status envelope:
# Requires pccx-lab binary on PATH or PCCX_LAB_BIN set.
bash scripts/status-stub.sh --backend pccx-lab
# Point to a specific build:
PCCX_LAB_BIN=/path/to/pccx-lab bash scripts/status-stub.sh --backend pccx-labBinary resolution order:
PCCX_LAB_BINenvironment variable (if non-empty and executable).pccx-labonPATH.
No silent fallback. If --backend pccx-lab is explicitly requested
but the binary is not found or returns an error, the script exits
non-zero with a clear message. It does not fall back to local scaffold
output.
The pccx-lab status output is an early, pre-compatibility run-status envelope. It operates in host-dry-run mode: no real KV260 device probing is performed, no model is executed, and no inference is started. This is a planned KV260-oriented launcher path, not a readiness claim.
The launcher now has a small data-only status contract for future editor consumers:
python3 contracts/launcher_ide_status_contract.py
python3 scripts/tests/launcher_ide_contract_test.pyThe contract reports conservative placeholder state: configured target, availability, runtime/model/evidence status, supported future operations, safety flags, and a planned read-only pccx-lab diagnostics handoff.
It does not execute the launcher, call a provider, contact hardware, load a model, implement an editor bridge, or make a compatibility promise. See docs/LAUNCHER_IDE_BRIDGE_CONTRACT.md. The later-track JetBrains and generic editor direction is tracked in docs/OTHER_EDITOR_BRIDGE_PLAN.md. The later-track local assistant mode direction is tracked in docs/LOCAL_WORKFLOW_MODE_PLAN.md.
The launcher also has a small data-only model/runtime descriptor boundary:
python3 contracts/model_runtime_descriptor_contract.py
python3 scripts/tests/model_runtime_descriptor_test.pyThe checked fixture covers Gemma 3N E4B as a descriptor target and a KV260 PCCX runtime placeholder. Model assets are external/user-provided and not bundled. The runtime path is planned, unavailable, and not configured, so compatibility remains provisional until evidence exists.
This boundary does not load weights, execute a runtime, call a provider, touch KV260 hardware, report performance, implement MCP/LSP, or make an API/ABI compatibility commitment. See docs/MODEL_RUNTIME_DESCRIPTOR_BOUNDARY.md. The later-track multi-model and multi-device direction is tracked in docs/MULTI_MODEL_DEVICE_SUPPORT_PLAN.md.
The launcher has a read-only diagnostics handoff contract for future pccx-lab consumers:
python3 contracts/diagnostics_handoff_contract.py
python3 scripts/tests/diagnostics_handoff_contract_test.pyThe checked fixture references the launcher/IDE status contract and the model/runtime descriptor fixture by id. It summarizes blocked or not-configured placeholder state without raw logs, private paths, user prompts, source code, secrets, tokens, provider configuration, model weight paths, telemetry, automatic upload, or write-back.
This boundary does not execute pccx-lab, invoke launcher runtime code, touch KV260 hardware, call providers, implement MCP/LSP, or add a marketplace flow. See docs/DIAGNOSTICS_HANDOFF_CONTRACT.md.
pccx-lab has a separate read-only validator for this JSON shape. The launcher does not invoke that command or depend on it at runtime.
The launcher now has a data-only, evidence-aware runtime readiness surface for the Gemma 3N E4B + KV260 target:
python3 contracts/runtime_readiness_contract.py --model gemma3n-e4b --target kv260
bash scripts/runtime-readiness-stub.sh --model gemma3n-e4b --target kv260
bash scripts/status-stub.sh --include-runtime-readiness
python3 scripts/tests/runtime_readiness_contract_test.pyThe checked fixture reports the current answer as blocked / not yet evidence-backed. It includes a deterministic fixture version, last-updated source boundary, top-level readiness/evidence states, descriptor evidence, xsim evidence of 11 passed and 0 failed, and Vivado synthesis evidence while keeping timing, implementation, bitstream, KV260 smoke, runtime evidence, and throughput measurement in blocked or target-only states. 20 tok/s remains a target until measured.
The status command reads the same local readiness stub and prints a short human summary. It is still read-only status data.
This surface does not load weights, execute a runtime, touch KV260 hardware, call providers, invoke pccx-lab, invoke systemverilog-ide, upload telemetry, or write artifacts. See docs/RUNTIME_READINESS_STATUS.md.
The launcher now has a data-only status panel and connection-flow contract for the planned Gemma 3N E4B + KV260 path:
python3 contracts/device_session_status_contract.py --model gemma3n-e4b --target kv260
bash scripts/device-session-status-stub.sh --model gemma3n-e4b --target kv260
bash scripts/status-stub.sh --include-device-session
python3 scripts/tests/device_session_status_contract_test.py
bash scripts/tests/status-device-session.shThe checked fixture reports device connection as not configured, model load as not loaded, session activity as inactive, pccx-lab diagnostics as a read-only placeholder, and runtime readiness as blocked. It also documents planned discovery paths, a gated connection and launch flow, and an error taxonomy with user remediation text.
This surface does not probe hardware, open serial ports, scan networks, attempt authentication, load model assets, invoke pccx-lab, start a runtime, stream logs, upload telemetry, or write artifacts. See docs/KV260_CONNECTION_AND_STATUS_FLOW.md.
The launcher now has a data-only standalone chat/session contract for the planned local chat entry point:
python3 contracts/chat_session_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_model_status_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_model_selection_policy_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_model_load_request_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_readiness_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_audit_event_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_error_taxonomy_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_response_stream_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_action_bar_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_redaction_policy_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_attachment_policy_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_session_store_policy_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_shortcut_map_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_session_title_policy_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_empty_state_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_status_summary_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_review_packet_contract.py --model gemma3n-e4b --target kv260
python3 contracts/chat_gap_matrix_contract.py --model gemma3n-e4b --target kv260
bash scripts/chat-model-status-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-model-selection-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-model-load-request-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-session-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-session-lifecycle-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-session-store-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-session-title-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-empty-state-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-readiness-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-audit-event-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-error-taxonomy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-response-stream-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-action-bar-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-clipboard-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-redaction-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-attachment-policy-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-shortcut-map-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-review-packet-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-gap-matrix-stub.sh --model gemma3n-e4b --target kv260
bash scripts/chat-surface-preview.sh --model gemma3n-e4b --target kv260
bash scripts/status-stub.sh --include-chat-model-status
bash scripts/status-stub.sh --include-chat-model-selection-policy
bash scripts/status-stub.sh --include-chat-model-load-request
bash scripts/status-stub.sh --include-chat-session
bash scripts/status-stub.sh --include-chat-readiness
bash scripts/status-stub.sh --include-chat-audit-event
bash scripts/status-stub.sh --include-chat-error-taxonomy
bash scripts/status-stub.sh --include-chat-response-stream
bash scripts/status-stub.sh --include-chat-action-bar
bash scripts/status-stub.sh --include-chat-clipboard-policy
bash scripts/status-stub.sh --include-chat-redaction-policy
bash scripts/status-stub.sh --include-chat-attachment-policy
bash scripts/status-stub.sh --include-chat-session-store-policy
bash scripts/status-stub.sh --include-chat-shortcut-map
bash scripts/status-stub.sh --include-chat-session-title-policy
bash scripts/status-stub.sh --include-chat-empty-state
bash scripts/status-stub.sh --include-chat-status-summary
bash scripts/status-stub.sh --include-chat-review-packet
bash scripts/status-stub.sh --include-chat-gap-matrix
python3 scripts/tests/chat_session_contract_test.py
python3 scripts/tests/chat_model_status_contract_test.py
python3 scripts/tests/chat_model_selection_policy_contract_test.py
python3 scripts/tests/chat_model_load_request_contract_test.py
python3 scripts/tests/chat_session_lifecycle_contract_test.py
python3 scripts/tests/chat_session_title_policy_contract_test.py
python3 scripts/tests/chat_readiness_contract_test.py
python3 scripts/tests/chat_audit_event_contract_test.py
python3 scripts/tests/chat_error_taxonomy_contract_test.py
python3 scripts/tests/chat_response_stream_contract_test.py
python3 scripts/tests/chat_action_bar_contract_test.py
python3 scripts/tests/chat_redaction_policy_contract_test.py
python3 scripts/tests/chat_attachment_policy_contract_test.py
python3 scripts/tests/chat_session_store_policy_contract_test.py
python3 scripts/tests/chat_shortcut_map_contract_test.py
python3 scripts/tests/chat_empty_state_contract_test.py
python3 scripts/tests/chat_status_summary_contract_test.py
python3 scripts/tests/chat_review_packet_contract_test.py
python3 scripts/tests/chat_gap_matrix_contract_test.py
python3 scripts/tests/chat_surface_preview_test.py
bash scripts/tests/status-chat-model-status.sh
bash scripts/tests/status-chat-model-selection-policy.sh
bash scripts/tests/status-chat-model-load-request.sh
bash scripts/tests/status-chat-session.sh
bash scripts/tests/status-chat-readiness.sh
bash scripts/tests/status-chat-audit-event.sh
bash scripts/tests/status-chat-error-taxonomy.sh
bash scripts/tests/status-chat-response-stream.sh
bash scripts/tests/status-chat-action-bar.sh
bash scripts/tests/status-chat-clipboard-policy.sh
bash scripts/tests/status-chat-redaction-policy.sh
bash scripts/tests/status-chat-attachment-policy.sh
bash scripts/tests/status-chat-session-store-policy.sh
bash scripts/tests/status-chat-shortcut-map.sh
bash scripts/tests/status-chat-session-title-policy.sh
bash scripts/tests/status-chat-empty-state.sh
bash scripts/tests/status-chat-status-summary.sh
bash scripts/tests/status-chat-review-packet.sh
bash scripts/tests/status-chat-gap-matrix.shThe checked chat/session fixture reports the chat surface as blocked, the session as inactive, and send controls as disabled. The checked chat model-status fixture adds descriptor, asset, load, runtime, context, and response display rows for the planned model-status panel. Model loading stays disabled and blocked. These fixtures define display and message envelope shapes without storing prompts, responses, transcripts, model paths, generated artifacts, private paths, secrets, or tokens. They reference the model/runtime descriptor, runtime readiness, device/session status, and chat/session fixtures as local data only.
The lifecycle fixture defines the session-management boundary for create, restore, clear, close, and export-summary operations. All operations stay disabled, blocked, inactive, or unavailable until readiness evidence, model load evidence, a reviewed local session store, and explicit export/redaction rules exist. It does not read or write manifests, transcripts, summaries, prompts, responses, or model paths.
The chat empty-state fixture defines display-only placeholder slots and disabled hints for the planned chat surface. It records local empty-state metadata without reading prompts, responses, transcripts, session stores, model paths, runtime logs, artifacts, or dispatching commands.
The chat session-title policy fixture defines placeholder display-name metadata for future local sessions. It renders only a static placeholder label and keeps stored-title reads, generated titles, rename, and persistence disabled or blocked. It does not read session stores, manifests, transcripts, summaries, prompts, responses, stored titles, model paths, private paths, or artifacts.
The chat readiness fixture defines the readiness checklist and recovery action boundary for the standalone chat surface. It records local fixture availability, target model display, model assets, runtime readiness, device session state, chat runtime state, session-store state, and no-provider mode as deterministic data. Recovery actions remain disabled or local data only; the fixture does not read prompts, model assets, paths, manifests, transcripts, summaries, or logs.
The chat audit-event fixture defines a blocked event metadata boundary for future chat UI audit summaries. It records event ids, states, blocked reason ids, redaction policy, and fixture references without prompt, response, transcript, actor, path, model, runtime, raw log, or artifact content. Audit logging and persistence remain disabled and not configured.
The chat error taxonomy fixture groups blocked chat error categories for future banners, status rows, and recovery affordances. It summarizes readiness blockers, model/runtime blockers, session/policy blockers, and local-only/provider policy metadata without reading prompts, responses, transcripts, configs, provider settings, model paths, logs, session stores, or artifacts.
The chat response stream fixture defines the disabled assistant response stream/progress display for the planned chat surface. It records stream phases, response placeholders, token-counter state, and stop-control state without accepting prompts, opening stream transport, generating response chunks, counting tokens, appending transcripts, reading stores, or writing artifacts.
The chat action-bar fixture defines the disabled conversation action controls for the planned chat surface. It records new chat, clear, export, retry, copy, stop, and attach controls without reading session stores, transcripts, message bodies, files, clipboard data, model paths, runtime logs, or artifacts.
The chat clipboard-policy fixture defines the disabled clipboard boundary for the planned chat surface. It records copy, paste, import, export, transcript-copy, message-copy, and clipboard-backed attachment gates without reading or writing clipboard data, prompt text, response text, transcripts, message bodies, files, model paths, runtime logs, or artifacts.
The chat redaction-policy fixture defines the disabled content scanning and redaction boundary for the planned chat surface. It records rule review, prompt, response, transcript, message, attachment, clipboard, audit, PII, secret, and result-persistence gates without loading rules, scanning content, applying redactions, reading stores, touching files, or starting model/runtime paths.
The chat attachment-policy fixture defines the disabled local attachment boundary for the planned chat surface. It records file picker, file metadata read, file content read, upload, import, preview, and persistence gates without reading file names, paths, metadata, contents, clipboard data, transcripts, generated artifacts, model paths, runtime logs, or artifacts.
The chat session-store policy fixture defines the disabled local store boundary for the planned chat surface. It records store configuration, store path, manifest, read, write, delete, retention, and migration gates without reading configuration, paths, manifests, session records, transcripts, titles, prompts, responses, summaries, model paths, runtime logs, or artifacts.
The chat model-selection policy fixture defines the disabled model picker boundary for the planned chat surface. It records a static placeholder model option plus disabled catalog, picker, asset discovery, provider fallback, selection persistence, and load-request gates without reading configuration, catalogs, model paths, assets, prompts, responses, transcripts, runtime logs, or artifacts.
The chat context-policy fixture defines the disabled context-window and tokenization boundary for the planned chat surface. It records disabled context windows, tokenization, token counting, transcript context, summary handling, truncation, context assembly, and runtime handoff gates without reading prompts, transcripts, summaries, tokenizers, model paths, runtime logs, or artifacts.
The chat model-load request fixture defines the disabled local model-load boundary for the planned chat surface. It records descriptor selection, asset path, checksum, runtime preflight, load, warmup, unload, and persistence gates without reading configuration, environment values, model paths, asset paths, weights, tokenizers, checksum manifests, prompts, responses, transcripts, runtime logs, or artifacts.
The chat status-summary, review-packet, and gap-matrix fixtures aggregate the checked chat boundary references without enabling them. The gap matrix records the remaining standalone chat blocker rows for runtime evidence, model assets, prompt input, response generation, session store, transcript/export, privacy, attachments/clipboard, audit, and UI enablement. It does not read prompt, transcript, session-store, model, file, clipboard, runtime, provider, hardware, or artifact data, and it does not close those gaps.
The preview command renders that same contract as a deterministic terminal chat surface sketch with disabled controls, blocked reasons, and an unavailable assistant response. It does not accept or echo prompts.
This surface does not execute a model, generate responses, persist transcripts, touch KV260 hardware, open serial ports, scan networks, call providers, invoke pccx-lab, invoke systemverilog-ide, upload telemetry, read artifacts, or write artifacts. See docs/STANDALONE_CHAT_SESSION_CONTRACT.md.
The legacy launcher scripts from the llm-lite era are preserved
read-only under scripts/legacy/ as historical
reference (see that directory's README for status).
The launcher-shaped pieces in this repository were taken from
hkimw/llm-bottleneck-lab @ 129c524 (2026-04-26). Full details and the
explicit list of what was and was not imported are in
docs/PROVENANCE.md.
- pccxai/pccx — spec / docs / roadmap / release coordination
- pccxai/pccx-FPGA-NPU-LLM-kv260 — v002 LLM RTL / Sail / KV260 / hardware evidence
- pccxai/pccx-LLM-v003 — active LLM RTL track in a separate repository
- pccxai/pccx-vision-v001 — active vision track for related KV260-oriented work
- pccxai/pccx-lab — verification lab + analysis backend
- pccxai/systemverilog-ide — SystemVerilog IDE spin-out
Apache License 2.0 — see LICENSE.
PCCX™ is a mark used by the PCCX project. Korean trademark
applications are pending for PCCX in Classes 09 and 42. Registration
has not been granted; do not use PCCX® until the central trademark
policy is updated. See
pccx/TRADEMARKS.md.