Deploy FinAgent: multi-agent trading signals powered by Qwen on AMD MI300X

- Gradio 4.44 frontend with live agent activity feed
- CrewAI orchestrator (5 specialized agents: Market Scanner,
Fundamental Analyst, Technical Analyst, Risk Manager, Chief Strategist)
- 10 keyless tool functions (yfinance, ddgs, pandas-ta)
- Backed by vLLM + Qwen3-8B running on AMD Instinct MI300X
- Built for the AMD Developer Hackathon (May 2026)

.gitignore

@@ -0,0 +1,11 @@
+# Keep the Space clean — prevent stray caches/local state from ever
+# getting pushed.
+__pycache__/
+*.py[cod]
+*$py.class
+.hypothesis/
+.pytest_cache/
+.DS_Store
+*.log
+.env
+.env.*

README.md

@@ -1,15 +1,74 @@
 ---
-title: Finagent
-emoji: 👀
-colorFrom: gray
-colorTo: purple
+title: FinAgent
+emoji: 🤖
+colorFrom: green
+colorTo: blue
 sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.13'
+sdk_version: 4.44.1
 app_file: app.py
 pinned: false
 license: mit
 short_description: Multi-agent trading signals powered by Qwen on AMD MI300X
+tags:
+  - crewai
+  - qwen
+  - amd-mi300x
+  - trading
+  - agents
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🤖 FinAgent — AI-Powered Trading Signal Generator
+
+**Built for the AMD Developer Hackathon** · Track: AI Agents & Agentic Workflows
+
+FinAgent is a CrewAI-driven multi-agent system that analyzes any ticker symbol you throw at it — stocks, crypto, ETFs — through five specialized AI agents and returns a structured BUY / SELL / HOLD trading signal with confidence, entry price, stop loss, and target.
+
+All the reasoning runs on **Qwen3-8B served by vLLM on an AMD Instinct MI300X** via the AMD Developer Cloud, accessed through a standard OpenAI-compatible API.
+
+## The five agents
+
+| Agent               | Role                                                | Tools                                           |
+| ------------------- | --------------------------------------------------- | ----------------------------------------------- |
+| Market Scanner      | Detect news, price changes, volume anomalies        | `search_news`, `get_price_change`, `get_volume` |
+| Fundamental Analyst | Evaluate financials, earnings, peer comparison      | `get_financials`, `get_earnings`, `get_peers`   |
+| Technical Analyst   | Read price history, indicators, entry / exit points | `get_price_history`, `calculate_indicators`     |
+| Risk Manager        | Size the position, place ATR-based stop loss        | `calculate_position_size`, `set_stop_loss`      |
+| Chief Strategist    | Synthesize all four into a final call               | — (pure reasoning)                              |
+
+The first three run in parallel. Risk Manager waits for Technical Analyst's entry price. Chief Strategist waits for everyone.
+
+## How it works
+
+1. You paste a comma-separated watchlist (up to 10 tickers).
+2. The Gradio UI streams agent activity live as they work.
+3. Each ticker produces a signal card: action (BUY/SELL/HOLD), confidence, entry / stop / target prices, and a per-agent reasoning summary.
+4. Failed tickers render an error card; one bad ticker doesn't stop the batch.
+
+## Try it
+
+Type something like:
+
+```
+AAPL, NVDA, BTC-USD, TSLA
+```
+
+pick your risk profile, portfolio value, and trading style, and hit **🔍 Analyze**.
+
+## Architecture
+
+```
+┌──────────────────────────────┐  HTTPS   ┌─────────────────────────────┐
+│  Hugging Face Space          │◄────────►│  AMD Developer Cloud        │
+│  • Gradio 4.44 UI            │          │  • AMD Instinct MI300X      │
+│  • CrewAI 1.14 orchestrator  │          │  • vLLM 0.6.3 + ROCm 6.2    │
+│  • yfinance / ddgs tools     │          │  • Qwen/Qwen3-8B            │
+└──────────────────────────────┘          └─────────────────────────────┘
+```
+
+## License
+
+MIT — see [GitHub repository](https://github.com/your-username/FinAgent) for the full source, tests, and development plan (4 specs built with Kiro spec-driven development).
+
+---
+
+⚠️ **Disclaimer:** Trading signals produced here are for informational purposes only and do not constitute financial advice. Always do your own research before placing a trade.

app.py

@@ -0,0 +1,549 @@
+"""FinAgent Gradio frontend — application entry point.
+
+This module constructs the Gradio Blocks application used as the FinAgent
+Hugging Face Space. The outer shell (title, theme, custom CSS) is defined
+in :func:`create_app`; UI widgets, session state, and event wiring are
+added by later tasks (6.2, 6.3, 6.4).
+
+The vLLM inference endpoint URL is read from the ``VLLM_ENDPOINT_URL``
+environment variable at module import time so it can be validated early
+by the Analyze event handler.
+"""
+
+import os
+import time
+from datetime import datetime
+
+import gradio as gr
+
+from rendering import (
+    build_css,
+    render_activity_entry,
+    render_activity_feed,
+    render_error_card,
+    render_signal_card,
+    render_summary,
+)
+from validation import validate_portfolio_value, validate_tickers
+
+# Inference endpoint URL for the vLLM server powering the agent pipeline.
+# Read at import time; the event handler is responsible for surfacing a
+# user-facing error when this value is missing.
+VLLM_ENDPOINT_URL = os.environ.get("VLLM_ENDPOINT_URL")
+
+# Hard cap on total pipeline execution time per Requirement 4.4. The
+# pipeline loop checks the elapsed wall-clock time before dispatching
+# each ticker and yields a timeout warning once this budget is exceeded.
+TIMEOUT_SECONDS = 180
+
+
+def _format_progress_message(
+    ticker: str,
+    i: int,
+    total: int,
+    elapsed_seconds: int,
+) -> str:
+    """Format the in-flight progress message shown above the activity feed.
+
+    Pulled out of :func:`run_analysis` as a pure, side-effect-free helper
+    so the progress string's contract (Requirements 4.2, 4.3) can be
+    exercised directly by property tests without constructing a full
+    Gradio event loop.
+
+    Args:
+        ticker: The ticker symbol currently being analyzed.
+        i: 1-indexed position of ``ticker`` in the watchlist.
+        total: Total number of tickers in the watchlist (``i <= total``).
+        elapsed_seconds: Whole seconds elapsed since the analysis began;
+            rendered verbatim in the ``(elapsed: Ns)`` suffix.
+
+    Returns:
+        A Markdown-formatted string of the form::
+
+            **Analyzing ticker {i} of {total}** — {ticker} (elapsed: {N}s)
+
+        which contains the ticker, ``i``, and ``total`` as substrings
+        (Property 6 in the design document).
+    """
+    return (
+        f"**Analyzing ticker {i} of {total}** — {ticker} "
+        f"(elapsed: {elapsed_seconds}s)"
+    )
+
+
+def run_analysis(
+    ticker_input,
+    risk_tolerance,
+    portfolio_value,
+    trading_style,
+    activity_log,
+    signals_state,
+):
+    """Analyze button event handler — streams UI updates as a generator.
+
+    This is the task 7.1 slice of the full handler: it covers environment
+    and input validation plus initial state setup. The pipeline execution
+    loop (task 7.2), error handling / completion yields (task 7.3), and
+    the ``_render_signals_dashboard`` helper (task 7.4) are added by
+    subsequent tasks.
+
+    Each ``yield`` produces the tuple wired to ``analyze_btn.click``'s
+    outputs in :func:`create_app`, in this order::
+
+        (analyze_btn, error_display, progress_text,
+         activity_feed, signals_dashboard,
+         activity_log, signals_state)
+
+    Yields:
+        Tuples of :class:`gradio.update` calls and session-state values
+        that incrementally update the UI during analysis.
+    """
+    # --- Environment validation ---
+    # The vLLM endpoint URL is required to run the pipeline. Surface a
+    # clear configuration error and re-enable the button so the user can
+    # retry once the variable is set.
+    if not VLLM_ENDPOINT_URL:
+        yield (
+            gr.update(interactive=True),
+            gr.update(
+                value=(
+                    "❌ Configuration error: `VLLM_ENDPOINT_URL` "
+                    "environment variable is not set."
+                ),
+                visible=True,
+            ),
+            gr.update(visible=False),
+            gr.update(),
+            gr.update(),
+            activity_log,
+            signals_state,
+        )
+        return
+
+    # --- Ticker validation ---
+    validation = validate_tickers(ticker_input)
+    if not validation.valid:
+        yield (
+            gr.update(interactive=True),
+            gr.update(value=f"❌ {validation.error_message}", visible=True),
+            gr.update(visible=False),
+            gr.update(),
+            gr.update(),
+            activity_log,
+            signals_state,
+        )
+        return
+
+    # --- Portfolio value validation ---
+    portfolio_error = validate_portfolio_value(portfolio_value)
+    if portfolio_error:
+        yield (
+            gr.update(interactive=True),
+            gr.update(value=f"❌ {portfolio_error}", visible=True),
+            gr.update(visible=False),
+            gr.update(),
+            gr.update(),
+            activity_log,
+            signals_state,
+        )
+        return
+
+    # --- Initialize per-run state ---
+    # Reset activity log and signals for a fresh run; capture the start
+    # timestamp so the pipeline loop (task 7.2) can enforce the timeout
+    # and report elapsed time in progress updates.
+    activity_log = []
+    signals_state = []
+    analysis_start = time.time()
+    tickers = validation.tickers
+    total = len(tickers)
+
+    # Seed the activity feed with a start entry so the user sees
+    # immediate feedback the moment the button is clicked.
+    start_entry = render_activity_entry(
+        datetime.now(),
+        "System",
+        f"Analysis started for {total} ticker(s)",
+        False,
+    )
+    activity_log.append(start_entry)
+
+    # Initial yield: disable button to prevent re-submission, hide any
+    # stale error banner, show the progress indicator, seed the activity
+    # feed, and clear the signals dashboard from any previous run.
+    yield (
+        gr.update(interactive=False),
+        gr.update(visible=False),
+        gr.update(value=f"**Analyzing ticker 1 of {total}**", visible=True),
+        render_activity_feed(activity_log),
+        "",
+        activity_log,
+        signals_state,
+    )
+
+    # --- Pipeline execution loop (task 7.2) ---
+    # The entire pipeline setup + per-ticker loop runs inside a single
+    # ``try`` block (task 7.3) so any unexpected exception — import
+    # failure, runner construction error, or an unhandled crash inside
+    # ``_run_single`` — is surfaced to the user as a visible error and
+    # the Analyze button is re-enabled instead of leaving the UI in a
+    # locked, spinning state (Requirements 8.1, 8.3).
+    try:
+        # Import the orchestration package lazily so ``app.py`` remains
+        # importable in environments where ``crew`` isn't installed
+        # (e.g., isolated unit-test runs of the validation/rendering
+        # modules).
+        from crew import (
+            LLMConfig,
+            OrchestratorConfig,
+            WatchlistRunner,
+        )
+        from crew.callbacks import ActivityEvent, ActivityFeedCallback, EventType
+
+        # Configure the orchestrator to point at the vLLM inference endpoint.
+        config = OrchestratorConfig(
+            llm=LLMConfig(base_url=VLLM_ENDPOINT_URL),
+        )
+
+        # Buffer events emitted by the runner/crew during ``_run_single``.
+        # The callback handler runs synchronously on the same thread, so
+        # a plain list plus a closure is sufficient — we drain it into
+        # the activity feed after each ticker completes.
+        pending_events: list[ActivityEvent] = []
+
+        def event_handler(event: ActivityEvent) -> None:
+            pending_events.append(event)
+
+        callback = ActivityFeedCallback(handler=event_handler)
+        runner = WatchlistRunner(config=config, tools={}, callback=callback)
+
+        for i, ticker in enumerate(tickers, 1):
+            # Enforce the overall pipeline timeout (Requirement 4.4). We
+            # check before dispatching each ticker so a slow ticker
+            # can't push the total past the budget unnoticed; when
+            # exceeded we append a timeout entry, re-enable the Analyze
+            # button, and return early.
+            elapsed = time.time() - analysis_start
+            if elapsed > TIMEOUT_SECONDS:
+                timeout_entry = render_activity_entry(
+                    datetime.now(),
+                    "System",
+                    f"⚠️ Analysis timed out after {TIMEOUT_SECONDS}s",
+                    False,
+                )
+                activity_log.append(timeout_entry)
+                yield (
+                    gr.update(interactive=True),
+                    gr.update(
+                        value="⚠️ Analysis timed out. Try fewer tickers.",
+                        visible=True,
+                    ),
+                    gr.update(visible=False),
+                    render_activity_feed(activity_log),
+                    _render_signals_dashboard(signals_state),
+                    activity_log,
+                    signals_state,
+                )
+                return
+
+            # Progress message surfaces the current ticker, its position
+            # in the batch, and elapsed seconds (Requirements 4.2, 4.3,
+            # 3.6). The format is centralized in
+            # :func:`_format_progress_message` so the contract can be
+            # property-tested directly.
+            progress_msg = _format_progress_message(
+                ticker=ticker,
+                i=i,
+                total=total,
+                elapsed_seconds=int(elapsed),
+            )
+
+            # Run the crew pipeline for this ticker. ``_run_single``
+            # handles its own exception isolation and always returns a
+            # CrewResult (success or failure), so per-ticker errors
+            # won't break the outer loop.
+            result = runner._run_single(ticker)
+
+            # Translate buffered callback events into activity feed HTML
+            # entries. Task-start events show a spinner to indicate work
+            # in progress; all other event types render as static lines.
+            for event in pending_events:
+                entry = render_activity_entry(
+                    event.timestamp,
+                    event.agent_name,
+                    event.message,
+                    is_spinner=(event.event_type == EventType.TASK_START),
+                )
+                activity_log.append(entry)
+            pending_events.clear()
+
+            # Collect the per-ticker outcome. Successful runs contribute
+            # a TradingSignal; failures contribute an error dict that
+            # ``_render_signals_dashboard`` renders via
+            # ``render_error_card`` (Requirement 5.5).
+            if result.success and result.signal is not None:
+                signals_state.append(result.signal)
+            else:
+                signals_state.append(
+                    {
+                        "ticker": ticker,
+                        "error": result.error or "Unknown error",
+                    }
+                )
+
+            # Stream the intermediate state to the UI: keep the button
+            # disabled (still running), hide the error banner, refresh
+            # the progress line, activity feed, and signals dashboard.
+            yield (
+                gr.update(interactive=False),
+                gr.update(visible=False),
+                gr.update(value=progress_msg, visible=True),
+                render_activity_feed(activity_log),
+                _render_signals_dashboard(signals_state),
+                activity_log,
+                signals_state,
+            )
+
+    except Exception as e:
+        # --- Unhandled pipeline error (task 7.3) ---
+        # Log the failure to the activity feed so the user can see what
+        # went wrong in-context (Requirement 8.2), surface a visible
+        # error banner with the exception message, hide the progress
+        # indicator, and re-enable the Analyze button so the user can
+        # retry (Requirements 8.1, 8.3). Any signals already collected
+        # from earlier tickers are preserved in ``signals_state`` and
+        # re-rendered in the final yield.
+        error_entry = render_activity_entry(
+            datetime.now(),
+            "System",
+            f"❌ Error: {str(e)}",
+            False,
+        )
+        activity_log.append(error_entry)
+        yield (
+            gr.update(interactive=True),
+            gr.update(value=f"❌ An error occurred: {str(e)}", visible=True),
+            gr.update(visible=False),
+            render_activity_feed(activity_log),
+            _render_signals_dashboard(signals_state),
+            activity_log,
+            signals_state,
+        )
+        return
+
+    # --- Successful completion (task 7.3) ---
+    # The pipeline finished without raising. Append a completion entry
+    # reporting total elapsed time (Requirement 8.4), hide the progress
+    # indicator, clear any lingering error banner, and re-enable the
+    # Analyze button for the next run.
+    elapsed_total = time.time() - analysis_start
+    complete_entry = render_activity_entry(
+        datetime.now(),
+        "System",
+        f"✅ Analysis complete ({int(elapsed_total)}s)",
+        False,
+    )
+    activity_log.append(complete_entry)
+
+    yield (
+        gr.update(interactive=True),
+        gr.update(visible=False),
+        gr.update(visible=False),
+        render_activity_feed(activity_log),
+        _render_signals_dashboard(signals_state),
+        activity_log,
+        signals_state,
+    )
+
+
+def _render_signals_dashboard(signals: list) -> str:
+    """Render the full signals dashboard HTML (summary bar + cards).
+
+    Iterates the collected results and produces a dashboard composed of
+    an aggregate :func:`render_summary` bar followed by one HTML card per
+    result: a :func:`render_signal_card` for :class:`TradingSignal`-like
+    objects and a :func:`render_error_card` for error dicts of the form
+    ``{"ticker": ..., "error": ...}``.
+
+    The action label is read defensively via ``getattr(item.action,
+    "value", item.action)`` so this helper works both with the orchestrator's
+    ``Action`` enum (``Action.BUY.value == "BUY"``) and with plain string
+    actions, without importing from the ``crew`` package.
+
+    Args:
+        signals: Ordered list of :class:`TradingSignal`-like objects and/or
+            error dicts accumulated during an analysis run.
+
+    Returns:
+        Concatenated HTML string (summary bar followed by card HTML joined
+        by newlines), or an empty string when ``signals`` is empty.
+    """
+    if not signals:
+        return ""
+
+    cards: list[str] = []
+    buy_count = 0
+    sell_count = 0
+    hold_count = 0
+
+    for item in signals:
+        # Error dicts are produced when a ticker fails analysis — render
+        # them as dedicated error cards and skip action counting.
+        if isinstance(item, dict) and "error" in item:
+            cards.append(render_error_card(item["ticker"], item["error"]))
+            continue
+
+        cards.append(render_signal_card(item))
+
+        # Categorize the action for the summary bar. ``item.action`` may
+        # be an enum (``.value`` gives the label) or already a string —
+        # ``getattr`` with a default covers both without importing the
+        # orchestrator's ``Action`` enum.
+        action_label = str(getattr(item.action, "value", item.action)).upper()
+        if action_label == "BUY":
+            buy_count += 1
+        elif action_label == "SELL":
+            sell_count += 1
+        elif action_label == "HOLD":
+            hold_count += 1
+
+    total = len(signals)
+    summary = render_summary(total, buy_count, sell_count, hold_count)
+
+    return summary + "\n".join(cards)
+
+
+def create_app() -> gr.Blocks:
+    """Build and return the Gradio Blocks application.
+
+    Creates the outer shell: page title, dark Base theme with an emerald
+    primary hue and slate neutral hue, and the custom dark financial
+    terminal CSS from :func:`rendering.build_css`.
+
+    Returns:
+        The configured :class:`gradio.Blocks` instance, ready to have UI
+        widgets and event handlers attached by subsequent tasks.
+    """
+    custom_css = build_css()
+
+    with gr.Blocks(
+        title="FinAgent - AI Trading Signals",
+        theme=gr.themes.Base(
+            primary_hue="emerald",
+            neutral_hue="slate",
+        ),
+        css=custom_css,
+    ) as app:
+        # --- Header ---
+        gr.Markdown(
+            "# 🤖 FinAgent\n"
+            "### AI-Powered Trading Signal Generator"
+        )
+
+        # --- Session State (per-user, isolated by gr.State) ---
+        activity_log = gr.State([])      # list[str]: HTML strings for activity feed entries
+        signals_state = gr.State([])     # list[TradingSignal | dict]: collected signals / errors
+        start_time = gr.State(None)      # Optional[float]: time.time() when analysis started
+
+        # --- Main Layout: Input panel (left) + Activity/Signals (right) ---
+        with gr.Row():
+            # Left Column: Input Panel
+            with gr.Column(scale=1):
+                ticker_input = gr.Textbox(
+                    label="Watchlist",
+                    placeholder="AAPL, NVDA, TSLA, BTC-USD",
+                    info="Comma-separated tickers (max 10)",
+                )
+                risk_tolerance = gr.Dropdown(
+                    choices=["Conservative", "Moderate", "Aggressive"],
+                    value="Moderate",
+                    label="Risk Tolerance",
+                )
+                portfolio_value = gr.Number(
+                    value=10000,
+                    minimum=0,
+                    label="Portfolio Value ($)",
+                )
+                trading_style = gr.Dropdown(
+                    choices=["Day Trading", "Swing Trading", "Position Trading"],
+                    value="Swing Trading",
+                    label="Trading Style",
+                )
+                analyze_btn = gr.Button(
+                    "🔍 Analyze",
+                    variant="primary",
+                    interactive=True,
+                )
+                error_display = gr.Markdown(visible=False)
+
+            # Right Column: Activity Feed + Signals Dashboard
+            with gr.Column(scale=2):
+                progress_text = gr.Markdown(visible=False)
+                activity_feed = gr.HTML(
+                    label="Agent Activity",
+                    value="<div class='activity-feed'></div>",
+                )
+                signals_dashboard = gr.HTML(
+                    label="Trading Signals",
+                    value="",
+                )
+
+        # --- Event Wiring ---
+        # The Analyze button streams results from the ``run_analysis``
+        # generator. Inputs carry the user's configuration plus the
+        # per-session activity log and collected signals so the handler
+        # can extend them incrementally. Outputs cover every widget the
+        # handler mutates during the run (button interactivity, error
+        # banner, progress text, activity feed, signals dashboard) plus
+        # the two session-state values it updates.
+        analyze_btn.click(
+            fn=run_analysis,
+            inputs=[
+                ticker_input,
+                risk_tolerance,
+                portfolio_value,
+                trading_style,
+                activity_log,
+                signals_state,
+            ],
+            outputs=[
+                analyze_btn,
+                error_display,
+                progress_text,
+                activity_feed,
+                signals_dashboard,
+                activity_log,
+                signals_state,
+            ],
+        )
+
+        # --- Footer ---
+        gr.Markdown(
+            "⚠️ **Disclaimer:** Trading signals are for informational purposes only "
+            "and do not constitute financial advice. Always do your own research."
+        )
+
+    # Expose widgets and session state on the returned Blocks so subsequent
+    # tasks (6.3 event wiring) can reference them without re-entering the
+    # context. These attributes are an internal contract between tasks in
+    # this module only.
+    app.ticker_input = ticker_input
+    app.risk_tolerance = risk_tolerance
+    app.portfolio_value = portfolio_value
+    app.trading_style = trading_style
+    app.analyze_btn = analyze_btn
+    app.error_display = error_display
+    app.progress_text = progress_text
+    app.activity_feed = activity_feed
+    app.signals_dashboard = signals_dashboard
+    app.activity_log = activity_log
+    app.signals_state = signals_state
+    app.start_time = start_time
+
+    return app
+
+
+if __name__ == "__main__":
+    # Launch the Gradio app on all interfaces so the Hugging Face Space
+    # container can route external traffic to it (per Requirement 7.5).
+    create_app().launch(server_name="0.0.0.0")

crew/__init__.py

@@ -0,0 +1,26 @@
+"""CrewAI multi-agent orchestration layer for FinAgent.
+
+This package coordinates five specialized AI agents to analyze financial
+tickers and produce structured trading signals (BUY/SELL/HOLD).
+"""
+
+from crew.callbacks import ActivityEvent, ActivityFeedCallback, EventType
+from crew.config import CrewConfig, LLMConfig, OrchestratorConfig
+from crew.crew import CrewResult, FinAgentCrew
+from crew.runner import WatchlistResult, WatchlistRunner
+from crew.signals import Action, TradingSignal
+
+__all__ = [
+    "Action",
+    "ActivityEvent",
+    "ActivityFeedCallback",
+    "CrewConfig",
+    "CrewResult",
+    "EventType",
+    "FinAgentCrew",
+    "LLMConfig",
+    "OrchestratorConfig",
+    "TradingSignal",
+    "WatchlistResult",
+    "WatchlistRunner",
+]

crew/agents.py

@@ -0,0 +1,124 @@
+"""Agent factory functions for creating configured CrewAI Agent instances."""
+
+from crewai import Agent
+from langchain_openai import ChatOpenAI
+
+from crew.config import LLMConfig
+
+
+def create_llm(config: LLMConfig) -> ChatOpenAI:
+    """Create a shared LLM instance pointing to the vLLM endpoint."""
+    return ChatOpenAI(
+        base_url=config.base_url,
+        model=config.model_name,
+        temperature=config.temperature,
+        max_tokens=config.max_tokens,
+        timeout=config.request_timeout,
+        api_key="not-needed",
+    )
+
+
+def create_market_scanner(llm: ChatOpenAI, tools: list) -> Agent:
+    """Create the Market Scanner agent.
+
+    Args:
+        llm: Shared LLM instance
+        tools: [search_news, get_price_change, get_volume]
+    """
+    return Agent(
+        role="Market Scanner",
+        goal="Detect significant market events, price movements, and volume anomalies for the given ticker",
+        backstory=(
+            "You are an experienced market surveillance specialist who monitors "
+            "news feeds, price action, and trading volumes 24/7. You have a keen "
+            "eye for detecting material events that could impact stock prices."
+        ),
+        llm=llm,
+        tools=tools,
+        max_iter=5,
+        verbose=True,
+    )
+
+
+def create_fundamental_analyst(llm: ChatOpenAI, tools: list) -> Agent:
+    """Create the Fundamental Analyst agent.
+
+    Args:
+        llm: Shared LLM instance
+        tools: [get_financials, get_earnings, get_peers]
+    """
+    return Agent(
+        role="Fundamental Analyst",
+        goal="Determine the intrinsic value of the company by analyzing financial metrics, earnings trends, and peer comparisons",
+        backstory=(
+            "You are a seasoned equity research analyst with 15 years of experience "
+            "in fundamental valuation. You specialize in dissecting financial statements, "
+            "identifying earnings quality, and comparing companies against their peers."
+        ),
+        llm=llm,
+        tools=tools,
+        max_iter=5,
+        verbose=True,
+    )
+
+
+def create_technical_analyst(llm: ChatOpenAI, tools: list) -> Agent:
+    """Create the Technical Analyst agent.
+
+    Args:
+        llm: Shared LLM instance
+        tools: [get_price_history, calculate_indicators]
+    """
+    return Agent(
+        role="Technical Analyst",
+        goal="Identify optimal entry and exit points using price patterns and technical indicators",
+        backstory=(
+            "You are a quantitative technical analyst who combines classical chart "
+            "patterns with modern indicator analysis. You focus on RSI, MACD, "
+            "Bollinger Bands, and moving average crossovers to time entries precisely."
+        ),
+        llm=llm,
+        tools=tools,
+        max_iter=5,
+        verbose=True,
+    )
+
+
+def create_risk_manager(llm: ChatOpenAI, tools: list) -> Agent:
+    """Create the Risk Manager agent.
+
+    Args:
+        llm: Shared LLM instance
+        tools: [calculate_position_size, set_stop_loss]
+    """
+    return Agent(
+        role="Risk Manager",
+        goal="Protect capital through optimal position sizing and stop-loss placement based on volatility",
+        backstory=(
+            "You are a portfolio risk specialist who never lets a single trade "
+            "risk more than the defined threshold. You use ATR-based stop-losses "
+            "and position sizing formulas to ensure consistent risk management."
+        ),
+        llm=llm,
+        tools=tools,
+        max_iter=5,
+        verbose=True,
+    )
+
+
+def create_chief_strategist(llm: ChatOpenAI) -> Agent:
+    """Create the Chief Strategist agent (no tools, pure reasoning)."""
+    return Agent(
+        role="Chief Strategist",
+        goal="Synthesize all agent analyses into a single, actionable trading signal with confidence level",
+        backstory=(
+            "You are the head of trading strategy with decades of experience "
+            "integrating fundamental, technical, and risk perspectives into "
+            "decisive trading calls. You weigh conflicting signals and produce "
+            "clear BUY/SELL/HOLD recommendations with calibrated confidence."
+        ),
+        llm=llm,
+        tools=[],
+        max_iter=5,
+        verbose=True,
+    )

crew/callbacks.py

@@ -0,0 +1,125 @@
+"""ActivityFeedCallback implementation for real-time UI updates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from typing import TYPE_CHECKING, Callable, Optional
+
+if TYPE_CHECKING:
+    from crew.signals import TradingSignal
+
+
+class EventType(str, Enum):
+    """Types of activity feed events."""
+
+    TICKER_START = "ticker_start"
+    TICKER_COMPLETE = "ticker_complete"
+    TASK_START = "task_start"
+    TASK_COMPLETE = "task_complete"
+    TASK_FAILED = "task_failed"
+    AGENT_OUTPUT = "agent_output"
+    CREW_ERROR = "crew_error"
+
+
+@dataclass
+class ActivityEvent:
+    """Structured payload for activity feed callbacks."""
+
+    event_type: EventType
+    agent_name: str
+    ticker: str
+    message: str
+    timestamp: datetime
+
+
+class ActivityFeedCallback:
+    """Manages activity feed event dispatch to the Gradio UI."""
+
+    def __init__(self, handler: Callable[[ActivityEvent], None]) -> None:
+        """Initialize with a handler function that receives ActivityEvent payloads.
+
+        Args:
+            handler: Function that receives ActivityEvent payloads.
+                     Typically connected to a Gradio state update.
+        """
+        self._handler = handler
+
+    def on_ticker_start(self, ticker: str) -> None:
+        """Emit event when a ticker analysis begins."""
+        event = ActivityEvent(
+            event_type=EventType.TICKER_START,
+            agent_name="system",
+            ticker=ticker,
+            message=f"Starting analysis for {ticker}",
+            timestamp=datetime.now(timezone.utc),
+        )
+        self._emit(event)
+
+    def on_ticker_complete(
+        self, ticker: str, signal: Optional[TradingSignal] = None
+    ) -> None:
+        """Emit event when a ticker analysis completes."""
+        if signal is not None:
+            message = f"Analysis complete for {ticker}: {signal.action.value} (Confidence: {signal.confidence}%)"
+        else:
+            message = f"Analysis complete for {ticker}"
+        event = ActivityEvent(
+            event_type=EventType.TICKER_COMPLETE,
+            agent_name="system",
+            ticker=ticker,
+            message=message,
+            timestamp=datetime.now(timezone.utc),
+        )
+        self._emit(event)
+
+    def on_task_start(self, agent_name: str, ticker: str) -> None:
+        """Emit event when an agent task begins execution."""
+        event = ActivityEvent(
+            event_type=EventType.TASK_START,
+            agent_name=agent_name,
+            ticker=ticker,
+            message=f"{agent_name} started task for {ticker}",
+            timestamp=datetime.now(timezone.utc),
+        )
+        self._emit(event)
+
+    def on_task_complete(
+        self, agent_name: str, ticker: str, output_summary: str
+    ) -> None:
+        """Emit event when an agent task completes successfully."""
+        event = ActivityEvent(
+            event_type=EventType.TASK_COMPLETE,
+            agent_name=agent_name,
+            ticker=ticker,
+            message=output_summary,
+            timestamp=datetime.now(timezone.utc),
+        )
+        self._emit(event)
+
+    def on_task_failed(self, agent_name: str, ticker: str, error: str) -> None:
+        """Emit event when an agent task fails."""
+        event = ActivityEvent(
+            event_type=EventType.TASK_FAILED,
+            agent_name=agent_name,
+            ticker=ticker,
+            message=f"{agent_name} failed for {ticker}: {error}",
+            timestamp=datetime.now(timezone.utc),
+        )
+        self._emit(event)
+
+    def on_agent_output(self, agent_name: str, ticker: str, output: str) -> None:
+        """Emit event for intermediate agent output."""
+        event = ActivityEvent(
+            event_type=EventType.AGENT_OUTPUT,
+            agent_name=agent_name,
+            ticker=ticker,
+            message=output,
+            timestamp=datetime.now(timezone.utc),
+        )
+        self._emit(event)
+
+    def _emit(self, event: ActivityEvent) -> None:
+        """Dispatch event to the registered handler."""
+        self._handler(event)

crew/config.py

@@ -0,0 +1,31 @@
+"""LLM configuration, timeouts, and constants for the orchestration layer."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class LLMConfig:
+    """Configuration for the vLLM endpoint connection."""
+
+    base_url: str = "http://localhost:8000/v1"
+    model_name: str = "Qwen/Qwen3-8B"
+    temperature: float = 0.7
+    max_tokens: int = 1024
+    request_timeout: int = 120  # seconds
+
+
+@dataclass
+class CrewConfig:
+    """Configuration for crew execution parameters."""
+
+    max_iterations: int = 5
+    task_timeout: int = 120  # seconds per task
+    verbose: bool = True
+
+
+@dataclass
+class OrchestratorConfig:
+    """Top-level configuration combining all settings."""
+
+    llm: LLMConfig = field(default_factory=LLMConfig)
+    crew: CrewConfig = field(default_factory=CrewConfig)

crew/crew.py

@@ -0,0 +1,205 @@
+"""FinAgentCrew class — main orchestrator for the multi-agent analysis pipeline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from crewai import Crew, Process
+
+from crew.config import OrchestratorConfig
+from crew.agents import (
+    create_llm,
+    create_market_scanner,
+    create_fundamental_analyst,
+    create_technical_analyst,
+    create_risk_manager,
+    create_chief_strategist,
+)
+from crew.tasks import (
+    create_market_scan_task,
+    create_fundamental_task,
+    create_technical_task,
+    create_risk_task,
+    create_strategy_task,
+)
+from crew.signals import TradingSignal, TradingSignalParser
+from crew.callbacks import ActivityFeedCallback
+
+
+@dataclass
+class CrewResult:
+    """Result of a single ticker crew execution."""
+
+    ticker: str
+    signal: Optional[TradingSignal]
+    raw_output: str
+    success: bool
+    error: Optional[str] = None
+
+
+class FinAgentCrew:
+    """Orchestrates the multi-agent analysis pipeline for a single ticker."""
+
+    def __init__(
+        self,
+        config: OrchestratorConfig,
+        tools: dict[str, list],
+        callback: Optional[ActivityFeedCallback] = None,
+    ):
+        """Initialize the crew orchestrator.
+
+        Args:
+            config: Full orchestrator configuration
+            tools: Dict mapping agent names to their tool lists:
+                {
+                    "market_scanner": [search_news, get_price_change, get_volume],
+                    "fundamental_analyst": [get_financials, get_earnings, get_peers],
+                    "technical_analyst": [get_price_history, calculate_indicators],
+                    "risk_manager": [calculate_position_size, set_stop_loss],
+                }
+            callback: Optional activity feed callback for real-time UI updates
+        """
+        self._config = config
+        self._tools = tools
+        self._callback = callback
+        self._parser = TradingSignalParser()
+
+    def run(self, ticker: str) -> CrewResult:
+        """Execute the full analysis pipeline for a single ticker.
+
+        Builds the crew, kicks off execution, parses the output into a
+        TradingSignal, and returns a CrewResult. Emits callback events
+        at task start, completion, and failure points.
+
+        Args:
+            ticker: Stock ticker symbol to analyze (e.g., "AAPL")
+
+        Returns:
+            CrewResult with parsed TradingSignal on success,
+            or error details on failure.
+        """
+        try:
+            if self._callback:
+                self._callback.on_task_start("Crew", ticker)
+
+            crew = self._build_crew(ticker)
+            result = crew.kickoff()
+            raw_output = str(result)
+
+            signal = self._parse_output(raw_output, ticker)
+
+            if signal is not None:
+                if self._callback:
+                    self._callback.on_task_complete(
+                        "Chief Strategist",
+                        ticker,
+                        f"{signal.action.value} ({signal.confidence}%)",
+                    )
+                return CrewResult(
+                    ticker=ticker,
+                    signal=signal,
+                    raw_output=raw_output,
+                    success=True,
+                )
+            else:
+                if self._callback:
+                    self._callback.on_task_failed(
+                        "Chief Strategist",
+                        ticker,
+                        "Failed to parse trading signal",
+                    )
+                return CrewResult(
+                    ticker=ticker,
+                    signal=None,
+                    raw_output=raw_output,
+                    success=False,
+                    error="Failed to parse trading signal from crew output",
+                )
+        except Exception as e:
+            error_msg = str(e)
+            if self._callback:
+                self._callback.on_task_failed("Crew", ticker, error_msg)
+            return CrewResult(
+                ticker=ticker,
+                signal=None,
+                raw_output="",
+                success=False,
+                error=error_msg,
+            )
+
+    def _build_crew(self, ticker: str) -> Crew:
+        """Assemble the Crew with agents, tasks, and process configuration.
+
+        Creates all five agents with their respective tools, builds tasks
+        with proper dependency chains, and returns a configured Crew instance.
+
+        Args:
+            ticker: Stock ticker symbol for task descriptions
+
+        Returns:
+            Configured Crew instance ready for kickoff
+        """
+        llm = create_llm(self._config.llm)
+
+        # Create agents with their assigned tools
+        market_scanner = create_market_scanner(
+            llm, self._tools.get("market_scanner", [])
+        )
+        fundamental_analyst = create_fundamental_analyst(
+            llm, self._tools.get("fundamental_analyst", [])
+        )
+        technical_analyst = create_technical_analyst(
+            llm, self._tools.get("technical_analyst", [])
+        )
+        risk_manager = create_risk_manager(
+            llm, self._tools.get("risk_manager", [])
+        )
+        chief_strategist = create_chief_strategist(llm)
+
+        # Create tasks with dependency chain
+        market_task = create_market_scan_task(market_scanner, ticker)
+        fundamental_task = create_fundamental_task(fundamental_analyst, ticker)
+        technical_task = create_technical_task(technical_analyst, ticker)
+        risk_task = create_risk_task(risk_manager, ticker, [technical_task])
+        strategy_task = create_strategy_task(
+            chief_strategist,
+            ticker,
+            [market_task, fundamental_task, technical_task, risk_task],
+        )
+
+        return Crew(
+            agents=[
+                market_scanner,
+                fundamental_analyst,
+                technical_analyst,
+                risk_manager,
+                chief_strategist,
+            ],
+            tasks=[
+                market_task,
+                fundamental_task,
+                technical_task,
+                risk_task,
+                strategy_task,
+            ],
+            process=Process.sequential,
+            verbose=self._config.crew.verbose,
+        )
+
+    def _parse_output(
+        self, raw_output: str, ticker: str
+    ) -> Optional[TradingSignal]:
+        """Parse crew output into a TradingSignal.
+
+        Delegates to TradingSignalParser which attempts primary structured
+        format first, then falls back to heuristic extraction.
+
+        Args:
+            raw_output: Raw text output from the crew execution
+            ticker: Expected ticker symbol for validation
+
+        Returns:
+            TradingSignal if parsing succeeds, None if output is unparseable
+        """
+        return self._parser.parse(raw_output, ticker)

crew/runner.py

@@ -0,0 +1,112 @@
+"""WatchlistRunner — multi-ticker sequential execution with fault isolation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from crew.config import OrchestratorConfig
+from crew.crew import CrewResult, FinAgentCrew
+from crew.callbacks import ActivityFeedCallback
+
+
+@dataclass
+class WatchlistResult:
+    """Aggregated result of running the analysis pipeline across multiple tickers."""
+
+    signals: list[CrewResult] = field(default_factory=list)
+    total_tickers: int = 0
+    successful: int = 0
+    failed: int = 0
+
+
+class WatchlistRunner:
+    """Runs the FinAgentCrew pipeline for each ticker in a watchlist sequentially."""
+
+    def __init__(
+        self,
+        config: OrchestratorConfig,
+        tools: dict[str, list],
+        callback: Optional[ActivityFeedCallback] = None,
+    ):
+        self._config = config
+        self._tools = tools
+        self._callback = callback
+
+    def run(self, watchlist: str) -> WatchlistResult:
+        """Parse the watchlist and run the analysis pipeline for each ticker.
+
+        Args:
+            watchlist: Comma-separated string of ticker symbols.
+
+        Returns:
+            WatchlistResult with aggregated signals and success/failure counts.
+        """
+        tickers = self._parse_watchlist(watchlist)
+        results: list[CrewResult] = []
+        successful = 0
+        failed = 0
+
+        for ticker in tickers:
+            if self._callback:
+                self._callback.on_ticker_start(ticker)
+
+            result = self._run_single(ticker)
+            results.append(result)
+
+            if result.success:
+                successful += 1
+            else:
+                failed += 1
+
+            if self._callback:
+                self._callback.on_ticker_complete(ticker, result.signal)
+
+        return WatchlistResult(
+            signals=results,
+            total_tickers=len(tickers),
+            successful=successful,
+            failed=failed,
+        )
+
+    def _parse_watchlist(self, watchlist: str) -> list[str]:
+        """Split watchlist string on commas, strip whitespace, uppercase, remove empties.
+
+        Args:
+            watchlist: Raw comma-separated ticker string.
+
+        Returns:
+            List of cleaned, uppercased ticker symbols.
+        """
+        parts = watchlist.split(",")
+        tickers = []
+        for part in parts:
+            stripped = part.strip().upper()
+            if stripped:
+                tickers.append(stripped)
+        return tickers
+
+    def _run_single(self, ticker: str) -> CrewResult:
+        """Run the full analysis pipeline for a single ticker with error isolation.
+
+        Args:
+            ticker: Uppercased ticker symbol.
+
+        Returns:
+            CrewResult on success or a failure CrewResult if an exception occurs.
+        """
+        try:
+            crew = FinAgentCrew(
+                config=self._config,
+                tools=self._tools,
+                callback=self._callback,
+            )
+            return crew.run(ticker)
+        except Exception as e:
+            return CrewResult(
+                ticker=ticker,
+                signal=None,
+                raw_output="",
+                success=False,
+                error=str(e),
+            )

crew/signals.py

@@ -0,0 +1,172 @@
+"""TradingSignal dataclass and parser for structured output handling."""
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class Action(str, Enum):
+    """Trading signal actions."""
+
+    BUY = "BUY"
+    SELL = "SELL"
+    HOLD = "HOLD"
+
+
+@dataclass
+class TradingSignal:
+    """Structured trading signal output."""
+
+    ticker: str
+    action: Action
+    confidence: int  # 0-100
+    entry_price: Optional[float] = None
+    stop_loss: Optional[float] = None
+    target_price: Optional[float] = None
+    reasoning: Optional[dict[str, str]] = None  # {agent_name: summary}
+
+    @staticmethod
+    def validate_confidence(value: int) -> int:
+        """Clamp confidence to 0-100 range."""
+        return max(0, min(100, value))
+
+
+class TradingSignalParser:
+    """Parses raw LLM output into structured TradingSignal objects."""
+
+    # Primary format: "AAPL — BUY (Confidence: 75%)"
+    PRIMARY_PATTERN = re.compile(
+        r"([A-Z\-\.]+)\s*[—–-]\s*(BUY|SELL|HOLD)\s*\(Confidence:\s*(\d{1,3})%\)",
+        re.IGNORECASE,
+    )
+
+    # Fallback patterns for less structured output
+    ACTION_PATTERN = re.compile(r"\b(BUY|SELL|HOLD)\b", re.IGNORECASE)
+    CONFIDENCE_PATTERN = re.compile(r"(\d{1,3})\s*%")
+    PRICE_PATTERN = re.compile(r"\$\s*([\d,]+\.?\d*)")
+
+    def parse(self, raw_output: str, ticker: str) -> Optional[TradingSignal]:
+        """Parse raw output into a TradingSignal.
+
+        Attempts primary pattern first, falls back to heuristic extraction.
+
+        Args:
+            raw_output: Raw text from Chief Strategist agent
+            ticker: Expected ticker symbol
+
+        Returns:
+            TradingSignal if parsing succeeds, None if output is unparseable
+        """
+        signal = self._parse_primary(raw_output, ticker)
+        if signal is not None:
+            return signal
+        return self._parse_fallback(raw_output, ticker)
+
+    def _parse_primary(self, raw_output: str, ticker: str) -> Optional[TradingSignal]:
+        """Attempt to parse using the primary structured format."""
+        match = self.PRIMARY_PATTERN.search(raw_output)
+        if not match:
+            return None
+
+        parsed_ticker = match.group(1).upper()
+        action_str = match.group(2).upper()
+        confidence_raw = int(match.group(3))
+
+        action = Action(action_str)
+        confidence = TradingSignal.validate_confidence(confidence_raw)
+
+        prices = self._extract_prices(raw_output)
+        reasoning = self._extract_reasoning(raw_output)
+
+        return TradingSignal(
+            ticker=parsed_ticker,
+            action=action,
+            confidence=confidence,
+            entry_price=prices.get("entry"),
+            stop_loss=prices.get("stop_loss"),
+            target_price=prices.get("target"),
+            reasoning=reasoning,
+        )
+
+    def _parse_fallback(self, raw_output: str, ticker: str) -> Optional[TradingSignal]:
+        """Attempt heuristic extraction from unstructured output."""
+        action_match = self.ACTION_PATTERN.search(raw_output)
+        if not action_match:
+            return None
+
+        action = Action(action_match.group(1).upper())
+
+        confidence_match = self.CONFIDENCE_PATTERN.search(raw_output)
+        if confidence_match:
+            confidence = TradingSignal.validate_confidence(int(confidence_match.group(1)))
+        else:
+            confidence = 50  # Default confidence when not specified
+
+        prices = self._extract_prices(raw_output)
+
+        return TradingSignal(
+            ticker=ticker.upper(),
+            action=action,
+            confidence=confidence,
+            entry_price=prices.get("entry"),
+            stop_loss=prices.get("stop_loss"),
+            target_price=prices.get("target"),
+        )
+
+    def _extract_prices(self, raw_output: str) -> dict[str, Optional[float]]:
+        """Extract entry, stop-loss, and target prices from text.
+
+        Finds all $XX.XX patterns and assigns:
+        - First as entry price
+        - Second as stop_loss
+        - Third as target price
+        """
+        matches = self.PRICE_PATTERN.findall(raw_output)
+        prices: dict[str, Optional[float]] = {
+            "entry": None,
+            "stop_loss": None,
+            "target": None,
+        }
+
+        # Parse matched price strings, removing commas
+        parsed = []
+        for m in matches:
+            cleaned = m.replace(",", "")
+            try:
+                parsed.append(float(cleaned))
+            except ValueError:
+                continue
+
+        if len(parsed) >= 1:
+            prices["entry"] = parsed[0]
+        if len(parsed) >= 2:
+            prices["stop_loss"] = parsed[1]
+        if len(parsed) >= 3:
+            prices["target"] = parsed[2]
+
+        return prices
+
+    def _extract_reasoning(self, raw_output: str) -> Optional[dict[str, str]]:
+        """Extract per-agent reasoning summaries from text.
+
+        Looks for lines like:
+        - Market: ...
+        - Fundamental: ...
+        - Technical: ...
+        - Risk: ...
+        """
+        reasoning_pattern = re.compile(
+            r"^-\s*(Market|Fundamental|Technical|Risk)\s*:\s*(.+)$",
+            re.MULTILINE | re.IGNORECASE,
+        )
+        matches = reasoning_pattern.findall(raw_output)
+
+        if not matches:
+            return None
+
+        reasoning = {}
+        for key, value in matches:
+            reasoning[key.strip()] = value.strip()
+
+        return reasoning if reasoning else None

crew/tasks.py

@@ -0,0 +1,115 @@
+"""Task factory functions with dependencies for CrewAI Task instances."""
+
+from crewai import Task, Agent
+
+
+def create_market_scan_task(agent: Agent, ticker: str) -> Task:
+    """Create the market scanning task."""
+    return Task(
+        description=(
+            f"Analyze the current market conditions for {ticker}. "
+            f"Search for recent news, check price changes, and identify volume anomalies. "
+            f"Summarize any significant market events that could affect the stock."
+        ),
+        expected_output=(
+            f"A summary of market conditions for {ticker} including: "
+            f"key news events, price change magnitude and direction, "
+            f"and whether volume is normal or unusual."
+        ),
+        agent=agent,
+    )
+
+
+def create_fundamental_task(agent: Agent, ticker: str) -> Task:
+    """Create the fundamental analysis task."""
+    return Task(
+        description=(
+            f"Perform a fundamental analysis of {ticker}. "
+            f"Retrieve financial metrics, recent earnings data, and peer comparisons. "
+            f"Assess whether the stock is overvalued, undervalued, or fairly valued."
+        ),
+        expected_output=(
+            f"A valuation assessment for {ticker} including: "
+            f"key financial metrics (P/E, margins, growth), "
+            f"earnings trend and surprises, peer comparison, "
+            f"and an overall fundamental outlook (bullish/bearish/neutral)."
+        ),
+        agent=agent,
+    )
+
+
+def create_technical_task(agent: Agent, ticker: str) -> Task:
+    """Create the technical analysis task."""
+    return Task(
+        description=(
+            f"Perform a technical analysis of {ticker}. "
+            f"Retrieve price history and calculate technical indicators. "
+            f"Identify the current trend, support/resistance levels, "
+            f"and recommend entry and target prices."
+        ),
+        expected_output=(
+            f"A technical analysis for {ticker} including: "
+            f"current trend direction, RSI/MACD/Bollinger signals, "
+            f"recommended entry price, and target price."
+        ),
+        agent=agent,
+    )
+
+
+def create_risk_task(agent: Agent, ticker: str, context: list) -> Task:
+    """Create the risk assessment task.
+
+    Args:
+        agent: Risk Manager agent
+        ticker: Stock symbol
+        context: [technical_task] — depends on Technical Analyst output
+    """
+    return Task(
+        description=(
+            f"Calculate position sizing and stop-loss levels for {ticker}. "
+            f"Use the entry price from the Technical Analyst's recommendation "
+            f"to determine optimal position size and ATR-based stop-loss."
+        ),
+        expected_output=(
+            f"Risk parameters for {ticker} including: "
+            f"recommended position size, stop-loss price, "
+            f"take-profit target, and risk-reward ratio."
+        ),
+        agent=agent,
+        context=context,
+    )
+
+
+def create_strategy_task(agent: Agent, ticker: str, context: list) -> Task:
+    """Create the strategy synthesis task.
+
+    Args:
+        agent: Chief Strategist agent
+        ticker: Stock symbol
+        context: [market_task, fundamental_task, technical_task, risk_task]
+    """
+    return Task(
+        description=(
+            f"Synthesize all analysis for {ticker} into a final trading signal. "
+            f"Consider the market conditions, fundamental valuation, technical signals, "
+            f"and risk parameters. Produce a clear BUY, SELL, or HOLD recommendation "
+            f"with a confidence percentage.\n\n"
+            f"Your output MUST follow this exact format:\n"
+            f"{ticker} — ACTION (Confidence: XX%)\n"
+            f"Entry: $XX.XX\n"
+            f"Stop Loss: $XX.XX\n"
+            f"Target: $XX.XX\n"
+            f"Reasoning:\n"
+            f"- Market: [summary]\n"
+            f"- Fundamental: [summary]\n"
+            f"- Technical: [summary]\n"
+            f"- Risk: [summary]"
+        ),
+        expected_output=(
+            f"A trading signal in the format: "
+            f"'{ticker} — BUY/SELL/HOLD (Confidence: XX%)' "
+            f"followed by entry, stop-loss, target prices and reasoning summaries."
+        ),
+        agent=agent,
+        context=context,
+    )

rendering.py

@@ -0,0 +1,298 @@
+"""HTML/CSS rendering for the FinAgent Gradio frontend.
+
+Provides pure rendering functions that generate HTML strings for:
+- Custom dark terminal theme CSS
+- Trading signal cards (BUY/SELL/HOLD)
+- Error cards for failed ticker analysis
+- Aggregate summary bar
+- Activity feed entries and container
+
+Full implementation is provided in task 4.x; this module currently
+contains function stubs.
+"""
+
+from datetime import datetime
+from typing import Any, List, Optional
+
+
+def build_css() -> str:
+    """Generate custom CSS for the dark financial terminal theme.
+
+    Returns:
+        CSS string to be injected into the Gradio Blocks ``css`` parameter.
+    """
+    return """
+    .gradio-container {
+        font-family: 'JetBrains Mono', 'Fira Code', 'Courier New', monospace !important;
+        background-color: #0d1117 !important;
+    }
+    .activity-feed {
+        background: #161b22;
+        border: 1px solid #30363d;
+        border-radius: 6px;
+        padding: 12px;
+        max-height: 400px;
+        overflow-y: auto;
+        font-family: 'JetBrains Mono', monospace;
+        font-size: 13px;
+    }
+    .activity-entry {
+        padding: 4px 0;
+        border-bottom: 1px solid #21262d;
+        color: #c9d1d9;
+    }
+    .activity-timestamp {
+        color: #8b949e;
+        margin-right: 8px;
+    }
+    .activity-agent {
+        color: #58a6ff;
+        font-weight: bold;
+    }
+    .activity-spinner {
+        color: #f0883e;
+    }
+    .signal-card {
+        background: #161b22;
+        border: 1px solid #30363d;
+        border-radius: 8px;
+        padding: 16px;
+        margin: 8px 0;
+        border-left: 4px solid;
+    }
+    .signal-buy { border-left-color: #3fb950; }
+    .signal-sell { border-left-color: #f85149; }
+    .signal-hold { border-left-color: #d29922; }
+    .signal-error { border-left-color: #f85149; background: #1c0c0c; }
+    .signal-ticker {
+        font-size: 18px;
+        font-weight: bold;
+        color: #f0f6fc;
+    }
+    .signal-action-buy { color: #3fb950; }
+    .signal-action-sell { color: #f85149; }
+    .signal-action-hold { color: #d29922; }
+    .signal-confidence {
+        font-size: 14px;
+        color: #8b949e;
+    }
+    .signal-prices {
+        display: grid;
+        grid-template-columns: repeat(3, 1fr);
+        gap: 8px;
+        margin-top: 8px;
+    }
+    .signal-price-item {
+        text-align: center;
+        padding: 8px;
+        background: #0d1117;
+        border-radius: 4px;
+    }
+    .signal-price-label {
+        font-size: 11px;
+        color: #8b949e;
+        text-transform: uppercase;
+    }
+    .signal-price-value {
+        font-size: 16px;
+        color: #f0f6fc;
+        font-weight: bold;
+    }
+    .summary-bar {
+        display: flex;
+        gap: 16px;
+        padding: 12px;
+        background: #161b22;
+        border-radius: 6px;
+        margin-top: 12px;
+        border: 1px solid #30363d;
+    }
+    .summary-item {
+        text-align: center;
+        flex: 1;
+    }
+    """
+
+
+def _format_price(value: Optional[float]) -> str:
+    """Format an optional price as ``$X.XX`` or ``N/A`` when missing."""
+    if value is None:
+        return "N/A"
+    return f"${value:.2f}"
+
+
+def _action_text(action: Any) -> str:
+    """Return the upper-case action label from an enum-like or string value."""
+    # Support both enum-like objects (with ``.value``) and plain strings.
+    raw = getattr(action, "value", action)
+    return str(raw).upper()
+
+
+def render_signal_card(signal: Any) -> str:
+    """Render a TradingSignal as an HTML card.
+
+    Args:
+        signal: TradingSignal dataclass instance containing ticker, action,
+            confidence, entry/stop-loss/target prices, and reasoning.
+
+    Returns:
+        HTML string for the signal card with action-specific color coding.
+    """
+    action_text = _action_text(signal.action)
+    action_lower = action_text.lower()
+    action_class = f"signal-{action_lower}"
+    action_color_class = f"signal-action-{action_lower}"
+
+    entry_price = getattr(signal, "entry_price", None)
+    stop_loss = getattr(signal, "stop_loss", None)
+    target_price = getattr(signal, "target_price", None)
+
+    prices_html = f"""
+        <div class="signal-prices">
+            <div class="signal-price-item">
+                <div class="signal-price-label">Entry</div>
+                <div class="signal-price-value">{_format_price(entry_price)}</div>
+            </div>
+            <div class="signal-price-item">
+                <div class="signal-price-label">Stop Loss</div>
+                <div class="signal-price-value">{_format_price(stop_loss)}</div>
+            </div>
+            <div class="signal-price-item">
+                <div class="signal-price-label">Target</div>
+                <div class="signal-price-value">{_format_price(target_price)}</div>
+            </div>
+        </div>
+        """
+
+    reasoning = getattr(signal, "reasoning", None) or {}
+    reasoning_html = ""
+    if reasoning:
+        reasoning_items = "".join(
+            f"<li><strong>{k}:</strong> {v}</li>"
+            for k, v in reasoning.items()
+        )
+        reasoning_html = (
+            f"<ul style='color:#c9d1d9;margin-top:8px;'>{reasoning_items}</ul>"
+        )
+
+    return f"""
+    <div class="signal-card {action_class}">
+        <div style="display:flex;justify-content:space-between;align-items:center;">
+            <span class="signal-ticker">{signal.ticker}</span>
+            <span class="{action_color_class}" style="font-size:20px;font-weight:bold;">
+                {action_text}
+            </span>
+        </div>
+        <div class="signal-confidence">Confidence: {signal.confidence}%</div>
+        {prices_html}
+        {reasoning_html}
+    </div>
+    """
+
+
+def render_error_card(ticker: str, error_message: str) -> str:
+    """Render an error card for a failed ticker analysis.
+
+    Args:
+        ticker: The ticker symbol that failed analysis.
+        error_message: Human-readable error description.
+
+    Returns:
+        HTML string for the error card with the ``signal-error`` class.
+    """
+    return f"""
+    <div class="signal-card signal-error">
+        <div class="signal-ticker">{ticker}</div>
+        <div style="color:#f85149;margin-top:4px;">⚠️ Analysis failed: {error_message}</div>
+    </div>
+    """
+
+
+def render_summary(
+    total: int,
+    buy_count: int,
+    sell_count: int,
+    hold_count: int,
+) -> str:
+    """Render the aggregate summary bar.
+
+    Args:
+        total: Total number of tickers analyzed.
+        buy_count: Number of BUY signals.
+        sell_count: Number of SELL signals.
+        hold_count: Number of HOLD signals.
+
+    Returns:
+        HTML string for the summary bar with color-coded counts
+        (green for BUY, red for SELL, yellow for HOLD).
+    """
+    return f"""
+    <div class="summary-bar">
+        <div class="summary-item">
+            <div style="font-size:24px;color:#f0f6fc;">{total}</div>
+            <div style="font-size:11px;color:#8b949e;">ANALYZED</div>
+        </div>
+        <div class="summary-item">
+            <div style="font-size:24px;color:#3fb950;">{buy_count}</div>
+            <div style="font-size:11px;color:#8b949e;">BUY</div>
+        </div>
+        <div class="summary-item">
+            <div style="font-size:24px;color:#f85149;">{sell_count}</div>
+            <div style="font-size:11px;color:#8b949e;">SELL</div>
+        </div>
+        <div class="summary-item">
+            <div style="font-size:24px;color:#d29922;">{hold_count}</div>
+            <div style="font-size:11px;color:#8b949e;">HOLD</div>
+        </div>
+    </div>
+    """
+
+
+def render_activity_entry(
+    timestamp: datetime,
+    agent_name: str,
+    message: str,
+    is_spinner: bool = False,
+) -> str:
+    """Render a single activity feed entry as HTML.
+
+    Args:
+        timestamp: Entry timestamp (formatted as HH:MM:SS).
+        agent_name: Name of the agent producing the entry.
+        message: Entry message content.
+        is_spinner: When True, include a spinner indicator.
+
+    Returns:
+        HTML string for the activity entry.
+    """
+    time_str = timestamp.strftime("%H:%M:%S")
+    spinner = '<span class="activity-spinner"> ⟳</span>' if is_spinner else ""
+    return f"""
+    <div class="activity-entry">
+        <span class="activity-timestamp">[{time_str}]</span>
+        <span class="activity-agent">{agent_name}</span>{spinner}
+        <span>{message}</span>
+    </div>
+    """
+
+
+def render_activity_feed(entries: List[str]) -> str:
+    """Wrap activity entries in the feed container with auto-scroll.
+
+    Args:
+        entries: List of pre-rendered HTML entry strings.
+
+    Returns:
+        HTML string for the activity feed container, including an
+        auto-scroll script that pins the view to the latest entry.
+    """
+    entries_html = "\n".join(entries)
+    return f"""
+    <div class="activity-feed" id="activity-feed">
+        {entries_html}
+    </div>
+    <script>
+        var feed = document.getElementById('activity-feed');
+        if (feed) feed.scrollTop = feed.scrollHeight;
+    </script>
+    """

requirements.txt

@@ -0,0 +1,23 @@
+# Hugging Face Space — runtime dependencies for FinAgent.
+#
+# This file is consumed by the Space builder and installs into a CPU-only
+# environment (the GPU inference runs elsewhere on AMD Developer Cloud).
+# Pins here should stay tight to avoid drifting into incompatible combinations.
+
+# Gradio frontend framework
+gradio==4.44.1
+
+# Agent orchestration
+crewai==1.14.4
+langchain-openai==0.3.18
+
+# Market / tool data providers
+yfinance==1.3.0
+ddgs>=9.0,<10
+pandas-ta-remake==1.0.4
+
+# pandas-ta-remake 1.0.4 still imports pkg_resources; Setuptools >=81 removed it.
+setuptools<81
+
+# Tokenizers 0.20.x lacks DecodeStream on Py3.13; crewai needs >=0.21.
+tokenizers>=0.21,<1

tools/__init__.py

@@ -0,0 +1,40 @@
+"""
+Agent Tools Module for FinAgent.
+
+This module provides 10 CrewAI tool functions across four domains:
+- Market Scanner: search_news, get_price_change, get_volume
+- Fundamental Analyst: get_financials, get_earnings, get_peers
+- Technical Analyst: get_price_history, calculate_indicators
+- Risk Manager: calculate_position_size, set_stop_loss
+
+All tools return formatted strings and handle errors gracefully.
+"""
+
+# Market Scanner Tools
+from tools.market_scanner import search_news, get_price_change, get_volume
+
+# Fundamental Analyst Tools
+from tools.fundamental_analyst import get_financials, get_earnings, get_peers
+
+# Technical Analyst Tools
+from tools.technical_analyst import get_price_history, calculate_indicators
+
+# Risk Manager Tools
+from tools.risk_manager import calculate_position_size, set_stop_loss
+
+__all__ = [
+    # Market Scanner
+    "search_news",
+    "get_price_change",
+    "get_volume",
+    # Fundamental Analyst
+    "get_financials",
+    "get_earnings",
+    "get_peers",
+    # Technical Analyst
+    "get_price_history",
+    "calculate_indicators",
+    # Risk Manager
+    "calculate_position_size",
+    "set_stop_loss",
+]

tools/cache.py

@@ -0,0 +1,107 @@
+"""
+TTL Cache module for Agent Tools.
+
+Provides an in-memory cache with time-to-live eviction to avoid
+redundant API calls and rate limiting.
+"""
+
+import json
+import threading
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class CacheEntry:
+    """A single cache entry with its stored value and creation timestamp."""
+
+    value: str
+    timestamp: float
+
+
+class TTLCache:
+    """In-memory cache with time-to-live eviction.
+
+    Stores string results keyed by function name + parameters.
+    Thread-safe via threading.Lock on all read/write operations.
+    """
+
+    def __init__(self, default_ttl: int = 300, max_age: int = 900):
+        """Initialize the cache.
+
+        Args:
+            default_ttl: Time-to-live in seconds (default 300 = 5 minutes).
+                         Entries older than this are considered expired on get().
+            max_age: Maximum entry age before forced eviction (default 900 = 15 minutes).
+                     Entries older than this are removed during eviction sweeps.
+        """
+        self.default_ttl = default_ttl
+        self.max_age = max_age
+        self._store: dict[str, CacheEntry] = {}
+        self._lock = threading.Lock()
+
+    def make_key(self, func_name: str, **kwargs) -> str:
+        """Generate a deterministic cache key from function name and parameters.
+
+        Uses sorted JSON serialization to ensure the same parameters always
+        produce the same key regardless of argument order.
+
+        Args:
+            func_name: The name of the tool function.
+            **kwargs: The parameters passed to the function.
+
+        Returns:
+            A string key in the format "func_name:{sorted_params_json}".
+        """
+        sorted_params_json = json.dumps(kwargs, sort_keys=True)
+        return f"{func_name}:{sorted_params_json}"
+
+    def get(self, key: str) -> Optional[str]:
+        """Return cached value if it exists and is within TTL, else None.
+
+        Always triggers _evict_stale() to clean up old entries.
+
+        Args:
+            key: The cache key to look up.
+
+        Returns:
+            The cached string value if valid, or None if expired/missing.
+        """
+        with self._lock:
+            self._evict_stale()
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            if time.time() - entry.timestamp > self.default_ttl:
+                return None
+            return entry.value
+
+    def set(self, key: str, value: str) -> None:
+        """Store a value in the cache with the current timestamp.
+
+        Args:
+            key: The cache key.
+            value: The string value to cache.
+        """
+        with self._lock:
+            self._store[key] = CacheEntry(value=value, timestamp=time.time())
+
+    def _evict_stale(self) -> None:
+        """Remove entries older than max_age (15 minutes by default).
+
+        This method is called internally and assumes the lock is already held.
+        """
+        current_time = time.time()
+        stale_keys = [
+            key
+            for key, entry in self._store.items()
+            if current_time - entry.timestamp > self.max_age
+        ]
+        for key in stale_keys:
+            del self._store[key]
+
+    def clear(self) -> None:
+        """Remove all entries from the cache. Useful for testing."""
+        with self._lock:
+            self._store.clear()

tools/fundamental_analyst.py

@@ -0,0 +1,329 @@
+"""
+Fundamental Analyst Tools for FinAgent.
+
+Provides tools for fundamental analysis agents:
+- get_financials: Retrieve key financial metrics
+- get_earnings: Retrieve earnings history with surprise calculations
+- get_peers: Retrieve sector/industry peers
+"""
+
+import math
+
+import yfinance
+from crewai.tools import tool
+
+from tools.cache import TTLCache
+from tools.utils import validate_ticker, format_currency, format_percent, safe_get
+
+cache = TTLCache()
+
+
+@tool("Get Financials")
+def get_financials(ticker: str) -> str:
+    """Retrieve key financial metrics for a company including market cap, P/E ratio, revenue growth, profit margin, and debt-to-equity ratio."""
+    try:
+        # 1. Input validation
+        valid, result = validate_ticker(ticker)
+        if not valid:
+            return result
+
+        normalized_ticker = result
+
+        # 2. Cache check
+        cache_key = cache.make_key("get_financials", ticker=normalized_ticker)
+        cached = cache.get(cache_key)
+        if cached:
+            return cached
+
+        # 3. External API call
+        info = yfinance.Ticker(normalized_ticker).info
+
+        if not info or info.get("regularMarketPrice") is None and info.get("currentPrice") is None:
+            return f"Error: Ticker '{normalized_ticker}' not found. Please verify the symbol."
+
+        # 4. Format response — missing fields show "N/A", not an error
+        market_cap = format_currency(info.get("marketCap"))
+        pe_ratio = safe_get(info, "trailingPE")
+        revenue_growth = format_percent(info.get("revenueGrowth"))
+        profit_margin = format_percent(info.get("profitMargins"))
+        debt_equity = safe_get(info, "debtToEquity")
+
+        response = (
+            f"Financial Metrics for {normalized_ticker}:\n"
+            f"Market Cap: {market_cap}\n"
+            f"P/E Ratio: {pe_ratio}\n"
+            f"Revenue Growth: {revenue_growth}\n"
+            f"Profit Margin: {profit_margin}\n"
+            f"Debt/Equity: {debt_equity}"
+        )
+
+        # 5. Cache and return
+        cache.set(cache_key, response)
+        return response
+
+    except Exception as e:
+        return f"Error: An unexpected error occurred while processing {ticker}: {str(e)}"
+
+
+@tool("Get Earnings")
+def get_earnings(ticker: str) -> str:
+    """Retrieve earnings history with surprise calculations for a given ticker.
+
+    Args:
+        ticker: Stock symbol (e.g., AAPL) or crypto pair (e.g., BTC-USD).
+
+    Returns:
+        A formatted string with the last 4 quarters of earnings data including
+        reported EPS, estimated EPS, and surprise percentage, or an error message.
+    """
+    try:
+        # 1. Input validation
+        valid, result = validate_ticker(ticker)
+        if not valid:
+            return result
+
+        normalized_ticker = result
+
+        # 2. Detect crypto tickers (contain "-" like BTC-USD, ETH-USD)
+        if "-" in normalized_ticker:
+            return "Earnings data is not available for this instrument type."
+
+        # 3. Cache check
+        cache_key = cache.make_key("get_earnings", ticker=normalized_ticker)
+        cached = cache.get(cache_key)
+        if cached:
+            return cached
+
+        # 4. External API call
+        stock = yfinance.Ticker(normalized_ticker)
+        earnings_dates = stock.earnings_dates
+
+        # 5. Check if earnings data is available
+        if earnings_dates is None or earnings_dates.empty:
+            return "Earnings data is not available for this instrument type."
+
+        # 6. Filter to rows that have reported EPS (past earnings only)
+        relevant_cols = ["EPS Estimate", "Reported EPS"]
+        if not all(col in earnings_dates.columns for col in relevant_cols):
+            return "Earnings data is not available for this instrument type."
+
+        earnings_data = earnings_dates.dropna(subset=["Reported EPS"])
+
+        if earnings_data.empty:
+            return "Earnings data is not available for this instrument type."
+
+        # Take the last 4 quarters (most recent first)
+        earnings_data = earnings_data.head(4)
+
+        # 7. Format response
+        lines = [f"Earnings History for {normalized_ticker} (Last 4 Quarters):"]
+
+        for date_idx, row in earnings_data.iterrows():
+            reported_eps = row["Reported EPS"]
+            estimated_eps = row.get("EPS Estimate")
+
+            # Determine quarter label from the date index
+            quarter_date = date_idx
+            quarter_num = (quarter_date.month - 1) // 3 + 1
+            quarter_label = f"Q{quarter_num} {quarter_date.year}"
+
+            # Calculate surprise percentage
+            if estimated_eps is not None and estimated_eps != 0:
+                if not math.isnan(estimated_eps):
+                    surprise = round(((reported_eps - estimated_eps) / abs(estimated_eps)) * 100, 2)
+                    surprise_str = f"+{surprise:.2f}%" if surprise >= 0 else f"{surprise:.2f}%"
+                    lines.append(
+                        f"{quarter_label}: EPS ${reported_eps:.2f} "
+                        f"(Est: ${estimated_eps:.2f}) | Surprise: {surprise_str}"
+                    )
+                else:
+                    lines.append(
+                        f"{quarter_label}: EPS ${reported_eps:.2f} "
+                        f"(Est: N/A) | Surprise: N/A"
+                    )
+            else:
+                lines.append(
+                    f"{quarter_label}: EPS ${reported_eps:.2f} "
+                    f"(Est: N/A) | Surprise: N/A"
+                )
+
+        response = "\n".join(lines)
+
+        # 8. Cache and return
+        cache.set(cache_key, response)
+        return response
+
+    except Exception as e:
+        return f"Error: An unexpected error occurred while processing {ticker}: {str(e)}"
+
+
+# Sector-to-peers mapping for common sectors
+SECTOR_PEERS = {
+    "Technology": [
+        ("MSFT", "Microsoft Corporation"),
+        ("AAPL", "Apple Inc."),
+        ("GOOGL", "Alphabet Inc."),
+        ("NVDA", "NVIDIA Corporation"),
+        ("META", "Meta Platforms Inc."),
+        ("AMZN", "Amazon.com Inc."),
+        ("CRM", "Salesforce Inc."),
+        ("ADBE", "Adobe Inc."),
+        ("ORCL", "Oracle Corporation"),
+        ("INTC", "Intel Corporation"),
+    ],
+    "Healthcare": [
+        ("JNJ", "Johnson & Johnson"),
+        ("UNH", "UnitedHealth Group Inc."),
+        ("PFE", "Pfizer Inc."),
+        ("ABBV", "AbbVie Inc."),
+        ("MRK", "Merck & Co. Inc."),
+        ("LLY", "Eli Lilly and Company"),
+        ("TMO", "Thermo Fisher Scientific Inc."),
+        ("ABT", "Abbott Laboratories"),
+    ],
+    "Financial Services": [
+        ("JPM", "JPMorgan Chase & Co."),
+        ("BAC", "Bank of America Corporation"),
+        ("GS", "Goldman Sachs Group Inc."),
+        ("MS", "Morgan Stanley"),
+        ("WFC", "Wells Fargo & Company"),
+        ("C", "Citigroup Inc."),
+        ("BLK", "BlackRock Inc."),
+        ("SCHW", "Charles Schwab Corporation"),
+    ],
+    "Consumer Cyclical": [
+        ("AMZN", "Amazon.com Inc."),
+        ("TSLA", "Tesla Inc."),
+        ("HD", "The Home Depot Inc."),
+        ("NKE", "Nike Inc."),
+        ("MCD", "McDonald's Corporation"),
+        ("SBUX", "Starbucks Corporation"),
+        ("TGT", "Target Corporation"),
+        ("LOW", "Lowe's Companies Inc."),
+    ],
+    "Consumer Defensive": [
+        ("PG", "Procter & Gamble Company"),
+        ("KO", "The Coca-Cola Company"),
+        ("PEP", "PepsiCo Inc."),
+        ("WMT", "Walmart Inc."),
+        ("COST", "Costco Wholesale Corporation"),
+        ("CL", "Colgate-Palmolive Company"),
+        ("MDLZ", "Mondelez International Inc."),
+    ],
+    "Communication Services": [
+        ("GOOGL", "Alphabet Inc."),
+        ("META", "Meta Platforms Inc."),
+        ("DIS", "The Walt Disney Company"),
+        ("NFLX", "Netflix Inc."),
+        ("CMCSA", "Comcast Corporation"),
+        ("T", "AT&T Inc."),
+        ("VZ", "Verizon Communications Inc."),
+    ],
+    "Industrials": [
+        ("CAT", "Caterpillar Inc."),
+        ("HON", "Honeywell International Inc."),
+        ("UPS", "United Parcel Service Inc."),
+        ("BA", "The Boeing Company"),
+        ("GE", "General Electric Company"),
+        ("RTX", "RTX Corporation"),
+        ("DE", "Deere & Company"),
+        ("LMT", "Lockheed Martin Corporation"),
+    ],
+    "Energy": [
+        ("XOM", "Exxon Mobil Corporation"),
+        ("CVX", "Chevron Corporation"),
+        ("COP", "ConocoPhillips"),
+        ("SLB", "Schlumberger Limited"),
+        ("EOG", "EOG Resources Inc."),
+        ("OXY", "Occidental Petroleum Corporation"),
+        ("MPC", "Marathon Petroleum Corporation"),
+    ],
+    "Real Estate": [
+        ("AMT", "American Tower Corporation"),
+        ("PLD", "Prologis Inc."),
+        ("CCI", "Crown Castle Inc."),
+        ("EQIX", "Equinix Inc."),
+        ("SPG", "Simon Property Group Inc."),
+        ("O", "Realty Income Corporation"),
+    ],
+    "Utilities": [
+        ("NEE", "NextEra Energy Inc."),
+        ("DUK", "Duke Energy Corporation"),
+        ("SO", "The Southern Company"),
+        ("D", "Dominion Energy Inc."),
+        ("AEP", "American Electric Power Company Inc."),
+        ("SRE", "Sempra"),
+    ],
+    "Basic Materials": [
+        ("LIN", "Linde plc"),
+        ("APD", "Air Products and Chemicals Inc."),
+        ("SHW", "The Sherwin-Williams Company"),
+        ("FCX", "Freeport-McMoRan Inc."),
+        ("NEM", "Newmont Corporation"),
+        ("DOW", "Dow Inc."),
+    ],
+}
+
+
+@tool("Get Peers")
+def get_peers(ticker: str) -> str:
+    """Retrieve sector/industry classification and peer companies for a given ticker.
+    Returns sector, industry, and up to 5 peer companies in the same sector.
+    Use this to contextualize a company's performance relative to competitors."""
+    try:
+        # 1. Input validation
+        valid, result = validate_ticker(ticker)
+        if not valid:
+            return result
+
+        normalized_ticker = result
+
+        # 2. Cache check
+        cache_key = cache.make_key("get_peers", ticker=normalized_ticker)
+        cached = cache.get(cache_key)
+        if cached:
+            return cached
+
+        # 3. Detect crypto/ETFs early by ticker pattern (e.g., BTC-USD, ETH-USD)
+        if "-" in normalized_ticker:
+            return "Peer comparison is not available for this instrument type."
+
+        # 4. External API call
+        yf_ticker = yfinance.Ticker(normalized_ticker)
+        info = yf_ticker.info
+
+        # 5. Check if sector is available (missing for crypto/ETFs)
+        sector = info.get("sector")
+        industry = info.get("industry")
+
+        if not sector:
+            return "Peer comparison is not available for this instrument type."
+
+        # 6. Identify peers from sector mapping, excluding the ticker itself
+        sector_companies = SECTOR_PEERS.get(sector, [])
+        peers = [
+            (sym, name)
+            for sym, name in sector_companies
+            if sym != normalized_ticker
+        ][:5]
+
+        # 7. Format response
+        lines = [f"Peer Analysis for {normalized_ticker}:"]
+        lines.append(f"Sector: {sector}")
+        lines.append(f"Industry: {industry if industry else 'N/A'}")
+
+        if peers:
+            lines.append("Peers:")
+            for sym, name in peers:
+                lines.append(f"- {sym} ({name})")
+        else:
+            lines.append("Peers: No peer data available for this sector.")
+
+        response = "\n".join(lines)
+
+        # 8. Cache and return
+        cache.set(cache_key, response)
+        return response
+
+    except Exception as e:
+        return f"Error: An unexpected error occurred while processing {ticker}: {str(e)}"

tools/market_scanner.py

@@ -0,0 +1,226 @@
+"""
+Market Scanner Tools for FinAgent.
+
+Provides tools for market scanning agents:
+- search_news: Search recent news for a ticker
+- get_price_change: Get current price vs previous close
+- get_volume: Get volume analysis with unusual activity detection
+"""
+
+import yfinance
+from crewai.tools import tool
+from ddgs import DDGS
+
+from tools.cache import TTLCache
+from tools.utils import validate_ticker
+
+cache = TTLCache()
+
+
+@tool("Search News")
+def search_news(ticker: str) -> str:
+    """Search recent news articles for a given ticker symbol.
+
+    Args:
+        ticker: Stock symbol (e.g., AAPL) or crypto pair (e.g., BTC-USD).
+
+    Returns:
+        A formatted string with up to 5 recent news articles including
+        title and snippet, or an error message if something goes wrong.
+    """
+    try:
+        # 1. Input validation
+        valid, result = validate_ticker(ticker)
+        if not valid:
+            return result
+
+        normalized_ticker = result
+
+        # 2. Cache check
+        cache_key = cache.make_key("search_news", ticker=normalized_ticker)
+        cached = cache.get(cache_key)
+        if cached:
+            return cached
+
+        # 3. External API call
+        ddgs = DDGS()
+        articles = ddgs.news(query=normalized_ticker, max_results=5, timelimit="w")
+
+        # 4. Format response
+        if not articles:
+            response = f"No recent news found for {normalized_ticker} in the last 7 days."
+        else:
+            lines = [f"Recent News for {normalized_ticker} (last 7 days):"]
+            for i, article in enumerate(articles[:5], start=1):
+                title = article.get("title", "No title")
+                snippet = article.get("body", "No description available")
+                lines.append(f"{i}. {title} - {snippet}")
+            response = "\n".join(lines)
+
+        # 5. Cache and return
+        cache.set(cache_key, response)
+        return response
+
+    except Exception as e:
+        return f"Error: An unexpected error occurred while processing {ticker}: {str(e)}"
+
+
+@tool("Get Price Change")
+def get_price_change(ticker: str) -> str:
+    """Get current price vs previous close and calculate the change for a ticker.
+
+    Retrieves the current price and previous closing price, then calculates
+    the absolute and percentage change.
+
+    Args:
+        ticker: Stock symbol (e.g., "AAPL") or crypto pair (e.g., "BTC-USD").
+
+    Returns:
+        Formatted string with price change data or error message.
+    """
+    try:
+        # 1. Input validation
+        valid, result = validate_ticker(ticker)
+        if not valid:
+            return result
+
+        normalized_ticker = result
+
+        # 2. Cache check
+        cache_key = cache.make_key("get_price_change", ticker=normalized_ticker)
+        cached = cache.get(cache_key)
+        if cached:
+            return cached
+
+        # 3. External API call
+        stock = yfinance.Ticker(normalized_ticker)
+        info = stock.info
+
+        current_price = info.get("currentPrice")
+        previous_close = info.get("previousClose")
+
+        # Crypto tickers (e.g. BTC-USD) expose regularMarketPrice rather than
+        # currentPrice. Fall back to it when currentPrice is missing.
+        if current_price is None:
+            current_price = info.get("regularMarketPrice")
+
+        # Fall back to history when either value is still unavailable.
+        # Some tickers (notably crypto) only return a single row for a 2-day
+        # lookback because trading is continuous, so also try a longer window.
+        if current_price is None or previous_close is None:
+            hist = stock.history(period="2d")
+            if hist is None or hist.empty:
+                return f"Error: Ticker '{normalized_ticker}' not found. Please verify the symbol."
+            if len(hist) < 2:
+                # Retry with a wider window to recover a previous close.
+                hist = stock.history(period="5d")
+                if hist is None or len(hist) < 2:
+                    return (
+                        f"Error: Ticker '{normalized_ticker}' not found. "
+                        f"Please verify the symbol."
+                    )
+            previous_close = float(hist["Close"].iloc[-2])
+            current_price = float(hist["Close"].iloc[-1])
+
+        # 4. Data validation
+        if previous_close is None or previous_close == 0:
+            return f"Error: Required data unavailable for {normalized_ticker}: previousClose"
+
+        if current_price is None:
+            return f"Error: Required data unavailable for {normalized_ticker}: currentPrice"
+
+        current_price = float(current_price)
+        previous_close = float(previous_close)
+
+        # 5. Calculate change
+        absolute_change = current_price - previous_close
+        percent_change = round(((current_price - previous_close) / previous_close) * 100, 2)
+
+        # 6. Format response
+        sign = "+" if absolute_change >= 0 else "-"
+        abs_change = abs(absolute_change)
+
+        response = (
+            f"Price Change for {normalized_ticker}:\n"
+            f"Current Price: ${current_price:.2f}\n"
+            f"Previous Close: ${previous_close:.2f}\n"
+            f"Change: {sign}${abs_change:.2f} ({'+' if percent_change >= 0 else ''}{percent_change}%)"
+        )
+
+        # 7. Cache and return
+        cache.set(cache_key, response)
+        return response
+
+    except Exception as e:
+        return f"Error: An unexpected error occurred while processing {ticker}: {str(e)}"
+
+
+@tool("Get Volume Analysis")
+def get_volume(ticker: str) -> str:
+    """Get volume analysis with unusual activity detection for a ticker.
+
+    Retrieves current volume and 20-day average volume, calculates the
+    volume ratio, and flags unusual activity when ratio exceeds 2.0.
+
+    Args:
+        ticker: Stock symbol (e.g., "AAPL") or crypto pair (e.g., "BTC-USD").
+
+    Returns:
+        Formatted string with volume analysis or error message.
+    """
+    try:
+        # 1. Input validation
+        valid, result = validate_ticker(ticker)
+        if not valid:
+            return result
+
+        normalized_ticker = result
+
+        # 2. Cache check
+        cache_key = cache.make_key("get_volume", ticker=normalized_ticker)
+        cached = cache.get(cache_key)
+        if cached:
+            return cached
+
+        # 3. External API call
+        stock = yfinance.Ticker(normalized_ticker)
+        hist = stock.history(period="25d")
+
+        if hist.empty or len(hist) < 2:
+            return f"Error: Ticker '{normalized_ticker}' not found. Please verify the symbol."
+
+        if "Volume" not in hist.columns:
+            return f"Error: Required data unavailable for {normalized_ticker}: Volume"
+
+        # 4. Data validation and computation
+        current_volume = int(hist["Volume"].iloc[-1])
+        # Average of prior 20 days (excluding the most recent day)
+        prior_volumes = hist["Volume"].iloc[:-1]
+        # Take up to 20 days for the average
+        prior_20 = prior_volumes.tail(20)
+
+        if len(prior_20) == 0 or prior_20.mean() == 0:
+            return f"Error: Required data unavailable for {normalized_ticker}: insufficient volume history"
+
+        avg_volume_float = prior_20.mean()
+        avg_volume = int(avg_volume_float)
+        volume_ratio = round(current_volume / avg_volume_float, 2)
+
+        # 5. Format response
+        response = (
+            f"Volume Analysis for {normalized_ticker}:\n"
+            f"Current Volume: {current_volume:,}\n"
+            f"20-Day Avg Volume: {avg_volume:,}\n"
+            f"Volume Ratio: {volume_ratio}x"
+        )
+
+        # Include UNUSUAL VOLUME flag when ratio > 2.0
+        if volume_ratio > 2.0:
+            response += "\n⚠️ UNUSUAL VOLUME"
+
+        # 6. Cache and return
+        cache.set(cache_key, response)
+        return response
+
+    except Exception as e:
+        return f"Error: An unexpected error occurred while processing {ticker}: {str(e)}"

tools/risk_manager.py

@@ -0,0 +1,163 @@
+"""
+Risk Manager Tools for FinAgent.
+
+Provides tools for risk management agents:
+- calculate_position_size: Calculate position size based on risk parameters
+- set_stop_loss: Calculate ATR-based stop-loss and take-profit levels
+"""
+
+import math
+
+import yfinance
+
+# pandas-ta-remake is the maintained fork published under a different module
+# name (pandas_ta_remake). Try it first, then fall back to the upstream
+# pandas_ta name if it is what the environment provides.
+try:
+    import pandas_ta_remake as ta  # type: ignore
+except ImportError:  # pragma: no cover - exercised only when remake is absent
+    import pandas_ta as ta  # type: ignore
+
+from crewai.tools import tool
+
+from tools.cache import TTLCache
+from tools.utils import validate_ticker
+
+cache = TTLCache()
+
+
+@tool("Calculate Position Size")
+def calculate_position_size(
+    portfolio_value: float,
+    risk_percent: float,
+    entry_price: float,
+    stop_loss: float,
+) -> str:
+    """Calculate position size based on portfolio risk parameters.
+
+    Args:
+        portfolio_value: Total portfolio value in dollars.
+        risk_percent: Percentage of portfolio to risk (0-100).
+        entry_price: Planned entry price per share.
+        stop_loss: Stop-loss price per share.
+
+    Returns:
+        Formatted string with position size details or error message.
+    """
+    try:
+        # 1. Input validation
+        if portfolio_value <= 0:
+            return "Error: portfolio_value must be positive."
+
+        if entry_price <= 0:
+            return "Error: entry_price must be positive."
+
+        if risk_percent <= 0 or risk_percent > 100:
+            return "Error: risk_percent must be between 0 and 100."
+
+        if entry_price == stop_loss:
+            return "Error: entry_price and stop_loss cannot be equal."
+
+        # 2. Calculate position size (no cache - pure computation)
+        risk_amount = portfolio_value * risk_percent / 100
+        risk_per_share = abs(entry_price - stop_loss)
+        shares = math.floor(risk_amount / risk_per_share)
+        total_position_value = shares * entry_price
+
+        # 3. Format response
+        response = (
+            f"Position Size Calculation:\n"
+            f"Portfolio Value: ${portfolio_value:,.2f}\n"
+            f"Risk Amount: ${risk_amount:,.2f} ({risk_percent}%)\n"
+            f"Entry Price: ${entry_price:,.2f}\n"
+            f"Stop Loss: ${stop_loss:,.2f}\n"
+            f"Risk Per Share: ${risk_per_share:,.2f}\n"
+            f"Position Size: {shares} shares\n"
+            f"Total Position Value: ${total_position_value:,.2f}"
+        )
+
+        return response
+
+    except Exception as e:
+        return f"Error: An unexpected error occurred: {str(e)}"
+
+
+@tool("Set Stop Loss")
+def set_stop_loss(ticker: str, entry_price: float, atr_multiplier: float) -> str:
+    """Calculate ATR-based stop-loss and take-profit levels.
+
+    Uses the 14-period Average True Range (ATR) to determine volatility-based
+    stop-loss and take-profit levels for a given entry price.
+
+    Args:
+        ticker: Stock symbol (e.g., AAPL) or crypto pair (e.g., BTC-USD).
+        entry_price: Entry price for the position.
+        atr_multiplier: Multiplier for ATR (e.g., 1.5, 2.0).
+
+    Returns:
+        Formatted string with stop-loss, take-profit, and risk-reward ratio.
+    """
+    try:
+        # 1. Input validation
+        if atr_multiplier <= 0:
+            return "Error: ATR multiplier must be positive."
+
+        if entry_price <= 0:
+            return "Error: Entry price must be positive."
+
+        valid, result = validate_ticker(ticker)
+        if not valid:
+            return result
+
+        normalized_ticker = result
+
+        # 2. Cache check
+        cache_key = cache.make_key(
+            "set_stop_loss",
+            ticker=normalized_ticker,
+            entry_price=entry_price,
+            atr_multiplier=atr_multiplier,
+        )
+        cached = cache.get(cache_key)
+        if cached:
+            return cached
+
+        # 3. External API call - get price history for ATR calculation
+        stock = yfinance.Ticker(normalized_ticker)
+        df = stock.history(period="30d")
+
+        if df.empty or len(df) < 14:
+            return f"Error: Insufficient data to calculate ATR for {normalized_ticker}."
+
+        # 4. Calculate ATR using pandas_ta
+        atr_series = ta.atr(df["High"], df["Low"], df["Close"], length=14)
+
+        if atr_series is None or atr_series.dropna().empty:
+            return f"Error: Insufficient data to calculate ATR for {normalized_ticker}."
+
+        atr_value = atr_series.dropna().iloc[-1]
+
+        if atr_value != atr_value:  # Check for NaN
+            return f"Error: Insufficient data to calculate ATR for {normalized_ticker}."
+
+        # 5. Calculate stop-loss and take-profit
+        stop_loss_price = round(entry_price - (atr_value * atr_multiplier), 2)
+        take_profit_price = round(entry_price + (atr_value * atr_multiplier * 2), 2)
+
+        # 6. Format response
+        response = (
+            f"Stop-Loss & Take-Profit for {normalized_ticker}:\n"
+            f"Entry Price: ${entry_price:.2f}\n"
+            f"ATR (14-period): ${atr_value:.2f}\n"
+            f"ATR Multiplier: {atr_multiplier}x\n"
+            f"Stop Loss: ${stop_loss_price:.2f} (Entry - ATR \u00d7 {atr_multiplier})\n"
+            f"Take Profit: ${take_profit_price:.2f} (Entry + ATR \u00d7 {atr_multiplier * 2})\n"
+            f"Risk/Reward Ratio: 1:2"
+        )
+
+        # 7. Cache and return
+        cache.set(cache_key, response)
+        return response
+
+    except Exception as e:
+        return f"Error: An unexpected error occurred while processing {ticker}: {str(e)}"

tools/technical_analyst.py

@@ -0,0 +1,289 @@
+"""
+Technical Analyst Tools for FinAgent.
+
+Provides tools for technical analysis agents:
+- get_price_history: Retrieve price history with calculated indicators
+- calculate_indicators: Compute buy/sell signals from technical indicators
+"""
+
+# pandas-ta-remake is the maintained fork published under a different module
+# name (pandas_ta_remake). Try it first, then fall back to the upstream
+# pandas_ta name if it is what the environment provides.
+try:
+    import pandas_ta_remake as ta  # type: ignore
+except ImportError:  # pragma: no cover - exercised only when remake is absent
+    import pandas_ta as ta  # type: ignore
+
+import yfinance
+from crewai.tools import tool
+
+from tools.cache import TTLCache
+from tools.utils import validate_ticker
+
+cache = TTLCache()
+
+
+@tool("Get Price History")
+def get_price_history(ticker: str) -> str:
+    """Retrieve 60 days of price history with technical indicators including RSI, MACD, SMA, and Bollinger Bands.
+
+    Args:
+        ticker: Stock symbol (e.g., AAPL) or crypto pair (e.g., BTC-USD).
+
+    Returns:
+        A formatted table with the last 5 days of price data and indicators,
+        or an error message if data is unavailable.
+    """
+    try:
+        # 1. Input validation
+        valid, result = validate_ticker(ticker)
+        if not valid:
+            return result
+
+        normalized_ticker = result
+
+        # 2. Cache check
+        cache_key = cache.make_key("get_price_history", ticker=normalized_ticker)
+        cached = cache.get(cache_key)
+        if cached:
+            return cached
+
+        # 3. External API call — fetch 90 calendar days to ensure ~60 trading days
+        stock = yfinance.Ticker(normalized_ticker)
+        hist = stock.history(period="90d")
+
+        if hist is None or hist.empty:
+            return f"Error: Ticker '{normalized_ticker}' not found. Please verify the symbol."
+
+        close = hist["Close"]
+        num_days = len(close)
+
+        # 4. Calculate indicators — mark as N/A if insufficient data
+        insufficient_data = num_days < 50
+
+        if insufficient_data:
+            # Not enough data for SMA50; calculate what we can
+            rsi = ta.rsi(close, length=14) if num_days >= 14 else None
+            macd_df = ta.macd(close, fast=12, slow=26, signal=9) if num_days >= 26 else None
+            sma20 = ta.sma(close, length=20) if num_days >= 20 else None
+            sma50 = None
+            bbands_df = ta.bbands(close, length=20, std=2) if num_days >= 20 else None
+        else:
+            rsi = ta.rsi(close, length=14)
+            macd_df = ta.macd(close, fast=12, slow=26, signal=9)
+            sma20 = ta.sma(close, length=20)
+            sma50 = ta.sma(close, length=50)
+            bbands_df = ta.bbands(close, length=20, std=2)
+
+        # 5. Format response — last 5 days of computed data
+        header = (
+            f"Price History & Indicators for {normalized_ticker} (Last 5 Days):\n"
+            f"Date       | Close   | RSI   | MACD  | Signal | SMA20   | SMA50   | BB_Upper | BB_Lower"
+        )
+
+        rows = []
+        last_5_indices = hist.index[-5:]
+
+        for idx in last_5_indices:
+            date_str = idx.strftime("%Y-%m-%d")
+            close_val = f"{close[idx]:.2f}"
+
+            # RSI
+            if rsi is not None and idx in rsi.index and not _is_na(rsi[idx]):
+                rsi_val = f"{rsi[idx]:.1f}"
+            else:
+                rsi_val = "N/A"
+
+            # MACD and Signal
+            if macd_df is not None and idx in macd_df.index:
+                macd_val_raw = macd_df["MACD_12_26_9"][idx]
+                signal_val_raw = macd_df["MACDs_12_26_9"][idx]
+                macd_val = f"{macd_val_raw:.2f}" if not _is_na(macd_val_raw) else "N/A"
+                signal_val = f"{signal_val_raw:.2f}" if not _is_na(signal_val_raw) else "N/A"
+            else:
+                macd_val = "N/A"
+                signal_val = "N/A"
+
+            # SMA20
+            if sma20 is not None and idx in sma20.index and not _is_na(sma20[idx]):
+                sma20_val = f"{sma20[idx]:.2f}"
+            else:
+                sma20_val = "N/A"
+
+            # SMA50
+            if sma50 is not None and idx in sma50.index and not _is_na(sma50[idx]):
+                sma50_val = f"{sma50[idx]:.2f}"
+            else:
+                sma50_val = "N/A"
+
+            # Bollinger Bands
+            if bbands_df is not None and idx in bbands_df.index:
+                bbu_raw = bbands_df["BBU_20_2.0"][idx]
+                bbl_raw = bbands_df["BBL_20_2.0"][idx]
+                bbu_val = f"{bbu_raw:.2f}" if not _is_na(bbu_raw) else "N/A"
+                bbl_val = f"{bbl_raw:.2f}" if not _is_na(bbl_raw) else "N/A"
+            else:
+                bbu_val = "N/A"
+                bbl_val = "N/A"
+
+            row = (
+                f"{date_str} | {close_val:>7} | {rsi_val:>5} | {macd_val:>5} | "
+                f"{signal_val:>6} | {sma20_val:>7} | {sma50_val:>7} | {bbu_val:>8} | {bbl_val:>8}"
+            )
+            rows.append(row)
+
+        response = header + "\n" + "\n".join(rows)
+
+        # 6. Cache and return
+        cache.set(cache_key, response)
+        return response
+
+    except Exception as e:
+        return f"Error: An unexpected error occurred while processing {ticker}: {str(e)}"
+
+
+def _is_na(value) -> bool:
+    """Check if a value is NaN or None."""
+    if value is None:
+        return True
+    try:
+        import math
+        return math.isnan(value)
+    except (TypeError, ValueError):
+        return False
+
+
+@tool("Calculate Indicators")
+def calculate_indicators(ticker: str) -> str:
+    """Compute current buy/sell signals from RSI, MACD, and Bollinger Bands for a given ticker.
+
+    Args:
+        ticker: Stock symbol (e.g., AAPL) or crypto pair (e.g., BTC-USD).
+
+    Returns:
+        A formatted string with each indicator's current value and signal classification
+        (BUY, SELL, or NEUTRAL), or an error message if data is unavailable.
+    """
+    try:
+        # 1. Input validation
+        valid, result = validate_ticker(ticker)
+        if not valid:
+            return result
+
+        normalized_ticker = result
+
+        # 2. Cache check
+        cache_key = cache.make_key("calculate_indicators", ticker=normalized_ticker)
+        cached = cache.get(cache_key)
+        if cached:
+            return cached
+
+        # 3. External API call — fetch 90 calendar days to ensure ~60 trading days
+        stock = yfinance.Ticker(normalized_ticker)
+        hist = stock.history(period="90d")
+
+        if hist is None or hist.empty:
+            return f"Error: Ticker '{normalized_ticker}' not found. Please verify the symbol."
+
+        close = hist["Close"]
+        num_days = len(close)
+
+        if num_days < 26:
+            return f"Error: Insufficient data for {normalized_ticker}. Need at least 26 trading days."
+
+        # 4. Calculate indicators
+        rsi_series = ta.rsi(close, length=14)
+        macd_df = ta.macd(close, fast=12, slow=26, signal=9)
+        bbands_df = ta.bbands(close, length=20, std=2)
+
+        # Get current values
+        current_rsi = rsi_series.iloc[-1] if rsi_series is not None else None
+        current_close = close.iloc[-1]
+
+        # MACD values
+        if macd_df is not None:
+            current_macd = macd_df["MACD_12_26_9"].iloc[-1]
+            current_signal = macd_df["MACDs_12_26_9"].iloc[-1]
+            prev_macd = macd_df["MACD_12_26_9"].iloc[-2]
+            prev_signal = macd_df["MACDs_12_26_9"].iloc[-2]
+        else:
+            current_macd = None
+            current_signal = None
+            prev_macd = None
+            prev_signal = None
+
+        # Bollinger Band values
+        if bbands_df is not None:
+            current_upper = bbands_df["BBU_20_2.0"].iloc[-1]
+            current_lower = bbands_df["BBL_20_2.0"].iloc[-1]
+        else:
+            current_upper = None
+            current_lower = None
+
+        # 5. Classify signals
+        # RSI classification
+        if current_rsi is not None and not _is_na(current_rsi):
+            if current_rsi < 30:
+                rsi_signal = "BUY"
+                rsi_desc = "Oversold"
+            elif current_rsi > 70:
+                rsi_signal = "SELL"
+                rsi_desc = "Overbought"
+            else:
+                rsi_signal = "NEUTRAL"
+                rsi_desc = "Neutral"
+            rsi_line = f"RSI (14): {current_rsi:.1f} → {rsi_signal} ({rsi_desc})"
+        else:
+            rsi_line = "RSI (14): N/A → NEUTRAL (Insufficient Data)"
+
+        # MACD classification
+        if (current_macd is not None and current_signal is not None and
+                prev_macd is not None and prev_signal is not None and
+                not _is_na(current_macd) and not _is_na(current_signal) and
+                not _is_na(prev_macd) and not _is_na(prev_signal)):
+            is_bullish = current_macd > current_signal and prev_macd <= prev_signal
+            is_bearish = current_macd < current_signal and prev_macd >= prev_signal
+
+            if is_bullish:
+                macd_signal = "BUY"
+                macd_desc = "Bullish Crossover"
+            elif is_bearish:
+                macd_signal = "SELL"
+                macd_desc = "Bearish Crossover"
+            else:
+                macd_signal = "NEUTRAL"
+                macd_desc = "Neutral"
+            macd_line = f"MACD: {current_macd:.2f} / Signal: {current_signal:.2f} → {macd_signal} ({macd_desc})"
+        else:
+            macd_line = "MACD: N/A / Signal: N/A → NEUTRAL (Insufficient Data)"
+
+        # Bollinger classification
+        if (current_upper is not None and current_lower is not None and
+                not _is_na(current_upper) and not _is_na(current_lower)):
+            if current_close < current_lower:
+                bb_signal = "BUY"
+                bb_desc = "Below Lower Band"
+            elif current_close > current_upper:
+                bb_signal = "SELL"
+                bb_desc = "Above Upper Band"
+            else:
+                bb_signal = "NEUTRAL"
+                bb_desc = "Neutral"
+            bb_line = f"Bollinger: Price ${current_close:.2f} / Upper ${current_upper:.2f} / Lower ${current_lower:.2f} → {bb_signal} ({bb_desc})"
+        else:
+            bb_line = "Bollinger: N/A → NEUTRAL (Insufficient Data)"
+
+        # 6. Format response
+        response = (
+            f"Technical Signals for {normalized_ticker}:\n"
+            f"{rsi_line}\n"
+            f"{macd_line}\n"
+            f"{bb_line}"
+        )
+
+        # 7. Cache and return
+        cache.set(cache_key, response)
+        return response
+
+    except Exception as e:
+        return f"Error: An unexpected error occurred while processing {ticker}: {str(e)}"

tools/utils.py

@@ -0,0 +1,114 @@
+"""
+Utility functions for Agent Tools.
+
+Provides shared helpers: ticker validation, currency formatting,
+safe dictionary access, and percentage formatting.
+"""
+
+
+def validate_ticker(ticker: str) -> tuple[bool, str]:
+    """Validate and normalize a ticker string.
+
+    Strips whitespace from input. If empty or whitespace-only after strip,
+    returns an error tuple. Otherwise returns the uppercase normalized ticker.
+
+    Args:
+        ticker: Raw ticker string from user/agent input.
+
+    Returns:
+        (True, normalized_ticker) if valid
+        (False, error_message) if invalid
+    """
+    stripped = ticker.strip()
+    if not stripped:
+        return (False, "Error: Invalid ticker provided. Ticker must be a non-empty string.")
+    return (True, stripped.upper())
+
+
+def format_currency(value: float, precision: int = 2) -> str:
+    """Format monetary values with appropriate units (B/M/K).
+
+    Args:
+        value: The monetary value to format. If None, returns "N/A".
+        precision: Number of decimal places (default 2).
+
+    Returns:
+        Formatted string like "$1.50B", "$250.00M", "$45.00K", or "$123.45".
+
+    Examples:
+        >>> format_currency(1_500_000_000)
+        '$1.50B'
+        >>> format_currency(250_000_000)
+        '$250.00M'
+        >>> format_currency(45_000)
+        '$45.00K'
+        >>> format_currency(123.456)
+        '$123.46'
+        >>> format_currency(None)
+        'N/A'
+    """
+    if value is None:
+        return "N/A"
+
+    abs_value = abs(value)
+    sign = "-" if value < 0 else ""
+
+    if abs_value >= 1_000_000_000:
+        return f"{sign}${abs_value / 1_000_000_000:.{precision}f}B"
+    elif abs_value >= 1_000_000:
+        return f"{sign}${abs_value / 1_000_000:.{precision}f}M"
+    elif abs_value >= 1_000:
+        return f"{sign}${abs_value / 1_000:.{precision}f}K"
+    else:
+        return f"{sign}${abs_value:.{precision}f}"
+
+
+def safe_get(info: dict, key: str, default: str = "N/A") -> str:
+    """Safely extract a value from a dict, returning default if missing or None.
+
+    Args:
+        info: Dictionary to look up.
+        key: Key to retrieve.
+        default: Value to return if key is missing or value is None.
+
+    Returns:
+        String representation of the value, or default.
+    """
+    value = info.get(key)
+    if value is None:
+        return default
+    return str(value)
+
+
+def format_percent(value: float, precision: int = 2) -> str:
+    """Format a decimal or percentage value as a string with % sign.
+
+    If value is None, returns "N/A". If value appears to be a decimal
+    (absolute value less than 1), it is multiplied by 100 first to
+    convert to a percentage.
+
+    Args:
+        value: The value to format. Decimals (e.g., 0.082) are converted
+               to percentages (8.20%). Values >= 1 are treated as already
+               being percentages.
+        precision: Number of decimal places (default 2).
+
+    Returns:
+        Formatted string like "8.20%" or "N/A".
+
+    Examples:
+        >>> format_percent(0.082)
+        '8.20%'
+        >>> format_percent(25.5)
+        '25.50%'
+        >>> format_percent(None)
+        'N/A'
+    """
+    if value is None:
+        return "N/A"
+
+    # If value is a decimal (abs < 1), multiply by 100 to get percentage
+    if abs(value) < 1:
+        value = value * 100
+
+    return f"{value:.{precision}f}%"

validation.py

@@ -0,0 +1,112 @@
+"""Input validation module for the FinAgent Gradio frontend.
+
+Provides pure validation functions (no Gradio dependencies) for ticker
+symbols and portfolio value inputs. These functions are used by the
+event handlers in ``app.py`` and are directly testable in isolation.
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+# Valid ticker characters: letters, digits, hyphens, periods.
+TICKER_PATTERN = re.compile(r"^[A-Za-z0-9\-\.]+$")
+
+# Maximum number of tickers allowed per analysis run.
+MAX_TICKERS = 10
+
+
+@dataclass
+class ValidationResult:
+    """Result of input validation.
+
+    Attributes:
+        valid: Whether the input passed all validation checks.
+        tickers: Normalized (trimmed, uppercased) ticker list. Empty if invalid.
+        error_message: Human-readable error message. ``None`` when valid.
+    """
+
+    valid: bool
+    tickers: list[str] = field(default_factory=list)
+    error_message: Optional[str] = None
+
+
+def validate_tickers(raw_input: str) -> ValidationResult:
+    """Validate and normalize a comma-separated ticker input string.
+
+    Rules enforced:
+        - Input must not be empty or whitespace-only
+        - Each ticker is trimmed and converted to uppercase
+        - Empty segments after splitting on commas are discarded
+        - Only letters, digits, hyphens, and periods are allowed
+        - Maximum of ``MAX_TICKERS`` tickers per submission
+
+    Args:
+        raw_input: Raw user input string (e.g., ``"aapl, nvda, tsla"``).
+
+    Returns:
+        A ``ValidationResult`` with normalized tickers on success, or an
+        error message on failure.
+    """
+    # Reject empty or whitespace-only input early.
+    if not raw_input or not raw_input.strip():
+        return ValidationResult(
+            valid=False,
+            tickers=[],
+            error_message="Please enter at least one ticker symbol.",
+        )
+
+    # Split, trim, uppercase, and drop empty segments (e.g., trailing commas).
+    raw_tickers = [segment.strip().upper() for segment in raw_input.split(",")]
+    tickers = [t for t in raw_tickers if t]
+
+    if not tickers:
+        return ValidationResult(
+            valid=False,
+            tickers=[],
+            error_message="Please enter at least one ticker symbol.",
+        )
+
+    # Character validation — collect every ticker that contains disallowed chars.
+    invalid_tickers: list[str] = []
+    for ticker in tickers:
+        if not TICKER_PATTERN.match(ticker):
+            invalid_chars = sorted(set(re.findall(r"[^A-Za-z0-9\-\.]", ticker)))
+            invalid_tickers.append(f"{ticker} (invalid: {''.join(invalid_chars)})")
+
+    if invalid_tickers:
+        return ValidationResult(
+            valid=False,
+            tickers=[],
+            error_message=f"Invalid characters in: {', '.join(invalid_tickers)}",
+        )
+
+    # Enforce maximum ticker count.
+    if len(tickers) > MAX_TICKERS:
+        return ValidationResult(
+            valid=False,
+            tickers=[],
+            error_message=(
+                f"Maximum {MAX_TICKERS} tickers per analysis. "
+                f"You entered {len(tickers)}."
+            ),
+        )
+
+    return ValidationResult(valid=True, tickers=tickers, error_message=None)
+
+
+def validate_portfolio_value(value: float) -> Optional[str]:
+    """Validate a portfolio value.
+
+    A portfolio value is considered valid when it is non-negative (``>= 0``).
+    Negative values are rejected with a human-readable error message.
+
+    Args:
+        value: The portfolio value to validate.
+
+    Returns:
+        An error message string if the value is invalid, or ``None`` if valid.
+    """
+    if value < 0:
+        return "Portfolio value must be non-negative."
+    return None