Crate gglib_core 

gglib-core

Pure domain types, ports, and traits for gglib — the foundation of the hexagonal architecture.

The product’s judgment lives here as pure logic: sampling resolution, dialect normalization, GGUF capability detection, and residency policy — all decidable without a GPU, a network, or a running llama-server, and therefore testable.

Architecture

This crate is the Core Layer — the innermost ring of the architecture. All other crates depend on it; it depends on none.

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                                    Core Layer                                       │
│   ┌─────────────────────────────────────────────────────────────────────────────┐   │
│   │                         ►►► gglib-core ◄◄◄                                  │   │
│   │              Pure domain types, ports & traits (no infra deps)              │   │
│   └─────────────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────────────┘
                                          │
                                          ▼
              ┌───────────────────────────────────────────────────────┐
              │  gglib-db, gglib-gguf, gglib-hf, gglib-mcp,           │
              │  gglib-download, gglib-runtime                        │
              └───────────────────────────────────────────────────────┘

See the Architecture Overview for the complete diagram.

Internal Structure

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              gglib-core                                             │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                 │
│  │   domain/   │  │   ports/    │  │  services/  │  │   events/   │                 │
│  │  Pure types │  │   Traits    │  │  Use cases  │  │  App events │                 │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘                 │
│         │                │                │                │                        │
│         ▼                ▼                ▼                ▼                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                 │
│  │   paths/    │  │  download/  │  │   utils/    │  │  settings   │                 │
│  │ Path config │  │Download DTOs│  │   Helpers   │  │   Config    │                 │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘                 │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘

Modules

Module	LOC	Complexity	Coverage
cache_config.rs
cache_metrics.rs
cors.rs
debug_switches.rs
is_local_origin.rs
server_config.rs
settings.rs
settings_loop_guard.rs
settings_loop_guard_tests.rs
settings_remote.rs
settings_remote_tests.rs
settings_tests.rs
settings_update.rs
settings_validate.rs
telemetry.rs
access/
contracts/
domain/
download/
events/
normalize/
paths/
ports/
request_pipeline/
retry/
services/
sse/
utils/

Module Descriptions:

• domain/ — Pure domain types: Model, ModelFile, McpServer, Conversation; agent loop primitives: AgentConfig, AgentMessage, AgentEvent, ToolDefinition, ToolCall, ToolResult; and server configuration: ServerConfig (per-model launch defaults with context_length, used in the 5-level fallback chain: runtime request → model server_defaults → global settings → fitted to hardware → hardcoded DEFAULT_CONTEXT_SIZE)
• ports/ — Trait definitions (repository ports, HF client port, event emitter, AgentLoopPort / ToolExecutorPort / AgentError for the backend agentic loop)
• services/ — Application use cases and business logic orchestration (model management, server lifecycle, chat history, settings, model verification & repair)
• events/ — Strongly-typed application events for UI/adapter notification
• paths/ — Path configuration and platform-specific directory handling
• download/ — Download-related DTOs and progress tracking types
• ports/mcp_dto.rs — Cross-boundary DTOs for MCP resolution status (Tauri/Axum/TypeScript)
• sse/ — OpenAI-compatible SSE codec: byte-stream SseStreamDecoder, single-frame parse_sse_frame, and SseEncoder that re-emits canonical chat.completion.chunk envelopes. Used by the proxy’s universal consistency layer.
• normalize/ — Universal normalization layer. The ToolCallParser trait plus dialect parsers (StandardJsonParser identity and the spec-driven DelimitedToolCallParser for marker-delimited tool calls) rewrite model-specific output into strict OpenAI events. Selected per-request from the model’s persisted DialectSpec (with a format:* tag fallback) via normalize::registry::get_parser.
• utils/ — Shared utility functions and helpers
• settings.rs — Application settings and configuration types

Design Principles

1. No Infrastructure Dependencies — No SQLx, no HTTP clients, no filesystem I/O
2. Trait-Based Ports — All external capabilities defined as traits for DI
3. Pure Data Types — Domain types are serializable, cloneable, and testable
4. Event-Driven — AppEventEmitter trait enables decoupled UI updates

Usage

use gglib_core::domain::Model;
use gglib_core::ports::{ModelRepository, RepositoryError};
use gglib_core::services::ModelService;
use gglib_core::events::AppEvent;

// Ports define capabilities
async fn example<R: ModelRepository>(repo: &R) -> Result<Vec<Model>, RepositoryError> {
    let models = repo.list().await?;
    Ok(models)
}

Re-exports

pub use access::ApiKeySource;

pub use access::ProxyAccessConfig;

pub use domain::AGENT_EVENT_CHANNEL_CAPACITY;

pub use domain::AgentConfig;

pub use domain::AgentEvent;

pub use domain::AgentMessage;

pub use domain::AssistantContent;

pub use domain::ChatMessage;

pub use domain::Conversation;

pub use domain::ConversationUpdate;

pub use domain::DEFAULT_MAX_ITERATIONS;

pub use domain::DEFAULT_MAX_STAGNATION_STEPS;

pub use domain::LlmStreamEvent;

pub use domain::LoopDetector;

pub use domain::MAX_ITERATIONS_CEILING;

pub use domain::MAX_PARALLEL_TOOLS_CEILING;

pub use domain::MAX_TOOL_TIMEOUT_MS_CEILING;

pub use domain::McpEnvEntry;

pub use domain::McpLifecycle;

pub use domain::McpServer;

pub use domain::McpServerConfig;

pub use domain::McpServerStatus;

pub use domain::McpServerType;

pub use domain::McpTool;

pub use domain::McpToolResult;

pub use domain::Message;

pub use domain::MessageContent;

pub use domain::MessageRole;

pub use domain::Model;

pub use domain::ModelCapabilities;

pub use domain::ModelFilterOptions;

pub use domain::NameSource;

pub use domain::NewConversation;

pub use domain::NewMcpServer;

pub use domain::NewMessage;

pub use domain::NewModel;

pub use domain::StagnationDetector;

pub use domain::ToolCall;

pub use domain::ToolDefinition;

pub use domain::ToolIndex;

pub use domain::ToolResult;

pub use domain::repo_short_name;

pub use domain::resolve_model_name;

pub use domain::strip_gguf_suffix;

pub use domain::transform_messages_for_capabilities;

pub use download::AttemptCounts;

pub use download::CompletionDetail;

pub use download::CompletionKey;

pub use download::CompletionKind;

pub use download::DownloadError;

pub use download::DownloadEvent;

pub use download::DownloadId;

pub use download::DownloadStatus;

pub use download::DownloadSummary;

pub use download::FailedDownload;

pub use download::Quantization;

pub use download::QueueRunSummary;

pub use download::QueueSnapshot;

pub use download::QueuedDownload;

pub use download::ShardInfo;

pub use events::AppEvent;

pub use events::ModelSummary;

pub use ports::AgentError;

pub use ports::AgentLoopPort;

pub use ports::AgentRunOutput;

pub use ports::AppEventEmitter;

pub use ports::ChatHistoryError;

pub use ports::ChatHistoryRepository;

pub use ports::CompletedDownload;

pub use ports::CoreError;

pub use ports::DownloadManagerConfig;

pub use ports::DownloadManagerPort;

pub use ports::DownloadRequest;

pub use ports::EmptyToolExecutor;

pub use ports::FilteredToolExecutor;

pub use ports::GgufCapabilities;

pub use ports::GgufMetadata;

pub use ports::GgufParseError;

pub use ports::GgufParserPort;

pub use ports::HfClientPort;

pub use ports::HfFileInfo;

pub use ports::HfPortError;

pub use ports::HfQuantInfo;

pub use ports::HfRepoInfo;

pub use ports::HfSearchOptions;

pub use ports::HfSearchResult;

pub use ports::JinjaMode;

pub use ports::LlmCompletionPort;

pub use ports::McpRepositoryError;

pub use ports::McpServerRepository;

pub use ports::McpServiceError;

pub use ports::ModelRegistrarPort;

pub use ports::ModelRepository;

pub use ports::NoopEmitter;

pub use ports::NoopGgufParser;

pub use ports::ProcessHandle;

pub use ports::QuantizationResolver;

pub use ports::Repos;

pub use ports::RepositoryError;

pub use ports::Resolution;

pub use ports::ResolvedFile;

pub use ports::ServerConfig;

pub use ports::SettingsRepository;

pub use ports::ToolExecutorPort;

pub use ports::UsageSink;

pub use services::ChatHistoryService;

pub use services::ModelRegistrar;

pub use settings::DAEMON_PORT;

pub use settings::DEFAULT_CONTEXT_SIZE;

pub use settings::DEFAULT_LLAMA_BASE_PORT;

pub use settings::DEFAULT_PROXY_PORT;

pub use settings::DEFAULT_REMOTE_PORT;

pub use settings::Device;

pub use settings::LoopGuardMode;

pub use settings::RemotePairing;

pub use settings::RemoteServe;

pub use settings::Settings;

pub use settings::SettingsUpdate;

pub use settings::validate_settings;

pub use is_local_origin::is_local_origin;

pub use paths::DirectoryCreationStrategy;

pub use paths::ModelsDirSource;

pub use paths::PathError;

pub use paths::data_root;

pub use paths::database_path;

pub use paths::default_models_dir;

pub use paths::ensure_directory;

pub use paths::is_prebuilt_binary;

pub use paths::llama_config_path;

pub use paths::llama_cpp_dir;

pub use paths::llama_server_path;

pub use paths::persist_models_dir;

pub use paths::resolve_models_dir;

pub use paths::resource_root;

Modules

access

Access

cache_config

KV-cache configuration types: quantized cache types and the host-RAM prompt cache setting.

cache_metrics

Prompt-cache reuse telemetry.

contracts

contracts

cors 🔒

CORS configuration types.

debug_switches

The GGLIB_DISABLE_* environment switches, and which are in effect here.

domain

domain

download

download

events

events

is_local_origin

Origin validation utilities for CORS and similar security checks.

normalize

normalize

paths

paths

ports

ports

request_pipeline

Request Pipeline

retry

Retry

server_config

Canonical context-size resolver (5-level fallback chain).

services

services

settings

Settings domain types and validation.

sse

sse

telemetry

Unified tracing initialization for gglib.

utils

utils

Enums

CorsConfig

CORS configuration for the web server.

Functions

elapsed_ms

Convert Instant::elapsed() to whole milliseconds, clamping to u64::MAX.

format_duration_human

Format a millisecond duration into a compact human-readable string.