@spheredata/embed

The embeddable SPHERE agent UI — a framework-agnostic <sphere-agent> Web Component any web page can drop in, plus optional in-browser tool packs. Shadow DOM keeps the host's CSS isolated; the agent loop runs client-side.

The product/brand is SPHERE — this package is published under the @spheredata npm scope. The custom element is <sphere-agent> and the design tokens are --sphere-* (unchanged).

Install

npm i @spheredata/embed @spheredata/sdk

A partner needs both: @spheredata/sdk provides createSphere (the backend client), and this package provides the UI element you wire it into.

Quick start

<sphere-agent id="agent" layout="split" attachments>
  <span slot="title">SPHERE Agent · ADRC</span>
  <span slot="notice">Python runs locally; your data never leaves the page.</span>
</sphere-agent>

<script type="module">
  import { createSphere } from "@spheredata/sdk";
  import { pyodideTools, learningStore } from "@spheredata/embed/tools";
  import "@spheredata/embed"; // registers the <sphere-agent> element

  const sphere = createSphere({ portal: "adrc" });
  const mem = learningStore(sphere.portal);

  const el = document.getElementById("agent");
  el.sphere = sphere;
  el.systemPrompt = "You are a SPHERE data analyst…";
  el.examples = ["What datasets are available?"];
  el.tools = [...pyodideTools({ baseUrl: "/data/", datasets: { scrna: "scrna.csv" } }), mem.tool];
  el.seed = mem.seed;   // inject prior learnings at the start of each conversation
  el.memory = mem;      // drive the memory badge (count())
</script>

Element API (properties)

| Property | Type | Purpose | | --- | --- | --- | | sphere | client | The @spheredata/sdk client (required). | | systemPrompt | string | System message for the agent. | | tools | array | Tool objects { name, description, input_schema, run() }. | | examples | string[] | Starter prompts shown in the welcome state. | | model | string | Model id override. | | maxTokens | number | Completion cap (default 4096). | | layout | "chat" | "split" | Single pane, or two-pane with a results panel for figures. | | attachments | boolean | Enable file attach in the composer. | | accountUrl | string | Where the "Add credits" link redirects (billing is never embedded). | | seed | () => messages[] | Inject prior messages/learnings at conversation start. | | seedMessages | array | Static alternative to seed(). | | memory | { count() } | Drives the memory badge. |

Reflected attributes: layout, attachments, account-url. Slots: title, notice.

Tool packs — @spheredata/embed/tools

• pyodideTools({ baseUrl, datasets, dataDictionary, packages }) — Python/pandas in the browser (load datasets, run code, return figures). No server round-trip.
• learningStore(namespace, storage?) — persistent per-portal memory; exposes .tool, .seed, and .count().
• calculatorTool — safe arithmetic.
• resolveDatasetUrl(baseUrl, datasets, name) — helper for dataset URL resolution.

Theming

Defaults are the SPHERE brand and match @spheredata/design token values, so a host that imports @spheredata/design/tokens.css looks identical. To re-skin per partner, override any of this Tier-2 contract on a host ancestor (e.g. :root or the element):

:root {
  --sphere-accent: #1d4ed8;
  --sphere-accent-hover: #1e40af;
  --sphere-radius: 6px;
  --sphere-font: "Inter", sans-serif;
  --sphere-surface: #ffffff;
  --sphere-panel: #eef2ff;
  --sphere-user-bg: #e0e7ff;
}

Full contract: --sphere-accent, --sphere-accent-hover, --sphere-radius, --sphere-font, --sphere-surface, --sphere-panel, --sphere-line, --sphere-text, --sphere-text-muted, --sphere-user-bg, --sphere-good, --sphere-warn, --sphere-danger, --sphere-results-bg, --sphere-results-width.

License

MIT