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

# TDF (Timepoint Data Format)

> JSON-LD interchange format connecting all Timepoint services. Content-addressed via SHA-256.

# TDF — Timepoint Data Format

**The universal data contract.** JSON-LD interchange format for temporal causal data. Every service in the Timepoint suite speaks TDF. Content-addressed via SHA-256 hash.

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/timepointai/timepoint-tdf">
    `timepointai/timepoint-tdf` — Apache-2.0, Pure Python, Pydantic
  </Card>

  <Card title="Detailed Docs" icon="book" href="https://github.com/timepointai/timepoint-tdf">
    Full schema reference, transforms, and integration docs
  </Card>
</CardGroup>

## Record Structure

```python theme={null}
TDFRecord:
    id: str           # Clockchain canonical URL or Flash UUID
    version: str      # "1.0.0"
    source: str       # "clockchain" | "flash" | "proteus" | "snag-bench"
    timestamp: datetime
    provenance: TDFProvenance
        generator: str
        run_id: str
        confidence: float
        flash_id: str | None
    payload: dict     # Source-specific content
    tdf_hash: str     # SHA-256 of canonicalized payload
```

## Transforms

Convert service-specific output to TDF:

```python theme={null}
from timepoint_tdf import from_flash, from_clockchain

# From Flash scene
tdf_record = from_flash(flash_output)

# From Clockchain node
tdf_record = from_clockchain(node_data)
```

## Content Addressing

Every TDF record includes a `tdf_hash` — the SHA-256 of the canonicalized payload. This enables:

* **Deduplication** across services
* **Integrity verification** end-to-end
* **Immutable references** between graph nodes

## Installation

```bash theme={null}
pip install -e "git+https://github.com/timepointai/timepoint-tdf.git#egg=timepoint-tdf"
```

Single dependency: `pydantic>=2.0`

## Service Integration

TDF is a pure library at the center. It provides transform functions — `from_flash()`, `from_clockchain()`, and a planned Proteus transform — that convert each service's output into the shared TDF format.

```
                ┌──────────────┐
                │  TDF v1.0.0  │
                │  (pure lib)  │
                └──────┬───────┘
                       │
          ┌────────────┼─────────────┐
          │            │             │
     from_flash() from_clockchain() (planned)
          │            │             │
     ┌────▼───┐  ┌────▼──────┐  ┌────▼────┐
     │ Flash  │  │Clockchain │  │Proteus  │
     └────────┘  └───────────┘  └─────────┘
```