The ecommerce super intelligence layer for firearms
The only production ontology for 2A retail: products, dealers, shoppers, demand, regulated commerce — and an in-store edge surface (My Betsy) that reuses the same objects without POS. Shared by Betsy, GunSearchAgent, and Brand Intelligence. Maturity is enforced in CI.
Put demand intelligence on your FFL site — inventory search is free to start on GunSearchAgent.
- live — production path today
- partial — code exists; data thin
- planned — named map only
Industry map v1.1.0. Object set is stable; depth is additive. Drift fails CI. Regulatory tools are library-only (not chat).
Governance proof
Enforced ontology · not a slide deck
Live operational model with automated drift gates on every merge. Maturity badges are CI, not marketing.
Last CI
8716aca
Aug 8, 4:29 PM
Deploy
8716aca
Matches green CI
Suite
v1.1.0
6 gates
Ontology gates · last green CI
Graph integrity
Pass
Live storage map
Pass
Chat tool surface
Pass
Regulatory boundary
Pass
Platform action evidence
Pass
Enterprise API contract
Pass
Continuous integration on main enforces ontology integrity and Enterprise API contract drift on every change.
Compliance boundary
Super Intelligence stops here
We name how 2A e-commerce works so demand stays honest — we never become the FFL’s transfer stack.
Never: file_4473 / e4473
ATF Form 4473 is completed with the FFL at licensed premises — not in chat.
Never: run_nics
Background checks are the licensed retailer’s process, not Betsy’s.
Never: decide_legality
No state-by-state legal determinations for a specific buyer or address.
Never: verify_ffl_license
FFL-to-FFL verification for transfers is operational compliance — public list lookup is educational only, not transfer clearance.
Never: write_bound_book
Acquisition & disposition / electronic bound books are a separate software category.
Never: file_eforms
ATF eForms filing is outside Super Intelligence product scope.
Never: store_serial_or_owner
No individual owner, serial-number, or private-transaction vault in this product.
Never: integrate_pos_or_register
My Betsy in-store deliberately goes around POS / register stacks — engagement surface only, not transfer software.
Never: silent_phone_capture
No silent takeover of phones that walk in. Customer must join store Wi‑Fi, scan QR, or open a URL.
SYS.01
Objects
The nouns of 2A commerce — products, dealers, journeys, demand, and regulated commerce class.
SYS.02
Links
How inventory, identity, intent, and purchase path relate — not orphaned tables.
SYS.03
Actions
What Betsy, shoppers, and Brand Intelligence can do — and what we never automate (4473, NICS).
Object graph
A simple map of how the system fits together. Hover a circle to see its neighbors. Click for a plain-language explanation — Product is in the center because everything else hangs off live inventory.
Hover a circle to see what connects to it. Click for a short explanation.
These are the building blocks of GunSearch — inventory, visits, and demand — shared by Betsy, dealers, and Brand Intelligence.
Object inventory
Each object is a real operational entity — backed by schema and APIs, not a slide-deck noun.
Product
Live listing / SKU from a dealer feed
products
Brand
Manufacturer / house brand
brands
Seller
FFL / retailer with feed + optional website embed + optional My Betsy in-store edge (same site_key)
sellers
Session
Shopping journey on main chat, dealer embed, or My Betsy in-store edge (legacy table: leads). channel distinguishes surfaces. Admin Sessions may show a derived settled status (soft cart/checkout abandon, bounced, walked away) — presentation only, not a stored column.
leads
Shopper
Verified identity for alerts (magic link / My Betsy account) — never in Brand Intelligence API. In-store email gate may create marketing continuity without a full account session.
shoppers
Watch
Saved search / restock alert
shopper_watches
SearchIntent
Rolling multi-turn demand signal on a session. Path beacons set funnel_stage as monotonic max: browse → cart → checkout → purchase (order-confirmation URL shapes only for purchase).
search_intent_summary + events
ModelTerm
Catalog-mined firearm platform / SKU family in titles
catalog_model_terms
EnterpriseClient
OEM / Platform Brand Intelligence tenant (not GSA dealers)
enterprise_clients + users + api_keys
DemandSignal
Anonymized aggregate — full/OEM for Brand Intelligence API; store-scoped or market teaser for GSA; public Insights teaser
derived from sessions + demand_daily_rollups (no PII)
RegulatoryClass
Coarse commerce class of a Product for discovery UX and demand — not a legal determination. Derived from catalog type + title salvage (GCA firearm, ammunition, reloading, suppressor, SBR, other NFA, frame/receiver, unknown). First-class demand families include suppressors and SBRs alongside ammo/firearms/reloading.
derived (regulatory-commerce.ts) — no products column rewrite
CommercePath
Expected discovery→purchase shape for a class (FFL transfer, ammo ship policy, NFA process). Educational templates for Betsy — never “this sale is legal for you.”
derived rules + educational templates (regulatory-commerce)
FFLLicense
Public ATF Federal Firearms Licensee list index (type, premises, status) + optional seller soft-link. Ops ingest via scripts/ingest-ffl.ts or ATF_FFL_PUBLIC_URL; admin /admin/ffl. Not transfer verification or eZ Check.
ffl_licenses (+ sellers.ffl_number denorm; provenance)
Jurisdiction
Federal/state/territory educational commerce context grounded in ATF P 5300.5 (36th Edition). Rows are provenance-backed shells; high-level notes are sparse by design — not a complete state-law database, legality engine, or municipal model.
jurisdictions (+ ATF P 5300.5 provenance; densify notes when a product surface needs them)
ATFRuling
Public classification/ruling summaries for education and search — not case-specific legal advice.
atf_rulings (+ provenance)
ProductionStat
AFMER-style public manufacturing volume aggregates by year/type (optional ingest).
production_stats (+ provenance)
FunnelStage
Max path stage on a session: browse → cart → checkout → purchase (purchase = high-confidence confirmation URL only).
search_intent_summary.funnel_stage + demand funnel aggregates
HostPage
Dealer *website* page observed by embed page-intent (path, soft-seed, funnel chrome). Not the Pi / captive in-store shell — physical walk-ins are Session channel mybetsy_edge + EdgeDevice, not HostPage. No full host URL dump in product APIs.
search_intent_summary.host_context + path history + page-intent events
Referrer
First-touch acquisition host before the dealer site (kind + host only; no full referrer URL vault).
search_intent_summary.referrer_* + demand topReferrers
CatalogFeed
Retailer product feed (AmmoSeek / GunEngine / GunMade / …) that materializes live Product rows on ingest.
sellers.feed_url + feed adapters + sync_logs
AlertDelivery
Outbound restock/price-change email for a Watch (cron-driven; verified shoppers only).
shopper_watches + watch-alerts cron + email
EdgeDevice
My Betsy in-store unit (Pi / thin edge): captive or QR walk-in shell, store-scoped site_key, optional SSID/serial/health. Heavy AI stays cloud (GSE). Not a second catalog brain. Distinct from shopper account My Betsy (/mybetsy).
conceptual — edge shell + open/storefront APIs live; device claim fleet tables planned
Transfer
Conceptual firearm handoff via licensed premises / FFL process. Named for industry literacy — never executed, filed, or approved in this product.
conceptual — not executed in product
ShippingPolicy
Dealer-asserted ship / transfer rules (future seller-configured). Complements Jurisdiction educational notes without a legality engine.
planned (seller fields / policy docs)
ComplianceBoundary
Explicit product stop-line: what Super Intelligence will not become (4473, NICS, bound book, buyer legality). Points at ONTOLOGY_NON_ACTIONS.
narrative + non-actions inventory
Form4473
Named ATF Form 4473 as an industry document boundary — completed at licensed premises with an FFL, never in chat. Twin of non-action file_4473.
conceptual — runtime forbidden
BackgroundCheck
Named NICS / background-check concept as boundary — retailer process, not a GSE integration. Twin of non-action run_nics.
conceptual — runtime forbidden
BoundBookEntry
Acquisition & disposition / electronic bound book as a separate software category — not Super Intelligence. Twin of non-action write_bound_book.
conceptual — runtime forbidden
Links
Relationships the platform enforces — store catalog scope, identity, and demand summaries.
| From | Link | To |
|---|---|---|
| Product | manufactured_by | Brand |
| Product | listed_by | Seller |
| Product | classified_as | RegulatoryClass |
| RegulatoryClass | implies | CommercePath |
| Product | restricted_in | Jurisdiction |
| Seller | holds | FFLLicense |
| Seller | is_licensed_as | FFLLicense |
| FFLLicense | operates_in | Jurisdiction |
| Brand | has_production | ProductionStat |
| Session | scoped_to | Seller |
| Session | identified_as | Shopper |
| Session | accumulates | SearchIntent |
| Shopper | subscribes | Watch |
| Watch | matches | Product |
| Session | clicked | Product |
| SearchIntent | aggregates_to | DemandSignal |
| ModelTerm | matches_title | Product |
| Session | rolls_up_to | DemandSignal |
| DemandSignal | consumed_by | EnterpriseClient |
| Session | reaches | FunnelStage |
| HostPage | advances | FunnelStage |
| FunnelStage | aggregates_to | DemandSignal |
| Session | views | HostPage |
| HostPage | scoped_to | Seller |
| HostPage | may_seed | SearchIntent |
| Referrer | originates | Session |
| Seller | publishes | CatalogFeed |
| CatalogFeed | materializes | Product |
| Watch | triggers | AlertDelivery |
| CommercePath | may_culminate_in | Transfer |
| Transfer | completed_by | Seller |
| ShippingPolicy | constrains | CommercePath |
| ShippingPolicy | respects | Jurisdiction |
| ComplianceBoundary | excludes | Form4473 |
| ComplianceBoundary | excludes | BackgroundCheck |
| ComplianceBoundary | excludes | BoundBookEntry |
| Transfer | requires_at_premises | Form4473 |
| Seller | may_deploy | EdgeDevice |
| EdgeDevice | serves_walk_in | Session |
| EdgeDevice | scoped_to | Seller |
| EdgeDevice | surfaces | Product |
Actions
Kinetic layer: governed operations that change or query the model. Shoppers feel CTAs; agents call tools; cron keeps the twin fresh.
search_productsReturn live product cards from the catalog
Betsy · Chat, dealer widget, in-store edge (proxy)
get_productLoad one product (limited to that store in the dealer widget)
Betsy · Chat, dealer widget, in-store edge (proxy)
compare_productsSide-by-side comparison of recent product results
Betsy · Chat, in-store edge (proxy)
email_resultsEmail a full result list and keep continuity by email
Shopper + Betsy · Chat, dealer widget
create_alertSave a search alert for restock or price changes
Shopper · Chat, My Betsy account (/mybetsy)
record_host_intentCapture first-touch referrer, page path, and shopping stage
Dealer widget · Dealer website storefront (not Pi captive shell)
load_mybetsy_storefrontLoad seller-scoped floor board: top demand UPCs, newest stock, demo in-store offer (site_key auth)
My Betsy edge shell · In-store edge shell · /api/embed/mybetsy-storefront
mybetsy_smart_openResolve site_key → probe local edge → open in-store board, else fall back to dealer website
Walk-in phone (QR / go link) · Smart open · /api/embed/mybetsy-open + go router
edge_device_heartbeatReport device health / uplink to platform (fleet ops)
Edge agent · planned — edge agent + future GSA Devices
claim_edge_deviceBind serial / claim token to seller agent and push SSID branding
Dealer (GSA portal) · planned — GunSearchAgent Devices
ingest_feedRefresh live inventory from retailer feeds
Scheduled import / admin · Catalog pipeline
fire_watch_alertsEmail shoppers when stock or price changes on a watched search
Scheduled jobs · Alert email
enterprise_apiDemand data, privacy-safe sessions, export, unmet demand, product intensity — OEM- or Platform-scoped
Brand Intelligence client · Portal + Enterprise API
create_api_keyCreate an API key (full secret shown only once)
Portal administrator · Portal, Enterprise API
send_weekly_insightsWeekly Brand Intelligence email summary
Cron (opt-in per EnterpriseClient) · enterprise-weekly-insights + cron
gsa_store_intelStore-scoped demand visualization (no session export)
GunSearchAgent (dealer portal) · Dealer intel API
gsa_market_teaserLimited anonymized market teaser — no full export or market API keys
GunSearchAgent Pro · Dealer market teaser API
explain_commerce_pathShort educational path copy (firearm → FFL transfer; ammo → dealer ship policy; NFA → tax-stamp process). Always includes disclaimer. Never decides legality for a buyer.
Betsy · library only — src/lib/regulatory-tools.ts (not registered in chat)
tag_regulatory_intentAnonymized regulatory_class / commerce_path facets for demand intel (no buyer-facing legality). Library helper; not auto-wired into chat turns yet.
Platform (silent) · library only — src/lib/regulatory-tools.ts (not registered in chat)
query_regulatory_classClassify product or free-text features → class + path + educational text + disclaimer
Betsy · library only — src/lib/regulatory-tools.ts (not registered in chat)
get_ffl_infoPublic FFL list summary by number or seller soft-link — not transfer verification. Partial until public FFL list is ingested.
Betsy · library only — src/lib/regulatory-tools.ts (not registered in chat)
get_jurisdiction_contextATF P 5300.5–grounded jurisdiction shells + provenance. Notes sparse by design; not a complete state-law dump.
Betsy · library only — src/lib/regulatory-tools.ts (not registered in chat)
check_basic_ship_eligibilityHigh-level educational notes for product class + dest state (P 5300.5 family disclaimer); never returns eligible=true/false as law
Betsy · library only — src/lib/regulatory-tools.ts (not registered in chat)
search_atf_rulingsSearch public/educational ATF ruling summaries with source URLs (corpus still thin)
Betsy · library only — src/lib/regulatory-tools.ts (not registered in chat)
get_production_statsAFMER-style public production aggregates by brand/year when loaded
Betsy · library only — src/lib/regulatory-tools.ts (not registered in chat)
ingest_atf_publicSoft weekly upsert of ATF P 5300.5 jurisdiction shells + educational ruling stubs (+ optional public FFL URL later). Fail soft; never blocks search.
Cron · /api/cron/atf-public
explain_transfer_boundaryEducational copy that Transfer / Form 4473 / NICS happen with an FFL — never in chat. Not registered in Grok yet.
Betsy (planned) · planned — library/chat product decision later
Lexicon layer
Semantic enrichment maps shooter language onto objects — the narrow “ammo ontology” is one file inside a larger identity stack.
LEX.01
Ammo load language
Shopper slang → structured load and casing (subs, green tip, named loads…)
Catalog slang map
LEX.02
Caliber aliases
Equivalents such as 300 BLK ↔ .300 AAC Blackout
Catalog caliber map
LEX.03
Brand normalize + roles
Canonical brand names and whether a brand is mostly guns, ammo, or both
Brand catalog
LEX.04
Catalog model terms
Recognize firearm platforms from product titles
Title mining
LEX.05
Intent taxonomy
Load type, use case, quantity, and budget signals
Search intent tags
LEX.06
Readiness rules
When Betsy may search vs when she should clarify first
Conversation policy
LEX.07
Commerce / regulatory language
FFL type codes 01–11, NFA categories, Form 1/4 educational names; shopper phrases → class/path templates — not legal advice
src/lib/regulatory-lexicon.ts + regulatory-commerce.ts
LEX.08
Path funnel stages
browse → cart → checkout → purchase (confirmation URL only for purchase)
funnel-stage.ts + Demand Funnel widget
LEX.09
Host path vs product path
Storefront HostPage beacons without treating cart/checkout chrome as product demand labels
host-page-intent + funnel chrome denylist
LEX.10
In-store engagement language
SSID join, captive/QR walk-in, floor board (demand/newest/offer) — not HostPage; not shopper-account My Betsy
My Betsy edge shell + smart open
Harness
Three layers keep the model trustworthy: eval quality gates, the agent runtime that only mutates the world through tools, and the Enterprise API that partners call with keys.
Quality checks
liveAutomated regression suite + ontology drift CI
- ▹Same search rules in production and tests
- ▹Golden queries for understanding and results
- ▹npm run test:ontology — graph, storage, tools, OpenAPI ↔ routes
- ▹Continuous integration on every change to main
- ▹Post-deploy smoke checks on the live site
Agent runtime
liveChat turn → catalog tools → product cards
- ▹Understand the query → readiness rules → tools → product cards
- ▹Rate limits, secure sessions, store-scoped dealer widgets
- ▹Thin in-store edge delivers the same brain (storefront board + optional chat proxy); no local LLM
- ▹Single agent with tools — not a multi-agent platform (by design)
- ▹Regulatory tools: commerce-path templates + public FFL/ruling helpers without legality judgments
Enterprise API v1
liveAPI key → /api/enterprise/v1/*
- ▹Public API docs: /docs/enterprise-api
- ▹Demand, sessions, export, unmet demand, products, referrers
- ▹Account, health, settings, API keys
- ▹Full-market demand · plan-gated lookback and export
Regulatory commerce context
Super Intelligence understands how firearms and ammo retail actually works — product class and purchase path — without replacing the FFL or compliance stack. Industry thesis: State of AI for FFLs.
Online discovery is not a completed firearm transfer. Betsy keeps the customer with the dealer: firearms typically move through an FFL transfer process; ammunition often follows a different ship path still governed by dealer policy and jurisdiction. NFA items follow a tax-stamp process with the licensed retailer. That literacy lives in RegulatoryClass and CommercePath — not in a pretend law engine.
Longer argument: State of AI for FFLs. Platform frame: Super Intelligence for FFLs.
Non-actions (never Betsy tools)
- file_4473 / e4473 — ATF Form 4473 is completed with the FFL at licensed premises — not in chat.
- run_nics — Background checks are the licensed retailer’s process, not Betsy’s.
- decide_legality — No state-by-state legal determinations for a specific buyer or address.
- verify_ffl_license — FFL-to-FFL verification for transfers is operational compliance — public list lookup is educational only, not transfer clearance.
- write_bound_book — Acquisition & disposition / electronic bound books are a separate software category.
- file_eforms — ATF eForms filing is outside Super Intelligence product scope.
- store_serial_or_owner — No individual owner, serial-number, or private-transaction vault in this product.
- integrate_pos_or_register — My Betsy in-store deliberately goes around POS / register stacks — engagement surface only, not transfer software.
- silent_phone_capture — No silent takeover of phones that walk in. Customer must join store Wi‑Fi, scan QR, or open a URL.
Why it matters
Why an ontology for 2A AI
- Demand over vanity traffic — Session + SearchIntent power dealer dashboards and Brand Intelligence: what shoppers asked for, not bounce rate.
- Live catalog, real stock — Product objects from dealer feeds so the store surface never invents inventory.
- Governed actions — Email, watches, and ingest are explicit tools — no invented side effects or compliance workflows.
- Shooter language — the lexicon layer turns slang into structure so demand stays searchable and honest.
- Regulated commerce literacy — product class and purchase path so discovery respects how FFLs actually transfer firearms — without becoming ATF software.
FAQ
- What is the GunSearch Ontology?
- It is the shared model for 2A product search: objects (Product, Brand, Seller, Session, Watch, RegulatoryClass…), links between them, and actions Betsy and humans can take (search, email results, set alerts, import inventory, export demand). Agents and apps use the same nouns so inventory and demand stay one system of record.
- Is Betsy ATF or 4473 compliance software?
- No. The ontology includes regulatory commerce context — product classes and typical purchase paths (for example FFL transfer for firearms) so discovery matches how the industry works. Betsy does not file Form 4473, run NICS, write a bound book, or decide whether a sale is legal for a specific buyer. Those remain with licensed retailers and their compliance systems.
- What are RegulatoryClass and CommercePath?
- RegulatoryClass is a coarse catalog class (ammunition, GCA firearm, NFA item, and so on) derived from product type. CommercePath is the expected discovery-to-purchase shape for education and demand tags — not a legal determination. See the object inventory and non-actions list on this page.
- Is the ontology validated automatically?
- Yes. Every change to main runs npm run test:ontology in CI: graph integrity, live objects mapped to schema tables, chat tool registration, regulatory boundary (library only — not chat), platform action evidence, and OpenAPI paths locked to Enterprise API v1 routes. The proof panel on this page shows the last green CI on main and the gate inventory.
- Is this page generated from the API or database?
- The map is curated so maturity stays honest — but it is not free to drift. CI fails if we claim live storage without tables, claim chat tools without agent-tools, or ship Enterprise routes without OpenAPI (and the reverse). HTTP contracts live at /docs/enterprise-api and /openapi/enterprise-v1.yaml.
- Is this the same as Palantir’s Ontology?
- Same idea — an operational model, not a chatbot prompt. Different scope: Palantir is a general enterprise twin. Ours is purpose-built for firearms and ammo ecommerce super intelligence — catalog, dealer embeds, in-store edge (My Betsy), demand, Brand Intelligence, and a hard compliance boundary — shipping in production with automated enforcement.
- How does Brand Intelligence fit in?
- Demand is the anonymized aggregate of how shoppers search. Brand Intelligence clients read it through their portal and the Enterprise API: demand packages, privacy-safe sessions, export, unmet demand, product intensity, and more — scoped to their brands (OEM) or the full market (Platform). Shopper emails never leave the shopper side of the model.
- How do you keep the agent honest?
- Product cards are never invented by the AI — only the catalog returns inventory. Clear rules decide when a search can run, and automated tests check that understanding, readiness, and results stay high quality. Regulatory path language is planned as curated templates, not freeform legal advice.
Curated by the product team — not auto-generated from the API or database. Machine-readable Enterprise API: /docs/enterprise-api.