competitive-intelligence CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Competitive Intelligence Monitor - A CocoIndex pipeline that tracks competitor mentions across the web using Tavily AI Search. Uses DeepSeek LLM-powered extraction to identify product launches, partnerships, funding rounds, key hires, and strategic moves.

Development Commands

Setup

pip install -e .                    # Install dependencies
cp .env.example .env                # Create environment config
# Edit .env with your API keys and database URL

Running the Pipeline

cocoindex update main -f            # One-time sync (force refresh)
cocoindex update -L main.py         # Live mode (continuous monitoring)

Testing

python3 test_results.py             # Run comprehensive tests

See TESTING.md for detailed testing procedures.

Database Setup

Requires PostgreSQL. The pipeline auto-creates tables:

• intel_articles - Raw news articles and blog posts
• intel_events - Extracted competitive intelligence events

Architecture

Data Flow

Sources → LLM Extraction → Dual Indexing → Query Handlers

1. Sources (main.py:49-99)

   • TavilySearchSource - AI-native web search optimized for agents
   • Searches with query: "{competitor} AND (funding OR partnership OR product launch OR acquisition OR executive hire)"
   • Returns clean, full article content (not just snippets)
   • Configurable via .env: COMPETITORS, REFRESH_INTERVAL_SECONDS, SEARCH_DAYS_BACK

2. LLM Extraction (main.py:136-164)

   • ExtractByLlm processes article content
   • Outputs structured CompetitiveEvent objects with:
     • event_type: product_launch, partnership, funding, key_hire, acquisition
     • competitor: Primary company involved
     • significance: high, medium, low (market impact)
     • related_companies: Partners, investors, etc.