@spfunctions/cli 1.4.4 → 1.5.0

package/README.md

@@ -1,92 +1,249 @@
 # SimpleFunctions CLI (`sf`)
 
-Prediction market thesis agent CLI. Pure HTTP client — no project dependencies.
+Prediction market intelligence CLI. Build causal thesis models, scan Kalshi/Polymarket for mispricings, detect edges, and trade — all from the terminal.
 
-## Install
+## Quick Start
 
 ```bash
 npm install -g @spfunctions/cli
+sf setup                            # interactive config wizard
+sf list                             # see your theses
+sf context <id> --json              # get thesis state as JSON
 ```
 
-## Configuration
+## Setup
+
+### Interactive (recommended)
 
 ```bash
-export SF_API_KEY=sf_live_xxx           # required
-export SF_API_URL=https://simplefunctions.dev  # optional, defaults to production
+sf setup
 ```
 
-Or pass inline:
+This walks you through:
+1. **SF API key** (required) — get one at [simplefunctions.dev](https://simplefunctions.dev)
+2. **Kalshi credentials** (optional) — for positions, trading, and orderbook data
+3. **Trading mode** (optional) — enable `sf buy`/`sf sell` commands
+
+Config is saved to `~/.sf/config.json`. Environment variables override config values.
+
+### Manual
+
 ```bash
-sf --api-key sf_live_xxx list
+export SF_API_KEY=sf_live_xxx                    # required
+export KALSHI_API_KEY_ID=xxx                     # optional, for positions/trading
+export KALSHI_PRIVATE_KEY_PATH=~/.ssh/kalshi.pem # optional, for positions/trading
 ```
 
-## Commands
+### Verify
 
-### `sf list`
-List all theses.
-```
-ID          Status  Conf    Updated         Title
-f582bf76    active   82%    Mar 12 11:13    Trump cannot exit the Iran war...
+```bash
+sf setup --check     # show current config status
+sf list              # should show your theses
 ```
 
-### `sf get <id>`
-Full thesis details: causal tree, edge analysis, positions, last evaluation.
+## Commands
+
+### Thesis Management
+
+| Command | Description |
+|---------|-------------|
+| `sf list` | List all theses with status, confidence, and update time |
+| `sf get <id>` | Full thesis details: causal tree, edges, positions, last evaluation |
+| `sf context <id>` | Compact context snapshot (primary command for agents) |
+| `sf create "thesis"` | Create a new thesis (waits for formation by default) |
+| `sf signal <id> "text"` | Inject a signal (news, observation) for next evaluation |
+| `sf evaluate <id>` | Trigger deep evaluation with heavy model |
+| `sf publish <id>` | Make thesis publicly viewable |
+| `sf unpublish <id>` | Remove from public view |
+
+### Market Exploration (no auth required)
+
+| Command | Description |
+|---------|-------------|
+| `sf scan "keywords"` | Search Kalshi markets by keyword |
+| `sf scan --series KXWTIMAX` | List all markets in a series |
+| `sf scan --market TICKER` | Get single market detail |
+| `sf explore` | Browse public theses |
+
+### Portfolio & Trading (requires Kalshi credentials)
+
+| Command | Description |
+|---------|-------------|
+| `sf edges` | Top edges across all theses — what to trade now |
+| `sf positions` | Current positions with P&L and edge overlay |
+| `sf balance` | Account balance |
+| `sf orders` | Resting (open) orders |
+| `sf fills` | Recent trade fills |
+| `sf performance` | P&L over time with thesis event annotations |
+| `sf settlements` | Settled contracts with final P&L |
+| `sf liquidity` | Market liquidity scanner by topic |
+
+### Trading (requires `sf setup --enable-trading`)
+
+| Command | Description |
+|---------|-------------|
+| `sf buy <ticker> <qty>` | Buy contracts |
+| `sf sell <ticker> <qty>` | Sell contracts |
+| `sf cancel [orderId]` | Cancel order(s) |
+| `sf rfq <ticker> <qty>` | Request for quote on large orders |
+
+### Analysis
+
+| Command | Description |
+|---------|-------------|
+| `sf whatif <id>` | What-if scenario: "if node X drops to 10%..." |
+| `sf feed` | Evaluation history stream |
+| `sf forecast <event>` | Market distribution forecast (P50/P75/P90) |
+| `sf dashboard` | Interactive TUI portfolio overview |
+
+### Interactive Modes
+
+| Command | Description |
+|---------|-------------|
+| `sf agent [id]` | Interactive agent with natural language + tool calling |
+| `sf telegram` | Telegram bot for monitoring and trading |
+
+## JSON Output
+
+Most commands support `--json` for machine-readable output:
+
 ```bash
-sf get f582bf76
+sf list --json
+sf context f582bf76 --json
+sf edges --json
+sf scan "oil" --json
 sf get f582bf76 --json
 ```
 
-### `sf context <id>`
-**Primary command for agents.** Returns a compact context snapshot: thesis, confidence, causal tree nodes, top edges, positions, last evaluation summary.
+## For AI Agents
+
+**If you are an AI coding agent (Claude, GPT, OpenClaw, Cursor, etc.), follow these steps:**
+
+### Step 1: Install and configure
+
 ```bash
-sf context f582bf76
-sf context f582bf76 --json   # machine-readable for agent parsing
+npm install -g @spfunctions/cli
+sf setup --key sf_live_YOUR_KEY_HERE
 ```
 
-### `sf create "thesis text"`
-Create a new thesis. Sync by default (waits for formation agent to complete).
+If `sf setup` is not available or you cannot run interactive commands:
 ```bash
-sf create "Trump cannot exit the Iran war gracefully before 2027"
-sf create "..." --async   # return immediately
+export SF_API_KEY=sf_live_YOUR_KEY_HERE
 ```
 
-### `sf signal <id> "content"`
-Inject a signal into the thesis queue. Queued for next monitor cycle.
+### Step 2: Verify it works
+
 ```bash
-sf signal f582bf76 "Oil closes at $95 today"
-sf signal f582bf76 "Iran closes Strait of Hormuz" --type news
-sf signal f582bf76 "My read: escalation likely" --type user_note
+sf list
+```
+
+Expected output (table format):
+```
+ID          Status  Conf    Updated         Title
+f582bf76    active   82%    Mar 12 11:13    Oil prices will exceed $100...
+a1b2c3d4    active   65%    Mar 11 09:30    Fed will cut rates by June...
 ```
-Signal types: `news` | `user_note` | `external` (default: `user_note`)
 
-### `sf evaluate <id>`
-Trigger a deep evaluation using the heavy model (Claude Opus).
+If you see theses, the CLI is working. If you see an error, check that `SF_API_KEY` is set correctly.
+
+### Step 3: Get thesis context (most important command)
+
 ```bash
-sf evaluate f582bf76
+sf context <thesisId> --json
 ```
 
-### `sf scan "keywords"`
-Explore Kalshi markets directly (no auth required).
+This returns a JSON object with the complete thesis state:
+
+```json
+{
+  "thesisId": "f582bf76-3113-4208-b0c1-...",
+  "thesis": "Oil prices will exceed $100 by end of 2026",
+  "title": "Oil Bull Thesis",
+  "status": "active",
+  "confidence": 0.82,
+  "causalTree": {
+    "rootClaim": "Oil prices will exceed $100",
+    "nodes": [
+      {
+        "id": "n1",
+        "label": "Supply disruption",
+        "probability": 0.75,
+        "importance": 0.6,
+        "depth": 0
+      }
+    ]
+  },
+  "edges": [
+    {
+      "marketId": "KXWTIMAX-26DEC31-T100",
+      "market": "Will oil exceed $100 by Dec 2026?",
+      "venue": "kalshi",
+      "direction": "yes",
+      "marketPrice": 35,
+      "thesisPrice": 55,
+      "edge": 20,
+      "confidence": 0.8
+    }
+  ],
+  "lastEvaluation": {
+    "summary": "Supply concerns rising due to...",
+    "newConfidence": 0.82,
+    "confidenceDelta": 0.03
+  }
+}
+```
+
+**Key fields:**
+- `confidence` — overall thesis probability (0 to 1)
+- `edges[].edge` — mispricing size in cents (positive = market underpriced vs thesis)
+- `edges[].marketPrice` — current market price in cents (0-100)
+- `edges[].thesisPrice` — what the thesis model thinks the price should be
+- `lastEvaluation.summary` — human-readable summary of latest analysis
+
+### Step 4: Other useful commands
+
 ```bash
-sf scan "oil recession iran"
-sf scan --series KXWTIMAX
-sf scan --market KXWTIMAX-26DEC31-T140
-sf scan "oil" --json
+# Inject a signal for the thesis to consider in its next evaluation
+sf signal <thesisId> "Breaking: OPEC announces production cut" --type news
+
+# View top edges (mispricings) across all theses
+sf edges --json
+
+# Search Kalshi markets by keyword
+sf scan "recession" --json
+
+# Trigger a deep re-evaluation
+sf evaluate <thesisId>
+
+# What-if analysis: what happens if a node probability changes?
+sf whatif <thesisId>
 ```
 
-## For AI Agents (OpenClaw etc.)
+### Common patterns for agents
 
-After `npm install -g simplefunctions` and setting `SF_API_KEY`:
+**Monitor a thesis:**
+```bash
+sf context <id> --json    # poll periodically, check confidence changes
+```
 
+**React to news:**
+```bash
+sf signal <id> "Reuters: Iran nuclear deal collapses" --type news
+sf evaluate <id>          # trigger re-evaluation after injecting signal
+sf context <id> --json    # read updated state
 ```
-You can use the sf CLI to interact with SimpleFunctions:
-- sf context <id> --json    Get current thesis state (JSON)
-- sf signal <id> "content"  Inject an observation note
-- sf list                   List all theses
-- sf scan "keywords"        Explore Kalshi markets
+
+**Find trading opportunities:**
+```bash
+sf edges --json           # get top mispricings sorted by edge size
 ```
 
-Agents should call `sf context <id> --json` periodically to get the latest state, then decide whether to inject signals or alert the user.
+### Error handling
+
+- **"API key required"** — set `SF_API_KEY` env var or run `sf setup --key <key>`
+- **"Thesis not found"** — use `sf list` to get valid thesis IDs. IDs can be short prefixes (first 8 chars)
+- **"Kalshi not configured"** — positions/trading commands need Kalshi credentials via `sf setup`
+- **Exit code 0** — success. **Exit code 1** — error (message printed to stderr)
 
 ## Local Development
 
@@ -95,6 +252,6 @@ cd cli
 npm install
 npm run dev -- list          # run without building
 npm run build                # compile to dist/
+npm run test                 # run unit tests
 npm link                     # install as global 'sf' command
-sf list
 ```

package/dist/cache.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Simple in-memory TTL cache for dashboard data
+ */
+export declare function cached<T>(key: string, ttlMs: number, fn: () => Promise<T>): Promise<T>;
+export declare function invalidate(key: string): void;
+export declare function invalidateAll(): void;

package/dist/cache.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Simple in-memory TTL cache for dashboard data
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cached = cached;
+exports.invalidate = invalidate;
+exports.invalidateAll = invalidateAll;
+const store = new Map();
+async function cached(key, ttlMs, fn) {
+    const hit = store.get(key);
+    if (hit && Date.now() < hit.expiry)
+        return hit.data;
+    try {
+        const data = await fn();
+        store.set(key, { data, expiry: Date.now() + ttlMs });
+        return data;
+    }
+    catch (err) {
+        // On error, return stale data if available
+        if (hit)
+            return hit.data;
+        throw err;
+    }
+}
+function invalidate(key) {
+    store.delete(key);
+}
+function invalidateAll() {
+    store.clear();
+}

package/dist/cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cache.test.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const cache_js_1 = require("./cache.js");
+(0, vitest_1.beforeEach)(() => {
+    (0, cache_js_1.invalidateAll)();
+    vitest_1.vi.useRealTimers();
+});
+(0, vitest_1.describe)('cached', () => {
+    (0, vitest_1.it)('returns fresh data on cache miss', async () => {
+        const fn = vitest_1.vi.fn().mockResolvedValue('data');
+        const result = await (0, cache_js_1.cached)('key1', 1000, fn);
+        (0, vitest_1.expect)(result).toBe('data');
+        (0, vitest_1.expect)(fn).toHaveBeenCalledOnce();
+    });
+    (0, vitest_1.it)('returns cached data on hit without calling fn', async () => {
+        const fn = vitest_1.vi.fn().mockResolvedValue('data');
+        await (0, cache_js_1.cached)('key2', 5000, fn);
+        const result = await (0, cache_js_1.cached)('key2', 5000, fn);
+        (0, vitest_1.expect)(result).toBe('data');
+        (0, vitest_1.expect)(fn).toHaveBeenCalledOnce();
+    });
+    (0, vitest_1.it)('expires after TTL', async () => {
+        vitest_1.vi.useFakeTimers();
+        const fn = vitest_1.vi.fn()
+            .mockResolvedValueOnce('first')
+            .mockResolvedValueOnce('second');
+        await (0, cache_js_1.cached)('key3', 1000, fn);
+        vitest_1.vi.advanceTimersByTime(1500);
+        const result = await (0, cache_js_1.cached)('key3', 1000, fn);
+        (0, vitest_1.expect)(result).toBe('second');
+        (0, vitest_1.expect)(fn).toHaveBeenCalledTimes(2);
+    });
+    (0, vitest_1.it)('returns stale data on error when cache exists', async () => {
+        vitest_1.vi.useFakeTimers();
+        const fn = vitest_1.vi.fn()
+            .mockResolvedValueOnce('stale')
+            .mockRejectedValueOnce(new Error('fail'));
+        await (0, cache_js_1.cached)('key4', 1000, fn);
+        vitest_1.vi.advanceTimersByTime(1500);
+        const result = await (0, cache_js_1.cached)('key4', 1000, fn);
+        (0, vitest_1.expect)(result).toBe('stale');
+    });
+    (0, vitest_1.it)('throws on error when no stale data', async () => {
+        const fn = vitest_1.vi.fn().mockRejectedValue(new Error('fail'));
+        await (0, vitest_1.expect)((0, cache_js_1.cached)('key5', 1000, fn)).rejects.toThrow('fail');
+    });
+});
+(0, vitest_1.describe)('invalidate', () => {
+    (0, vitest_1.it)('clears a specific key', async () => {
+        const fn = vitest_1.vi.fn()
+            .mockResolvedValueOnce('first')
+            .mockResolvedValueOnce('second');
+        await (0, cache_js_1.cached)('key6', 60000, fn);
+        (0, cache_js_1.invalidate)('key6');
+        const result = await (0, cache_js_1.cached)('key6', 60000, fn);
+        (0, vitest_1.expect)(result).toBe('second');
+        (0, vitest_1.expect)(fn).toHaveBeenCalledTimes(2);
+    });
+});
+(0, vitest_1.describe)('invalidateAll', () => {
+    (0, vitest_1.it)('clears all keys', async () => {
+        const fn1 = vitest_1.vi.fn().mockResolvedValue('a');
+        const fn2 = vitest_1.vi.fn().mockResolvedValue('b');
+        await (0, cache_js_1.cached)('x', 60000, fn1);
+        await (0, cache_js_1.cached)('y', 60000, fn2);
+        (0, cache_js_1.invalidateAll)();
+        await (0, cache_js_1.cached)('x', 60000, fn1);
+        await (0, cache_js_1.cached)('y', 60000, fn2);
+        (0, vitest_1.expect)(fn1).toHaveBeenCalledTimes(2);
+        (0, vitest_1.expect)(fn2).toHaveBeenCalledTimes(2);
+    });
+});

package/dist/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client.test.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const client_js_1 = require("./client.js");
+const mockFetch = vitest_1.vi.fn();
+vitest_1.vi.stubGlobal('fetch', mockFetch);
+(0, vitest_1.beforeEach)(() => {
+    mockFetch.mockReset();
+    delete process.env.SF_API_KEY;
+    delete process.env.SF_API_URL;
+});
+(0, vitest_1.describe)('SFClient constructor', () => {
+    (0, vitest_1.it)('throws when no API key provided', () => {
+        (0, vitest_1.expect)(() => new client_js_1.SFClient()).toThrow('API key required');
+    });
+    (0, vitest_1.it)('accepts explicit API key', () => {
+        (0, vitest_1.expect)(() => new client_js_1.SFClient('sf_live_test')).not.toThrow();
+    });
+    (0, vitest_1.it)('reads from env', () => {
+        process.env.SF_API_KEY = 'sf_live_env';
+        (0, vitest_1.expect)(() => new client_js_1.SFClient()).not.toThrow();
+    });
+    (0, vitest_1.it)('strips trailing slash from base URL', () => {
+        const client = new client_js_1.SFClient('key', 'https://example.com/');
+        mockFetch.mockResolvedValue({ ok: true, json: () => Promise.resolve({ theses: [] }) });
+        client.listTheses();
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('https://example.com/api/thesis', vitest_1.expect.any(Object));
+    });
+});
+(0, vitest_1.describe)('SFClient requests', () => {
+    let client;
+    (0, vitest_1.beforeEach)(() => {
+        client = new client_js_1.SFClient('sf_live_testkey', 'https://api.test.com');
+    });
+    (0, vitest_1.it)('sends GET with correct headers', async () => {
+        mockFetch.mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ theses: [] }),
+        });
+        await client.listTheses();
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('https://api.test.com/api/thesis', vitest_1.expect.objectContaining({
+            method: 'GET',
+            headers: vitest_1.expect.objectContaining({
+                Authorization: 'Bearer sf_live_testkey',
+                'Content-Type': 'application/json',
+            }),
+        }));
+    });
+    (0, vitest_1.it)('sends POST with JSON body', async () => {
+        mockFetch.mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ id: '123' }),
+        });
+        await client.injectSignal('thesis1', 'news', 'breaking news');
+        const call = mockFetch.mock.calls[0];
+        (0, vitest_1.expect)(call[1].method).toBe('POST');
+        (0, vitest_1.expect)(JSON.parse(call[1].body)).toEqual({
+            type: 'news',
+            content: 'breaking news',
+            source: 'cli',
+        });
+    });
+    (0, vitest_1.it)('throws on non-ok response', async () => {
+        mockFetch.mockResolvedValue({
+            ok: false,
+            status: 404,
+            text: () => Promise.resolve('Not found'),
+        });
+        await (0, vitest_1.expect)(client.getThesis('bad-id')).rejects.toThrow('API error 404: Not found');
+    });
+    (0, vitest_1.it)('getContext calls correct path', async () => {
+        mockFetch.mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({}),
+        });
+        await client.getContext('abc123');
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('https://api.test.com/api/thesis/abc123/context', vitest_1.expect.any(Object));
+    });
+    (0, vitest_1.it)('evaluate sends POST', async () => {
+        mockFetch.mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ evaluation: {} }),
+        });
+        await client.evaluate('thesis1');
+        const call = mockFetch.mock.calls[0];
+        (0, vitest_1.expect)(call[1].method).toBe('POST');
+        (0, vitest_1.expect)(call[0]).toBe('https://api.test.com/api/thesis/thesis1/evaluate');
+    });
+});