financial-researcher

# Financial Researcher 🔍📈

> An AI-powered multi-agent system that researches any publicly traded company and delivers a polished financial analysis report — in minutes.

Built with [CrewAI](https://crewai.com), it orchestrates two specialised AI agents that work in sequence: one scours the web for real-time data, the other synthesises those findings into a professional-grade Markdown report.

---

## Table of Contents

- [Demo](#demo)
- [How It Works](#how-it-works)
- [CrewAI Concepts Explained](#crewai-concepts-explained)
  - [Agent](#-agent)
  - [Task](#-task)
  - [Crew](#-crew)
  - [Process — Sequential vs Hierarchical](#-process--sequential-vs-hierarchical)
  - [Tools](#-tools)
- [Project Structure](#project-structure)
- [Agents & Tasks in This Project](#agents--tasks-in-this-project)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Running the Crew](#running-the-crew)
- [Sample Output](#sample-output)
- [Contributing](#contributing)
- [License](#license)

---

## Demo

```
$ crewai run

Enter the company to research: Apple

[Researcher Agent] Searching the web for Apple financial data...
[Analyst Agent] Synthesising research into a comprehensive report...

=== FINAL REPORT ===

# Comprehensive Report on Apple Inc.
As of 2026-03-24 ...

Report has been saved to output/report.md
```

---

## How It Works

```
┌─────────────────────────────────────────────────────────────┐
│                        USER INPUT                           │
│                   "Enter company name"                      │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    CREW  (Sequential)                       │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  STEP 1 — Research Task                              │   │
│  │  Agent: Senior Financial Researcher                  │   │
│  │  Tool:  SerperDevTool (Google Search)                │   │
│  │  Output: Structured research document                │   │
│  └──────────────────────────┬───────────────────────────┘   │
│                             │  context passed downstream    │
│  ┌──────────────────────────▼───────────────────────────┐   │
│  │  STEP 2 — Analysis Task                              │   │
│  │  Agent: Market Analyst & Report Writer               │   │
│  │  Tool:  (none — works from research context)         │   │
│  │  Output: output/report.md                            │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

---

## CrewAI Concepts Explained

### 🤖 Agent

An **Agent** is an autonomous AI entity with a specific **role**, **goal**, and **backstory**. Think of it as hiring a specialist for a job — you describe who they are, what they're trying to achieve, and the context that shapes their expertise. Each agent is backed by an LLM and can optionally be equipped with tools to interact with the outside world.

| Property    | Purpose |
|-------------|---------|
| `role`      | The agent's job title / persona (e.g., *Senior Financial Researcher*) |
| `goal`      | What the agent is trying to accomplish |
| `backstory` | Background context that shapes the agent's reasoning style |
| `llm`       | The language model powering the agent |
| `tools`     | External capabilities the agent can invoke (search, code execution, APIs…) |
| `verbose`   | Prints the agent's chain-of-thought reasoning to the console |

```yaml
# config/agents.yaml
researcher:
  role: Senior Financial Researcher for {company}
  goal: Research the company, news and potential for {company}
  backstory: You're a seasoned financial researcher...
  llm: openai/gpt-4o-mini
```

---

### 📋 Task

A **Task** is a specific piece of work assigned to an agent. It defines *what* needs to be done, what a successful result looks like, and which agent is responsible. Tasks can receive the output of previous tasks as **context**, enabling agents to build on each other's work.

| Property          | Purpose |
|-------------------|---------|
| `description`     | Detailed instructions for what to do |
| `expected_output` | Describes what a complete, correct result looks like |
| `agent`           | Which agent is assigned to this task |
| `context`         | List of prior tasks whose output is fed into this task |
| `output_file`     | (Optional) Persist the result to a file |

```yaml
# config/tasks.yaml
analysis_task:
  description: Analyze the research findings and create a comprehensive report...
  expected_output: A polished, professional report...
  agent: analyst
  context:
    - research_task          # ← analyst reads the researcher's full output
  output_file: output/report.md
```

---

### 🚢 Crew

A **Crew** is the team — it binds agents and tasks together under a shared **process** (execution strategy). The crew is responsible for scheduling tasks, routing context between them, and collecting the final result.

```python
@crew
def crew(self) -> Crew:
    return Crew(
        agents=self.agents,   # [researcher, analyst]
        tasks=self.tasks,     # [research_task, analysis_task]
        process=Process.sequential,
        verbose=True,
    )
```

Kickoff the crew with dynamic inputs:

```python
ResearchCrew().crew().kickoff(inputs={"company": "Apple", "date": "2026-03-24"})
```

---

### ⚙️ Process — Sequential vs Hierarchical

The **Process** controls how tasks are executed relative to each other.

#### `Process.sequential` *(used in this project)*

Tasks run **one after another**, in the order they are defined. The output of each task is automatically passed as context to the next. Simple, predictable, and great for linear pipelines.

```
Task 1 ──► Task 2 ──► Task 3 ──► Final Result
```

#### `Process.hierarchical`

A designated **manager agent** (or manager LLM) dynamically **delegates** tasks to the most suitable agent, decides the order of execution, and reviews outputs. Best for complex, open-ended workflows where the path isn't known upfront.

```
              Manager Agent
             /      |       \
        Task A   Task B   Task C   (assigned dynamically)
             \      |       /
              Final Result
```

| Feature              | Sequential           | Hierarchical               |
|----------------------|----------------------|----------------------------|
| Execution order      | Fixed, top-to-bottom | Dynamic delegation         |
| Manager agent needed | No                   | Yes                        |
| Complexity           | Low                  | High                       |
| Best for             | Linear pipelines     | Complex, adaptive workflows |

---

### 🛠️ Tools

**Tools** extend an agent's capabilities beyond text generation. They allow agents to interact with the real world — search the web, read files, execute code, call APIs, query databases, and more.

#### How tools work

1. The agent decides it needs external information
2. It calls the appropriate tool with the required arguments
3. The tool returns results back to the agent
4. The agent incorporates the results into its reasoning

#### Tools used in this project

| Tool            | Source         | Purpose |
|-----------------|----------------|---------|
| `SerperDevTool` | `crewai_tools` | Executes real-time Google searches — gives the researcher access to current news, stock data, and filings |

#### Other popular CrewAI tools

| Tool                      | Purpose |
|---------------------------|---------|
| `FileReadTool`            | Read local files |
| `WebsiteSearchTool`       | Scrape and search a specific website |
| `YoutubeVideoSearchTool`  | Search YouTube transcripts |
| `CodeInterpreterTool`     | Execute Python code |
| `ScrapeWebsiteT

[truncated…]