aspace://realm/mapping

The mapping

This page is the middle step of the better-together picture: how a realm's definitions become the fleet's cards. An import drafts a record for each part and marks it with the realm's name. Once a person approves the draft, it reaches the group as an AgentSpaces record.

AgentSpaces 0.6.0Embabel agentsEmbabel realms
What each part becomesAn app card from a realmHow an import runsNext: the worked example
aspace://realm/becomes

What each part becomes

Realm partIn the group, once a person approves the draftrealmname, version, namespaceorigin on each AppCard; the namespace of each entry typetypesentry types: the namespace followed by the type nameproducersremote, apian AssetCard per operation, from a REST connectorproducerssqlan AssetCard per query, from a SQL connectorproducerscompute, vector, jar, ...AgentCards of a fleet package that serves <realm>/<producer>apisa FlowManifest with a code stage per listed operationpromptsthe group's prompt set, carried as a configurationappsan AppCard with origin realm and the link app://<realm>/<app>
What each part becomes. An import drafts a record for each realm part, and once a person approves it, it reaches the group as an AgentSpaces record.
Realm part AgentSpaces record in the group
realm (name, version, commit, namespace)origin on each app card (below), and the namespace of every entry type IRI
typesentries whose schema name is the type's IRI, the namespace followed by the type name, such as https://acme.example/realm/claims-ops#Claim
producers of kind remote or apian AssetCard per operation, from an OpenAPI 3.x and REST connector, configured with the API's location, a credential reference, the operation, the base URL from the document's first server, and the auth scheme
producers of kind sqlan AssetCard per query, from a SQL connector, configured with the datasource and the query
producers of any other kindthe AgentCards of a fleet package that serves the agent kind <realm>/<producer>, configured with the producer's fields
apisa FlowManifest with one code stage per listed operation, on a lane named after the API; the operation's request schema cues each stage, its parameters are cue fields, and its response schema is the result
promptsthe group's prompt set, carried as a configuration
appsan AppCard with owner the realm, origin realm, formats with the realm's namespace, and the app link app://<realm>/<app>

A realm imports into one group per import, and creates no group. It names no spaces of its own: the lanes come from the flows its APIs become. A realm ships no code to the fleet either, so a fleet package serves the producer kinds that no connector serves.

The realm's type names become the vocabulary of the fleet. A Claim the realm declares is the shape of the Claim entries agents write into the group's lanes. A flow's stage is cued by a type, and a planner's goal is achieve Payment. The Embabel guide shows an Embabel agent naming its records by the realm's namespace.

aspace://realm/appcard

An app card from a realm

An AppCard whose origin.system is realm keeps the realm's provenance on the wire. The group's members find a realm's apps by discovery, by origin, and by format. AgentSpaces and Realm (REALM.md in the AgentSpaces specification) ยง5 defines the card, and it is normative with SPEC v0.1.33.

Field What it holds
origin.ref<realm>/<app>
origin.versionthe realm's own semver, 0.0.0 when the realm names none, and empty for a version of another form
origin.attrs["realm.format"]the form the import read and the commit of the Embabel Realm Specification its reader follows, such as yaml@<commit>
origin.attrs["realm.namespace"]the realm's namespace, or urn:realm:<realm># when it names none
origin.attrs["realm.digest"]the SHA-256 of the import document (SHOULD)
origin.attrs["realm.reads"], ["realm.commit"]the type names the app reads, and the commit the realm's files came from (MAY)
ownerthe realm's name
urlthe app link app://<realm>/<app>, which a world that installs the realm serves at /apps/<realm>/<app>.html
formatstext/html first for an HTML page, then the realm's namespace

The card constrains no kind, and a reader never refuses a card for its kind or its origin. The issuer signs that the app, the version, the namespace, the commit, and the type names are the import document's own. The card makes no claim that the realm's authors approved the publication.

aspace://realm/import

How an import runs

An import reads one document, the import document. It is a realm folded by hand into one YAML file, with the parts as top-level keys, each OpenAPI document inline under its API, and each agent's prompt file inline under promptText. Its shape follows the legacy YAML form of a realm in the Embabel Realm Specification at commit 89faba6. Two of its keys are its own: commit, the commit the realm's files came from, and namespace, the IRI (RFC 3987) namespace of the realm's types. The worked example shows one.

Embabel now prefers realm.ts, a realm written in TypeScript that a world's host evaluates directly. No tool turns it into YAML yet, so an import cannot read a realm.ts realm today.

The realma person folds its filesby hand into one YAMLimport documentThe importreads the document, draftsa record per part, markseach with the realm, andwrites a reportA personapproves the set of draftsthis use case needsThe groupconnectors serveAssetCards, packagespublish AgentCards, flowsrun, members find AppCardsdocumentdraftsapprovedthe import's report goes back: what the reader could not use, which fleet package is missingnothing a realm proposes runs before a person approves it; a second import drafts new versions and changes nothing in force
How an import runs. One direction only, realm to group. The report comes back with the import's answer.
  1. Fold. A person folds the realm's files into one import document, by hand today.
  2. Import. A person or a script hands the import document to an importer, with the target group.
  3. Draft. The importer drafts one record per type, producer, API, prompt, and app, and marks each with the realm's name. Its answer carries a report of what it could not use. It never guesses a missing piece.
  4. Approve. A person reviews what one import proposed, and approves the set the use case needs.
  5. Serve. The approved records reach the group. The connectors publish AssetCards, a fleet package's agents publish AgentCards, the reconciler applies the FlowManifests, and members find the AppCards by discovery.
  6. Import again. A second import of the same realm drafts new versions of the same records, and nothing in force changes until a person approves it.

Data moves one way. Nothing writes back into a realm, and what the agents produce stays in the group's spaces.