facts

Documentation

Overview

Package facts is STABLE — local and remote cluster fact collection. It is part of the stable operator path.

Index

• Constants
• func ApplyOllamaWarmth(info *models.OllamaInfo, rms []models.ResidentModel)
• func BuildPairwiseLinkMatrix(ctx context.Context, localName string, nodes []models.NodeFacts) *models.PairwiseLinkMatrix
• func DefaultOllamaKeepAlive(info *models.OllamaInfo) time.Duration
• func DiscoverTools(ctx context.Context) []models.ToolInfo
• func MapDarwinPressureToPSI(level int) (float64, float64)
• func TopologySummary(m *models.PairwiseLinkMatrix) string
• func WrapBash(cmd string) string
• type Collector
• type LocalCollector
  • func NewLocalCollector(name, role string) *LocalCollector
  • func (c *LocalCollector) Collect(ctx context.Context) (*models.NodeFacts, error)
• type RemoteCollector
  • func NewRemoteCollector(name, role, hostname string, exec transport.Executor) *RemoteCollector
  • func (c *RemoteCollector) Collect(ctx context.Context) (*models.NodeFacts, error)

Constants

const LlamaServerDiscoveryScript = `` /* 1891-byte string literal not displayed */

LlamaServerDiscoveryScript is the bash script used to detect a running llama-server process, extract its loaded model from the command line, and report it as a resident model. Works locally and over SSH.

pgrep is trimmed to a single PID with | head -1 to handle multiple instances deterministically. The --model/-m flag is parsed with awk to handle both --model=path and --model path forms and avoid fragile column assumptions.

const MLXDiscoveryScript = `` /* 1872-byte string literal not displayed */

MLXDiscoveryScript detects a running mlx_lm.server process and queries its OpenAI-compatible /v1/models endpoint to enumerate resident models.

mlx_lm is a Python package (pip install mlx-lm), so python3 is used for JSON parsing — it is always present on any node that can run MLX. The server defaults to port 8080; the script respects an explicit --port argument.

Note: llama-server also defaults to port 8080. On nodes running both, only the first server to bind the port will be reachable; the other probe will return an empty resident-model list rather than an error.

const OllamaDiscoveryScript = `` /* 3911-byte string literal not displayed */

OllamaDiscoveryScript is the bash script used to robustly discover Ollama state and models across both local and remote nodes.

Functions

func ApplyOllamaWarmth

func ApplyOllamaWarmth(info *models.OllamaInfo, rms []models.ResidentModel)

applyOllamaWarmth populates ExpiresAt and WarmthScore for each ResidentModel from Ollama's /api/ps payload. The Ollama probe emits an `expires_at` field per resident model and a process-level `default_keep_alive` duration (Ollama 0.3.10+). Warmth is a continuous score in [0, 1] computed as remaining / total, where total falls back to 5m (Ollama's stock default) when `default_keep_alive` is absent or unparseable. When `expires_at` is missing or already past, WarmthScore is 0 (cold). Both fields are advisory metadata only — placement consumes them as a bounded tiebreaker in internal/placement/ranker.go modelWarmthRank.

Exported for testability from internal/placement and from internal/facts tests.

func BuildPairwiseLinkMatrix

func BuildPairwiseLinkMatrix(ctx context.Context, localName string, nodes []models.NodeFacts) *models.PairwiseLinkMatrix

BuildPairwiseLinkMatrix probes directional RTT from the local node to each remote node in the snapshot and returns a best-effort PairwiseLinkMatrix.

Measurement model: from a single vantage (the local node), ping each remote's ResolvedDialTarget (falling back to SSHTarget). Cross-remote edges (remote→remote) are NOT probed directly — only local→remote is measured. Throughput is left at 0 (unmeasured); RTTLatencyP95 is the primary signal.

The matrix is best-effort: nodes that can't be reached or where ping is unavailable are omitted rather than the whole build failing.

func DefaultOllamaKeepAlive

func DefaultOllamaKeepAlive(info *models.OllamaInfo) time.Duration

DefaultOllamaKeepAlive resolves the process-level default_keep_alive duration from an Ollama /api/ps payload, falling back to 5m (Ollama's stock default since 0.3.10) when the field is absent or unparseable. Returns a positive duration on success. Exported for testability.

func DiscoverTools

func DiscoverTools(ctx context.Context) []models.ToolInfo

DiscoverTools probes for installed tools on the local machine. Silent failure allowed — missing tools are simply not reported.

func MapDarwinPressureToPSI

func MapDarwinPressureToPSI(level int) (float64, float64)

MapDarwinPressureToPSI maps Darwin vm pressure level (1, 2, 4) to nominal memory PSI levels (some, full).

func TopologySummary

func TopologySummary(m *models.PairwiseLinkMatrix) string

TopologySummary returns a human-readable summary of the matrix for logging.

func WrapBash

func WrapBash(cmd string) string

WrapBash returns a remote command that runs cmd under bash without profile/rc.

Critical: sshd executes remote commands as `$SHELL -c "<string>"`. When $SHELL is fish, the string must be valid fish syntax (or a pure external command line). POSIX constructs like `name=value`, `for ...; do`, and `[ ]` fail under fish before bash is ever reached — which is exactly the slow-shell case this wrapper targets.

Therefore the outer form is a pure external invocation with no shell logic:

/usr/bin/env bash --noprofile --norc -c '<script>'

fish, bash, zsh, and dash all treat this as "run program env with args…". `env` resolves bash on PATH (works on NixOS non-FHS layouts). Absolute fallbacks are tried only via env's PATH, not via shell loops.

Multi-session collects still pay login-shell startup once per session; prefer the one-shot fact bundle for remote nodes.

Types

type Collector

type Collector interface {
	Collect(ctx context.Context) (*models.NodeFacts, error)
}

Collector collects facts from a node. Implementations: LocalCollector (direct), RemoteCollector (SSH-based, temporary).

type LocalCollector

type LocalCollector struct {
	Name string
	Role string
}

LocalCollector collects facts from the local machine.

func NewLocalCollector

func NewLocalCollector(name, role string) *LocalCollector

NewLocalCollector creates a collector for the local node.

func (*LocalCollector) Collect

func (c *LocalCollector) Collect(ctx context.Context) (*models.NodeFacts, error)

Collect gathers all facts from the local machine. Tolerates missing values — degrades to partial, never crashes.

type RemoteCollector

type RemoteCollector struct {
	NodeName string
	Role     string
	Hostname string
	Exec     transport.Executor
}

RemoteCollector collects facts from a remote node via SSH. The Executor interface keeps the collection path decoupled from the current transport implementation.

func NewRemoteCollector

func NewRemoteCollector(name, role, hostname string, exec transport.Executor) *RemoteCollector

NewRemoteCollector creates a remote fact collector.

func (*RemoteCollector) Collect

func (c *RemoteCollector) Collect(ctx context.Context) (*models.NodeFacts, error)

Collect gathers facts from the remote node. Maps failures precisely:

• connect/first-command fail → unreachable
• subsequent command fail → partial

Collection strategy (utility-preserving):

1. Force bash for all remote probes (avoids non-POSIX login shells for scripts).
2. Prefer a one-shot fact bundle (one SSH session worth of shell work).
3. Fall back to the legacy multi-Run path if the bundle fails.
4. Always run best-effort AI resident discovery (ollama/llama/mlx) + TurboQuant.