{"openapi":"3.1.0","info":{"title":"SmartShop AI API","description":"Two-Tower Recommendation System API","version":"1.0.0"},"paths":{"/api/v1/recommend":{"post":{"tags":["recommendations"],"summary":"Get Recommendations","description":"Main recommendation endpoint - handles both search and personalization.\n\nTwo modes:\n1. WITH query: Sentence-Transformer semantic search + LightGBM ranking\n2. WITHOUT query: Two-Tower personalization (user history) + LightGBM ranking\n\nPipeline:\n- Retrieval: Sentence-Transformer (text) or Two-Tower (personalization)\n- Features: Feast Online Store (user + item features)\n- Ranking: LightGBM (final_score = 0.4*similarity + 0.6*model_score)","operationId":"get_recommendations_api_v1_recommend_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/search":{"post":{"tags":["recommendations"],"summary":"Search Products","description":"Search products by text query using Sentence-Transformer semantic search.\n\nReturns products matching the search query based on semantic similarity.","operationId":"search_products_api_v1_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/{user_id}/features":{"get":{"tags":["recommendations"],"summary":"Get User Features","description":"Get features for a specific user from Feast Online Store.","operationId":"get_user_features_api_v1_user__user_id__features_get","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/item/{item_id}/features":{"get":{"tags":["recommendations"],"summary":"Get Item Features","description":"Get features for a specific item from Feast Online Store.","operationId":"get_item_features_api_v1_item__item_id__features_get","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","title":"Item Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/products/{product_id}":{"get":{"tags":["recommendations"],"summary":"Get Product Details","description":"Get product metadata (title, description, price, image, etc.).","operationId":"get_product_details_api_v1_products__product_id__get","parameters":[{"name":"product_id","in":"path","required":true,"schema":{"type":"string","title":"Product Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/products/batch":{"post":{"tags":["recommendations"],"summary":"Get Products Batch","description":"Get metadata for multiple products at once.","operationId":"get_products_batch_api_v1_products_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchProductsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/interactions":{"post":{"tags":["recommendations"],"summary":"Track Interaction","description":"Track a single user interaction (click, add_to_cart, etc.).\n\nThis data feeds the continuous learning pipeline:\n- Clicks become positive training examples\n- Impressions without clicks become negative examples\n- Data is stored in PostgreSQL and S3 for training","operationId":"track_interaction_api_v1_interactions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/interactions/batch":{"post":{"tags":["recommendations"],"summary":"Track Impressions","description":"Track multiple impressions (products shown to user).\n\nCall this when displaying recommendation results to track\nwhich products were shown but not clicked.","operationId":"track_impressions_api_v1_interactions_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchImpressionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/interactions/stats":{"get":{"tags":["recommendations"],"summary":"Get Interaction Stats","description":"Get interaction tracking statistics.","operationId":"get_interaction_stats_api_v1_interactions_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/session/init":{"get":{"tags":["recommendations"],"summary":"Init Session","description":"Initialize session and assign an Amazon user automatically.\n\nThis endpoint:\n1. Selects a random user from the pre-built user pool\n2. Returns user_id and metadata for personalization\n3. Frontend stores this in localStorage\n\nNo manual user selection needed.","operationId":"init_session_api_v1_session_init_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/session/pool-stats":{"get":{"tags":["recommendations"],"summary":"Get Pool Stats","description":"Get user pool statistics.","operationId":"get_pool_stats_api_v1_session_pool_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/for-you":{"get":{"tags":["recommendations"],"summary":"Get For You Recommendations","description":"Get personalized recommendations for \"Sana Özel\" page.\n\nUses Two-Tower model with assigned user's history.\nNo search query - pure personalization.","operationId":"get_for_you_recommendations_api_v1_for_you_get","parameters":[{"name":"user_id","in":"query","required":true,"schema":{"type":"string","description":"Assigned user ID","title":"User Id"},"description":"Assigned user ID"},{"name":"top_k","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of recommendations","default":20,"title":"Top K"},"description":"Number of recommendations"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"summary":"Health Check","description":"Health check endpoint.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"BatchImpressionRequest":{"properties":{"user_id":{"type":"string","title":"User Id","description":"User identifier"},"product_ids":{"items":{"type":"string"},"type":"array","title":"Product Ids","description":"List of shown product IDs"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Source: recommend, search"},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"Search query if applicable"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Session identifier"}},"type":"object","required":["user_id","product_ids"],"title":"BatchImpressionRequest","description":"Request model for batch impression tracking."},"BatchProductsRequest":{"properties":{"product_ids":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Product Ids"}},"type":"object","required":["product_ids"],"title":"BatchProductsRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InteractionRequest":{"properties":{"user_id":{"type":"string","title":"User Id","description":"User identifier"},"product_id":{"type":"string","title":"Product Id","description":"Product identifier"},"interaction_type":{"type":"string","title":"Interaction Type","description":"Type: click, impression, add_to_cart"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Source: recommend, search"},"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position","description":"Position in result list (0-indexed)"},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"Search query if applicable"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Session identifier"}},"type":"object","required":["user_id","product_id","interaction_type"],"title":"InteractionRequest","description":"Request model for tracking user interactions."},"ProductRecommendation":{"properties":{"product_id":{"type":"string","title":"Product Id"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"similarity_score":{"type":"number","title":"Similarity Score"},"model_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Model Score"},"final_score":{"type":"number","title":"Final Score"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price"},"average_rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Rating"},"rating_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rating Count"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["product_id","similarity_score","final_score"],"title":"ProductRecommendation"},"RecommendationRequest":{"properties":{"user_id":{"type":"string","title":"User Id","description":"User identifier"},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"Search query text"},"top_k":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Top K","description":"Number of recommendations","default":10}},"type":"object","required":["user_id"],"title":"RecommendationRequest"},"RecommendationResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"recommendations":{"items":{"$ref":"#/components/schemas/ProductRecommendation"},"type":"array","title":"Recommendations"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["user_id","recommendations","count"],"title":"RecommendationResponse"},"SearchRequest":{"properties":{"query":{"type":"string","minLength":1,"title":"Query","description":"Search query"},"top_k":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Top K","description":"Number of results","default":20}},"type":"object","required":["query"],"title":"SearchRequest"},"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"}}}}