svai (Stock Screener focused on Value)

A small .NET CLI for fetching market data and running a v0 screening workflow (prices + fundamentals, with optional macro/options inputs).

Solution layout

• src/StockScreener.Cli/ — CLI app (svai) built with Spectre.Console.Cli
• src/StockScreener.Core/ — domain models + scoring + orchestration (StockScreenerEngine)
• src/StockScreener.Data/ — data providers (prices, fundamentals, macro, options)
• tests/StockScreener.Tests/ — unit tests (xUnit)

Prerequisites

• .NET SDK (targets net10.0)

Install (macOS/Linux)

Option A: install via scripts (recommended)

This repo includes helper scripts that publish and install svai onto your PATH via a symlink.

Default install location: /usr/local/bin/svai.

./install.sh

Uninstall:

./uninstall.sh

If you prefer a user-local install (no sudo), use:

PREFIX=~/.local ./install.sh
PREFIX=~/.local ./uninstall.sh
# ensure ~/.local/bin is on your PATH

Option B: Makefile shortcuts

make publish
make install
make uninstall

Option C: dotnet tool-style install (local tool manifest)

This is convenient for development machines because it pins the tool in a repo-local manifest.

make svai-install
# run:
dotnet tool run svai -- --help
# or (dotnet supports this shorthand for local tools):
dotnet svai -- --help

Uninstall:

make svai-uninstall

Run

Show CLI help:

dotnet run --project src/StockScreener.Cli/StockScreener.Cli.csproj -- --help

Prices

Fetch recent daily prices (default provider: Stooq):

dotnet run --project src/StockScreener.Cli/StockScreener.Cli.csproj -- prices AAPL --days 5

Doctor

Print configured vs effective providers and whether required API keys are present:

dotnet run --project src/StockScreener.Cli/StockScreener.Cli.csproj -- doctor --verbose

Screen (v0)

Run a simple screen over tickers. This fetches fundamentals + price history per ticker and computes a toy score.

dotnet run --project src/StockScreener.Cli/StockScreener.Cli.csproj -- screen AAPL,MSFT,NVDA --days 90 --top 10

Explain a single ticker (factor breakdown + the inputs used):

dotnet run --project src/StockScreener.Cli/StockScreener.Cli.csproj -- screen AAPL,MSFT,NVDA --days 90 --explain MSFT

Normalization / z-scoring

By default, scoring uses raw heuristic inputs.

You can optionally normalize inputs using per-run z-scores (computed only over the tickers in the current screen invocation):

• --normalize none (default)
• --normalize global — z-score across all tickers in the run
• --normalize sector — z-score within each sector (falls back to global if the sector sample is too small)

Example:

dotnet run --project src/StockScreener.Cli/StockScreener.Cli.csproj -- screen AAPL,MSFT,NVDA,GOOG --days 90 --normalize global

Simple filters

Filters exclude tickers before scoring (and before optional/expensive calls like options):

• --min-fcf-yield <YIELD>
• --max-pe <PE>
• --min-roic <ROIC>
• --max-netdebt-ebitda <X>
• --min-momentum <R> (20d momentum, e.g. 0 for non-negative)

Example:

dotnet run --project src/StockScreener.Cli/StockScreener.Cli.csproj -- screen AAPL,MSFT,NVDA --days 90 --max-pe 30 --min-roic 0.1 --min-momentum 0

Configuration

Edit src/StockScreener.Cli/appsettings.json.

Providers

Providers are selected via:

• Providers:PriceProvider
• Providers:FundamentalsProvider
• Providers:MacroProvider
• Providers:OptionsProvider

Supported implementations (current):

• Prices: Stooq, Yahoo (unofficial), AlphaVantage
• Fundamentals: Fmp (recommended, default), AlphaVantage, or config fallback
• Macro: Fred or config fallback
• Options: Polygon (may require paid entitlements) or config fallback (returns null)

Environment variables / .env (recommended for API keys)

This project loads environment variables via .NET configuration and (for local dev convenience) also loads a local .env file at startup.

• Copy .env.example to .env
• Fill in your real keys in .env
• .env is gitignored (do not commit secrets)

Example keys:

• Providers__FmpApiKey — Financial Modeling Prep (free tier: 250 req/day)
• Providers__AlphaVantageApiKey — Alpha Vantage (free tier: 25 req/day)
• Providers__FredApiKey — FRED
• Providers__PolygonApiKey — Polygon.io

Notes

• Scoring is intentionally naive (toy heuristics). It will evolve toward normalized, sector-aware factors.
• Some APIs have free-tier rate limits. FMP (250 req/day) is recommended over AlphaVantage (25 req/day) for fundamentals.
• Polygon options snapshots may return 403 NOT_AUTHORIZED depending on your plan; the CLI degrades gracefully (options snapshot will be none).