# CLAUDE.md

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

## Project Overview

This is a creative ideation system that uses LLMs to break "semantic gravity" (the tendency of LLMs to generate ideas clustered around high-probability training distributions). The system analyzes objects through multiple attribute dimensions and transforms them using expert perspectives to generate novel ideas.

## Development Commands

### Starting the Application
```bash
./start.sh    # Starts both backend (port 8001) and frontend (port 5173)
./stop.sh     # Stops all services
```

### Backend (FastAPI + Python)
```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
```

### Frontend (React + Vite + TypeScript)
```bash
cd frontend
npm install
npm run dev      # Development server
npm run build    # TypeScript check + production build
npm run lint     # ESLint
```

## Architecture

### Multi-Agent Pipeline

The system uses three interconnected agents that process queries through Server-Sent Events (SSE) for real-time streaming:

```
Query → Attribute Agent → Expert Transformation Agent → Deduplication Agent
                                    ↓
                            Patent Search (optional)
```

**1. Attribute Agent** (`/api/analyze`)
- Analyzes a query (e.g., "bicycle") through configurable category dimensions
- Step 0: Category analysis (5 modes: FIXED_ONLY, FIXED_PLUS_CUSTOM, FIXED_PLUS_DYNAMIC, CUSTOM_ONLY, DYNAMIC_AUTO)
- Step 1: Generate attributes per category
- Step 2: Build DAG relationships between attributes across categories
- Output: `AttributeDAG` with nodes and edges

**2. Expert Transformation Agent** (`/api/expert-transformation/category`)
- Takes attributes and transforms them through diverse expert perspectives
- Step 0: Generate expert team (sources: `llm`, `curated`, `dbpedia`, `wikidata`)
- Step 1: Each expert generates keywords for each attribute
- Step 2: Generate descriptions for each keyword
- Formula: `total_keywords = attributes × expert_count × keywords_per_expert`

**3. Deduplication Agent** (`/api/deduplication/deduplicate`)
- Consolidates similar ideas using embedding similarity or LLM judgment
- Groups duplicates while preserving representative descriptions

### Backend Structure (`backend/app/`)
- `routers/` - FastAPI endpoints with SSE streaming
- `services/` - LLM service (Ollama/OpenAI), embedding service, expert source service
- `prompts/` - Bilingual prompt templates (zh/en) for each agent step
- `data/` - Curated occupation lists for expert sourcing (210 professions)

### Frontend Structure (`frontend/src/`)
- `hooks/` - React hooks matching backend agents (`useAttribute`, `useExpertTransformation`, `useDeduplication`)
- `components/` - UI panels for each stage + DAG visualization (D3.js, @xyflow/react)
- `services/api.ts` - SSE stream parsing and API calls
- `types/index.ts` - TypeScript interfaces mirroring backend schemas

### Key Patterns

**SSE Event Flow**: All agent operations stream progress via SSE events:
```typescript
// Frontend callback pattern
onStep0Start → onStep0Complete → onStep1Start → onStep1Complete → onDone
```

**Bilingual Support**: All prompts and UI support `PromptLanguage = 'zh' | 'en'`. Language flows through the entire pipeline from request to response messages.

**Expert Source Fallback**: If external sources (DBpedia, Wikidata) fail, system automatically falls back to LLM-based expert generation.

### Configuration

Backend requires `.env` file:
```
OLLAMA_BASE_URL=http://localhost:11435  # Default Ollama endpoint
DEFAULT_MODEL=qwen3:8b                   # Default LLM model
OPENAI_API_KEY=                          # Optional: for OpenAI-compatible APIs
LENS_API_TOKEN=                          # Optional: for patent search
```

### Dual-Path Mode

The system supports analyzing two queries in parallel (`PathA` and `PathB`) with attribute crossover functionality for comparing and combining ideas across different objects.