Bullish

Bullish turns a bearish database into decision KPIs and serves them to an LLM client over the Model Context Protocol: which sector, country or ETF is attractive, which stocks fit a preset such as quality on sale, whether a stock is fundamentally sound and only temporarily oversold, and whether the data is good enough to judge. Technical analysis (TA-Lib indicators and signals) is one block of those KPIs.

Nothing here is a forecast: every KPI carries an evidence tier (A academic, B practitioner, C heuristic) and every answer the date of the run it is based on.

Prerequisites

• A bearish database: bearish run ./bear.db Belgium (prices, statements, analyst and ownership data), then bearish macro, bearish link, bearish members, bearish fx for the group-level KPIs.
• TA-Lib: the ta-lib wheel bundles the C library on supported platforms; otherwise see the TA-Lib installation guide.

pip install bullishpy

What is computed

KPIs are ranked 0-100 inside their peer group (winsorised, direction-aware), blocks average their KPIs and composites average their blocks; weights are declared in bullish/scoring/presets.py and every block carries its rationale. Values are stored point-in-time in the long kpi table and the score table, so as_of questions are answered with what was known then.

Running it

# compute every KPI, score and grade for today (or a past date) and store them
bullish compute --db /path/to/bear.db [--as-of 2026-06-30] [--country USA --country DEU]
bullish compute --db /path/to/bear.db --symbol AAPL --symbol NVDA   # a few names only
bullish compute --db /path/to/bear.db --profile                     # per-phase time and memory

# a monthly grid of past runs, then a rank backtest of a KPI or a preset
bullish history 2024-01-31 2026-09-30 --db /path/to/bear.db --step-months 1
bullish backtest mom_12_1 --db /path/to/bear.db --horizon-months 3
bullish backtest quality_on_sale --db /path/to/bear.db

# serve the MCP server (stdio for Claude Desktop / Claude Code, or streamable HTTP)
bullish mcp --db /path/to/bear.db
bullish mcp --db /path/to/bear.db --transport streamable-http --port 8765

Claude Desktop / Claude Code configuration:

{
  "mcpServers": {
    "bullish": {
      "command": "uv",
      "args": ["run", "bullish", "mcp", "--db", "/path/to/bear.db"]
    }
  }
}

Settings come from the environment or a .env file (BULLISH_DATABASE_PATH, BULLISH_BASE_CURRENCY, BULLISH_PEER_GROUP, BULLISH_MIN_DOLLAR_VOLUME, BULLISH_MIN_MARKET_CAP, BULLISH_ALLOW_SQL, ...), see bullish/config.py.

A run covers the equities that have at least BULLISH_MIN_PRICE_ROWS (default 60) price rows inside the lookback; everything else bearish knows is still reachable through the coverage and scorecard tools. The per-symbol technical signals run in BULLISH_WORKERS processes (default: all CPUs but one). Each run stores its long kpi rows and one compressed wide frame (kpiwide), which is what the MCP server reads, so a tool call costs milliseconds once warm. bullish history loads the data once for the whole span and derives every monthly run from it. docs/plans/2026-10-compute-performance.md has the measurements behind these choices.

MCP tools

get_market_regime, rank_sectors, rank_industries, rank_countries, rank_etfs, compare_etfs, screen_equities, explain_score, get_equity_scorecard, assess_stock, get_kpi_series, get_smart_money, get_technical_signals, get_filings, get_earnings_calendar, get_macro_snapshot, get_commodity_snapshot, get_data_coverage, analyze_portfolio, list_kpis, describe_kpi, list_composites, list_runs and, when BULLISH_ALLOW_SQL=1, a read-only query. Resources expose the KPI catalogue and the methodology of each composite; prompts cover a weekly market review, a sector briefing, an ETF selection and a stock due diligence.

The plan behind this layer, with the literature it rests on, is in docs/plans/2026-10-decision-kpis-and-mcp.md.

Development

Bullish uses uv for dependency management.

uv sync --all-groups          # environment with the dev tools
uv run pytest                 # tests (tests/v2 run on a synthetic bearish database; test_benchmark bounds a 500-symbol run)
uv run nox -s linting         # black, mypy (strict), ruff

The repository layout:

What Bullish is not

Not a trading platform and not real-time: it is a research layer for decisions over days to months, on data you own locally.