A submission for the Agentic AI Developer Certification Program (Module 3)

Author: Chidambara Raju G
Version: 2.0
Project Repository: Capital Compass

This publication details the evolution of Capital Compass, a multi-agent financial research application, from its initial prototype (Module 2) into a robust, production-ready system. The focus is on the specific enhancements made in testing, safety, user interface design, and operational resilience to meet the demands of a real-world application.

🏗️ The Foundation: An Agentic Research System (Module 2 Recap)

The initial version of Capital Compass was developed as a proof-of-concept for an automated investment research tool. It was built on a sophisticated multi-agent architecture using LangGraph to orchestrate specialized AI agents that could reason, analyze, and synthesize a final investment report.

🎯 Workflow Diagram

%%{init: {
  "theme": "dark",
  "themeVariables": {
    "primaryColor": "#0b1220",
    "primaryTextColor": "#E5E7EB",
    "primaryBorderColor": "#93C5FD",
    "lineColor": "#93C5FD",
    "tertiaryColor": "#111827",
    "fontSize": "12px",          /* Slightly smaller text */
    "padding": 12,               /* More space inside nodes */
    "nodeSpacing": 60,           /* Wider horizontal spacing */
    "rankSpacing": 60,           /* Wider vertical spacing */
    "fontFamily": "Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto"
  }
}}%%

graph TD
    A[Start:<br/>User Enters Ticker] --> B[Fetch:<br/>Financial Overview]
    A --> C[Fetch:<br/>News & Sentiment]
    A --> I[Fetch:<br/>Web Search]

    B --> D{Analyze:<br/>Financials}
    C --> E{Analyze:<br/>Sentiment}
    I --> J{Summarize:<br/>Web Research}

    D --> F[Balanced Review:<br/>Risk & Opportunity]
    E --> F
    J --> F

    F --> G[Final Synthesis:<br/>Generate Report]
    G --> H[End:<br/>Display Report]

    %% Dark-friendly styles
    classDef fetch fill:#0F172A,stroke:#818CF8,color:#E5E7EB,stroke-width:2px
    classDef websearch fill:#1E1B4B,stroke:#A5B4FC,color:#E5E7EB,stroke-width:2px
    classDef analyze fill:#111827,stroke:#60A5FA,color:#E5E7EB,stroke-width:2px
    classDef critic fill:#1F0A0A,stroke:#FCA5A5,color:#FEE2E2,stroke-width:2px
    classDef final fill:#052E2B,stroke:#34D399,color:#D1FAE5,stroke-width:2px
    classDef default fill:#0B1220,stroke:#93C5FD,color:#E5E7EB,stroke-width:1.5px

    class B,C fetch
    class I websearch
    class J analyze
    class D,E analyze
    class F critic
    class G final

Core Workflow:

• 🔍 Parallel Information Gathering: Fetching financial data, news sentiment, and web search results simultaneously.
• 📊 Specialized Analysis: Agents for financial, sentiment, and web data interpreted and summarized the raw information.
• ⚖️ Balanced Review: A Risk & Opportunity agent distilled these analyses into a core thesis.
• 🧑‍💼 Final Synthesis: A Senior Advisor agent combined all inputs to produce a structured investment report.

📄 The full report on the initial design and architecture is available in the Module 2 publication: Capital Compass Publication

While functional, the prototype lacked the robustness required for deployment. The goal of this module was to bridge that gap by hardening the system for reliability, safety, and production readiness.

🚀 The Path to Production: Module 3 Enhancements

To transform Capital Compass into a production-ready application, the following four critical areas were addressed:

1. A pragmatic testing strategy
2. Safety & error resilience
3. A polished user interface
4. Monitoring & observability

1. ✅ A Pragmatic and Multi-Layered Testing Strategy

Professional-grade applications demand verifiable reliability. A pytest-based testing strategy was implemented covering both individual components and the full system.

🔧 Integration Testing with Live LLMs

• Tests in tests/test_analysis_agents.py ensure each agent processes its inputs and produces valid outputs.
• Static mock API data (managed in conftest.py) is used for consistency.
• Live LLM calls are retained to validate prompts against the non-deterministic nature of real models.

🔄 End-to-End (E2E) Testing

• tests/test_e2e_workflow.py runs the full LangGraph workflow with a real stock ticker.
• Tests confirm:
  • The complete graph runs without errors.
  • The final report is valid and non-empty.
  • Recommendations are one of the predefined, valid outputs.

This layered approach ensures both component integrity and system-wide reliability.

2. 🛡️ Safety & Resilience Through Edge Case Handling

Beyond basic error handling, the system was made robust against unpredictable input and API behavior.

🧩 Custom Exception Handling

# capital_compass/exceptions.py
class APIClientError(Exception):
    """Custom exception for errors related to the API client."""
    pass

🔍 Pre-emptive Input Validation

Before hitting the backend, the Streamlit UI validates ticker input with a regex:

if not re.match(r"^[A-Z]{1,5}(\.[A-Z]{1,2})?$", ticker):
    st.error("Invalid ticker format...")

⚠️ Graceful API Error Handling

# tools/alpha_vantage_client.py
def get_company_overview(ticker: str) -> dict:
    data = response.json()
    if not data or "Error Message" in data:
        raise APIClientError(f"Ticker '{ticker}' not found or is invalid.")

3. 🎨 A Polished and Performant User Interface

The Streamlit UI was refined for clarity, speed, and user trust.

import streamlit as st
import re
from capital_compass.graph import app  # Import the compiled LangGraph app
from capital_compass.exceptions import APIClientError

# --- Page Configuration ---
st.set_page_config(
    page_title="Capital Compass",
    page_icon="🧭",
    layout="wide",
    initial_sidebar_state="expanded",
)

# --- Sidebar Content ---
with st.sidebar:
    st.image("assets/logo.png", width=200)
    st.header("About Capital Compass")
    st.info(
        "Capital Compass is an AI-powered investment research tool that "
        "synthesizes financial data and market news to generate a comprehensive "
        "investment report for any given stock ticker."
    )
    st.markdown("---")
    st.subheader("Technology Stack")
    st.markdown(
        """
        - **UI:** Streamlit
        - **Orchestration:** LangGraph
        - **LLMs:** Groq (Multi-model)
        - **Data:** Alpha Vantage
        """
    )

# --- Main Application UI ---
st.title("Capital Compass 🧭")
st.markdown("Your AI-powered co-pilot for investment research. Enter a stock ticker to begin.")
st.info("This is an AI-generated report and should not be considered financial advice. Always conduct your own research and consult with a professional financial advisor.")

# --- User Input ---
ticker = st.text_input(
    "Enter a stock ticker symbol (e.g., AAPL, NVDA, TSLA)",
    value="NVDA",
    max_chars=10,
    help="Provide the ticker symbol for the company you want to analyze."
).upper()

# --- Analysis Trigger ---
if st.button("Generate Investment Report", type="primary"):
    # 1. Pre Validation: Check the ticker format before calling the API
    # This regex checks for 1-5 uppercase letters, optionally followed by a dot and 1-2 letters (for non-US exchanges)
    if not re.match(r"^[A-Z]{1,5}(\.[A-Z]{1,2})?$", ticker):
        st.error("Invalid ticker format. Please enter a valid stock symbol (e.g., 'AAPL', 'MSFT').")
    # 2. Validate non-empty input
    elif not ticker:
        st.warning("Please enter a stock ticker to proceed.")
    else:
        # 3. Run the LangGraph agent with a loading spinner
        with st.spinner(f"Analyzing {ticker}... This may take a moment."):
            try:
                # 4. Define the initial state and invoke the graph
                initial_state = {"company_ticker": ticker}
                final_state = app.invoke(initial_state, {"recursion_limit": 10})
                
                # 5. Display the final report
                st.markdown("---")
                st.subheader(f"Investment Report for {ticker}")
                st.markdown(final_state.get("final_report", "No report was generated."))

            except APIClientError as e:
                # 6. Handle specific API errors gracefully
                st.error(f"Failed to fetch data: {e}")
            except Exception as e:
                # 7. Handle other unexpected errors
                st.error(f"An unexpected error occurred: {e}")

4. 📊 Monitoring & Observability with LangSmith

Operational resilience is achieved with LangSmith integration, enabling:

• Trace Every Run: Visualize the execution graph with agent inputs/outputs.
• Debug Failures: Pinpoint failing nodes and problematic data.
• Optimize Performance: Monitor latency and token usage per agent.

⚙️ Setup and Installation

Follow these steps to get a local copy running:

Prerequisites

• Python 3.11+
• Alpha Vantage API Key
• Groq API Key
• Tavily API Key
• Langsmith API Key

Installation

Clone the repository:

git clone https://github.com/ChidambaraRaju/capital-compass
cd capital-compass

Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Set up environment variables:

Create a .env file in the project root with:

ALPHAVANTAGE_API_KEY="YOUR_ALPHA_VANTAGE_KEY"
GROQ_API_KEY="YOUR_GROQ_API_KEY"
TAVILY_API_KEY="YOUR_TAVILY_API_KEY"
LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
LANGSMITH_API_KEY="YOUR_LANGSMITH_API_KEY"
LANGSMITH_PROJECT="project-name"

▶️ Usage

Run the Streamlit app from the root directory:

streamlit run main.py

📁 Project Structure

.
├── assets/
│   └── logo.png
├── capital_compass/
│   ├── agents/
│   │   ├── analysis_agents.py
│   │   └── data_fetcher.py
│   ├── tools/
│   │   ├── alpha_vantage_client.py
│   │   └── tavily_search_tool.py
│   ├── tests/
│   │   ├── conftest.py
│   │   ├── pytest.ini
│   │   ├── test_analysis_agents.py
│   │   └── test_e2e_workflow.py
│   ├── exceptions.py
│   ├── graph.py
│   └── state.py
├── .env
├── main.py
└── requirements.txt

📜 License

This project is released under the MIT License.

Permission is granted, free of charge, to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of this software, provided that proper credit is given.

⚠️ Disclaimer: Capital Compass is an AI-powered research assistant. Reports are not financial advice. Always do independent research before making investment decisions.

🔮 Conclusion

Capital Compass evolved from a fragile prototype into a production-grade, resilient multi-agent system. Through structured testing, robust error handling, user-centric design, and operational monitoring, it now provides a dependable research companion for exploring financial markets.

This journey highlights the transformation from experimental agentic systems into deployable, user-ready applications — a crucial step for any real-world AI-powered product.

✨ Capital Compass is not just a proof-of-concept anymore. It’s a reliable compass for navigating complex financial data. 🧭