Stock Price — Indian Equity Research Crew

Production-style multi-agent stock research and selection system built with crewAI, powered by Anthropic Claude and focused on NSE/BSE listed Indian equities.

Given a sector (e.g. Banking, Technology, Pharma), the crew searches Indian financial news, identifies trending companies, performs financial analysis, and selects the single best stock for investment — delivering a final decision report and optional push notification.

---

Table of Contents

1. What This Project Does
2. High-Level Architecture
3. Execution Flow
4. Crew Terminology Explained
5. Repository Structure
6. Prerequisites
7. Quick Start
8. Environment Variables
9. Run the Project
10. Outputs
11. How Hierarchical Orchestration Works Here
12. Configuration Deep Dive
13. Tooling and Integrations
14. Customization Guide
15. Troubleshooting
16. Security Notes
17. Roadmap Ideas
18. License

---

What This Project Does

Given a sector keyword, the crew executes a three-stage investment workflow for Indian stocks listed on NSE or BSE:

1. Find — Identifies 3 trending Indian companies in the selected sector from latest news (Economic Times, Moneycontrol, Mint, Business Standard).
2. Research — Produces a concise financial research note for each company: NSE/BSE ticker, market cap in INR crores, P/E ratio, revenue growth, investment case, and key risk.
3. Pick — Selects the single best stock, explains the rationale, briefly rejects the others, and sends a push notification.

---

High-Level Architecture

Jupyter Notebook / main.py
        │
        ▼
StockPicker().crew().kickoff(inputs)
        │
        ▼
  Manager Agent (claude-sonnet-4-5)
  ┌─────┴──────────────────────┐
  ▼                            ▼
Task 1                      Task 2                      Task 3
find_trending_companies  →  research_trending_companies  →  pick_best_company
(trending_company_finder)   (financial_researcher)          (stock_picker)
        │                            │                            │
        ▼                            ▼                            ▼
output/trending_companies.json  output/research_report.json  output/decision.md

Design pattern

• Orchestration model: manager-driven hierarchical process
• Task dependencies: context-based task chaining
• Output contracts: structured Pydantic outputs for intermediate stages
• LLM provider: Anthropic Claude (claude-sonnet-4-5) for all agents
• Memory: disabled (avoids OpenAI embedding dependency)

---

Execution Flow

1. User sets sector in the Jupyter notebook (or runs main.py)
2. StockPicker().crew().kickoff(inputs={"sector": ..., "current_date": ...}) starts execution
3. Manager agent coordinates the three worker agents under Process.hierarchical
4. Task 1 — trending_company_finder searches Indian financial news and writes output/trending_companies.json
5. Task 2 — financial_researcher receives Task 1 output as context, analyses each company, writes output/research_report.json
6. Task 3 — stock_picker receives Task 2 output as context, picks the best stock, sends a push notification, writes output/decision.md
7. Final result is available in result.raw and all three output files

---

Crew Terminology Explained

| Term | What it means in this project | |------|-------------------------------| | Crew | The full multi-agent system: agents + tasks + process + manager, wired in crew.py | | Agent | An AI worker with a role, goal, backstory, and tools. Four agents: trending_company_finder, financial_researcher, stock_picker, manager | | Task | A unit of work assigned to one agent. Three tasks defined in tasks.yaml | | Process | Process.hierarchical — manager agent plans and delegates dynamically | | Context | Prior task output passed to a later task. Research task receives finder output; picker task receives research output | | Tools | External capabilities: SerperDevTool (news search), PushNotificationTool (Pushover alert) |

---

Repository Structure

stock_price/
├── crew.py                    # Crew orchestration — agents, tasks, process wiring
├── main.py                    # CLI entry point (alternative to notebook)
├── __init__.py
├── config/
│   ├── agents.yaml            # Agent definitions (role, goal, backstory, llm)
│   └── tasks.yaml             # Task definitions (description, expected output, agent, context)
├── tools/
│   └── push_tool.py           # PushNotificationTool (Pushover integration)
├── output/                    # Generated per-run: trending_companies.json, research_report.json, decision.md
├── memory/                    # Reserved for future memory storage
├── reports/                   # Timestamped markdown reports saved from notebook
├── env.example                # Template for environment variables
├── .env                       # Your real secrets (git-ignored)
└── .gitignore

---

Prerequisites

• Python 3.11
• pip (or uv)
• Anthropic API key (for Claude)
• Serper API key (for web/news search via SerperDevTool)
• (Optional) Pushover credentials for push notifications

---

Quick Start

1. Clone the repo

git clone <your-repo-url>
cd stock_price

2. Install dependencies

pip install "crewai==0.86.0" "crewai-tools==0.17.0" "openai<2.0.0" \
            pydantic anthropic python-dotenv fastembed

3. Set environment variables

cp env.example .env
# Edit .env and fill in your real keys

4. Run

Option A — Jupyter Notebook (recommended)

Open the notebook, run cell 4 (env setup) then cell 6 (crew kickoff), then cell 8 (save report).

Option B — Terminal

cd C:\Users\<you>\Documents   # parent directory of stock_price
python -m stock_price.main

---

Environment Variables

Copy env.example to .env and populate:

| Variable | Required | Purpose | |----------|----------|---------| | ANTHROPIC_API_KEY | ✅ Yes | Anthropic Claude API (all agents use Claude) | | SERPER_API_KEY | ✅ Yes | Web/news search via SerperDevTool | | OPENAI_API_KEY | ⚠️ Placeholder | crewAI validates this at startup even when using Anthropic. Set any dummy value e.g. sk-placeholder-not-used | | PUSHOVER_USER | ❌ Optional | Pushover user key for push notifications | | PUSHOVER_TOKEN | ❌ Optional | Pushover app token for push notifications |

---

Run the Project

From Jupyter Notebook

Run cells in order:

| Cell | Purpose | Charges credits? | |------|---------|-----------------| | Cell 4 | Load .env, set sys.path, OPENAI placeholder | No | | Cell 6 | Run the crew (StockPicker().crew().kickoff(...)) | Yes | | Cell 8 | Save full report from output files | No |

To change sector, edit sector = "Banking" in cell 6. Available sectors:

sector = "Banking"         # HDFC Bank, ICICI Bank, SBI, Kotak...
sector = "Technology"      # TCS, Infosys, Wipro, HCL...
sector = "Pharma"          # Sun Pharma, Dr Reddy's, Cipla...
sector = "FMCG"            # HUL, ITC, Nestle India...
sector = "Auto"            # Maruti, M&M, Tata Motors...
sector = "Infrastructure"  # L&T, Adani Ports, IRFC...

From Terminal (CLI)

# Run from the parent of stock_price (i.e. Documents/)
cd C:\Users\<you>\Documents
python -m stock_price.main

You will be prompted:

Enter the sector you want to research (e.g. Technology, Healthcare, Finance):

---

Outputs

After a successful run, the following files are written to output/:

| File | Contents | |------|----------| | trending_companies.json | 3 trending Indian companies with NSE/BSE tickers and trending reasons | | research_report.json | Concise financial analysis of each company | | decision.md | Final stock pick with rationale and rejection of alternatives |

Timestamped Markdown reports are saved to reports/ when cell 8 is run in the notebook.

---

How Hierarchical Orchestration Works Here

Process.hierarchical means a manager agent dynamically coordinates the worker agents — it does not simply fire tasks in order. Combined with explicit context: links in tasks.yaml, this project gets:

• Dynamic orchestration: the manager can re-delegate or ask clarifying questions mid-run
• Deterministic data flow: each task still receives exactly the output from its declared upstream context tasks

This matters because it allows the manager to handle edge cases (e.g. an agent failing to find companies) without the whole crew crashing.

---

Configuration Deep Dive

Agents (config/agents.yaml)

Each agent entry:

trending_company_finder:
  role: Financial News Analyst that finds trending Indian companies in {sector}
  goal: Find exactly 3 Indian companies listed on NSE or BSE ...
  backstory: You are an Indian market expert tracking NSE/BSE listed companies ...
  llm: anthropic/claude-sonnet-4-5

All four agents (trending_company_finder, financial_researcher, stock_picker, manager) use anthropic/claude-sonnet-4-5.

Tasks (config/tasks.yaml)

Each task entry:

find_trending_companies:
  description: Search latest Indian financial news ...
  expected_output: A JSON list of 3 Indian {sector} companies ...
  agent: trending_company_finder
  output_file: output/trending_companies.json

Task 2 and 3 include context: to receive upstream outputs:

research_trending_companies:
  context:
    - find_trending_companies

Structured Outputs (crew.py)

Tasks 1 and 2 use Pydantic schemas (TrendingCompanyList, TrendingCompanyResearchList) to enforce consistent JSON shapes on intermediate outputs.

---

Tooling and Integrations

SerperDevTool

Used by: trending_company_finder, financial_researcher

Purpose: Live web and news search. Requires SERPER_API_KEY. Powers evidence-backed discovery of trending Indian companies.

PushNotificationTool

Used by: stock_picker

Purpose: Sends a push notification to your phone/device via Pushover when the final stock pick is made.

Implementation: POST to https://api.pushover.net/1/messages.json with user, token, message fields.

Requires PUSHOVER_USER and PUSHOVER_TOKEN in .env. If not set, the tool call will be made but silently fail — the rest of the crew continues normally.

---

Customization Guide

Change sector

In the Jupyter notebook cell 6, change:

sector = "Banking"  # to any sector you want

Add a new agent

1. Add an entry to config/agents.yaml
2. Add a corresponding @agent method in crew.py

Add a new task

1. Add an entry to config/tasks.yaml with context: dependencies if needed
2. Add a corresponding @task method in crew.py

Switch to sequential process

In crew.py, change:

process=Process.hierarchical,
manager_agent=manager,

to:

process=Process.sequential,

and remove the manager agent definition.

Improve decision quality

• Add valuation filters: P/E threshold, market cap floor, promoter holding minimum
• Add a risk scoring rubric to the pick_best_company task description
• Add a fourth task for portfolio-level diversification checks

---

Troubleshooting

| Problem | Fix | |---------|-----| | TypeError: unhashable type: 'dict' on startup | llm: in agents.yaml must be a plain string (anthropic/claude-sonnet-4-5), not a dict | | ModuleNotFoundError: No module named 'stock_price' | Run from the parent directory of stock_price/, or add it to sys.path in notebook cell 4 | | ValueError: Please provide an OpenAI API key | Set OPENAI_API_KEY=sk-placeholder-not-used in .env or cell 4 | | rag_storage ERROR: APIStatusError.__init__() missing arguments | Ensure memory=False in the Crew(...) call in crew.py | | Output truncated / incomplete | Task descriptions have word limits. If responses are still cut off, increase max_tokens by setting it in the LLM config or simplify the expected_output | | Push notification not received | Check PUSHOVER_USER and PUSHOVER_TOKEN in .env. Verify Pushover app/device is active | | Model 404 errors | Only these models work with claude-series: claude-haiku-4-5, claude-sonnet-4-5, claude-opus-4-5. Run cell 5 in the notebook to verify | | crewai-tools incompatibility | This project is pinned to crewai==0.86.0 and crewai-tools==0.17.0. Do not upgrade without testing |

---

Security Notes

• Never commit your real .env file. It is in .gitignore.
• Rotate API keys (Anthropic, Serper, Pushover) periodically.
• The OPENAI_API_KEY placeholder value (sk-placeholder-not-used) is never sent to OpenAI — it only satisfies a startup validation check in crewAI.
• Validate generated investment output before making any real-world financial decisions. This is a research assistant, not financial advice.

---

Roadmap Ideas

• Add NSE/BSE live price fetching tool for real-time valuation checks
• Add backtesting against Nifty 50 / Nifty Bank benchmarks
• Add portfolio construction mode (top-3 picks with allocation weights)
• Add SEBI compliance and insider trading news filtering
• Add scheduled runs (daily sector rotation analysis)
• Add unit and integration tests for tools and task output contracts
• Re-enable memory with a locally-hosted embedding model (e.g. fastembed) once crewAI/OpenAI SDK compatibility is resolved

---

License

This project is licensed under the MIT License. See the LICENSE file for details.