investing 0.1.310 → 0.1.312

package/README.md

@@ -4,26 +4,30 @@
 
 <!-- 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 -->
 
+<!-- skills:install:start -->
+**🤖 Agent skill** — `npx skills@latest add https://github.com/OpenSourceAGI/qwksearch-research-agent --skill investing` ([what it covers](../../skills/investing/SKILL.md))
+<!-- skills:install:end -->
+
 # Investing Library
 
 A comprehensive TypeScript/JavaScript library for investment analysis, trading automation, and financial data processing. This package provides reusable utilities for building investment applications, trading bots, and financial analysis tools.
@@ -33,98 +37,14 @@ 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
 - 🧠 **AI-Powered Analysis** - LLM-based investment research and debate generation
 - 📦 **Data Files** - Pre-packaged stock indexes, sector information, and market data
 
-## Third-party strategy signals
-
-The source integration connects all ten vendored project folders to the agent
-pipeline through pure sources, venue/data mappings and a survival risk posture.
-The [integration overview](../../devdocs/third-party-trading-bots-overview.md)
-records each project's runtime, license, native assessment and operational scope.
-Full notices ship in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
-
-From the repository root, run the credential-free paper demo in Docker:
-
-```bash
-bash devdocs/third-party-integration/harness/run.sh install
-bash devdocs/third-party-integration/harness/run.sh demo
-```
-
-The image uses pinned Bun 1.3.11 with Node/native build prerequisites. Dependencies
-live in container-only volumes; the staged repository excludes credentials and
-host node_modules. Tests and the demo run with `--network=none`.
-
-The demo first prints a readable summary: six numbered stages per run (strategy,
-normalized signal, research input, Trader, Portfolio Manager, execution). It then
-prints the full JSON trace: signals → report → proposal → Trader → risk debate → judge →
-verdict → Fund Manager → approval → fill → account snapshots. It includes momentum
-BUY/SELL, Vibe YES/NO, BTC bullish/bearish, copy sizing, sequential Gabagool targets,
-PyKalshi and pmxt mappings, OpenBB-backed stock BUY/SELL and Defensive sizing.
-The pmxt fixture opts into explicitly synthetic quotes; a point price is not a
-live executable quote. Models are scripted and all prices/forecasts are fixtures.
-
-Source consumers can opt into the new stage with the fourth graph argument and
-the third `propagate` argument:
-
-```typescript
-// Source-level example inside packages/investing. Avoid src/index.ts: it loads
-// native dependencies and dotenv. Built package/subpath imports remain broken.
-import { TradingAgentsGraph } from './src/trading-agents/graph/trading-graph'
-import { kalshiMomentumSource } from './src/strategy-signals/sources/kalshi-momentum'
-
-const graph = new TradingAgentsGraph([], false, undefined, {
-  llm: { deep: suppliedLLM, quick: suppliedLLM },
-  riskReview: true,
-  riskLimits: { maxPositionPerMarket: 50, maxOpenPositions: 5 },
-})
-const context = { account: venue.snapshot(), evaluationTime }
-const strategySignals = kalshiMomentumSource.run({ ticks }, context)
-const result = await graph.propagate(market.title, evaluationTime.slice(0, 10), {
-  instrument: { type: 'event', venue: venue.venue, marketId: market.marketId },
-  strategySignals,
-  account: context.account,
-  evaluationTime,
-  event: market,
-  sources: { [kalshiMomentumSource.id]: kalshiMomentumSource },
-})
-if (result.state.approval) await venue.execute(result.state.approval)
-```
-
-The caller supplies the LLM, current venue/account, market and evaluation time. With `riskReview: true`, an `account` snapshot is required for stocks too: without one the gate cannot check cash or holdings, so the run ends at HOLD.
-Register each executable source so its freshness and guards can run; unregistered
-third-party proposals fail closed. Event runs skip stock analysts. Fixture stock
-runs select no external analysts and execute an Alpaca-shaped order against
-`MockEquityBroker` after a cash/share preflight. Existing callers without `run`
-retain byte-identical prompts; risk review is opt-in.
-
-Every executable result binds to one selected `proposalId`. BLOCK means HOLD;
-REDUCE supplies a whole-number cap. Final quantity is the minimum of the proposal,
-common/source risk caps, judge cap and Fund Manager quantity. Invalid model output
-or model errors cannot grant approval. Red flags remain advisory input. Forecast
-guards/Kelly apply only to genuine forecasts, never a substituted market price.
-
-Gabagool portfolio targets execute one leg per call, recomputed from actual
-holdings and fill costs. A rejected leg does not create a holding. Strategy prices
-retain decimal-cent precision; the paper execution bridge rejects unsupported
-sub-cent prices. Fractional weighted average costs are valid account values.
-Survival multipliers (1 / 1 / 0.75 / 0.5 / 0) are new demo policy, not upstream rules.
-
-Verification commands are `run.sh test`, `test-root`, `tsc`, `build`, `coverage`
-and `pack`. The type gate permits only reproduced pre-existing diagnostic
-identities/occurrences; it does not claim a clean TypeScript build. Coverage is
-reported for the new module and changed graph/risk-judge files.
-
-**Scope:** source-level fixture/paper execution only. Built exports, the web app
-and Workers runtime are not validated by this demo. Live broker/venue execution,
-an execution ledger, portfolio versioning and concurrency control are outside
-this integration. Current snapshots must be refreshed and callers must serialize
-execution. See the [workflow](../../devdocs/third-party-integration/skills/integrate-trading-bot/SKILL.md)
-to add a source, mapping or posture.
-
 ## Installation
 
 ```bash
@@ -197,68 +117,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.
-
-The recorded demo also runs actionable intents through the existing
-strategy-signal graph, research judge, Trader, risk review and proposal-bound
-FundManager before this same paper executor. It requires no keys or services.
-The original synchronous API remains direct strategy/paper replay.
-
-For graph review, use `runKalshiMomentumPaperAgentWithResearch` and
-`reviewPredictionMarketIntent`. Configure the existing graph with
-`riskReview: true`, and pass `{ fundManagerReview: true }` to the review
-adapter to require unchanged explicit approval. MODIFY, missing approval or
-a changed quantity becomes HOLD for this replay; the executor retains its
-own cash, inventory and combined market-position checks.
-
-After building, run `node scripts/verify-prediction-market-build.mjs` to check
-actual ESM/CommonJS subpaths and the packaged MIT notice. See the
-[walkthrough](../../devdocs/prediction-markets-agent-system-walkthrough.md) for
-the full flow and the recorded result of $100.50 cash and $0.50 realized P&L.
+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
 
@@ -364,7 +252,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 {
@@ -373,26 +261,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
 
@@ -473,6 +415,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
@@ -585,7 +533,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/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)