Intuition Data Structures

This package defines the canonical data contracts for atom classification and atom enrichment in Intuition.

If you are new to this area, the key idea is:

• store minimal identity onchain
• attach rich metadata offchain

Atom Classification (Identity Layer)

Atom classification is the canonical, minimal shape of an entity in Intuition. It is designed for durability and onchain use: enough data to identify the entity and disambiguate it, but not enough to become stale quickly.

Classification output is type-first and identity-first:

{
  "type": "Person",
  "data": {
    "@context": "https://schema.org/",
    "@type": "Person",
    "name": "Brad Pitt",
    "sameAs": ["https://www.wikidata.org/wiki/Q35332"]
  }
}

Atom Enrichment (Context Layer)

Atom enrichment is refreshable, offchain context attached to a classified atom. It captures provider-specific metadata that changes over time (descriptions, media, links, stats, market data, and other dynamic fields), without mutating the atom's core identity.

Enrichment output always uses a shared artifact envelope:

{
  "artifact_type": "wikipedia",
  "data": {
    "summary": "American actor and film producer"
  },
  "meta": {
    "pluginId": "wikipedia",
    "provider": "wikipedia",
    "fetchedAt": "2026-02-26T12:00:00Z",
    "sourceUrl": "https://www.wikidata.org/wiki/Q35332"
  }
}

How They Work Together

1. Classify the input into a minimal canonical atom shape.
2. Persist/reference that stable identity onchain.
3. Attach and refresh enrichment artifacts offchain as better context becomes available.
4. Compose identity + context at read time for product UX and search.

Why This Matters

Atoms are the core identity primitives in the Intuition graph. If atoms contain too many mutable fields (images, long descriptions, changing URLs), they become stale and expensive to maintain.

Instead, this package enforces minimal atom payloads that are durable over time. Rich context still exists, but as enrichment artifacts that can be refreshed independently.

Design Principles

1. Minimal by default: keep only the smallest viable identity payload in base atoms.
2. Durable over complete: prefer fields that are stable over time.
3. Separate identity and context:
   • onchain atom = identity
   • offchain enrichment = context
4. Flat taxonomy: each classification type is a top-level category in this repo.
5. Extensible by artifacts: new metadata sources should not require changing core atom identity.

Onchain vs Offchain

Layer	Purpose	Typical Data
On-chain Atom	Stable identity	name, canonical type, minimal disambiguators
Off-chain Enrichment	Rich context for UX/search	images, descriptions, social links, provider-specific fields

What Is In This Folder

• classifications/
  • one folder per classification type
  • each file defines:
    • minimal Atom Data
    • Atom Classification envelope
    • an example payload
• enrichment/
  • provider-specific enrichment schemas
  • shared artifact envelope conventions

URL to Atom to Enrichment Flow

1. Input URL

https://en.wikipedia.org/wiki/Brad_Pitt

2. Classification Output (Minimal)

{
  "type": "Person",
  "data": {
    "@context": "https://schema.org/",
    "@type": "Person",
    "name": "Brad Pitt",
    "sameAs": ["https://www.wikidata.org/wiki/Q35332"]
  }
}

3. Onchain Atom

Only the minimal atom data is committed onchain.

4. Offchain Enrichment Artifact

{
  "artifact_type": "person",
  "data": {
    "image": "https://upload.wikimedia.org/example.jpg",
    "description": "American actor and film producer"
  },
  "meta": {
    "pluginId": "wikidata",
    "provider": "wikidata",
    "fetchedAt": "2026-02-26T12:00:00Z",
    "sourceUrl": "https://www.wikidata.org/wiki/Q35332",
    "confidence": 0.98
  }
}

5. Query-Time Composition

Clients compose:

• stable atom identity from onchain data
• latest enrichment artifacts from backend services

This provides rich UX without bloating atom payloads.

Flat Classification Catalog

Each type below is a first-class top-level classification:

• Thing (Thing)
• Person (Person)
• Company (Organization)
• Location (Place)
• Product (Product)
• Service (Service)
• Software (SoftwareSourceCode)
• Music Recording (MusicRecording)
• Music Album (MusicAlbum)
• Music Group (MusicGroup)
• Book (Book)
• Article (Article)
• News Article (NewsArticle)
• Social Media Posting (SocialMediaPosting)
• Comment (Comment)
• Review (Review)
• Aggregate Rating (AggregateRating)
• Image (ImageObject)
• Video Object (VideoObject)
• Movie (Movie)
• TV Series (TVSeries)
• Podcast Series (PodcastSeries)
• Podcast Episode (PodcastEpisode)
• Event (Event)
• Web Site (WebSite)
• Web Page (WebPage)
• Brand (Brand)
• Software Application (SoftwareApplication)
• Mobile Application (MobileApplication)
• Dataset (Dataset)
• Job Posting (JobPosting)
• Local Business (LocalBusiness)
• Defined Term (DefinedTerm)
• Ethereum Account (EthereumAccount)
• Ethereum Smart Contract (EthereumSmartContract)
• Ethereum ERC20 (EthereumERC20)

Minimal Atom Examples

Person

{
  "@context": "https://schema.org/",
  "@type": "Person",
  "name": "Brad Pitt",
  "sameAs": ["https://www.wikidata.org/wiki/Q35332"]
}

Company

{
  "@context": "https://schema.org/",
  "@type": "Organization",
  "name": "OpenAI",
  "url": "https://openai.com"
}

Software

{
  "@context": "https://schema.org/",
  "@type": "SoftwareSourceCode",
  "name": "Bun",
  "codeRepository": "https://github.com/oven-sh/bun"
}

Music Recording

{
  "@context": "https://schema.org/",
  "@type": "MusicRecording",
  "name": "Bohemian Rhapsody",
  "byArtist": "Queen",
  "inAlbum": "A Night at the Opera"
}

Ethereum Smart Contract

{
  "chainId": "1",
  "address": "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}

Enrichment Artifact Envelope

All enrichment payloads follow this common envelope:

{
  "artifact_type": "<classification_slug>",
  "data": {},
  "meta": {
    "pluginId": "<plugin_slug>",
    "provider": "<provider_name>",
    "fetchedAt": "<iso_datetime>",
    "sourceUrl": "<source_url_if_available>",
    "confidence": "<number_0_to_1_if_available>",
    "fromCache": "<boolean_if_available>",
    "cachedAt": "<iso_datetime_if_available>"
  }
}

Provider examples:

• AI Entities
• AI Summary
• Apple Music
• arXiv
• Brand
• CoinGecko
• Color Palette
• Company Profile
• Crossref
• Crunchbase
• Dictionary
• ENS
• Etherscan
• Favicon
• Geocode
• GitHub
• ISBN
• Microdata
• MusicBrainz
• NFT Metadata
• NPM
• oEmbed
• OpenGraph
• Places
• Product Listing
• Pubmed
• Reddit Post
• Screenshot
• Spotify
• TMDB
• Twitter Profile
• Vimeo
• Wikidata
• Wikipedia
• YouTube

Adding a New Classification

1. Create classifications/<type-slug>/index.md.
2. Keep required fields minimal and identity-focused.
3. Move mutable metadata to enrichment artifacts.
4. Include:
   • Atom Data
   • Atom Classification
   • one concrete example