Skip to content
Embabel Worlds
Search
Ctrl
K
Cancel
GitHub
Select theme
Dark
Light
Auto
Menu
Guide
Realm spec
API
Blog
The realm specification
Overview
Repository convention
Directory Structure
Realm shapes
Realm source
realm.yml
actions/
goals/
types/
Overview
Persistence (graph-backed)
Populating types from an external system (deterministic, no code)
Joining types on demand (virtual joins, not mirrored)
producers/
Connected-account identity bridges (identityBridge:)
Identity bridges (resolve: chains) — link Person/Organization to any external system
CypherScript — Cypher woven into TypeScript/JavaScript
views/ — saved queries, and the two shapes they come in
lenses/
sources.yml — declaring how a COLLECTION behaves
Overview
The fields that carry real weight
Coverage — completeness is a fact in the graph, not a hope
visibility: public — a world's mirror, and why the scope differs from reference/
Filling a mirror before anyone asks — a whole index as graph
Source authority profile
lane: documents — a collection that lands as searchable DOCUMENTS
reference/
apis/
keys.yml — the keys a realm needs
src/ and tests/ — hand-authored TypeScript handlers
Overview
When to add TS handlers
Realm project layout
Handler signature
Type methods — classes that extend Entity
Manifest format
Build and test cycle
Install-time behaviour
Trust model
Author tooling
World execution and isolation boundary
Execution hosts
Overview
Placement
Authoring a wasm realm
Single file, or a typed project
The manifest, schedules, and type methods
Build on load
Limits
Shipping a compiled module
Three realms, three hosts
Captured handler schema profile
What placement never changes
Captured handler producers
mcp/
commands/
webhooks/
events/ — event ingestion
channels/ — realm-shipped channel connectors
agents/ — Agents and their Routines
Overview
Sweeps — the cold materializations an agent keeps filled
What an agent may ask for — forward-looking
Stage: off duty, observing, on duty
Signed versions
Talking to an agent
From an OpenAI client — host surface
What an inline routine sees
Activation — forward-looking
Routines that call a Realm Function, and dispatch-scoped replies — forward-looking
decorations/ — scheduled KG node enrichment
apps/
artifacts.yml
LLM roles
prompts/
skills/
notebook/
personalities/
focuses/
tests/
seed/
hints/
Validating a realm in CI
Installation
Realm Discovery
What's intentionally not in a realm
Conventions
Versioning
License
Virtual Cypher: a guide
Overview
The idea in one paragraph
3. Worked examples
Overview
3.1 The simplest join — id-match (Person → HubSpot contact by email)
3.2 A bridge plus a downstream hop (Person → GitHub identity → issues)
3.3 A literal-seeded anchor — fetch anyone's data through your credentials
3.4 Predicate pushdown — scope the fetch at the source
3.5 Pagination, batching, and the starvation trap (batchSafe)
3.6 Brought sub-graph — parent and children in one fetch
3.7 Filtered anchors — fetch only what survives the filter
3.8 Existence and intersection across sources (EXISTS / NOT EXISTS / OR)
3.9 Fan-out aggregate — count over fetched data
3.10 Vector edge — similarity is the join (RELEVANT_TO + r.score)
3.11 A bridge reachable only through another virtual node (staged re-planning)
3.12 Convergence — the same node reached two ways
3.13 One anchor, many keys — joining on a list-valued property
3.14 Narrowing at the source — membership pushdown
3.15 Attributed reporting — prose that arrives with its receipts
3.16 Statistics over a cross-section — correlate and regress
3.17 Text into the graph, and one query as a pipeline — ai.fromText
3.18 Asking the spine for a key — canonicalize
3.19 Ask for the result, not the steps — a goal view, then English
3.20 When the person's words are not the data's — ai.terms
Where to go next
Virtual Cypher: reference
Overview
1. What Virtual Cypher is
2. The execution model
3. Worked examples — see the User Guide
4. What is not possible — and why
5. The join surface (reference)
Overview
5.1 Two link shapes (same engine)
5.2 Identity bridges — resolve: chains
5.2.1 What a join may make DURABLE, and what it may not
5.3 Producer kinds
5.4 Entity canonicalization — the spines a join anchors on
5.5 Graph-cached aggregates — cache: {kind: graph}
5.6 Typed extraction — kind: extract (lazy entities)
5.7 keyTransform — rewriting the key into the source's own query language
5.8 tabular — a published file as a joinable source
5.9 Range partitioning — partition: on a remote producer
5.10 feed — an RSS/Atom feed as a keyed source
5.11 Enumerated anchors — WHERE anchor.key IN [...]
5.12 Bounded variable-length traversal — self-recursive joins
5.13 Timely sources — cache: currency and the freshness result block
5.13.1 Kept records — cache: {kind: graph} on any producer
5.14 sparql — a SPARQL endpoint as a keyed source
5.15 cypher — a remote graph as a keyed source, and the governance: grammar
5.16 elasticsearch — a search index as a relevance source
5.17 Calendar history — periods: on a remote producer
5.18 jar — a Java jar's classes as a keyed source
5.19 source-tree with from: jar — the source a jar was compiled from
5.20 stacktrace — a Java stack trace as a keyed source
5.21 source-tree — a project's source in any of fourteen languages
6. Vector edges — semantic joins in depth
7. LLM query primitives — filter, rerank, and steer with the ai namespace
Overview
7.1 The ai and realm namespaces are reserved
7.2 The {ai: {…}} directive map — steer and tune a fetch
7.3 ai.relevant — the per-row relevance filter
7.4 ai.score — the per-row rerank
7.5 ai.classify — the per-row projection
7.6 Cost, determinism, and failure
7.6.1 Gating an expensive judgment — what actually narrows it
7.7 Aggregations — reduce a whole GROUP to one cell
7.8 ai.fromText — project a typed graph shape out of text
7.9 Writing projected types inside a query — one query is a pipeline
7.10 ai.terms — a model suggests what to look for; the data decides what exists
8. Views — a saved query used as a label
9. Caps, cost, and diagnostics
Overview
9.1 Fills — driving a large materialization slowly
9.2 Host-defined limits and defaults
10. Steering the generator — type-level examples:
11. Determinism and guarantees
12. Graph annotation writes — bounded local writes after federated selection
13. Derived labels and relationships — DERIVE rules
Overview
13.1 Params, and anchoring a rule
13.2 What a rule may say — the validated fragment
13.3 Conclusions are computed, never stored — and they carry their why
13.4 Derived relationships — an edge whose existence is a conclusion
13.5 Guidance
13.6 What a rule set may assume about its facts
13.7 What a rule set costs — quoted before it runs
14. The contract, in one line
15. Scope — per-user accessibility, per-world focus
16. Planning: ask for the result, not the steps
Overview
16.1 The model
16.2 Introspection — what a step needs and makes
16.3 What makes a view plannable
16.4 Inputs
16.5 Outcomes — none is a guess
16.6 Costing — stored before API before AI
16.7 Scope
16.8 Explain, then run — the plan tool and its endpoints
16.9 English mode — the question writes the goal
16.10 Goal views — a saved answer whose steps are planned
16.11 What is not here yet
Realms in TypeScript
Overview
Contents
Build a realm
App limits and profiles
Realm metadata
Handlers
The handler context
The model call
Credentials
APIs
GraphQL
Channels
Sources, consumers and triggers
Publishing events
Dependencies
Types
Producers
Graph queries and view references
Goals
Lenses and watches
Apps
Write proposals
Owner approval, step by step
Limits at a glance
Declaration coverage and open contracts
Declaring types
Overview
TypeScript object declarations
Legacy declarations
1. The two forms
2. Vocabulary
3. What each form expresses
4. What TypeScript checks that YAML does not
5. Where each legacy form is available
6. What stays data
Changelog
Labels and composition
External documents
GitHub
Select theme
Dark
Light
Auto
Legacy declarations
The rest of this document describes the supported legacy type forms.