Type Hierarchy¶

Complete reference for all types in the graph type system.

Type Tree¶

GraphType
├── Primitive
│   ├── void
│   ├── bool
│   ├── int
│   ├── float
│   ├── string
│   ├── bytes
│   └── datetime
├── Domain (semantic types backed by primitives)
│   ├── Url          (string)
│   ├── Html         (string)
│   ├── Markdown     (string)
│   ├── Text         (string)
│   ├── Query        (string)
│   ├── Json         (string)
│   ├── Entity       (object)
│   ├── Chunk        (object)
│   ├── Vector       (float[])
│   ├── GeoPoint     (object)
│   ├── Image        (bytes)
│   └── Pdf          (bytes)
├── Collection[T]    (arrays of any type)
├── Compound         (structured objects with fields)
└── Union            (A | B | C alternatives)

Primitive Types¶

Basic data types that map directly to Python types.

Type	Python	Description	Example
`void`	`None`	No data (side-effect only)	-
`bool`	`bool`	Boolean	`true`, `false`
`int`	`int`	Integer	`42`, `-17`
`float`	`float`	Floating-point	`3.14`, `-0.5`
`string`	`str`	UTF-8 text	`"hello"`
`bytes`	`bytes`	Binary data	`b'\x00\x01'`
`datetime`	`datetime`	ISO 8601 timestamp	`"2024-01-15T10:30:00Z"`

Domain Types¶

Semantic types that add meaning to primitives.

String-Based Domain Types¶

Type	Base	Validation	Description
`Url`	string	RFC 3986 URI	HTTP/HTTPS/Onion URL
`Html`	string	Contains HTML tags	HTML document content
`Markdown`	string	Valid markdown	Markdown formatted text
`Text`	string	Non-empty	Plain text content
`Query`	string	Non-empty	Search query
`Json`	string	Valid JSON	JSON document

Object-Based Domain Types¶

Entity¶

Entity:
  fields:
    text: string          # The entity text
    type: EntityType      # person|organization|location|event|topic|date|unknown
    confidence: float     # 0.0 to 1.0
    context: string?      # Optional surrounding context
    start_offset: int?    # Character offset in source
    end_offset: int?      # Character offset in source

Chunk¶

Chunk:
  fields:
    text: string          # Chunk content
    chunk_id: string      # Unique identifier
    word_count: int       # Number of words
    quality_score: float? # Optional quality metric (0.0 to 1.0)
    vector: Vector?       # Optional embedding
    source_url: Url?      # Source URL if known
    metadata: object?     # Additional metadata

GeoPoint¶

GeoPoint:
  fields:
    lat: float           # Latitude (-90 to 90)
    lon: float           # Longitude (-180 to 180)
    accuracy: float?     # Accuracy in meters
    source: string?      # Geocoding source

TorResult¶

TorResult:
  fields:
    url: Url             # Onion or clearnet URL
    title: string?       # Page title
    description: string? # Snippet/description
    engine: string       # Search engine used
    score: float?        # Relevance score

Binary Domain Types¶

Type	Base	Format	Description
`Image`	bytes	PNG/JPEG/WebP	Image binary data
`Pdf`	bytes	PDF	PDF document

Numeric Domain Type¶

Vector¶

Vector:
  base: float[]
  constraints:
    - dimensions: [384, 768, 1024, 1536]  # Common embedding sizes

Collection Types¶

Collections wrap any type to represent arrays.

Syntax¶

Collection[T]   # Full syntax
T[]             # Shorthand

Examples¶

Url[]           # Array of URLs
Chunk[]         # Array of chunks
Entity[]        # Array of entities
Vector[]        # Array of vectors
string[]        # Array of strings

Collection Operations¶

Operation	Input	Output	Description
`first`	`T[]`	`T`	Get first element
`last`	`T[]`	`T`	Get last element
`count`	`T[]`	`int`	Get array length
`flatten`	`T[][]`	`T[]`	Flatten nested arrays
`unique`	`T[]`	`T[]`	Remove duplicates

Compound Types¶

Structured objects with named fields.

Definition¶

types:
  SearchResult:
    fields:
      urls: Url[]
      query: Query
      total_count: int
      search_engine: string

  DocumentAnalysis:
    fields:
      summary: Text
      entities: Entity[]
      topics: string[]
      sentiment: float

Usage¶

- op: search
  output:
    type: SearchResult
    name: results

Union Types¶

Value can be one of several types.

Syntax¶

A | B | C       # Value can be A, B, or C

Examples¶

Text | Html     # Either plain text or HTML
Url | Url[]     # Single URL or array of URLs
string | null   # Optional string

Usage¶

inputs:
  - name: content
    type: Text | Html
    description: Content in either format

EntityType Enum¶

class EntityType(str, Enum):
    PERSON = "person"
    ORGANIZATION = "organization"
    LOCATION = "location"
    EVENT = "event"
    TOPIC = "topic"
    DATE = "date"
    MONEY = "money"
    PERCENT = "percent"
    UNKNOWN = "unknown"

Common Vector Dimensions¶

Model	Dimensions
all-MiniLM-L6-v2	384
all-mpnet-base-v2	768
nomic-embed-text	768
mxbai-embed-large	1024
text-embedding-ada-002	1536
text-embedding-3-small	1536