Skip to content

vox-populi API Reference (generated)

Crate: vox-populi · Version: 0.6.0 · Target: Library (lib.rs)

Vox Populi: multi-node worker registry, HTTP control plane, and Mens native ML (Burn / Candle QLoRA).

Vox populi — node registry, optional HTTP control plane, and (feature mens) native ML.

CPU-first: each [NodeRecord] carries vox_orchestrator::TaskCapabilityHints. See docs/src/architecture/populi-ssot.md for environment variables. The mens module holds Burn/Candle QLoRA training (--features mens …).

FeatureDefault / Enables
default—
gamifydep:vox-gamify
hw-probe-live-test—
inferencemens-candle-qlora
mensdep:anyhow, dep:serde_yaml, dep:ctrlc, dep:chrono, dep:dirs, dep:sysinfo, dep:rand, dep:vox-tensor, dep:vox-corpus, dep:vox-db, dep:vox-bounded-fs, dep:vox-hf-layout, dep:objc2-metal, dep:vox-package, dep:vox-orchestrator-queue, dep:sha3
mens-candle-qloramens, dep:candle-core, dep:candle-nn, dep:safetensors, dep:tokenizers, dep:qlora-rs, dep:reqwest, dep:vox-quantize
mens-candle-qlora-cudamens-candle-qlora, candle-core/cuda, candle-nn/cuda
mens-candle-qlora-metalmens-candle-qlora, candle-core/metal, candle-nn/metal
mens-cloudmens, mens-hf-hub, dep:reqwest, dep:vox-http-client, vox-db/host-integration
mens-hf-hubmens, dep:hf-hub, tokio/rt-multi-thread, dep:askama, dep:vox-eval, dep:tempfile
mens-trainmens, mens-candle-qlora, mens-hf-hub, dep:vox-eval, dep:vox-plugin-host
mesh-discovery-publishdep:vox-publisher
nvml-gpu-probe—
tlsdep:rustls, dep:rustls-pemfile, dep:tokio-rustls
transportdep:axum, dep:reqwest, dep:reqwest-middleware, dep:vox-http-client, vox-http-client/middleware, dep:tower-http, dep:subtle, dep:vox-bounded-fs, dep:jsonwebtoken, dep:ed25519-dalek, dep:blake3, dep:data-encoding, dep:base64, dep:dashmap, dep:vox-db, dep:turso
DependencyKind
vox-bounded-fsNormal
vox-configNormal
vox-corpusNormal
vox-cryptoNormal
vox-dbNormal
vox-evalNormal
vox-foundationNormal
vox-gamifyNormal
vox-hf-layoutNormal
vox-http-clientNormal
vox-identityNormal
vox-mesh-typesNormal
vox-orchestrator-queueNormal
vox-packageNormal
vox-plugin-hostNormal
vox-populi-typesNormal
vox-publisherNormal
vox-quantizeNormal
vox-repositoryNormal
vox-secretsNormal
vox-tensorNormal
ModuleDescription
mens—
http_client—
http_lifecycle—
tls—
transport—
pairingGitHub-attested pairing and revocation (P5-T2).
quotaPer-key token-bucket quota + reputation EMA (P5-T3).
distributed_training—
inferenceMENS Mn-T2 inference backends (Candle CPU/CUDA/Metal, llama.cpp RPC, Ollama).
StructDescription
PopuliEnvParsed populi-related environment (best-effort).
FunctionDescription
populi_enabled_from_envWhether populi hooks are enabled (VOX_MESH_ENABLED=1 or true).
populi_env_resolvedMerge Vox.toml [populi] into env-derived values when the corresponding env is unset. Precedence: environment always wins over TOML for each field.
populi_advertise_gpu_effectiveWhether VOX_MESH_ADVERTISE_GPU is set, or [populi].advertise_gpu = true when env is unset.
normalize_http_control_baseNormalize a control-plane URL for use as an HTTP client base (join / heartbeat / list). Returns [None] for empty strings, invalid trim, or bind-all hosts (0.0.0.0, ::) where the value is meant for vox populi serve --bind, not outbound requests.
populi_envRead populi env vars (does not mutate process state).
populi_scope_id_from_envVOX_MESH_SCOPE_ID when set and non-empty after trim.
wall_clock_unix_msCurrent Unix time in milliseconds (for federation timestamps and tests).
resolve_vox_toml_best_effortResolve Vox.toml path next to the current working directory (nearest manifest root).
node_record_for_current_processBuild a [NodeRecord] for this process using orchestrator host probe + populi env labels.
publish_local_registry_best_effortRegister this process into the default local registry file (no-op if VOX_MESH_ENABLED is off).
populi_registration_record_for_process[NodeRecord] for this process — same id and listen_addr as [publish_local_registry_best_effort].
local_registry_pathResolved on-disk registry path (honours VOX_MESH_REGISTRY_PATH).
current_target_tripleReturns the current target triple (Wave 4 best-effort).
Dependency Topology, diagram 121 nodes, 20 edges: vox-populi → vox-bounded-fs; vox-populi → vox-config; vox-populi → vox-corpus; vox-populi → vox-crypto; vox-populi → vox-db; vox-populi → vox-eval; vox-populi → vox-foundation; vox-populi → vox-gamify; vox-populi → vox-hf-layout; vox-populi → vox-http-client; vox-populi → vox-id…vox-populivox-bounded-fsvox-configvox-corpusvox-cryptovox-dbvox-evalvox-foundationvox-gamifyvox-hf-layoutvox-http-clientvox-identityvox-mesh-typesvox-clivox-cli-researchvox-ml-clivox-orchestratorvox-orchestrator-mcpvox-plugin-populi-meshvox-speechvox-workflow-runtime
Diagram source
graph {
direction: right
node vox_populi: "vox-populi"
node vox_bounded_fs: "vox-bounded-fs"
vox_populi -> vox_bounded_fs
node vox_config: "vox-config"
vox_populi -> vox_config
node vox_corpus: "vox-corpus"
vox_populi -> vox_corpus
node vox_crypto: "vox-crypto"
vox_populi -> vox_crypto
node vox_db: "vox-db"
vox_populi -> vox_db
node vox_eval: "vox-eval"
vox_populi -> vox_eval
node vox_foundation: "vox-foundation"
vox_populi -> vox_foundation
node vox_gamify: "vox-gamify"
vox_populi -> vox_gamify
node vox_hf_layout: "vox-hf-layout"
vox_populi -> vox_hf_layout
node vox_http_client: "vox-http-client"
vox_populi -> vox_http_client
node vox_identity: "vox-identity"
vox_populi -> vox_identity
node vox_mesh_types: "vox-mesh-types"
vox_populi -> vox_mesh_types
node vox_cli: "vox-cli"
vox_cli -> vox_populi
node vox_cli_research: "vox-cli-research"
vox_cli_research -> vox_populi
node vox_ml_cli: "vox-ml-cli"
vox_ml_cli -> vox_populi
node vox_orchestrator: "vox-orchestrator"
vox_orchestrator -> vox_populi
node vox_orchestrator_mcp: "vox-orchestrator-mcp"
vox_orchestrator_mcp -> vox_populi
node vox_plugin_populi_mesh: "vox-plugin-populi-mesh"
vox_plugin_populi_mesh -> vox_populi
node vox_speech: "vox-speech"
vox_speech -> vox_populi
node vox_workflow_runtime: "vox-workflow-runtime"
vox_workflow_runtime -> vox_populi
}
Consumer CrateRole
vox-cliDirect workspace dependent
vox-cli-researchDirect workspace dependent
vox-ml-cliDirect workspace dependent
vox-orchestratorDirect workspace dependent
vox-orchestrator-mcpDirect workspace dependent
vox-plugin-populi-meshDirect workspace dependent
vox-speechDirect workspace dependent
vox-workflow-runtimeDirect workspace dependent
KindSymbolSignatureSourceDescription
fnpopuli_enabled_from_envpub fn populi_enabled_from_env() -> boolcrates/vox-populi/src/lib.rs#L17-L25Whether populi hooks are enabled (VOX_MESH_ENABLED=1 or true).
structPopuliEnvpub struct PopuliEnvcrates/vox-populi/src/lib.rs#L29-L50Parsed populi-related environment (best-effort).
fnpopuli_env_resolvedpub fn populi_env_resolved(vox_toml_path: Option<&std::path::Path>) -> PopuliEnvcrates/vox-populi/src/lib.rs#L55-L98Merge Vox.toml [populi] into env-derived values when the corresponding env is unset. Precedence: environment always wins over TOML for each field.
fnpopuli_advertise_gpu_effectivepub fn populi_advertise_gpu_effective(vox_toml_path: Option<&std::path::Path>) -> boolcrates/vox-populi/src/lib.rs#L102-L120Whether VOX_MESH_ADVERTISE_GPU is set, or [populi].advertise_gpu = true when env is unset.
fnnormalize_http_control_basepub fn normalize_http_control_base(raw: &str) -> Option<String>crates/vox-populi/src/lib.rs#L127-L143Normalize a control-plane URL for use as an HTTP client base (join / heartbeat / list). Returns [None] for empty strings, invalid trim, or bind-all hosts (0.0.0.0, ::) where the value is meant for vox populi serve --bind, not outbound requests.
fnpopuli_envpub fn populi_env() -> PopuliEnvcrates/vox-populi/src/lib.rs#L165-L207Read populi env vars (does not mutate process state).
fnpopuli_scope_id_from_envpub fn populi_scope_id_from_env() -> Option<String>crates/vox-populi/src/lib.rs#L211-L216VOX_MESH_SCOPE_ID when set and non-empty after trim.
fnwall_clock_unix_mspub fn wall_clock_unix_ms() -> u64crates/vox-populi/src/lib.rs#L220-L222Current Unix time in milliseconds (for federation timestamps and tests).
fnresolve_vox_toml_best_effortpub fn resolve_vox_toml_best_effort() -> Option<PathBuf>crates/vox-populi/src/lib.rs#L241-L247Resolve Vox.toml path next to the current working directory (nearest manifest root).
fnnode_record_for_current_processpub fn node_record_for_current_process(node_id: String, listen_addr: Option<String>) -> NodeRecordcrates/vox-populi/src/lib.rs#L251-L329Build a [NodeRecord] for this process using orchestrator host probe + populi env labels.
fnpublish_local_registry_best_effortpub fn publish_local_registry_best_effort() -> Result<(), PopuliRegistryError>crates/vox-populi/src/lib.rs#L332-L339Register this process into the default local registry file (no-op if VOX_MESH_ENABLED is off).
fnpopuli_registration_record_for_processpub fn populi_registration_record_for_process() -> NodeRecordcrates/vox-populi/src/lib.rs#L343-L352[NodeRecord] for this process — same id and listen_addr as [publish_local_registry_best_effort].
fnlocal_registry_pathpub fn local_registry_path() -> PathBufcrates/vox-populi/src/lib.rs#L356-L358Resolved on-disk registry path (honours VOX_MESH_REGISTRY_PATH).
fncurrent_target_triplepub fn current_target_triple() -> &'static strcrates/vox-populi/src/lib.rs#L375-L393Returns the current target triple (Wave 4 best-effort).
structhttp_client::A2AInboxPagerpub struct A2AInboxPagercrates/vox-populi/src/http_client.rs#L29-L34Iterator-style paging cursor for non-claimer A2A inbox reads.
fnhttp_client::newpub fn new(receiver_agent_id: impl Into<String>, page_size: usize) -> Selfcrates/vox-populi/src/http_client.rs#L39-L46Create a pager for a receiver id with a bounded page size.
fnhttp_client::next_pagepub async fn next_page(crates/vox-populi/src/http_client.rs#L49Fetch the next page (newest-first). Empty page means completion.
structhttp_client::PopuliHttpClientpub struct PopuliHttpClientcrates/vox-populi/src/http_client.rs#L74-L78Call the populi HTTP API (join / list / heartbeat / leave).
fnhttp_client::for_hosted_control_planepub fn for_hosted_control_plane(base: impl Into<String>) -> Selfcrates/vox-populi/src/http_client.rs#L93-L95Hosted / BaaS control plane entrypoint: same as [Self::new], but documents org-scoped HTTPS bases (see docs/src/adr/009-populi-hosted-baas.md). Never embed secrets in the URL.
fnhttp_client::queue_statspub async fn queue_stats(&self) -> Result<MeshQueueStats, PopuliRegistryError>crates/vox-populi/src/http_client.rs#L98-L120Get mesh queue stats.
fnhttp_client::newpub fn new(base: impl Into<String>) -> Selfcrates/vox-populi/src/http_client.rs#L124-L126New client; base is normalized (trailing / stripped). No Authorization header.
fnhttp_client::new_with_timeoutpub fn new_with_timeout(base: impl Into<String>, timeout: Duration) -> Selfcrates/vox-populi/src/http_client.rs#L130-L146Like [Self::new] with an explicit request timeout (federation / control plane).
fnhttp_client::with_bearerpub fn with_bearer(mut self, token: impl Into<String>) -> Selfcrates/vox-populi/src/http_client.rs#L150-L154Attach Authorization: Bearer … to every request (e.g. matches server VOX_MESH_TOKEN).
fnhttp_client::with_env_tokenpub fn with_env_token(self) -> Selfcrates/vox-populi/src/http_client.rs#L158-L164If VOX_MESH_TOKEN is set and non-empty, same as [Self::with_bearer] with that value.
fnhttp_client::with_env_deliver_tokenpub fn with_env_deliver_token(self) -> Selfcrates/vox-populi/src/http_client.rs#L168-L174Bearer for POST /v1/populi/a2a/deliver: first non-empty among mesh, submitter, then admin tokens.
fnhttp_client::list_nodespub async fn list_nodes(&self) -> Result<PopuliRegistryFile, PopuliRegistryError>crates/vox-populi/src/http_client.rs#L224-L237GET /v1/populi/nodes
fnhttp_client::sync_node_registrypub async fn sync_node_registry(crates/vox-populi/src/http_client.rs#L245Fetch the control-plane node list (GET /v1/populi/nodes), merge it into the on-disk LocalRegistry at reg (deduped by id, fresher last_seen_unix_ms wins, control plane authoritative on ties), and persist atomically. Returns the merged view. The HTTP fetch is the only part that needs a live control plane; the merge (merge_registry_by_last_seen) is a pure, separately unit-tested function.
fnhttp_client::federation_directorypub async fn federation_directory(crates/vox-populi/src/http_client.rs#L261GET /v1/populi/federation/directory
fnhttp_client::federation_announcepub async fn federation_announce(crates/vox-populi/src/http_client.rs#L279POST /v1/populi/federation/announce
fnhttp_client::joinpub async fn join(&self, node: &NodeRecord) -> Result<NodeRecord, PopuliRegistryError>crates/vox-populi/src/http_client.rs#L298-L311POST /v1/populi/join
fnhttp_client::heartbeatpub async fn heartbeat(&self, node: &NodeRecord) -> Result<NodeRecord, PopuliRegistryError>crates/vox-populi/src/http_client.rs#L314-L327POST /v1/populi/heartbeat
fnhttp_client::bootstrap_exchangepub async fn bootstrap_exchange(crates/vox-populi/src/http_client.rs#L333POST /v1/populi/bootstrap/exchange — exchange a one-time bootstrap token for the mesh bearer token. The endpoint is unauthenticated (no Authorization header); the bootstrap token itself is the credential. Returns the long-lived mesh bearer token and optional scope id.
fnhttp_client::leavepub async fn leave(&self, node_id: &str) -> Result<bool, PopuliRegistryError>crates/vox-populi/src/http_client.rs#L355-L374POST /v1/populi/leave — returns true if the node was present and removed.
fnhttp_client::relay_a2apub async fn relay_a2a(&self, req: &A2ADeliverRequest) -> Result<(), PopuliRegistryError>crates/vox-populi/src/http_client.rs#L377-L386POST /v1/populi/a2a/deliver — forward an A2A message to a remote node.
fnhttp_client::relay_a2a_inboxpub async fn relay_a2a_inbox(crates/vox-populi/src/http_client.rs#L389POST /v1/populi/a2a/inbox — fetch undelivered messages for a receiver id.
fnhttp_client::relay_a2a_inbox_limitedpub async fn relay_a2a_inbox_limited(crates/vox-populi/src/http_client.rs#L398POST /v1/populi/a2a/inbox with optional server-side max row cap.
fnhttp_client::relay_a2a_inbox_all_pagedpub async fn relay_a2a_inbox_all_paged(crates/vox-populi/src/http_client.rs#L424Page through non-claimer inbox rows until empty (newest-to-oldest by id).
fnhttp_client::relay_a2a_ackpub async fn relay_a2a_ack(crates/vox-populi/src/http_client.rs#L442POST /v1/populi/a2a/ack — acknowledge one delivered message.
fnhttp_client::exec_lease_grantpub async fn exec_lease_grant(crates/vox-populi/src/http_client.rs#L469POST /v1/populi/exec/lease/grant — acquire or refresh a remote execution lease for scope_key.
fnhttp_client::list_exec_leasespub async fn list_exec_leases(crates/vox-populi/src/http_client.rs#L487GET /v1/populi/exec/leases — mesh/admin bearer; non-expired rows after server sweep.
fnhttp_client::exec_lease_renewpub async fn exec_lease_renew(crates/vox-populi/src/http_client.rs#L504POST /v1/populi/exec/lease/renew.
fnhttp_client::exec_lease_releasepub async fn exec_lease_release(crates/vox-populi/src/http_client.rs#L519POST /v1/populi/exec/lease/release.
fnhttp_client::relay_a2a_lease_renewpub async fn relay_a2a_lease_renew(crates/vox-populi/src/http_client.rs#L534POST /v1/populi/a2a/lease-renew.
fnhttp_client::admin_quarantinepub async fn admin_quarantine(crates/vox-populi/src/http_client.rs#L549POST /v1/populi/admin/quarantine — requires mesh/admin bearer.
fnhttp_client::admin_maintenancepub async fn admin_maintenance(crates/vox-populi/src/http_client.rs#L564POST /v1/populi/admin/maintenance — requires mesh/admin bearer.