truth-terminal

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Truth Terminal

Truth Terminal is a **prediction research workstation for timing arbitrage** on Polymarket.

## The Vision

The fundamental question it answers:

> “I believe X will happen, but the market prices in uncertainty about *when*. How do I time my entry to maximize returns?”

This is **not HFT**. The edge is:
- Better prediction of **when information arrives**
- Better modeling of **how repricing unfolds over time**
- Disciplined execution via **precommitted rules**

We’re building five core capabilities, in order:
1. **Watchlist + Conviction Tracker** (structured theses + edge vs market)
2. **Polymarket Order Book** (liquidity/spread/depth/slippage)
3. **Information Calendar** (when will new info arrive that moves watched markets?)
4. **Entry Rule Engine** (precommitted IF/THEN rules; alerts first)
5. **Portfolio Dashboard** (positions + P&L + concentration/time-to-resolution)

## Current Status

What works today:

- **Bloomberg-vibes local UI** with windows/workspaces/persistence (`web/`, `src/ui/server.ts`)
- **Tool registry + agent tool-calling** (agent can fetch live data sources on-demand; `GET /api/tools`)
- **Research agent** that can produce structured cases and transcripts (`src/agents/`, `data/cases/`, `data/transcripts/`)
- **Manipulation detection** (trade stream → enrichment → detection report) (`src/manipulation/`, `data/manipulation.db`)
- **Local SQLite** persistence for core subsystems (`data/*.db`)

What’s missing (roadmap work):
- Workflow refinements: conviction editor, case→conviction linking, real-time edge refresh, richer portfolio analytics
- Window-targeted outputs (tool routing) + more data tools
- Unified server→UI event streaming (event bus)
- Provider hardening (rate limits/retries/fallbacks)

## Quick Start

```bash
npm install
cp .env.example .env
# Add your API keys to .env:
#   ANTHROPIC_API_KEY=sk-ant-...
#   GROK_API_KEY=xai-...   # or XAI_API_KEY
```

### Commands

```bash
# UI (Bloomberg-vibes)
npm run ui
# open http://127.0.0.1:7777

# CLI (REPL)
npm run tt
npm run tt -- --eval "help"

# Test individual components
npm run test:grok "Russia Ukraine ceasefire"
npm run test:youtube <video-id>

# Research
npm run phase0:list              # List top markets
npm run phase0 516719            # Claude-only research
npm run research 516719          # Grok+Claude pipeline
npm run research:quick 516719    # Faster
npm run research:agentic 516719  # Tool-using agent (transcripts + scratchpad)

# Manipulation detection (Polymarket)
npm run stream
npm run stream:enrich
npm run stream:detect
npm run stream:stats
```

## Architecture

Truth Terminal is a local UI + a thin command surface + a set of subsystems:

- **UI layer:** `src/ui/server.ts` + `web/` (windows/workspaces; localhost-only)
- **Command surface:** `src/core/` (parsing + command registry used by `/api/exec` and CLI)
- **Research system:** `src/agents/`, `src/db/`, `data/truth-terminal.db`
- **Manipulation detection:** `src/manipulation/`, `data/manipulation.db`
- **Execution simulator (local):** `src/execution/`, `data/execution.db`

## Project Structure

```
src/
├── agents/
│   ├── claude.ts       # Claude SDK, basic research
│   ├── grok.ts         # Grok Live Search (X + web + news)
│   ├── youtube.ts      # YouTube transcript extraction
│   └── research.ts     # Multi-source research orchestrator
│   └── agentic-research.ts  # Tool-using agent (logs + scratchpad)
├── tools/               # Provider-agnostic tools (JSONSchema params → structured data)
├── polymarket/
│   └── client.ts       # Polymarket API client
├── manipulation/        # Polymarket manipulation detection
├── execution/           # Local execution simulator
├── ui/                  # UI server
├── core/                # Command parsing/registry
├── db/
│   └── index.ts        # SQLite for cases, decisions, trades
├── types/
│   └── market.ts       # Type definitions
├── phase0.ts           # Basic single-source research
├── test-grok.ts        # Grok integration test
├── test-youtube.ts     # YouTube transcript test
└── test-research.ts    # Full pipeline test

web/                     # UI (HTML/CSS/JS)
```

## Intel Sources

| Source | Status | Cost | What it provides |
|--------|--------|------|------------------|
| Polymarket APIs | ✅ | Free | Markets (Gamma), trades (Data API), order books (CLOB) |
| Grok Live Search | ✅ | $25/1k sources | Twitter/X + web + news |
| GDELT | ✅ | Free | News headlines |
| CoinGecko | ✅ | Free | Crypto spot prices/24h change |
| YouTube Transcripts | ✅ | Free | Video content analysis |
| Claude Sonnet | ✅ | API pricing | Analysis and synthesis |
| Nasdaq (delayed) | ✅ | Free | US stock quotes + candles |

## Research Case Output

Each research case includes:

```json
{
  "thesis": "Clear statement of position and reasoning",
  "edge": "What the market is missing",
  "recommendedPosition": "Yes/No/None",
  "confidence": "low/medium/high",
  "keyUncertainties": ["list", "of", "risks"],
  "whatWouldChangeAssessment": "Specific conditions",
  "sources": ["citations from Grok/web"],
  "twitterSignal": "bullish/bearish/neutral",
  "newsSignal": "bullish/bearish/neutral"
}
```

## Data Storage

- Research: `data/truth-terminal.db`, `data/cases/`, `data/transcripts/`, `data/scratchpads/`
- Manipulation: `data/manipulation.db`
- Execution (sim): `data/execution.db`

## Development Roadmap

- [x] UI shell (windows/workspaces) + local server
- [x] Research agent + cases/transcripts
- [x] Manipulation detection (stream/enrich/detect)
- [x] Watchlist + conviction tracker (v1: schema + CRUD + UI)
- [x] Polymarket order book window (v1: CLOB depth + slippage)
- [x] Information calendar (v1: events CRUD + UI)
- [x] Entry rule engine (v1: alerts-only)
- [x] Portfolio dashboard (v1: positions CRUD + P&L)
- [x] Agent upgrade (tool registry + tool-calling)
- [ ] Agent upgrade (window targeting, durable memory)
- [ ] Event bus (server→UI streaming) + provider hardening

## API Costs

Rough estimates per research case:
- Claude Sonnet: ~$0.02-0.05
- Grok Live Search: ~$0.10-0.50 (depends on sources)
- YouTube: Free
- Polymarket: Free

## Resources

- [Polymarket API Docs](https://docs.polymarket.com)
- [xAI/Grok API Docs](https://docs.x.ai)
- [Polymarket agents repo](https://github.com/Polymarket/agents)

Truth Terminal

Truth Terminal is a prediction research workstation for timing arbitrage on Polymarket.

The Vision

The fundamental question it answers:

“I believe X will happen, but the market prices in uncertainty about when. How do I time my entry to maximize returns?”

This is not HFT. The edge is:

Better prediction of when information arrives
Better modeling of how repricing unfolds over time
Disciplined execution via precommitted rules

We’re building five core capabilities, in order:

Watchlist + Conviction Tracker (structured theses + edge vs market)
Polymarket Order Book (liquidity/spread/depth/slippage)
Information Calendar (when will new info arrive that moves watched markets?)
Entry Rule Engine (precommitted IF/THEN rules; alerts first)
Portfolio Dashboard (positions + P&L + concentration/time-to-resolution)

Current Status

What works today:

Bloomberg-vibes local UI with windows/workspaces/persistence (web/, src/ui/server.ts)
Tool registry + agent tool-calling (agent can fetch live data sources on-demand; GET /api/tools)
Research agent that can produce structured cases and transcripts (src/agents/, data/cases/, data/transcripts/)
Manipulation detection (trade stream → enrichment → detection report) (src/manipulation/, data/manipulation.db)
Local SQLite persistence for core subsystems (data/*.db)

What’s missing (roadmap work):

Workflow refinements: conviction editor, case→conviction linking, real-time edge refresh, richer portfolio analytics
Window-targeted outputs (tool routing) + more data tools
Unified server→UI event streaming (event bus)
Provider hardening (rate limits/retries/fallbacks)

Quick Start

npm install
cp .env.example .env
# Add your API keys to .env:
#   ANTHROPIC_API_KEY=sk-ant-...
#   GROK_API_KEY=xai-...   # or XAI_API_KEY

Commands

# UI (Bloomberg-vibes)
npm run ui
# open http://127.0.0.1:7777

# CLI (REPL)
npm run tt
npm run tt -- --eval "help"

# Test individual components
npm run test:grok "Russia Ukraine ceasefire"
npm run test:youtube <video-id>

# Research
npm run phase0:list              # List top markets
npm run phase0 516719            # Claude-only research
npm run research 516719          # Grok+Claude pipeline
npm run research:quick 516719    # Faster
npm run research:agentic 516719  # Tool-using agent (transcripts + scratchpad)

# Manipulation detection (Polymarket)
npm run stream
npm run stream:enrich
npm run stream:detect
npm run stream:stats

Architecture

Truth Terminal is a local UI + a thin command surface + a set of subsystems:

UI layer: src/ui/server.ts + web/ (windows/workspaces; localhost-only)
Command surface: src/core/ (parsing + command registry used by /api/exec and CLI)
Research system: src/agents/, src/db/, data/truth-terminal.db
Manipulation detection: src/manipulation/, data/manipulation.db
Execution simulator (local): src/execution/, data/execution.db

Project Structure

src/
├── agents/
│   ├── claude.ts       # Claude SDK, basic research
│   ├── grok.ts         # Grok Live Search (X + web + news)
│   ├── youtube.ts      # YouTube transcript extraction
│   └── research.ts     # Multi-source research orchestrator
│   └── agentic-research.ts  # Tool-using agent (logs + scratchpad)
├── tools/               # Provider-agnostic tools (JSONSchema params → structured data)
├── polymarket/
│   └── client.ts       # Polymarket API client
├── manipulation/        # Polymarket manipulation detection
├── execution/           # Local execution simulator
├── ui/                  # UI server
├── core/                # Command parsing/registry
├── db/
│   └── index.ts        # SQLite for cases, decisions, trades
├── types/
│   └── market.ts       # Type definitions
├── phase0.ts           # Basic single-source research
├── test-grok.ts        # Grok integration test
├── test-youtube.ts     # YouTube transcript test
└── test-research.ts    # Full pipeline test

web/                     # UI (HTML/CSS/JS)

Intel Sources

Source	Status	Cost	What it provides
Polymarket APIs	✅	Free	Markets (Gamma), trades (Data API), order books (CLOB)
Grok Live Search	✅	$25/1k sources	Twitter/X + web + news
GDELT	✅	Free	News headlines
CoinGecko	✅	Free	Crypto spot prices/24h change
YouTube Transcripts	✅	Free	Video content analysis
Claude Sonnet	✅	API pricing	Analysis and synthesis
Nasdaq (delayed)	✅	Free	US stock quotes + candles

Research Case Output

Each research case includes:

{
  "thesis": "Clear statement of position and reasoning",
  "edge": "What the market is missing",
  "recommendedPosition": "Yes/No/None",
  "confidence": "low/medium/high",
  "keyUncertainties": ["list", "of", "risks"],
  "whatWouldChangeAssessment": "Specific conditions",
  "sources": ["citations from Grok/web"],
  "twitterSignal": "bullish/bearish/neutral",
  "newsSignal": "bullish/bearish/neutral"
}

Data Storage

Research: data/truth-terminal.db, data/cases/, data/transcripts/, data/scratchpads/
Manipulation: data/manipulation.db
Execution (sim): data/execution.db

Development Roadmap

UI shell (windows/workspaces) + local server
Research agent + cases/transcripts
Manipulation detection (stream/enrich/detect)
Watchlist + conviction tracker (v1: schema + CRUD + UI)
Polymarket order book window (v1: CLOB depth + slippage)
Information calendar (v1: events CRUD + UI)
Entry rule engine (v1: alerts-only)
Portfolio dashboard (v1: positions CRUD + P&L)
Agent upgrade (tool registry + tool-calling)
Agent upgrade (window targeting, durable memory)
Event bus (server→UI streaming) + provider hardening

API Costs

Rough estimates per research case:

Claude Sonnet: ~$0.02-0.05
Grok Live Search: ~$0.10-0.50 (depends on sources)
YouTube: Free
Polymarket: Free