Refine analyzer streaming format and prompt

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,19 @@
 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.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,14 +21,13 @@ 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"
 analyzer = PortfolioAnalyzer(llm_service, MODEL_NAME)
 comparer = PortfolioComparer(llm_service, MODEL_NAME)
-chatbot = ChatAssistant(llm_service, MODEL_NAME)
 
 # === Main Interface ===
 with gr.Blocks(css=base_css) as demo:
@@ -39,32 +46,97 @@ 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.HTML(value="", elem_id="analysis_output")
+            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_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)
+        # with gr.TabItem("Metrics Table"):
+        #     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 (temporarily disabled; duplicate removed) ---
+        # 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"):
@@ -72,32 +144,61 @@ with gr.Blocks(css=base_css) as demo:
 
             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

@@ -1,15 +1,21 @@
 """
 🇬🇧 Module: analyzer.py()
-Purpose: Handles single-portfolio analysis using LLM. Fetches metrics, builds prompt, streams reasoning.
+Purpose: Handles single-portfolio analysis using LLM. Fetches metrics, builds prompt, returns formatted HTML.
 
 🇷🇺 Модуль: analyzer.py
-Назначение: анализ одного инвестиционного портфеля с использованием LLM. Получает метрики, формирует промпт, возвращает потоковый ответ.
+Назначение: анализ одного инвестиционного портфеля с использованием LLM. Получает метрики, формирует промпт, возвращает отформатированный HTML-отчёт.
 """
 
-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 typing import Iterable
+
+from infrastructure.cache import CacheUnavailableError
+from infrastructure.output_api import extract_portfolio_id, fetch_metrics_cached
+from infrastructure.llm_client import llm_service
+from presentation.components.analysis_formatter import (
+    render_analysis_html,
+    render_status_html,
+)
 from prompts.system_prompts import ANALYSIS_SYSTEM_PROMPT
 from prompts.reference_templates import REFERENCE_PROMPT
 
@@ -21,37 +27,56 @@ class PortfolioAnalyzer:
         self.llm = llm
         self.model_name = model_name
 
-    def run(self, text: str) -> Generator[str, None, None]:
-        """Stream analysis result step by step."""
+    def run(self, text: str) -> Iterable[str]:
+        """Stream formatted HTML analysis while keeping layout consistent."""
         portfolio_id = extract_portfolio_id(text)
         if not portfolio_id:
-            yield "❗ Please enter a portfolio ID."
+            yield render_status_html("❗ Please enter a portfolio ID.")
             return
 
-        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 render_status_html(
+                f"⚠️ API temporarily unavailable. Please retry in ~{wait} seconds."
+            )
+            return
+        except Exception:
+            yield render_status_html("❌ Failed to collect metrics. Please try again later.")
             return
 
         if not metrics:
-            yield "❗ Metrics can't be collected."
+            yield render_status_html("❗ Metrics can't be collected.")
             return
 
         metrics_text = ", ".join(f"{k}: {v}" for k, v in metrics.items())
         prompt = f"{REFERENCE_PROMPT}\n\nИспользуй эти данные для анализа:\n{metrics_text}"
 
-        try:
-            messages = [
-                {"role": "system", "content": ANALYSIS_SYSTEM_PROMPT},
-                {"role": "user", "content": prompt},
-            ]
+        messages = [
+            {"role": "system", "content": ANALYSIS_SYSTEM_PROMPT},
+            {"role": "user", "content": prompt},
+        ]
 
-            partial = ""
+        buffer: list[str] = []
+        try:
+            yield render_status_html("🔄 Generating analysis…")
             for delta in self.llm.stream_chat(messages=messages, model=self.model_name):
-                partial += delta
-                yield partial
+                if not delta:
+                    continue
+                buffer.append(delta)
+                partial = "".join(buffer).strip()
+                if not partial:
+                    continue
+                yield render_analysis_html(partial, show_caret=True)
+        except Exception:
+            yield render_status_html("❌ LLM is unavailable right now. Please try again later.")
+            return
+
+        final_text = "".join(buffer).strip()
+        if not final_text:
+            yield render_status_html("❗ The analysis did not return any content.")
+            return
 
-        except Exception as e:
-            yield f"❌ LLM's error: {e}"
+        # Ensure the last render is fully trimmed and styled
+        yield render_analysis_html(final_text)

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/styles/base.css

@@ -1,18 +0,0 @@
-/* === Global Layout === */
-.gradio-container { font-family: 'Inter', sans-serif; background:#0d1117 !important; }
-[data-testid="block-container"] { max-width:1180px !important; margin:auto !important; }
-h2, h3, .gr-markdown { color:#f0f6fc !important; font-weight:600 !important; }
-
-/* buttons / slider */
-.gr-button {
-  border-radius:6px !important; font-weight:600 !important; height:52px !important;
-  background:linear-gradient(90deg,#4f46e5,#6366f1) !important; border:none !important;
-  box-shadow:0 2px 4px rgba(0,0,0,.25);
-}
-.gr-slider { height:52px !important; }
-.gr-slider input[type=range]::-webkit-slider-thumb { background:#6366f1 !important; }
-
-/* tables */
-.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; }

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/analysis_formatter.py

@@ -0,0 +1,324 @@
+"""Utilities to render portfolio analysis output with styled HTML."""
+
+from __future__ import annotations
+
+import re
+from html import escape
+from html.parser import HTMLParser
+from typing import Iterable, List, Tuple
+
+_SPAN_TAG = re.compile(r"</?span(?:\s+[^>]*?)?>", re.IGNORECASE)
+_SPAN_ATTR = re.compile(r"([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*=\s*\"(.*?)\"")
+
+ALLOWED_CLASSES = {
+    "analysis-container",
+    "analysis-output",
+    "analysis-status",
+    "analysis-line",
+    "analysis-keyword",
+    "analysis-caret",
+    "bullet",
+    "metric",
+    "metric-name",
+    "metric-separator",
+    "metric-value",
+    "negative",
+    "neutral",
+    "positive",
+    "section",
+}
+
+ALLOWED_TAGS = {"div", "p", "span", "h2", "h3", "ul", "ol", "li"}
+
+SECTION_TITLES: Tuple[str, ...] = (
+    "Objective Evaluation",
+    "Risk Assessment",
+    "Interpretation",
+    "Recommendation",
+)
+
+KEYWORD_HIGHLIGHTS: Tuple[str, ...] = (
+    "poor performance",
+    "high risk",
+    "underperformed",
+    "volatility",
+    "recommendation",
+    "drawdown",
+    "exposure",
+    "opportunity",
+)
+
+METRIC_TOOLTIPS = {
+    "Sharpe Ratio": "Sharpe Ratio: excess return per unit of total risk.",
+    "Sortino Ratio": "Sortino Ratio: downside-risk-adjusted performance.",
+    "Calmar Ratio": "Calmar Ratio: annual return divided by max drawdown.",
+    "Max Drawdown": "Max Drawdown: largest observed portfolio loss from peak.",
+    "Beta": "Beta: sensitivity to benchmark movements.",
+    "Volatility": "Volatility: standard deviation of returns.",
+}
+
+_POSITIVE_HINTS = re.compile(
+    r"(\+|strong|improv|growth|positive|bullish|resilien|outperfor|favorable|advantage)",
+    re.IGNORECASE,
+)
+_NEGATIVE_HINTS = re.compile(
+    r"(-|poor|negative|risk|declin|drawdown|weak|bearish|loss|volatil|stress)",
+    re.IGNORECASE,
+)
+_KEYWORD_REGEX = re.compile(
+    "|".join(re.escape(word) for word in KEYWORD_HIGHLIGHTS), re.IGNORECASE
+)
+_METRIC_LINE = re.compile(r"^[-•]?\s*([^:]+?):\s*(.+)$")
+_SECTION_HEADER = re.compile(r"^\*\*(.+?)\*\*")
+
+
+def render_status_html(message: str) -> str:
+    """Render interim status or error messages."""
+    safe = escape(message)
+    body = f"<div class='analysis-output'><p class='analysis-status'>{safe}</p></div>"
+    return _wrap_with_container(body)
+
+
+def render_analysis_html(text: str, show_caret: bool = False) -> str:
+    """Convert LLM response into themed HTML without inline styles."""
+    stripped = text.strip()
+    if not stripped:
+        html = _wrap_with_container("<div class='analysis-output'></div>")
+        return _append_caret(html) if show_caret else html
+
+    if _looks_like_html(stripped):
+        sanitized = _sanitize_analysis_html(stripped)
+        if sanitized.strip():
+            cleaned = _trim_trailing_breaks(sanitized).strip()
+            html = _wrap_with_container(cleaned)
+            return _append_caret(html) if show_caret else html
+
+    sections = _split_sections(stripped)
+    if not sections:
+        formatted_lines = _format_lines(stripped.splitlines())
+        body = "".join(formatted_lines)
+        html = _wrap_with_container(f"<div class='analysis-output'>{body}</div>")
+        return _append_caret(html) if show_caret else html
+
+    parts: List[str] = ["<div class='analysis-output'>"]
+    for idx, (title, content) in enumerate(sections):
+        parts.append("<div class='section'>")
+        parts.append(f"<h2>{escape(title)}</h2>")
+        formatted_lines = _format_lines(content.splitlines())
+        parts.extend(formatted_lines)
+        parts.append("</div>")
+    parts.append("</div>")
+    html = "".join(parts)
+    html = _wrap_with_container(_trim_trailing_breaks(html).strip())
+    return _append_caret(html) if show_caret else html
+
+
+def _split_sections(text: str) -> List[Tuple[str, str]]:
+    sections: List[Tuple[str, str]] = []
+    current_title = None
+    buffer: List[str] = []
+
+    allowed_headers = {title.lower(): title for title in SECTION_TITLES}
+
+    for line in text.splitlines():
+        stripped = line.strip()
+        header_match = _SECTION_HEADER.match(stripped)
+        if header_match:
+            # flush previous section
+            if current_title and buffer:
+                sections.append((current_title, "\n".join(buffer).strip()))
+                buffer.clear()
+            matched_title = header_match.group(1).strip()
+            normalized = allowed_headers.get(matched_title.lower(), matched_title)
+            current_title = normalized
+            continue
+        if stripped in allowed_headers:
+            if current_title and buffer:
+                sections.append((current_title, "\n".join(buffer).strip()))
+                buffer.clear()
+            current_title = allowed_headers[stripped]
+            continue
+        buffer.append(line)
+
+    if current_title and buffer:
+        sections.append((current_title, "\n".join(buffer).strip()))
+    return sections
+
+
+def _format_lines(lines: Iterable[str]) -> List[str]:
+    formatted: List[str] = []
+    for raw_line in lines:
+        line = raw_line.strip()
+        if not line:
+            continue
+
+        metric_match = _METRIC_LINE.match(line)
+        if metric_match:
+            formatted.append(_format_metric_line(metric_match.group(1), metric_match.group(2)))
+            continue
+
+        bullet = raw_line.lstrip().startswith(('-', '•'))
+        content = re.sub(r"^[-•]\s*", "", line) if bullet else line
+        paragraph = _decorate_text(content)
+        if bullet:
+            formatted.append(f"<p class='analysis-line bullet'>{paragraph}</p>")
+        else:
+            formatted.append(f"<p class='analysis-line'>{paragraph}</p>")
+    return formatted
+
+
+def _format_metric_line(name: str, value: str) -> str:
+    value_class = _value_class(value)
+    tooltip = METRIC_TOOLTIPS.get(name.strip())
+    name_text = escape(name.strip())
+    name_span = (
+        f"<span class='metric-name' data-tooltip='{escape(tooltip)}'>{name_text}</span>"
+        if tooltip
+        else f"<span class='metric-name'>{name_text}</span>"
+    )
+    value_span = f"<span class='{value_class}'>{_decorate_text(value)}</span>"
+    return (
+        "<p class='analysis-line metric'>"
+        f"{name_span}<span class='metric-separator'>:</span>{value_span}"
+        "</p>"
+    )
+
+
+def _decorate_text(text: str) -> str:
+    preserved = _preserve_spans(text)
+    if not preserved:
+        return ""
+    highlighted = _KEYWORD_REGEX.sub(
+        lambda match: f"<span class='analysis-keyword'>{match.group(0)}</span>", preserved
+    )
+    return highlighted
+
+
+def _preserve_spans(text: str) -> str:
+    """Escape text while allowing limited span tags for inline emphasis."""
+
+    result: List[str] = []
+    last_index = 0
+    for match in _SPAN_TAG.finditer(text):
+        start, end = match.span()
+        if start > last_index:
+            result.append(escape(text[last_index:start]))
+        result.append(_sanitize_span(match.group(0)))
+        last_index = end
+    if last_index < len(text):
+        result.append(escape(text[last_index:]))
+    return "".join(result)
+
+
+def _sanitize_span(tag: str) -> str:
+    if tag.startswith("</"):
+        return "</span>"
+
+    attributes = {}
+    for attr, value in _SPAN_ATTR.findall(tag):
+        if attr.lower() != "class":
+            continue
+        filtered = _filter_allowed_classes(value)
+        if filtered:
+            attributes["class"] = filtered
+
+    attr_string = "".join(
+        f" {name}=\"{escape(val)}\"" for name, val in attributes.items()
+    )
+    return f"<span{attr_string}>"
+
+
+def _filter_allowed_classes(raw_value: str) -> str:
+    classes = [cls for cls in raw_value.split() if cls in ALLOWED_CLASSES]
+    return " ".join(dict.fromkeys(classes))
+
+
+def _looks_like_html(text: str) -> bool:
+    return bool(re.search(r"<\s*(div|p|span|h2|h3|ul|ol|li)\b", text, re.IGNORECASE))
+
+
+class _AnalyzerHTMLSanitizer(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.parts: List[str] = []
+        self._open_tags: List[str] = []
+
+    def handle_starttag(self, tag: str, attrs: List[Tuple[str, str]]) -> None:
+        tag_lower = tag.lower()
+        if tag_lower not in ALLOWED_TAGS:
+            self._open_tags.append("")
+            return
+
+        attr_string = ""
+        if attrs:
+            allowed_attrs = []
+            for name, value in attrs:
+                name_lower = name.lower()
+                if name_lower == "class":
+                    filtered = _filter_allowed_classes(value)
+                    if filtered:
+                        allowed_attrs.append(("class", filtered))
+            if allowed_attrs:
+                attr_string = "".join(
+                    f" {escape(attr)}=\"{escape(val)}\"" for attr, val in allowed_attrs
+                )
+
+        self.parts.append(f"<{tag_lower}{attr_string}>")
+        self._open_tags.append(tag_lower)
+
+    def handle_endtag(self, tag: str) -> None:
+        if not self._open_tags:
+            return
+        open_tag = self._open_tags.pop()
+        if open_tag:
+            self.parts.append(f"</{open_tag}>")
+
+    def handle_data(self, data: str) -> None:
+        if data:
+            self.parts.append(escape(data))
+
+    def handle_entityref(self, name: str) -> None:
+        self.parts.append(f"&{name};")
+
+    def handle_charref(self, name: str) -> None:
+        self.parts.append(f"&#{name};")
+
+
+def _sanitize_analysis_html(text: str) -> str:
+    sanitizer = _AnalyzerHTMLSanitizer()
+    sanitizer.feed(text)
+    sanitizer.close()
+    sanitized = "".join(sanitizer.parts)
+    return re.sub(r"<style.*?>.*?</style>", "", sanitized, flags=re.IGNORECASE | re.DOTALL)
+
+
+def _value_class(value: str) -> str:
+    if _NEGATIVE_HINTS.search(value):
+        return "metric-value negative"
+    if _POSITIVE_HINTS.search(value):
+        return "metric-value positive"
+    return "metric-value neutral"
+
+
+def _trim_trailing_breaks(html: str) -> str:
+    return re.sub(r"(?:<br\s*/?>\s*)+$", "", html)
+
+
+def _wrap_with_container(body: str) -> str:
+    """Ensure the analysis output is wrapped in the themed container."""
+
+    if re.search(r"class\s*=\s*['\"]analysis-container['\"]", body):
+        return body
+    return f"<div class='analysis-container'>{body}</div>"
+
+
+def _append_caret(html: str) -> str:
+    """Append a blinking caret to indicate streaming output."""
+
+    caret = "<span class='analysis-caret'>|</span>"
+    if caret in html:
+        return html
+    updated = re.sub(r"(</div>\s*</div>\s*)$", caret + r"\1", html, count=1)
+    if updated == html:
+        return html + caret
+    return updated

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] = []

presentation/styles/themes/base.css

@@ -0,0 +1,230 @@
+/* === Global Layout === */
+.gradio-container { font-family: 'Inter', sans-serif; background:#0d1117 !important; }
+[data-testid="block-container"] { max-width:1180px !important; margin:auto !important; }
+h2, h3, .gr-markdown { color:#f0f6fc !important; font-weight:600 !important; }
+
+/* analysis output styling */
+#analysis_output {
+  display:flex;
+  justify-content:center;
+  padding:0 16px;
+  box-sizing:border-box;
+  font-family:'Inter','Segoe UI',sans-serif;
+  color:#f0f6fc;
+}
+
+#analysis_output .analysis-container {
+  max-width:900px;
+  width:100%;
+  margin:0 auto;
+  padding:20px 24px;
+  border-radius:10px;
+  border:1px solid #1f2937;
+  background-color:#0d1117;
+  box-shadow:0 0 8px rgba(0,0,0,0.3);
+  box-sizing:border-box;
+  color:#f0f6fc;
+}
+
+#analysis_output .analysis-output {
+  width:100%;
+  font-size:15px;
+  line-height:1.6;
+}
+
+#analysis_output .analysis-output .section {
+  margin-top:30px;
+  margin-bottom:24px;
+}
+
+#analysis_output .analysis-output .section:first-of-type {
+  margin-top:0;
+}
+
+#analysis_output .analysis-output .section:last-of-type {
+  margin-bottom:0;
+}
+
+#analysis_output .analysis-output .section h2 {
+  color:#58a6ff;
+  text-align:center;
+  margin:0 0 10px;
+  font-size:1.15rem;
+  font-weight:600;
+}
+
+#analysis_output .analysis-output .section:not(:last-child)::after {
+  content:"";
+  display:block;
+  border-bottom:1px solid #30363d;
+  margin:22px 0 0;
+}
+
+#analysis_output p,
+#analysis_output span,
+#analysis_output div {
+  word-spacing:normal !important;
+  letter-spacing:normal !important;
+  white-space:normal !important;
+}
+
+#analysis_output p,
+#analysis_output li {
+  margin:8px 0;
+  color:#9ca3af;
+  text-align:justify;
+  text-justify:inter-word;
+  line-height:1.6;
+  text-wrap:balance;
+  hyphens:auto;
+  word-break:normal;
+}
+
+#analysis_output ul,
+#analysis_output ol {
+  margin:8px 0 8px 20px;
+  padding-left:4px;
+  color:#9ca3af;
+}
+
+#analysis_output .analysis-line {
+  margin:6px 0;
+  width:100%;
+}
+
+#analysis_output .analysis-line + .analysis-line {
+  margin-top:8px;
+}
+
+#analysis_output .analysis-line.metric {
+  display:block;
+}
+
+#analysis_output .analysis-line.bullet {
+  position:relative;
+  padding-left:18px;
+}
+
+#analysis_output .analysis-line.bullet::before {
+  content:"•";
+  color:#58a6ff;
+  position:absolute;
+  left:0;
+  top:0;
+}
+
+.metric-name {
+  font-family:'JetBrains Mono','Fira Code','Source Code Pro',monospace;
+  font-weight:600;
+  color:#9ca3af;
+  display:inline !important;
+}
+
+.metric-name[data-tooltip] {
+  position:relative;
+  cursor:help;
+}
+
+.metric-name[data-tooltip]::after {
+  content:attr(data-tooltip);
+  position:absolute;
+  left:0;
+  bottom:120%;
+  background:#111827;
+  border:1px solid #1f2937;
+  padding:6px 8px;
+  font-size:12px;
+  line-height:1.35;
+  color:#cbd5f5;
+  border-radius:6px;
+  white-space:nowrap;
+  opacity:0;
+  transform:translateY(6px);
+  pointer-events:none;
+  transition:opacity 0.15s ease, transform 0.15s ease;
+  z-index:20;
+}
+
+.metric-name[data-tooltip]:hover::after {
+  opacity:1;
+  transform:translateY(0);
+}
+
+.metric-separator {
+  color:#293548;
+  margin:0 6px;
+}
+
+.metric-value {
+  font-family:'JetBrains Mono','Fira Code','Source Code Pro',monospace;
+  font-weight:500;
+  margin-left:6px;
+  display:inline !important;
+}
+
+
+.metric-value.positive { color:#4ade80; }
+.metric-value.negative { color:#f87171; }
+.metric-value.neutral  { color:#9ca3af; }
+
+#analysis_output .analysis-keyword {
+  color:#93c5fd;
+  font-weight:600;
+}
+
+#analysis_output .analysis-status {
+  color:#cbd5f5;
+  font-size:15px;
+  margin:0;
+  text-align:center;
+}
+
+.analysis-caret {
+  display:inline-block;
+  width:2px;
+  height:1.2em;
+  margin-left:6px;
+  background:#58a6ff;
+  animation:analysisCaretBlink 1s steps(1) infinite;
+  vertical-align:baseline;
+}
+
+@keyframes analysisCaretBlink {
+  0%, 49% { opacity:1; }
+  50%, 100% { opacity:0; }
+}
+
+@media (max-width: 860px) {
+  #analysis_output {
+    padding:0 12px;
+  }
+
+  #analysis_output .analysis-container {
+    padding:18px 20px;
+    border-radius:10px;
+  }
+}
+
+/* buttons / slider */
+.gr-button {
+  border-radius:6px !important; font-weight:600 !important; height:52px !important;
+  background:linear-gradient(90deg,#4f46e5,#6366f1) !important; border:none !important;
+  box-shadow:0 2px 4px rgba(0,0,0,.25);
+}
+.gr-slider { height:52px !important; }
+.gr-slider input[type=range]::-webkit-slider-thumb { background:#6366f1 !important; }
+
+/* tables */
+.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;

prompts/reference_templates.py

@@ -7,19 +7,14 @@ Purpose: Defines reusable prompt templates for portfolio analysis and comparison
 """
 
 REFERENCE_PROMPT = (
-    "**Analysis**\n\n"
-    "For each key metric, provide value and brief interpretation:\n"
-    "- Annualized Return: {value1}\n"
-    "- Max Drawdown: {value2}\n"
-    "- Sharpe Ratio: {value3}\n"
-    "- Sortino Ratio: {value4}\n"
-    "- Calmar Ratio: {value5}\n"
-    "- Beta: {value6}\n"
-    "- Volatility: {value7}\n\n"
-    "**Interpretation**\n"
-    "Summarize the overall strategy characteristics, risk level, and stability.\n\n"
-    "**Recommendation**\n"
-    "Provide a brief conclusion about the portfolio’s viability."
+    "Objective Evaluation\n"
+    "Provide metric-level commentary for return, drawdown, Sharpe, Sortino, Calmar, beta, and volatility.\n\n"
+    "Risk Assessment\n"
+    "Explain downside risks, drawdown behaviour, and volatility stability.\n\n"
+    "Interpretation\n"
+    "Summarize the portfolio’s style, consistency, and resilience based on the figures.\n\n"
+    "Recommendation\n"
+    "Conclude with a concise actionable insight rooted in the supplied data."
 )
 
 REFERENCE_COMPARISON_PROMPT = (

prompts/system_prompts.py

@@ -9,14 +9,23 @@ Purpose: Stores system-level instructions for LLM.
 ANALYSIS_SYSTEM_PROMPT = """
 You are a quantitative portfolio analyst.
 
-Given a single portfolio’s metrics, provide:
-1️⃣ **Objective evaluation** of performance (returns, alpha, Sharpe ratio).
-2️⃣ **Risk assessment** (volatility, max drawdown).
-3️⃣ **Interpretation of efficiency** (how well risk and return balance).
-4️⃣ **Concise recommendation** — state whether the portfolio is performing *well, neutrally, or poorly*, and what could be improved.
-
-Avoid general statements. Use data context.
-Your tone: professional, precise, analytical.
+Produce a structured plain-text report using exactly four sections in this order:
+Objective Evaluation
+Risk Assessment
+Interpretation
+Recommendation
+
+Formatting requirements:
+- Place each section title on its own line exactly as written above.
+- Follow every title with metric lines formatted as "Metric Name: value — brief interpretation".
+- Keep the metric name, colon, value, and commentary on a single line with natural single-spacing.
+- Avoid HTML tags, Markdown headings, tables, bullets, tabs, or extra spaces.
+- After the key metrics in each section, add 1–2 concise sentences (around 80–100 characters) explaining the implications.
+- Do not end the response with blank lines.
+
+Analytical guidance:
+- Base the commentary strictly on the provided portfolio metrics.
+- Highlight both strengths and weaknesses, including return efficiency, risk exposure, and stability.
 """
 
 COMPARISON_SYSTEM_PROMPT = """

services/__init__.py

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