CastleArq
CastleArq is a command-line tool for running local GGUF models with llama.cpp that checks whether a model can run on your machine — and shows its work — before running it.
CastleArq does not replace llama.cpp and does not perform inference itself. llama.cpp is the runtime that loads the model and generates text. CastleArq manages model files, evaluates compatibility, applies admission and orchestrates execution against that runtime.
Version note. The current release candidate is
0.6.2. The annotated tagv0.6.2exists locally; it has not yet been published to GitHub, and the package is not yet published on PyPI. Versions are identified by their annotated tags and CastleArq publications. This source state advances the production source state relative to thev0.5.0baseline: it adds the admitted-model journey (admit/describe/refresh/reconcile/show), a bounded SFT+LoRA training prototype, and GPU offload evidence, while the HTTP contract exposed to Desktop (/healthwithversion,/v1/models,/v1/artifacts) is unchanged. Local GGUF files can still be brought into the model store withimport, and thevalidatecommand remains available for stored artifacts. Requires Python 3.11 or newer.
What problem does it solve?
You have GGUF model files and a local llama.cpp runtime. Pointing llama-cli at
a model gives you either output or a failure, and nothing in between: no answer
to why it failed, and no way to know in advance whether it could have worked at
all on this machine, with this artifact, on this runtime.
CastleArq answers that question first, with evidence, and refuses to run what it cannot justify running.
How it works
runtime -> inspect the llama.cpp runtime that is actually installed
models -> catalog of candidate models for this machine
download -> fetch a GGUF artifact (the model file) and store it locally
list -> locally stored artifacts and their derived state
validate -> validate one stored artifact: filesystem, size, integrity
compatibility -> evaluate five conditions and print the evidence
execute -> refuse or run, according to that evaluation
Why compatibility evidence matters
The compatibility evaluation checks exactly five named conditions between one specific artifact and the detected runtime:
| Condition | Question |
|---|---|
| artifact–model identity | is this file the model that was asked for? |
| artifact format support | does the runtime accept this file format? |
| model architecture support | does the runtime know this architecture? |
| runtime artifact support | does the runtime report supporting this artifact? |
| runtime backend support | does the selected backend support this model? |
Each condition is reported with what was Expected, what was Observed, and
the Evidence recorded for that observation. A condition is PASSED,
FAILED, or UNKNOWN — and UNKNOWN is reported as UNKNOWN. It is never
silently converted into a failure.
When the evaluation does not admit the model, admission — the decision that allows or refuses execution — refuses it, and the run does not happen. There is no flag to force execution past a refusal.
The same admission policy applies to every surface that runs a model: the
execute and run commands, POST /v1/run over HTTP, and opening a chat session.
Throughout this document:
- model — the logical model you want to use;
MODEL_ID— the canonical identifier the CLI accepts. For an artifact brought in withimport, that value is the labelimportreports andlistshows; the model's logical identity can remainUNKNOWN;- artifact — the concrete model file (GGUF) stored locally;
- quantization — the chosen size/precision variant of that file;
- runtime — the llama.cpp installation that loads and runs the model.
Installation
pip install castlearq
From a checkout:
python3 -m venv .venv
. .venv/bin/activate
pip install .
castlearq --version
A previously built wheel or sdist can also be installed, for example
pip install dist/castlearq-0.5.1-py3-none-any.whl. Installation needs neither
PYTHONPATH nor the source tree afterwards, and the package contains no models.
Requirements
CastleArq is for developers already working with local AI models on Linux who have, or can obtain, llama.cpp, and who use GGUF files. It is not a consumer application.
You need:
- Linux as the exercised baseline.
- Python 3.11 or newer.
- llama.cpp provided externally. CastleArq does not install, build or vendor
it, and does not ship models, drivers, Vulkan, CUDA or ROCm. The official
llamalauncher must be on yourPATH. - Disk space for model files. A single 7B Q4_K_M artifact is roughly 4.4 GiB.
The normal flow does not require sudo and does not modify your system.
Runtime setup
CastleArq requires the llama executable; it does not install or build
llama.cpp. First check that the launcher is on your PATH:
command -v llama
Then inspect the state CastleArq can observe:
castlearq runtime
The output shows the runtime, launcher, resolved executable, version, build, availability and detected capabilities.
| State | Meaning | Action |
|---|---|---|
AVAILABLE |
runtime usable | continue with models |
NOT_FOUND |
llama is not available |
provide llama.cpp externally |
FOUND_UNUSABLE |
a path was found but is not usable | check path, permissions and file type |
PROBE_ERROR |
validation could not complete | read reason, check the llama.cpp install/build |
UNKNOWN |
not enough evidence | read reason and re-run the diagnostic |
llama is the official launcher. llama-cli, llama-server and llama.app do
not automatically stand in for llama in CastleArq 0.5.x.
Quick start
There are two routes, depending on whether you already have a model file. Both end in the same commands; they differ only in where the artifact comes from.
Route A: you already have a local GGUF
# 1. Check the runtime CastleArq will drive
castlearq runtime
# 2. Import the file you already have; it reports the label to use next
castlearq import ./my-model.gguf
# 3. See what is stored and in what state
castlearq list
# 4. Validate that stored artifact: filesystem, size, integrity
castlearq validate <LABEL>
# 5. Check it can run here, and see the evidence
castlearq compatibility <LABEL>
# 6. Run a prompt
castlearq execute <LABEL> "Reply with exactly: OK"
import runs nothing: it copies the file into the model store and prints the
label you use as <LABEL> in the commands after it. The label is the
operational identifier of the artifact, not a statement about which model the
file is; a local file carries no evidence of that, so its logical identity may
stay UNKNOWN.
Route B: you need to get a model from the catalog
# 1. Check the runtime CastleArq will drive
castlearq runtime
# 2. See which models are candidates for this machine
castlearq models
# 3. Fetch one explicitly (multi-GB download)
castlearq download qwen2.5-coder-7b-instruct
# 4. See what is stored and in what state
castlearq list
# 5. Validate that stored artifact: filesystem, size, integrity
castlearq validate qwen2.5-coder-7b-instruct
# 6. Check it can run here, and see the evidence
castlearq compatibility qwen2.5-coder-7b-instruct
# 7. Run a prompt
castlearq execute qwen2.5-coder-7b-instruct "Reply with exactly: OK"
From here on, MODEL_ID means whatever identifier list shows for the
artifact you want to work with: a catalog model id after download, or the
label after import. For an imported artifact, that label is only the
operational handle — the model's logical identity can remain UNKNOWN.
Route C: discover a GGUF repository and acquire it
# 1. Search remote GGUF repositories (read-only discovery metadata)
castlearq search "qwen3 8b gguf"
# 2. Inspect one repository: variants, quantizations, sizes, SHA-256, revision
castlearq inspect someowner/somemodel-gguf
# 3. Acquire one explicit artifact of that repository (multi-GB download).
# The repository is the locator; --quantization / --filename make the
# selection explicit. With several candidate files, a selector is required.
castlearq download someowner/somemodel-gguf --quantization Q4_K_M
# 4..7 continue exactly as in Route B with the printed model id
castlearq list
castlearq validate <MODEL_ID>
castlearq compatibility <MODEL_ID>
castlearq execute <MODEL_ID> "Reply with exactly: OK"
download <owner/name> needs no manual catalog edit: the logical model id is
resolved through CastleArq's admitted identity authority (curated identity
first, a deterministic derived identity otherwise) and explicitly registered
in the existing identity-admission and acquisition-binding registries, both
explicit and idempotent, and neither one records a partial state, before the
unchanged download, verification and storage flow runs. The command prints
both the repository and the resolved model id. Two different repositories can
never share a logical id. Acquiring a model does not admit it for execution:
describe/compatibility admission still applies before execute.
list shows each stored artifact and its derived state; validate re-checks one
artifact on demand and reports what it can and cannot prove. Both are read-only
and neither changes what may run. compatibility is a normal step in this flow,
not optional troubleshooting: it is the same evaluation execute uses to decide
whether to run.
Check compatibility before running anything
castlearq compatibility qwen2.5-coder-7b-instruct
This command is read-only: it runs no inference, starts no runtime, downloads nothing, does not modify the model store and creates no persistent state. It prints the verdict and, for each condition, its status, what was expected, what was observed, and the evidence already recorded.
Abridged output (the real command prints all five conditions):
Compatibility evaluation
Model: qwen2.5-coder-7b-instruct
Artifact: qwen2.5-coder-7b-instruct-q4_k_m.gguf (Q4_K_M)
Runtime: llama.cpp CLI
Verdict: INSUFFICIENT_EVIDENCE
Checks:
artifact format support: PASSED
Expected: 'gguf'
Observed: 'gguf'
Evidence (observed): artifact.format = 'gguf'
runtime artifact support: UNKNOWN
Evidence (observed): runtime.supports_artifact = None
Exit codes: 0 when the evaluation admits execution, 1 when it does not,
2 on incorrect usage.
The criterion is the same one execute uses: this command reports, it does not
change policy.
INSUFFICIENT_EVIDENCE does not mean incompatible
INSUFFICIENT_EVIDENCE is the overall verdict when not every condition has
sufficient evidence. It does not assert that the model is incompatible; it
asserts that CastleArq does not know enough to assert either way.
The actual behaviour, which compatibility does not alter:
- if any condition is
FAILED, a failure is demonstrated and execution is refused; - if the only conditions without evidence are the ones that do not depend on a
prior evaluation, CastleArq treats them as non-blocking and admits execution.
That is why you can see
Verdict: INSUFFICIENT_EVIDENCEtogether with exit code0: the verdict is honest about what it does not know, and the admission is equally honest about what it does.
UNKNOWN never becomes FAILED, and INSUFFICIENT_EVIDENCE never
automatically becomes "not compatible". To know whether a given model is
blocked, the admission result decides — not the name of the verdict.
First execution
castlearq execute qwen2.5-coder-7b-instruct "Reply with exactly: OK"
A successful prompt prints the model's response on stdout. The runtime may print loading and generation messages, and CastleArq may print warnings on stderr. A warning does not by itself mean the execution failed.
- exit code
0: success; - exit code
1: operational failure; - exit code
2: incorrect arguments or usage.
Exact output varies with the model and prompt. A successful result includes
generated output and code 0.
execute versus run
The legacy run interface also exists and reaches the same llama.cpp runtime:
castlearq run qwen2.5-coder-7b-instruct --prompt "Reply with exactly: OK"
They differ in interface and in how a refusal is reported:
execute |
run |
|
|---|---|---|
| Prompt | positional | --prompt |
| Strict evaluation before running | yes | yes |
| Admission | yes | yes |
| Runtime | llama.cpp | llama.cpp |
execute evaluates compatibility strictly and refuses to run when admission
denies it, showing the conditions, reasons and evidence. run is the legacy
interface: it reaches the same runtime through the legacy preparation path,
performs strict evaluation and applies the same admission policy, but reports
a refusal as a plain run error instead of the full evaluation report.
Use execute. run is kept for compatibility.
A real run
The transcript below was captured from a real execution on Linux with llama.cpp 0.4.0-dev and a real 4.4 GiB Q4_K_M artifact, using the commands above. Nothing in it is hand-written.
castlearq compatibility qwen2.5-coder-7b-instruct:
Compatibility evaluation
Model: qwen2.5-coder-7b-instruct
Artifact: qwen2.5-coder-7b-instruct-q4_k_m.gguf (Q4_K_M)
Runtime: llama.cpp CLI
Verdict: INSUFFICIENT_EVIDENCE
Checks:
artifact-model identity: PASSED
Expected: 'qwen2.5-coder-7b-instruct'
Observed: 'qwen2.5-coder-7b-instruct'
Evidence (observed): model.identity.model_id = 'qwen2.5-coder-7b-instruct'
Evidence (observed): artifact.identifier = 'qwen2.5-coder-7b-instruct'
artifact format support: PASSED
Expected: 'gguf'
Observed: 'gguf'
Evidence (observed): artifact.format = 'gguf'
Evidence (observed): runtime.supported_formats = 'gguf'
Evidence (observed): runtime.unsupported_formats = None
model architecture support: PASSED
Expected: 'qwen2'
Observed: 'qwen2'
Evidence (observed): model.architecture = 'qwen2'
Evidence (observed): runtime.architecture_knowledge = 'explicit lists'
runtime artifact support: UNKNOWN
Evidence (observed): runtime.name = 'llama.cpp'
Evidence (observed): runtime.supports_artifact = None
runtime backend support: UNKNOWN
Evidence (observed): context.backend = None
Evidence (observed): runtime.supported_backends = 'cpu, cuda, hip'
Evidence (observed): runtime.unsupported_backends = None
Read it honestly: three conditions passed with evidence; two are UNKNOWN
because the runtime reports nothing for them. CastleArq reports
INSUFFICIENT_EVIDENCE rather than inventing a pass, and admission still allows
the run because those two conditions are not blocking.
castlearq execute qwen2.5-coder-7b-instruct "Reply with exactly: CASTLEARQ_OK"
(llama.cpp's own loading banner elided, indicated below):
Warning: Model memory is an estimate.
[... llama.cpp loading banner and runtime command help elided ...]
> Reply with exactly: CASTLEARQ_OK
CASTLEARQ_OK
[ Prompt: 258.1 t/s | Generation: 38.0 t/s ]
The command exited 0 and the model produced exactly the requested token
sequence. The Warning: line comes from CastleArq's own memory estimation,
which is separate from the five-condition verdict — see
What the verdict does not cover.
Model management
Artifacts reach CastleArq from one of two sources, and both lead to the same place:
catalog: models -> download MODEL_ID -> list -> execute
local file: import PATH -> list -> execute
models shows the catalog and its per-machine recommendations; it is about
candidates, not about what you have. list shows the managed artifacts
available for use, whether they arrived through download or through import.
An imported GGUF therefore does not appear in models: models is the
catalog, list is your store, and CastleArq keeps them apart.
For a downloaded artifact, the model id is the identifier later commands take.
For an imported one, that identifier is the label reported by import and
shown by list. The label is an operational handle, not a claim about the
model's logical identity, which a local file provides no evidence for and which
may stay UNKNOWN.
The catalog cycle is:
models -> choose MODEL_ID -> download -> list -> execute
download acquires the artifact explicitly, and repeating execute does not
download the model again.
models prints, per candidate, the recommended quantization, an estimated
memory figure, the selected runtime and backend, the reason, and any warning.
Those recommendations come from CastleArq's memory estimation and hardware
assessment, which are not the five-condition compatibility verdict.
To pick a specific variant:
castlearq download MODEL_ID --quantization QUANTIZATION
castlearq download MODEL_ID --filename MODEL_FILE.gguf
A download requires network access to the remote source, and CastleArq does not assume a remote model stays available forever.
Verify local artifacts
castlearq list
list shows locally stored artifacts with their model id, filename,
quantization, size and verification state. Artifacts are reused by later runs.
An artifact brought in with import appears here under its label, which is the
value to pass to the commands below in its place.
To validate one stored artifact explicitly, use validate:
castlearq validate MODEL_ID
validate reports three independent dimensions, each PASSED, FAILED
or UNKNOWN:
| Dimension | What it proves |
|---|---|
safety |
the artifact exists, is a regular non-symlink file at its declared path, is complete, and can be opened without following a link |
size |
the artifact matches size_bytes when the manifest declares one |
integrity |
the artifact matches the declared SHA-256 when the manifest declares one |
An artifact without a declared SHA-256 reports integrity: UNKNOWN:
qwen2.5-coder-7b-instruct / qwen2.5-coder-7b-instruct-Q4_K_M.gguf
size: UNKNOWN
no size is declared in the manifest;
integrity: UNKNOWN
no SHA-256 is declared in the manifest;
no content comparison was performed
Artifact state: DOWNLOADED
UNKNOWN means insufficient evidence to decide. It is never reported as a
pass and never as a failure: CastleArq did not compare the contents against
anything, and it says so. An artifact with no declared SHA-256 is still
executable, exactly as before.
validate is a read-only inspection: it changes nothing, never modifies or
re-derives the artifact, and adds --quantization / --filename to select
which artifact to validate.
The model store is independent of the checkout. CastleArq selects it from the first source you declare, in this order of authority:
| Declared source | Store used |
|---|---|
castlearq --model-store PATH ... |
PATH, for that one invocation |
[models] directory in config.toml |
the configured directory |
XDG_DATA_HOME |
$XDG_DATA_HOME/castlearq/models |
| nothing declared | ~/.local/share/castlearq/models |
| nothing declared, and no CastleArq store exists yet | ~/.local/share/localai-hub/models (legacy compatibility) |
Explicit configuration always wins, and directory existence does not decide the winner: a store you select is used even when its directory does not exist yet, is empty, or sits next to another store. Resolving the path does not create anything; the directory appears only when an operation actually writes to it.
To see which store is in use:
castlearq store
Store
Path: /home/you/.local/share/castlearq/models
Source: default
Exists: no
Legacy detected: yes
Legacy used: no
Source names the source that won: cli, config, xdg, default or
legacy-compatibility. store is read-only.
The user configuration file is $XDG_CONFIG_HOME/castlearq/config.toml,
falling back to ~/.config/castlearq/config.toml, and it selects the store with:
[models]
directory = "~/.local/share/castlearq/models"
The config/config.toml in the repository is a sample of that schema, not a
file CastleArq reads at runtime.
~/.local/share/localai-hub/models is the path used by the predecessor local
installation. It is a compatibility fallback and nothing more: it is selected
only when you declared no store at all, the CastleArq store does not exist, and
the legacy store does. When that happens, CastleArq says so on stderr, and it
uses the artifacts where they already are. CastleArq does not migrate, move,
copy or delete models, so you never need to edit manifests or relocate models
by hand.
--model-store PATH selects the store for one invocation only:
castlearq --model-store /path/to/store list
How this differs from using llama.cpp directly
CastleArq drives llama.cpp; it does not replace it and does not perform inference itself. llama.cpp is the runtime that loads the model and generates text. CastleArq manages artifacts, evaluates compatibility, applies admission and orchestrates execution against that runtime.
The difference is what happens before the runtime is invoked. Pointing
llama-cli at a model starts generation immediately. CastleArq first reports
which of five conditions it could verify, what it expected, what it observed, and
what evidence it has — and then refuses to start generation when the evaluation
does not admit the model.
CastleArq makes no claim to be better, faster, safer or more reliable than any other tool, and makes no comparison with other local-AI runtimes. What it claims is narrower and checkable: it evaluates those five conditions, shows the evidence, and does not run what it cannot justify running.
What the verdict does not cover
The compatibility verdict is evidence about five named conditions between one artifact and one detected runtime. Reading it as anything broader would be a misreading, so this is stated explicitly.
The verdict does not establish:
- memory sufficiency. It is not a RAM/VRAM capacity check. CastleArq's memory
estimation is a separate, approximate heuristic reported separately (as a
Warning:line), and it is labelled as an estimate. - output quality, model quality or semantic correctness of anything generated.
- model behaviour — the verdict says nothing about what a model will say.
- security or safety. CastleArq is not a sandbox and provides no isolation or hardening. A model that passes admission is not thereby safe to run.
- performance. No speed, throughput or latency claim is made or measured.
- absence of crashes or runtime failures. Admission is a decision made
before generation; the runtime may still fail afterwards, and
executereports that as an operational failure.
Admission is also not a permission system. CastleArq has no identities, roles or
accounts; the HTTP 403 status it returns for a refusal means "the evaluation
did not admit this", not "you are not authorised".
A pass therefore means: these five conditions were checked and none of them demonstrably failed. It does not mean this model will run well.
HTTP API
castlearq serve
serve is not a status-only endpoint. It starts an HTTP API and performs
real inference:
GET /health -> liveness and version (this one is read-only)
GET /v1/models -> catalog
GET /v1/artifacts -> local artifacts
POST /v1/run -> RUNS a prompt (real inference)
POST /v1/chat/sessions -> opens a live chat session
POST /v1/chat/sessions/{id}/turns -> sends a prompt to that session
GET /v1/chat/sessions/{id} -> session status
DELETE /v1/chat/sessions/{id} -> closes the session
The server binds loopback (127.0.0.1) by default and rejects non-loopback
hosts. That is a property of network exposure.
Execution policy is a separate matter, and the two should not be confused:
HTTP execution applies the same strict evaluation admission as execute.
Admission is a property of execution, not of the command or the transport. A
model that strict evaluation does not admit is not executed over HTTP.
| Status | Meaning |
|---|---|
200 |
success (model_id, output, exit_code, warnings) |
400 |
malformed request |
404 |
model not in the local catalog |
409 |
an execution is already running (global lock, no queue) |
403 |
admission denied by the compatibility evaluation |
422 |
preparation failure (invalid artifact, no executable target) |
500 |
evaluation error — the evaluation failed; this is not a denial |
503 |
runtime unavailable, or the runner failed |
A refusal returns only the admission summary:
{
"error": "execution refused by compatibility admission",
"admission": { "status": "evaluated", "verdict": "incompatible" }
}
Checks, diagnostics, evidence, local paths and exception details are never
returned. For the full evaluation use castlearq compatibility MODEL_ID.
A 500 means the evaluation raised (for example an unreadable GGUF), not
that it denied: that is why no verdict is shown. Execution is refused in both
cases.
POST /v1/chat/sessions opens a live session, so it is subject to the same
admission and the same global lock.
Limitations
Current, factual limitations of this release:
- Linux is the exercised baseline. The code inspects other platforms, but only Linux has been run end to end.
- llama.cpp is an external dependency. CastleArq does not install, build or
vendor it. Without a working
llamalauncher, nothing can run. - Models are large. A 7B Q4_K_M artifact is roughly 4.4 GiB; downloads need network access, time and disk.
- The catalog currently contains 3 models.
castlearq modelsrecommends from that small catalog, so treat it as a starting point rather than a broad index. - CastleArq does not perform inference itself. It orchestrates llama.cpp.
- Memory figures are estimates. They are derived from parameter count and quantization, not measured, and are reported with a warning.
- No quantization, scheduling, clustering or multi-GPU features. The backend is selected for the detected hardware; there is no workload scheduler.
- One execution at a time. The HTTP surface serialises execution behind a
single lock and answers
409rather than queueing. - Blocked revision mismatch. A requested model revision that does not match the revision stored on disk is refused, and the already stored artifact is preserved; the download fails with a clear blocked error rather than replacing the existing file. Use another revision or another artifact instead.
- No auth, TLS or persistence.
serveis loopback-only by design; chat sessions live in memory only.
Troubleshooting
llama not found
command -v llama
castlearq runtime
If you see NOT_FOUND, provide llama.cpp externally and re-run
castlearq runtime. CastleArq will not install it for you.
Runtime FOUND_UNUSABLE
CastleArq found a path it cannot use as a launcher. Check the reported path, permissions, file type, and the runtime install/build.
Runtime PROBE_ERROR
CastleArq found the launcher but could not validate its interface. Read Reason,
check the llama.cpp install/build and re-run the diagnostic. This does not by
itself demonstrate a universal incompatibility.
Artifact missing
castlearq list
castlearq models
castlearq download MODEL_ID
Artifact invalid or incomplete
Check castlearq list. Do not try to run an artifact whose state is not usable.
If it is not downloaded, use download again; the existing command keeps its
validation semantics and will not publish an artifact that fails its checks.
Incompatibility
Execution can be blocked by model, artifact, memory, quantization or
capabilities. Check castlearq models, castlearq list and castlearq runtime
before choosing a different artifact or prompt.
Backend unavailable
castlearq runtime
Do not assume a backend advertised by the hardware is available in the runtime. Use a backend compatible with what was detected.
Admission denied
CastleArq blocked execution according to the current evaluation. The output includes the full evaluation that produced the block: the verdict, each condition with its status, what was expected, what was observed, and the evidence. There is no instruction to force execution.
castlearq compatibility MODEL_ID
shows that same evaluation without running anything, and is the recommended way to understand the reason before trying again.
A UNKNOWN condition is not a failure: it means there is not enough evidence,
and it is not treated as an incompatibility.
Compatibility evaluation error
If the evaluation could not complete, CastleArq says so explicitly:
Compatibility evaluation error: GGUFReadError: ...
This is not a policy denial: it means the evaluation failed. The
reported cause (for example a corrupt or unreadable GGUF) is the real problem,
and execution remains blocked. Check the artifact with castlearq list and
re-download it if its state is not usable.
Execution failure
Check the error and the execution's stderr, and compare:
castlearq runtime
castlearq list
A process failure does not automatically mean the runtime or the artifact is missing.
Download failure
Check connectivity, remote source availability, the MODEL_ID, the
quantization/filename selection, and re-run:
castlearq download MODEL_ID
CLI usage error
castlearq --help
Exit code 2 indicates incorrect usage, such as missing arguments or invalid
flags.
Command reference
| Command | What it does |
|---|---|
models |
Catalog with recommendations scored against the detected hardware |
download MODEL_ID |
Explicitly fetch a GGUF artifact |
import PATH |
Imports a local GGUF file into the model store |
list |
Locally stored artifacts and their state |
store |
Reports the model store in use: path, source, existence, legacy status |
validate MODEL_ID |
Validates one stored artifact: filesystem, size, integrity |
compatibility MODEL_ID |
Compatibility evaluation without running anything |
execute MODEL_ID "PROMPT" |
Run a prompt (recommended; strict evaluation applies) |
train --base-model DIR --dataset DATA.jsonl --output-dir ADAPTER_DIR |
Train a bounded LoRA adapter from a local Transformers checkpoint (prototype; output is not an executable model artifact) |
run MODEL_ID --prompt "T" |
Legacy interface; strict evaluation and admission apply, refusal shown as a run error |
chat MODEL_ID |
Interactive chat session with the model |
serve |
HTTP API on 127.0.0.1 that executes models (see above) |
runtime |
Resolved llama.cpp runtime state |
detect |
System, CPU, memory and GPU |
diagnose |
GPU software diagnosis (Vulkan/CUDA/ROCm) |
verify |
Re-checks the GPU diagnosis, not artifact integrity |
source huggingface REPO |
Inspects a remote source |
search QUERY |
Queries the configured model discovery/catalog capability |
inspect REPO |
Inspects one remote repository's declared variants and artifacts |
plan REPO FILENAME |
Inspects one specific remote artifact |
admitted --op admit --source SRC --repo OWNER/NAME |
Explicitly admit one logical model identity (forward-only) |
admitted --op describe --model-id ID --source SRC --repo OWNER/NAME |
Create the durable Executable Model Description (forward-only) |
admitted --op bind --model-id ID --source SRC --repo OWNER/NAME |
Create the explicit acquisition binding (never automatic) |
admitted --op show --model-id ID |
Read-only admitted-model description and provenance |
admitted --op observe --model-id ID --claim CLAIM --value VALUE --context-note NOTE |
Explicitly record one durable local observation |
admitted --op refresh --model-id ID |
Explicit on-demand refresh (stages pending only) |
admitted --op reconcile --model-id ID --claim CLAIM --decision DECISION --basis BASIS |
Explicit claim-scoped reconciliation |
| `convert MODEL --quantization fp16 | int8 |
import-openvino <source-dir> <model-id> [--precision PRECISION] [--revision REVISION] |
Import a local OpenVINO IR directory into the managed model store. Validates structure, copies files and registers manifest. Does not run inference. |
ov-run <model-id> <prompt> [--backend BACKEND] [--limit LIMIT] |
Run OpenVINO inference with a prompt. Device backend default: CPU. Tokens limit default: 8. |
import PATH copies a local GGUF file into the model store. It reports the
artifact's content ID (the SHA-256 CastleArq computed, which is the file's
physical identity) separately from its logical identity, which stays
UNKNOWN: a local file carries no evidence of which model it is, of who
published it, or of its integrity declaration. Only general.architecture is
read, as physical GGUF evidence. Use --label NAME to choose the storage and
presentation label; the store sanitizes it, and it is never used as a model id.
Importing does not run anything: run the artifact later with execute.
detect, runtime, models, list, store, compatibility, source,
search, inspect and plan are read-only: they change nothing.
search QUERY queries the configured model discovery/catalog capability and
prints the remote candidates it returned, together with the next_cursor the
provider produced when more results exist:
castlearq search "qwen coder"
castlearq search "qwen coder" --limit 50
castlearq search "qwen coder" --cursor "<next_cursor from the previous call>"
castlearq search "qwen coder" --json
It reports candidates as the discovery provider declared them. It does not
rank them, recommend one, score them against your hardware or select a
quantization: choosing the artifact is a separate decision made by download,
compatibility and execute. --limit is forwarded unchanged to the provider,
which owns the bound. --cursor takes the opaque next_cursor from a previous
call and forwards it unchanged; CastleArq never decodes or interprets it, and
it never paginates automatically. Results are remote, unverified metadata:
they say what a source declares, not what your machine can run.
verify checks environment remediation after a diagnose. It is not an
artifact integrity check; for that, use validate, which reports what can be
proven about one stored artifact and which evidence is missing. list shows
the derived state of every stored artifact.
Eleven of these commands also accept --json for machine-readable output; see
Machine-readable CLI output.
Machine-readable CLI output
Eleven commands also accept --json, which prints exactly one JSON document on
stdout instead of the human report:
compatibility validate list store import
models runtime detect plan search inspect
Everything else is unchanged: the exit codes are the same in both modes,
warnings and notices (such as the legacy-store notice) go to stderr, and
argparse errors stay plain stderr + exit 2 with no JSON at all. The
document is always this envelope:
{
"schema": "castlearq.cli",
"schema_version": 1,
"command": "compatibility",
"exit_code": 0,
"payload": {},
"warnings": [],
"error": null
}
exit_code is the code the process really returns, warnings is a list of
strings, and error is either null or a {"kind", "message"} object. A
--json run and a human run of the same command always agree on the exit code.
Two rules keep this output unambiguous for scripts:
- UNKNOWN is explicit, never a string. A property that is relevant but was
not observed is reported as
{"value": null, "status": "unknown", "reason": "not_observed"}(other ratified reasons areno_checksum_declared,no_size_declared,no_catalog_evidenceandnot_declared). UNKNOWN is neverFAILED, never a barenullthat hides its status, and never the literal"Unknown". - Identity and integrity stay separate.
importreportscontent_id, the SHA-256 CastleArq computed for the bytes it copied. That is the file's physical identity, not an integrity declaration: the imported artifact declares no checksum, so itsintegritystays UNKNOWN (reason: "not_declared"). Itslogical_identitystays UNKNOWN too (reason: "no_catalog_evidence") — the label is addressing and presentation, never a model id.
In compatibility --json the strict evaluation and the admission projection
are two separate objects (payload.evaluation and payload.admission). An
evaluation that is INSUFFICIENT_EVIDENCE while admission still permits
execution is observable as exactly that, and is reported truthfully in both
modes. An operational failure is error.kind = "evaluation_error" with exit
1; an admission denial is not an error, it stays in the payload.
models reports its catalog assessment under legacy_compatibility, which is
the historical, hardware-scored domain and not the strict evaluation domain.
plan reports the download planner's own statuses (ready,
already_downloaded, blocked, unknown); an UNKNOWN plan is a plan status,
not an error.
The commands diagnose, verify, execute, run, download, source,
train and admitted do not accept --json and reject it with exit 2;
serve and chat are outside this contract by nature.
Chat
castlearq chat qwen2.5-coder-7b-instruct
Opens an interactive session with the model already loaded. During the session
it responds to /regen (regenerate), /clear (clear history), /read <file>
and /glob <pattern>; /exit or Ctrl+C closes it.
chat uses the same runtime and the same local artifact as execute, so a
model downloaded with download is reused without downloading it again. To
check compatibility before starting a conversation, run
castlearq compatibility MODEL_ID.
Opening a chat session starts a model, so it is subject to the same admission as
execute.
Architecture
Technical architecture, contracts and decision records are in
docs/, covering runtime discovery, capability, compatibility,
admission, the model store and execution. It is optional material for the user
flow above.
Development
From a checkout, the supported mechanism is:
python3 -m castlearq.main --help
python3 -m castlearq.main --version
Tests run with pytest:
python3 -m pytest
pytest is not a runtime dependency. It is declared as a pinned development extra, which is what CI installs:
python3 -m pip install ".[dev]"
The same command runs on every push to main and on every pull request, across
Python 3.11, 3.12 and 3.13. A red run is a validation failure: it is
diagnosed, not worked around. The suite needs no llama.cpp, no models and no
GPU; tests that open a socket do so on 127.0.0.1 only. Working from a
checkout is not required to use the installed package.
CastleArq is developed by Nicolás Bruna.
License
Licensed under the Apache License, Version 2.0. See LICENSE for
the full text.
Metadata
Release files for castlearq 0.6.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| castlearq-0.6.2.tar.gz | 673.1 kB | With provenance | Details for castlearq-0.6.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| castlearq-0.6.2-py3-none-any.whl | Python 3 | none | any | Details for castlearq-0.6.2-py3-none-any.whl |
Total release size: 1.0 MB
Release files / castlearq-0.6.2.tar.gz
| Download URL | castlearq-0.6.2.tar.gz |
|---|---|
| Size | 673.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2bc2775b83a27d72a662210d02edf45ef123b5312bc25007bbd1029cc4626d7a
|
|
BLAKE2b-256 checksum How to use checksums |
74730d231c9c99835b4af89fa233374356d544bf537b24acb8b8e3c5228d3ebf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logRelease files / castlearq-0.6.2-py3-none-any.whl
| Download URL | castlearq-0.6.2-py3-none-any.whl |
|---|---|
| Size | 354.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5fc08c4a14afe0a78dda8ac61e91e7f10a484027d57ec16c29e58decd1456a97
|
|
BLAKE2b-256 checksum How to use checksums |
3a44bb7ba1c1fbcdd2483bdf33534e2cae8a1656bb37b07e58aa2c282a3732af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logSecurity for castlearq 0.6.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for castlearq-0.6.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.