Smart Invest

Smart Invest is an educational stock research and portfolio insight platform powered by provider-backed market data, normalized domain models, and LangChain Deep Agents orchestration.

It is built for research and decision support only. It does not place trades, transmit brokerage instructions, or provide fiduciary financial advice.

What it does

• Research one or more tickers with market snapshots, fundamentals, news, sentiment, citations, and risk context.
• Review local portfolio files (.json or .csv) and generate educational portfolio reports.
• Scan top losers for educational opportunity candidates.
• Expose the same core workflows through a CLI and a FastAPI service.
• Preserve provenance, freshness, and source errors instead of fabricating unavailable market data.

Workspace layout

packages/core     Canonical models, settings, policies, recommendations, and analytics
packages/tools    Provider adapters, normalization, storage, portfolio ingestion, and tool functions
packages/agents   Deep Agents orchestration, reporting, subagents, and tool registry
apps/cli          `smart-invest` command-line interface
apps/api          FastAPI application and HTTP routes
apps/mcp          MCP app package scaffold

Requirements

• Python 3.14+
• uv
• Optional: just for workspace task shortcuts

Setup

Install all workspace packages and development dependencies:

uv sync --all-packages --dev

Or use the task runner:

just bootstrap

Configuration

Start from the example config and replace placeholder values with your own keys:

cp smart-invest.yaml.example smart-invest.yaml

The config loader checks, in order:

1. --config <path>
2. SMART_INVEST_CONFIG
3. smart-invest.yaml
4. .smart-invest.yaml
5. ~/.config/smart-invest/config.yaml

You can select a profile with --profile or SMART_INVEST_PROFILE.

Required settings include OpenRouter and Alpha Vantage credentials. Optional integrations include NewsAPI, Alpha Vantage news, Langfuse tracing, cache settings, and Postgres-backed storage.

CLI usage

Show CLI help:

uv run smart-invest --help
# or
just cli --help

Research tickers:

uv run smart-invest research NVDA
uv run smart-invest r NVDA MSFT --output json
uv run smart-invest research AAPL --focus "Check valuation and catalysts"

Review a portfolio file:

uv run smart-invest review-portfolio portfolio.json
uv run smart-invest rp holdings.csv --output json
uv run smart-invest review-portfolio portfolio.json --focus "Check concentration risk"

Scan for educational opportunity candidates:

uv run smart-invest find-opportunities --limit 5
uv run smart-invest opps --limit 10 --output json

Use a specific config or profile:

uv run smart-invest --config smart-invest.yaml --profile local research TSLA
uv run smart-invest --set-env SMART_INVEST_OPENROUTER__MODEL=openai/gpt-5.4 research META

API usage

Start the API in development mode:

just api
# equivalent:
uv run --package smart-invest-api uvicorn smart_invest_api.app:app --reload --host 0.0.0.0 --port 8000

Available routes include:

• GET /health
• POST /research/ticker
• POST /portfolio/review
• POST /portfolio/saved/review
• POST /portfolio/recommendations

Example ticker research request:

curl -X POST http://localhost:8000/research/ticker \
  -H 'content-type: application/json' \
  -d '{"ticker":"NVDA","include_news":true,"include_fundamentals":true}'

Example uploaded portfolio review:

curl -X POST http://localhost:8000/portfolio/review \
  -F file=@portfolio.json \
  -F 'focus=Check concentration risk'

Common development commands

just sync          # install workspace packages and dev dependencies
just lint-check    # run ruff without modifying files
just fmt-check     # check formatting
just typecheck     # run basedpyright
just test          # run pytest
just check         # lint, format check, and typecheck
just ci            # sync, quality checks, and tests

Targeted tests:

just test-path packages/core
just test-k smoke

Package builds and publishing:

just build-packages
just publish-packages <uv-index>

Safety and product boundaries

Smart Invest is educational and non-advisory. User-facing recommendations must include citations, provenance, risk context, and disclaimer coverage. The system must never auto-trade, generate brokerage-ready instructions, or hide missing citations, stale data, provider failures, or low-confidence outputs.