Skip to content

README.md

Latest commit

 

History

History
118 lines (102 loc) · 4.69 KB

README.md

File metadata and controls

118 lines (102 loc) · 4.69 KB

StockBot – Weekly Value-Scoring Assistant

Build License Python

Overview

StockBot automates a weekly value-investing workflow. It fetches financial statements from Yahoo Finance, derives per-share metrics, and scores each holding against eleven weighted criteria covering valuation (P/E, P/B, PEG), quality (ROE, Piotroski), cash flow, and margin-of-safety considerations. Scores drive BUY/HOLD/SELL recommendations that are persisted to PostgreSQL and surfaced via CSV exports and Telegram notifications. The project demonstrates production-grade async database access, typed data pipelines, and lightweight integrations with LLM-based confirmation and news enrichment.

Features

  • Eleven-factor scoring model covering value, profitability, and quality metrics.
  • Daily ingestion that aggregates into a Monday rebalancing report.
  • CSV export suitable for manual execution or brokerage import.
  • Optional LLM confirmation stage with OpenAI and Tavily news search.
  • Telegram notifications for daily status updates.
  • Async PostgreSQL data layer built on psycopg v3.
  • Key dependencies include yfinance for market data, psycopg for async database access, openai and tavily-python for confirmation, and python-dotenv for configuration management.

11-Factor Scoring Model

Factor Weight
Asset Value (P/B vs 1) 15 %
P/E Ratio 10 %
P/B Ratio 5 %
PEG Ratio 10 %
Debt / Equity 5 %
ROE 10 %
Free-Cash-Flow Yield 10 %
Dividend Yield 5 %
Margin of Safety (Intrinsic – Price) 15 %
Peer Relative (EV/EBITDA & P/S) 10 %
Piotroski F-score 5 %

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Configuration

  1. Duplicate .env.example as .env and provide the following variables:
    • DB_REMOTE (or DB_DSN): PostgreSQL connection string.
    • WEEKLY_BUDGET: Optional weekly cash contribution (defaults to 50).
    • OPENAI_API_KEY, TAVILY_API_KEY: Required for LLM confirmation.
    • TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID: Required for notifications.
  2. Ensure PostgreSQL is reachable. Example using Docker: 
    docker run --name stockbot-db \
  -e POSTGRES_USER=stockbot \
  -e POSTGRES_PASSWORD=stockpass \
  -e POSTGRES_DB=stockbot \
  -p 5432:5432 -d postgres:16
  3. Bootstrap the schema: 
    python ensure_tables.py
  4. Seed the starting portfolio by editing portfolio.csv and running: 
    python init_portfolio/init_portfolio.py

Usage

Daily ingestion and weekly aggregation

python main.py

This command performs a weekday-specific ingestion. Monday executions aggregate the previous six daily snapshots, compute average scores, clear the daily tables, send a Telegram summary, and store final decisions in the analysis table.

LLM confirmation pipeline

from llm_confirmer import confirm_decisions

analyses = [
    {"ticker": "BMW.DE", "score": 72.5, "decision": "BUY"},
    {"ticker": "ENEL.MI", "score": 38.1, "decision": "SELL"},
]
confirmed = confirm_decisions(analyses)

CSV report generation

from portfolio_manager import plan_trades
from report import write_csv

portfolio = [
    {"ticker": "BMW.DE", "quantity": 5.0},
    {"ticker": "ENEL.MI", "quantity": 10.0},
]
analyses = [
    {"ticker": "BMW.DE", "price": 95.2, "score": 78.4, "llm_decision": "BUY"},
    {"ticker": "ENEL.MI", "price": 6.1, "score": 35.0, "llm_decision": "SELL"},
]

sell_plan, buy_plan = plan_trades(portfolio, analyses, base_budget=50.0)
write_csv(sell_plan, buy_plan)

This produces a CSV similar to:

Action,Ticker,Quantity,Price,Allocated Amount (€)
SELL,ENEL.MI,10.0,6.1,61.0
BUY,BMW.DE,1,95.2,95.2

Testing

Run the automated test suite with:

pytest

Deployment

  • Database: Host PostgreSQL on a managed service such as Neon or RDS.
  • Scheduler: Use a cron service (Render cron jobs, GitHub Actions, or systemd timers) to execute python main.py at the desired cadence.
  • Secrets Management: Provide environment variables through the scheduler or a secrets manager.

License

Distributed under the MIT License. See LICENSE for details.