セマンティックプロダクト検索

セマンティックな商品検索：キーワードマッチングではなく、クエリの意図を理解し（埋め込み＋類似性検索）、エージェントを使用してカタログに関する推奨を生成します。カタログはMCPサーバーとして公開され、別のエージェントによって消費されます。

🚧 活発に開発中のプロジェクト。現在 フェーズ1 · バックエンドセットアップ にあります。 アーキテクチャ、デモ、設計上の決定に関するセクションは、エンドツーエンドのフローが機能するようになった後で完成させます。

スタック

• API: FastAPI

• エージェント / オーケストレーション: LangChain + LangChain Anthropic (Claude)

• ローカルモデル: Ollama

• 可観測性: LangSmith

• 設定 / バリデーション: Pydantic + Pydantic Settings

• データベース: Postgres + pgvector（ローカル開発時：SQLite）

• パッケージマネージャー: uv

Related MCP server: Vertex AI Search for Commerce MCP Server

プロジェクト構造

app/
  main.py           # entrypoint de la API
  api/routes.py      # rutas HTTP
  catalog/           # ingesta + modelos de datos del catálogo
  search/             # embeddings + similarity search
  reviews/
  mcp_server/         # servidor MCP (expone el catálogo/búsqueda como tools)
  agent/               # agente que consume el MCP y arma la recomendación
  core/
    config.py         # settings (variables de entorno)
    db.py              # conexión a Postgres/pgvector
  models/
    schemas.py         # modelos Pydantic compartidos
tests/

ローカルセットアップ

必要条件：Python >= 3.12 および uv がインストールされていること。

# Instalar dependencias
uv sync

# Configurar variables de entorno
cp .env.example .env
# completar ANTHROPIC_API_KEY y LANGSMITH_API_KEY en .env

# Correr el entrypoint
uv run python -m app.main

環境変数

⚠️ APIキーやシークレットの値は決してログに記録しないでください （ANTHROPIC_API_KEY、LANGSMITH_API_KEY など）。Settings をデバッグする必要がある場合は、失敗したフィールドの名前のみを出力し、その値は出力しないでください — app/core/config.py は起動時の検証でそのように動作します。

ロードマップ

開発はフェーズに分けて整理されています（Notionボードを参照）：

1. バックエンドセットアップ

2. カタログ + 埋め込み

3. セマンティック検索

4. レビュー + コメント

5. MCPサーバー

6. エージェント + 推奨

7. REST API + ストリーミング

8. 最適化

9. フロントエンド + 公開

アーキテクチャと設計上の決定

未定 — プロジェクトにエンドツーエンドのフローができ、実際のコンテキストで図、デモ、決定事項（キャッシュ、検索＋再ランキングなど）を説明できるようになった時点で、フェーズ9（PROD-32）で文書化します。