LangGraph Deep Research

Project Overview

This repository contains a runnable LangGraph multi-agent research workflow for a P&G business research assignment. The system plans the research question, gathers category-specific evidence, extracts structured challenger-brand findings, scores/ranks those findings, and writes both a human-readable business report and structured source metadata.

The project is intentionally small enough to explain in a 5-10 minute project video while still showing the core patterns of a deep-research agent: planning, worker specialization, tool-backed evidence gathering, structured extraction, scoring, synthesis, and output persistence.

Research Question

What are the emerging brands that compete with P&G products and why are they popular with consumers?

Why This Project

P&G competes across many mature household and personal-care categories, where challenger brands often grow by focusing on a narrower consumer promise: sustainability, refill/reuse models, clean ingredients, premium performance, affordability, subscription convenience, Gen Z branding, social virality, personalization, mission-driven branding, or retail expansion.

This project turns that broad business question into a repeatable research workflow that produces:

• A category-by-category competitor view.
• Source-backed brand findings.
• Transparent ranking logic.
• Files that can be reviewed, shared, or used in a presentation.

Course Connection

This project was inspired by LangChain Academy's Deep Research with LangGraph course. The submitted repo is a separate custom implementation for the P&G assignment.

The local course repo was used only as a reference for graph structure, state design, prompt organization, and research-agent workflow patterns. This repo has its own package layout, state schema, category workers, search helper, extraction logic, scoring layer, and output format.

Architecture

The graph follows this high-level flow:

User question
  -> supervisor/planner
  -> category-specific research workers
  -> evidence collection
  -> structured extraction
  -> scoring/ranking
  -> synthesis/report generation
  -> output writer

Generated LangGraph visualization:

The graph is exported from:

./src/pg_emerging_brand_research/graph.py:graph

langgraph.json registers it as:

{
  "graphs": {
    "pg_research_agent": "./src/pg_emerging_brand_research/graph.py:graph"
  },
  "python_version": "3.11",
  "env": ".env",
  "dependencies": ["."]
}

Multi-Agent Workflow

• Supervisor/planner agent: Converts the user question into category-specific research tasks for the six P&G category buckets.
• Fabric & Home Care researcher: Searches and gathers evidence for challenger brands competing with Tide, Gain, Downy, Febreze, and Swiffer.
• Baby Care researcher: Searches and gathers evidence for challenger brands competing with Pampers and Luvs.
• Feminine Care researcher: Searches and gathers evidence for challenger brands competing with Always and Tampax.
• Grooming researcher: Searches and gathers evidence for challenger brands competing with Gillette and Venus.
• Beauty / Hair Care researcher: Searches and gathers evidence for challenger brands competing with Pantene, Head & Shoulders, Olay, and Native.
• Oral Care / Health Care researcher: Searches and gathers evidence for challenger brands competing with Crest, Oral-B, Vicks, and Metamucil.
• Extraction agent/node: Uses OpenAI structured output when OPENAI_API_KEY is available. If OpenAI is unavailable or a provider call fails, it uses heuristic extraction.
• Scoring node: Applies a weighted, explainable score to each brand and ranks the findings.
• Synthesis/report node: Builds the Markdown business report from structured findings. This step is deterministic Markdown assembly, not a separate LLM generation call.
• Output writer node: Saves outputs/result.md and outputs/sources.json.

Tools and Technologies Used

Verified from pyproject.toml and the source code:

• Python 3.11+
• LangGraph for graph orchestration.
• LangChain / LangChain Core / LangChain OpenAI for message and OpenAI structured-output integration.
• OpenAI API for structured extraction.
• Tavily Search API for live web search. The current helper calls Tavily's HTTP API with requests.
• Pydantic for structured schemas.
• python-dotenv for loading .env.
• Rich for terminal Markdown rendering and progress/status output.
• requests for Tavily HTTP calls.
• uv for dependency management and command execution.
• Ruff for lint validation.
• Git/GitHub for version control and submission.

Note: langchain-tavily is included as a dependency, but the current implementation uses Tavily's HTTP API directly through requests.

Models and APIs Used

• OpenAI model: gpt-5.4-mini
• Where used: src/pg_emerging_brand_research/graph.py uses ChatOpenAI(model="gpt-5.4-mini", temperature=0) for structured extraction.
• Structured output method: OpenAI function-calling via with_structured_output(CategoryFindings, method="function_calling").
• Model configurability: The model name is currently hardcoded in graph.py. There is no model-selection environment variable in the current implementation.
• Live search provider: Tavily Search API via https://api.tavily.com/search.
• Report synthesis: Deterministic Markdown generation from the extracted findings and scores.
• LangSmith: .env.example includes LangSmith variables. They are optional and can be used by the LangChain/LangGraph runtime for tracing when configured.

Project Structure

pg-emerging-brand-research/
  README.md
  pyproject.toml
  langgraph.json
  .env.example
  .gitignore
  outputs/
    result.md
    sources.json
  src/
    pg_emerging_brand_research/
      __init__.py
      main.py
      graph.py
      state.py
      prompts.py
      tools.py
      schemas.py
      utils.py

Key files:

• graph.py: LangGraph nodes, graph edges, extraction, scoring, synthesis, and output writing.
• tools.py: Tavily search helper plus curated fallback evidence.
• schemas.py: Pydantic models for research tasks, evidence, findings, and category results.
• state.py: Typed graph state.
• main.py: CLI entrypoint.
• outputs/result.md: Human-readable report.
• outputs/sources.json: Structured sources, findings, metadata, and scoring fields.

Setup

uv sync
cp .env.example .env
# edit .env and add API keys

Do not commit .env.

Environment Variables

Variables from .env.example:

Variable	Required	Purpose
OPENAI_API_KEY	Yes for live LLM extraction	Used for OpenAI structured extraction calls.
TAVILY_API_KEY	Yes for live search	Used for Tavily web search.
LANGSMITH_API_KEY	Optional	Used for LangSmith tracing/evaluation if enabled in the runtime.
LANGSMITH_TRACING	Optional	Enables LangSmith tracing when set, for example true.
LANGSMITH_PROJECT	Optional	LangSmith project name. The example uses pg-emerging-brand-research.

How to Run

Default question:

uv run python -m pg_emerging_brand_research.main

Custom question, positional:

uv run python -m pg_emerging_brand_research.main "Which emerging brands are pressuring P&G in home care and grooming?"

Custom question, flag:

uv run python -m pg_emerging_brand_research.main --question "Which challenger brands should P&G watch in oral care?"

The CLI loads .env, streams concise graph-node progress, prints the final report, and saves both output files.

Outputs

• outputs/result.md: Human-readable business report with the research question, approach, top brands, findings by P&G category, consumer patterns, scoring method, conclusion, improvements, and source links.
• outputs/sources.json: Structured evidence and metadata, including timestamp, question, whether live search was used, whether OpenAI extraction was used, source records, brand findings, scoring fields, and category worker summaries.

The latest checked output in outputs/sources.json shows:

• live_search_used: true
• openai_used: true
• warnings: []

Example Result

Full report: outputs/result.md

Approach excerpt:

A supervisor/planner split the P&G competitor question into six category-specific research workers. Each worker gathered evidence for challenger brands in its category, the extraction node converted evidence into structured brand findings, and the scoring node ranked brands with a weighted business rubric.

Top 5 brands from the latest generated report:

Rank	Brand	Category	Score	Main Drivers
1	Blueland	Fabric & Home Care	4.47/5	sustainability, refill/reuse model
2	Grove Collaborative	Fabric & Home Care	4.47/5	sustainability, subscription convenience, refill/reuse model, clean ingredients
3	Kudos	Baby Care	4.47/5	clean ingredients, ingredient transparency, premium performance, subscription convenience
4	August	Feminine Care	4.47/5	Gen Z branding, sustainability, subscription convenience
5	K18	Beauty / Hair Care	4.47/5	premium performance, TikTok/social virality

Major consumer patterns from the latest report:

The most repeated consumer drivers across the findings are subscription convenience, premium performance, clean ingredients, sustainability, ingredient transparency, and Gen Z branding.

Scoring Method

Each brand is scored on a 1-5 scale:

score = (
    category_fit * 0.30
    + evidence_strength * 0.25
    + consumer_trend_fit * 0.25
    + novelty_or_growth_signal * 0.20
)

Factor meanings:

• category_fit: How directly the brand competes in the relevant P&G category.
• evidence_strength: How strong, specific, and source-quality-adjusted the evidence is.
• consumer_trend_fit: How well the brand maps to consumer trend drivers such as clean ingredients, subscription convenience, sustainability, social virality, or personalization.
• novelty_or_growth_signal: Evidence of novelty, momentum, growth, retail expansion, or category disruption.

The scoring layer also applies source-quality guardrails. Primary brand pages, credible business/news sources, retailer pages, and category-relevant market sources are treated as stronger evidence. Broad or poorly targeted Tavily results are weighted lower or filtered out.

Fallback Mode

The project can still run without API keys:

• Without TAVILY_API_KEY, category workers use curated fallback evidence from tools.py.
• Without OPENAI_API_KEY, extraction uses deterministic heuristics.
• If Tavily or OpenAI fails during a run, the graph records warnings and continues where possible.
• Fallback output is clearly marked with warnings in the terminal output, outputs/result.md, and outputs/sources.json.

Live mode is preferred for final submission because it can incorporate current Tavily search evidence and OpenAI structured extraction.

Validation

Run these commands before submission:

uv run python -m pg_emerging_brand_research.main
uv run python -m compileall src
uv run ruff check .

What I Would Improve Next

• Add more source types beyond web search, including retailer reviews and syndicated market data.
• Add TikTok, Instagram, and search-trend data for social velocity.
• Compare emerging brands against sales, share, pricing, and distribution data.
• Add LangSmith evaluations for extraction quality, citation coverage, and scoring consistency.
• Improve source credibility scoring with more explicit source classes and per-source audit notes.
• Make the OpenAI model configurable via an environment variable.

Notes on Safety and Secrets

• .env is ignored by git.
• .env.example is safe to commit because it contains placeholders only.
• API keys should never be committed, printed, or pasted into issues/PRs.
• Generated outputs do not contain secret keys.
• The CLI reports whether live search/extraction was used, but it does not print API key values.