investing 0.1.147 → 0.1.148

package/README.md

@@ -4,22 +4,22 @@
 
 <!-- template-git-repo:badges:start -->
 <p align="center">
-    <a href="https://docs.autoinvestment.broker/"><img src="https://img.shields.io/badge/Docs-blue?logo=ReadTheDocs&logoColor=white" alt="Documentation" /></a>
+    <a href="https://qwksearch.com/api"><img src="https://img.shields.io/badge/Docs-blue?logo=ReadTheDocs&logoColor=white" alt="Documentation" /></a>
     <br />
-    <a href="https://github.com/OpenSourceAGI/ai-broker-investing-agent/stargazers"><img src="https://img.shields.io/github/stars/OpenSourceAGI/ai-broker-investing-agent" alt="GitHub Stars" /></a>
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/stargazers"><img src="https://img.shields.io/github/stars/OpenSourceAGI/qwksearch-research-agent" alt="GitHub Stars" /></a>
     <a href="https://www.npmjs.com/package/investing"><img src="https://img.shields.io/npm/dm/investing.svg" alt="NPM Monthly Downloads" /></a>
     <a href="https://www.npmjs.com/package/investing"><img src="https://img.shields.io/npm/v/investing.svg" alt="npm version" /></a>
     <a href="https://www.npmjs.com/package/investing"><img src="https://img.shields.io/npm/dt/investing.svg" alt="NPM Total Downloads" /></a>
     <a href="https://www.npmjs.com/package/investing"><img src="https://img.shields.io/npm/types/investing" alt="TypeScript types" /></a>
     <a href="https://packagephobia.com/result?p=investing"><img src="https://packagephobia.com/badge?p=investing" alt="Install size" /></a>
     <br />
-    <a href="https://github.com/OpenSourceAGI/ai-broker-investing-agent/issues"><img src="https://img.shields.io/github/issues/OpenSourceAGI/ai-broker-investing-agent?logo=github" alt="GitHub Issues" /></a>
-    <a href="https://github.com/OpenSourceAGI/ai-broker-investing-agent/pulls"><img src="https://img.shields.io/github/issues-pr/OpenSourceAGI/ai-broker-investing-agent?logo=github&label=PRs" alt="Open Pull Requests" /></a>
-    <a href="https://github.com/OpenSourceAGI/ai-broker-investing-agent/pulls?q=is%3Apr+is%3Aclosed"><img src="https://img.shields.io/github/issues-pr-closed/OpenSourceAGI/ai-broker-investing-agent?logo=github&label=PRs%20merged&color=8957e5" alt="Merged Pull Requests" /></a>
-    <a href="https://github.com/OpenSourceAGI/ai-broker-investing-agent/discussions"><img src="https://img.shields.io/github/discussions/OpenSourceAGI/ai-broker-investing-agent" alt="GitHub Discussions" /></a>
-    <a href="https://github.com/OpenSourceAGI/ai-broker-investing-agent/commits/main/"><img src="https://img.shields.io/github/last-commit/OpenSourceAGI/ai-broker-investing-agent.svg" alt="GitHub last commit" /></a>
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/issues"><img src="https://img.shields.io/github/issues/OpenSourceAGI/qwksearch-research-agent?logo=github" alt="GitHub Issues" /></a>
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/pulls"><img src="https://img.shields.io/github/issues-pr/OpenSourceAGI/qwksearch-research-agent?logo=github&label=PRs" alt="Open Pull Requests" /></a>
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/pulls?q=is%3Apr+is%3Aclosed"><img src="https://img.shields.io/github/issues-pr-closed/OpenSourceAGI/qwksearch-research-agent?logo=github&label=PRs%20merged&color=8957e5" alt="Merged Pull Requests" /></a>
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/discussions"><img src="https://img.shields.io/github/discussions/OpenSourceAGI/qwksearch-research-agent" alt="GitHub Discussions" /></a>
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/commits/master/"><img src="https://img.shields.io/github/last-commit/OpenSourceAGI/qwksearch-research-agent.svg" alt="GitHub last commit" /></a>
     <br />
-    <a href="https://stackblitz.com/github/OpenSourceAGI/ai-broker-investing-agent/tree/main/packages/investing"><img height="20px" src="https://developer.stackblitz.com/img/open_in_stackblitz.svg" alt="Open in StackBlitz" /></a>
+    <a href="https://stackblitz.com/github/OpenSourceAGI/qwksearch-research-agent/tree/master/packages/investing"><img height="20px" src="https://developer.stackblitz.com/img/open_in_stackblitz.svg" alt="Open in StackBlitz" /></a>
     <img src="https://img.shields.io/badge/Bun-14151A?logo=bun&logoColor=white" alt="Bun" /> <img src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" /> <img src="https://img.shields.io/badge/Drizzle%20ORM-C5F74F?logo=drizzle&logoColor=white" alt="Drizzle ORM" /> <img src="https://img.shields.io/badge/Zod-3E67B1?logo=zod&logoColor=white" alt="Zod" /> <img src="https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white" alt="Vite" /> <img src="https://img.shields.io/badge/Vitest-6E9F18?logo=vitest&logoColor=white" alt="Vitest" />
 </p>
 <!-- template-git-repo:badges:end -->
@@ -33,6 +33,8 @@ A comprehensive TypeScript/JavaScript library for investment analysis, trading a
 - 🤖 **Trading Agents** - Multi-agent framework for automated trading strategies
 - 📊 **Stock Data** - Fetch and analyze stock data from Yahoo Finance, SEC filings, and more
 - 💹 **Prediction Markets** - Polymarket integration for prediction market data
+- 🔮 **PredictOS Core** - Multi-agent prediction-market analysis, Kalshi/Polymarket
+  data clients, and cross-platform arbitrage (merged in from the `predictos` package)
 - 🔌 **Alpaca Trading API** - Easy-to-use wrapper for Alpaca trading platform
 - 📈 **Technical Analysis** - Algorithmic trading strategies and indicators
 - 🎯 **Social Trading** - Track and analyze top traders and strategies
@@ -111,51 +113,36 @@ const leaders = await fetchLeaderboard({
 });
 ```
 
-### Kalshi Momentum Paper Agent
+### PredictOS — Prediction-Market Analysis & Arbitrage
 
-The prediction-markets package includes a deterministic TypeScript port of the
-momentum rules from PyKalshi's MIT-licensed
-`kalshi-bot-api/examples/momentum_bot.py`. It consumes recorded ticks and uses
-an in-memory paper executor, so it never connects to Kalshi, submits orders, or
-requires credentials.
+```typescript
+import {
+  runEventAnalysisAgent,
+  findArbitrage,
+  getEvents,
+} from "investing/predictos";
 
-Run the included replay from `packages/investing`:
+const url = "https://polymarket.com/event/will-x-happen-by-2026";
 
-```bash
-bun run demo:kalshi-momentum
-```
+// Resolve a Polymarket / Kalshi / Jupiter event URL into its raw markets
+const event = await getEvents({ url });
 
-```typescript
-import { runKalshiMomentumPaperAgent } from "investing/prediction-markets";
-
-const result = runKalshiMomentumPaperAgent({
-  initialCashCents: 10_000,
-  ticks: [50, 51, 52, 53, 58].map((yesPriceCents, index) => ({
-    ticker: "DEMO-KALSHI-MARKET",
-    timestamp: new Date(Date.UTC(2026, 0, 1, 0, index)).toISOString(),
-    yesPriceCents,
-  })),
+// Analyze those markets for alpha and a predicted winner
+const { analysis } = await runEventAnalysisAgent({
+  markets: event.markets,
+  eventIdentifier: event.eventIdentifier,
+  pmType: event.pmType,
+  model: "grok-4-fast",
+  tools: ["x_search"], // Grok models only
 });
 
-console.log(result.report);
+// Look for the same event mispriced on the other venue
+const arb = await findArbitrage({ url, model: "grok-4-fast" });
 ```
 
-Prices are integer cents per contract. A YES tick of `53` implies a NO price
-of `47`. Trade `action` (`BUY`, `SELL`, `HOLD`) is separate from the binary
-`outcome` (`YES`, `NO`): selling YES closes YES contracts and does not mean
-buying NO.
-
-Configuration controls `lookback`, `momentumThreshold`, `positionSize`,
-`profitTargetCents`, `stopLossCents`, and `maxPosition`. The defaults preserve
-the upstream example: three consecutive moves, 10 contracts, a 5-cent target,
-a 3-cent stop, and a 50-contract limit. The paper executor fills immediately at
-the recorded outcome price with no fees or slippage and reports cash, open
-positions, and realized/unrealized P&L.
-
-This replay is a strategy demonstration, not a backtest or live execution
-system. It assumes complementary YES/NO prices, does not model an order book,
-partial fills, fees, latency, settlement, or market resolution, and does not
-enable the existing unimplemented Kalshi live mapper.
+Every entry point takes a typed `request` object and an optional second
+`config` (`AIConfig` / `DataConfig`) that falls back to `process.env`. Missing
+required fields **throw** rather than returning an error result.
 
 ### Trading Agents Framework
 
@@ -261,7 +248,7 @@ Get Polymarket leaderboard of top traders.
 - `limit` - Number of results (default: 20)
 - `category` - Market category (default: 'overall')
 
-### Prediction-Market Agents & Arbitrage
+### PredictOS Core
 
 ```typescript
 import {
@@ -270,26 +257,80 @@ import {
   runMapperAgent,
   findArbitrage,
   getEvents,
-} from "investing/prediction-markets";
+} from "investing/predictos";
 ```
 
-Multi-agent analysis over Polymarket and Kalshi, refactored from Deno/Supabase
-edge functions into plain typed async functions (MIT, see
-`src/prediction-markets/LICENSE`):
-
-- **AI clients** — OpenAI, Grok/xAI and BlockRun (x402 micropayments), plus the
-  analysis prompt builders.
-- **Market data** — Kalshi via DFlow and Polymarket via Dome/Gamma.
-- `runEventAnalysisAgent` — analyzes an event's markets for alpha and a
-  predicted winner.
-- `runBookmakerAgent` — aggregates several agent analyses into one assessment.
-- `runMapperAgent` — turns an analysis into Polymarket order parameters.
-- `findArbitrage` — finds the same event on the other venue and checks whether
-  it is mispriced across venues.
-- `getEvents` — resolves a Polymarket/Kalshi URL into its raw markets.
-
-Keys are read from options, falling back to `OPENAI_API_KEY`, `XAI_API_KEY`,
-`BLOCKRUN_WALLET_KEY`, `DOME_API_KEY` and `DFLOW_API_KEY`.
+> Adapted from [PredictOS](https://github.com/PredictionXBT/PredictOS) by
+> **PredictionXBT** (MIT licensed, © 2025). The original code shipped as
+> Deno/Supabase edge functions; here it is refactored into plain, typed,
+> dependency-light library functions with no HTTP/CORS layer. It lived in a
+> sibling `predictos` package until that package was merged into `investing`.
+> See [`NOTICE`](./NOTICE) and
+> [`LICENSE-PredictOS-MIT`](./LICENSE-PredictOS-MIT).
+
+#### What it covers
+
+- **AI provider clients** — OpenAI (Responses API), Grok/xAI (Responses API,
+  with optional `x_search` / `web_search` tools), and BlockRun (x402
+  wallet-based micropayments across 20+ models), plus the analysis prompt
+  builders (`analyzeEventMarkets`, `bookmakerAnalysis`, `arbitrageAnalysis`,
+  `searchQueryGenerator`).
+- **Market data clients** — Kalshi via the DFlow API
+  (`investing/predictos/data/kalshi`) and Polymarket via the Dome API
+  (`investing/predictos/data/polymarket`).
+- **Multi-agent pipeline** (`investing/predictos/agents`):
+  - `runEventAnalysisAgent` — analyzes an event's markets for alpha and a
+    predicted winner.
+  - `runBookmakerAgent` — aggregates multiple agent analyses (and optional
+    external data sources) into a single consolidated assessment.
+  - `runMapperAgent` — turns an analysis into Polymarket order parameters
+    (pure logic; Kalshi mapping not yet implemented).
+- **Cross-platform arbitrage** (`investing/predictos/arbitrage`) —
+  `findArbitrage` parses a Polymarket/Kalshi URL, generates a search query with
+  AI, searches the other platform, and evaluates whether the same event is
+  mispriced across venues.
+- **Event fetching** (`getEvents`) — resolves a Polymarket/Kalshi/Jupiter URL
+  into its raw markets (Kalshi via DFlow, Polymarket via the Gamma API).
+
+#### Subpath exports
+
+| Import | Contents |
+| --- | --- |
+| `investing/predictos` | Everything (barrel) |
+| `investing/predictos/ai` | AI clients + prompt builders |
+| `investing/predictos/data/kalshi` | Kalshi (DFlow) data client |
+| `investing/predictos/data/polymarket` | Polymarket (Dome) data client |
+| `investing/predictos/agents` | `runEventAnalysisAgent`, `runBookmakerAgent`, `runMapperAgent` |
+| `investing/predictos/arbitrage` | `findArbitrage` |
+
+The barrel re-exports the Kalshi (DFlow) client at the top level. The Polymarket
+(Dome) client exposes Kalshi helpers under the same names, so the barrel renames
+those two to `getDomeKalshiMarketsByEvent` / `buildDomeKalshiMarketUrl` — import
+from `investing/predictos/data/polymarket` for their original names. The
+Gamma/CLOB trading client, Polyfactual and x402 are namespaced on the barrel as
+`polymarketClob`, `polyfactual` and `x402` for the same reason.
+
+#### Refactor notes (Deno → Node)
+
+- Deno HTTP handlers (`Deno.serve`, `new Response(...)`, CORS headers) were
+  removed. Each endpoint is now a plain exported async function taking typed
+  parameters and returning a typed result; validation failures `throw`.
+- `Deno.env.get("X")` was replaced with config/options objects
+  (`AIConfig`, `DataConfig`, per-call `apiKey`/`walletKey`) that fall back to
+  `process.env` (`OPENAI_API_KEY`, `XAI_API_KEY`, `BLOCKRUN_WALLET_KEY`,
+  `DOME_API_KEY`, `DFLOW_API_KEY`). No secrets are hardcoded.
+- Remote (`https://...`) and `npm:` import specifiers were replaced with normal
+  package imports (`ethers`). The global `fetch` (Node 18+) is used throughout.
+- Prompt text and analysis logic are preserved verbatim.
+
+#### Not ported (yet)
+
+Intentionally left out of the core port — noted for future work: the Next.js
+`terminal/` frontend, the Python alpha-hunter examples, the **pay.sh** payment
+serving flows, **Irys** verifiable-agent storage, wallet-tracking websockets, and
+on-chain order execution (the mapper produces order parameters, but placing
+orders is out of scope). The BlockRun client *is* ported (it only needs `ethers`
++ `fetch`), but its on-chain micropayment flow is untested in this environment.
 
 ### Trading Agents
 
@@ -370,6 +411,12 @@ ALPACA_SECRET=your_secret_here
 # OpenAI for AI-powered analysis
 OPENAI_API_KEY=your_openai_key
 
+# PredictOS: prediction-market analysis and data
+XAI_API_KEY=your_xai_key           # Grok/xAI
+BLOCKRUN_WALLET_KEY=your_wallet_key # BlockRun x402 micropayments
+DOME_API_KEY=your_dome_key          # Polymarket market data
+DFLOW_API_KEY=your_dflow_key        # Kalshi market data
+
 # Optional: Alternative LLM providers
 ANTHROPIC_API_KEY=your_anthropic_key
 GOOGLE_API_KEY=your_google_key
@@ -482,7 +529,15 @@ See the `/examples` directory for complete working examples:
 
 - [GitHub Repository](https://github.com/vtempest/ai-broker-investment-agent)
 - [Documentation](https://invest.vtempest.com/docs)
+- [Agent skill](../../skills/ask-investing/SKILL.md)
 - [Examples](./examples)
 
+## Credits
+
+The `predictos` module is a derivative work of
+[PredictOS](https://github.com/PredictionXBT/PredictOS) — all original design and
+logic © 2025 PredictionXBT, MIT licensed. See [`NOTICE`](./NOTICE) and
+[`LICENSE-PredictOS-MIT`](./LICENSE-PredictOS-MIT).
+
 - [GitHub Issues](https://github.com/vtempest/ai-broker-investment-agent/issues)
 - [Documentation](https://invest.vtempest.com/docs)