> ## Documentation Index
> Fetch the complete documentation index at: https://doc.blueapi.ir/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Import Algorithm and Sequence

> Specification for importing models into EMEP. Covers the ModelLoader algorithm, hash verification, ArtifactStore staging, and the full interaction sequence with external sources.

Model import is the first step in the EMEP lifecycle. This page specifies the ModelLoader algorithm, the interaction sequence with external model sources, and the exact outputs that feed into the ModelRegistry.

## ModelImport Algorithm

The ModelLoader executes this flowchart for every import request.

```mermaid theme={null}
flowchart TD
    START([START]) --> INPUT[Input: source URI, requested revision, import config]
    INPUT --> FETCH_META[Fetch metadata from source]
    FETCH_META --> META_OK{Metadata valid?}
    META_OK -->|no| FAIL_META[FAIL: invalid metadata]
    META_OK -->|yes| FETCH_WEIGHTS[Fetch weight files]
    FETCH_WEIGHTS --> WEIGHTS_OK{Files complete?}
    WEIGHTS_OK -->|no| FAIL_WEIGHTS[FAIL: incomplete download]
    WEIGHTS_OK -->|yes| VERIFY_HASH[Verify SHA-256 hashes]
    VERIFY_HASH --> HASH_OK{Hash match?}
    HASH_OK -->|no| FAIL_HASH[FAIL: hash mismatch]
    HASH_OK -->|yes| UNPACK[Unpack weights to staging area]
    UNPACK --> UNPACK_OK{Unpack valid?}
    UNPACK_OK -->|no| FAIL_UNPACK[FAIL: corrupt archive]
    UNPACK_OK -->|yes| STAGE[Stage in ArtifactStore]
    STAGE --> MANIFEST[Generate import manifest]
    MANIFEST --> REGISTER[Register in ModelRegistry]
    REGISTER --> RETURN[Return manifest to caller]
    RETURN --> END([END])
    FAIL_META --> END
    FAIL_WEIGHTS --> END
    FAIL_HASH --> END
    FAIL_UNPACK --> END
```

## Import Sequence Diagram

This sequence shows the full interaction between the user, ModelLoader, external source, ArtifactStore, and ModelRegistry.

```mermaid theme={null}
sequenceDiagram
    actor U as User
    participant ML as ModelLoader
    participant HF as Hugging Face / Mirror
    participant AS as ArtifactStore
    participant MR as ModelRegistry

    U->>ML: request_import(source_uri, revision, config)
    ML->>HF: fetch_metadata(source_uri, revision)
    HF-->>ML: metadata_json
    ML->>ML: validate_metadata
    ML->>HF: fetch_weight_files(file_list)
    HF-->>ML: weight_files
    ML->>ML: verify_sha256(file_list, expected_hashes)
    ML->>AS: stage_files(weight_files, import_id)
    AS-->>ML: staging_path
    ML->>ML: unpack_and_validate(staging_path)
    ML->>AS: commit_staging(import_id)
    AS-->>ML: artifact_uri
    ML->>ML: build_manifest(metadata, artifact_uri, hashes)
    ML->>MR: register_model(manifest)
    MR-->>ML: model_id
    ML-->>U: return manifest with model_id
```

## Import Manifest

The manifest returned to the caller and stored in ModelRegistry contains:

| Field         | Description                                   |
| ------------- | --------------------------------------------- |
| model\_id     | UUID assigned by ModelRegistry                |
| source\_uri   | Original source (HF repo, mirror, local path) |
| revision      | Tag, branch, or commit hash                   |
| artifact\_uri | Path in ArtifactStore                         |
| metadata      | Architecture, size, layer count, etc.         |
| hashes        | SHA-256 of every weight file                  |
| import\_time  | ISO 8601 timestamp                            |
| status        | IMPORTED                                      |

## Failure Modes

| Failure             | Cause                           | Recovery            |
| ------------------- | ------------------------------- | ------------------- |
| Invalid metadata    | Source returned malformed JSON  | Retry or fail       |
| Incomplete download | Network interruption            | Resume or restart   |
| Hash mismatch       | Corruption or tampering         | Reject and alert    |
| Corrupt archive     | Unpack error                    | Reject and alert    |
| Staging conflict    | Concurrent import of same model | Deduplicate by hash |

## Cross-Links

* [Model Compatibility](/compatibility/model-compatibility) for what happens after import.
* [Model Registry](/tracking/model-registry) for registration details.
* [Artifact Registry](/tracking/artifact-registry) for ArtifactStore semantics.