modelforge 0.1.10

# 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

```toml
[dependencies]
modelforge = "0.1"
```

## Providers

```rust
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

```rust
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.