Crate ferrox_api 

The wire contract between ferrox-server and everything that talks to it: the web UI served at /, the desktop shell that spawns the server as a child process, ferrox chat, and any third-party client.

Why a crate instead of literals at both ends: the UI is deliberately “just another API client” (see docs/plans/ferrox-ui.md) – it calls the same public endpoints an IDE would, so the public contract cannot rot without the UI breaking first. That only holds if there is exactly one definition of each path and each payload shape. A hand-copied "/v1/chat/completions" in a frontend is a contract that drifts silently; a pub const that both sides import is one that cannot.

Scope rule: this crate owns ferrox-specific additions and control surfaces (health/capabilities, the process-ready handshake, usage timings, task progress). The OpenAI-compatible request/response bodies stay in ferrox-server where they are validated – mirroring someone else’s schema here would create a second place for it to be wrong.

Deliberately dependency-light (serde only): a desktop shell, a CLI and a WASM frontend may all link it.

Re-exports

pub use admin::CancelResponse;

pub use admin::DownloadRequest;

pub use admin::LoadModelRequest;

pub use admin::ModelEntry;

pub use admin::ModelState;

pub use admin::ModelsResponse;

pub use admin::ProgressState;

pub use admin::RecentRequest;

pub use admin::StatsResponse;

pub use admin::TaskAccepted;

pub use admin::TaskKind;

pub use admin::TaskProgress;

pub use admin::TaskStatus;

pub use admin::TaskView;

pub use admin::TasksResponse;

pub use admin::UnloadResponse;

pub use cancel::CancelGenerationRequest;

pub use cancel::CancelGenerationResponse;

pub use health::Capability;

pub use health::HealthResponse;

pub use health::HealthState;

pub use lifecycle::ServerReady;

pub use lifecycle::READY_EVENT;

pub use progress::RateEstimator;

pub use progress::RateReport;

pub use request_id::next_request_id;

pub use usage::CompletionTokensDetails;

pub use usage::Usage;

Modules

admin

Wire shapes for the /admin control surface: the model inventory, the one long-running-task contract, and the server’s own counters.

cancel

Wire shapes for POST /v1/cancel.

health

GET /health as a capability handshake rather than a boolean.

lifecycle

The process-ready handshake: one machine-readable line on the server’s stdout, naming the address it actually bound and the pid that owns it.

progress

Rolling-window transfer rate and ETA for long-running jobs (downloads, conversions, model loads).

request_id

Server-assigned request ids.

routes

Every path ferrox-server serves, named once.

usage

OpenAI-convention token accounting plus llama.cpp-style timings.