Crate spn_core

Expand description

spn-core: Core types and validation for the SuperNovae ecosystem.

This crate provides:

Provider definitions (20+ LLM and MCP service providers)
Model definitions (curated models for native inference)
Model storage trait (download-only, no inference)
Key format validation with detailed error messages
MCP server configuration types
Package registry types

§Design Principles

Zero dependencies: Pure Rust, fast compilation, WASM-compatible
Single source of truth: All provider and model definitions in one place
Shared types: Used by spn-cli, spn-client, spn-keyring, spn-native, and nika

§Example

use spn_core::{
    Provider, ProviderCategory, KNOWN_PROVIDERS,
    find_provider, provider_to_env_var,
    validate_key_format, mask_key, ValidationResult,
};

// Find a provider
let provider = find_provider("anthropic").unwrap();
assert_eq!(provider.env_var, "ANTHROPIC_API_KEY");

// Validate a key format
match validate_key_format("anthropic", "sk-ant-api03-xxx") {
    ValidationResult::Valid => println!("Key is valid!"),
    ValidationResult::InvalidPrefix { expected, .. } => {
        println!("Key should start with: {}", expected);
    }
    _ => {}
}

// Mask a key for display
let masked = mask_key("sk-ant-secret-key-12345");
assert_eq!(masked, "sk-ant-••••••••");

§Model Resolution

use spn_core::{find_model, resolve_model, ResolvedModel, Quantization};

// Find a curated model
let model = find_model("qwen3:8b").unwrap();
assert_eq!(model.model_type.name(), "Text");

// Resolve model (curated or HuggingFace passthrough)
match resolve_model("hf:bartowski/Qwen3-8B-GGUF") {
    Some(ResolvedModel::HuggingFace { repo }) => {
        println!("HF repo: {}", repo);
    }
    Some(ResolvedModel::Curated(model)) => {
        println!("Curated: {}", model.name);
    }
    None => {}
}

// Auto-select quantization based on RAM
use spn_core::auto_select_quantization;
let model = find_model("qwen3:8b").unwrap();
let quant = auto_select_quantization(model, 16); // 16GB RAM
assert_eq!(quant, Quantization::Q8_0);

Structs§

BackupContents: Summary of what each subsystem contributed to the backup.
BackupInfo: Information about a completed backup.
BackupManifest: Backup manifest containing metadata about the backup.
ChatMessage: A message in a chat conversation.
ChatOptions: Options for chat completion.
ChatResponse: Response from a chat completion.
ComponentVersions: Component version information.
DownloadRequest: Request to download a model.
DownloadResult: Result of a model download.
EmbeddingResponse: Response from an embedding request.
GpuInfo: GPU device information.
KnownModel: A curated model in the registry.
LoadConfig: Configuration for loading a model.
McpConfig: Complete MCP configuration containing multiple servers.
McpServer: MCP server configuration.
ModelInfo: Information about an installed model.
NikaContents: Nika-specific backup contents.
NovaNetContents: NovaNet-specific backup contents.
PackageManifest: Package manifest (spn.yaml content).
PackageRef: Reference to a package in the registry.
Provider: Provider metadata.
PullProgress: Progress information during model pull/download.
RestoreInfo: Information about a completed restore.
RunningModel: Information about a currently running/loaded model.
SpnContents: spn-specific backup contents.

Enums§

BackendError: Error types for backend operations.
BackupError: Backup operation errors.
ChatRole: Role in a chat conversation.
McpServerType: Type of MCP server transport.
McpSource: Source of an MCP configuration.
ModelArchitecture: Architecture supported by mistral.rs v0.7.0.
ModelType: Model capability type.
PackageType: Type of package in the registry.
ProviderCategory: Category of provider service.
Quantization: Quantization levels for GGUF models.
ResolvedModel: Result of model resolution.
Source: Source of a package - where to fetch the actual content.
ValidationResult: Result of key format validation.

Statics§

KNOWN_MODELS: Curated model registry.
KNOWN_PROVIDERS: All known providers in the SuperNovae ecosystem.

Traits§

ModelStorage: Model storage backend (sync version).

Functions§

auto_select_quantization: Auto-select quantization based on available RAM.
default_model_dir: Default model storage directory (fallback when dirs feature is disabled).
detect_available_ram_gb: Detect available system RAM in gigabytes.
find_model: Find a curated model by ID.
find_provider: Find a provider by ID (case-insensitive).
mask_key: Mask an API key for safe display.
models_by_type: List all models of a specific type.
provider_to_env_var: Get the environment variable name for a provider.
providers_by_category: Get all providers in a specific category.
resolve_model: Resolve a model ID to a KnownModel or HuggingFace passthrough.
validate_key_format: Validate an API key format for a specific provider.

Type Aliases§

ProgressCallback: Type alias for download progress callbacks.

Crate spn_core

Crate spn_core Copy item path

§Design Principles

§Example

§Model Resolution

Structs§

Enums§

Statics§

Traits§

Functions§

Type Aliases§

Crate spn_core