@undesirables/plugin-tcg-oracle 1.0.0 → 2.0.0

package/LICENSE

@@ -2,20 +2,81 @@ Business Source License 1.1
 
 Parameters
 
-Licensor:             The Undesirables LLC
-Licensed Work:        plugin-undesirables
-                      The Licensed Work is (c) 2026 The Undesirables LLC
-Additional Use Grant: You may use the Licensed Work for non-production purposes,
-                      personal projects, and evaluation. Production use requires
-                      a commercial license from The Undesirables LLC.
-Change Date:          2030-04-24
-Change License:       MIT
-
-Notice
-
-The Business Source License (this document, or the "License") is not an Open
-Source license. However, the Licensed Work will eventually be made available
-under an Open Source License, as stated in this License.
-
-For more information on the Business Source License, please visit:
-https://mariadb.com/bsl11/
+  Licensor:             The Undesirables LLC
+  Licensed Work:        Plugin TCG Oracle
+                        Copyright (c) 2026 The Undesirables LLC.
+                        All Rights Reserved.
+  Additional Use Grant: You may make production use of the Licensed Work,
+                        provided Your use does not include offering the
+                        Licensed Work to third parties on a hosted or
+                        embedded basis as a Competitive Offering.
+
+                        A "Competitive Offering" is a product or service
+                        offered to third parties on a paid basis (including
+                        through paid support arrangements) that provides
+                        TCG market intelligence, pricing aggregation, AI
+                        card grading, or on-chain price oracle functionality
+                        as a primary feature.
+
+                        If Your product is not a Competitive Offering when
+                        You first make it generally available, it will not
+                        become a Competitive Offering later due to the
+                        Licensor releasing a new version of the Licensed
+                        Work with additional capabilities.
+
+                        Products that are not provided on a paid basis are
+                        not Competitive Offerings.
+
+  Change Date:          June 1, 2030
+  Change License:       MIT
+
+For alternative licensing arrangements, contact:
+  theundesirables7@gmail.com
+
+─────────────────────────────────────────────────────────────────────────
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may
+vary for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+─────────────────────────────────────────────────────────────────────────
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+BUSL-1.1 license template: https://mariadb.com/bsl11/

package/README.md

@@ -1,11 +1,36 @@
-# @undesirables/plugin-tcg-oracle
+<div align="center">
 
 ![TCG Oracle Banner](./images/banner.jpg)
 
-[![npm](https://img.shields.io/npm/v/@undesirables/plugin-tcg-oracle)](https://www.npmjs.com/package/@undesirables/plugin-tcg-oracle)
-[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue)](LICENSE)
+# @undesirables/plugin-tcg-oracle
+
+**Give any ElizaOS agent real trading card market intelligence — search, grade, and forecast.**
+
+[![npm](https://img.shields.io/npm/v/@undesirables/plugin-tcg-oracle?style=flat-square)](https://www.npmjs.com/package/@undesirables/plugin-tcg-oracle)
+[![npm downloads](https://img.shields.io/npm/dm/@undesirables/plugin-tcg-oracle?style=flat-square)](https://www.npmjs.com/package/@undesirables/plugin-tcg-oracle)
+[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-red?style=flat-square)](LICENSE)
+[![ElizaOS](https://img.shields.io/badge/ElizaOS-Compatible-5A67D8?style=flat-square&logo=data:image/svg+xml;base64,&logoColor=white)](https://elizaos.ai)
+[![Games](https://img.shields.io/badge/Games-Pok%C3%A9mon%20%C2%B7%20MTG%20%C2%B7%20Yu--Gi--Oh!-ff14a0?style=flat-square)](https://tcgcsv.com)
+
+[npm](https://www.npmjs.com/package/@undesirables/plugin-tcg-oracle) · [TCG Oracle API](https://the-undesirables.com/docs) · [Kaggle Dataset](https://www.kaggle.com/datasets/sailorpepe/tcg-market-intelligence)
+
+</div>
+
+---
+
+## Table of Contents
 
-> Give any ElizaOS agent real trading card market intelligence — search 370K+ products, grade cards with AI vision, and simulate future prices with Monte Carlo models.
+- [Why This Exists](#why-this-exists)
+- [Quick Start](#quick-start)
+- [Actions](#actions)
+- [How It Works](#how-it-works)
+- [Supported Games](#supported-games-25)
+- [How the Data Works](#how-the-data-works)
+- [Self-Hosting](#self-hosting)
+- [Configuration](#configuration)
+- [Architecture](#architecture)
+- [Related Projects](#related-projects)
+- [License & Commercial Use](#-license--commercial-use)
 
 ---
 
@@ -15,9 +40,9 @@ The trading card market is worth **$50 billion** and growing. Millions of people
 
 This plugin gives your ElizaOS agent the ability to do all of that in one conversation:
 
-1. **"Search for Charizard cards"** → Instantly searches 370K+ real products across 25 games
+1. **"Search for Charizard cards"** → Instantly searches 446K+ real products across 25+ games
 2. **"Grade this card"** → AI vision analyzes centering, corners, edges, surface → predicts PSA/Beckett score
-3. **"Simulate Charizard VMAX at $350 for 60 days"** → Runs 10,000 Monte Carlo simulations using Heston, Merton, or Kou stochastic models → returns percentile price bands
+3. **"Simulate Charizard VMAX at $350 for 60 days"** → Runs a calibrated conformal risk forecast → returns honest VaR + percentile price bands
 4. **"Show me the Pokemon market"** → Pulls the latest daily market snapshot with top movers and volume trends
 
 No API keys required from third parties. You just point it at the TCG Oracle server (self-hosted or public).
@@ -55,10 +80,44 @@ That's it. Your agent can now search cards, grade images, and run simulations.
 
 | Action | What It Does | Example Prompt |
 |--------|-------------|----------------|
-| `TCG_ORACLE_SEARCH` | Search 370K+ products by card name, set, or keyword | "Search for Base Set Charizard" |
+| `TCG_ORACLE_SEARCH` | Search 446K+ products by card name, set, or keyword | "Search for Base Set Charizard" |
 | `TCG_ORACLE_GRADE` | Grade a card image URL — returns PSA/Beckett prediction | "Grade this card: https://..." |
-| `TCG_ORACLE_SIMULATE` | Monte Carlo price forecast with 3 stochastic models | "Simulate Charizard at $350 for 60 days" |
+| `TCG_ORACLE_SIMULATE` | Calibrated risk forecast — honest VaR (conformal default; Monte Carlo opt-in) | "Simulate Charizard at $350 for 60 days" |
 | `TCG_ORACLE_MARKET` | Pull the latest daily market snapshot for any game | "Show me the Pokemon market" |
+| `TCG_ORACLE_GRADE_OR_NOT` | Grade-or-Not ROI engine — "will grading this make me money?" | "Should I grade my Charizard?" |
+| `TCG_ORACLE_TRENDING` | Trending cards by 30-day sales volume and price velocity | "What Pokemon cards are trending?" |
+
+---
+
+## How It Works
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                        ElizaOS Agent                           │
+│                                                                │
+│  User: "Simulate Charizard VMAX at $350 for 60 days"          │
+│                         │                                      │
+│                         ▼                                      │
+│              ┌─────────────────────┐                           │
+│              │  Action Router      │                           │
+│              │  (LLM selects best  │                           │
+│              │   action + params)  │                           │
+│              └────────┬────────────┘                           │
+└───────────────────────┼────────────────────────────────────────┘
+                        │  fetch() + 30s timeout
+                        ▼
+┌────────────────────────────────────────────────────────────────┐
+│                    TCG Oracle API Server                        │
+│                                                                │
+│  /api/v1/search ─────── 446K+ products (TCGCSV)               │
+│  /api/v1/grade ──────── Vision LLM + OpenCV → PSA/BGS score   │
+│  /api/v1/simulate ───── Conformal forecast + card grades      │
+│  /api/v1/market ─────── Daily snapshot + top movers            │
+│  /api/v1/trending ───── 30-day volume + price velocity         │
+│  /api/v1/grade-or-not ─ PSA fee × grade × value = GO/NO-GO   │
+│                                                                │
+└────────────────────────────────────────────────────────────────┘
+```
 
 ---
 
@@ -70,12 +129,11 @@ Pokémon · Magic: The Gathering · Yu-Gi-Oh! · Disney Lorcana · One Piece ·
 
 ## How the Data Works
 
-All market data comes from [TCGCSV](https://tcgcsv.com) — a community project that snapshots pricing data daily for 25 TCG games. Our GitLab CI pipeline automatically refreshes this data every 24 hours. The full dataset (370K+ products) is also available on [Kaggle](https://www.kaggle.com/datasets/sailorpepe/tcg-market-intelligence).
+All market data comes from [TCGCSV](https://tcgcsv.com) — a community project that snapshots pricing data daily for 25 TCG games. Our GitLab CI pipeline automatically refreshes this data every 24 hours. The full dataset (446K+ products) is also available on [Kaggle](https://www.kaggle.com/datasets/sailorpepe/tcg-market-intelligence).
 
-**Monte Carlo models explained:**
-- **Heston** — Models volatility itself as stochastic (volatility changes over time). Best for cards with unpredictable hype cycles.
-- **Merton** — Adds random jumps to the price process. Best for cards that can spike on tournament results or reprints.
-- **Kou** — Uses double-exponential jump distribution. Best for modeling asymmetric risk (big upside spikes vs gradual decline).
+**Risk model — conformal calibration (default):**
+
+Price forecasts default to a **regime-aware split-conformal** model: distribution-free bands calibrated on real cross-card price history, so the published downside risk (VaR) is *honest* — out-of-sample, a "5% loss" actually happens about 5% of the time — and fully **deterministic**, so anyone can reproduce the exact numbers. Each card also gets two letter grades: **Safe-Hold** (downside protection) and **Momentum** (direction). Monte Carlo models (GBM and Merton jump-diffusion) remain available via `model=`, seeded from the public **drand** randomness beacon for provably-fair draws. Forecast responses include the model parameters (e.g. `drift_mu`, `diffusion_sigma`, `regime`) for full transparency.
 
 ---
 
@@ -114,6 +172,43 @@ This is a **native TypeScript** ElizaOS plugin. It runs natively in the ElizaOS
 
 ---
 
-## License
+## 📝 License & Commercial Use
+
+This project is licensed under the **[Business Source License 1.1 (BUSL-1.1)](LICENSE)**.
+
+We build in public and support the developer ecosystem — but we also protect the infrastructure and IP of **The Undesirables LLC**.
+
+### ✅ What You CAN Do (Free)
+
+- **Personal & Educational Use** — Download, modify, and run locally for learning, research, or personal projects.
+- **Non-Competing Applications** — Integrate our packages into your app, provided your app does not offer TCG market intelligence, pricing aggregation, AI card grading, or on-chain price oracle services as its primary function.
+- **MCP / Agent Integration** — Connect your AI agent to our tools for non-commercial use.
+- **Community Contributions** — Security audits, bug fixes, and PRs are always welcome.
+
+### 🚫 What You CANNOT Do (Use Limitation)
+
+- **Competing Service** — You may not use this code to operate a competing TCG market intelligence, pricing aggregation, AI card grading, or on-chain price oracle service.
+- **Commercial Resale** — You may not wrap our API, data pipelines, or AI models into a paid service without a commercial license.
+- **Hosted SaaS** — You may not host this software as a service for third parties without written permission.
+
+### 🔓 Open-Source Conversion
+
+On **June 1, 2030** (or 4 years after the first public release of each version), this code automatically converts to the **MIT License** — fully open source, forever.
+
+### 🤝 Commercial Licensing
+
+Building a commercial product? Want guaranteed API access or white-label integration? Contact us:
+
+📧 **theundesirables7@gmail.com** · 🐦 **[@undesirables_ai](https://x.com/undesirables_ai)**
+
+© 2026 The Undesirables LLC
+
+---
+
+<div align="center">
+
+⭐ **If this project helped you, please star this repo** — it helps others find it.
+
+[Report Bug](../../issues) · [Request Feature](../../issues)
 
-[BUSL-1.1](LICENSE) — Business Source License 1.1. Copyright © 2026 The Undesirables LLC.
+</div>

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { Plugin } from '@elizaos/core';
+
 /**
  * TCG Oracle — ElizaOS Plugin v1.0.0
  * ====================================
@@ -5,19 +7,19 @@
  * Native TypeScript rewrite of the Python G.A.M.E. SDK version.
  *
  * Features:
- * - Search 370K+ TCG products across 25 games (Pokemon, MTG, Yu-Gi-Oh, etc.)
+ * - Search 446K+ TCG products across 25+ games (Pokemon, MTG, Yu-Gi-Oh, etc.)
  * - AI Vision card grading (PSA/Beckett prediction via Qwen VL)
- * - Monte Carlo price simulation (Heston, Merton, Kou stochastic models)
+ * - Conformal-calibrated risk forecasts (honest VaR + Safe-Hold/Momentum grades);
+ *   Monte Carlo (GBM/Merton) opt-in via the model parameter
  * - Real-time market snapshots from TCGCSV daily data
  * - License key purchase & verification (Ethereum NFT)
  *
  * @see https://the-undesirables.com
  * @see https://github.com/sailorpepe/elizaos-tcg-oracle-plugin
  */
-import type { Plugin } from "@elizaos/core";
+
 declare const SUPPORTED_GAMES: readonly ["Pokemon", "Magic: The Gathering", "Yu-Gi-Oh!", "Lorcana", "One Piece", "Flesh and Blood", "Star Wars: Unlimited", "Dragon Ball Super", "Digimon", "MetaZoo", "Union Arena", "Gundam Card Game", "LoL Riftbound"];
-declare const SIMULATION_MODELS: readonly ["heston", "merton", "kou"];
+declare const SIMULATION_MODELS: readonly ["conformal", "merton", "gbm"];
 declare const tcgOraclePlugin: Plugin;
-export default tcgOraclePlugin;
-export { SUPPORTED_GAMES, SIMULATION_MODELS };
-//# sourceMappingURL=index.d.ts.map
+
+export { SIMULATION_MODELS, SUPPORTED_GAMES, tcgOraclePlugin as default };