bitcraft 0.1.0__py3-none-any.whl

bitcraft/__init__.py

@@ -0,0 +1,3 @@
+"""BitCraft terminal interface package. Built with Textual."""
+
+__version__ = "0.1.0"

bitcraft/api_client.py

@@ -0,0 +1,146 @@
+"""HTTP client for the BitCraft FastAPI backend.
+
+Thin transport only: JSON in and out. Parsing into dataclasses lives in
+ApiProvider. All ML results are pre-computed; this client never triggers
+scoring (plans/plan.md section 10.3).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+DEFAULT_BASE_URL = "http://localhost:8000"
+DEFAULT_TIMEOUT_S = 1.5
+
+
+class ApiClient:
+    """httpx wrapper around the plan section 10.1 endpoints."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_s: float = DEFAULT_TIMEOUT_S,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout_s = timeout_s
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout_s,
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        """Close the underlying httpx client."""
+        self._client.close()
+
+    def get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        """GET JSON from path. Raises httpx.HTTPError on transport failure."""
+        response = self._client.get(path, params=params)
+        response.raise_for_status()
+        return response.json()
+
+    def health(self) -> dict:
+        """GET /health."""
+        return self.get("/health")
+
+    def get_alerts(self, params: Optional[dict[str, Any]] = None) -> Any:
+        """GET /alerts."""
+        return self.get("/alerts", params=params)
+
+    def get_alert_detail(self, tx_id: int) -> dict:
+        """GET /alerts/{tx_id}."""
+        return self.get(f"/alerts/{tx_id}")
+
+    def get_graph(self, tx_id: int, depth: int = 1) -> dict:
+        """GET /graph/{tx_id}?depth=."""
+        return self.get(f"/graph/{tx_id}", params={"depth": depth})
+
+    def get_community(self, community_id: int) -> dict:
+        """GET /communities/{community_id}."""
+        return self.get(f"/communities/{community_id}")
+
+    def get_communities(self, limit: int = 25, sort: str = "risk") -> list:
+        """GET /communities (top communities overview)."""
+        return self.get("/communities", params={"limit": limit, "sort": sort})
+
+    def get_threat_overview(self) -> dict:
+        """GET /threats/overview."""
+        return self.get("/threats/overview")
+
+    def get_entities(self, offset: int = 0, limit: int = 100) -> dict:
+        """GET /entities (ranked wallets)."""
+        return self.get("/entities", params={"offset": offset, "limit": limit})
+
+    def get_entity(self, entity_id: int) -> dict:
+        """GET /entities/{id}."""
+        return self.get(f"/entities/{entity_id}")
+
+    def get_entity_graph(self, entity_id: int) -> dict:
+        """GET /entities/{id}/graph."""
+        return self.get(f"/entities/{entity_id}/graph")
+
+    def get_stats_summary(self) -> dict:
+        """GET /stats/summary."""
+        return self.get("/stats/summary")
+
+    def get_pipeline_status(self) -> dict:
+        """GET /pipeline/status."""
+        return self.get("/pipeline/status")
+
+
+# Module-level helpers kept for earlier call sites / tests.
+def get_alerts(params: dict | None = None) -> list[dict]:
+    """GET /alerts via a one-shot client (prefer ApiClient in new code)."""
+    client = ApiClient()
+    try:
+        return client.get_alerts(params)
+    finally:
+        client.close()
+
+
+def get_alert_detail(tx_id: int) -> dict:
+    """GET /alerts/{tx_id} via a one-shot client."""
+    client = ApiClient()
+    try:
+        return client.get_alert_detail(tx_id)
+    finally:
+        client.close()
+
+
+def get_graph(tx_id: int, depth: int = 1) -> dict:
+    """GET /graph/{tx_id} via a one-shot client."""
+    client = ApiClient()
+    try:
+        return client.get_graph(tx_id, depth)
+    finally:
+        client.close()
+
+
+def get_community(community_id: int) -> dict:
+    """GET /communities/{community_id} via a one-shot client."""
+    client = ApiClient()
+    try:
+        return client.get_community(community_id)
+    finally:
+        client.close()
+
+
+def get_stats_summary() -> dict:
+    """GET /stats/summary via a one-shot client."""
+    client = ApiClient()
+    try:
+        return client.get_stats_summary()
+    finally:
+        client.close()
+
+
+def get_pipeline_status() -> dict:
+    """GET /pipeline/status via a one-shot client."""
+    client = ApiClient()
+    try:
+        return client.get_pipeline_status()
+    finally:
+        client.close()

bitcraft/app.py

@@ -0,0 +1,217 @@
+"""BitCraft TUI entry point.
+
+Terminal interface built with Textual. Reads pre-computed alert, graph,
+and community data through a swappable DataProvider (demo or FastAPI).
+No ML code runs here. See docs/tui_design.md and plans/plan.md section 11.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from typing import Optional
+
+from textual.app import App, ScreenStackError
+from textual.binding import Binding
+from textual.theme import Theme
+
+from bitcraft.api_client import DEFAULT_BASE_URL
+from bitcraft.providers.demo_provider import DemoProvider
+from bitcraft.providers.factory import create_provider, resolve_source
+from bitcraft.screens.boot import BootScreen
+from bitcraft.screens.dashboard import DashboardScreen
+from bitcraft.screens.graph_explorer import GraphExplorerScreen
+from bitcraft.screens.splash import SplashScreen
+from bitcraft.screens.threat_detection import ThreatDetectionScreen
+from bitcraft.screens.wallet import WalletsScreen
+from bitcraft.store import Store
+
+
+# Gold everywhere Textual would otherwise paint its default blue: table
+# cursors, scrollbars, focus borders, footer keys, checkboxes, selections.
+BITCRAFT_THEME = Theme(
+    name="bitcraft",
+    primary="#d4af37",
+    secondary="#ffa700",
+    accent="#ffd84d",
+    warning="#ff8c42",
+    error="#b3261e",
+    success="#d4af37",
+    foreground="#e6e6e6",
+    background="#000000",
+    surface="#050505",
+    panel="#0d0b08",
+    dark=True,
+    variables={
+        "block-cursor-background": "#d4af37",
+        "block-cursor-foreground": "#000000",
+        "block-cursor-text-style": "bold",
+        "block-cursor-blurred-background": "#d4af37 45%",
+        "block-cursor-blurred-foreground": "#000000",
+        "block-hover-background": "#d4af37 12%",
+        "scrollbar": "#d4af37 55%",
+        "scrollbar-hover": "#e8c55a",
+        "scrollbar-active": "#ffd84d",
+        "scrollbar-background": "#0d0b08",
+        "scrollbar-background-hover": "#0d0b08",
+        "scrollbar-background-active": "#0d0b08",
+        "scrollbar-corner-color": "#0d0b08",
+        "footer-key-foreground": "#d4af37",
+        "footer-foreground": "#7a7a7a",
+        "footer-background": "#000000",
+        "footer-description-foreground": "#9a9080",
+        "input-cursor-background": "#d4af37",
+        "input-cursor-foreground": "#000000",
+        "input-selection-background": "#d4af37 35%",
+        "screen-selection-background": "#d4af37 35%",
+        "border": "#d4af37",
+        "border-blurred": "#3a3020",
+        "link-color": "#ffd84d",
+    },
+)
+
+
+class BitCraftApp(App):
+    """Root Textual application using modes for the main investigation screens.
+
+    Flow: splash -> boot -> dashboard. Modes: dashboard, threats, graph.
+    Detail screens push on top of the active mode.
+    """
+
+    CSS_PATH = "theme.tcss"
+    TITLE = "BitCraft"
+    MODES = {
+        "dashboard": DashboardScreen,
+        "graph": GraphExplorerScreen,
+        "threats": ThreatDetectionScreen,
+        "wallets": WalletsScreen,
+    }
+    DEFAULT_MODE = "dashboard"
+    BINDINGS = [
+        Binding("q", "quit", "Quit", priority=True),
+        Binding("d", "show_dashboard", "Dashboard", priority=True),
+        Binding("g", "show_graph", "Graph", priority=True),
+        Binding("t", "show_threats", "Threats", priority=True),
+        Binding("w", "show_wallets", "Wallets", priority=True),
+        Binding("escape", "go_home", "Home", priority=True),
+    ]
+
+    def __init__(self, store: Optional[Store] = None) -> None:
+        super().__init__()
+        if store is None:
+            store = Store(
+                provider=DemoProvider(simulate_latency=False),
+                is_demo=True,
+                boot_log=["demo default"],
+                fast_boot=True,
+            )
+        self.store = store
+        self.register_theme(BITCRAFT_THEME)
+        self.theme = "bitcraft"
+
+    def clear_selection(self) -> None:
+        """Ignore the startup window where the mode stack is still empty.
+
+        Textual mounts the DEFAULT_MODE screen before registering its stack,
+        and with eager tasks the dashboard's filter Inputs run their selection
+        watcher (which calls this) inside that window. Textual only catches
+        NoScreen here, so a real `app.run()` crashed with ScreenStackError.
+        """
+        try:
+            super().clear_selection()
+        except ScreenStackError:
+            pass
+
+    def on_mount(self) -> None:
+        """Open on the brand splash above the default dashboard mode."""
+        self.push_screen(SplashScreen())
+
+    def _pop_overlays(self) -> None:
+        """Pop pushed overlays until a mode screen is on top."""
+        mode_types = (DashboardScreen, GraphExplorerScreen, ThreatDetectionScreen, WalletsScreen)
+        while len(self.screen_stack) > 1 and not isinstance(self.screen, mode_types):
+            self.pop_screen()
+
+    def action_show_dashboard(self) -> None:
+        """Switch to dashboard mode (ignored on splash)."""
+        if isinstance(self.screen, (SplashScreen, BootScreen)):
+            return
+        self.switch_mode("dashboard")
+        self._pop_overlays()
+
+    def action_show_graph(self) -> None:
+        """Switch to graph mode."""
+        if isinstance(self.screen, (SplashScreen, BootScreen)):
+            return
+        self.switch_mode("graph")
+        self._pop_overlays()
+
+    def action_show_threats(self) -> None:
+        """Switch to threats mode."""
+        if isinstance(self.screen, (SplashScreen, BootScreen)):
+            return
+        self.switch_mode("threats")
+        self._pop_overlays()
+
+    def action_show_wallets(self) -> None:
+        """Switch to wallets mode."""
+        if isinstance(self.screen, (SplashScreen, BootScreen)):
+            return
+        self.switch_mode("wallets")
+        self._pop_overlays()
+
+    def action_go_home(self) -> None:
+        """Return to the ASCII-logo splash above the current mode."""
+        if isinstance(self.screen, SplashScreen):
+            return
+        if isinstance(self.screen, BootScreen):
+            return
+        while len(self.screen_stack) > 1:
+            self.pop_screen()
+        self.push_screen(SplashScreen())
+
+    def enter_from_splash(self) -> None:
+        """Dismiss splash and open the boot loader."""
+        if isinstance(self.screen, SplashScreen):
+            self.pop_screen()
+        self.push_screen(BootScreen())
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    """CLI flags for data source selection."""
+    parser = argparse.ArgumentParser(description="BitCraft terminal interface")
+    parser.add_argument(
+        "--demo",
+        action="store_true",
+        help="Force the deterministic demo provider",
+    )
+    parser.add_argument(
+        "--api",
+        action="store_true",
+        help="Force the FastAPI provider",
+    )
+    parser.add_argument(
+        "--api-url",
+        default=os.environ.get("BITCRAFT_API_URL", DEFAULT_BASE_URL),
+        help=f"Backend base URL (default {DEFAULT_BASE_URL})",
+    )
+    return parser
+
+
+def main(argv: Optional[list[str]] = None) -> None:
+    """Run the BitCraft terminal interface."""
+    args = build_arg_parser().parse_args(argv)
+    source = resolve_source(cli_demo=args.demo, cli_api=args.api)
+    choice = create_provider(source=source, api_url=args.api_url)
+    store = Store(
+        provider=choice.provider,
+        boot_log=list(choice.boot_log),
+        is_demo=(choice.provider.source_label == "DEMO DATA"),
+        fast_boot=False,
+    )
+    app = BitCraftApp(store=store)
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

bitcraft/cli.py

@@ -0,0 +1,132 @@
+"""The `bitcraft` command.
+
+    bitcraft                      open BitCraft in a new, large window
+    bitcraft run [options]        same, with options
+    bitcraft demo                 new window with built-in demo data
+    bitcraft here [options]       run inside the current terminal
+    bitcraft status               check the API and the last pipeline run
+    bitcraft version              print the version
+
+Options for run / here:
+    --demo | --api                force a data source (default: auto)
+    --api-url URL                 backend to use (default http://localhost:8000)
+    --size COLSxROWS              window size for run / demo (default 190x52)
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from bitcraft import __version__
+from bitcraft.api_client import DEFAULT_BASE_URL
+from bitcraft.launcher import DEFAULT_SIZE, Options, api_healthy, open_window, run_session
+
+COMMANDS = ("run", "demo", "here", "status", "version")
+
+
+def _size(text: str) -> tuple[int, int]:
+    try:
+        cols, rows = (int(v) for v in text.lower().split("x"))
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("size must look like 190x52") from exc
+    if cols < 100 or rows < 30:
+        raise argparse.ArgumentTypeError("BitCraft needs at least 100x30")
+    return cols, rows
+
+
+def _source_args(p: argparse.ArgumentParser) -> None:
+    group = p.add_mutually_exclusive_group()
+    group.add_argument("--demo", action="store_true", help="built-in demo data, no API")
+    group.add_argument("--api", action="store_true", help="require the API (no demo fallback)")
+    p.add_argument(
+        "--api-url",
+        default=os.environ.get("BITCRAFT_API_URL", DEFAULT_BASE_URL),
+        help=f"backend URL (default {DEFAULT_BASE_URL})",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="bitcraft",
+        description="BitCraft: Bitcoin transaction intelligence in your terminal.",
+        epilog="Run `bitcraft` with no arguments to open it in a new window.",
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"bitcraft {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    run = sub.add_parser("run", help="open in a new, large terminal window (default)")
+    _source_args(run)
+    run.add_argument("--size", type=_size, default=DEFAULT_SIZE, help="window size, e.g. 190x52")
+
+    demo = sub.add_parser("demo", help="open in a new window with demo data")
+    demo.add_argument("--size", type=_size, default=DEFAULT_SIZE, help="window size, e.g. 190x52")
+
+    here = sub.add_parser("here", help="run inside the current terminal")
+    _source_args(here)
+
+    status = sub.add_parser("status", help="check the API and the last pipeline run")
+    status.add_argument("--api-url", default=os.environ.get("BITCRAFT_API_URL", DEFAULT_BASE_URL))
+
+    sub.add_parser("version", help="print the version")
+    return parser
+
+
+def _options(args: argparse.Namespace) -> Options:
+    source = "demo" if getattr(args, "demo", False) else ("api" if getattr(args, "api", False) else "auto")
+    return Options(
+        source=source,
+        api_url=getattr(args, "api_url", DEFAULT_BASE_URL),
+        size=getattr(args, "size", DEFAULT_SIZE),
+    )
+
+
+def _launch(opts: Options) -> int:
+    try:
+        where = open_window(opts)
+    except Exception as exc:  # noqa: BLE001 - no GUI terminal: run right here
+        print(f"Could not open a new window ({exc}); starting here.")
+        return run_session(opts)
+    cols, rows = opts.size
+    print(f"BitCraft is opening in a new {where} window ({cols}x{rows}).")
+    return 0
+
+
+def _status(api_url: str) -> int:
+    print(f"bitcraft {__version__}")
+    if not api_healthy(api_url, timeout_s=1.5):
+        print(f"API      {api_url}  not reachable (BitCraft will use demo data)")
+        return 1
+    import httpx
+
+    stats = httpx.get(f"{api_url}/stats/summary", timeout=3).json()
+    pipeline = httpx.get(f"{api_url}/pipeline/status", timeout=3).json()
+    print(f"API      {api_url}  ok")
+    print(f"data     {stats['total_transactions']:,} transactions, {stats['total_alerts']:,} alerts")
+    finished = pipeline.get("finished_at") or "-"
+    print(f"pipeline {pipeline.get('status', 'unknown')} (finished {finished})")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    # Bare `bitcraft` (or `bitcraft --demo ...`) means `bitcraft run ...`.
+    if not argv or (argv[0] not in COMMANDS and argv[0] not in ("-h", "--help", "-V", "--version")):
+        argv.insert(0, "run")
+    args = build_parser().parse_args(argv)
+
+    if args.command == "version":
+        print(f"bitcraft {__version__}")
+        return 0
+    if args.command == "status":
+        return _status(args.api_url)
+    if args.command == "here":
+        return run_session(_options(args))
+    if args.command == "demo":
+        return _launch(Options(source="demo", size=args.size))
+    return _launch(_options(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bitcraft/helpers/__init__.py

@@ -0,0 +1 @@
+"""Pure, unit-testable TUI helpers."""

bitcraft/helpers/drivers.py

@@ -0,0 +1,37 @@
+"""Primary driver tags from weighted score contributions.
+
+Weights mirrored from ml/config.yaml (plans/plan.md section 7).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from bitcraft.providers.demo_provider import (
+    ANOMALY_WEIGHT,
+    COMMUNITY_WEIGHT,
+    MODEL_WEIGHT,
+    NETWORK_WEIGHT,
+)
+
+DriverTag = Literal["MODEL", "ANOMALY", "COMMUNITY", "NETWORK"]
+
+
+def weighted_parts(
+    anomaly: float, community: float, network: float, model: float | None = 0.0
+) -> dict[DriverTag, float]:
+    """Return weighted contribution of each composite component."""
+    return {
+        "MODEL": MODEL_WEIGHT * (model or 0.0),
+        "ANOMALY": ANOMALY_WEIGHT * anomaly,
+        "COMMUNITY": COMMUNITY_WEIGHT * community,
+        "NETWORK": NETWORK_WEIGHT * network,
+    }
+
+
+def primary_driver(
+    anomaly: float, community: float, network: float, model: float | None = 0.0
+) -> DriverTag:
+    """Component with the largest weighted contribution."""
+    parts = weighted_parts(anomaly, community, network, model)
+    return max(parts, key=parts.get)  # type: ignore[arg-type]

bitcraft/helpers/format.py

@@ -0,0 +1,43 @@
+"""Number, score bar, and glyph formatting helpers."""
+
+from __future__ import annotations
+
+import os
+
+
+def ascii_mode() -> bool:
+    """True when BITCRAFT_ASCII=1 forces plain ASCII glyphs."""
+    return os.environ.get("BITCRAFT_ASCII", "").strip() == "1"
+
+
+def format_int(n: int) -> str:
+    """Format an integer with thousands separators."""
+    return f"{n:,}"
+
+
+def format_pct(value: float, digits: int = 1) -> str:
+    """Format a percentage value."""
+    return f"{value:.{digits}f}%"
+
+
+def score_bar(score: float, width: int = 10) -> str:
+    """Render a composite score as a filled bar like #######---."""
+    score = max(0.0, min(1.0, score))
+    filled = int(round(score * width))
+    fill = "#" if ascii_mode() else "#"
+    empty = "-"
+    return fill * filled + empty * (width - filled)
+
+
+def network_cell(has_network: bool, signal: float) -> str:
+    """Render network signal: n/a when missing, else ~0.42 modeled."""
+    if not has_network:
+        return "n/a"
+    return f"~{signal:.2f}"
+
+
+def modeled_mark(text: str) -> str:
+    """Prefix modeled values with the ~ glyph."""
+    if text.startswith("~"):
+        return text
+    return f"~{text}"

bitcraft/helpers/severity.py

@@ -0,0 +1,32 @@
+"""Display-only severity tiers derived from composite_score.
+
+These thresholds are not model outputs. They should eventually be tuned
+against precision@k from ml/config.yaml (see plans/future.md).
+"""
+
+from __future__ import annotations
+
+from bitcraft.providers.models import SeverityTier
+
+# Display thresholds only. Not used by the ML pipeline.
+SEVERITY_THRESHOLDS: tuple[tuple[SeverityTier, float], ...] = (
+    ("critical", 0.80),
+    ("high", 0.60),
+    ("medium", 0.40),
+    ("low", 0.0),
+)
+
+SEVERITY_STYLE: dict[SeverityTier, str] = {
+    "critical": "alert-high",
+    "high": "alert-high",
+    "medium": "alert-medium",
+    "low": "alert-low",
+}
+
+
+def severity_for_score(composite_score: float) -> SeverityTier:
+    """Map a composite score to a display severity tier."""
+    for tier, floor in SEVERITY_THRESHOLDS:
+        if composite_score >= floor:
+            return tier
+    return "low"