{"openapi":"3.1.0","info":{"title":"evaluate_idea API","description":"YC·K-Startup 학습 기반 아이디어 검증 백엔드","version":"0.1.0"},"paths":{"/api/health":{"get":{"summary":"Health","operationId":"health_api_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Api Health Get"}}}}}}},"/api/trends":{"get":{"tags":["trends"],"summary":"Google Trends + 캐즘 위치 판단","description":"단일 키워드의 5년 검색 추이를 가져오고, 캐즘 단계를 판정한다.\n\n- 응답의 `chasm.signal` 은 신호등(green/yellow/red).\n- `source == \"fallback\"` 이면 Google Trends 호출이 실패한 상태 (시계열 빈 배열).","operationId":"get_trends_api_trends_get","parameters":[{"name":"keyword","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":80,"description":"검색 키워드","title":"Keyword"},"description":"검색 키워드"},{"name":"geo","in":"query","required":false,"schema":{"enum":["KR","US","global"],"type":"string","description":"지역: KR / US / global","default":"KR","title":"Geo"},"description":"지역: KR / US / global"},{"name":"timeframe","in":"query","required":false,"schema":{"type":"string","description":"pytrends timeframe (예: 'today 5-y', 'today 12-m', 'all')","default":"today 5-y","title":"Timeframe"},"description":"pytrends timeframe (예: 'today 5-y', 'today 12-m', 'all')"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/similar":{"post":{"tags":["similar"],"summary":"YC 유사 회사 + 차별 시그널","description":"입력 태그 기반으로 YC 5,785개에서 유사 회사 Top-N + 성공/실패 비율 + 차별 시그널을 계산.\n\n- `resolved_tags`: 정규화 사전을 거친 후 실제 데이터에 매칭된 태그.\n- `unmatched_inputs`: 매칭 실패한 원본 입력(태그 사전 개선 트래킹용).\n- `differential_signals`: pool 내에서 성공자 vs 실패자 보유율 차이가 큰 태그 (양수=성공 시그널).\n- `korea_match_count`: YC 데이터 한국 커버리지 한계 노출용.","operationId":"post_similar_api_similar_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilarityQuery"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilarityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/evaluate":{"post":{"tags":["evaluate"],"summary":"아이디어 통합 평가 (단일 텍스트 → 6 카테고리)","description":"아이디어 텍스트 1건을 받아 6개 카테고리로 평가.\n\n입력은 단일 자유 텍스트(`idea`) 1개. 백엔드 룰 파서가 태그·industry·트렌드 키워드를 자동 추출하며,\n응답의 `parsed` 필드로 어떻게 해석됐는지 투명하게 노출.\n\n카테고리별 데이터 소스:\n- similarity, competitors: YC 5,785개 데이터 (실데이터) + 4-bucket 큐레이션\n- chasm: Google Trends 실시간 (실패 시 fallback)\n- profitability: description 키워드 룰 + 유사 회사 단서\n- market_size, guide: LLM placeholder (현재 단계 미연동)\n\n모든 카테고리는 공통 `verdict { signal, headline, narrative, source }` 패턴.","operationId":"post_evaluate_api_evaluate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeaTextInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CategoryVerdict":{"properties":{"signal":{"type":"string","enum":["green","yellow","red"],"title":"Signal"},"headline":{"type":"string","title":"Headline"},"narrative":{"type":"string","title":"Narrative"},"source":{"type":"string","enum":["yc_data","google_trends","fallback","rule","llm_placeholder"],"title":"Source"}},"type":"object","required":["signal","headline","narrative","source"],"title":"CategoryVerdict"},"ChasmCategory":{"properties":{"verdict":{"$ref":"#/components/schemas/CategoryVerdict"},"keywords":{"items":{"$ref":"#/components/schemas/ChasmKeywordResult"},"type":"array","title":"Keywords"}},"type":"object","required":["verdict","keywords"],"title":"ChasmCategory"},"ChasmKeywordResult":{"properties":{"keyword":{"type":"string","title":"Keyword"},"geo":{"type":"string","enum":["KR","US","global"],"title":"Geo"},"series":{"items":{"$ref":"#/components/schemas/TrendPoint"},"type":"array","title":"Series"},"chasm":{"$ref":"#/components/schemas/ChasmVerdict"},"source":{"type":"string","enum":["google_trends","fallback"],"title":"Source"}},"type":"object","required":["keyword","geo","series","chasm","source"],"title":"ChasmKeywordResult"},"ChasmVerdict":{"properties":{"stage":{"type":"string","enum":["innovators","early_adopters","early_mainstream","late_mainstream","laggards","declining"],"title":"Stage"},"signal":{"type":"string","enum":["green","yellow","red"],"title":"Signal"},"peak_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Peak Date"},"peak_value":{"type":"integer","title":"Peak Value"},"current_value":{"type":"integer","title":"Current Value"},"recent_3m_avg":{"type":"integer","title":"Recent 3M Avg"},"yoy_change_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Yoy Change Pct"},"narrative":{"type":"string","title":"Narrative"}},"type":"object","required":["stage","signal","peak_date","peak_value","current_value","recent_3m_avg","yoy_change_pct","narrative"],"title":"ChasmVerdict"},"CompanyCard":{"properties":{"company_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Company Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"batch":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch"},"batch_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Batch Year"},"current_status":{"type":"string","enum":["Active","Inactive","Acquired","Public"],"title":"Current Status"},"status_group":{"type":"string","enum":["success","neutral","failure"],"title":"Status Group"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"sub_industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Industry"},"hq_region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hq Region"},"is_top_company":{"type":"boolean","title":"Is Top Company"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"matched_tags":{"items":{"type":"string"},"type":"array","title":"Matched Tags"},"jaccard":{"type":"number","title":"Jaccard"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"}},"type":"object","required":["company_id","name","description","batch","batch_year","current_status","status_group","industry","sub_industry","hq_region","is_top_company","tags","matched_tags","jaccard","website"],"title":"CompanyCard"},"CompetitorBucket":{"properties":{"label":{"type":"string","title":"Label"},"companies":{"items":{"$ref":"#/components/schemas/CompanyCard"},"type":"array","title":"Companies"}},"type":"object","required":["label","companies"],"title":"CompetitorBucket"},"CompetitorsCategory":{"properties":{"verdict":{"$ref":"#/components/schemas/CategoryVerdict"},"buckets":{"items":{"$ref":"#/components/schemas/CompetitorBucket"},"type":"array","title":"Buckets"},"korea_coverage_note":{"type":"string","title":"Korea Coverage Note"}},"type":"object","required":["verdict","buckets","korea_coverage_note"],"title":"CompetitorsCategory"},"CuratedBuckets":{"properties":{"success":{"items":{"$ref":"#/components/schemas/CompanyCard"},"type":"array","title":"Success"},"failure":{"items":{"$ref":"#/components/schemas/CompanyCard"},"type":"array","title":"Failure"},"top_company":{"items":{"$ref":"#/components/schemas/CompanyCard"},"type":"array","title":"Top Company"},"recent":{"items":{"$ref":"#/components/schemas/CompanyCard"},"type":"array","title":"Recent"}},"type":"object","required":["success","failure","top_company","recent"],"title":"CuratedBuckets","description":"단일 Top-N 대신 4 시각으로 큐레이션. 동일 회사가 여러 버킷에 등장 가능."},"DifferentialSignal":{"properties":{"tag":{"type":"string","title":"Tag"},"success_holder_pct":{"type":"number","title":"Success Holder Pct"},"failure_holder_pct":{"type":"number","title":"Failure Holder Pct"},"delta_pp":{"type":"number","title":"Delta Pp"},"sample_size_success":{"type":"integer","title":"Sample Size Success"},"sample_size_failure":{"type":"integer","title":"Sample Size Failure"}},"type":"object","required":["tag","success_holder_pct","failure_holder_pct","delta_pp","sample_size_success","sample_size_failure"],"title":"DifferentialSignal"},"EvaluationResponse":{"properties":{"input_text":{"type":"string","title":"Input Text"},"parsed":{"$ref":"#/components/schemas/ParsedSummary"},"target_market":{"type":"string","enum":["KR","US","global"],"title":"Target Market"},"summary":{"additionalProperties":{"type":"string","enum":["green","yellow","red"]},"type":"object","title":"Summary"},"overall_signal":{"type":"string","enum":["green","yellow","red"],"title":"Overall Signal"},"one_liner":{"type":"string","title":"One Liner"},"similarity":{"$ref":"#/components/schemas/SimilarityCategory"},"competitors":{"$ref":"#/components/schemas/CompetitorsCategory"},"chasm":{"$ref":"#/components/schemas/ChasmCategory"},"profitability":{"$ref":"#/components/schemas/ProfitabilityCategory"},"market_size":{"$ref":"#/components/schemas/MarketSizeCategory"},"guide":{"$ref":"#/components/schemas/GuideCategory"}},"type":"object","required":["input_text","parsed","target_market","summary","overall_signal","one_liner","similarity","competitors","chasm","profitability","market_size","guide"],"title":"EvaluationResponse"},"ExecutionGuide":{"properties":{"prerequisites":{"items":{"type":"string"},"type":"array","title":"Prerequisites"},"recommended_resources":{"items":{"type":"string"},"type":"array","title":"Recommended Resources"},"tech_stack":{"additionalProperties":{"type":"string"},"type":"object","title":"Tech Stack"},"wbs":{"items":{"$ref":"#/components/schemas/WBSItem"},"type":"array","title":"Wbs"}},"type":"object","required":["prerequisites","recommended_resources","tech_stack","wbs"],"title":"ExecutionGuide"},"GuideCategory":{"properties":{"verdict":{"$ref":"#/components/schemas/CategoryVerdict"},"guide":{"$ref":"#/components/schemas/ExecutionGuide"}},"type":"object","required":["verdict","guide"],"title":"GuideCategory"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IdeaTextInput":{"properties":{"idea":{"type":"string","maxLength":2000,"minLength":10,"title":"Idea","description":"아이디어를 자유롭게 한 덩어리로 입력. 백엔드가 태그·industry·트렌드 키워드 자동 추출."},"target_market":{"type":"string","enum":["KR","US","global"],"title":"Target Market","description":"타겟 시장: KR / US / global","default":"KR"}},"type":"object","required":["idea"],"title":"IdeaTextInput","description":"단일 텍스트 입력 (사용자 페이스 페이스). 백엔드가 룰 파서로 IdeaInput 변환."},"MarketSizeCategory":{"properties":{"verdict":{"$ref":"#/components/schemas/CategoryVerdict"},"estimate":{"$ref":"#/components/schemas/MarketSizeEstimate"}},"type":"object","required":["verdict","estimate"],"title":"MarketSizeCategory"},"MarketSizeEstimate":{"properties":{"tam_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tam Hint"},"sam_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sam Hint"},"som_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Som Hint"},"rationale":{"type":"string","title":"Rationale"}},"type":"object","required":["tam_hint","sam_hint","som_hint","rationale"],"title":"MarketSizeEstimate"},"ParsedSummary":{"properties":{"detected_tags":{"items":{"type":"string"},"type":"array","title":"Detected Tags"},"detected_industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detected Industry"},"detected_sub_industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detected Sub Industry"},"detected_trend_keywords":{"items":{"type":"string"},"type":"array","title":"Detected Trend Keywords"},"unmatched_signals":{"items":{"type":"string"},"type":"array","title":"Unmatched Signals"}},"type":"object","required":["detected_tags","detected_industry","detected_sub_industry","detected_trend_keywords","unmatched_signals"],"title":"ParsedSummary","description":"파싱 결과를 사용자에게 투명하게 노출 (어떻게 해석됐는지)."},"PoolStats":{"properties":{"pool_size":{"type":"integer","title":"Pool Size"},"success":{"type":"integer","title":"Success"},"failure":{"type":"integer","title":"Failure"},"neutral":{"type":"integer","title":"Neutral"},"success_share":{"type":"number","title":"Success Share"},"failure_share":{"type":"number","title":"Failure Share"},"baseline_success_share":{"type":"number","title":"Baseline Success Share"},"success_share_delta_pp":{"type":"number","title":"Success Share Delta Pp"}},"type":"object","required":["pool_size","success","failure","neutral","success_share","failure_share","baseline_success_share","success_share_delta_pp"],"title":"PoolStats"},"PriceBenchmark":{"properties":{"company":{"type":"string","title":"Company"},"price_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Hint"},"note":{"type":"string","title":"Note"}},"type":"object","required":["company","price_hint","note"],"title":"PriceBenchmark"},"ProfitabilityCategory":{"properties":{"verdict":{"$ref":"#/components/schemas/CategoryVerdict"},"revenue_model":{"$ref":"#/components/schemas/RevenueModelDiagnosis"},"price_benchmarks":{"items":{"$ref":"#/components/schemas/PriceBenchmark"},"type":"array","title":"Price Benchmarks"}},"type":"object","required":["verdict","revenue_model","price_benchmarks"],"title":"ProfitabilityCategory"},"RevenueModelDiagnosis":{"properties":{"detected_models":{"items":{"type":"string"},"type":"array","title":"Detected Models"},"clarity":{"type":"string","enum":["clear","ambiguous","unclear"],"title":"Clarity"},"rationale":{"type":"string","title":"Rationale"}},"type":"object","required":["detected_models","clarity","rationale"],"title":"RevenueModelDiagnosis"},"SimilarityCategory":{"properties":{"verdict":{"$ref":"#/components/schemas/CategoryVerdict"},"resolved_tags":{"items":{"type":"string"},"type":"array","title":"Resolved Tags"},"unmatched_inputs":{"items":{"type":"string"},"type":"array","title":"Unmatched Inputs"},"pool":{"$ref":"#/components/schemas/PoolStats"},"top":{"items":{"$ref":"#/components/schemas/CompanyCard"},"type":"array","title":"Top"},"buckets":{"$ref":"#/components/schemas/CuratedBuckets"},"differential_signals":{"items":{"$ref":"#/components/schemas/DifferentialSignal"},"type":"array","title":"Differential Signals"}},"type":"object","required":["verdict","resolved_tags","unmatched_inputs","pool","top","buckets","differential_signals"],"title":"SimilarityCategory"},"SimilarityQuery":{"properties":{"tags":{"items":{"type":"string"},"type":"array","maxItems":15,"minItems":1,"title":"Tags","description":"아이디어의 태그 배열"},"sub_industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Industry","description":"선택: Sub-Industry 필터(예: 'Fintech', 'Productivity')"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry","description":"선택: Industry 대분류 필터"},"top_n":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Top N","description":"반환할 Top-N 카드 개수","default":10},"pool_min_overlap":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Pool Min Overlap","description":"유사 풀에 포함시킬 최소 태그 일치 개수","default":1},"user_keywords":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":30},{"type":"null"}],"title":"User Keywords","description":"아이디어 텍스트에서 추출한 비-태그 영어 키워드 (예: 'ETF','AUM','round-up'). description 매칭 보너스에 사용."}},"type":"object","required":["tags"],"title":"SimilarityQuery"},"SimilarityResponse":{"properties":{"resolved_tags":{"items":{"type":"string"},"type":"array","title":"Resolved Tags"},"unmatched_inputs":{"items":{"type":"string"},"type":"array","title":"Unmatched Inputs"},"pool":{"$ref":"#/components/schemas/PoolStats"},"top":{"items":{"$ref":"#/components/schemas/CompanyCard"},"type":"array","title":"Top"},"buckets":{"$ref":"#/components/schemas/CuratedBuckets"},"differential_signals":{"items":{"$ref":"#/components/schemas/DifferentialSignal"},"type":"array","title":"Differential Signals"},"korea_match_count":{"type":"integer","title":"Korea Match Count"}},"type":"object","required":["resolved_tags","unmatched_inputs","pool","top","buckets","differential_signals","korea_match_count"],"title":"SimilarityResponse"},"TrendPoint":{"properties":{"date":{"type":"string","title":"Date"},"value":{"type":"integer","title":"Value"}},"type":"object","required":["date","value"],"title":"TrendPoint"},"TrendsResponse":{"properties":{"keyword":{"type":"string","title":"Keyword"},"geo":{"type":"string","enum":["KR","US","global"],"title":"Geo"},"timeframe":{"type":"string","title":"Timeframe"},"series":{"items":{"$ref":"#/components/schemas/TrendPoint"},"type":"array","title":"Series"},"chasm":{"$ref":"#/components/schemas/ChasmVerdict"},"source":{"type":"string","enum":["google_trends","fallback"],"title":"Source","default":"google_trends"},"fetched_at":{"type":"string","title":"Fetched At"}},"type":"object","required":["keyword","geo","timeframe","series","chasm","fetched_at"],"title":"TrendsResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WBSItem":{"properties":{"title":{"type":"string","title":"Title"},"duration_weeks":{"type":"integer","title":"Duration Weeks"},"difficulty":{"type":"string","enum":["low","medium","high"],"title":"Difficulty"}},"type":"object","required":["title","duration_weeks","difficulty"],"title":"WBSItem"}}}}