# Core Data Models (`reanimator.models`)

All data models in REANIMATOR-VLM are JSON-serializable dataclasses supporting `to_dict()` and `from_dict()`.

---

## `Document`

Top-level container representing a processed document.

```python
class Document(
    doc_id: str,
    doi: Optional[str] = None,
    url: Optional[str] = None,
    pdf_path: Optional[str] = None,
    text: Optional[str] = None,
    markdown_pages: List[str] = field(default_factory=list),
    tables: List[Table] = field(default_factory=list),
    figures: List[Figure] = field(default_factory=list),
    formulas: List[Formula] = field(default_factory=list),
    chunks: List[Chunk] = field(default_factory=list),
    metadata: Dict = field(default_factory=dict),
)
```

### Methods

#### `Document.load(path: Union[str, Path]) -> Document`
Load a `Document` instance from a saved `.json` file artifact on disk.

```python
doc = Document.load("parsed_docs/2504.07584.json")
```

#### `Document.save(path: Union[str, Path]) -> None`
Save a `Document` instance to a `.json` file artifact on disk.

```python
doc.save("parsed_docs/2504.07584.json")
```

#### `Document.summary() -> str`
Return a formatted summary string of extracted tables, figures, formulas, and pages.

---

## `Table`

Represents a single table extracted from a document.

```python
class Table(
    id: str,
    content: pandas.DataFrame,
    caption: Optional[str] = None,
    name: Optional[str] = None,
    references: Optional[List[str]] = None,
    raw_markdown: Optional[str] = None,
    pos_page: Optional[int] = None,
    pos_top: Optional[float] = None,
    pos_left: Optional[float] = None,
    pos_right: Optional[float] = None,
    pos_bottom: Optional[float] = None,
    metadata: Dict = field(default_factory=dict),
)
```

### Attributes

- `content` (`pandas.DataFrame`): Parsed tabular data.
- `caption` (`str`): Full table caption text.
- `references` (`List[str]`): In-text sentences referencing this table by number.
- `pos_left`, `pos_top`, `pos_right`, `pos_bottom` (`float`): Bounding box coordinates normalized to $[0.0, 1.0]$.

---

## `Figure`

Represents an extracted figure or diagram.

```python
class Figure(
    id: str,
    caption: Optional[str] = None,
    name: Optional[str] = None,
    references: Optional[List[str]] = None,
    image_path: Optional[str] = None,
    raw_markdown: Optional[str] = None,
    pos_page: Optional[int] = None,
    pos_top: Optional[float] = None,
    pos_left: Optional[float] = None,
    pos_right: Optional[float] = None,
    pos_bottom: Optional[float] = None,
    metadata: Dict = field(default_factory=dict),
)
```

---

## `Formula`

Represents an extracted math formula or equation.

```python
class Formula(
    id: str,
    latex: Optional[str] = None,
    raw_markdown: Optional[str] = None,
    name: Optional[str] = None,
    references: List[str] = field(default_factory=list),
    pos_page: Optional[int] = None,
    metadata: Dict = field(default_factory=dict),
)
```

---

## `Topic`

Represents an information retrieval query/topic.

```python
class Topic(
    query_id: str,
    query_text: str,
    context: Optional[Dict] = field(default_factory=dict),
    rewritten_texts: List[str] = field(default_factory=list),
    metadata: Dict = field(default_factory=dict),
)
```

---

## `Judgement`

Represents a synthetic relevance judgment.

```python
class Judgement(
    query_id: str,
    doc_id: str,
    score: int,
    source: str,
    chunk_id: Optional[str] = None,
    resource_id: Optional[str] = None,
    modality: str = "chunk",
    reasoning: Optional[str] = None,
    metadata: Dict = field(default_factory=dict),
)
```

### Properties

- `binary_score` (`int`): Returns `1` if `score >= 2` else `0`.