Add crypto news digest tab and refine bubble scaling

README.md

@@ -11,3 +11,14 @@ license: apache-2.0
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## Repository layout
+
+The prototype is now organized into lightweight layers to keep responsibilities clear even in a demo setting:
+
+- `application/` – orchestration services that combine prompts with infrastructure adapters.
+- `infrastructure/` – clients for external APIs and market data providers (Featherless, Coinlore, etc.).
+- `presentation/` – Gradio components, dashboards, and CSS themes displayed in the Space UI.
+- `domain/` – placeholder for future data models specific to the investment analytics domain.
+
+`app.py` wires these pieces together to expose the multi-tab Gradio experience on Hugging Face Spaces.

app.py

@@ -1,11 +1,20 @@
 import gradio as gr
-from services.llm_client import llm_service
-from core.analyzer import PortfolioAnalyzer
-from core.comparer import PortfolioComparer
-from core.chat import ChatAssistant
-from core.metrics import show_metrics_table
-from core.crypto_dashboard import build_crypto_dashboard  # Plotly dashboard + KPI-line
-from core.visual_comparison import build_price_chart, build_volatility_chart  # Interactive pair comparison
+
+from application.chat_assistant import ChatAssistant
+from application.metrics_table import show_metrics_table
+from application.portfolio_analyzer import PortfolioAnalyzer
+from application.portfolio_comparer import PortfolioComparer
+from infrastructure.llm_client import llm_service
+from core.news_digest import fetch_crypto_news, summarize_news
+from presentation.components.crypto_dashboard import (
+    build_crypto_dashboard,
+)  # Plotly dashboard + KPI-line
+from presentation.components.comparison_table import show_comparison_table
+from presentation.components.visual_comparison import (
+    build_comparison_chart,
+    build_volatility_chart,
+    preload_pairs,
+)  # Interactive pair comparison
 
 # === CSS loader ===
 def load_css(path: str) -> str:
@@ -13,8 +22,8 @@ def load_css(path: str) -> str:
         return f.read()
 
 # === Styles ===
-base_css   = load_css("core/styles/base.css")
-crypto_css = load_css("core/styles/crypto_dashboard.css")
+base_css = load_css("presentation/styles/themes/base.css")
+crypto_css = load_css("presentation/styles/themes/crypto_dashboard.css")
 
 # === Model setup ===
 MODEL_NAME = "meta-llama/Meta-Llama-3.1-8B-Instruct"
@@ -39,65 +48,164 @@ with gr.Blocks(css=base_css) as demo:
                 value="b1ef37aa-5b9a-41b4-9394-8823f2de36bb",
             )
             analyze_btn = gr.Button("Run Analysis", variant="primary")
-            analyze_out = gr.Textbox(label="Analysis Result", lines=15, elem_id="analysis_output")
-            analyze_btn.click(fn=analyzer.run, inputs=portfolio_input, outputs=analyze_out)
+            analyze_out = gr.Textbox(
+                label="Analysis Result",
+                lines=15,
+                elem_id="analysis_output",
+                interactive=False,
+            )
+            analyze_btn.click(
+                fn=analyzer.run,
+                inputs=portfolio_input,
+                outputs=analyze_out,
+                show_progress="minimal",
+            )
 
         # --- Comparison Table ---
         with gr.TabItem("Comparison Table"):
-            from core.comparison_table import show_comparison_table
-            pid_a = gr.Textbox(label="Portfolio A", value="3852a354-e66e-4bc5-97e9-55124e31e687")
-            pid_b = gr.Textbox(label="Portfolio B", value="b1ef37aa-5b9a-41b4-8823f2de36bb")
+            with gr.Row():
+                pid_a = gr.Textbox(
+                    label="Portfolio A",
+                    value="3852a354-e66e-4bc5-97e9-55124e31e687",
+                    scale=1,
+                )
+                pid_b = gr.Textbox(
+                    label="Portfolio B",
+                    value="b1ef37aa-5b9a-41b4-9394-8823f2de36bb",
+                    scale=1,
+                )
             compare_btn = gr.Button("Load Comparison", variant="primary")
-            comp_table = gr.Dataframe(label="Comparative Metrics", wrap=True)
-            comp_comment = gr.Textbox(label="AI Commentary", lines=14, elem_id="llm_comment_box")
-            compare_btn.click(fn=show_comparison_table, inputs=[pid_a, pid_b], outputs=[comp_table, comp_comment])
-
-        # --- Assistant ---
-        with gr.TabItem("Assistant"):
-            chat_in = gr.Textbox(label="Ask about investments or analysis")
-            chat_btn = gr.Button("Send Question", variant="primary")
-            chat_out = gr.Textbox(label="AI Response", lines=8)
-            chat_btn.click(fn=chatbot.run, inputs=chat_in, outputs=chat_out)
+            comp_table = gr.Dataframe(
+                label="Comparative Metrics",
+                wrap=True,
+                elem_id="comparison_table",
+            )
+            comp_comment = gr.Textbox(
+                label="AI Commentary",
+                lines=14,
+                elem_id="llm_comment_box",
+                interactive=False,
+            )
+            compare_btn.click(
+                fn=show_comparison_table,
+                inputs=[pid_a, pid_b],
+                outputs=[comp_table, comp_comment],
+                show_progress="minimal",
+            )
 
         # --- Metrics Table ---
         with gr.TabItem("Metrics Table"):
-            metrics_in = gr.Textbox(label="Portfolio ID", value="b1ef37aa-5b9a-41b4-9394-8823f2de36bb")
+            metrics_in = gr.Textbox(
+                label="Portfolio ID",
+                value="b1ef37aa-5b9a-41b4-9394-8823f2de36bb",
+            )
             metrics_btn = gr.Button("Load Metrics", variant="primary")
             metrics_out = gr.Dataframe(label="Portfolio Metrics", wrap=True)
             metrics_btn.click(fn=show_metrics_table, inputs=metrics_in, outputs=metrics_out)
 
+        # --- Assistant ---
+        with gr.TabItem("Assistant"):
+            chat_in = gr.Textbox(label="Ask about investments or analysis")
+            chat_btn = gr.Button("Send Question", variant="primary")
+            chat_out = gr.Textbox(label="AI Response", lines=8, interactive=False)
+            chat_btn.click(
+                fn=chatbot.run,
+                inputs=chat_in,
+                outputs=chat_out,
+                show_progress="minimal",
+            )
+
+        # --- Crypto News Digest ---
+        with gr.TabItem("Crypto News Digest"):
+            gr.Markdown("### 🗞️ Latest Crypto News (via NewsData.io)")
+            headlines_box = gr.Markdown("Fetching latest headlines...", elem_id="news_headlines")
+            ai_summary_box = gr.Textbox(
+                label="AI Market Summary",
+                lines=10,
+                interactive=False,
+            )
+            refresh_btn = gr.Button("🔄 Refresh News", variant="primary")
+
+            def run_news():
+                headlines, ok = fetch_crypto_news()
+                if not ok:
+                    return headlines, "⚠️ Summary will appear once fresh headlines are available."
+                summary = summarize_news(headlines)
+                return headlines, summary
+
+            refresh_btn.click(
+                fn=run_news,
+                inputs=None,
+                outputs=[headlines_box, ai_summary_box],
+                show_progress="minimal",
+            )
+            demo.load(
+                fn=run_news,
+                inputs=None,
+                outputs=[headlines_box, ai_summary_box],
+            )
+
         # --- Visual Comparison (Interactive Plotly Edition) ---
         with gr.TabItem("Visual Comparison"):
             gr.Markdown("### 📊 Market Pair Comparison — Interactive Plotly Edition")
 
             available_pairs = [
                 ("bitcoin", "ethereum"),
-                ("bitcoin", "solana"),
                 ("ethereum", "bnb"),
-                ("solana", "dogecoin"),
-                ("bitcoin", "toncoin"),
+                ("solana", "avalanche-2"),
+                ("litecoin", "bitcoin-cash"),
+                ("dogecoin", "shiba-inu"),
             ]
 
-            pair_selector = gr.Dropdown(
-                label="Select Pair for Comparison",
-                choices=[f"{a.capitalize()} vs {b.capitalize()}" for a, b in available_pairs],
-                value="Bitcoin vs Ethereum",
-                interactive=True,
-            )
+            def _format_pair(pair: tuple[str, str]) -> str:
+                def _label(asset: str) -> str:
+                    return asset.replace("-", " ").title()
+
+                a, b = pair
+                return f"{_label(a)} vs {_label(b)}"
+
+            pair_map = {_format_pair(pair): pair for pair in available_pairs}
+            default_label = _format_pair(available_pairs[0])
+
+            with gr.Row():
+                pair_selector = gr.Dropdown(
+                    label="Select Pair for Comparison",
+                    choices=list(pair_map.keys()),
+                    value=default_label,
+                    interactive=True,
+                    scale=3,
+                )
+                normalize_toggle = gr.Checkbox(
+                    label="Normalized Mode (%)",
+                    value=False,
+                    interactive=True,
+                    scale=1,
+                )
 
             price_plot = gr.Plot(label="Price Comparison")
             vol_plot = gr.Plot(label="Volatility Comparison")
 
-            def update_visuals(selected_pair: str):
-                for a, b in available_pairs:
-                    if selected_pair.lower() == f"{a} vs {b}":
-                        return build_price_chart((a, b)), build_volatility_chart((a, b))
-                return build_price_chart(("bitcoin", "ethereum")), build_volatility_chart(("bitcoin", "ethereum"))
+            def update_visuals(selected_pair: str, normalized: bool):
+                pair = pair_map.get(selected_pair, available_pairs[0])
+                return (
+                    build_comparison_chart(pair, normalized=normalized),
+                    build_volatility_chart(pair),
+                )
 
-            pair_selector.change(fn=update_visuals, inputs=pair_selector, outputs=[price_plot, vol_plot])
+            pair_selector.change(
+                fn=update_visuals,
+                inputs=[pair_selector, normalize_toggle],
+                outputs=[price_plot, vol_plot],
+            )
+            normalize_toggle.change(
+                fn=update_visuals,
+                inputs=[pair_selector, normalize_toggle],
+                outputs=[price_plot, vol_plot],
+            )
 
             def init_visuals():
-                return update_visuals("Bitcoin vs Ethereum")
+                preload_pairs(available_pairs)
+                return update_visuals(default_label, False)
 
             demo.load(fn=init_visuals, inputs=None, outputs=[price_plot, vol_plot])
 

application/__init__.py

@@ -0,0 +1,13 @@
+"""Application layer services orchestrating domain and infrastructure."""
+
+from .chat_assistant import ChatAssistant
+from .metrics_table import show_metrics_table
+from .portfolio_analyzer import PortfolioAnalyzer
+from .portfolio_comparer import PortfolioComparer
+
+__all__ = [
+    "ChatAssistant",
+    "PortfolioAnalyzer",
+    "PortfolioComparer",
+    "show_metrics_table",
+]

core/chat.py → application/chat_assistant.py

@@ -7,7 +7,8 @@ Purpose: General chat interface for user questions about investments or portfoli
 """
 
 from typing import Generator
-from services.llm_client import llm_service
+
+from infrastructure.llm_client import llm_service
 from prompts.system_prompts import GENERAL_CONTEXT
 
 
@@ -20,16 +21,21 @@ class ChatAssistant:
 
     def run(self, user_input: str) -> Generator[str, None, None]:
         """Stream chat responses."""
+        if not user_input or not user_input.strip():
+            yield "❗ Please enter a question for the assistant."
+            return
+
+        yield "⏳ Working..."
+        partial = ""
         messages = [
             {"role": "system", "content": GENERAL_CONTEXT},
             {"role": "user", "content": user_input},
         ]
 
         try:
-            partial = ""
             for delta in self.llm.stream_chat(messages=messages, model=self.model_name):
                 partial += delta
                 yield partial
 
-        except Exception as e:
-            yield f"❌ Ошибка при генерации ответа: {e}"
+        except Exception:
+            yield "❌ Assistant is unavailable right now. Please try again later."

core/metrics.py → application/metrics_table.py

@@ -7,28 +7,36 @@ Purpose: Provides async utilities to fetch and display portfolio metrics as a Da
 """
 
 import pandas as pd
-import asyncio
-from services.output_api import extract_portfolio_id, fetch_metrics_async
+
+from infrastructure.cache import CacheUnavailableError
+from infrastructure.output_api import extract_portfolio_id, fetch_metrics_cached
 
 
 def show_metrics_table(portfolio_input: str):
     """Fetch portfolio metrics and return them as a DataFrame for Gradio."""
     pid = extract_portfolio_id(portfolio_input)
     if not pid:
-        return "❌ Invalid portfolioId format."
+        return _message_df("❌ Invalid portfolioId format.")
 
     try:
-        df = asyncio.run(_get_metrics_df(pid))
+        df = _get_metrics_df(pid)
         return df
-    except Exception as e:
-        return f"❌ Error fetching metrics: {e}"
+    except CacheUnavailableError as e:
+        wait = int(e.retry_in) + 1
+        return _message_df(f"⚠️ Metrics API cooling down. Retry in ~{wait} seconds.")
+    except Exception:
+        return _message_df("❌ Error fetching metrics. Please try again later.")
 
 
-async def _get_metrics_df(portfolio_id: str) -> pd.DataFrame:
-    """Internal helper to asynchronously get metrics."""
-    metrics = await fetch_metrics_async(portfolio_id)
+def _get_metrics_df(portfolio_id: str) -> pd.DataFrame:
+    """Internal helper to get metrics with caching."""
+    metrics = fetch_metrics_cached(portfolio_id)
     if not metrics:
         raise ValueError("No metrics found for given portfolio.")
 
     df = pd.DataFrame(list(metrics.items()), columns=["Metric", "Value"])
     return df
+
+
+def _message_df(message: str) -> pd.DataFrame:
+    return pd.DataFrame({"Message": [message]})

core/analyzer.py → application/portfolio_analyzer.py

@@ -6,10 +6,11 @@ Purpose: Handles single-portfolio analysis using LLM. Fetches metrics, builds pr
 Назначение: анализ одного инвестиционного портфеля с использованием LLM. Получает метрики, формирует промпт, возвращает потоковый ответ.
 """
 
-import asyncio
 from typing import Generator
-from services.output_api import extract_portfolio_id, fetch_metrics_async
-from services.llm_client import llm_service
+
+from infrastructure.cache import CacheUnavailableError
+from infrastructure.output_api import extract_portfolio_id, fetch_metrics_cached
+from infrastructure.llm_client import llm_service
 from prompts.system_prompts import ANALYSIS_SYSTEM_PROMPT
 from prompts.reference_templates import REFERENCE_PROMPT
 
@@ -30,9 +31,13 @@ class PortfolioAnalyzer:
 
         yield "⏳ Working..."
         try:
-            metrics = asyncio.run(fetch_metrics_async(portfolio_id))
-        except Exception as e:
-            yield f"❌ Fail to collect metrics: {e}"
+            metrics = fetch_metrics_cached(portfolio_id)
+        except CacheUnavailableError as e:
+            wait = int(e.retry_in) + 1
+            yield f"⚠️ API temporarily unavailable. Please retry in ~{wait} seconds."
+            return
+        except Exception:
+            yield "❌ Failed to collect metrics. Please try again later."
             return
 
         if not metrics:
@@ -53,5 +58,5 @@ class PortfolioAnalyzer:
                 partial += delta
                 yield partial
 
-        except Exception as e:
-            yield f"❌ LLM's error: {e}"
+        except Exception:
+            yield "❌ LLM is unavailable right now. Please try again later."

core/comparer.py → application/portfolio_comparer.py

@@ -6,10 +6,11 @@ Purpose: Compares two portfolios using LLM. Fetches metrics for both and builds
 Назначение: сравнение двух инвестиционных портфелей с помощью LLM. Получает метрики обоих портфелей, формирует промпт и возвращает потоковый результат.
 """
 
-import asyncio
 from typing import Generator
-from services.output_api import extract_portfolio_id, fetch_metrics_async
-from services.llm_client import llm_service
+
+from infrastructure.cache import CacheUnavailableError
+from infrastructure.output_api import extract_portfolio_id, fetch_metrics_cached
+from infrastructure.llm_client import llm_service
 from prompts.system_prompts import COMPARISON_SYSTEM_PROMPT
 from prompts.reference_templates import REFERENCE_COMPARISON_PROMPT
 
@@ -35,10 +36,14 @@ class PortfolioComparer:
 
         yield "⏳ Working..."
         try:
-            m1 = asyncio.run(fetch_metrics_async(id1))
-            m2 = asyncio.run(fetch_metrics_async(id2))
-        except Exception as e:
-            yield f"❌ There are issue via collecting data: {e}"
+            m1 = fetch_metrics_cached(id1)
+            m2 = fetch_metrics_cached(id2)
+        except CacheUnavailableError as e:
+            wait = int(e.retry_in) + 1
+            yield f"⚠️ API temporarily unavailable. Retry in ~{wait} seconds."
+            return
+        except Exception:
+            yield "❌ Failed to collect comparison data. Please try again later."
             return
 
         if not m1 or not m2:
@@ -66,5 +71,5 @@ class PortfolioComparer:
                 partial += delta
                 yield partial
 
-        except Exception as e:
-            yield f"❌ Ошибка при сравнении портфелей через LLM: {e}"
+        except Exception:
+            yield "❌ LLM comparison is unavailable right now. Please try again later."

config.py

@@ -14,7 +14,12 @@ FEATHERLESS_MODEL = "meta-llama/Meta-Llama-3.1-8B-Instruct"
 
 # === External API Configuration ===
 EXTERNAL_API_URL = os.getenv("EXTERNAL_API_URL")
+NEWSDATA_API_KEY = os.getenv("NEWSDATA_API_KEY")
 
 # === Request / Connection Settings ===
 REQUEST_TIMEOUT = 15
 DEBUG = os.getenv("DEBUG", "false").lower() == "true"
+
+# === Caching Settings ===
+CACHE_TTL_SECONDS = int(os.getenv("CACHE_TTL_SECONDS", "600"))  # 10 minutes
+CACHE_RETRY_SECONDS = int(os.getenv("CACHE_RETRY_SECONDS", "30"))  # cooldown after failures

core/__init__.py

@@ -1,2 +1,13 @@
-# __init__.py
-# Marks this directory as a Python package.
+"""Legacy compatibility layer bridging old imports to the new structure."""
+
+from application.chat_assistant import ChatAssistant
+from application.metrics_table import show_metrics_table
+from application.portfolio_analyzer import PortfolioAnalyzer
+from application.portfolio_comparer import PortfolioComparer
+
+__all__ = [
+    "ChatAssistant",
+    "PortfolioAnalyzer",
+    "PortfolioComparer",
+    "show_metrics_table",
+]

core/comparison_table.py

@@ -1,70 +0,0 @@
-"""
-🇬🇧 Module: comparison_table.py
-Purpose: Generates comparative DataFrame for two portfolios and an LLM commentary.
-
-🇷🇺 Модуль: comparison_table.py
-Назначение: создаёт сравнительную таблицу метрик двух портфелей и комментарий LLM.
-"""
-
-import pandas as pd
-import asyncio
-from services.output_api import fetch_metrics_async, extract_portfolio_id
-from services.llm_client import llm_service
-from prompts.system_prompts import COMPARISON_SYSTEM_PROMPT
-
-
-def show_comparison_table(portfolio_a: str, portfolio_b: str):
-    """Public Gradio entry: returns both a DataFrame and LLM commentary."""
-    pid_a = extract_portfolio_id(portfolio_a)
-    pid_b = extract_portfolio_id(portfolio_b)
-    if not pid_a or not pid_b:
-        return "❌ Invalid portfolio IDs.", "No commentary available."
-
-    try:
-        df, commentary = asyncio.run(_build_comparison_with_comment(pid_a, pid_b))
-        return df, commentary
-    except Exception as e:
-        return f"❌ Error building comparison table: {e}", "❌ LLM analysis failed."
-
-
-async def _build_comparison_with_comment(p1: str, p2: str):
-    """Async helper: builds table and gets commentary."""
-    m1 = await fetch_metrics_async(p1)
-    m2 = await fetch_metrics_async(p2)
-    if not m1 or not m2:
-        raise ValueError("Metrics unavailable for one or both portfolios.")
-
-    all_keys = sorted(set(m1.keys()) | set(m2.keys()))
-    rows = []
-    for k in all_keys:
-        v1 = m1.get(k, 0)
-        v2 = m2.get(k, 0)
-        diff = v1 - v2
-        symbol = "▲" if diff > 0 else "▼" if diff < 0 else "—"
-        rows.append({
-            "Metric": k,
-            "Portfolio A": round(v1, 3),
-            "Portfolio B": round(v2, 3),
-            "Δ Difference": f"{symbol} {diff:+.3f}"
-        })
-    df = pd.DataFrame(rows, columns=["Metric", "Portfolio A", "Portfolio B", "Δ Difference"])
-
-    # Generate LLM commentary
-    summary = "\n".join(f"{r['Metric']}: {r['Δ Difference']}" for r in rows)
-    prompt = (
-        f"{COMPARISON_SYSTEM_PROMPT}\n"
-        f"Compare and explain the differences between Portfolio A and B:\n{summary}\n"
-        f"Write your insights as a concise professional commentary."
-    )
-
-    commentary = ""
-    for delta in llm_service.stream_chat(
-        messages=[
-            {"role": "system", "content": "You are an investment portfolio analyst."},
-            {"role": "user", "content": prompt},
-        ],
-        model="meta-llama/Meta-Llama-3.1-8B-Instruct",
-    ):
-        commentary += delta
-
-    return df, commentary

core/news_digest.py

@@ -0,0 +1,114 @@
+"""Helpers for fetching crypto news and summarizing sentiment."""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import List, Tuple
+
+import requests
+
+from config import (
+    CACHE_RETRY_SECONDS,
+    CACHE_TTL_SECONDS,
+    NEWSDATA_API_KEY,
+    REQUEST_TIMEOUT,
+)
+from infrastructure.cache import CacheUnavailableError, TTLCache
+from infrastructure.llm_client import llm_service
+
+
+_news_cache: TTLCache[List[dict]] = TTLCache(CACHE_TTL_SECONDS, CACHE_RETRY_SECONDS)
+
+
+def _load_news_payload() -> List[dict]:
+    if not NEWSDATA_API_KEY:
+        raise CacheUnavailableError("News API key is missing.", CACHE_RETRY_SECONDS)
+
+    url = "https://newsdata.io/api/1/news"
+    params = {
+        "apikey": NEWSDATA_API_KEY,
+        "q": "crypto",
+        "language": "en",
+        "category": "business",
+    }
+
+    try:
+        response = requests.get(url, params=params, timeout=REQUEST_TIMEOUT)
+        response.raise_for_status()
+    except requests.RequestException as exc:  # noqa: PERF203 - surface API issues
+        raise CacheUnavailableError("News service request failed.", CACHE_RETRY_SECONDS) from exc
+
+    payload = response.json()
+    results = payload.get("results")
+    if not isinstance(results, list):
+        raise CacheUnavailableError("News service returned unexpected format.", CACHE_RETRY_SECONDS)
+
+    return results
+
+
+def _format_timestamp(value: str | None) -> str:
+    if not value:
+        return "Unknown time"
+    try:
+        parsed = dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
+        return parsed.strftime("%Y-%m-%d %H:%M UTC")
+    except ValueError:
+        return value
+
+
+def fetch_crypto_news() -> Tuple[str, bool]:
+    """Return Markdown-formatted headlines and success flag."""
+
+    try:
+        items = _news_cache.get("crypto_news", _load_news_payload)
+    except CacheUnavailableError as exc:
+        wait = int(exc.retry_in) + 1
+        return f"⚠️ News service cooling down. Retry in ~{wait} seconds.", False
+    except Exception:
+        return "❌ Failed to load crypto headlines. Please try again later.", False
+
+    lines = []
+    for idx, item in enumerate(items[:5]):
+        title = (item.get("title") or "Untitled headline").strip()
+        link = (item.get("link") or "").strip() or "#"
+        source = (item.get("source_id") or "Unknown source").strip()
+        timestamp = _format_timestamp(item.get("pubDate"))
+        lines.append(f"{idx + 1}. [{title}]({link}) — *{source}* ({timestamp})")
+
+    if not lines:
+        return "⚠️ No recent crypto headlines were returned.", False
+
+    return "\n".join(lines), True
+
+
+def summarize_news(headlines_text: str) -> str:
+    if not headlines_text.strip():
+        return "⚠️ No headlines available for summarization."
+
+    messages = [
+        {
+            "role": "system",
+            "content": (
+                "You are a crypto market strategist. Write a concise 4-5 sentence digest of the "
+                "current market tone using the provided headlines. Highlight catalysts, risks, "
+                "and cross-asset themes. Finish with a separate line in the format "
+                "'Market Tone: <emoji> <Bullish/Bearish/Neutral> — <one-sentence rationale>'."
+            ),
+        },
+        {
+            "role": "user",
+            "content": (
+                "Analyze these crypto news headlines and summarize market sentiment:\n"
+                f"{headlines_text}"
+            ),
+        },
+    ]
+
+    try:
+        chunks = []
+        for delta in llm_service.stream_chat(messages=messages):
+            chunks.append(delta)
+        summary = "".join(chunks).strip()
+        return summary or "⚠️ Summary is unavailable right now."
+    except Exception:
+        return "❌ Unable to summarize the news at the moment. Please try again later."

core/visual_comparison.py

@@ -1,94 +0,0 @@
-"""
-Module: visual_comparison.py
-Purpose: Interactive crypto pair comparison (Plotly + CoinGecko)
-"""
-
-import requests
-import pandas as pd
-import plotly.graph_objects as go
-
-COINGECKO_API = "https://api.coingecko.com/api/v3"
-
-
-def get_coin_history(coin_id: str, days: int = 180):
-    """Fetch historical market data for given coin from CoinGecko API."""
-    url = f"{COINGECKO_API}/coins/{coin_id}/market_chart?vs_currency=usd&days={days}"
-    r = requests.get(url)
-    r.raise_for_status()
-    data = r.json()
-    df = pd.DataFrame(data["prices"], columns=["timestamp", "price"])
-    df["timestamp"] = pd.to_datetime(df["timestamp"], unit="ms")
-    return df
-
-
-def build_price_chart(pair: tuple[str, str], days: int = 180):
-    """Build comparative price chart for selected pair."""
-    coin_a, coin_b = pair
-
-    df_a = get_coin_history(coin_a, days)
-    df_b = get_coin_history(coin_b, days)
-
-    fig = go.Figure()
-    fig.add_trace(go.Scatter(
-        x=df_a["timestamp"],
-        y=df_a["price"],
-        name=f"{coin_a.capitalize()} / USD",
-        line=dict(width=2),
-    ))
-    fig.add_trace(go.Scatter(
-        x=df_b["timestamp"],
-        y=df_b["price"],
-        name=f"{coin_b.capitalize()} / USD",
-        line=dict(width=2),
-    ))
-
-    fig.update_layout(
-        template="plotly_dark",
-        height=480,
-        margin=dict(l=40, r=20, t=30, b=40),
-        xaxis_title="Date",
-        yaxis_title="Price (USD)",
-        legend_title="Asset",
-        hovermode="x unified",
-    )
-
-    return fig
-
-
-def build_volatility_chart(pair: tuple[str, str], days: int = 180):
-    """Build comparative volatility chart for selected pair."""
-    coin_a, coin_b = pair
-
-    df_a = get_coin_history(coin_a, days)
-    df_b = get_coin_history(coin_b, days)
-
-    df_a["returns"] = df_a["price"].pct_change() * 100
-    df_b["returns"] = df_b["price"].pct_change() * 100
-
-    fig = go.Figure()
-    fig.add_trace(go.Scatter(
-        x=df_a["timestamp"],
-        y=df_a["returns"],
-        name=f"{coin_a.upper()} Daily Change (%)",
-        mode="lines",
-        line=dict(width=1.6),
-    ))
-    fig.add_trace(go.Scatter(
-        x=df_b["timestamp"],
-        y=df_b["returns"],
-        name=f"{coin_b.upper()} Daily Change (%)",
-        mode="lines",
-        line=dict(width=1.6),
-    ))
-
-    fig.update_layout(
-        template="plotly_dark",
-        height=400,
-        margin=dict(l=40, r=20, t=30, b=40),
-        xaxis_title="Date",
-        yaxis_title="Daily Change (%)",
-        legend_title="Volatility",
-        hovermode="x unified",
-    )
-
-    return fig

domain/__init__.py

@@ -0,0 +1,3 @@
+"""Domain layer placeholder for future data models in the prototype."""
+
+__all__: list[str] = []

infrastructure/__init__.py

@@ -0,0 +1,20 @@
+"""Infrastructure adapters for external services and data providers."""
+
+from . import market_data
+from .llm_client import FeatherlessLLM, llm_service
+from .output_api import (
+    extract_portfolio_id,
+    fetch_absolute_pnl_async,
+    fetch_metrics_async,
+    fetch_metrics_cached,
+)
+
+__all__ = [
+    "FeatherlessLLM",
+    "llm_service",
+    "extract_portfolio_id",
+    "fetch_absolute_pnl_async",
+    "fetch_metrics_async",
+    "fetch_metrics_cached",
+    "market_data",
+]

infrastructure/cache.py

@@ -0,0 +1,167 @@
+"""Utility caching primitives used across the demo application."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from threading import Lock
+from typing import Awaitable, Callable, Dict, Generic, Hashable, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+class CacheUnavailableError(RuntimeError):
+    """Raised when cached resource is temporarily unavailable."""
+
+    def __init__(self, message: str, retry_in: float):
+        super().__init__(message)
+        self.retry_in = max(retry_in, 0.0)
+
+
+@dataclass
+class _CacheRecord(Generic[T]):
+    value: Optional[T]
+    expires_at: float
+    error_until: float
+    error_message: Optional[str]
+
+
+class AsyncTTLCache(Generic[T]):
+    """Simple async-aware TTL cache with cooldown on failures."""
+
+    def __init__(self, ttl: float, retry_after: float):
+        self.ttl = ttl
+        self.retry_after = retry_after
+        self._store: Dict[Hashable, _CacheRecord[T]] = {}
+        self._locks: Dict[Hashable, asyncio.Lock] = {}
+        self._global_lock = asyncio.Lock()
+
+    async def get(self, key: Hashable, loader: Callable[[], Awaitable[T]]) -> T:
+        now = time.monotonic()
+        record = self._store.get(key)
+        if record:
+            if record.value is not None and now < record.expires_at:
+                return record.value
+            if record.error_message and now < record.error_until:
+                raise CacheUnavailableError(
+                    record.error_message,
+                    record.error_until - now,
+                )
+
+        lock = await self._get_lock(key)
+        async with lock:
+            now = time.monotonic()
+            record = self._store.get(key)
+            if record:
+                if record.value is not None and now < record.expires_at:
+                    return record.value
+                if record.error_message and now < record.error_until:
+                    raise CacheUnavailableError(
+                        record.error_message,
+                        record.error_until - now,
+                    )
+
+            try:
+                value = await loader()
+            except CacheUnavailableError as exc:
+                cooldown = max(exc.retry_in, self.retry_after)
+                message = str(exc) or "Resource unavailable"
+                self._store[key] = _CacheRecord(
+                    value=None,
+                    expires_at=0.0,
+                    error_until=now + cooldown,
+                    error_message=message,
+                )
+                raise CacheUnavailableError(message, cooldown) from exc
+            except Exception as exc:  # noqa: BLE001 - surface upstream
+                message = str(exc) or "Source request failed"
+                self._store[key] = _CacheRecord(
+                    value=None,
+                    expires_at=0.0,
+                    error_until=now + self.retry_after,
+                    error_message=message,
+                )
+                raise CacheUnavailableError(message, self.retry_after) from exc
+            else:
+                self._store[key] = _CacheRecord(
+                    value=value,
+                    expires_at=now + self.ttl,
+                    error_until=0.0,
+                    error_message=None,
+                )
+                return value
+
+    async def _get_lock(self, key: Hashable) -> asyncio.Lock:
+        lock = self._locks.get(key)
+        if lock is not None:
+            return lock
+        async with self._global_lock:
+            lock = self._locks.get(key)
+            if lock is None:
+                lock = asyncio.Lock()
+                self._locks[key] = lock
+            return lock
+
+
+class TTLCache(Generic[T]):
+    """Synchronous TTL cache with cooldown control."""
+
+    def __init__(self, ttl: float, retry_after: float):
+        self.ttl = ttl
+        self.retry_after = retry_after
+        self._store: Dict[Hashable, _CacheRecord[T]] = {}
+        self._lock = Lock()
+
+    def get(self, key: Hashable, loader: Callable[[], T]) -> T:
+        now = time.monotonic()
+        record = self._store.get(key)
+        if record:
+            if record.value is not None and now < record.expires_at:
+                return record.value
+            if record.error_message and now < record.error_until:
+                raise CacheUnavailableError(
+                    record.error_message,
+                    record.error_until - now,
+                )
+
+        with self._lock:
+            now = time.monotonic()
+            record = self._store.get(key)
+            if record:
+                if record.value is not None and now < record.expires_at:
+                    return record.value
+                if record.error_message and now < record.error_until:
+                    raise CacheUnavailableError(
+                        record.error_message,
+                        record.error_until - now,
+                    )
+            try:
+                value = loader()
+            except CacheUnavailableError as exc:
+                cooldown = max(exc.retry_in, self.retry_after)
+                message = str(exc) or "Resource unavailable"
+                self._store[key] = _CacheRecord(
+                    value=None,
+                    expires_at=0.0,
+                    error_until=now + cooldown,
+                    error_message=message,
+                )
+                raise CacheUnavailableError(message, cooldown) from exc
+            except Exception as exc:  # noqa: BLE001 - propagate for visibility
+                message = str(exc) or "Source request failed"
+                self._store[key] = _CacheRecord(
+                    value=None,
+                    expires_at=0.0,
+                    error_until=now + self.retry_after,
+                    error_message=message,
+                )
+                raise CacheUnavailableError(message, self.retry_after) from exc
+            else:
+                self._store[key] = _CacheRecord(
+                    value=value,
+                    expires_at=now + self.ttl,
+                    error_until=0.0,
+                    error_message=None,
+                )
+                return value

infrastructure/market_data/__init__.py

@@ -0,0 +1,5 @@
+"""Market data providers used across the prototype."""
+
+from . import binance, coinlore, yfinance
+
+__all__ = ["binance", "coinlore", "yfinance"]

{services → infrastructure}/output_api.py

@@ -1,17 +1,17 @@
-"""
-🇬🇧 Module: api_client.py
-Purpose: Provides async API client for external portfolio analytics service.
-Handles fetching metrics, alphaBTC data, and other portfolio information.
-
-🇷🇺 Модуль: api_client.py
-Назначение: асинхронный клиент для внешнего API аналитики портфелей,
-выполняющий запросы к метрикам, данным alphaBTC и другой информации о портфелях.
-"""
+"""Client helpers for the external portfolio analytics API."""
 
 import re
-import httpx
 from typing import Any, Dict, List, Optional
-from config import EXTERNAL_API_URL, REQUEST_TIMEOUT, DEBUG
+
+import httpx
+from config import (
+    CACHE_RETRY_SECONDS,
+    CACHE_TTL_SECONDS,
+    DEBUG,
+    EXTERNAL_API_URL,
+    REQUEST_TIMEOUT,
+)
+from infrastructure.cache import CacheUnavailableError, TTLCache
 
 # === UUID detection ===
 UUID_PATTERN = re.compile(
@@ -36,20 +36,24 @@ async def _get_json(url: str) -> Dict[str, Any]:
         return r.json()
 
 
+def _parse_metrics(payload: Dict[str, Any]) -> Dict[str, Any]:
+    extended = payload.get("data", {}).get("extended", {})
+    result: Dict[str, Any] = {}
+    for k, v in extended.items():
+        if isinstance(v, (int, float)):
+            if k in {"cagr", "alphaRatio", "volatility", "maxDD"}:
+                result[k] = v * 100
+            else:
+                result[k] = v
+    return result
+
+
 async def fetch_metrics_async(portfolio_id: str) -> Optional[Dict[str, Any]]:
-    """Fetch portfolio metrics (extended data)."""
+    """Fetch portfolio metrics (extended data) asynchronously."""
     url = f"{EXTERNAL_API_URL}/portfolio/get?portfolioId={portfolio_id}&extended=1"
     try:
         data = await _get_json(url)
-        extended = data.get("data", {}).get("extended", {})
-        result = {}
-        for k, v in extended.items():
-            if isinstance(v, (int, float)):
-                # Convert some fields to percentages for readability
-                if k in {"cagr", "alphaRatio", "volatility", "maxDD"}:
-                    result[k] = v * 100
-                else:
-                    result[k] = v
+        result = _parse_metrics(data)
         if DEBUG:
             print(f"[DEBUG] Metrics fetched for {portfolio_id}: {result}")
         return result
@@ -59,6 +63,50 @@ async def fetch_metrics_async(portfolio_id: str) -> Optional[Dict[str, Any]]:
         return None
 
 
+def _get_json_sync(url: str) -> Dict[str, Any]:
+    """Synchronous helper mirroring :func:`_get_json`."""
+    if DEBUG:
+        print(f"[DEBUG] Requesting URL (sync): {url}")
+
+    with httpx.Client(timeout=REQUEST_TIMEOUT) as client:
+        r = client.get(url, headers={"User-Agent": "Mozilla/5.0", "Accept": "application/json"})
+        r.raise_for_status()
+        return r.json()
+
+
+def fetch_metrics(portfolio_id: str) -> Optional[Dict[str, Any]]:
+    """Synchronous helper to fetch metrics for caching loaders."""
+    url = f"{EXTERNAL_API_URL}/portfolio/get?portfolioId={portfolio_id}&extended=1"
+    try:
+        data = _get_json_sync(url)
+        result = _parse_metrics(data)
+        if DEBUG:
+            print(f"[DEBUG] Metrics fetched (sync) for {portfolio_id}: {result}")
+        return result
+    except Exception as e:
+        if DEBUG:
+            print(f"[ERROR] fetch_metrics: {e}")
+        return None
+
+
+_metrics_cache = TTLCache(CACHE_TTL_SECONDS, CACHE_RETRY_SECONDS)
+
+
+def fetch_metrics_cached(portfolio_id: str) -> Dict[str, Any]:
+    """Cached variant with cooldown on upstream failures."""
+
+    def _loader() -> Dict[str, Any]:
+        data = fetch_metrics(portfolio_id)
+        if not data:
+            raise CacheUnavailableError(
+                "Metrics temporarily unavailable from upstream API.",
+                CACHE_RETRY_SECONDS,
+            )
+        return data
+
+    return _metrics_cache.get(portfolio_id, _loader)
+
+
 async def fetch_absolute_pnl_async(portfolio_id: str) -> Optional[List[Dict[str, Any]]]:
     """Fetch absolutePnL daily data."""
     url = f"{EXTERNAL_API_URL}/portfolio/get?portfolioId={portfolio_id}&extended=1&step=day"

presentation/__init__.py

@@ -0,0 +1,5 @@
+"""Presentation layer: UI components, charts, and styles."""
+
+from . import components, styles
+
+__all__ = ["components", "styles"]

presentation/components/__init__.py

@@ -0,0 +1,17 @@
+"""Individual UI components used by the Gradio interface."""
+
+from .comparison_table import show_comparison_table
+from .crypto_dashboard import build_crypto_dashboard
+from .visual_comparison import (
+    build_comparison_chart,
+    build_price_chart,
+    build_volatility_chart,
+)
+
+__all__ = [
+    "show_comparison_table",
+    "build_crypto_dashboard",
+    "build_comparison_chart",
+    "build_price_chart",
+    "build_volatility_chart",
+]

presentation/components/comparison_table.py

@@ -0,0 +1,97 @@
+"""Generate comparative tables and commentary for two portfolios."""
+
+from typing import Dict, List
+
+import pandas as pd
+
+from infrastructure.cache import CacheUnavailableError
+from infrastructure.llm_client import llm_service
+from infrastructure.output_api import extract_portfolio_id, fetch_metrics_cached
+from prompts.system_prompts import COMPARISON_SYSTEM_PROMPT
+
+
+def show_comparison_table(portfolio_a: str, portfolio_b: str):
+    """Return the comparison DataFrame along with commentary."""
+
+    pid_a = extract_portfolio_id(portfolio_a)
+    pid_b = extract_portfolio_id(portfolio_b)
+    if not pid_a or not pid_b:
+        message = "❌ Invalid portfolio IDs."
+        return _message_df(message), message
+
+    try:
+        df, commentary = _build_comparison_with_comment(pid_a, pid_b)
+        return df, commentary
+    except CacheUnavailableError as e:
+        wait = int(e.retry_in) + 1
+        message = f"⚠️ Metrics temporarily unavailable. Retry in ~{wait} seconds."
+        return _message_df(message), message
+    except Exception:
+        message = "❌ Unable to build comparison right now. Please try again later."
+        return _message_df(message), message
+
+
+def _build_comparison_with_comment(p1: str, p2: str):
+    m1 = fetch_metrics_cached(p1)
+    m2 = fetch_metrics_cached(p2)
+    if not m1 or not m2:
+        raise ValueError("Metrics unavailable for one or both portfolios.")
+
+    rows = _rows_from_metrics(m1, m2)
+    df = pd.DataFrame(rows, columns=["Δ Difference", "Portfolio A", "Portfolio B", "Metric"])
+    commentary = _collect_commentary(rows)
+    return df, commentary
+
+
+def _rows_from_metrics(m1: Dict, m2: Dict) -> List[Dict]:
+    all_keys = sorted(set(m1.keys()) | set(m2.keys()))
+    rows: List[Dict] = []
+    for k in all_keys:
+        v1 = m1.get(k, 0)
+        v2 = m2.get(k, 0)
+        diff = v1 - v2
+        symbol = "▲" if diff > 0 else "▼" if diff < 0 else "—"
+        rows.append(
+            {
+                "Δ Difference": f"{symbol} {diff:+.3f}",
+                "Portfolio A": round(v1, 3),
+                "Portfolio B": round(v2, 3),
+                "Metric": k,
+            }
+        )
+    return rows
+
+
+def _message_df(message: str) -> pd.DataFrame:
+    return pd.DataFrame({"Message": [message]})
+
+
+def _collect_commentary(rows: List[Dict]) -> str:
+    commentary = ""
+    for partial in _commentary_stream(rows):
+        commentary = partial
+    return commentary
+
+
+def _commentary_stream(rows: List[Dict]):
+    summary = "\n".join(f"{r['Metric']}: {r['Δ Difference']}" for r in rows)
+    prompt = (
+        f"{COMPARISON_SYSTEM_PROMPT}\n"
+        f"Compare and explain the differences between Portfolio A and B:\n{summary}\n"
+        f"Write your insights as a concise professional commentary."
+    )
+
+    partial = ""
+    try:
+        iterator = llm_service.stream_chat(
+            messages=[
+                {"role": "system", "content": "You are an investment portfolio analyst."},
+                {"role": "user", "content": prompt},
+            ],
+            model="meta-llama/Meta-Llama-3.1-8B-Instruct",
+        )
+        for delta in iterator:
+            partial += delta
+            yield partial
+    except Exception:
+        yield "❌ LLM analysis is unavailable right now. Please try again later."

{core → presentation/components}/crypto_dashboard.py

@@ -5,19 +5,58 @@ Crypto Dashboard — Plotly Edition (clean layout)
 • без глобального Markdown-заголовка
 """
 import requests
+
+import numpy as np
 import pandas as pd
 import plotly.express as px
-from services.llm_client import llm_service
+import plotly.graph_objects as go
+
+from config import CACHE_RETRY_SECONDS, CACHE_TTL_SECONDS
+from infrastructure.cache import CacheUnavailableError, TTLCache
+from infrastructure.llm_client import llm_service
+
+
+_coinlore_cache = TTLCache(CACHE_TTL_SECONDS, CACHE_RETRY_SECONDS)
 
 
-def fetch_coinlore_data(limit=100):
+def _load_coinlore() -> pd.DataFrame:
     url = "https://api.coinlore.net/api/tickers/"
-    data = requests.get(url).json()["data"]
+    try:
+        response = requests.get(url, timeout=20)
+        response.raise_for_status()
+        payload = response.json()
+        data = payload.get("data")
+        if not isinstance(data, list):
+            raise ValueError("Unexpected Coinlore payload structure")
+    except requests.RequestException as exc:  # noqa: PERF203 - propagate meaningful message
+        raise CacheUnavailableError(
+            "Coinlore API request failed.",
+            CACHE_RETRY_SECONDS,
+        ) from exc
+    except ValueError as exc:
+        raise CacheUnavailableError(
+            "Coinlore API returned unexpected response.",
+            CACHE_RETRY_SECONDS,
+        ) from exc
+
     df = pd.DataFrame(data)
-    for col in ["price_usd", "market_cap_usd", "volume24",
-                "percent_change_1h", "percent_change_24h", "percent_change_7d"]:
+    for col in [
+        "price_usd",
+        "market_cap_usd",
+        "volume24",
+        "percent_change_1h",
+        "percent_change_24h",
+        "percent_change_7d",
+    ]:
         df[col] = pd.to_numeric(df[col], errors="coerce")
-    return df.head(limit)
+    return df
+
+
+def fetch_coinlore_data(limit: int = 100) -> pd.DataFrame:
+    """Return cached Coinlore data limited to the requested number of rows."""
+
+    base = _coinlore_cache.get("coinlore", _load_coinlore)
+    return base.head(limit).copy()
 
 
 def _kpi_line(df) -> str:
@@ -40,7 +79,27 @@ def _kpi_line(df) -> str:
 
 
 def build_crypto_dashboard(top_n=50):
-    df = fetch_coinlore_data(top_n)
+    try:
+        df = fetch_coinlore_data(top_n)
+    except CacheUnavailableError as e:
+        wait = int(e.retry_in) + 1
+        message = f"⚠️ Coinlore API cooling down. Retry in ~{wait} seconds."
+        return (
+            _error_figure("Market Composition", message),
+            _error_figure("Top Movers", message),
+            _error_figure("Market Cap vs Volume", message),
+            message,
+            message,
+        )
+    except Exception:  # noqa: BLE001 - surface unexpected failures
+        message = "❌ Failed to load market data. Please try again later."
+        return (
+            _error_figure("Market Composition", message),
+            _error_figure("Top Movers", message),
+            _error_figure("Market Cap vs Volume", message),
+            message,
+            message,
+        )
 
     # === Treemap ===
     fig_treemap = px.treemap(
@@ -81,11 +140,36 @@ def build_crypto_dashboard(top_n=50):
     )
 
     # === Scatter (Market Cap vs Volume) ===
+    bubble_df = df.head(60).copy()
+    if not bubble_df.empty:
+        cap = bubble_df["market_cap_usd"].fillna(0).clip(lower=1.0)
+        rank = cap.rank(pct=True)
+
+        sqrt_cap = np.sqrt(cap)
+        sqrt_min, sqrt_max = float(sqrt_cap.min()), float(sqrt_cap.max())
+        if sqrt_max - sqrt_min > 0:
+            sqrt_norm = (sqrt_cap - sqrt_min) / (sqrt_max - sqrt_min)
+        else:
+            sqrt_norm = pd.Series(0.0, index=bubble_df.index)
+
+        log_cap = np.log1p(cap)
+        log_min, log_max = float(log_cap.min()), float(log_cap.max())
+        if log_max - log_min > 0:
+            log_norm = (log_cap - log_min) / (log_max - log_min)
+        else:
+            log_norm = pd.Series(0.0, index=bubble_df.index)
+
+        hybrid = 0.55 * rank + 0.30 * sqrt_norm + 0.15 * log_norm
+        hybrid = np.power(hybrid, 0.85)
+        bubble_df["bubble_size"] = 10 + (56 - 10) * hybrid
+    else:
+        bubble_df["bubble_size"] = 10
+
     fig_bubble = px.scatter(
-        df.head(60),
+        bubble_df,
         x="market_cap_usd",
         y="volume24",
-        size="price_usd",
+        size="bubble_size",
         color="percent_change_7d",
         hover_name="symbol",
         log_x=True,
@@ -109,18 +193,86 @@ def build_crypto_dashboard(top_n=50):
 
 
 def _ai_summary(df):
+    timestamp = pd.Timestamp.utcnow().strftime("%Y-%m-%d %H:%M UTC")
     leaders = df.sort_values("percent_change_24h", ascending=False).head(3)["symbol"].tolist()
     laggards = df.sort_values("percent_change_24h").head(3)["symbol"].tolist()
-    prompt = f"""
-Summarize today's crypto market based on Coinlore data.
-Top gainers: {', '.join(leaders)}.
-Top losers: {', '.join(laggards)}.
-Include: overall sentiment, volatility/liquidity, short-term outlook.
+
+    total_cap = float(df["market_cap_usd"].sum()) if not df.empty else 0.0
+    total_volume = float(df["volume24"].sum()) if not df.empty else 0.0
+    btc_cap = float(df.loc[df["symbol"] == "BTC", "market_cap_usd"].sum()) if total_cap else 0.0
+    btc_dominance = (btc_cap / total_cap * 100) if total_cap else 0.0
+
+    snapshot_rows = (
+        df.sort_values("market_cap_usd", ascending=False)
+        .head(12)
+        [["symbol", "price_usd", "percent_change_24h", "percent_change_7d", "volume24"]]
+    )
+    lines = []
+    for row in snapshot_rows.itertuples(index=False):
+        lines.append(
+            (
+                f"{row.symbol}: price ${row.price_usd:,.2f}, "
+                f"24h {row.percent_change_24h:+.2f}%, "
+                f"7d {row.percent_change_7d:+.2f}%, "
+                f"24h volume ${row.volume24:,.0f}"
+            )
+        )
+    snapshot_text = "\n".join(lines)
+
+    system_prompt = (
+        "You are a crypto market strategist receiving a fresh Coinlore snapshot. "
+        "Use only the provided metrics to deliver an actionable analysis. "
+        "Do not mention training cutoffs or missing live access—assume the snapshot reflects the current market."
+    )
+    user_prompt = f"""
+Coinlore snapshot captured at {timestamp}.
+Aggregate totals:
+- Total market cap (tracked set): ${total_cap:,.0f}
+- 24h traded volume: ${total_volume:,.0f}
+- BTC dominance: {btc_dominance:.2f}%
+
+Key movers by 24h change:
+{snapshot_text or 'No data available.'}
+
+Top gainers (24h): {', '.join(leaders) if leaders else 'n/a'}
+Top laggards (24h): {', '.join(laggards) if laggards else 'n/a'}
+
+Provide:
+1. Market sentiment and breadth.
+2. Liquidity and volatility observations.
+3. Short-term outlook and immediate risks, grounded in this snapshot.
 """
+
     text = ""
     for delta in llm_service.stream_chat(
-        messages=[{"role": "user", "content": prompt}],
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
         model="meta-llama/Meta-Llama-3.1-8B-Instruct",
     ):
         text += delta
     return text
+
+
+def _error_figure(title: str, message: str) -> go.Figure:
+    fig = go.Figure()
+    fig.add_annotation(
+        text=message,
+        showarrow=False,
+        font=dict(color="#ff6b6b", size=16),
+        xref="paper",
+        yref="paper",
+        x=0.5,
+        y=0.5,
+    )
+    fig.update_layout(
+        template="plotly_dark",
+        title=title,
+        xaxis=dict(visible=False),
+        yaxis=dict(visible=False),
+        height=360,
+        paper_bgcolor="rgba(0,0,0,0)",
+        plot_bgcolor="rgba(0,0,0,0)",
+    )
+    return fig

presentation/components/visual_comparison.py

@@ -0,0 +1,217 @@
+"""
+Module: visual_comparison.py
+Purpose: Interactive crypto pair comparison (Plotly + CoinGecko)
+"""
+
+import requests
+import pandas as pd
+import plotly.graph_objects as go
+
+from config import CACHE_RETRY_SECONDS, CACHE_TTL_SECONDS
+from infrastructure.cache import CacheUnavailableError, TTLCache
+
+COINGECKO_API = "https://api.coingecko.com/api/v3"
+
+_history_cache = TTLCache(CACHE_TTL_SECONDS, CACHE_RETRY_SECONDS)
+
+
+def _asset_label(asset: str) -> str:
+    """Format asset identifiers for display."""
+
+    return asset.replace("-", " ").title()
+
+
+def get_coin_history(coin_id: str, days: int = 180):
+    """Fetch historical market data for given coin from CoinGecko API."""
+    def _load():
+        url = f"{COINGECKO_API}/coins/{coin_id}/market_chart?vs_currency=usd&days={days}"
+        r = requests.get(url, timeout=20)
+        r.raise_for_status()
+        data = r.json()
+        df = pd.DataFrame(data["prices"], columns=["timestamp", "price"])
+        df["timestamp"] = pd.to_datetime(df["timestamp"], unit="ms")
+        return df
+
+    return _history_cache.get((coin_id, days), _load)
+
+
+def build_price_chart(
+    pair: tuple[str, str],
+    days: int = 180,
+    *,
+    normalized: bool = False,
+):
+    """Build comparative price chart for selected pair."""
+    coin_a, coin_b = pair
+
+    try:
+        df_a = get_coin_history(coin_a, days)
+        df_b = get_coin_history(coin_b, days)
+    except CacheUnavailableError as e:
+        wait = int(e.retry_in) + 1
+        return _error_figure(
+            "Normalized Growth (Index = 1.0)" if normalized else "Price Comparison",
+            f"API cooling down. Retry in ~{wait} seconds.",
+        )
+    except Exception:  # noqa: BLE001
+        return _error_figure(
+            "Normalized Growth (Index = 1.0)" if normalized else "Price Comparison",
+            "Failed to load data. Please try again later.",
+        )
+
+    y_title = "Price (USD)"
+    chart_title = "Price Comparison"
+    y_a = df_a["price"]
+    y_b = df_b["price"]
+    hovertemplate = None
+
+    if normalized:
+        def _normalize(series: pd.Series) -> pd.Series:
+            first = series.iloc[0]
+            if pd.isna(first) or first == 0:
+                return pd.Series([0.0] * len(series), index=series.index)
+            return ((series / first) - 1) * 100
+
+        y_a = _normalize(df_a["price"])
+        y_b = _normalize(df_b["price"])
+        y_title = "Relative Growth (%)"
+        chart_title = "Normalized Growth (Index = 1.0)"
+        hovertemplate = "%{y:.2f}%<extra>%{fullData.name}</extra>"
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=df_a["timestamp"],
+            y=y_a,
+            name=(
+                f"{_asset_label(coin_a)} / USD"
+                if not normalized
+                else f"{_asset_label(coin_a)} Indexed"
+            ),
+            line=dict(width=2),
+            hovertemplate=hovertemplate,
+        )
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=df_b["timestamp"],
+            y=y_b,
+            name=(
+                f"{_asset_label(coin_b)} / USD"
+                if not normalized
+                else f"{_asset_label(coin_b)} Indexed"
+            ),
+            line=dict(width=2),
+            hovertemplate=hovertemplate,
+        )
+    )
+
+    fig.update_layout(
+        template="plotly_dark",
+        height=480,
+        margin=dict(l=40, r=20, t=30, b=40),
+        xaxis_title="Date",
+        yaxis_title=y_title,
+        legend_title="Asset" if not normalized else "Asset (Indexed)",
+        title=chart_title,
+        hovermode="x unified",
+    )
+
+    fig.update_yaxes(ticksuffix="%" if normalized else None)
+
+    return fig
+
+
+def build_comparison_chart(
+    pair: tuple[str, str],
+    days: int = 180,
+    normalized: bool = False,
+):
+    """Convenience wrapper for the price/normalized comparison chart."""
+
+    return build_price_chart(pair, days=days, normalized=normalized)
+
+
+def build_volatility_chart(pair: tuple[str, str], days: int = 180):
+    """Build comparative volatility chart for selected pair."""
+    coin_a, coin_b = pair
+
+    try:
+        df_a = get_coin_history(coin_a, days)
+        df_b = get_coin_history(coin_b, days)
+    except CacheUnavailableError as e:
+        wait = int(e.retry_in) + 1
+        return _error_figure(
+            "Volatility Comparison",
+            f"API cooling down. Retry in ~{wait} seconds.",
+        )
+    except Exception:  # noqa: BLE001
+        return _error_figure(
+            "Volatility Comparison",
+            "Failed to load data. Please try again later.",
+        )
+
+    df_a["returns"] = df_a["price"].pct_change() * 100
+    df_b["returns"] = df_b["price"].pct_change() * 100
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=df_a["timestamp"],
+        y=df_a["returns"],
+        name=f"{coin_a.upper()} Daily Change (%)",
+        mode="lines",
+        line=dict(width=1.6),
+    ))
+    fig.add_trace(go.Scatter(
+        x=df_b["timestamp"],
+        y=df_b["returns"],
+        name=f"{coin_b.upper()} Daily Change (%)",
+        mode="lines",
+        line=dict(width=1.6),
+    ))
+
+    fig.update_layout(
+        template="plotly_dark",
+        height=400,
+        margin=dict(l=40, r=20, t=30, b=40),
+        xaxis_title="Date",
+        yaxis_title="Daily Change (%)",
+        legend_title="Volatility",
+        hovermode="x unified",
+    )
+
+    return fig
+
+
+def preload_pairs(pairs: list[tuple[str, str]], days: int = 180) -> None:
+    """Warm up the cache for all coins involved in the provided pairs."""
+
+    coins = {coin for pair in pairs for coin in pair}
+    for coin in coins:
+        try:
+            get_coin_history(coin, days)
+        except CacheUnavailableError:
+            continue
+        except Exception:
+            continue
+
+
+def _error_figure(title: str, message: str):
+    fig = go.Figure()
+    fig.add_annotation(
+        text=message,
+        showarrow=False,
+        font=dict(color="#ff6b6b", size=16),
+        xref="paper",
+        yref="paper",
+        x=0.5,
+        y=0.5,
+    )
+    fig.update_layout(
+        template="plotly_dark",
+        title=title,
+        xaxis=dict(visible=False),
+        yaxis=dict(visible=False),
+        height=420,
+    )
+    return fig

presentation/styles/__init__.py

@@ -0,0 +1,5 @@
+"""Static style assets for the presentation layer."""
+
+__all__ = [
+    "themes",
+]

presentation/styles/themes/__init__.py

@@ -0,0 +1,3 @@
+"""Theme CSS assets for the presentation layer."""
+
+__all__: list[str] = []

{core/styles → presentation/styles/themes}/base.css

@@ -16,3 +16,13 @@ h2, h3, .gr-markdown { color:#f0f6fc !important; font-weight:600 !important; }
 .gr-dataframe table { width:100% !important; color:#c9d1d9 !important; background:#161b22 !important; }
 .gr-dataframe th { background:#21262d !important; color:#f0f6fc !important; border-bottom:1px solid #30363d !important; }
 .gr-dataframe td { border-top:1px solid #30363d !important; padding:8px !important; }
+
+#comparison_table table { table-layout:fixed; }
+#comparison_table table th:nth-child(1),
+#comparison_table table td:nth-child(1) { width:40% !important; }
+#comparison_table table th:nth-child(2),
+#comparison_table table td:nth-child(2),
+#comparison_table table th:nth-child(3),
+#comparison_table table td:nth-child(3),
+#comparison_table table th:nth-child(4),
+#comparison_table table td:nth-child(4) { width:20% !important; }

{core/styles → presentation/styles/themes}/crypto_dashboard.css

@@ -26,10 +26,17 @@
   align-items: center;
   justify-content: flex-start;
   min-height: 24px;
-  border-bottom: 1px solid #30363d;
   transition: all 0.2s ease-in-out;
 }
 
+#kpi_row .gr-html,
+#kpi_line,
+#kpi_line .kpi-line {
+  background: transparent !important;
+  box-shadow: none !important;
+  border: none !important;
+}
+
 /* KPI items */
 .kpi-item {
   margin-right: 14px;

services/__init__.py

@@ -1,2 +0,0 @@
-# __init__.py
-# Marks this directory as a Python package.