modelforge 0.1.10

Provider-aware model target parsing primitives for archive tools
Documentation

ModelForge

ModelForge provides model-provider and model-target parsing primitives used by thesa.

Made by Trevor Knott for Knott Dynamics. ModelForge is part of the thesa archive stack alongside repoforge, siteforge, Scrin, and Aisling.

The crate normalizes Hugging Face, Ollama, and CivitAI target forms into simple archive targets. It does not call provider APIs and it does not download models; it only turns user-facing target strings into stable Rust enums.

ModelForge is meant to sit at the boundary between CLI/TUI input and provider clients. It keeps parsing rules testable, reusable, and separate from network or filesystem side effects.

What It Does

  • Parses Hugging Face organization and model targets.
  • Parses Hugging Face model URLs.
  • Parses Ollama keyword/model inputs.
  • Parses CivitAI numeric IDs and model URLs.
  • Normalizes shared presets such as top, trending, latest, and newest.
  • Provides provider labels, short labels, slugs, and slug parsing.

What It Does Not Do

  • Does not call Hugging Face, Ollama, or CivitAI APIs.
  • Does not download, clone, pull, or write model files.
  • Does not store tokens or credentials.
  • Does not decide archive output paths.

Install

[dependencies]
modelforge = "0.1"

Providers

assert_eq!(modelforge::ModelProvider::Hf.slug(), "hf");
assert_eq!(
    modelforge::ModelProvider::from_slug("hugging-face"),
    Some(modelforge::ModelProvider::Hf)
);

Supported providers:

  • ModelProvider::Hf: Hugging Face Hub
  • ModelProvider::Ollama: local Ollama registry/runtime
  • ModelProvider::Civitai: CivitAI model catalog

Provider aliases accept common separators, so hugging-face, hugging face, and hugging_face resolve the same way.

API Surface

  • parse_model_target(input): parse simple Hugging Face-style owner or owner/model forms.
  • parse_model_target_for_provider(input, provider): parse with provider-specific rules.
  • ModelProvider::slug(): stable lowercase provider slug.
  • ModelProvider::ALL and ModelProvider::all(): stable provider iteration order.
  • ModelProvider::from_slug(value): parse accepted provider aliases.
  • ModelProvider::label(): human-readable provider label.
  • ModelProvider::short_label(): compact provider label.
  • ModelTarget::kind(): target kind label.
  • ModelTarget::value(): borrowed target id for Org or Model variants.
  • ModelTarget::org() and ModelTarget::model(): variant-specific borrowed values.
  • ModelTarget::is_org() and ModelTarget::is_model(): variant checks for caller branching.
  • ModelTarget::is_preset(): whether target is Top or Latest.

Core data types:

  • ModelProvider: Hf, Ollama, or Civitai.
  • ModelTarget: Org, Model, Top, or Latest.
  • ModelForgeError: invalid target errors with the rejected target payload.

Targets

let target = modelforge::parse_model_target_for_provider(
    "https://huggingface.co/openai-community/gpt2",
    modelforge::ModelProvider::Hf,
)?;

assert_eq!(target.kind(), "model");
assert_eq!(target.value(), Some("openai-community/gpt2"));
# Ok::<(), modelforge::ModelForgeError>(())

Normalized targets:

  • ModelTarget::Org(String): namespace, organization, owner, or search keyword
  • ModelTarget::Model(String): concrete model id
  • ModelTarget::Top: top/trending/popular preset
  • ModelTarget::Latest: latest/newest/new preset

Accepted Forms

Hugging Face:

  • owner
  • owner/model
  • https://huggingface.co/owner/model
  • https://www.huggingface.co/owner/model
  • https://hf.co/owner/model
  • top, trending, popular
  • latest, newest, new

Ollama:

  • model-name or search keyword
  • https://ollama.com/library/model-name
  • https://www.ollama.com/library/model-name
  • top, trending, popular
  • latest, newest, new

CivitAI:

  • numeric model id, such as 827184
  • https://civitai.com/models/827184
  • https://www.civitai.com/models/827184
  • search keyword
  • top, trending, popular
  • latest, newest, new

Design

ModelForge keeps parsing separate from provider API clients. Consumers such as thesa can use the normalized target enum to decide whether to fetch a single model, list a namespace, or run a provider-specific preset query.

Package Contents

Cargo releases are explicitly whitelisted to avoid shipping sessions, notes, build output, or local artifacts. The package contains only:

  • Cargo.toml
  • Cargo.lock
  • README.md
  • LICENSE
  • CHANGELOG.md
  • src/**

Role In Thesa

thesa uses ModelForge before calling provider APIs. The CLI and TUI collect a target string, ModelForge normalizes it, and thesa then runs the provider flow with Scrin/Aisling status panels and .thesa integrity manifests.