ATLAS Explain
Market jargon in plain language: terms, official figures, crypto prices and charts, headlines.
التثبيت
أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: .cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).
claude mcp add --transport http atlas-explain 'https://atlas-explain-mcp.atlas-explain.workers.dev/mcp'
{
"mcpServers": {
"atlas-explain": {
"type": "http",
"url": "https://atlas-explain-mcp.atlas-explain.workers.dev/mcp"
}
}
}
التوثيق
مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.
المحتويات
- ATLAS Explain
- Value proposition
- How Firebase AI Logic hybrid inference is used
- Architecture
- Setup
- Deploy
- Deep links, desk hand-off, and concepts
- Connecting to ATLAS
- For AI assistants (MCP)
- Screenshots
- On-device model in Chrome
- Demo
- Chrome extension
- Tests and CI
- Limitations
- Relationship to ATLAS
- What to build next
- License
ATLAS Explain
Educational explanations of a market move. After a sharp drop, ATLAS Explain turns a structured move card into a balanced account of why a buyer might see opportunity and why a seller might see further risk. It is free to use, Apache-2.0, and it does not tell anyone to trade.
The model runs through Firebase AI Logic hybrid inference. Chrome uses Gemini Nano on the device when that model is available, and Gemini in the cloud when it is not. The screen names the path that actually ran.
This is an entry for Google's #BuildHybridAI 2026 hackathon.
Educational explanations only. Not financial advice, not a recommendation, and not an offer to buy or sell any security.
Value proposition
A sharp move can support two careful readings at once. Someone might buy a dip because the drop looks larger than the new information. Someone else might sell because the same information can keep pressuring the price. ATLAS Explain makes both readings explicit from a move card the user supplies: symbol, percent move, volume versus normal, the market and sector that day, peers, volatility, upcoming events, and optional headlines.
Headline text is classified into a fixed taxonomy: AI capex, China / export rules, scandal / governance, earnings / guidance, rates / Fed, macro shock, or other. The answer is always three buyer reasons, three seller reasons, and what would change the picture.
Private notes and a watchlist can ride along only when the on-device model runs. They are omitted from cloud prompts and they are never written to Firestore.
How Firebase AI Logic hybrid inference is used
The web client uses the Firebase JavaScript SDK (firebase@13.3.0) and the hybrid API documented here:
- Build hybrid experiences in Web apps
- Configuration options
- Structured output for hybrid experiences
InferenceModereference
Checked against @firebase/ai 3.1.0 typings shipped with that SDK. The calls are:
| Step | API | Where it runs |
|---|---|---|
| Gemini Developer API backend | getAI(app, { backend: new GoogleAIBackend() }) | src/platform/web/explainer.ts line 45 |
| Mode | InferenceMode.PREFER_ON_DEVICE, ONLY_ON_DEVICE, PREFER_IN_CLOUD, or ONLY_IN_CLOUD | src/platform/web/explainer.ts lines 37–41 |
| Model | getGenerativeModel(ai, { mode, inCloudParams, onDeviceParams }) | src/platform/web/explainer.ts lines 95–125 |
| On-device init, after the Explain click | model.initializeDeviceModel(onDownloadProgress) | src/platform/web/explainer.ts lines 127–132 |
| Inference | model.generateContent(prompt) | src/platform/web/explainer.ts line 144 |
| Which path ran | result.response.inferenceSource (on_device or in_cloud) | src/platform/web/explainer.ts lines 148 and 159–167 |
inCloudParams.generationConfig sets responseMimeType: "application/json" and a responseSchema built with Schema.object / Schema.enumString. The same schema is passed to the on-device model as onDeviceParams.promptOptions.responseConstraint, which is what the hybrid structured-output guide requires so both paths return the same shape.
The cloud model id defaults to gemini-3.5-flash-lite (the SDK 13 default) and can be changed with Remote Config. Temperature is not sent: the SDK marks it unsupported on Gemini 3.x and later.
Path selection before that call lives in src/core/inference-path.ts (selectInferencePath, line 20) and is applied in src/core/run-explanation.ts (lines 52 and 69):
- Remote Config
inference_modeis the preference. The in-app default isprefer_on_device. - More than 8 headlines, a prompt over 6,000 characters, or a document over 1,200 characters forces
ONLY_IN_CLOUD. On-device Gemini Nano's context is 9,216 tokens. - Notes and the watchlist are included only on an
ONLY_ON_DEVICEcall. If the device model is unavailable and the preference wasprefer_on_device, the app retries once in the cloud with those fields removed.
App Check, Remote Config, and Firestore are started in src/platform/web/backend.ts:
- App Check with
ReCaptchaEnterpriseProvider: lines 58–61. A debug token is assigned just above that, and only innpm run dev. - Remote Config
fetchAndActivateandgetValue: lines 65–89. In-app defaults insrc/core/settings.tsmatchremoteconfig.template.json. - Firestore
addDocunderusers/{uid}/explanations: line 117. Anonymous Authentication supplies the uid.
Without a Firebase web config and a reCAPTCHA Enterprise site key, src/main.ts lines 27–28 render a setup screen and do not initialize Firebase.
Architecture
src/core has no Firebase and no DOM. A Chrome extension or an Android shell can reuse the move card, the prompt, the taxonomy parser, and the path decision. The web UI and the extension popup share one wallet shell in src/wallet/; the web app (src/web/app.ts) mounts it over a WebBackend.
flowchart TD
user[Move card, question, optional notes] --> desk[Web desk]
desk --> core[src/core validation, prompt, path]
core --> mode{Inference mode}
mode -->|short card, prefer on-device| device[initializeDeviceModel then generateContent]
mode -->|private notes| deviceOnly[ONLY_ON_DEVICE with notes]
deviceOnly -->|Gemini Nano missing| cloudRetry[ONLY_IN_CLOUD without notes]
mode -->|long input or cloud preference| cloud[ONLY_IN_CLOUD or PREFER_IN_CLOUD without notes]
device --> source[response.inferenceSource]
cloud --> source
cloudRetry --> source
source --> parse[Taxonomy parser]
parse --> ui[On-device or cloud badge]
parse --> store[Firestore users/uid/explanations]
rc[Remote Config] --> core
check[App Check reCAPTCHA Enterprise] --> device
check --> cloud
Setup
Requirements: Node.js 22 or newer, a Firebase project on the Spark plan or above, and Chrome when you want the on-device path. npm install may print an engine warning from the firebase package, which declares a newer Node for running the SDK inside Node. This app bundles the SDK for the browser and does not run inference in Node.
npm install
npm run dev
The public web config for project atlas-explain is committed in src/platform/web/firebaseConfig.ts and is used when the VITE_ variables are unset. .env.example lists optional overrides for a different Firebase project. Copy it to .env.local only if you need those overrides. Do not commit service-account keys.
This Firebase project
atlas-explain is on the Spark plan. AI Logic uses the Gemini Developer API with App Check enforced. Anonymous Authentication is on. Firestore is the (default) database in nam5, in production mode. App Check uses a score-based reCAPTCHA Enterprise key limited to atlas-explain.web.app and atlas-explain.firebaseapp.com. Localhost is not on that key.
App Check debug token (localhost)
npm run dev sets self.FIREBASE_APPCHECK_DEBUG_TOKEN = true before initializeAppCheck. A production build does not set it, even if VITE_APPCHECK_DEBUG_TOKEN is present.
- Run
npm run devand open the local URL. - Open the browser developer console. The App Check SDK prints a line like
AppCheck debug token: "...". - In the Firebase console, go to Security → App Check → Apps, open the web app, and choose Manage debug tokens.
- Add the token from the console, then reload the app. Cloud calls stay blocked until that token is registered.
- To reuse a token you already registered, set
VITE_APPCHECK_DEBUG_TOKENin.env.localto that token. Set it tofalseto turn the debug provider off. Do not addlocalhostto the production reCAPTCHA key.
Firebase console (another project)
- Create a project. Analytics is optional.
- Register a Web app and copy its config into
.env.localusing theVITE_FIREBASE_*names in.env.example. - Open AI Services → AI Logic and finish Get started with the Gemini Developer API. Leave App Check enforced.
- Create a score-based reCAPTCHA Enterprise key and register the web app in App Check. Put the key in
VITE_RECAPTCHA_ENTERPRISE_SITE_KEY. - Enable Authentication → Anonymous.
- Create a Firestore database. Rules allow a signed-in user to read and write only
users/{their uid}/explanations/*, and they reject documents that containnotesorwatchlist. - Remote Config parameters, also compiled into
src/core/settings.tsuntil a template is published:inference_mode,cloud_model,prompt_template,topic_taxonomy,on_device_max_headlines,on_device_max_chars,long_document_chars,max_output_tokens. Prompt placeholders are{{TAXONOMY}},{{QUESTION}},{{MOVE_CARD}}, and{{PRIVATE_CONTEXT}}. Taxonomy ids are fixed in code; Remote Config can rename labels or hide an id, andotheris always kept.
Deploy
.firebaserc selects project atlas-explain. firebase.json publishes Hosting from dist/ with a single-page rewrite, Firestore rules from firestore.rules, and Remote Config from remoteconfig.template.json.
Sign in once:
npx firebase-tools login
Run the release gate, then deploy hosting, rules, and Remote Config:
npm run release:check # typecheck, lint, test, both builds, manifest, bundle budget, audit, trade-word scan
npx firebase-tools deploy --only hosting,firestore:rules,remoteconfig
Billing is shipped switched off. billing_enabled defaults to false, checkout is not shown, and the badge says "Free during beta". See docs/MONETIZATION.md before changing that.
Deep links, desk hand-off, and concepts
ATLAS Explain can load a public move card from a link or from a message sent by an allowed page. It never auto-runs an explanation. The user still clicks Explain the move. Notes, watchlists, balances, and account fields are stripped on the way in and are not written into the editor.
The context envelope is version 1:
{
"v": 1,
"kind": "move_card",
"source": "atlas_desk",
"card": { "symbol": "BTCUSDT", "asOf": "2026-11-12", "movePct": -6.2 },
"question": "Why might some traders buy this dip while others sell?",
"concepts": ["shadow"]
}
A bare public move card (the existing JSON shape) is also accepted. Allowed card fields are the public MoveCard keys in src/core/move-card.ts. Forbidden keys include notes, watchlist, balances, positions, account identifiers, and secrets.
Hash links keep the payload out of Hosting query logs:
https://atlas-explain.web.app/app/explain#c=<base64url(JSON)>(links made for/still work; they are forwarded here)https://atlas-explain.web.app/app/explain#card=<uri-encoded JSON>for a small cardhttps://atlas-explain.web.app/app/explain#concept=shadowto open a glossary entry without a card
src/core/context-link.ts builds and parses these hashes. Concept ids live in src/core/glossary.ts: shadow, signal15, chart_layers, live_lock, paper_only, drop_study, hybrid_inference, and move_card.
postMessage, for a same-machine ATLAS desk tab or a future extension page that is not implemented in this change:
otherWindow.postMessage(
{ type: "atlas-explain/v1/load", payload: envelope, concept: "chart_layers" },
"https://atlas-explain.web.app",
);
The app accepts that type only from https://atlas-explain.web.app, https://atlas-explain.firebaseapp.com, http://localhost:3000, and http://127.0.0.1:3000. It replies with atlas-explain/v1/loaded or atlas-explain/v1/error. This repository still does not contain ATLAS models, signals, or account data.
Connecting to ATLAS
ATLAS Explain never reads balances, positions, or account ids. When it talks to the private ATLAS desk, it uses this repo's connectors library (src/connectors/, see docs/connectors/README.md):
- The hosted web app at https://atlas-explain.web.app never calls localhost. Its header pill says Live prices when the public price feed answers, and shows nothing otherwise. Everything ATLAS-only (the Signal tab, the desk menu item, the ATLAS digest) is hidden.
- The Chrome extension and a local loopback build may probe ATLAS on this computer. They prefer public MCP (
POST /api/mcp/public) and fall back to the REST catalog (GET /api/explain/assets). - The header says ATLAS connected only when one of those probes actually answers, and only then do the ATLAS-only parts appear. It says ATLAS desk when this tab is the Markets desk and Offline when the browser is offline. It does not fake a connection, and it never shows a "Not connected" state to people who don't run ATLAS.
The desk can also open this app with a public move card (#c= / #card=) or a glossary concept (#concept=). Loading a card does not run the model until you click Explain the move.
For AI assistants (MCP)
ATLAS Explain also has a free, read-only MCP server hosted online (Cloudflare Workers free plan). Assistants such as Claude add its web address as a connector, and can then look up glossary terms, official figures (with sources) and today's headlines. Nothing is downloaded. Hosting and owner steps: docs/MCP.md.
Screenshots
Stills live in docs/screenshots/. Six were retaken on 15 Nov 2026 from the live site and a local build; local-header.png (ATLAS was not running at the time) and desk-explain-link.png (a crop of the private desk) are older. They show honest header states, the desk hand-off, today's brief, the grey signal light, and the practice page. An on-device badge is not included: that still needs a recording on a laptop with Gemini Nano (see docs/DEMO.md).
The hosted web app at https://atlas-explain.web.app/app is one page: Explain at the top, then Today, Learn and Assets, reached from the header. The pill shows Live prices; the hosted app never calls localhost.
A local loopback build shows ATLAS connected only when public MCP or the REST catalog on this computer answers. (This still predates the one-page layout and shows the older "ATLAS local" label.)
The private ATLAS desk can open this app with a public move card (#c= / #card=) or a glossary concept (#concept=).
With ATLAS on this computer, Today adds the brief and the paper signal light. An earlier official note is labelled as not today's, and is not presented as today's brief.
On the hosted app, Today shows the biggest crypto moves from the public price feed, with the source and time. The ATLAS digest and the signal light appear only when ATLAS runs on the visitor's own computer.
A #concept=shadow link opens "Explain a market move" with an educational question filled in. Nothing is sent until you click Explain the move.
The paper signal light stays grey unless the desk sends its public signal. This is the honest default when there is not enough evidence, or when this tab is not the desk.
The practice page (https://atlas-explain.web.app/welcome, opened on install) uses static, educational language. It has no live prices and no account fields.
On-device model in Chrome
On-device inference needs Chrome on desktop, version 139 or newer (getting started guide):
- Set
chrome://flags/#prompt-api-for-gemini-nano-multimodal-inputto Enabled and restart Chrome. - Optional, in DevTools:
await LanguageModel.availability(), thenawait LanguageModel.create()if the result isdownloadable. The first download can take several minutes. - Click Explain the move.
initializeDeviceModelruns from that click, which satisfies Chrome's user-activation rule. The badge then reads On-device or Cloud frominferenceSource.
If Nano is not available and the card has no private notes, PREFER_ON_DEVICE falls through to the cloud model inside the SDK. If the card has notes, the first call is device-only so the notes cannot take the cloud fallback; a failure retries in the cloud without them, and the badge says so.
Demo
Try the highlight flow on a static practice page with no prices and no account: atlas-explain.web.app/welcome. Highlight a sentence, right-click, and choose Explain with ATLAS Explain, or press Alt+Shift+X. Alt+Shift+E opens the Explain popup.
The full three-minute script (ATLAS desk → Explain → on-device badge → two-sided reasons → highlighted text on a trading page → Recent and Learn path → signal light) is in docs/DEMO.md. The submission checklist is in docs/SUBMISSION.md.
| Step | What the judge sees |
|---|---|
| 1 | The ATLAS desk's Explain this move opens a public move card in the wallet. Nothing runs until the click. |
| 2 | Explain the move runs Firebase AI Logic hybrid inference; the badge names the path that ran (on-device Gemini Nano or cloud Gemini). |
| 3 | Three reasons a buyer might weigh, three a seller might weigh, and what would change the picture. |
| 4 | On a trading or charting page, a highlighted sentence is explained in the same wallet, with the site type (charting, broker, crypto exchange, market news) read from the site name only. |
| 5 | Recent explanations and Learn path progress stay on the device. |
Chrome extension
The Manifest V3 extension lives in extension/ and reuses src/core for the prompt, the refusal rules, and the billing entitlements. It tries Chrome's Prompt API (Gemini Nano) first. If that model is unavailable, it calls Firebase AI Logic with InferenceMode.ONLY_IN_CLOUD on the same atlas-explain project. The popup says which path answered.
Each explanation is a click: the toolbar icon, the selection context menu Explain with ATLAS Explain, the Alt+Shift+X shortcut (or Alt+Shift+E to open the popup), or a button you add to the current page. The extension sends the highlighted text, the page title, and the site name. The site name and title also tell it what kind of page the highlight came from (charting site, broker, crypto exchange, market news, or the ATLAS desk), so an "RSI" on a charting site is read as an indicator; the page body is never read. Recent explanations and Learn path progress are kept in chrome.storage.local on the device only. It does not read form fields, balances, or account numbers. On-device answers are unlimited. Cloud answers follow billing_enabled (off during beta, so they are free).
scripting is included with activeTab so the highlight and the page button run only after that click. sidePanel is optional.
Load it unpacked:
npm run build:extension- Open
chrome://extensions, turn on Developer mode, and choose Load unpacked. - Select
extension/dist. - For Gemini Nano, use Chrome on desktop, version 139 or newer, and set
chrome://flags/#prompt-api-for-gemini-nano-multimodal-inputto Enabled. - The reCAPTCHA key does not include
chrome-extension://origins. For a cloud fallback while unpacked, register an App Check debug token and paste it into Settings → AI in the popup. - To light the signal, open the ATLAS Markets desk (
http://localhost:3000/markets) in the active tab, then click the toolbar icon. The desk answers the popup'satlas-explain/v1/request-contextmessage with its public payload. Onlylean,hitRate,sampleSize, andreasonare read.
npm run build:extension writes extension/atlas-explain-chrome.zip. For a Chrome Web Store release, bump the version with npm version <x.y.z> (it updates extension/manifest.json too), then npm run release:extension writes release/atlas-explain-chrome-v<x.y.z>.zip and its .sha256; upload that zip. Listing images are in store/; the full listing text, privacy-practices answers and submission steps are in docs/CHROME_STORE.md. The identity is documented in docs/BRAND.md. The listing should say the extension is educational and not investment advice. Do not ship an App Check debug token in the store build.
The popup opens like a wallet menu that drops down from the toolbar, with three tabs: Explain, Learn and Assets. Settings opens from its menu, and a Signal tab appears only while ATLAS research software is running. The hosted web app at /app uses the same parts on one scrolling page. Explanations of highlighted text appear in the same popup, with loading, empty, error, and offline states. The layout, motion, and icon rules are in docs/BRAND.md. A signal light at the top stays grey unless a shadow model has cleared the evidence gate. Today none have, so the honest state is grey, or "connect ATLAS" when the desk tab is not open. The light never says buy or sell.
Tests and CI
npm run release:check
That one command runs the Node version check, typecheck, lint, tests, the web and extension builds, the manifest least-privilege check, the bundle budget (every chunk ≤ 500 kB, popup ≤ 120 kB), npm audit (must be 0) and the trade-word scan, and stops at the first failure. Hosting sends a strict CSP and security headers from firebase.json. Node ^22.12 || ^24 (.nvmrc = 24). Audit overrides are explained in docs/DEPENDENCIES.md.
Unit tests cover move-card validation, prompt building, the taxonomy parser, inference-path selection, the explain retry that drops private notes, and the Firebase AI Logic calls with firebase/ai mocked. GitHub Actions (.github/workflows/ci.yml) runs the same steps on Node 22.
npm run remote-config rewrites remoteconfig.template.json from the in-app defaults. A test fails if the two drift.
Limitations
- On-device inference is Chrome on desktop, version 139 or newer, with the Prompt API flag. Other browsers use the cloud path.
- On-device context is 9,216 tokens. Long cards are sent to the cloud without private notes. Hybrid mode does not support multi-turn chat, token counting, or the Live API.
- The on-device model can still return slightly messy JSON. The parser coerces unknown topics to
otherand rejects an answer that does not contain three reasons on each side. - Sample cards are illustrative. January 27, 2025 and April 3–4, 2025 figures are rounded from contemporaneous Reuters, AP, BBC, and CNBC reports linked on the card. They are not a licensed feed, and this repo does not ship Polygon, Yahoo, or Coinbase data. The blank card's −6% is a placeholder.
- Anonymous history is tied to the browser profile. Clearing site data starts a new user.
- App Check debug tokens are for localhost only. Production needs the reCAPTCHA Enterprise key and enforcement left on.
- Explanations can be wrong, incomplete, or too confident. They are not research from the private ATLAS desk and they are not a forecast.
Relationship to ATLAS
ATLAS is a private, paper-only trading-research desk. ATLAS Explain is a separate public companion. This repository does not contain ATLAS models, signals, notebooks, positions, or data. A move card exists only because someone pasted it, picked a labeled sample, or loaded their own saved explanation.
What to build next
Chrome extension. Shipped in extension/ (see above). Next: a Chrome Web Store listing, and structured output on the extension's on-device path so its answers use the same buyer/seller schema as the web app.
Android shell. Port the move card, prompt, taxonomy, and path decision, then call Firebase AI Logic's Android hybrid API so Gemini Nano runs through ML Kit when the device has it and Gemini in the cloud otherwise. Use the current Android getting-started guide rather than a copied web snippet: hybrid inference for Android. Reuse App Check (Play Integrity), the same Firestore rules, and the same Remote Config keys.
License
Apache License 2.0. See LICENSE.
الأسئلة الشائعة
ما هو ATLAS Explain؟
Market jargon in plain language: terms, official figures, crypto prices and charts, headlines.
كيف أثبّت ATLAS Explain؟
يعمل كخادم بعيد. في Claude Code: claude mcp add --transport http atlas-explain 'https://atlas-explain-mcp.atlas-explain.workers.dev/mcp'. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.
هل يحتاج ATLAS Explain إلى مفتاح API؟
لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.
هل ATLAS Explain مفتوح المصدر؟
نعم. شيفرته متاحة على GitHub بترخيص Apache-2.0.
من يصون ATLAS Explain؟
ينشره MISHHF93. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.
من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.