Stock Picker

StockPicker is a CrewAI-based multi-agent system that finds trending companies in a given sector, researches them, and recommends the best one for investment. It demonstrates how specialized AI agents work together in a hierarchical setup with a manager delegating tasks to worker agents.

CrewAI at a Glance

Crew = Agents + Tasks + Context

  ┌─────────────────────────────────────────────────────────┐
  │  Crew                                                   │
  │  ┌─────────┐  ┌─────────┐  ┌─────────┐                  │
  │  │ Agent 1 │  │ Agent 2 │  │ Agent 3 │  ...             │
  │  │ + tools │  │ + tools │  │ + tools │                  │
  │  └────┬────┘  └────┬────┘  └────┬────┘                  │
  │       │            │            │                       │
  │       ▼            ▼            ▼                       │
  │  Task 1 ──context──► Task 2 ──context──► Task 3         │
  └─────────────────────────────────────────────────────────┘

Concepts: Crew = team of agents; Agent = role + goal + tools; Task = work item; Context = one task's output passed to the next.

Project Flow

Input: sector, date
        │
        ▼
   ┌─────────┐
   │ Manager │  delegates
   └────┬────┘
        │
        ├──► Find trending companies ──► 2-3 companies
        │
        ├──► Research each company ───► analysis report
        │
        └──► Pick best + notify ──────► final decision + push

Technologies

| Technology | Purpose | |------------|---------| | CrewAI | Multi-agent orchestration framework with hierarchical process | | OpenAI GPT-4o / GPT-4o-mini | LLMs for agents and manager | | Serper | Web search for news and company research | | Pushover | Push notifications for the final stock pick | | Pydantic | Structured outputs for task results | | RAG + SQLite | Long-term, short-term, and entity memory | | UV | Python package and dependency management |

Prerequisites

• Python >=3.10, <3.13
• UV (pip install uv)
• CrewAI CLI (pip install crewai)

Setup

1. Clone and enter the crew directory

   cd src/stock_picker
   

2. Install dependencies

   uv sync # or crewai install
   

3. Configure environment Create a .env file with:

   • OPENAI_API_KEY — required for agents
   • SERPER_API_KEY — required for web search (get one)
   • PUSHOVER_USER and PUSHOVER_TOKEN — optional, for push notifications (get one)

How to Run

From src/stock_picker/:

Using CrewAI CLI

crewai run

The crew will:

1. Find 2–3 trending companies in the Technology sector
2. Research each company in depth
3. Pick the best one and optionally send a push notification

Outputs are written to src/stock_picker/output/ (trending companies, research report, final decision).

Running Tests

From src/stock_picker/:

# Install dev dependencies (pytest, pyyaml)
uv sync --group dev

# Run all tests
uv run pytest tests/ -v

# Run a specific test file
uv run pytest tests/test_models.py -v

No real API keys are needed for tests. If you hit import errors, set dummy env vars:

OPENAI_API_KEY=dummy SERPER_API_KEY=dummy uv run pytest tests/ -v

See docs/tests.md for more details, test structure, and troubleshooting.

Project Structure

src/stock_picker/
├── config/
│   ├── agents.yaml    # Agent roles, goals, backstories
│   └── tasks.yaml     # Task definitions and context chain
├── crew.py            # Crew, agents, tasks, memory
├── main.py            # Entry point
├── tests/             # Unit tests (see docs/tests.md)
│   ├── test_models.py
│   ├── test_push_tool.py
│   └── test_crew.py
├── tools/
│   └── push_tool.py   # Pushover notification tool
└── output/            # Generated reports

• AGENTS.md — Contributor map: layout, components, run commands
• docs/architecture.md — Architecture, flow diagrams, and code flow
• docs/developers_guide.md — Step-by-step guide for building crews
• docs/tests.md — Testing guide with run instructions and troubleshooting

Related Projects

| Project | Description | |---------|-------------| | ai-crew-financial-researcher | Two-agent pipeline: a Researcher gathers company data via web search (Serper), and an Analyst synthesizes it into a markdown report. Sequential flow, config-driven; supports multiple LLMs (e.g. OpenAI for research, Groq for analysis). Good for learning sequential flows and web search integration. | | ai-crew-engineering-team | Four-agent pipeline that turns natural language requirements into a designed backend module, implementation, Gradio UI, and unit tests. Engineering Lead → design doc; Backend Engineer → Python module; Frontend Engineer → Gradio app.py; Test Engineer → unit tests. Uses CrewAI’s Code Interpreter in a Docker sandbox for safe code execution. |

Comparison: All Three CrewAI Projects

| Aspect | ai-crew-financial-researcher | ai-crew-stock-picker (this project) | ai-crew-engineering-team | |--------|------------------------------|--------------------------------------|---------------------------| | Process | Sequential (2 tasks) | Hierarchical (Manager → workers) | Sequential (4 tasks) | | Agents | 2 (Researcher, Analyst) | Manager + 3 workers (finder, researcher, picker) | 4 (Engineering Lead, Backend, Frontend, Test Engineer) | | Input | Company name | Sector, date | Requirements (natural language), module name, class name | | Output | Markdown report | Best stock pick, JSON reports, push notification | Design doc, Python backend, Gradio UI, unit tests | | Tools | SerperDevTool (web search) | Serper, Pushover, RAG + SQLite | Code Interpreter (Docker) | | External APIs | Serper | Serper, Pushover | None (code-only) | | Memory | No | Yes (long-term, short-term, entity) | No | | Structured output | Markdown | Pydantic models + markdown | Markdown + Python files | | Code execution | No | No | Yes (Docker sandbox) | | Use case | Research & reporting on one company | Investment recommendation (find → research → pick) | Automated software development (design → code → UI → tests) |

Pipeline summary

• Financial Researcher — Search → research document → report. Best for learning sequential flows and Serper integration.
• Stock Picker — Manager delegates: find trending companies → research each → pick best → optional push. Demonstrates hierarchical orchestration, memory, and notifications.
• Engineering Team — Design → code → UI → tests. Full software lifecycle automation with code generation and execution in Docker.