> ## 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 Lineage Graph and Ancestry Tracking

> Specification for model lineage tracking in EMEP, covering parent-child relationships, merge metadata, and lineage graph visualization.

Model lineage tracks the ancestry of every model in EMEP. It records which parent models were combined, how they were merged, and what experiments produced the result. This page specifies the lineage data model, graph structure, and query interface.

## Lineage Graph Example

```mermaid theme={null}
flowchart TD
    A[model_llama_7b_base_v3] -->|TIES alpha=0.6,0.4| B[model_llama_7b_persian_v1]
    C[model_llama_7b_instruct_v2] -->|TIES alpha=0.6,0.4| B
    B -->|SLERP alpha=0.7,0.3| D[model_llama_7b_persian_code_v1]
    E[model_llama_7b_code_v1] -->|SLERP alpha=0.7,0.3| D
    D -->|Task Arithmetic| F[model_llama_7b_final_v1]
    G[model_llama_7b_safety_v1] -->|Task Arithmetic| F
```

## Lineage Edge Metadata

Every parent-to-child edge includes:

| Field             | Description                                       |
| ----------------- | ------------------------------------------------- |
| parent\_id        | Source model                                      |
| child\_id         | Result model                                      |
| experiment\_id    | Experiment that produced the merge                |
| merge\_method     | SLERP, TIES, DARE, Task Arithmetic, Franken-Merge |
| merge\_parameters | Alpha, density, layer routing, etc.               |
| timestamp         | Merge execution time                              |
| genome\_id        | Genome used for the merge                         |

## Data Model

Lineage is stored as a directed acyclic graph. Cycles are impossible by construction: a child cannot be a parent of its own ancestor. The ModelRegistry enforces this at merge time.

## Query Interface

```text theme={null}
Lineage.get_parents(model_id) -> List[LineageEdge]
Lineage.get_children(model_id) -> List[LineageEdge]
Lineage.get_ancestors(model_id, depth) -> List[model_id]
Lineage.get_descendants(model_id, depth) -> List[model_id]
Lineage.get_path(model_a, model_b) -> List[LineageEdge]
Lineage.get_full_graph() -> Graph
```

## Visualization

The lineage graph can be exported for visualization. Supported formats:

* Mermaid (for documentation)
* GraphViz DOT
* Cytoscape JSON
* NetworkX (for Python analysis)

## Use Cases

**Provenance Verification**

Trace any model back to its original base model and all intermediate merges. Verify that each step used approved parents and methods.

**Impact Analysis**

If a parent model is found to have a defect, identify all descendants that may be affected. This enables targeted re-evaluation or deprecation.

**Experiment Reproduction**

Reconstruct the exact sequence of merges and parameters that produced a model. Combined with the experiment record, this enables full reproduction.

**Release Audit**

Before releasing a model, review its lineage to ensure all ancestors meet quality and license requirements.

## Integration

| Component         | Role                                      |
| ----------------- | ----------------------------------------- |
| ModelRegistry     | Stores parent references in model records |
| ExperimentTracker | Logs merge events with full parameters    |
| ArtifactStore     | Stores lineage graph exports              |
| Provenance system | Signs lineage edges for tamper evidence   |

<Info>
  Lineage edges are immutable. If a merge is reverted or a model is deprecated, the lineage record remains. A deprecation event is appended as a new edge type, not as a deletion.
</Info>