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

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

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

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.