> ## 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.

# ModelRegistry API and State Management

> Specification for the ModelRegistry in EMEP, covering API operations, storage model, and state transitions aligned with the model lifecycle.

The ModelRegistry is the canonical catalog of all models in EMEP. It tracks model metadata, lifecycle state, and relationships. This page specifies the registry API, storage model, and the complete state transition diagram.

## Model Lifecycle State Diagram

```mermaid theme={null}
stateDiagram-v2
    [*] --> DISCOVERED: Import detected
    DISCOVERED --> IMPORTED: Download complete
    IMPORTED --> VALIDATED: Compatibility passed
    VALIDATED --> REGISTERED: Approved for use
    REGISTERED --> CANDIDATE: Selected for merge
    CANDIDATE --> EVALUATED: Benchmark complete
    EVALUATED --> PROMOTED: Meets thresholds
    EVALUATED --> REGISTERED: Below thresholds
    PROMOTED --> RELEASED: Approved for release
    RELEASED --> DEPLOYED: Deployed to inference
    RELEASED --> DEPRECATED: Superseded
    DEPLOYED --> DEPRECATED: New version available
    DEPRECATED --> ARCHIVED: Retired
    ARCHIVED --> [*]
    REGISTERED --> DEPRECATED: Withdrawn
    CANDIDATE --> INVALID: Integrity failure
    INVALID --> [*]
```

## State Definitions

| State      | Description                               | Entry Condition                             |
| ---------- | ----------------------------------------- | ------------------------------------------- |
| DISCOVERED | Model identified but not yet downloaded   | Automatic import detection                  |
| IMPORTED   | Weights downloaded, metadata extracted    | Download and hash verification              |
| VALIDATED  | Compatibility and integrity checks passed | ModelCompatibilityAnalyzer approval         |
| REGISTERED | Approved for use as parent or baseline    | Manual or automated approval                |
| CANDIDATE  | Selected for merge experiment             | EvolutionEngine or manual selection         |
| EVALUATED  | Benchmark suite completed                 | EvaluationEngine completion                 |
| PROMOTED   | Exceeds baseline on critical metrics      | FitnessEngine and RegressionEngine approval |
| RELEASED   | Approved for external use                 | Release workflow completion                 |
| DEPLOYED   | Active in inference backend               | DeploymentManager confirmation              |
| DEPRECATED | Superseded, not recommended for new use   | Newer version promoted                      |
| ARCHIVED   | Retired, retained for audit only          | Manual archival or auto-expiry              |
| INVALID    | Failed integrity or compatibility         | Validation failure                          |

## API Operations

```text theme={null}
ModelRegistry.register(model_metadata) -> model_id
ModelRegistry.get(model_id) -> ModelRecord
ModelRegistry.update_state(model_id, new_state, reason) -> bool
ModelRegistry.list(filters) -> List[ModelRecord]
ModelRegistry.get_lineage(model_id) -> LineageGraph
ModelRegistry.delete(model_id) -> bool  # soft delete to ARCHIVED
```

## Model Record Schema

| Field            | Type              | Description                         |
| ---------------- | ----------------- | ----------------------------------- |
| model\_id        | string            | Canonical identifier                |
| version          | string            | Semantic version                    |
| state            | string            | Current lifecycle state             |
| architecture     | string            | Model architecture family           |
| parameter\_count | int               | Total parameters                    |
| tensor\_shapes   | Dict\[str, Tuple] | Key layer dimensions                |
| tokenizer\_id    | string            | Associated tokenizer                |
| parent\_models   | List\[string]     | For merged models: parent IDs       |
| experiment\_id   | string            | Experiment that produced this model |
| artifact\_hash   | string            | SHA-256 of weight archive           |
| created\_at      | ISO8601           | Registration timestamp              |
| updated\_at      | ISO8601           | Last state change                   |

## Storage Model

Model records are stored in a relational database with the following invariants:

* model\_id is unique and immutable
* state transitions follow the diagram above; invalid transitions are rejected
* artifact\_hash references the ArtifactStore
* parent\_models references other model\_ids, creating a directed acyclic graph

## Transition Triggers

| Transition              | Triggering Component              |
| ----------------------- | --------------------------------- |
| DISCOVERED to IMPORTED  | ModelLoader                       |
| IMPORTED to VALIDATED   | ModelCompatibilityAnalyzer        |
| VALIDATED to REGISTERED | Automated rule or manual approval |
| REGISTERED to CANDIDATE | EvolutionEngine or user selection |
| CANDIDATE to EVALUATED  | EvaluationEngine                  |
| EVALUATED to PROMOTED   | FitnessEngine + RegressionEngine  |
| PROMOTED to RELEASED    | Release workflow                  |
| RELEASED to DEPLOYED    | DeploymentManager                 |
| Any to DEPRECATED       | Newer version promotion           |
| DEPRECATED to ARCHIVED  | Retention policy or manual action |

## Query Patterns

* List all models in REGISTERED state eligible for merge
* Find all models produced by a specific experiment
* Trace lineage from a deployed model to its ancestors
* Identify deprecated models with active deployments

<Info>
  The ModelRegistry does not store model weights. It stores metadata and references to the ArtifactStore. Weights are loaded on demand by the ModelLoader using the artifact\_hash.
</Info>