opencandle 0.11.1 → 0.12.0

package/src/sentiment/adapters/finnhub.ts

@@ -1,49 +0,0 @@
-import { randomUUID } from "node:crypto";
-import type { FinnhubArticle } from "../../providers/finnhub.js";
-import { extractEntities } from "../../routing/entity-extractor.js";
-import type { SentinelRecord } from "../types.js";
-
-const MAX_TICKERS = 3;
-
-export class FinnhubAdapter {
-  readonly source = "finnhub" as const;
-
-  mapToRecords(articles: FinnhubArticle[], query: string): SentinelRecord[] {
-    const fetchedAt = new Date().toISOString();
-    return articles.map((article) => ({
-      id: randomUUID(),
-      source: this.source,
-      sourceId: String(article.id),
-      query,
-      title: article.headline,
-      text: article.summary,
-      author: article.source,
-      url: article.url,
-      publishedAt: new Date(article.datetime * 1000).toISOString(),
-      fetchedAt,
-      engagement: {
-        score: 0,
-        replies: null,
-        shares: null,
-        views: null,
-      },
-      sentiment: {
-        score: 0,
-        confidence: 0,
-        method: "keyword" as const,
-        tickers: article.related
-          ? article.related
-              .split(",")
-              .map((t) => t.trim())
-              .filter(Boolean)
-          : [],
-      },
-      metadata: { category: article.category },
-    }));
-  }
-}
-
-export function extractTickersFromQuery(query: string): string[] {
-  const entities = extractEntities(query);
-  return entities.symbols.slice(0, MAX_TICKERS);
-}

package/src/sentiment/adapters/reddit.ts

@@ -1,65 +0,0 @@
-import { randomUUID } from "node:crypto";
-import type { RedditComment } from "../../providers/reddit.js";
-import type { RedditSentimentResult } from "../../types/sentiment.js";
-import type { SentimentAdapter, SentinelRecord } from "../types.js";
-
-export class RedditAdapter implements SentimentAdapter {
-  readonly source = "reddit" as const;
-
-  mapPostsToRecords(result: RedditSentimentResult, query: string): SentinelRecord[] {
-    const fetchedAt = result.fetchedAt;
-    return result.posts.map((post) => ({
-      id: randomUUID(),
-      source: this.source,
-      sourceId: post.id,
-      query,
-      title: post.title,
-      text: post.selftext ? `${post.title}\n${post.selftext}` : post.title,
-      author: post.author,
-      url: post.url,
-      publishedAt: post.created,
-      fetchedAt,
-      engagement: {
-        score: post.score,
-        replies: post.comments,
-        shares: null,
-        views: null,
-      },
-      sentiment: { score: 0, confidence: 0, method: "keyword" as const, tickers: [] },
-      metadata: { subreddit: result.subreddit },
-    }));
-  }
-
-  mapCommentsToRecords(
-    comments: RedditComment[],
-    parentId: string,
-    subreddit: string,
-    query: string,
-  ): SentinelRecord[] {
-    const fetchedAt = new Date().toISOString();
-    return comments.map((comment) => ({
-      id: randomUUID(),
-      source: this.source,
-      sourceId: comment.id,
-      query,
-      title: null,
-      text: comment.body,
-      author: comment.author,
-      url: comment.permalink,
-      publishedAt: null,
-      fetchedAt,
-      engagement: {
-        score: comment.score,
-        replies: null,
-        shares: null,
-        views: null,
-      },
-      sentiment: { score: 0, confidence: 0, method: "keyword" as const, tickers: [] },
-      metadata: { isComment: true, parentId, subreddit },
-    }));
-  }
-
-  async fetch(_query: string, _options?: { hours?: number }): Promise<SentinelRecord[]> {
-    throw new Error("Use pipeline.run() instead of adapter.fetch() directly");
-  }
-}

package/src/sentiment/adapters/twitter.ts

@@ -1,36 +0,0 @@
-import { randomUUID } from "node:crypto";
-import type { TwitterSentimentResult } from "../../types/sentiment.js";
-import type { SentimentAdapter, SentinelRecord } from "../types.js";
-
-export class TwitterAdapter implements SentimentAdapter {
-  readonly source = "twitter" as const;
-
-  mapToRecords(result: TwitterSentimentResult, query: string): SentinelRecord[] {
-    const fetchedAt = result.fetchedAt;
-    return result.tweets.map((tweet) => ({
-      id: randomUUID(),
-      source: this.source,
-      sourceId: tweet.id,
-      query,
-      title: null,
-      text: tweet.text,
-      author: tweet.author,
-      url: tweet.url,
-      publishedAt: tweet.created,
-      fetchedAt,
-      engagement: {
-        score: tweet.likes,
-        replies: tweet.replies,
-        shares: tweet.retweets,
-        views: tweet.views,
-      },
-      sentiment: { score: 0, confidence: 0, method: "keyword" as const, tickers: [] },
-      metadata: {},
-    }));
-  }
-
-  async fetch(_query: string, _options?: { hours?: number }): Promise<SentinelRecord[]> {
-    // Actual fetching is done by the pipeline via the provider
-    throw new Error("Use pipeline.run() instead of adapter.fetch() directly");
-  }
-}

package/src/sentiment/adapters/web.ts

@@ -1,44 +0,0 @@
-import { randomUUID } from "node:crypto";
-import type { WebSearchEnvelope } from "../../types/sentiment.js";
-import type { SentimentAdapter, SentinelRecord } from "../types.js";
-
-export class WebAdapter implements SentimentAdapter {
-  readonly source = "web" as const;
-
-  mapToRecords(envelope: WebSearchEnvelope, query: string): SentinelRecord[] {
-    const fetchedAt = envelope.fetchedAt;
-    return envelope.results.map((result) => ({
-      id: randomUUID(),
-      source: this.source,
-      sourceId: canonicalizeUrl(result.url),
-      query,
-      title: result.title,
-      text: result.snippet,
-      author: result.source,
-      url: result.url,
-      publishedAt: result.published,
-      fetchedAt,
-      engagement: {
-        score: 0,
-        replies: null,
-        shares: null,
-        views: null,
-      },
-      sentiment: { score: 0, confidence: 0, method: "keyword" as const, tickers: [] },
-      metadata: { category: result.category, provider: envelope.provider },
-    }));
-  }
-
-  async fetch(_query: string, _options?: { hours?: number }): Promise<SentinelRecord[]> {
-    throw new Error("Use pipeline.run() instead of adapter.fetch() directly");
-  }
-}
-
-function canonicalizeUrl(url: string): string {
-  try {
-    const parsed = new URL(url);
-    return parsed.origin + parsed.pathname;
-  } catch {
-    return url;
-  }
-}

package/src/sentiment/index.ts

@@ -1,49 +0,0 @@
-export { RedditAdapter } from "./adapters/reddit.js";
-export { TwitterAdapter } from "./adapters/twitter.js";
-export { WebAdapter } from "./adapters/web.js";
-export { buildSentimentInsight, labelForScore } from "./insights.js";
-export { BEARISH_TERMS, BULLISH_TERMS } from "./keywords.js";
-export { SentimentPipeline } from "./pipeline.js";
-export { keywordScore, scoreRecords } from "./scorer.js";
-export { SentimentStore } from "./store.js";
-export { computeDivergence, computeTrend, renderSparkline } from "./trends.js";
-export type {
-  DivergenceResult,
-  ScorerOptions,
-  SentimentAdapter,
-  SentimentSource,
-  SentimentSummary,
-  SentinelEngagement,
-  SentinelRecord,
-  SentinelSentiment,
-  TrendBucket,
-  TrendResult,
-} from "./types.js";
-export { isSentinelRecord, SENTIMENT_SOURCES } from "./types.js";
-
-import { getConfig } from "../config.js";
-import { resolveOpenCandlePath } from "../infra/opencandle-paths.js";
-import { SentimentPipeline } from "./pipeline.js";
-import { SentimentStore } from "./store.js";
-
-let _pipeline: SentimentPipeline | null = null;
-let _store: SentimentStore | null = null;
-
-export function getSentimentStore(): SentimentStore {
-  if (!_store) {
-    const dbPath = resolveOpenCandlePath("sentinel.db");
-    _store = new SentimentStore(dbPath);
-    const config = getConfig();
-    _store.prune(config.sentiment?.retentionDays ?? 30);
-  }
-  return _store;
-}
-
-export function getSentimentPipeline(): SentimentPipeline {
-  if (!_pipeline) {
-    const store = getSentimentStore();
-    const config = getConfig();
-    _pipeline = new SentimentPipeline(store, config.sentiment!);
-  }
-  return _pipeline;
-}

package/src/sentiment/insights.ts

@@ -1,269 +0,0 @@
-import type { SentimentConfig } from "../config.js";
-import type {
-  SentimentInsight,
-  SentimentInsightConfidence,
-  SentimentInsightDriver,
-  SentimentRepresentativeItem,
-} from "../types/sentiment.js";
-import type { SentimentSource, SentinelRecord } from "./types.js";
-
-const DEFAULT_MIN_SAMPLE = 10;
-const DEFAULT_DRIVER_CAP = 3;
-const DEFAULT_SOURCE_ITEM_CAP = 5;
-const DEFAULT_AGGREGATE_ITEM_CAP = 8;
-const DEFAULT_CLAIM_CAP = 5;
-
-export interface BuildSentimentInsightOptions {
-  query: string;
-  records: SentinelRecord[];
-  score?: number;
-  label?: string;
-  source?: SentimentSource | "aggregate";
-  missingSources?: string[];
-  sourceNotes?: string[];
-  config?: Partial<SentimentConfig>;
-  aggregate?: boolean;
-  extraCaveats?: string[];
-}
-
-interface TermBucket {
-  term: string;
-  count: number;
-  sourceIds: Set<string>;
-}
-
-export function buildSentimentInsight(options: BuildSentimentInsightOptions): SentimentInsight {
-  const records = options.records;
-  const scored = records.filter((record) => Math.abs(record.sentiment.score) > 0);
-  const score =
-    typeof options.score === "number"
-      ? options.score
-      : records.length > 0
-        ? records.reduce((sum, record) => sum + record.sentiment.score, 0) / records.length
-        : 0;
-  const sourceCounts = countBySource(records);
-  const positiveDrivers = driversFromTerms(records, "positive", options.config);
-  const negativeDrivers = driversFromTerms(records, "negative", options.config);
-  const caveats = buildCaveats(records, scored, sourceCounts, options);
-  const confidence = buildConfidence(records, scored, sourceCounts, caveats, options.config);
-  const representativeItems = representativeItemsFor(records, options);
-
-  return {
-    label: options.label ?? labelForScore(score),
-    score,
-    sampleSize: records.length,
-    scoredSampleSize: scored.length,
-    confidence,
-    positiveDrivers,
-    negativeDrivers,
-    mixedDrivers: buildMixedDrivers(positiveDrivers, negativeDrivers, score),
-    notableClaims: notableClaimsFor(records, options),
-    representativeItems,
-    sourceCoverage: {
-      sources: Object.keys(sourceCounts),
-      counts: sourceCounts,
-      missingSources: options.missingSources?.filter(Boolean),
-      notes: options.sourceNotes?.filter(Boolean),
-    },
-    caveats,
-    method: "deterministic-keyword-v1",
-  };
-}
-
-export function labelForScore(score: number): string {
-  if (score > 0.3) return "Bullish";
-  if (score < -0.3) return "Bearish";
-  if (score > 0) return "Leaning Bullish";
-  if (score < 0) return "Leaning Bearish";
-  return "Neutral";
-}
-
-function driversFromTerms(
-  records: SentinelRecord[],
-  polarity: "positive" | "negative",
-  config: Partial<SentimentConfig> | undefined,
-): SentimentInsightDriver[] {
-  const buckets = new Map<string, TermBucket>();
-  const metadataKey = polarity === "positive" ? "matchedBullishTerms" : "matchedBearishTerms";
-
-  for (const record of records) {
-    const terms = stringArray(record.metadata[metadataKey]);
-    for (const term of terms) {
-      const existing = buckets.get(term) ?? { term, count: 0, sourceIds: new Set<string>() };
-      existing.count += 1;
-      existing.sourceIds.add(record.sourceId);
-      buckets.set(term, existing);
-    }
-  }
-
-  return [...buckets.values()]
-    .sort((a, b) => b.count - a.count || a.term.localeCompare(b.term))
-    .slice(0, config?.maxInsightDriversPerPolarity ?? DEFAULT_DRIVER_CAP)
-    .map((bucket) => ({
-      label: bucket.term,
-      count: bucket.count,
-      polarity,
-      terms: [bucket.term],
-      sourceIds: [...bucket.sourceIds],
-    }));
-}
-
-function buildMixedDrivers(
-  positiveDrivers: SentimentInsightDriver[],
-  negativeDrivers: SentimentInsightDriver[],
-  score: number,
-): SentimentInsightDriver[] {
-  if (positiveDrivers.length === 0 || negativeDrivers.length === 0) return [];
-  if (Math.abs(score) > 0.3) return [];
-  return [
-    {
-      label: "offsetting bullish and bearish evidence",
-      count: Math.min(sumDriverCounts(positiveDrivers), sumDriverCounts(negativeDrivers)),
-      polarity: "mixed",
-      terms: [
-        ...positiveDrivers.flatMap((d) => d.terms),
-        ...negativeDrivers.flatMap((d) => d.terms),
-      ],
-      sourceIds: [
-        ...new Set([
-          ...positiveDrivers.flatMap((d) => d.sourceIds),
-          ...negativeDrivers.flatMap((d) => d.sourceIds),
-        ]),
-      ],
-    },
-  ];
-}
-
-function representativeItemsFor(
-  records: SentinelRecord[],
-  options: BuildSentimentInsightOptions,
-): SentimentRepresentativeItem[] {
-  const cap = options.aggregate
-    ? (options.config?.maxAggregateRepresentativeItems ?? DEFAULT_AGGREGATE_ITEM_CAP)
-    : (options.config?.maxRepresentativeItemsPerSource ?? DEFAULT_SOURCE_ITEM_CAP);
-
-  return [...records]
-    .sort((a, b) => itemRank(b) - itemRank(a))
-    .slice(0, cap)
-    .map((record) => ({
-      source: record.source,
-      sourceId: record.sourceId,
-      title: record.title,
-      excerpt: excerptFor(record),
-      url: record.url || null,
-      author: record.author,
-      publishedAt: record.publishedAt,
-      engagement: Number.isFinite(record.engagement.score) ? record.engagement.score : null,
-      score: record.sentiment.score,
-      matchedTerms: [
-        ...stringArray(record.metadata.matchedBullishTerms),
-        ...stringArray(record.metadata.matchedBearishTerms),
-      ],
-      metadata: record.metadata,
-    }));
-}
-
-function notableClaimsFor(
-  records: SentinelRecord[],
-  options: BuildSentimentInsightOptions,
-): string[] {
-  const cap = options.config?.maxNotableClaims ?? DEFAULT_CLAIM_CAP;
-  const claims = new Set<string>();
-  for (const record of representativeItemsFor(records, { ...options, aggregate: false })) {
-    const claim = record.title ?? record.excerpt;
-    if (claim) claims.add(claim);
-    if (claims.size >= cap) break;
-  }
-  return [...claims];
-}
-
-function buildConfidence(
-  records: SentinelRecord[],
-  scored: SentinelRecord[],
-  sourceCounts: Record<string, number>,
-  caveats: string[],
-  config: Partial<SentimentConfig> | undefined,
-): SentimentInsightConfidence {
-  const minSample = config?.minUsefulSampleSize ?? DEFAULT_MIN_SAMPLE;
-  const sampleRatio = Math.min(records.length / minSample, 1);
-  const scoredRatio = records.length === 0 ? 0 : scored.length / records.length;
-  const coverageRatio = Math.min(Object.keys(sourceCounts).length / 3, 1);
-  let score = sampleRatio * 0.4 + scoredRatio * 0.4 + coverageRatio * 0.2;
-  const reasons: string[] = [];
-
-  if (records.length < minSample) {
-    reasons.push(`low sample size (${records.length}/${minSample})`);
-  }
-  if (scoredRatio < 0.5) {
-    reasons.push("most records were neutral or had no keyword sentiment match");
-  }
-  if (Object.keys(sourceCounts).length <= 1) {
-    reasons.push("single-source sentiment coverage");
-  }
-  if (caveats.length > 0) {
-    score -= Math.min(0.2, caveats.length * 0.05);
-  }
-
-  score = clamp01(score);
-  return {
-    level: score >= 0.7 ? "high" : score >= 0.4 ? "medium" : "low",
-    score,
-    reasons,
-  };
-}
-
-function buildCaveats(
-  records: SentinelRecord[],
-  scored: SentinelRecord[],
-  sourceCounts: Record<string, number>,
-  options: BuildSentimentInsightOptions,
-): string[] {
-  const minSample = options.config?.minUsefulSampleSize ?? DEFAULT_MIN_SAMPLE;
-  const caveats = [...(options.extraCaveats ?? [])];
-  if (records.length < minSample) caveats.push(`Low sample size: ${records.length} records.`);
-  if (records.length > 0 && scored.length === 0)
-    caveats.push("No records contained keyword sentiment matches.");
-  if (records.length > 0 && scored.length / records.length < 0.5) {
-    caveats.push("Most records were neutral or unscored by keyword matching.");
-  }
-  if (Object.keys(sourceCounts).length <= 1) caveats.push("Single-source sentiment coverage.");
-  if (options.missingSources && options.missingSources.length > 0) {
-    caveats.push(`Missing sources: ${options.missingSources.join(", ")}.`);
-  }
-  return [...new Set(caveats)];
-}
-
-function countBySource(records: SentinelRecord[]): Record<string, number> {
-  const counts: Record<string, number> = {};
-  for (const record of records) {
-    counts[record.source] = (counts[record.source] ?? 0) + 1;
-  }
-  return counts;
-}
-
-function stringArray(value: unknown): string[] {
-  return Array.isArray(value)
-    ? value.filter((item): item is string => typeof item === "string")
-    : [];
-}
-
-function sumDriverCounts(drivers: SentimentInsightDriver[]): number {
-  return drivers.reduce((sum, driver) => sum + driver.count, 0);
-}
-
-function itemRank(record: SentinelRecord): number {
-  const sentimentWeight = Math.abs(record.sentiment.score) * 100;
-  const confidenceWeight = record.sentiment.confidence * 20;
-  const engagementWeight = Math.log10(Math.max(0, record.engagement.score) + 1);
-  return sentimentWeight + confidenceWeight + engagementWeight;
-}
-
-function excerptFor(record: SentinelRecord): string {
-  const raw = record.title ? `${record.title} ${record.text}` : record.text;
-  const normalized = raw.replace(/\s+/g, " ").trim();
-  return normalized.length > 220 ? `${normalized.slice(0, 219)}…` : normalized;
-}
-
-function clamp01(value: number): number {
-  return Math.max(0, Math.min(1, value));
-}

package/src/sentiment/keywords.ts

@@ -1,31 +0,0 @@
-export const BULLISH_TERMS = [
-  "moon",
-  "buy",
-  "undervalued",
-  "breakout",
-  "calls",
-  "bullish",
-  "rocket",
-  "diamond hands",
-  "accumulate",
-  "dip buy",
-  "long",
-  "rip",
-  "squeeze",
-] as const;
-
-export const BEARISH_TERMS = [
-  "crash",
-  "overvalued",
-  "sell",
-  "puts",
-  "bearish",
-  "bubble",
-  "dump",
-  "short",
-  "bagholding",
-  "exit",
-  "drill",
-  "tank",
-  "rug",
-] as const;

package/src/sentiment/pipeline.ts

@@ -1,91 +0,0 @@
-import type { SentimentConfig } from "../config.js";
-import { buildSentimentInsight } from "./insights.js";
-import { scoreRecords } from "./scorer.js";
-import type { SentimentStore } from "./store.js";
-import { computeDivergence, computeTrend, type SourceStats } from "./trends.js";
-import type {
-  DivergenceResult,
-  SentimentSource,
-  SentimentSummary,
-  SentinelRecord,
-  TrendResult,
-} from "./types.js";
-
-export class SentimentPipeline {
-  constructor(
-    private store: SentimentStore,
-    private config: SentimentConfig,
-  ) {}
-
-  async processRecords(records: SentinelRecord[], query: string): Promise<SentimentSummary> {
-    const warnings: string[] = [];
-
-    if (records.length === 0) {
-      return { fresh: [], trend: null, divergence: null, warnings };
-    }
-
-    // Check if store had prior data before this fetch
-    const priorSeries = this.store.getTimeSeries(query, { days: 30, bucketHours: 24 });
-    const hadPriorData = priorSeries.length >= 2;
-
-    // Score all records
-    const scored = scoreRecords(records);
-
-    // Insert into store
-    this.store.insert(scored);
-
-    // Compute trend from historical data (only if we had prior data)
-    let trend: TrendResult[] | null = null;
-    if (hadPriorData) {
-      const series = this.store.getTimeSeries(query, { days: 7, bucketHours: 24 });
-      if (series.length >= 2) {
-        trend = [computeTrend(series, "aggregate")];
-      }
-    }
-
-    // Compute divergence from fresh records
-    let divergence: DivergenceResult | null = null;
-    const sourceGroups = groupBySource(scored);
-    const sourceStats: {
-      twitter?: SourceStats;
-      reddit?: SourceStats;
-      web?: SourceStats;
-      finnhub?: SourceStats;
-    } = {};
-
-    for (const [source, recs] of Object.entries(sourceGroups)) {
-      // Exclude comments from divergence calculation
-      const postLevel = recs.filter((r) => !r.metadata.isComment);
-      if (postLevel.length > 0) {
-        const avg = postLevel.reduce((sum, r) => sum + r.sentiment.score, 0) / postLevel.length;
-        sourceStats[source as SentimentSource] = { avg, count: postLevel.length };
-      }
-    }
-
-    if (Object.keys(sourceStats).length >= 2) {
-      divergence = computeDivergence(sourceStats, this.config.divergenceThreshold);
-    }
-
-    return {
-      fresh: scored,
-      trend,
-      divergence,
-      warnings,
-      insight: buildSentimentInsight({
-        query,
-        records: scored,
-        config: this.config,
-        aggregate: true,
-      }),
-    };
-  }
-}
-
-function groupBySource(records: SentinelRecord[]): Record<string, SentinelRecord[]> {
-  const groups: Record<string, SentinelRecord[]> = {};
-  for (const r of records) {
-    if (!groups[r.source]) groups[r.source] = [];
-    groups[r.source].push(r);
-  }
-  return groups;
-}