Yarlis Assistant

AI chat assistants for websites: a streaming chat service that answers from a site's own docs, with one profile per site, and the widget that embeds it. Sam (rulescascade.com) runs from this repository; Maxi (sdods.com) runs the same engine from npm with SDODS's own step tools.

site page ── <script src=…/widget.js> ── POST /chat (SSE) ──► Cloud Run <id>-assistant ──► Claude API
                                                                │   ├─ web_fetch (index mode, own domains)
                                                                │   └─ MCP connector → the product's MCP server
                                                                ├─ Secret Manager: <id>-anthropic-key
                                                                └─ Firestore: <id>Chats, <id>Usage

What a profile sets

assistants/<id>.yaml (schema and defaults: src/profile.ts): the persona, what it knows, its tools, the wording of its errors, who may call it and what its widget looks like.

| Assistant | Site | Knowledge | Tools | Service | | --- | --- | --- | --- | --- | | Sam | rulescascade.com | index: rulescascade.com/llms.txt, pages fetched with web_fetch (rulescascade.com only) | the hosted Rule Cascade MCP server (read-only), through the MCP connector | sam-assistant | | Maxi | sdods.com, docs.sdods.com | full: docs.sdods.com/llms-full.txt in the cached prompt | find_steps, validate_feature (SDODS's own, packages/maxi in sdods) | sdods-maxi, deployed from sdods |

Knowledge modes. full sends the whole corpus on every turn (cached for an hour), which fits a corpus up to roughly 150K tokens. index sends an index and lets the assistant fetch the pages a question needs, for anything bigger.

Embedding

Any site adds one tag; the script reads the service's /widget.json and mounts the chat in a shadow root, so neither page's CSS reaches the other:

<script src="https://<domain>/widget.js" defer></script>

<domain> is the profile's domain:, a subdomain of the product the assistant serves (Sam is sam.rulescascade.com). It is a Cloud Run domain mapping, which costs nothing, and it keeps the run.app URL out of every site, so a service can move to another project without a site change.

A React site can render the chat itself:

import { AssistantChat } from '@yarlisai/assistant/widget';
import '@yarlisai/assistant/styles.css';

<AssistantChat endpoint={process.env.NEXT_PUBLIC_SAM_URL} name="Sam" greeting="Hi, I'm Sam." />;

The package

@yarlisai/assistant on npm:

| Import | What | | --- | --- | | @yarlisai/assistant | the engine: startAssistant, buildAssistantServer, runChat, profiles, the corpus, the stores | | @yarlisai/assistant/widget | AssistantChat and its helpers (React 19) | | @yarlisai/assistant/styles.css | the widget's styles | | @yarlisai/assistant/widget.js | the built embed script, for an image that serves /widget.js | | @yarlisai/assistant/testing | fakeClient, a scripted stand-in for the Claude API |

Started from the package (not the image), a YAML profile needs ASSISTANTS_DIR pointing at the folder that holds <id>.yaml: the package ships the engine, not the profiles.

A host with tools that must run inside the service passes them in:

import { startAssistant } from '@yarlisai/assistant';

await startAssistant({ builtin: MY_PROFILE, tools: () => ({ definitions, run }) });

Develop

bun install
bun run type-check && bun run test && bun run build
ASSISTANT=sam ANTHROPIC_API_KEY=… bun run dev

Deploy

| Once per | Step | | --- | --- | | GCP project | a person creates yarlis-assistant and links billing; then bash deploy/setup-project.sh and set the two repository variables it prints | | assistant | a person makes its Anthropic key in its own Console workspace with a monthly spend limit, stored as <id>-anthropic-key (ykeep); then bash deploy/provision-assistant.sh <id>, and its Firestore rules pair (firebase deploy --only firestore:rules --project yarlis-assistant) | | assistant domain | set domain: in the profile; after the first deploy, run provision-assistant.sh <id> again (as a verified owner of the domain) to map it, add the CNAME to ghs.googlehosted.com. it prints (yarlis-networks scripts/dns-txt.sh cname), and declare the host in yarlis-networks apps/assistant.env | | change | merge to main: the deploy workflow builds one image and deploys every provisioned profile |

The site-assistant skill (.claude/skills/site-assistant) walks through adding and operating one. Publishing: bump version in package.json; merging it publishes to npm (release workflow).

Licence

Apache-2.0.