• investment_workflow.py: Main investment analysis workflow orchestrating multiple specialized agents
• investment_executors.py: Individual agent implementations (Financial, Risk, Market, Compliance analysts)
• prompts/: Agent-specific prompt templates for consistent analysis

2. Frontend Web Application (web-app/)

A modern React-based single-page application providing an intuitive user interface.

Core Technologies:

• React 18 with TypeScript
• Vite: Fast build tool and dev server
• Shadcn/ui: Beautiful, accessible UI component library
• Tailwind CSS: Utility-first CSS framework
• Lucide React: Icon library

Key Features:

• Dashboard for managing investment opportunities
• Document upload and processing interface
• Real-time analysis progress visualization with agent workflow diagrams
• Interactive chat interface for what-if scenarios
• Responsive design for desktop and mobile

Main Pages:

• Index.tsx: Landing page with feature showcase
• NewOpportunity.tsx / EditOpportunity.tsx: Opportunity management
• ProcessDocuments.tsx: Document upload and processing
• Analysis.tsx: Analysis execution and visualization

3. AI Agent Workflow

The system uses a sophisticated multi-agent architecture:

Investment Analysis Workflow:

Data Preparation → [Financial Analyst, Risk Analyst, Market Analyst, Compliance Analyst] 
→ Analysis Aggregator → Investment Debate Executor → Summary Report Generator

Each agent:

• Has specialized knowledge and analysis focus
• Receives contextual prompts from prompt templates
• Processes in parallel where possible (fan-out pattern)
• Results are aggregated and synthesized
• Agents engage in a debate to challenge assumptions
• Final summary report is generated

What-If Chat Workflow:

Planning Agent → [Financial, Risk, Market, Compliance Agents] → Analysis Summarizer

• Interprets user questions and scenarios
• Routes to relevant specialist agents
• Synthesizes responses into coherent answers
• Maintains conversation context across turns

4. Event Streaming Architecture

The application uses Server-Sent Events (SSE) for real-time updates:

• Event Queue System (app/utils/sse_stream_event_queue.py): In-memory queue for managing events per analysis
• Event Types: workflow_started, agent_started, agent_progress, agent_completed, workflow_completed
• Client Subscription: Frontend subscribes to /api/analysis/{id}/events endpoint
• Historical Events: New subscribers receive historical events before live updates
• Background Processing: Analysis runs in FastAPI background tasks while streaming events

📦 Prerequisites

• Python 3.11+ (3.13 recommended)
• Node.js 18+ and npm
• Azure Account with:
  • Azure Cosmos DB instance
  • Azure Blob Storage account
  • Azure OpenAI service with a deployed chat model
• Environment Variables: See Configuration section below

⚙️ Configuration

Backend Environment Variables

Create a .env file in the api-app/ directory:

# API Server Settings
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8084
API_SERVER_WORKERS=1
LOG_LEVEL=DEBUG
DEBUG=True
ENVIRONMENT=development

# Azure Cosmos DB
COSMOS_DB_ENDPOINT=https://<your-cosmos-account>.documents.azure.com:443/
COSMOS_DB_DATABASE_NAME=ai-investment-analysis-sample

# Azure Blob Storage
AZURE_STORAGE_ACCOUNT_NAME=your-storage-account
AZURE_STORAGE_CONTAINER_NAME=opportunity-documents

# Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://<ai-foundry-resource>.cognitiveservices.azure.com/openai/deployments/<deployment_name>/chat/completions?api-version=2025-01-01-preview
AZURE_OPENAI_DEPLOYMENT_NAME=<model-deployment-name>

Frontend Environment Variables

Create a .env file in the web-app/ directory:

VITE_API_BASE_URL=http://localhost:8084/api

🚀 Running Locally

1. Backend API Setup

# Navigate to the api-app directory
cd api-app

# Create and activate a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Ensure your .env file is configured (see Configuration section)

# Run the FastAPI server
python main.py

# The API will be available at http://localhost:8084
# API documentation at http://localhost:8084/docs

Alternative: Run with uvicorn directly

uvicorn main:app --host 0.0.0.0 --port 8084 --reload

2. Frontend Web Application Setup

Open a new terminal window:

# Navigate to the web-app directory
cd web-app

# Install dependencies
npm install

# Ensure your .env file is configured (see Configuration section)

# Start the development server
npm run dev

# The web app will be available at http://localhost:8080

3. Azure Services Setup

Cosmos DB:

1. Create a Cosmos DB account with NoSQL API

2. The application will automatically create the database and containers on first run

3. Ensure your connection endpoint is in the .env file

4. Ensure proper access permissions on Cosmos DB account:

   Follow the steps in this article: Connect to Azure Cosmos DB for NoSQL using role-based access control and Microsoft Entra ID

Blob Storage:

1. Create a Storage Account
2. Create a container named opportunity-documents (or your chosen name)
3. Ensure proper access permissions (Storage Blob Data Contributor role)

Azure AI Foundry:

1. Deploy an Azure AI Foundry resource - or connect directly to an existing one if available
2. Deploy a chat model (e.g., GPT-4.1, GPT-4.1-mini)
3. Note the endpoint and deployment name
4. Ensure proper access permissions (Azure AI User role)

4. Authentication

For local development with Azure services, authenticate using Azure CLI:

az login

The application uses DefaultAzureCredential which supports:

• Azure CLI authentication (for local development)
• Managed Identity (for Azure deployments)
• Environment variables
• Interactive browser authentication

💡 Using the Application

1. Create an Investment Opportunity

• Navigate to the home page
• Click "New Opportunity" or go to /opportunity/new
• Fill in the investment details:
  • Company name
  • Investment hypothesis
  • Investment stage
  • Industry
  • Initial investment amount
  • Description

2. Process Documents

• After creating an opportunity, upload relevant documents:
  • Financial statements
  • Pitch decks
  • Market research
  • Due diligence documents
• The system will automatically extract and analyze the content
• Monitor real-time processing progress

3. Run Investment Analysis

• From the opportunity detail page, click "Start Analysis"
• Watch as specialized AI agents analyze the opportunity:
  • Data preparation and context loading
  • Parallel analysis by Financial, Risk, Market, and Compliance agents
  • Agent debate to challenge assumptions
  • Final summary report generation
• View real-time progress and intermediate results via SSE streaming

4. Explore What-If Scenarios

• After analysis completes, use the chat interface
• Ask hypothetical questions like:
  • "What if the market growth is 10% slower?"
  • "How would a 20% increase in costs affect the ROI?"
  • "What are the compliance risks if we expand to Europe?"
• Get instant analysis from relevant specialist agents

📁 Project Structure

agentic-ai-investment-analysis-sample/
├── api-app/                          # Backend FastAPI application
│   ├── main.py                       # Application entry point
│   ├── requirements.txt              # Python dependencies
│   ├── run_investment_workflow.py    # Workflow testing script
│   ├── run_what_if_chat.py          # Chat testing script
│   └── app/
│       ├── core/                     # Core configuration
│       ├── database/                 # Database clients and repositories
│       ├── models/                   # Pydantic data models
│       ├── routers/                  # FastAPI route handlers
│       ├── services/                 # Business logic layer
│       ├── utils/                    # Utility functions
│       ├── workflow/                 # Investment analysis workflow
│       │   ├── investment_workflow.py
│       │   ├── investment_executors.py
│       │   ├── investment_models.py
│       │   └── prompts/             # Agent promp