StockSage

Local-first, multi-agent stock analysis. Enter a ticker → get a full investment report in minutes — valuation, performance, financial health, sentiment, and a final verdict — all streamed live to your browser.

You bring your own model (Ollama, OpenAI, Gemini, DeepSeek, Groq, Anthropic). No cloud account required to run locally.

⚠️ Not financial advice. Output is generated by LLMs and may be inaccurate. Never make investment decisions based solely on this tool.

Project status: solo-maintained, alpha. Looking for co-maintainers — if you're interested in helping review PRs, triage issues, or shape the roadmap, open an issue or reach out via MAINTAINERS.md. Contributions of any size are welcome (see CONTRIBUTING.md).

<!-- [](https://pypi.org/project/stocksage/) --> <!-- Uncomment once published to PyPI (tracked in ROADMAP item 1). -->

CI intentionally targets Python 3.13 for deterministic behavior across local runs and contributors.

---

What it does

Symbol input → live pipeline → structured analysis cards

• Validates the ticker (US and Indian .NS/.BO formats)
• Downloads price history, financials, benchmarks, news, Google Trends, insider transactions, and institutional holders — saved as CSVs
• Runs a 7-agent CrewAI pipeline sequentially: data sanity check → valuation ratios → price performance → financial health → market sentiment → cross-agent review → final investment report
• Streams every step live to the browser via SSE — see the agents think in real time
• Renders structured cards for each analysis domain with a final BUY / HOLD / SELL verdict and confidence level

Analysis card example — Financial Health

---

Quickstart

# 1. Clone and install
git clone https://github.com/kanishk-varshney/StockSage.git
cd StockSage
uv sync                         # or: pip install -e ".[dev]"

# 2. Configure
cp .env.example .env            # set LLM_MODEL + API key (see table below)

# 3. Check config
make check

# 4. Run
make run                        # opens at http://127.0.0.1:8000

Enter a symbol (AAPL, RELIANCE.NS, GOOGL) and hit Analyze.

---

Model providers

Pick any row. Set LLM_MODEL and the matching API key in .env.

| Provider | LLM_MODEL | Key needed | Cost | |----------|-------------|------------|------| | Ollama (local) | ollama/qwen2.5:14b-instruct | None — install Ollama + ollama pull … | Free | | DeepSeek | deepseek/deepseek-chat | DEEPSEEK_API_KEY | ~$0.01–0.05 / analysis | | Gemini | gemini/gemini-2.5-flash | GEMINI_API_KEY | Free tier (10 RPM) | | Groq | groq/llama-3.3-70b-versatile | GROQ_API_KEY | Free tier | | OpenAI | openai/gpt-4o-mini | OPENAI_API_KEY | Pay-per-use | | Anthropic | anthropic/claude-3-5-haiku-20241022 | ANTHROPIC_API_KEY | Pay-per-use |

Optional: Set LLM_FALLBACK_MODEL to a cloud model — if Ollama is unreachable the app switches automatically.

Optional: Set SERPER_API_KEY for live web search inside the sentiment agent.

Full copy-paste .env recipes: docs/model-providers.md

---

How it works

Browser → StockProcessor → DownloadPipeline → CSV files
                       ↓
               AnalysisPipeline (CrewAI)
                  ├── data_sanity_agent
                  ├── ratio_analyst
                  ├── performance_analyst
                  ├── fundamental_analyst
                  ├── sentiment_analyst
                  ├── market_reviewer        ← cross-checks other agents
                  └── investment_advisor     ← final verdict
                       ↓
               format_log_entry → SSE stream → UI cards

Each agent gets read-only access to the downloaded CSVs via a CSVReaderTool. Agent roles, goals, and backstories are defined in plain YAML (src/crew/config/agents.yaml) — no code changes needed to adjust behavior.

Full architecture and extension points: docs/architecture.md

---

Make commands

make install   # install deps + pre-commit hooks
make run       # start prod server (http://127.0.0.1:8000)
make dev       # start dev/mock-stream server
make test      # run tests with coverage
make lint      # ruff check
make format    # auto-fix lint + format
make typecheck # mypy over src/
make security  # pip-audit + bandit
make check     # validate .env + LLM connectivity
make clean     # remove __pycache__, .pytest_cache, coverage artifacts

API docs (auto-generated by FastAPI):

| URL | What | |-----|------| | http://127.0.0.1:8000/docs | Swagger / interactive API explorer | | http://127.0.0.1:8000/redoc | ReDoc reference docs |

Docker

# Build and run with docker-compose (persists .market_data between restarts)
docker compose up --build

# Or build the image directly
docker build -t stocksage .
docker run -p 8000:8000 --env-file .env stocksage

---

Self-hosting

StockSage needs a persistent container (not serverless) — analyses run for 2–5 minutes with SSE streaming. Recommended platforms:

| Platform | Cost | Notes | |----------|------|-------| | Railway | $5/mo | Best value. Auto-detects Dockerfile. | | Render | $7/mo | Good alternative. Free tier sleeps. | | Fly.io | ~$3–5/mo | Competitive, slightly more config. |

Do not use Vercel — serverless timeouts will cut off analyses.

Full deploy guide: docs/self-host.md · walkthrough.md

---

Documentation

📖 Full docs site: kanishk-varshney.github.io/StockSage

| Doc | What's in it | |-----|-------------| | docs/local-setup.md | Install, platform notes, troubleshooting | | docs/model-providers.md | .env recipes per LLM provider | | docs/architecture.md | Module map, data flow, extension points | | docs/self-host.md | Docker, Railway, RAM requirements | | docs/examples/output-preview.md | Sample analysis output | | docs/stream-api.md | SSE events for /stream and /stream/mock | | walkthrough.md | Dev modes, mock streaming, agent iteration | | ROADMAP.md | Scope, non-goals, near-term priorities | | CHANGELOG.md | Release notes |

---

Contributing

Contributions are welcome — bug fixes, new features, better agent prompts, UI improvements, and docs.

1. Set up

git clone https://github.com/kanishk-varshney/StockSage.git
cd StockSage
uv sync                  # install exact deps from uv.lock
cp .env.example .env     # set LLM_MODEL + key
make test                # confirm all tests pass before you start

2. Branch naming & commits

Branches must match ^(feat|fix|docs|chore|refactor|test)/[a-z0-9][a-z0-9-]*$ and PR titles follow Conventional Commits. Both are enforced in CI. Signed commits are required on main.

Full rules, examples, and signing setup: CONTRIBUTING.md → Branching & commits.

3. Workflow

main  ──┬──────────────────────────────────► main
        │
        └─► feat/your-feature
              ├── make test && make lint   (before pushing)
              └── open PR → describe what + why + how you tested

• One logical change per PR — easier to review and revert if needed
• Never push directly to main
• Run make test and make lint locally before opening a PR
• UI changes: include a screenshot or short screen recording in the PR description
• Docs changes: update any affected docs/ files in the same PR

4. Good first issues

If you're new here, these are well-scoped starting points:

| Issue | Where to look | |-------|--------------| | Add a test for the download pipeline with mocked yfinance | tests/core/, src/core/market/ | | Improve error message when a ticker has no financial data | src/core/processing/download_pipeline.py | | Add a new LLM provider example to docs | docs/model-providers.md | | Add a new analysis card (formatter + schema) | src/app/utils/formatters/, src/crew/schemas/ | | Add workflow_dispatch trigger to CI | .github/workflows/ci.yml |

Label: look for good first issue once the repo is public.

5. AI-assisted contributions

This project was built with AI coding assistance. AI-generated contributions are welcome — use whatever tools help you. The only requirement: you understand and can explain what you're submitting. Don't paste-and-run without reading.

Full guide: CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md

---

Contributors

<!-- ALL-CONTRIBUTORS-LIST:START -->

Contributions of any kind are welcome — code, docs, issue reports, and feedback all count.

<!-- ALL-CONTRIBUTORS-LIST:END -->

---

License

Released under the MIT License.