opencandle 0.1.1 → 0.3.0

package/dist/sentiment/scorer.js

@@ -0,0 +1,64 @@
+import { BULLISH_TERMS, BEARISH_TERMS } from "./keywords.js";
+const TICKER_REGEX = /\$([A-Z]{1,5})\b/g;
+export function keywordScore(record) {
+    const lower = record.text.toLowerCase();
+    const engagement = 1 + (record.engagement.score ?? 0);
+    let bullishWeight = 0;
+    let bearishWeight = 0;
+    let bullishCount = 0;
+    let bearishCount = 0;
+    for (const term of BULLISH_TERMS) {
+        if (lower.includes(term)) {
+            bullishCount++;
+            bullishWeight += engagement;
+        }
+    }
+    for (const term of BEARISH_TERMS) {
+        if (lower.includes(term)) {
+            bearishCount++;
+            bearishWeight += engagement;
+        }
+    }
+    const totalWeight = bullishWeight + bearishWeight;
+    const score = totalWeight === 0 ? 0 : (bullishWeight - bearishWeight) / totalWeight;
+    const totalMatches = bullishCount + bearishCount;
+    let confidence = 0;
+    if (totalMatches > 0) {
+        // Base confidence from keyword matches
+        confidence = Math.min(totalMatches / 5, 1) * 0.6;
+        // Boost for longer text
+        const textLength = record.text.length;
+        confidence += Math.min(textLength / 500, 1) * 0.3;
+        // Multiple matches boost
+        if (totalMatches >= 3)
+            confidence += 0.1;
+        // Twitter penalty
+        if (record.source === "twitter")
+            confidence -= 0.1;
+        // Clamp
+        confidence = Math.max(0, Math.min(1, confidence));
+    }
+    // Extract tickers
+    const tickers = [];
+    for (const match of record.text.matchAll(TICKER_REGEX)) {
+        if (!tickers.includes(match[1])) {
+            tickers.push(match[1]);
+        }
+    }
+    return { score, confidence, tickers };
+}
+export function scoreRecords(records) {
+    return records.map((record) => {
+        const result = keywordScore(record);
+        return {
+            ...record,
+            sentiment: {
+                score: result.score,
+                confidence: result.confidence,
+                method: "keyword",
+                tickers: result.tickers,
+            },
+        };
+    });
+}
+//# sourceMappingURL=scorer.js.map

package/dist/sentiment/scorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.js","sourceRoot":"","sources":["../../src/sentiment/scorer.ts"],"names":[],"mappings":"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"}

package/dist/sentiment/store.d.ts

@@ -0,0 +1,24 @@
+import type { SentinelRecord, SentimentSource, TrendBucket } from "./types.js";
+export interface SearchOptions {
+    source?: SentimentSource;
+    since?: string;
+    until?: string;
+}
+export interface TimeSeriesOptions {
+    days: number;
+    bucketHours: number;
+}
+export declare class SentimentStore {
+    private db;
+    constructor(pathOrMemory: string);
+    private initSchema;
+    getSchemaVersion(): number;
+    insert(records: SentinelRecord[]): void;
+    search(query: string, options?: SearchOptions): SentinelRecord[];
+    getByTicker(ticker: string, options?: {
+        since?: string;
+    }): SentinelRecord[];
+    getTimeSeries(query: string, options: TimeSeriesOptions): TrendBucket[];
+    prune(retentionDays: number): number;
+    close(): void;
+}

package/dist/sentiment/store.js

@@ -0,0 +1,177 @@
+import Database from "better-sqlite3";
+const SCHEMA_VERSION = 1;
+const CREATE_SCHEMA = `
+  CREATE TABLE IF NOT EXISTS schema_version (
+    version INTEGER NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS sentinel_records (
+    id TEXT NOT NULL,
+    source TEXT NOT NULL,
+    source_id TEXT NOT NULL,
+    query TEXT NOT NULL,
+    title TEXT,
+    text TEXT NOT NULL,
+    author TEXT,
+    url TEXT NOT NULL,
+    published_at TEXT,
+    fetched_at TEXT NOT NULL,
+    engagement_json TEXT NOT NULL,
+    sentiment_score REAL NOT NULL,
+    sentiment_confidence REAL NOT NULL,
+    sentiment_method TEXT NOT NULL,
+    tickers_json TEXT NOT NULL,
+    metadata_json TEXT NOT NULL,
+    UNIQUE(source, source_id, fetched_at)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_sentinel_source ON sentinel_records(source);
+  CREATE INDEX IF NOT EXISTS idx_sentinel_fetched_at ON sentinel_records(fetched_at);
+  CREATE INDEX IF NOT EXISTS idx_sentinel_query ON sentinel_records(query);
+
+  CREATE VIRTUAL TABLE IF NOT EXISTS sentinel_fts USING fts5(
+    text, title, author, query, source,
+    content=sentinel_records,
+    content_rowid=rowid
+  );
+`;
+const TRIGGERS = `
+  CREATE TRIGGER IF NOT EXISTS sentinel_ai AFTER INSERT ON sentinel_records BEGIN
+    INSERT INTO sentinel_fts(rowid, text, title, author, query, source)
+    VALUES (new.rowid, new.text, new.title, new.author, new.query, new.source);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS sentinel_ad AFTER DELETE ON sentinel_records BEGIN
+    INSERT INTO sentinel_fts(sentinel_fts, rowid, text, title, author, query, source)
+    VALUES ('delete', old.rowid, old.text, old.title, old.author, old.query, old.source);
+  END;
+`;
+export class SentimentStore {
+    db;
+    constructor(pathOrMemory) {
+        this.db = new Database(pathOrMemory);
+        if (pathOrMemory !== ":memory:") {
+            this.db.pragma("journal_mode = WAL");
+        }
+        this.initSchema();
+    }
+    initSchema() {
+        this.db.exec(CREATE_SCHEMA);
+        this.db.exec(TRIGGERS);
+        const row = this.db.prepare("SELECT version FROM schema_version").get();
+        if (!row) {
+            this.db.prepare("INSERT INTO schema_version (version) VALUES (?)").run(SCHEMA_VERSION);
+        }
+    }
+    getSchemaVersion() {
+        const row = this.db.prepare("SELECT version FROM schema_version").get();
+        return row.version;
+    }
+    insert(records) {
+        const stmt = this.db.prepare(`
+      INSERT OR IGNORE INTO sentinel_records
+        (id, source, source_id, query, title, text, author, url,
+         published_at, fetched_at, engagement_json,
+         sentiment_score, sentiment_confidence, sentiment_method,
+         tickers_json, metadata_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const tx = this.db.transaction((recs) => {
+            for (const r of recs) {
+                stmt.run(r.id, r.source, r.sourceId, r.query, r.title, r.text, r.author, r.url, r.publishedAt, r.fetchedAt, JSON.stringify(r.engagement), r.sentiment.score, r.sentiment.confidence, r.sentiment.method, JSON.stringify(r.sentiment.tickers), JSON.stringify(r.metadata));
+            }
+        });
+        tx(records);
+    }
+    search(query, options) {
+        let sql = `
+      SELECT sr.* FROM sentinel_records sr
+      JOIN sentinel_fts fts ON sr.rowid = fts.rowid
+      WHERE sentinel_fts MATCH ?
+    `;
+        const params = [query];
+        if (options?.source) {
+            sql += " AND sr.source = ?";
+            params.push(options.source);
+        }
+        if (options?.since) {
+            sql += " AND sr.fetched_at >= ?";
+            params.push(options.since);
+        }
+        if (options?.until) {
+            sql += " AND sr.fetched_at <= ?";
+            params.push(options.until);
+        }
+        sql += " ORDER BY bm25(sentinel_fts) LIMIT 100";
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(rowToRecord);
+    }
+    getByTicker(ticker, options) {
+        let sql = `SELECT * FROM sentinel_records WHERE tickers_json LIKE ?`;
+        const pattern = `%"${ticker}"%`;
+        const params = [pattern];
+        if (options?.since) {
+            sql += " AND fetched_at >= ?";
+            params.push(options.since);
+        }
+        sql += " ORDER BY fetched_at DESC LIMIT 100";
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(rowToRecord);
+    }
+    getTimeSeries(query, options) {
+        const since = new Date();
+        since.setDate(since.getDate() - options.days);
+        const sinceStr = since.toISOString();
+        const bucketSeconds = options.bucketHours * 3600;
+        const sql = `
+      SELECT
+        (CAST(strftime('%s', fetched_at) AS INTEGER) / ?) * ? AS bucket_ts,
+        AVG(sentiment_score) AS avg_score,
+        COUNT(*) AS cnt
+      FROM sentinel_records
+      WHERE query = ? AND fetched_at >= ?
+      GROUP BY bucket_ts
+      ORDER BY bucket_ts
+    `;
+        const rows = this.db.prepare(sql).all(bucketSeconds, bucketSeconds, query, sinceStr);
+        return rows.map((r) => ({
+            timestamp: new Date(r.bucket_ts * 1000).toISOString(),
+            avgScore: r.avg_score,
+            count: r.cnt,
+        }));
+    }
+    prune(retentionDays) {
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - retentionDays);
+        const result = this.db
+            .prepare("DELETE FROM sentinel_records WHERE fetched_at < ?")
+            .run(cutoff.toISOString());
+        return result.changes;
+    }
+    close() {
+        this.db.close();
+    }
+}
+function rowToRecord(row) {
+    return {
+        id: row.id,
+        source: row.source,
+        sourceId: row.source_id,
+        query: row.query,
+        title: row.title,
+        text: row.text,
+        author: row.author,
+        url: row.url,
+        publishedAt: row.published_at,
+        fetchedAt: row.fetched_at,
+        engagement: JSON.parse(row.engagement_json),
+        sentiment: {
+            score: row.sentiment_score,
+            confidence: row.sentiment_confidence,
+            method: row.sentiment_method,
+            tickers: JSON.parse(row.tickers_json),
+        },
+        metadata: JSON.parse(row.metadata_json),
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/sentiment/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/sentiment/store.ts"],"names":[],"mappings":"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"}

package/dist/sentiment/trends.d.ts

@@ -0,0 +1,13 @@
+import type { TrendBucket, TrendResult, DivergenceResult, SentimentSource } from "./types.js";
+export declare function renderSparkline(values: number[]): string;
+export declare function computeTrend(buckets: TrendBucket[], source: SentimentSource | "aggregate"): TrendResult;
+export interface SourceStats {
+    avg: number;
+    count: number;
+}
+export declare function computeDivergence(sources: {
+    twitter?: SourceStats;
+    reddit?: SourceStats;
+    web?: SourceStats;
+    finnhub?: SourceStats;
+}, threshold: number): DivergenceResult;

package/dist/sentiment/trends.js

@@ -0,0 +1,73 @@
+const SPARKLINE_CHARS = "▁▂▃▄▅▆▇█";
+export function renderSparkline(values) {
+    if (values.length === 0)
+        return "";
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const range = max - min;
+    return values
+        .map((v) => {
+        if (range === 0)
+            return SPARKLINE_CHARS[3]; // middle block for flat
+        const idx = Math.round(((v - min) / range) * 7);
+        return SPARKLINE_CHARS[idx];
+    })
+        .join("");
+}
+export function computeTrend(buckets, source) {
+    const scores = buckets.map((b) => b.avgScore);
+    const totalCount = buckets.reduce((sum, b) => sum + b.count, 0);
+    const avgScore = totalCount === 0 ? 0 : buckets.reduce((sum, b) => sum + b.avgScore * b.count, 0) / totalCount;
+    const sparkline = renderSparkline(scores);
+    // Delta: last value minus first value
+    const delta = scores.length >= 2 ? scores[scores.length - 1] - scores[0] : 0;
+    let direction;
+    if (delta > 0.1)
+        direction = "rising";
+    else if (delta < -0.1)
+        direction = "falling";
+    else
+        direction = "stable";
+    return { source, sparkline, avgScore, count: totalCount, direction, delta };
+}
+export function computeDivergence(sources, threshold) {
+    const retailSources = [];
+    if (sources.twitter && sources.twitter.count >= 5)
+        retailSources.push(sources.twitter);
+    if (sources.reddit && sources.reddit.count >= 5)
+        retailSources.push(sources.reddit);
+    const newsSources = [];
+    if (sources.web && sources.web.count >= 5)
+        newsSources.push(sources.web);
+    if (sources.finnhub && sources.finnhub.count >= 5)
+        newsSources.push(sources.finnhub);
+    if (retailSources.length === 0 || newsSources.length === 0) {
+        return {
+            detected: false,
+            retailAvg: null,
+            newsAvg: null,
+            gap: null,
+            message: "Insufficient data for divergence analysis",
+        };
+    }
+    const retailAvg = retailSources.reduce((sum, s) => sum + s.avg, 0) / retailSources.length;
+    const newsAvg = newsSources.reduce((sum, s) => sum + s.avg, 0) / newsSources.length;
+    const gap = Math.abs(retailAvg - newsAvg);
+    if (gap > threshold) {
+        return {
+            detected: true,
+            retailAvg,
+            newsAvg,
+            gap,
+            message: `⚠ DIVERGENCE: Retail sentiment (${retailAvg >= 0 ? "+" : ""}${retailAvg.toFixed(2)}) vs news sentiment (${newsAvg >= 0 ? "+" : ""}${newsAvg.toFixed(2)}) — gap of ${gap.toFixed(2)}.`,
+        };
+    }
+    return {
+        detected: false,
+        retailAvg,
+        newsAvg,
+        gap,
+        message: "Sources broadly aligned",
+    };
+}
+//# sourceMappingURL=trends.js.map

package/dist/sentiment/trends.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trends.js","sourceRoot":"","sources":["../../src/sentiment/trends.ts"],"names":[],"mappings":"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"}

package/dist/sentiment/types.d.ts

@@ -0,0 +1,66 @@
+export declare const SENTIMENT_SOURCES: readonly ["twitter", "reddit", "web", "finnhub"];
+export type SentimentSource = (typeof SENTIMENT_SOURCES)[number];
+export interface SentinelEngagement {
+    score: number;
+    replies: number | null;
+    shares: number | null;
+    views: number | null;
+}
+export interface SentinelSentiment {
+    score: number;
+    confidence: number;
+    method: "keyword";
+    tickers: string[];
+}
+export interface SentinelRecord {
+    id: string;
+    source: SentimentSource;
+    sourceId: string;
+    query: string;
+    title: string | null;
+    text: string;
+    author: string | null;
+    url: string;
+    publishedAt: string | null;
+    fetchedAt: string;
+    engagement: SentinelEngagement;
+    sentiment: SentinelSentiment;
+    metadata: Record<string, unknown>;
+}
+export declare function isSentinelRecord(val: unknown): val is SentinelRecord;
+export interface SentimentAdapter {
+    source: SentimentSource;
+    fetch(query: string, options?: {
+        hours?: number;
+    }): Promise<SentinelRecord[]>;
+}
+export interface ScorerOptions {
+    /** Minimum confidence for a keyword score to be considered "high confidence" */
+    confidenceThreshold?: number;
+}
+export interface TrendBucket {
+    timestamp: string;
+    avgScore: number;
+    count: number;
+}
+export interface TrendResult {
+    source: SentimentSource | "aggregate";
+    sparkline: string;
+    avgScore: number;
+    count: number;
+    direction: "rising" | "falling" | "stable";
+    delta: number;
+}
+export interface DivergenceResult {
+    detected: boolean;
+    retailAvg: number | null;
+    newsAvg: number | null;
+    gap: number | null;
+    message: string;
+}
+export interface SentimentSummary {
+    fresh: SentinelRecord[];
+    trend: TrendResult[] | null;
+    divergence: DivergenceResult | null;
+    warnings: string[];
+}

package/dist/sentiment/types.js

@@ -0,0 +1,54 @@
+export const SENTIMENT_SOURCES = ["twitter", "reddit", "web", "finnhub"];
+export function isSentinelRecord(val) {
+    if (val === null || typeof val !== "object")
+        return false;
+    const r = val;
+    if (typeof r.id !== "string")
+        return false;
+    if (typeof r.source !== "string" || !SENTIMENT_SOURCES.includes(r.source))
+        return false;
+    if (typeof r.sourceId !== "string")
+        return false;
+    if (typeof r.query !== "string")
+        return false;
+    if (r.title !== null && typeof r.title !== "string")
+        return false;
+    if (typeof r.text !== "string")
+        return false;
+    if (r.author !== null && typeof r.author !== "string")
+        return false;
+    if (typeof r.url !== "string")
+        return false;
+    if (r.publishedAt !== null && typeof r.publishedAt !== "string")
+        return false;
+    if (typeof r.fetchedAt !== "string")
+        return false;
+    const eng = r.engagement;
+    if (eng === null || typeof eng !== "object")
+        return false;
+    const e = eng;
+    if (typeof e.score !== "number")
+        return false;
+    if (e.replies !== null && typeof e.replies !== "number")
+        return false;
+    if (e.shares !== null && typeof e.shares !== "number")
+        return false;
+    if (e.views !== null && typeof e.views !== "number")
+        return false;
+    const sent = r.sentiment;
+    if (sent === null || typeof sent !== "object")
+        return false;
+    const s = sent;
+    if (typeof s.score !== "number" || s.score < -1 || s.score > 1)
+        return false;
+    if (typeof s.confidence !== "number" || s.confidence < 0 || s.confidence > 1)
+        return false;
+    if (s.method !== "keyword")
+        return false;
+    if (!Array.isArray(s.tickers))
+        return false;
+    if (r.metadata === null || typeof r.metadata !== "object")
+        return false;
+    return true;
+}
+//# sourceMappingURL=types.js.map

package/dist/sentiment/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sentiment/types.ts"],"names":[],"mappings":"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"}

package/dist/system-prompt.js

@@ -16,9 +16,10 @@ You provide data-driven analysis for stocks, crypto, macro economics, and portfo
 - **Fundamentals**: get_company_overview, get_financials, get_earnings, compute_dcf, compare_companies, get_sec_filings — company financials, valuation metrics, DCF intrinsic value, peer comparison, and SEC EDGAR filings (10-K, 10-Q, 8-K)
 - **Technical Analysis**: get_technical_indicators, backtest_strategy — SMA, EMA, RSI, MACD, Bollinger Bands, OBV, VWAP computed from price data, plus simple strategy backtesting
 - **Macro**: get_economic_data, get_fear_greed — FRED economic indicators and market sentiment
-- **Sentiment**: get_reddit_sentiment, get_reddit_discussions — retail sentiment from financial Reddit communities
+- **Sentiment**: get_reddit_sentiment, get_twitter_sentiment, get_web_sentiment, get_sentiment_trend, get_sentiment_summary — retail and news sentiment from Reddit, Twitter/X, and web sources with historical trends
 - **Options**: get_option_chain — full options chain with strikes, bids/asks, volume, OI, IV, and computed Greeks (delta, gamma, theta, vega, rho)
 - **Portfolio**: track_portfolio, analyze_risk, manage_watchlist, analyze_correlation, track_prediction — position tracking, P&L, Sharpe ratio, VaR, watchlist with price alerts, correlation matrix, and prediction tracking with accuracy scoring
+- **User Interaction**: ask_user — ask clarification questions; trigger_twitter_login — open a browser for Twitter/X login
 
 ## Analytical Framework
 When analyzing a stock, follow these steps in order:
@@ -29,7 +30,7 @@ When analyzing a stock, follow these steps in order:
 5. **SYNTHESIS**: State your reasoning chain explicitly: "Because [data point] + [data point], I conclude [thesis]."
 
 ## Guidelines
-- Always fetch data with tools before stating prices, ratios, or metrics. Never guess financial numbers.
+- Always fetch data with tools before stating prices, ratios, or metrics. Never guess financial numbers. Every substantive response should be backed by at least one tool call — if you find yourself writing a response with zero tool calls, stop and think about what data would make it better.
 - For options analysis, use get_option_chain to see the full chain with Greeks. Pay attention to put/call ratio, unusual volume, and IV levels.
 - Present numerical data in tables when comparing multiple securities.
 - Include data timestamps so users know how fresh the information is.
@@ -39,6 +40,63 @@ When analyzing a stock, follow these steps in order:
 - Reuse prior tool outputs when they already answer the question. Do not re-fetch the same symbol and parameters unless you need a missing field or fresher timestamp.
 - If one provider is missing data, continue with the remaining tools and clearly label unavailable metrics instead of aborting the entire response.
 
+## Handling skipped data sources
+Tool results may include a tagged line beginning with \`[OPENCANDLE_SKIPPED ...]\`, \`[OPENCANDLE_CREDENTIAL_REQUIRED ...]\`, or \`[OPENCANDLE_SOFT_DEGRADED ...]\`. These signal that a data source was either skipped at the user's request, not configured, or fell back to a keyless alternative (e.g. Brave → DuckDuckGo, Exa → keyless MCP). When you see one or more of these in your tool results:
+1. Continue the analysis using whatever other data you have. Do NOT apologize, do NOT treat it as an error, do NOT suggest the user fix something they already declined.
+2. At the end of your final answer, add a \`**Data gaps**\` section listing each affected provider as one bullet, quoting the \`remediation\` string verbatim (e.g. \`run /connect financials to unlock\`). Aggregate \`[OPENCANDLE_SKIPPED ...]\` and \`[OPENCANDLE_SOFT_DEGRADED ...]\` tags together — both are "you didn't get the keyed source" signals from the user's perspective.
+3. For \`[OPENCANDLE_SOFT_DEGRADED ...]\` tags, briefly name the fallback that was used so the user understands where the data actually came from (e.g. "Web search used DuckDuckGo instead of Brave").
+4. EXCEPTION: if the \`remediation\` string contains the literal text \`(silenced)\`, the user has explicitly asked not to be pestered about this provider. Still describe the omission but OMIT the \`/connect\` remediation text for that bullet. Something like "Finnhub news was omitted (silenced)" is enough.
+5. A \`[OPENCANDLE_CONNECTED ...]\` tag means a credential was JUST saved mid-turn. Acknowledge it briefly ("Alpha Vantage just connected") and tell the user to re-run the previous request to fetch the data. Pi does not currently support re-dispatching the original tool call automatically.
+
+## When to Ask for Clarification
+Use the ask_user tool BEFORE proceeding when:
+- The request is broad or vague (e.g., "analyze the market" without specifying which asset or sector)
+- Required information is missing: a ticker symbol for asset analysis, a budget for portfolio construction, or a time horizon for recommendations
+- Multiple valid analysis approaches exist and the user has not indicated a preference (e.g., fundamental vs. technical, short-term vs. long-term)
+- Risk tolerance is unclear for portfolio or options recommendations
+
+Do NOT ask clarifying questions when:
+- The request is clear and specific (e.g., "get AAPL quote", "analyze BTC")
+- You can reasonably infer the intent from context or prior conversation
+- A reasonable default exists and can be disclosed in the Assumptions block instead
+- The user explicitly asks you to use your judgment
+
+Keep questions concise and offer specific options when possible. Prefer select-type questions over open-ended text input to minimize user effort.
+
+## Twitter Authentication
+get_twitter_sentiment requires a one-time Twitter/X login. When the tool returns [LOGIN_NEEDED]:
+1. Use ask_user (confirm) to ask: "Twitter sentiment requires a one-time login. A browser will open — want to proceed?"
+2. If confirmed, call trigger_twitter_login. It opens a browser, waits for the user to log in, and returns success/failure.
+3. On success, retry get_twitter_sentiment with the original query.
+If the user declines, skip Twitter sentiment and continue with other available data sources.
+
+## After Clarification: Fetch Data Immediately
+CRITICAL: After ask_user answers come back, your NEXT action MUST be tool calls — not a text response. You are a data agent, not a chatbot. Never respond with generic investment categories or tell the user to come back with tickers. YOU pick the relevant assets and indicators based on what you learned, then fetch the data.
+
+Playbooks by scenario (use these as starting points, adapt as needed):
+
+**"Where should I put $X" / general investment advice:**
+1. Fetch get_fear_greed — is the market fearful or greedy right now?
+2. Fetch get_economic_data for key macro indicators (Fed funds rate, CPI, unemployment)
+3. Fetch get_stock_quote for benchmark ETFs relevant to their goal (e.g., SPY, QQQ, VTI for growth; BND, SCHD for income; GLD, BTC for alternatives)
+4. Fetch get_technical_indicators on those ETFs to assess current momentum and overbought/oversold conditions
+5. Synthesize: "Given current market conditions [data], here's how I'd think about allocating $X across [specific assets] and why"
+
+**"Build me a portfolio" / allocation request:**
+1. Pick 5-8 candidate assets matching their stated goal and risk level
+2. Fetch get_stock_quote and get_company_overview for each
+3. Fetch analyze_correlation to check diversification
+4. Present a concrete allocation with percentages, backed by the data you fetched
+
+**"What's happening in the market" / market outlook:**
+1. Fetch get_stock_quote for SPY, QQQ, IWM, DIA (major indices)
+2. Fetch get_fear_greed
+3. Fetch get_economic_data for 2-3 key FRED series
+4. Fetch get_reddit_sentiment for current retail mood
+5. Synthesize a market snapshot with data points
+
+If you are about to write a response that contains zero tool call results, STOP. Go fetch data first.
+
 ## Assumption Disclosure
 Workflow prompts include a pre-rendered "Assumptions" block with correct source attribution (user-specified, saved preference, or default). Start your response with that block exactly as written. Do NOT independently relabel any value's source anywhere in your response. The assumptions block is the single authoritative provenance representation.
 ${memorySection}

package/dist/system-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../src/system-prompt.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,iBAAiB,CAAC,aAAsB;IACtD,MAAM,aAAa,GAAG,aAAa;QACjC,CAAC,CAAC;;;;EAIJ,aAAa,EAAE;QACb,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCP,aAAa;;;mNAGoM,CAAC;AACpN,CAAC"}
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../src/system-prompt.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,iBAAiB,CAAC,aAAsB;IACtD,MAAM,aAAa,GAAG,aAAa;QACjC,CAAC,CAAC;;;;EAIJ,aAAa,EAAE;QACb,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6FP,aAAa;;;mNAGoM,CAAC;AACpN,CAAC"}

package/dist/tool-kit.d.ts

@@ -8,12 +8,16 @@ export { agentToolToPiTool } from "./pi/tool-adapter.js";
 export { Type } from "@sinclair/typebox";
 export type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 export type { AgentTool } from "@mariozechner/pi-agent-core";
-export declare function getThirdPartyToolDescriptions(): ReadonlyArray<{
+export declare function getAddonToolDescriptions(): ReadonlyArray<{
     name: string;
     description: string;
 }>;
-export interface RegisterToolsOptions {
-    namespace?: string;
-    description?: string;
+export interface ToolConfig<TParams extends TSchema, TDetails = unknown> {
+    name: string;
+    label: string;
+    description: string;
+    parameters: TParams;
+    execute: AgentTool<TParams, TDetails>["execute"];
 }
-export declare function registerOpenCandleTools<TParams extends TSchema>(pi: ExtensionAPI, tools: AgentTool<TParams>[], options?: RegisterToolsOptions): void;
+export declare function createTool<TParams extends TSchema, TDetails = unknown>(config: ToolConfig<TParams, TDetails>): AgentTool<TParams, TDetails>;
+export declare function registerTools<TParams extends TSchema>(pi: ExtensionAPI, tools: AgentTool<TParams>[]): void;