bbterm-tui 0.1.1__py3-none-any.whl

bbterm/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("bbterm-tui")
+except PackageNotFoundError:  # running from a source tree, not installed
+    __version__ = "0.0.0+source"

bbterm/commands.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_SYMBOL_RE = re.compile(r"^[A-Z0-9]{1,6}([.\-][A-Z0-9]{1,4})?$")
+
+
+@dataclass(frozen=True)
+class LoadSymbol:
+    symbol: str
+
+
+@dataclass(frozen=True)
+class AddSymbol:
+    symbol: str
+
+
+@dataclass(frozen=True)
+class RemoveSymbol:
+    symbol: str
+
+
+@dataclass(frozen=True)
+class ShowChart:
+    pass
+
+
+@dataclass(frozen=True)
+class ShowStats:
+    pass
+
+
+@dataclass(frozen=True)
+class ShowFundamentals:
+    pass
+
+
+@dataclass(frozen=True)
+class ShowFilings:
+    pass
+
+
+@dataclass(frozen=True)
+class Help:
+    pass
+
+
+@dataclass(frozen=True)
+class Unknown:
+    text: str
+
+
+def _is_symbol(token: str) -> bool:
+    return bool(_SYMBOL_RE.match(token))
+
+
+def parse_command(text: str):
+    cleaned = " ".join(text.strip().split())
+    if not cleaned:
+        return Unknown(text)
+    parts = cleaned.split(" ")
+    verb = parts[0].upper()
+    arg = parts[1].upper() if len(parts) > 1 else None
+
+    if verb in ("ADD",):
+        return AddSymbol(arg) if arg and _is_symbol(arg) else Unknown(text)
+    if verb in ("DEL", "REMOVE"):
+        return RemoveSymbol(arg) if arg and _is_symbol(arg) else Unknown(text)
+    if verb == "GP":
+        return ShowChart()
+    if verb == "DES":
+        return ShowStats()
+    if verb == "FA":
+        return ShowFundamentals()
+    if verb == "FIL":
+        return ShowFilings()
+    if verb in ("?", "HELP"):
+        return Help()
+    if arg is None and _is_symbol(verb):
+        return LoadSymbol(verb)
+    return Unknown(text)

bbterm/config.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Config:
+    databento_api_key: str | None
+    db_path: Path
+    cost_cap_usd: float
+    databento_dataset: str
+
+
+def _load_dotenv(path: Path) -> dict[str, str]:
+    if not path.exists():
+        return {}
+    values: dict[str, str] = {}
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        values[key.strip()] = value.strip().strip('"').strip("'")
+    return values
+
+
+def load_config(root: Path | None = None) -> Config:
+    root = root or Path.cwd()
+    env = {**_load_dotenv(root / ".env"), **os.environ}
+    return Config(
+        databento_api_key=env.get("DATABENTO_API_KEY"),
+        db_path=Path(env.get("BBTERM_DB_PATH", str(root / "data" / "market.duckdb"))),
+        cost_cap_usd=float(env.get("BBTERM_COST_CAP_USD", "1.0")),
+        databento_dataset=env.get("BBTERM_DATASET", "EQUS.MINI"),
+    )

bbterm/data/__init__.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import sys
+
+from bbterm.config import Config
+from bbterm.data.providers.edgar import EdgarProvider
+from bbterm.data.providers.yfinance_ import YFinanceProvider
+from bbterm.data.service import DataService
+from bbterm.data.store import Store
+
+
+def build_service(config: Config) -> DataService:
+    store = Store(config.db_path)
+    yf_provider = YFinanceProvider()
+    edgar = EdgarProvider()
+    if config.databento_api_key:
+        try:
+            from bbterm.data.providers.databento_ import DatabentoProvider
+        except ImportError:
+            print(
+                "DATABENTO_API_KEY is set but the 'databento' package is not "
+                "installed. Run: pip install 'bbterm[databento]'. "
+                "Falling back to yfinance.",
+                file=sys.stderr,
+            )
+        else:
+            bars = DatabentoProvider(
+                api_key=config.databento_api_key,
+                dataset=config.databento_dataset,
+                cost_cap_usd=config.cost_cap_usd,
+            )
+            return DataService(store, bars, yf_provider, edgar_provider=edgar)
+    return DataService(store, yf_provider, yf_provider, edgar_provider=edgar)

bbterm/data/fundamentals.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+
+from bbterm.data.models import Filing, FundamentalMetric
+
+
+@dataclass(frozen=True)
+class MetricSpec:
+    label: str
+    concepts: list[str]   # candidate XBRL concept names, first match wins
+    unit: str             # units key: "USD" | "USD/shares" | "shares"
+
+
+METRIC_SPECS: list[MetricSpec] = [
+    MetricSpec("Revenue",
+               ["RevenueFromContractWithCustomerExcludingAssessedTax",
+                "Revenues", "SalesRevenueNet"], "USD"),
+    MetricSpec("Net Income", ["NetIncomeLoss"], "USD"),
+    MetricSpec("EPS (diluted)", ["EarningsPerShareDiluted"], "USD/shares"),
+    MetricSpec("Gross Profit", ["GrossProfit"], "USD"),
+    MetricSpec("Total Assets", ["Assets"], "USD"),
+    MetricSpec("Total Liabilities", ["Liabilities"], "USD"),
+    MetricSpec("Stockholders' Equity",
+               ["StockholdersEquity",
+                "StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest"],
+               "USD"),
+    MetricSpec("Operating Cash Flow",
+               ["NetCashProvidedByUsedInOperatingActivities"], "USD"),
+    MetricSpec("Shares Outstanding",
+               ["CommonStockSharesOutstanding",
+                "EntityCommonStockSharesOutstanding"], "shares"),
+]
+
+
+def _find_unit_series(facts_json: dict, concept: str, unit: str) -> list[dict] | None:
+    """Return the datapoint list for concept+unit, searching us-gaap then dei."""
+    facts = facts_json.get("facts", {})
+    for taxonomy in ("us-gaap", "dei"):
+        node = facts.get(taxonomy, {}).get(concept)
+        if node:
+            series = node.get("units", {}).get(unit)
+            if series:
+                return series
+    return None
+
+
+def _annual(series: list[dict]) -> list[dict]:
+    return [d for d in series if d.get("fp") == "FY" and "end" in d and "val" in d]
+
+
+def _extract_one(facts_json: dict, spec: MetricSpec) -> FundamentalMetric | None:
+    for concept in spec.concepts:
+        series = _find_unit_series(facts_json, concept, spec.unit)
+        if not series:
+            continue
+        annual = _annual(series)
+        if not annual:
+            continue
+        latest = max(annual, key=lambda d: (d["end"], d.get("fy", 0)))
+        prior = [d for d in annual if d.get("fy") == latest.get("fy", 0) - 1]
+        yoy = None
+        if prior:
+            prior_val = max(prior, key=lambda d: d["end"])["val"]
+            if prior_val:
+                yoy = (latest["val"] - prior_val) / abs(prior_val) * 100
+        return FundamentalMetric(
+            label=spec.label,
+            value=float(latest["val"]),
+            unit=spec.unit,
+            period_end=date.fromisoformat(latest["end"]),
+            fy=int(latest.get("fy", 0)),
+            fp="FY",
+            yoy_pct=yoy,
+        )
+    return None
+
+
+def extract_fundamentals(facts_json: dict) -> list[FundamentalMetric]:
+    out = []
+    for spec in METRIC_SPECS:
+        metric = _extract_one(facts_json, spec)
+        if metric is not None:
+            out.append(metric)
+    return out
+
+
+def parse_filings(submissions_json: dict, limit: int = 20) -> list[Filing]:
+    cik = int(submissions_json.get("cik", 0))
+    recent = submissions_json.get("filings", {}).get("recent", {})
+    forms = recent.get("form", [])
+    dates = recent.get("filingDate", [])
+    periods = recent.get("reportDate", [])
+    accns = recent.get("accessionNumber", [])
+    out: list[Filing] = []
+    for i in range(min(limit, len(forms))):
+        acc = accns[i]
+        acc_nodash = acc.replace("-", "")
+        url = (
+            f"https://www.sec.gov/Archives/edgar/data/{cik}/"
+            f"{acc_nodash}/{acc}-index.htm"
+        )
+        out.append(Filing(
+            form=forms[i],
+            filed_date=date.fromisoformat(dates[i]),
+            period=periods[i] if i < len(periods) else "",
+            accession=acc,
+            url=url,
+        ))
+    return out

bbterm/data/models.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime
+
+
+@dataclass(frozen=True)
+class Bar:
+    symbol: str
+    interval: str  # "1d" or "1m"
+    ts: datetime
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: int
+
+
+@dataclass(frozen=True)
+class Quote:
+    symbol: str
+    price: float
+    prev_close: float
+    name: str = ""
+
+    @property
+    def change(self) -> float:
+        return self.price - self.prev_close
+
+    @property
+    def pct_change(self) -> float:
+        if not self.prev_close:
+            return 0.0
+        return self.change / self.prev_close * 100
+
+    @property
+    def is_up(self) -> bool:
+        return self.change >= 0
+
+    @property
+    def change_str(self) -> str:
+        sign = "+" if self.change >= 0 else ""
+        return f"{sign}{self.change:.2f} ({sign}{self.pct_change:.2f}%)"
+
+
+@dataclass(frozen=True)
+class FundamentalMetric:
+    label: str
+    value: float
+    unit: str
+    period_end: date
+    fy: int
+    fp: str
+    yoy_pct: float | None
+
+
+@dataclass(frozen=True)
+class Filing:
+    form: str
+    filed_date: date
+    period: str
+    accession: str
+    url: str

bbterm/data/providers/base.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Protocol
+
+from bbterm.data.models import Bar, Quote
+
+
+class CostCapExceeded(Exception):
+    def __init__(self, estimated_usd: float, cap_usd: float) -> None:
+        self.estimated_usd = estimated_usd
+        self.cap_usd = cap_usd
+        super().__init__(
+            f"estimated cost ${estimated_usd:.4f} exceeds cap ${cap_usd:.2f}"
+        )
+
+
+class BarProvider(Protocol):
+    name: str
+
+    def get_bars(
+        self, symbol: str, interval: str, start: datetime, end: datetime
+    ) -> list[Bar]: ...
+
+
+class QuoteProvider(Protocol):
+    name: str
+
+    def get_quote(self, symbol: str) -> Quote | None: ...
+
+
+class FundamentalsProvider(Protocol):
+    name: str
+
+    def get_facts(self, symbol: str) -> dict: ...
+
+
+class FilingsProvider(Protocol):
+    name: str
+
+    def get_submissions(self, symbol: str) -> dict: ...

bbterm/data/providers/databento_.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+import databento as db
+
+from bbterm.data.models import Bar
+from bbterm.data.providers.base import CostCapExceeded
+
+_SCHEMA = {"1d": "ohlcv-1d", "1m": "ohlcv-1m"}
+
+
+class DatabentoProvider:
+    name = "databento"
+
+    def __init__(
+        self,
+        api_key: str,
+        dataset: str,
+        cost_cap_usd: float,
+        client: db.Historical | None = None,
+    ) -> None:
+        self._client = client or db.Historical(api_key)
+        self._dataset = dataset
+        self._cap = cost_cap_usd
+
+    def get_bars(
+        self, symbol: str, interval: str, start: datetime, end: datetime
+    ) -> list[Bar]:
+        schema = _SCHEMA[interval]
+        cost = float(
+            self._client.metadata.get_cost(
+                dataset=self._dataset, symbols=[symbol], schema=schema,
+                start=start, end=end,
+            )
+        )
+        if cost > self._cap:
+            raise CostCapExceeded(cost, self._cap)
+        result = self._client.timeseries.get_range(
+            dataset=self._dataset, symbols=[symbol], schema=schema,
+            start=start, end=end,
+        )
+        df = result.to_df()
+        bars: list[Bar] = []
+        for ts, row in df.iterrows():
+            naive = ts.to_pydatetime().replace(tzinfo=None)
+            bars.append(
+                Bar(
+                    symbol, interval, naive,
+                    float(row["open"]), float(row["high"]),
+                    float(row["low"]), float(row["close"]), int(row["volume"]),
+                )
+            )
+        return bars

bbterm/data/providers/edgar.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.request
+
+_USER_AGENT = "bbterm/0.1 (yagurootajum@gmail.com)"
+_TICKERS_URL = "https://www.sec.gov/files/company_tickers.json"
+_FACTS_URL = "https://data.sec.gov/api/xbrl/companyfacts/CIK{cik}.json"
+_SUBMISSIONS_URL = "https://data.sec.gov/submissions/CIK{cik}.json"
+
+
+def _http_get(url: str, user_agent: str) -> bytes:
+    req = urllib.request.Request(url, headers={"User-Agent": user_agent})
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return resp.read()
+
+
+class EdgarProvider:
+    name = "edgar"
+
+    def __init__(
+        self,
+        user_agent: str = _USER_AGENT,
+        *,
+        opener=None,
+        rate_limit_sleep: float = 0.0,
+    ) -> None:
+        self._ua = user_agent
+        self._open = opener or _http_get
+        self._sleep = rate_limit_sleep
+        self._cik_map: dict[str, str] | None = None
+
+    def _fetch(self, url: str) -> bytes:
+        if self._sleep:
+            time.sleep(self._sleep)
+        return self._open(url, self._ua)
+
+    def _load_cik_map(self) -> dict[str, str]:
+        raw = json.loads(self._fetch(_TICKERS_URL))
+        out: dict[str, str] = {}
+        for row in raw.values():
+            out[str(row["ticker"]).upper()] = f"{int(row['cik_str']):010d}"
+        return out
+
+    def _cik(self, symbol: str) -> str:
+        if self._cik_map is None:
+            self._cik_map = self._load_cik_map()
+        return self._cik_map[symbol.upper()]
+
+    def get_facts(self, symbol: str) -> dict:
+        url = _FACTS_URL.format(cik=self._cik(symbol))
+        return json.loads(self._fetch(url))
+
+    def get_submissions(self, symbol: str) -> dict:
+        url = _SUBMISSIONS_URL.format(cik=self._cik(symbol))
+        return json.loads(self._fetch(url))

bbterm/data/providers/yfinance_.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+import yfinance as yf
+
+from bbterm.data.models import Bar, Quote
+
+_YF_INTERVAL = {"1d": "1d", "1m": "1m"}
+
+
+class YFinanceProvider:
+    """Dev/fallback provider. Unofficial Yahoo data — not for commercial use."""
+
+    name = "yfinance"
+
+    def get_bars(
+        self, symbol: str, interval: str, start: datetime, end: datetime
+    ) -> list[Bar]:
+        try:
+            df = yf.Ticker(symbol).history(
+                start=start, end=end, interval=_YF_INTERVAL[interval]
+            )
+        except Exception:
+            return []
+        bars: list[Bar] = []
+        for ts, row in df.iterrows():
+            naive = ts.to_pydatetime().replace(tzinfo=None)
+            bars.append(
+                Bar(
+                    symbol, interval, naive,
+                    float(row["Open"]), float(row["High"]),
+                    float(row["Low"]), float(row["Close"]), int(row["Volume"]),
+                )
+            )
+        return bars
+
+    def get_quote(self, symbol: str) -> Quote | None:
+        try:
+            fast = yf.Ticker(symbol).fast_info
+            price, prev = fast.last_price, fast.previous_close
+            if price is None or prev is None:
+                return None
+            return Quote(symbol=symbol, price=float(price), prev_close=float(prev))
+        except Exception:
+            return None

bbterm/data/service.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from datetime import datetime, timedelta
+
+from bbterm.data.fundamentals import extract_fundamentals, parse_filings
+from bbterm.data.models import Bar, Filing, FundamentalMetric, Quote
+from bbterm.data.providers.base import BarProvider, QuoteProvider
+from bbterm.data.store import Store
+
+FETCH_TTL_SECONDS = 300.0
+EDGAR_TTL_SECONDS = 86400.0
+
+
+def _step(interval: str) -> timedelta:
+    return timedelta(days=1) if interval == "1d" else timedelta(minutes=1)
+
+
+class DataService:
+    def __init__(
+        self,
+        store: Store,
+        bar_provider: BarProvider,
+        quote_provider: QuoteProvider,
+        fetch_ttl: float = FETCH_TTL_SECONDS,
+        edgar_provider=None,
+    ) -> None:
+        self.store = store
+        self._bars = bar_provider
+        self._quotes = quote_provider
+        self._ttl = fetch_ttl
+        self._edgar = edgar_provider
+        self._last_fetch: dict[tuple[str, str], float] = {}
+
+    async def get_bars(
+        self, symbol: str, interval: str, start: datetime, end: datetime
+    ) -> list[Bar]:
+        coverage = self.store.coverage(symbol, interval)
+        gaps: list[tuple[datetime, datetime]] = []
+        if coverage is None:
+            gaps.append((start, end))
+        elif not self._recently_fetched(symbol, interval):
+            lo, hi = coverage
+            if start < lo:
+                gaps.append((start, lo - _step(interval)))
+            if end > hi:
+                gaps.append((hi + _step(interval), end))
+        # Daily bars are timestamped at midnight while query bounds carry a
+        # time-of-day, so a gap can collapse to an inverted/sub-step range the
+        # provider rejects. Drop any gap that isn't a forward span.
+        gaps = [(s, e) for s, e in gaps if s < e]
+        for gap_start, gap_end in gaps:
+            fetched = await asyncio.to_thread(
+                self._bars.get_bars, symbol, interval, gap_start, gap_end
+            )
+            self.store.upsert_bars(fetched)
+            self._last_fetch[(symbol, interval)] = time.monotonic()
+        return self.store.get_bars(symbol, interval, start, end)
+
+    async def get_quote(self, symbol: str) -> Quote | None:
+        return await asyncio.to_thread(self._quotes.get_quote, symbol)
+
+    def _recently_fetched(self, symbol: str, interval: str) -> bool:
+        if self._ttl <= 0:
+            return False
+        last = self._last_fetch.get((symbol, interval))
+        return last is not None and (time.monotonic() - last) < self._ttl
+
+    # ---- EDGAR fundamentals / filings -------------------------------------
+    def _edgar_fresh(self, cached) -> bool:
+        if cached is None:
+            return False
+        fetched_at, _ = cached
+        return (datetime.now() - fetched_at).total_seconds() < EDGAR_TTL_SECONDS
+
+    async def get_fundamentals(self, symbol: str) -> list[FundamentalMetric]:
+        cached = self.store.get_edgar_facts(symbol)
+        if not self._edgar_fresh(cached):
+            try:
+                facts = await asyncio.to_thread(self._edgar.get_facts, symbol)
+                self.store.set_edgar_facts(symbol, json.dumps(facts))
+                cached = self.store.get_edgar_facts(symbol)
+            except Exception:
+                if cached is None:
+                    raise
+        _, payload = cached
+        return extract_fundamentals(json.loads(payload))
+
+    async def get_filings(self, symbol: str) -> list[Filing]:
+        cached = self.store.get_edgar_filings(symbol)
+        if not self._edgar_fresh(cached):
+            try:
+                subs = await asyncio.to_thread(self._edgar.get_submissions, symbol)
+                self.store.set_edgar_filings(symbol, json.dumps(subs))
+                cached = self.store.get_edgar_filings(symbol)
+            except Exception:
+                if cached is None:
+                    raise
+        _, payload = cached
+        return parse_filings(json.loads(payload))

bbterm/data/stats.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from bbterm.data.models import Bar, Quote
+
+_ONE_MONTH_SESSIONS = 21
+
+
+@dataclass(frozen=True)
+class Stats:
+    symbol: str
+    last: float
+    change: float | None
+    pct_change: float | None
+    high_52w: float
+    low_52w: float
+    ret_1m: float | None
+    ret_ytd: float | None
+    avg_volume: float
+    day_low: float
+    day_high: float
+
+
+def compute_stats(bars: list[Bar], quote: Quote | None) -> Stats | None:
+    if not bars:
+        return None
+    last_bar = bars[-1]
+    last = quote.price if quote else last_bar.close
+    change = quote.change if quote else None
+    pct_change = quote.pct_change if quote else None
+
+    ret_1m = None
+    if len(bars) >= _ONE_MONTH_SESSIONS + 1:
+        ref = bars[-(_ONE_MONTH_SESSIONS + 1)].close
+        if ref:
+            ret_1m = (last_bar.close / ref - 1) * 100
+
+    year = last_bar.ts.year
+    ytd_ref = next((b.close for b in bars if b.ts.year == year), None)
+    ret_ytd = None
+    if ytd_ref:
+        ret_ytd = (last_bar.close / ytd_ref - 1) * 100
+
+    return Stats(
+        symbol=last_bar.symbol,
+        last=last,
+        change=change,
+        pct_change=pct_change,
+        high_52w=max(b.high for b in bars),
+        low_52w=min(b.low for b in bars),
+        ret_1m=ret_1m,
+        ret_ytd=ret_ytd,
+        avg_volume=sum(b.volume for b in bars) / len(bars),
+        day_low=last_bar.low,
+        day_high=last_bar.high,
+    )