feat: サークル検索API実装（BM25F + fastText対応）

- サークルデータ取得API（/api/circles）の追加
- サークル詳細取得API（/api/details）の追加
- 検索API（/api/search）のBM25F + fastText対応
- CirclesRepository, CirclesServiceの実装
- CORSミドルウェアの設定
- スキーマ定義（circles.py）の追加
- ビルドスクリプトの更新

app/main.py

@@ -9,6 +9,7 @@ from contextlib import asynccontextmanager
 from fastapi import FastAPI, Response, Depends, HTTPException, Security, Query
 from fastapi.responses import RedirectResponse, JSONResponse
 from fastapi.security import APIKeyHeader
+from fastapi.middleware.cors import CORSMiddleware
 from pydantic import BaseModel
 
 from dotenv import load_dotenv
@@ -19,11 +20,11 @@ sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
 sys.path.append(os.path.dirname(__file__))
 
 from utils.logger import setup_logger
-from schemas.projects import Image, ProjectSummary, ProjectDetail, ProjectIds
+from schemas.circles import Image, CircleSummary, CircleDetail, CircleIds
 
-from .repositories.projects_repository import ProjectsRepository
+from .repositories.circles_repository import CirclesRepository
 from .search.engine import SearchEngine
-from .services.projects_service import ProjectsService
+from .services.circles_service import CirclesService
 
 log = setup_logger(__name__)
 
@@ -46,10 +47,10 @@ async def get_api_key(key: str = Security(api_key_header)):
 
 # --- App ---
 engine = SearchEngine()
-projects_repository = ProjectsRepository()
-projects_cache_ttl = int(os.getenv("PROJECTS_CACHE_TTL", "300"))
-projects_service = ProjectsService(
-    projects_repository, cache_ttl_seconds=projects_cache_ttl
+circles_repository = CirclesRepository()
+circles_cache_ttl = int(os.getenv("CIRCLES_CACHE_TTL", "300"))
+circles_service = CirclesService(
+    circles_repository, cache_ttl_seconds=circles_cache_ttl
 )
 
 
@@ -80,6 +81,18 @@ async def lifespan(app: FastAPI):
 
 app = FastAPI(lifespan=lifespan)
 
+# CORS設定
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "https://circle-search-26.pages.dev",
+        "http://localhost:3000",
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
 # PostHog（ログ分析）
 if POSTHOG_PROJECT_API_KEY:
     posthog = Posthog(
@@ -102,40 +115,42 @@ def health_check():
 
 
 @app.get(
-    "/api/projects",
-    response_model=list[ProjectSummary],
+    "/api/circles",
+    response_model=list[CircleSummary],
     dependencies=[Depends(get_api_key)],
 )
 def get_summary_data():
     # ここで必要なフィールドのみ抽出して返す
     summaries_payload: list[dict[str, object]] = []
-    for project in projects_service.list_projects():
+    for circle in circles_service.list_circles():
         # 画像はprimaryの1枚だけ返す
-        image = _select_primary_image(project.images)
-        if not image:
-            log.error("企画ID %s の画像選択に失敗しました", project.projectId)
-
-        summary = ProjectSummary(
-            projectId=project.projectId,
-            circleName=project.circleName,
-            name=project.name,
-            projectType=project.projectType,
-            category=project.category,
-            day1=project.day1,
-            day2=project.day2,
-            day3=project.day3,
-            location=project.location,
-            description=project.description,
-            prSummary=project.prSummary,
-            remark=project.remark,
-            image=image,
-            tags=project.tags,
-            isArchived=project.isArchived,
+        image = _select_primary_image(circle.images) if circle.images else None
+
+        summary = CircleSummary(
+            circleId=circle.circleId,
+            circleName=circle.circleName,
+            circleNameKana=circle.circleNameKana,
+            isOfficial=circle.isOfficial,
+            isIntercollegiate=circle.isIntercollegiate,
+            projectId=circle.projectId,
+            projectName=circle.projectName,
+            mainCategory=circle.mainCategory,
+            subCategory=circle.subCategory,
+            category=circle.category,
+            areaCode=circle.areaCode,
+            pamphletNumber=circle.pamphletNumber,
+            prSummary=circle.prSummary,
+            description=circle.description,
+            mainImage=image,
+            memberCount=circle.memberCount,
+            tags=circle.tags,
+            featureTags=circle.featureTags,
+            isArchived=circle.isArchived,
         )
         summaries_payload.append(summary.model_dump(mode="json"))
 
     content = json.dumps(summaries_payload, ensure_ascii=False).encode("utf-8")
-    log.info(f"Project summaries fetched: {len(summaries_payload)} items")
+    log.info(f"Circle summaries fetched: {len(summaries_payload)} items")
     return Response(
         content=gzip.compress(content),
         headers={"Content-Encoding": "gzip", "Content-Type": "application/json"},
@@ -144,15 +159,15 @@ def get_summary_data():
 
 @app.get(
     "/api/details",
-    response_model=ProjectDetail,
+    response_model=CircleDetail,
     dependencies=[Depends(get_api_key)],
 )
-def get_project_detail(projectId: str = Query(..., description="取得したい企画のID")):
-    p = projects_service.get_project(projectId)
-    if not p:
-        raise HTTPException(status_code=404, detail="Project not found")
-    log.info(f"Project detail fetched: {projectId}")
-    return ProjectDetail(**p.model_dump(include=set(ProjectDetail.model_fields.keys())))
+def get_circle_detail(circleId: str = Query(..., description="取得したいサークルのID")):
+    c = circles_service.get_circle(circleId)
+    if not c:
+        raise HTTPException(status_code=404, detail="Circle not found")
+    log.info(f"Circle detail fetched: {circleId}")
+    return CircleDetail(**c.model_dump(include=set(CircleDetail.model_fields.keys())))
 
 
 class SearchRequest(BaseModel):
@@ -166,7 +181,7 @@ class TaskUpdateResponse(BaseModel):
 
 @app.post(
     "/api/search",
-    response_model=ProjectIds,
+    response_model=CircleIds,
     dependencies=[Depends(get_api_key)],
 )
 def search(request: SearchRequest):
@@ -176,25 +191,25 @@ def search(request: SearchRequest):
     result = engine.search(request.query, debug=request.debug)
     if request.debug:
         pairs, diag = result
-        ids = [pid for pid, _ in pairs]
+        ids = [cid for cid, _ in pairs]
         return JSONResponse(
             content={
-                "projectIds": ids,
+                "circleIds": ids,
                 "scores": [
-                    {"projectId": pid, "score": float(score)} for pid, score in pairs
+                    {"circleId": cid, "score": float(score)} for cid, score in pairs
                 ],
                 "details": diag.get("details", []),
             }
         )
     pairs = result
-    ids = [pid for pid, _ in pairs]
+    ids = [cid for cid, _ in pairs]
 
     # ログ送信
     GET_LOGS = os.getenv("GET_LOGS", "false").lower() == "true"
     if GET_LOGS and posthog:
         try:
             posthog.capture(
-                event="projects searched",
+                event="circles searched",
                 properties={
                     "query": request.query,
                     "result_count": len(ids),
@@ -204,7 +219,7 @@ def search(request: SearchRequest):
         except Exception:
             pass
     log.info(f'Search query="{request.query}" => {len(ids)} results')
-    return ProjectIds(projectIds=ids)
+    return CircleIds(circleIds=ids)
 
 
 @app.post(

app/repositories/__init__.py

@@ -1,5 +1,5 @@
 """Repository layer providing data access abstractions."""
 
-from .projects_repository import ProjectsRepository
+from .circles_repository import CirclesRepository
 
-__all__ = ["ProjectsRepository"]
+__all__ = ["CirclesRepository"]

app/repositories/circles_repository.py

@@ -0,0 +1,51 @@
+import json
+from pathlib import Path
+from typing import Any
+
+import sys
+import os
+
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
+
+from schemas.circles import Circle
+from utils.logger import setup_logger
+
+log = setup_logger(__name__)
+
+
+class CirclesRepository:
+    """サークルデータのリポジトリ"""
+
+    def __init__(self):
+        self.circles: list[Circle] = []
+        self.circles_map: dict[str, Circle] = {}
+        self._load_circles()
+
+    def _load_circles(self):
+        """サークルデータをJSONファイルから読み込む"""
+        # config/files.json から読み込み
+        config_path = Path(__file__).resolve().parents[2] / "config" / "files.json"
+        with open(config_path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+
+        circles_json_path = Path(__file__).resolve().parents[2] / config["circles"]["circles_json"]
+
+        if not circles_json_path.exists():
+            log.warning(f"Circles JSON file not found: {circles_json_path}")
+            return
+
+        with open(circles_json_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        self.circles = [Circle(**item) for item in data]
+        self.circles_map = {c.circleId: c for c in self.circles}
+
+        log.info(f"Loaded {len(self.circles)} circles from {circles_json_path}")
+
+    def list_circles(self) -> list[Circle]:
+        """全サークルを取得"""
+        return self.circles
+
+    def get_circle(self, circle_id: str) -> Circle | None:
+        """指定IDのサークルを取得"""
+        return self.circles_map.get(circle_id)

app/search/engine.py

@@ -66,10 +66,10 @@ class SearchEngine:
         self.custom_synonyms: Dict[str, List[str]] = {}
         self.synonyms_cache: Dict[str, List[str]] = {}
 
-        # Data
-        self.projects: List[Dict[str, Any]] = []
-        self.project_map: Dict[str, Dict[str, Any]] = {}
-        self.project_idx: Dict[str, int] = {}
+        # Data (project -> circle)
+        self.circles: List[Dict[str, Any]] = []
+        self.circle_map: Dict[str, Dict[str, Any]] = {}
+        self.circle_idx: Dict[str, int] = {}
         self.org_norms: Dict[str, str] = {}
         self.reading_norms: Dict[str, str] = {}
         self.substring_index: Dict[str, List[str]] = {}
@@ -108,16 +108,16 @@ class SearchEngine:
             query_subword_enable=bool(search("query_subword.enable")),
             query_subword_path=files("embeddings.fasttext_bin"),
             query_subword_oov_weight=float(search("query_subword.oov_weight")),
-            org_boost_exact=float(search("circleName.boost.exact", 1.0)),
-            org_boost_prefix=float(search("circleName.boost.prefix", 0.7)),
-            org_boost_substring=float(search("circleName.boost.substring", 0.5)),
-            org_boost_min_len=int(search("circleName.boost.min_len", 2)),
+            org_boost_exact=float(search("org_boost.exact", 1.5)),
+            org_boost_prefix=float(search("org_boost.prefix", 0.9)),
+            org_boost_substring=float(search("org_boost.substring", 0.6)),
+            org_boost_min_len=int(search("org_boost.min_len", 2)),
             min_results=int(search("filter.min_results", 20)),
-            max_results=int(search("filter.max_results", 50)),
-            bm25_min=float(search("filter.bm25_min", 0.1)),
-            word_sim_min=float(search("filter.word_sim_min", 0.35)),
-            fused_min=float(search("filter.fused_min", 0.12)),
-            fused_rel_top_ratio=float(search("filter.fused_rel_top_ratio", 0.5)),
+            max_results=int(search("filter.max_results", 100)),
+            bm25_min=float(search("filter.bm25_min", 0.5)),
+            word_sim_min=float(search("filter.word_sim_min", 0.3)),
+            fused_min=float(search("filter.fused_min", 0.4)),
+            fused_rel_top_ratio=float(search("filter.fused_rel_top_ratio", 0.7)),
         )
 
         # Tokenizer
@@ -160,18 +160,18 @@ class SearchEngine:
         else:
             self.substring_index = {}
 
-        # Projects
-        with open(files("projects.projects_json"), encoding="utf-8") as f:
-            self.projects = json.load(f)
-        self.project_map = {p["projectId"]: p for p in self.projects}
-        self.project_idx = {p["projectId"]: idx for idx, p in enumerate(self.projects)}
+        # Circles (projects -> circles)
+        with open(files("circles.circles_json"), encoding="utf-8") as f:
+            self.circles = json.load(f)
+        self.circle_map = {c["circleId"]: c for c in self.circles}
+        self.circle_idx = {c["circleId"]: idx for idx, c in enumerate(self.circles)}
         self.org_norms = {
-            p["projectId"]: normalize_text_for_org(p.get("circleName") or "")
-            for p in self.projects
+            c["circleId"]: normalize_text_for_org(c.get("circleName") or "")
+            for c in self.circles
         }
         self.reading_norms = {
-            p["projectId"]: normalize_text_for_org(p.get("circleNameKana") or "")
-            for p in self.projects
+            c["circleId"]: normalize_text_for_org(c.get("circleNameKana") or "")
+            for c in self.circles
         }
 
         # BM25F assets
@@ -318,7 +318,7 @@ class SearchEngine:
                 out.append(term)
         return out
 
-    def _substring_match_project_ids(self, query: str) -> Set[str]:
+    def _substring_match_circle_ids(self, query: str) -> Set[str]:
         if not self.substring_index:
             return set()
         terms = self._normalize_substring_terms(query)
@@ -510,12 +510,12 @@ class SearchEngine:
         if self.cfg.synonyms_enable:
             terms = self._expand_synonyms(terms)
 
-        substring_hits = self._substring_match_project_ids(query)
+        substring_hits = self._substring_match_circle_ids(query)
         substring_idx_set: Set[int] = set()
-        substring_mask = np.zeros((len(self.projects),), dtype=bool)
+        substring_mask = np.zeros((len(self.circles),), dtype=bool)
         if substring_hits:
-            for pid in substring_hits:
-                idx = self.project_idx.get(pid)
+            for cid in substring_hits:
+                idx = self.circle_idx.get(cid)
                 if idx is None:
                     continue
                 substring_idx_set.add(idx)
@@ -534,15 +534,15 @@ class SearchEngine:
         # circleName/circleNameKana auto-boost based on raw query substring match
         qn = normalize_text_for_org(query)
         boost_enabled = len(qn) >= int(self.cfg.org_boost_min_len)
-        boost = np.zeros((len(self.projects),), dtype=np.float32)
+        boost = np.zeros((len(self.circles),), dtype=np.float32)
         if boost_enabled:
-            exact = np.zeros((len(self.projects),), dtype=bool)
+            exact = np.zeros((len(self.circles),), dtype=bool)
             prefix = np.zeros_like(exact)
             substr = np.zeros_like(exact)
-            for i, d in enumerate(self.projects):
-                pid = d.get("projectId")
-                on = self.org_norms.get(pid, "")
-                rn = self.reading_norms.get(pid, "")
+            for i, d in enumerate(self.circles):
+                cid = d.get("circleId")
+                on = self.org_norms.get(cid, "")
+                rn = self.reading_norms.get(cid, "")
                 if qn and (qn == on or (rn and qn == rn)):
                     exact[i] = True
                 elif qn and (on.startswith(qn) or (rn and rn.startswith(qn))):
@@ -557,7 +557,7 @@ class SearchEngine:
             )
 
         # collect results
-        ids = [d.get("projectId") for d in self.projects]
+        ids = [d.get("circleId") for d in self.circles]
 
         # Filtering to reduce false positives while keeping recall
         # Relative threshold anchored to the top fused score
@@ -632,17 +632,16 @@ class SearchEngine:
             return pairs
         # build debug details for all docs sorted by score
         ranked_indices = sorted(
-            range(len(self.projects)),
+            range(len(self.circles)),
             key=lambda idx: (-float(final_scores[idx]), ids[idx]),
         )
         details = []
         for idx in ranked_indices:
-            project = self.projects[idx]
+            circle = self.circles[idx]
             details.append(
                 {
-                    "projectId": ids[idx],
-                    "circleName": project.get("circleName"),
-                    "name": project.get("name"),
+                    "circleId": ids[idx],
+                    "circleName": circle.get("circleName"),
                     "bm25": float(bm25[idx]),
                     "ws_filter_topk": float(ws_filter[idx]),
                     "ws_rerank_pairavg": float(ws_rerank[idx])
@@ -656,8 +655,8 @@ class SearchEngine:
             )
         return pairs, {"details": details}
 
-    def get_projects(self) -> List[Dict[str, Any]]:
-        return self.projects
+    def get_circles(self) -> List[Dict[str, Any]]:
+        return self.circles
 
-    def get_project_map(self) -> Dict[str, Dict[str, Any]]:
-        return self.project_map
+    def get_circle_map(self) -> Dict[str, Dict[str, Any]]:
+        return self.circle_map

app/services/__init__.py

@@ -1,5 +1,5 @@
 """Service layer modules."""
 
-from .projects_service import ProjectsService
+from .circles_service import CirclesService
 
-__all__ = ["ProjectsService"]
+__all__ = ["CirclesService"]

app/services/circles_service.py

@@ -0,0 +1,36 @@
+import time
+from typing import Any
+
+import sys
+import os
+
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
+
+from schemas.circles import Circle
+from app.repositories.circles_repository import CirclesRepository
+from utils.logger import setup_logger
+
+log = setup_logger(__name__)
+
+
+class CirclesService:
+    """サークル情報を管理するサービス"""
+
+    def __init__(self, repository: CirclesRepository, cache_ttl_seconds: int = 300):
+        self.repository = repository
+        self.cache_ttl = cache_ttl_seconds
+        self._cache: list[Circle] | None = None
+        self._cache_time: float = 0
+
+    def list_circles(self) -> list[Circle]:
+        """全サークルを取得（キャッシュ付き）"""
+        now = time.time()
+        if self._cache is None or (now - self._cache_time) > self.cache_ttl:
+            self._cache = self.repository.list_circles()
+            self._cache_time = now
+            log.info("Cache refreshed")
+        return self._cache
+
+    def get_circle(self, circle_id: str) -> Circle | None:
+        """指定IDのサークルを取得"""
+        return self.repository.get_circle(circle_id)

config/files.json

@@ -7,9 +7,9 @@
         "synonyms_cache": "data/generated/synonyms_cache.json",
         "stopwords": "resources/stopwords.json"
     },
-    "projects": {
-        "projects_json": "data/generated/projects.json",
-        "output_json": "data/generated/projects.json"
+    "circles": {
+        "original_csv": "resources/original_circles.csv",
+        "circles_json": "data/generated/circles.json"
     },
     "bm25": {
         "bm25_meta": "data/generated/bm25_meta.json",

config/search_model.json

@@ -1,18 +1,25 @@
 {
-  "target_pos_l1": [
-    "名詞",
-    "動詞",
-    "形容詞",
-    "形容動詞語幹"
-  ],
+  "target_pos_l1": ["名詞", "動詞", "形容詞"],
   "target_fields": [
-    "name",
     "circleName",
     "circleNameKana",
+    "projectName",
     "description",
     "prSummary",
-    "prDetail"
+    "detailDescription"
   ],
+  "bm25f": {
+    "k1": 1.2,
+    "b": 0.75,
+    "field_weights": {
+      "circleName": 2.5,
+      "circleNameKana": 0.8,
+      "projectName": 1.8,
+      "description": 1.0,
+      "prSummary": 1.2,
+      "detailDescription": 0.9
+    }
+  },
   "synonyms": {
     "enable": true,
     "sources": {
@@ -20,54 +27,37 @@
       "custom_json": "resources/synonyms_custom.json"
     },
     "limits": {
+      "max_synonym_per_term": 3,
+      "max_term_len": 6,
       "max_expansions_per_term": 4,
       "max_query_variants": 5,
       "min_char_len": 2
     },
-    "banlist": [
-      "部",
-      "会",
-      "サークル"
-    ]
-  },
-  "bm25f": {
-    "k1": 1.2,
-    "b": 0.75,
-    "field_weights": {
-      "name": 2.0,
-      "circleName": 1.5,
-      "circleNameKana": 0.6,
-      "description": 1.0,
-      "prSummary": 1.0,
-      "prDetail": 0.8
-    }
+    "banlist": ["の", "こと", "もの", "部", "会", "サークル"]
   },
   "word_sim": {
     "enable": true,
-    "mode": "topk",
     "alpha": 0.5,
     "topk_k": 3,
     "rerank": "pair_avg"
   },
   "query_subword": {
-    "enable": true,
-    "oov_weight": 0.8,
-    "cache_size": 50000
+    "enable": false,
+    "path": "resources/embeddings/subword_vectors.bin",
+    "oov_weight": 0.5
   },
-  "circleName": {
-    "boost": {
-      "exact": 1.0,
-      "prefix": 0.7,
-      "substring": 0.5,
-      "min_len": 2
-    }
+  "org_boost": {
+    "exact": 1.5,
+    "prefix": 0.9,
+    "substring": 0.6,
+    "min_len": 2
   },
   "filter": {
-    "min_results": 10,
-    "max_results": 30,
-    "bm25_min": 0.15,
-    "word_sim_min": 0.40,
-    "fused_min": 0.15,
-    "fused_rel_top_ratio": 0.50
+    "min_results": 20,
+    "max_results": 100,
+    "bm25_min": 0.5,
+    "word_sim_min": 0.3,
+    "fused_min": 0.4,
+    "fused_rel_top_ratio": 0.7
   }
 }

docs/【有効】2026-01-19_サークル検索API実装ガイド.md

@@ -0,0 +1,1356 @@
+# サークル検索API実装ガイド
+## ステップバイステップ完全版
+
+**最終更新**: 2026年1月19日  
+**対象**: circle-search-26のためのBM25F + fastText検索API構築
+
+---
+
+## 前提条件
+
+- GitHubアカウント
+- Huggingface アカウント（無料）
+- ローカル開発環境（Python 3.12、Git、エディタ）
+- circle-search-26は既にAPI検索対応済み（`src/lib/api.ts`）
+
+---
+
+## 全体フロー概要
+
+```
+1. chibafes-website-api-v2 をフォーク
+2. サークル検索用にコード改造
+3. ローカルでテスト
+4. Huggingface Space にデプロイ
+5. GitHub Actions 設定
+6. circle-search-26 から接続テスト
+```
+
+---
+
+## Phase 1: リポジトリのフォークとセットアップ
+
+### Step 1-1: chibafes-website-api-v2 をフォーク
+
+1. ブラウザで https://github.com/chibafes-dev/chibafes-website-api-v2 を開く
+
+2. 右上の "Fork" ボタンをクリック
+
+3. リポジトリ名を変更:
+   ```
+   Repository name: circle-search-api
+   Description: Circle search API with BM25F and fastText for circle-search-26
+   ```
+
+4. "Create fork" をクリック
+
+### Step 1-2: ローカルにクローン
+
+```bash
+# フォークしたリポジトリをクローン
+git clone https://github.com/YOUR_USERNAME/circle-search-api.git
+cd circle-search-api
+
+# リモートに upstream を追加（オリジナルの追跡用）
+git remote add upstream https://github.com/chibafes-dev/chibafes-website-api-v2.git
+```
+
+### Step 1-3: Python環境のセットアップ
+
+```bash
+# pyenv で Python 3.12.11 をインストール（未インストールの場合）
+pyenv install 3.12.11
+
+# 仮想環境を作成・有効化
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# 依存関係をインストール
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+### Step 1-4: 環境変数ファイルの作成
+
+`.env` ファイルをプロジェクトルートに作成:
+
+```bash
+# API側 GitHub の secrets と HF Spaces の Secrets の両方に登録
+HF_TOKEN=hf_xxx  # Huggingfaceのアクセストークン
+
+# HF Spaces の secrets に登録
+API_SECRET_KEY=your-secret-key-here  # 任意の強力なパスワード
+
+# Huggingface embeddings リポジトリ（後で作成）
+HF_EMBEDDINGS_REPO_ID=YOUR_USERNAME/circle-embeddings
+
+# PostHog（オプション、分析用）
+POSTHOG_PROJECT_API_KEY=  # 空欄でOK
+
+# ログ取得（オプション）
+GET_LOGS=false
+```
+
+**重要**: `.env` ファイルは `.gitignore` に含まれているか必ず確認！
+
+---
+
+## Phase 2: コードの改造（企画 → サークル）
+
+### Step 2-1: スキーマ定義の変更
+
+#### `schemas/circles.py` を新規作成
+
+```python
+from typing import Literal
+from pydantic import BaseModel
+
+
+class Image(BaseModel):
+    """画像情報"""
+    url: str
+    alt: str | None = None
+    order: int = 0
+
+
+class Sns(BaseModel):
+    """SNS情報"""
+    type: str
+    url: str
+
+
+class Circle(BaseModel):
+    """サークル情報（フル）"""
+    circleId: str
+    circleName: str
+    circleNameKana: str
+    isOfficial: bool
+    isIntercollegiate: bool
+    
+    # 企画関連（大祭企画との紐付け用、オプション）
+    projectId: str | None = None
+    projectName: str | None = None
+    
+    # カテゴリ情報
+    mainCategory: str
+    subCategory: str | None = None
+    category: str | None = None  # 大祭用カテゴリ
+    
+    # 場所情報
+    areaCode: str | None = None
+    areaNumber: str | None = None
+    pamphletNumber: int | None = None
+    
+    # 開催日情報（大祭用、オプション）
+    beforeDay: bool = False
+    firstDay: bool = False
+    secondDay: bool = False
+    thirdDay: bool = False
+    
+    # 概要情報
+    prSummary: str | None = None
+    description: str | None = None
+    detailDescription: str | None = None
+    message: str | None = None
+    
+    # 画像・SNS
+    images: list[Image] = []
+    sns: list[Sns] = []
+    
+    # メンバー情報
+    memberCount: int | None = None
+    genderRatioMale: float | None = None
+    genderRatioFemale: float | None = None
+    
+    # 設立情報
+    establishedYear: int | None = None
+    
+    # 金銭情報
+    annualFee: int | None = None
+    hasNoFee: bool = False
+    
+    # タグ
+    tags: list[str] = []
+    featureTags: list[str] = []
+    
+    # 活動情報
+    activityFrequency: str | None = None
+    activityTimeSlot: str | None = None
+    
+    # 新歓情報
+    hasTrialEvent: bool = False
+    
+    # アーカイブ
+    isArchived: bool = False
+
+
+class CircleSummary(BaseModel):
+    """サークル概要（一覧表示用）"""
+    circleId: str
+    circleName: str
+    circleNameKana: str
+    isOfficial: bool
+    isIntercollegiate: bool
+    projectId: str | None = None
+    projectName: str | None = None
+    mainCategory: str
+    subCategory: str | None = None
+    category: str | None = None
+    areaCode: str | None = None
+    pamphletNumber: int | None = None
+    prSummary: str | None = None
+    description: str | None = None
+    mainImage: Image | None = None
+    memberCount: int | None = None
+    tags: list[str] = []
+    featureTags: list[str] = []
+    isArchived: bool = False
+
+
+class CircleDetail(BaseModel):
+    """サークル詳細"""
+    circleId: str
+    circleName: str
+    circleNameKana: str
+    isOfficial: bool
+    isIntercollegiate: bool
+    projectId: str | None = None
+    projectName: str | None = None
+    mainCategory: str
+    subCategory: str | None = None
+    category: str | None = None
+    prSummary: str | None = None
+    description: str | None = None
+    detailDescription: str | None = None
+    message: str | None = None
+    images: list[Image] = []
+    sns: list[Sns] = []
+    memberCount: int | None = None
+    tags: list[str] = []
+    featureTags: list[str] = []
+    isArchived: bool = False
+
+
+class CircleIds(BaseModel):
+    """検索結果のID配列"""
+    circleIds: list[str]
+```
+
+#### `schemas/__init__.py` を更新
+
+```python
+from .circles import Circle, CircleSummary, CircleDetail, CircleIds, Image, Sns
+
+__all__ = [
+    "Circle",
+    "CircleSummary",
+    "CircleDetail",
+    "CircleIds",
+    "Image",
+    "Sns",
+]
+```
+
+### Step 2-2: リポジトリ層の変更
+
+#### `app/repositories/circles_repository.py` を新規作成
+
+```python
+import json
+from pathlib import Path
+from typing import Any
+
+import sys
+import os
+
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
+
+from schemas.circles import Circle
+from utils.logger import setup_logger
+
+log = setup_logger(__name__)
+
+
+class CirclesRepository:
+    """サークルデータのリポジトリ"""
+
+    def __init__(self):
+        self.circles: list[Circle] = []
+        self.circles_map: dict[str, Circle] = {}
+        self._load_circles()
+
+    def _load_circles(self):
+        """サークルデータをJSONファイルから読み込む"""
+        # config/files.json から読み込み
+        config_path = Path(__file__).resolve().parents[2] / "config" / "files.json"
+        with open(config_path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+
+        circles_json_path = Path(__file__).resolve().parents[2] / config["circles"]["circles_json"]
+
+        if not circles_json_path.exists():
+            log.warning(f"Circles JSON file not found: {circles_json_path}")
+            return
+
+        with open(circles_json_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        self.circles = [Circle(**item) for item in data]
+        self.circles_map = {c.circleId: c for c in self.circles}
+
+        log.info(f"Loaded {len(self.circles)} circles from {circles_json_path}")
+
+    def list_circles(self) -> list[Circle]:
+        """全サークルを取得"""
+        return self.circles
+
+    def get_circle(self, circle_id: str) -> Circle | None:
+        """指定IDのサークルを取得"""
+        return self.circles_map.get(circle_id)
+```
+
+### Step 2-3: サービス層の変更
+
+#### `app/services/circles_service.py` を新規作成
+
+```python
+import time
+from typing import Any
+
+import sys
+import os
+
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
+
+from schemas.circles import Circle
+from app.repositories.circles_repository import CirclesRepository
+from utils.logger import setup_logger
+
+log = setup_logger(__name__)
+
+
+class CirclesService:
+    """サークル情報を管理するサービス"""
+
+    def __init__(self, repository: CirclesRepository, cache_ttl_seconds: int = 300):
+        self.repository = repository
+        self.cache_ttl = cache_ttl_seconds
+        self._cache: list[Circle] | None = None
+        self._cache_time: float = 0
+
+    def list_circles(self) -> list[Circle]:
+        """全サークルを取得（キャッシュ付き）"""
+        now = time.time()
+        if self._cache is None or (now - self._cache_time) > self.cache_ttl:
+            self._cache = self.repository.list_circles()
+            self._cache_time = now
+            log.info("Cache refreshed")
+        return self._cache
+
+    def get_circle(self, circle_id: str) -> Circle | None:
+        """指定IDのサークルを取得"""
+        return self.repository.get_circle(circle_id)
+```
+
+### Step 2-4: 検索エンジンの変更
+
+#### `app/search/engine.py` の修正（重要な変更のみ）
+
+**変更1: インポート部分**
+
+```python
+# 既存のインポートに追加
+from schemas.circles import Circle
+
+# projects関連のインポートを削除して circles に変更
+```
+
+**変更2: SearchEngine クラスの初期化**
+
+```python
+class SearchEngine:
+    def __init__(self):
+        # ... 既存のコード ...
+        
+        # Data（プロパティ名変更）
+        self.circles: List[Dict[str, Any]] = []  # projects → circles
+        self.circle_map: Dict[str, Dict[str, Any]] = {}  # project_map → circle_map
+        self.circle_idx: Dict[str, int] = {}  # project_idx → circle_idx
+        
+        # 以下同様に全ての project を circle に変更
+```
+
+**変更3: データ読み込み部分**
+
+```python
+def initialize(self):
+    files = field_getter("config/files.json")
+    search = field_getter("config/search_model.json")
+
+    # ... 既存の設定読み込み ...
+
+    # circles.json のパスを取得（projects.json → circles.json）
+    circles_json_path = files("circles.circles_json")
+    with open(circles_json_path, "r", encoding="utf-8") as f:
+        self.circles = json.load(f)
+    
+    # circle_id でマッピング（projectId → circleId）
+    for idx, c in enumerate(self.circles):
+        cid = c["circleId"]  # projectId → circleId
+        self.circle_map[cid] = c
+        self.circle_idx[cid] = idx
+        # org_norms も circleName で作成
+        self.org_norms[cid] = normalize_text_for_org(c.get("circleName", ""))
+    
+    # ... 以下同様に全ての project を circle に変更 ...
+```
+
+**変更4: 検索対象フィールドの調整**
+
+```python
+# target_fields の定義を circle に合わせて調整
+# デフォルト設定例:
+"target_fields": [
+    "circleName",
+    "circleNameKana",
+    "projectName",
+    "description",
+    "prSummary",
+    "detailDescription"
+]
+```
+
+### Step 2-5: FastAPI エンドポイントの変更
+
+#### `app/main.py` を大幅修正
+
+```python
+# インポート部分
+from schemas.circles import Image, CircleSummary, CircleDetail, CircleIds
+from .repositories.circles_repository import CirclesRepository
+from .services.circles_service import CirclesService
+
+# 初期化
+engine = SearchEngine()
+circles_repository = CirclesRepository()
+circles_cache_ttl = int(os.getenv("CIRCLES_CACHE_TTL", "300"))
+circles_service = CirclesService(
+    circles_repository, cache_ttl_seconds=circles_cache_ttl
+)
+
+# エンドポイント変更
+@app.get(
+    "/api/circles",
+    response_model=list[CircleSummary],
+    dependencies=[Depends(get_api_key)],
+)
+def get_summary_data():
+    summaries_payload: list[dict[str, object]] = []
+    for circle in circles_service.list_circles():
+        # 画像はmainImageの1枚だけ返す
+        image = circle.mainImage if hasattr(circle, 'mainImage') else None
+        
+        summary = CircleSummary(
+            circleId=circle.circleId,
+            circleName=circle.circleName,
+            circleNameKana=circle.circleNameKana,
+            isOfficial=circle.isOfficial,
+            isIntercollegiate=circle.isIntercollegiate,
+            projectId=circle.projectId,
+            projectName=circle.projectName,
+            mainCategory=circle.mainCategory,
+            subCategory=circle.subCategory,
+            category=circle.category,
+            areaCode=circle.areaCode,
+            pamphletNumber=circle.pamphletNumber,
+            prSummary=circle.prSummary,
+            description=circle.description,
+            mainImage=image,
+            memberCount=circle.memberCount,
+            tags=circle.tags,
+            featureTags=circle.featureTags,
+            isArchived=circle.isArchived,
+        )
+        summaries_payload.append(summary.model_dump(mode="json"))
+
+    content = json.dumps(summaries_payload, ensure_ascii=False).encode("utf-8")
+    log.info(f"Circle summaries fetched: {len(summaries_payload)} items")
+    return Response(
+        content=gzip.compress(content),
+        headers={"Content-Encoding": "gzip", "Content-Type": "application/json"},
+    )
+
+
+@app.get(
+    "/api/details",
+    response_model=CircleDetail,
+    dependencies=[Depends(get_api_key)],
+)
+def get_circle_detail(circleId: str = Query(..., description="取得したいサークルのID")):
+    c = circles_service.get_circle(circleId)
+    if not c:
+        raise HTTPException(status_code=404, detail="Circle not found")
+    log.info(f"Circle detail fetched: {circleId}")
+    return CircleDetail(**c.model_dump(include=set(CircleDetail.model_fields.keys())))
+
+
+@app.post(
+    "/api/search",
+    response_model=CircleIds,
+    dependencies=[Depends(get_api_key)],
+)
+def search(request: SearchRequest):
+    if not request.query:
+        raise HTTPException(status_code=400, detail="Query cannot be empty")
+
+    result = engine.search(request.query, debug=request.debug)
+    if request.debug:
+        pairs, diag = result
+        ids = [cid for cid, _ in pairs]
+        return JSONResponse(
+            content={
+                "circleIds": ids,
+                "scores": [
+                    {"circleId": cid, "score": float(score)} for cid, score in pairs
+                ],
+                "details": diag.get("details", []),
+            }
+        )
+    pairs = result
+    ids = [cid for cid, _ in pairs]
+
+    # ログ送信
+    GET_LOGS = os.getenv("GET_LOGS", "false").lower() == "true"
+    if GET_LOGS and posthog:
+        try:
+            posthog.capture(
+                event="circles searched",
+                properties={
+                    "query": request.query,
+                    "result_count": len(ids),
+                    "$process_person_profile": False,
+                },
+            )
+        except Exception:
+            pass
+    log.info(f'Search query="{request.query}" => {len(ids)} results')
+    return CircleIds(circleIds=ids)
+```
+
+### Step 2-6: 設定ファイルの変更
+
+#### `config/files.json` を修正
+
+```json
+{
+  "circles": {
+    "original_csv": "resources/original_circles.csv",
+    "circles_json": "data/generated/circles.json"
+  },
+  "tf_token": {
+    "tf_token_json": "data/generated/tf_token.json"
+  },
+  "circle_names": {
+    "circle_names_txt": "data/generated/circle_names.txt"
+  },
+  "bm25f_meta": {
+    "idf_json": "data/generated/idf.json",
+    "avg_len_json": "data/generated/avg_len.json"
+  },
+  "embeddings": {
+    "vocab_txt": "resources/embeddings/vocab.txt",
+    "vectors_npy": "resources/embeddings/vectors.npy"
+  },
+  "stopwords": {
+    "stopwords_json": "resources/stopwords.json"
+  },
+  "synonyms": {
+    "custom_json": "resources/synonyms_custom.json",
+    "sudachi_txt": "resources/synonyms_DO_NOT_EDIT.txt"
+  },
+  "user_dict": {
+    "user_dict_csv": "resources/user_dict.csv"
+  }
+}
+```
+
+#### `config/search_model.json` を修正
+
+```json
+{
+  "target_pos_l1": ["名詞", "動詞", "形容詞"],
+  "target_fields": [
+    "circleName",
+    "circleNameKana",
+    "projectName",
+    "description",
+    "prSummary",
+    "detailDescription"
+  ],
+  "bm25f": {
+    "k1": 1.2,
+    "b": 0.75,
+    "field_weights": {
+      "circleName": 2.5,
+      "circleNameKana": 0.8,
+      "projectName": 1.8,
+      "description": 1.0,
+      "prSummary": 1.2,
+      "detailDescription": 0.9
+    }
+  },
+  "synonyms": {
+    "enable": true,
+    "limits": {
+      "max_synonym_per_term": 3,
+      "max_term_len": 6
+    }
+  },
+  "banlist": ["の", "こと", "もの"],
+  "word_sim": {
+    "enable": true,
+    "alpha": 0.5,
+    "topk_k": 3,
+    "rerank": "pair_avg"
+  },
+  "query_subword": {
+    "enable": false,
+    "path": "resources/embeddings/subword_vectors.bin",
+    "oov_weight": 0.5
+  },
+  "org_boost": {
+    "exact": 1.5,
+    "prefix": 0.9,
+    "substring": 0.6,
+    "min_len": 2
+  },
+  "filter": {
+    "min_results": 20,
+    "max_results": 100,
+    "bm25_min": 0.5,
+    "word_sim_min": 0.3,
+    "fused_min": 0.4,
+    "fused_rel_top_ratio": 0.7
+  }
+}
+```
+
+### Step 2-7: スクリプトの変更
+
+#### `scripts/2_create_projects_data.py` を `scripts/2_create_circles_data.py` にリネーム・修正
+
+```python
+#!/usr/bin/env python3
+"""
+CSVからサークルデータのJSONを生成するスクリプト
+"""
+
+import sys
+import os
+import json
+import csv
+from pathlib import Path
+
+sys.path.append(str(Path(__file__).resolve().parents[1]))
+
+from utils.json import field_getter
+from utils.logger import setup_logger
+
+log = setup_logger(__name__)
+
+
+def main():
+    log.info("Starting circles data creation...")
+    
+    files = field_getter("config/files.json")
+    
+    # CSVファイルを読み込み
+    csv_path = Path(__file__).resolve().parents[1] / files("circles.original_csv")
+    if not csv_path.exists():
+        log.error(f"CSV file not found: {csv_path}")
+        return
+    
+    circles = []
+    with open(csv_path, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            circle = {
+                "circleId": row.get("circleId", ""),
+                "circleName": row.get("circleName", ""),
+                "circleNameKana": row.get("circleNameKana", ""),
+                "isOfficial": row.get("isOfficial", "false").lower() == "true",
+                "isIntercollegiate": row.get("isIntercollegiate", "false").lower() == "true",
+                "projectId": row.get("projectId") or None,
+                "projectName": row.get("projectName") or None,
+                "mainCategory": row.get("mainCategory", "OTHER"),
+                "subCategory": row.get("subCategory") or None,
+                "category": row.get("category") or None,
+                "areaCode": row.get("areaCode") or None,
+                "pamphletNumber": int(row["pamphletNumber"]) if row.get("pamphletNumber") else None,
+                "prSummary": row.get("prSummary") or None,
+                "description": row.get("description") or None,
+                "detailDescription": row.get("detailDescription") or None,
+                "memberCount": int(row["memberCount"]) if row.get("memberCount") else None,
+                "tags": row.get("tags", "").split(",") if row.get("tags") else [],
+                "featureTags": row.get("featureTags", "").split(",") if row.get("featureTags") else [],
+                "isArchived": row.get("isArchived", "false").lower() == "true",
+            }
+            circles.append(circle)
+    
+    # JSONファイルを出力
+    output_path = Path(__file__).resolve().parents[1] / files("circles.circles_json")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(circles, f, ensure_ascii=False, indent=2)
+    
+    log.info(f"Created circles JSON: {output_path} ({len(circles)} circles)")
+
+
+if __name__ == "__main__":
+    main()
+```
+
+#### `scripts/7_prepare_circle_names.py` を作成（旧 `7_prepare_circle_names.py` を修正）
+
+```python
+#!/usr/bin/env python3
+"""
+サークル名の正規化テキストを生成するスクリプト
+"""
+
+import sys
+import os
+import json
+import unicodedata
+from pathlib import Path
+
+sys.path.append(str(Path(__file__).resolve().parents[1]))
+
+from utils.json import field_getter
+from utils.logger import setup_logger
+
+log = setup_logger(__name__)
+
+
+def normalize_text_for_org(s: str) -> str:
+    """団体名正規化"""
+    try:
+        s = unicodedata.normalize("NFKC", s)
+    except Exception:
+        pass
+    s = " ".join(s.split())
+    return s
+
+
+def main():
+    log.info("Starting circle names preparation...")
+    
+    files = field_getter("config/files.json")
+    
+    # circles.json を読み込み
+    circles_json_path = Path(__file__).resolve().parents[1] / files("circles.circles_json")
+    with open(circles_json_path, "r", encoding="utf-8") as f:
+        circles = json.load(f)
+    
+    # 正規化した団体名を生成
+    circle_names = []
+    for c in circles:
+        name = c.get("circleName", "")
+        if name:
+            normalized = normalize_text_for_org(name)
+            circle_names.append(normalized)
+    
+    # テキストファイルに出力
+    output_path = Path(__file__).resolve().parents[1] / files("circle_names.circle_names_txt")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write("\n".join(circle_names))
+    
+    log.info(f"Created circle names: {output_path} ({len(circle_names)} names)")
+
+
+if __name__ == "__main__":
+    main()
+```
+
+#### `scripts/build_all.py` を修正
+
+```python
+# 既存のインポートと変更なし
+# 実行部分を修正
+
+if __name__ == "__main__":
+    log.info("=== Starting full build process ===")
+    
+    # Step 0: データダウンロード（オプション）
+    # run_script("scripts/0_download_data.py")
+    
+    # Step 1: 辞書構築
+    run_script("scripts/1_build_dict.py")
+    
+    # Step 2: サークルデータ作成（projects → circles）
+    run_script("scripts/2_create_circles_data.py")
+    
+    # Step 3: 同義語辞書構築
+    run_script("scripts/3_build_synonyms_from_sudachi.py")
+    
+    # Step 4: BM25F メタデータ準備
+    run_script("scripts/4_prepare_bm25f_meta.py")
+    
+    # Step 5: TF-token 準備
+    run_script("scripts/5_prepare_tf_token.py")
+    
+    # Step 6: Word embeddings 構築
+    run_script("scripts/6_build_word_embeddings.py")
+    
+    # Step 7: サークル名準備（projects → circles）
+    run_script("scripts/7_prepare_circle_names.py")
+    
+    log.info("=== Full build process completed ===")
+```
+
+### Step 2-8: サンプルデータの作成
+
+#### `resources/original_circles.csv` を作成
+
+最小限のサンプルデータ:
+
+```csv
+circleId,circleName,circleNameKana,isOfficial,isIntercollegiate,projectId,projectName,mainCategory,subCategory,category,areaCode,pamphletNumber,prSummary,description,detailDescription,memberCount,tags,featureTags,isArchived
+circle-001,千葉大学サッカー部,ちばだいがくさっかーぶ,true,false,,,SPORTS,BALL_SPORTS,PERFORMANCE,T,1,関東大学サッカーリーグ所属。週5日の練習で全国大会出場を目指しています。,サッカー部の詳細説明,詳細な活動内容,50,サッカー|運動,freq_daily|size_medium|feat_official,false
+circle-002,吹奏楽部,すいそうがくぶ,true,false,,,CULTURE,MUSIC_PERFORM,MUSIC,L,2,定期演奏会や学祭での演奏を行っています。,吹奏楽部の詳細説明,詳細な活動内容,60,音楽|吹奏楽,freq_3_4|size_large|feat_official,false
+circle-003,軽音楽サークル,けいおんがくさーくる,false,false,,,CULTURE,MUSIC_PERFORM,MUSIC,K,3,バンド活動を通じて音楽を楽しむサークルです。,軽音楽サークルの詳細説明,詳細な活動内容,30,音楽|バンド,freq_1_2|size_medium|feat_beginner,false
+```
+
+---
+
+## Phase 3: ローカルテスト
+
+### Step 3-1: データビルド
+
+```bash
+# 仮想環境を有効化
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# データビルドスクリプトを実行
+python scripts/build_all.py
+```
+
+**注意**: 初回実行時は約6GBのfastTextモデルをダウンロードするため、WiFi環境で実行してください。
+
+### Step 3-2: サーバー起動
+
+```bash
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### Step 3-3: 動作確認
+
+#### ブラウザで確認
+
+```
+http://localhost:8000/docs
+```
+
+Swagger UIが開きます。
+
+#### API テスト
+
+**1. Health Check**
+```bash
+curl http://localhost:8000/api/health
+```
+
+**2. サークル一覧取得**
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/circles' \
+  -H 'X-API-KEY: your-secret-key-here'
+```
+
+**3. 検索テスト**
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/search' \
+  -H 'X-API-KEY: your-secret-key-here' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "query": "サッカー",
+  "debug": false
+}'
+```
+
+期待される結果:
+```json
+{
+  "circleIds": ["circle-001"]
+}
+```
+
+**4. デバッグモードでの検索**
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/search' \
+  -H 'X-API-KEY: your-secret-key-here' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "query": "音楽",
+  "debug": true
+}'
+```
+
+期待される結果（スコア情報付き）:
+```json
+{
+  "circleIds": ["circle-002", "circle-003"],
+  "scores": [
+    {"circleId": "circle-002", "score": 15.23},
+    {"circleId": "circle-003", "score": 12.45}
+  ],
+  "details": [...]
+}
+```
+
+---
+
+## Phase 4: Huggingface Space へのデプロイ
+
+### Step 4-1: Huggingface Spaceの作成
+
+1. https://huggingface.co/spaces にアクセス
+
+2. "Create new Space" をクリック
+
+3. 設定:
+   ```
+   Owner: YOUR_USERNAME
+   Space name: circle-search-api
+   License: mit
+   SDK: Docker
+   Space hardware: CPU basic (無料)
+   ```
+
+4. "Create Space" をクリック
+
+### Step 4-2: Huggingface トークンの取得
+
+1. https://huggingface.co/settings/tokens にアクセス
+
+2. "New token" をクリック
+
+3. 設定:
+   ```
+   Name: circle-search-api
+   Type: Write
+   ```
+
+4. "Generate token" をクリックしてトークンをコピー
+
+### Step 4-3: Huggingface Spaceのシークレット設定
+
+1. 作成したSpaceのページで "Settings" タブをクリック
+
+2. "Variables and secrets" セクションで以下を追加:
+
+   ```
+   Name: HF_TOKEN
+   Value: hf_xxxxxxxxxxxxxxxxxx (Step 4-2で取得したトークン)
+   
+   Name: API_SECRET_KEY
+   Value: your-secret-key-here (強力なパスワード)
+   
+   Name: HF_EMBEDDINGS_REPO_ID
+   Value: YOUR_USERNAME/circle-embeddings (後で作成)
+   
+   Name: POSTHOG_PROJECT_API_KEY
+   Value: (空欄でOK、または分析用のキー)
+   
+   Name: GET_LOGS
+   Value: false
+   ```
+
+### Step 4-4: リポジトリのプッシュ
+
+```bash
+# Huggingface Space用のリモートを追加
+git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/circle-search-api
+
+# mainブランチにコミット
+git add .
+git commit -m "Initial commit: Circle search API"
+
+# Huggingface Spaceにプッシュ
+git push hf main
+```
+
+**注意**: プッシュ時にユーザー名とパスワードを求められます。
+- ユーザー名: Huggingface のユーザー名
+- パスワード: Step 4-2で取得したHuggingfaceトークン
+
+### Step 4-5: デプロイの確認
+
+1. Huggingface SpaceのページでBuild logを確認
+
+2. デプロイ完了後、以下のURLでアクセス可能:
+   ```
+   https://YOUR_USERNAME-circle-search-api.hf.space
+   ```
+
+3. Swagger UIで確認:
+   ```
+   https://YOUR_USERNAME-circle-search-api.hf.space/docs
+   ```
+
+### Step 4-6: CORS設定の追加
+
+`app/main.py` に以下を追加:
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+# FastAPIアプリ作成後に追加
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "https://circle-search-26.pages.dev",  # あなたのCloudflare PagesのURL
+        "http://localhost:3000",  # ローカル開発用
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+変更をコミット・プッシュ:
+```bash
+git add app/main.py
+git commit -m "Add CORS configuration"
+git push hf main
+```
+
+---
+
+## Phase 5: GitHub Actions の設定
+
+### Step 5-1: GitHub リポジトリの準備
+
+1. GitHubでフォークしたリポジトリ (`YOUR_USERNAME/circle-search-api`) を開く
+
+2. "Settings" → "Secrets and variables" → "Actions" をクリック
+
+3. "New repository secret" をクリックして以下を追加:
+
+   ```
+   Name: HF_TOKEN
+   Secret: hf_xxxxxxxxxxxxxxxxxx
+   
+   Name: API_SECRET_KEY
+   Secret: your-secret-key-here
+   ```
+
+4. "Variables" タブで以下を追加:
+
+   ```
+   Name: FASTAPI_URL
+   Value: https://YOUR_USERNAME-circle-search-api.hf.space
+   ```
+
+### Step 5-2: GitHub Actions ワークフローの確認
+
+既存の `.github/workflows/deploy_to_hf_space.yaml` を確認:
+
+```yaml
+name: Deploy to Hugging Face Space
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  deploy-to-space:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Push to Hugging Face Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git clone https://YOUR_USERNAME:$HF_TOKEN@huggingface.co/spaces/YOUR_USERNAME/circle-search-api space-repo
+          rsync -av --delete --exclude='.git/' --exclude='space-repo/' ./ space-repo/
+          cd space-repo
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+          git add .
+          if ! git diff-index --quiet HEAD; then
+            git commit -m "Update from GitHub Actions"
+          fi
+          git push https://YOUR_USERNAME:$HF_TOKEN@huggingface.co/spaces/YOUR_USERNAME/circle-search-api main
+```
+
+### Step 5-3: 定期データ更新の設定（オプション）
+
+既存の `.github/workflows/update_data.yaml` を確認:
+
+```yaml
+name: update data
+on:
+  schedule:
+    - cron: '0 18 * * *' # 毎日3時（JST）に実行
+  workflow_dispatch:
+
+jobs:
+  call:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger HF Space FastAPI Endpoint
+        run: |
+          curl --fail --show-error --silent -X 'POST' \
+            '${{ vars.FASTAPI_URL }}/tasks/update' \
+            -H 'accept: application/json' \
+            -H 'Authorization: Bearer ${{ secrets.HF_TOKEN }}' \
+            -H 'X-API-KEY: ${{ secrets.API_SECRET_KEY }}' \
+            -d ''
+```
+
+### Step 5-4: 動作確認
+
+1. GitHubリポジトリで "Actions" タブをクリック
+
+2. "Deploy to Hugging Face Space" ワークフローを選択
+
+3. "Run workflow" をクリックして手動実行
+
+4. ログを確認してデプロイが成功したことを確認
+
+---
+
+## Phase 6: circle-search-26 からの接続テスト
+
+### Step 6-1: 環境変数の設定
+
+`circle-search-26/.env.local` ファイルを作成:
+
+```bash
+# 検索API設定
+NEXT_PUBLIC_USE_API_SEARCH=true
+NEXT_PUBLIC_SEARCH_API_URL=https://YOUR_USERNAME-circle-search-api.hf.space
+NEXT_PUBLIC_SEARCH_API_KEY=your-secret-key-here
+```
+
+### Step 6-2: 開発サーバーの起動
+
+```bash
+cd /path/to/circle-search-26
+npm run dev
+```
+
+### Step 6-3: 検索テスト
+
+1. ブラウザで `http://localhost:3000` を開く
+
+2. 検索バーに「サッカー」と入力
+
+3. 開発者ツール（F12）の "Network" タブを確認:
+   - `https://YOUR_USERNAME-circle-search-api.hf.space/api/search` へのPOSTリクエストが表示される
+   - レスポンスに `circleIds` が含まれている
+
+4. コンソールログを確認:
+   ```
+   Search using API: サッカー
+   API search success: 1 results
+   ```
+
+### Step 6-4: フォールバック機能のテスト
+
+1. `.env.local` で一時的に無効なAPIキーを設定:
+   ```bash
+   NEXT_PUBLIC_SEARCH_API_KEY=invalid-key
+   ```
+
+2. サーバーを再起動して検索
+
+3. コンソールログを確認:
+   ```
+   API search failed, falling back to client-side search
+   ```
+
+4. 検索結果が表示されることを確認（クライアントサイド検索が動作）
+
+---
+
+## Phase 7: 本番デプロイとモニタリング
+
+### Step 7-1: Cloudflare Pages の環境変数設定
+
+1. Cloudflare Dashboard で Pages プロジェクトを開く
+
+2. "Settings" → "Environment variables" をクリック
+
+3. Production環境に以下を追加:
+   ```
+   NEXT_PUBLIC_USE_API_SEARCH=true
+   NEXT_PUBLIC_SEARCH_API_URL=https://YOUR_USERNAME-circle-search-api.hf.space
+   NEXT_PUBLIC_SEARCH_API_KEY=your-secret-key-here
+   ```
+
+### Step 7-2: デプロイ
+
+```bash
+cd /path/to/circle-search-26
+git add .
+git commit -m "Enable API search"
+git push origin main
+```
+
+Cloudflare Pagesが自動的にデプロイします。
+
+### Step 7-3: 本番環境での動作確認
+
+1. デプロイされたサイトにアクセス
+
+2. 検索機能をテスト
+
+3. ブラウザの開発者ツールでネットワークリクエストを確認
+
+### Step 7-4: モニタリング設定
+
+#### Huggingface Space のログ確認
+
+1. Huggingface SpaceのページでLogsタブを確認
+
+2. リクエスト数、エラーレート、レスポンスタイムを監視
+
+#### PostHog 分析（オプション）
+
+1. https://posthog.com でアカウント作成
+
+2. プロジェクトを作成してAPIキーを取得
+
+3. Huggingface Spaceのシークレットに追加:
+   ```
+   POSTHOG_PROJECT_API_KEY=phc_xxxxx
+   GET_LOGS=true
+   ```
+
+4. PostHogダッシュボードで検索クエリや結果数を分析
+
+---
+
+## トラブルシューティング
+
+### 問題1: Huggingface Space のビルドが失敗する
+
+**症状**: Build logに "Error: ..." が表示される
+
+**解決策**:
+1. `requirements.txt` の依存関係を確認
+2. `Dockerfile` の構文を確認
+3. `.env` ファイルが含まれていないことを確認
+4. ログの詳細なエラーメッセージを確認
+
+### 問題2: 検索が遅い
+
+**症状**: 検索リクエストに3秒以上かかる
+
+**解決策**:
+1. Huggingface Spaceの無料プランはCPUが限られているため、初回リクエストが遅い
+2. キャッシュを有効化（`CIRCLES_CACHE_TTL=600` 等）
+3. 有料プランへの移行を検討（$0.60/hour〜）
+
+### 問題3: CORSエラーが発生する
+
+**症状**: ブラウザのコンソールに "CORS policy" エラーが表示される
+
+**解決策**:
+1. `app/main.py` のCORS設定を確認
+2. `allow_origins` にCloudflare PagesのURLが含まれているか確認
+3. Huggingface Spaceを再デプロイ
+
+### 問題4: APIキー認証エラー
+
+**症状**: "Could not validate credentials" エラーが返される
+
+**解決策**:
+1. `.env.local` のAPIキーを確認
+2. Huggingface Spaceのシークレット設定を確認
+3. `app/main.py` の `get_api_key` 関数を確認
+
+### 問題5: 検索結果が0件
+
+**症状**: 検索クエリに対して結果が返されない
+
+**解決策**:
+1. `resources/original_circles.csv` にデータが存在するか確認
+2. `data/generated/circles.json` が正しく生成されているか確認
+3. デバッグモード（`debug: true`）で検索して詳細を確認
+4. `config/search_model.json` のフィルター設定を確認
+
+---
+
+## 次のステップ
+
+### 実際のサークルデータの追加
+
+1. Google Spreadsheetsでサークルデータを整理
+
+2. CSVファイルとしてエクスポート
+
+3. `resources/original_circles.csv` に配置
+
+4. `python scripts/build_all.py` を実行
+
+5. Gitにコミット・プッシュ
+
+### 検索精度の改善
+
+1. `config/search_model.json` のパラメータを調整:
+   - `field_weights`: フィールドごとの重み
+   - `bm25f.k1`, `bm25f.b`: BM25のパラメータ
+   - `word_sim.alpha`: BM25とベクトル類似度のバランス
+
+2. ユーザーフィードバックを収集
+
+3. 同義語辞書を拡充（`resources/synonyms_custom.json`）
+
+### パフォーマンス最適化
+
+1. キャッシュ戦略の改善:
+   - Redis等の外部キャッシュの導入
+   - CDNの活用
+
+2. Huggingface Space の有料プランへの移行
+
+3. リクエストのバッチング実装
+
+---
+
+## まとめ
+
+このガイドに従うことで、以下が実現できます:
+
+✅ chibafes-website-api-v2 をフォークしてサークル検索用に改造
+✅ BM25F + fastText による高精度な日本語検索
+✅ Huggingface Space での無料ホスティング
+✅ GitHub Actions による自動デプロイ
+✅ circle-search-26 からのシームレスな統合
+✅ フォールバック機能による高可用性
+
+**推定所要時間**: 初回セットアップ 4-6時間
+
+**運用コスト**: 月0円〜（Huggingface無料枠内）
+
+---
+
+## 参考資料
+
+- [chibafes-website-api-v2 Documentation](./docs/)
+- [Huggingface Spaces Documentation](https://huggingface.co/docs/hub/spaces)
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+- [GitHub Actions Documentation](https://docs.github.com/actions)
+- [BM25アルゴリズム詳説](./docs/検索アルゴリズム詳説.md)

resources/original_circles.csv

@@ -0,0 +1,4 @@
+circleId,circleName,circleNameKana,isOfficial,isIntercollegiate,projectId,projectName,mainCategory,subCategory,category,areaCode,pamphletNumber,prSummary,description,detailDescription,memberCount,tags,featureTags,isArchived
+circle-001,千葉大学サッカー部,ちばだいがくさっかーぶ,true,false,,,SPORTS,BALL_SPORTS,PERFORMANCE,T,1,関東大学サッカーリーグ所属。週5日の練習で全国大会出場を目指しています。,サッカー部の詳細説明,詳細な活動内容,50,サッカー|運動,freq_daily|size_medium|feat_official,false
+circle-002,吹奏楽部,すいそうがくぶ,true,false,,,CULTURE,MUSIC_PERFORM,MUSIC,L,2,定期演奏会や学祭での演奏を行っています。,吹奏楽部の詳細説明,詳細な活動内容,60,音楽|吹奏楽,freq_3_4|size_large|feat_official,false
+circle-003,軽音楽サークル,けいおんがくさーくる,false,false,,,CULTURE,MUSIC_PERFORM,MUSIC,K,3,バンド活動を通じて音楽を楽しむサークルです。,軽音楽サークルの詳細説明,詳細な活動内容,30,音楽|バンド,freq_1_2|size_medium|feat_beginner,false

schemas/__init__.py

@@ -0,0 +1,10 @@
+from .circles import Circle, CircleSummary, CircleDetail, CircleIds, Image, Sns
+
+__all__ = [
+    "Circle",
+    "CircleSummary",
+    "CircleDetail",
+    "CircleIds",
+    "Image",
+    "Sns",
+]

schemas/circles.py

@@ -0,0 +1,132 @@
+from typing import Literal
+from pydantic import BaseModel
+
+
+class Image(BaseModel):
+    """画像情報"""
+    url: str
+    alt: str | None = None
+    order: int = 0
+
+
+class Sns(BaseModel):
+    """SNS情報"""
+    type: str
+    url: str
+
+
+class Circle(BaseModel):
+    """サークル情報（フル）"""
+    circleId: str
+    circleName: str
+    circleNameKana: str
+    isOfficial: bool
+    isIntercollegiate: bool
+
+    # 企画関連（大祭企画との紐付け用、オプション）
+    projectId: str | None = None
+    projectName: str | None = None
+
+    # カテゴリ情報
+    mainCategory: str
+    subCategory: str | None = None
+    category: str | None = None  # 大祭用カテゴリ
+
+    # 場所情報
+    areaCode: str | None = None
+    areaNumber: str | None = None
+    pamphletNumber: int | None = None
+
+    # 開催日情報（大祭用、オプション）
+    beforeDay: bool = False
+    firstDay: bool = False
+    secondDay: bool = False
+    thirdDay: bool = False
+
+    # 概要情報
+    prSummary: str | None = None
+    description: str | None = None
+    detailDescription: str | None = None
+    message: str | None = None
+
+    # 画像・SNS
+    images: list[Image] = []
+    sns: list[Sns] = []
+
+    # メンバー情報
+    memberCount: int | None = None
+    genderRatioMale: float | None = None
+    genderRatioFemale: float | None = None
+
+    # 設立情報
+    establishedYear: int | None = None
+
+    # 金銭情報
+    annualFee: int | None = None
+    hasNoFee: bool = False
+
+    # タグ
+    tags: list[str] = []
+    featureTags: list[str] = []
+
+    # 活動情報
+    activityFrequency: str | None = None
+    activityTimeSlot: str | None = None
+
+    # 新歓情報
+    hasTrialEvent: bool = False
+
+    # アーカイブ
+    isArchived: bool = False
+
+
+class CircleSummary(BaseModel):
+    """サークル概要（一覧表示用）"""
+    circleId: str
+    circleName: str
+    circleNameKana: str
+    isOfficial: bool
+    isIntercollegiate: bool
+    projectId: str | None = None
+    projectName: str | None = None
+    mainCategory: str
+    subCategory: str | None = None
+    category: str | None = None
+    areaCode: str | None = None
+    pamphletNumber: int | None = None
+    prSummary: str | None = None
+    description: str | None = None
+    mainImage: Image | None = None
+    memberCount: int | None = None
+    tags: list[str] = []
+    featureTags: list[str] = []
+    isArchived: bool = False
+
+
+class CircleDetail(BaseModel):
+    """サークル詳細"""
+    circleId: str
+    circleName: str
+    circleNameKana: str
+    isOfficial: bool
+    isIntercollegiate: bool
+    projectId: str | None = None
+    projectName: str | None = None
+    mainCategory: str
+    subCategory: str | None = None
+    category: str | None = None
+    prSummary: str | None = None
+    description: str | None = None
+    detailDescription: str | None = None
+    message: str | None = None
+    images: list[Image] = []
+    sns: list[Sns] = []
+    memberCount: int | None = None
+    tags: list[str] = []
+    featureTags: list[str] = []
+    isArchived: bool = False
+
+
+class CircleIds(BaseModel):
+    """検索結果のID配列"""
+    circleIds: list[str]

schemas/tf_token.py

@@ -15,8 +15,8 @@ class Fields(BaseModel):
     prDetail: TfOfField
 
 
-class Project(BaseModel):
-    projectId: str
+class Circle(BaseModel):
+    circleId: str
     fields: Fields
     tf: dict[str, int]
     tokens: dict[str, int]

scripts/2_create_circles_data.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""
+CSVからサークルデータのJSONを生成するスクリプト
+"""
+
+import os
+import sys
+import csv
+import json
+
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from utils.logger import setup_logger
+from utils.json import get_file_path_from_config, json_dumps
+
+# --- ロギングの設定 ---
+log = setup_logger(__name__)
+
+
+def parse_bool(value: str) -> bool:
+    """文字列をブール値に変換"""
+    return value.lower() in ("true", "1", "yes")
+
+
+def parse_int(value: str) -> int | None:
+    """文字列を整数に変換（空の場合はNone）"""
+    if not value or value.strip() == "":
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def parse_list(value: str, delimiter: str = "|") -> list[str]:
+    """区切り文字で分割してリストに変換"""
+    if not value or value.strip() == "":
+        return []
+    return [item.strip() for item in value.split(delimiter) if item.strip()]
+
+
+def main():
+    """CSVからサークルデータを読み込み circles.json を生成する。"""
+
+    log.info("CSVファイルからサークルデータを読み込みcircles.jsonを生成します。")
+
+    input_csv_path = get_file_path_from_config(
+        "circles.original_csv", "resources/original_circles.csv"
+    )
+    output_json_path = get_file_path_from_config(
+        "circles.circles_json", "data/generated/circles.json"
+    )
+
+    if not os.path.exists(input_csv_path):
+        log.error(f"入力CSVファイルが見つかりません: {input_csv_path}")
+        sys.exit(1)
+
+    circles = []
+    try:
+        with open(input_csv_path, "r", encoding="utf-8") as f:
+            reader = csv.DictReader(f)
+            for row in reader:
+                circle = {
+                    "circleId": row.get("circleId", ""),
+                    "circleName": row.get("circleName", ""),
+                    "circleNameKana": row.get("circleNameKana", ""),
+                    "isOfficial": parse_bool(row.get("isOfficial", "false")),
+                    "isIntercollegiate": parse_bool(row.get("isIntercollegiate", "false")),
+                    "projectId": row.get("projectId") or None,
+                    "projectName": row.get("projectName") or None,
+                    "mainCategory": row.get("mainCategory", ""),
+                    "subCategory": row.get("subCategory", ""),
+                    "category": row.get("category", ""),
+                    "areaCode": row.get("areaCode", ""),
+                    "pamphletNumber": parse_int(row.get("pamphletNumber", "")),
+                    "prSummary": row.get("prSummary", ""),
+                    "description": row.get("description", ""),
+                    "detailDescription": row.get("detailDescription", ""),
+                    "memberCount": parse_int(row.get("memberCount", "")),
+                    "tags": parse_list(row.get("tags", "")),
+                    "featureTags": parse_list(row.get("featureTags", "")),
+                    "isArchived": parse_bool(row.get("isArchived", "false")),
+                    "images": [],  # CSVではimagesは空配列
+                    "sns": [],  # CSVではsnsは空配列
+                }
+                circles.append(circle)
+    except Exception as exc:
+        log.error(f"CSVファイルの読み込みに失敗しました: {exc}")
+        sys.exit(1)
+
+    os.makedirs(os.path.dirname(output_json_path), exist_ok=True)
+    json_dumps(circles, output_json_path)
+
+    log.info(f"サークルデータの生成が完了しました: {output_json_path} ({len(circles)}件)")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

scripts/3_build_synonyms_from_sudachi.py

@@ -12,13 +12,13 @@ sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
 from utils.logger import setup_logger
 from utils.json import get_file_path_from_config, field_getter, json_dumps
 from utils.io import LineIteratorIO, comment_filtered_lines
-from schemas.projects import Project
+from schemas.circles import Circle
 
 # --- ロギングの設定 ---
 log = setup_logger(__name__)
 
 # --- 設定 ---
-input_file = get_file_path_from_config("projects.projects_json")
+input_file = get_file_path_from_config("circles.circles_json")
 output_file = get_file_path_from_config("sudachi.synonyms_cache")
 sudachi_config_file = get_file_path_from_config("sudachi.sudachi_config")
 
@@ -65,13 +65,13 @@ def tokenize(text: str) -> list[str]:
     return tokens
 
 
-def get_corpus_vocab(projects: list[Project]) -> set[str]:
-    """プロジェクト全体から語彙セットを構築する"""
+def get_corpus_vocab(circles: list[Circle]) -> set[str]:
+    """サークル全体から語彙セットを構築する"""
     vocab = set()
     log.info("語彙セットを構築中...")
-    for project in tqdm(projects):
+    for circle in tqdm(circles):
         for field in target_fields:
-            text = getattr(project, field, "")
+            text = getattr(circle, field, "")
             if not text:
                 continue
             tokens = tokenize(str(text))
@@ -124,8 +124,8 @@ def main():
 
     with open(input_file, encoding="utf-8") as f:
         try:
-            project_dicts = json.load(f)
-            projects = [Project(**item) for item in project_dicts]
+            circle_dicts = json.load(f)
+            circles = [Circle(**item) for item in circle_dicts]
         except json.JSONDecodeError as e:
             log.error(f"JSONデコードエラー: {e}")
             sys.exit(1)
@@ -137,7 +137,7 @@ def main():
             sys.exit(1)
 
     # 1. コーパスの語彙を構築
-    vocab = get_corpus_vocab(projects)
+    vocab = get_corpus_vocab(circles)
     log.info(f"コーパスの語彙数: {len(vocab)}")
 
     # 2. Sudachiの同義語辞書をパース

scripts/4_prepare_bm25f_meta.py

@@ -67,32 +67,32 @@ def main():
         log.error(f"設定の読み込みに失敗しました: {e}")
         sys.exit(1)
 
-    projects_path = get_file_path_from_config(
-        "projects.projects_json", "data/generated/projects.json"
+    circles_path = get_file_path_from_config(
+        "circles.circles_json", "data/generated/circles.json"
     )
     output_path = get_file_path_from_config(
         "bm25.bm25_meta", "data/generated/bm25_meta.json"
     )
 
     try:
-        with open(projects_path, encoding="utf-8") as f:
-            projects = json.load(f)
+        with open(circles_path, encoding="utf-8") as f:
+            circles = json.load(f)
     except Exception as e:
-        log.error(f"projects.jsonの読み込みに失敗しました: {e}")
+        log.error(f"circles.jsonの読み込みに失敗しました: {e}")
         sys.exit(1)
 
     tok, mode = build_tokenizer(sudachi_config_path)
 
-    N = len(projects)
+    N = len(circles)
     df: Dict[str, int] = defaultdict(int)
     field_token_lens_sum: Dict[str, int] = {f: 0 for f in target_fields}
 
     log.info(f"ドキュメント数: {N}")
 
-    for p in projects:
+    for c in circles:
         seen_in_doc = set()
         for field in target_fields:
-            text = p.get(field) or ""
+            text = c.get(field) or ""
             if not text:
                 continue
             toks = tokenize(str(text), tok, mode, target_pos_l1, ban_list, stopwords)

scripts/5_prepare_tf_token.py

@@ -67,26 +67,26 @@ def main():
         log.error(f"設定の読み込みに失敗しました: {e}")
         sys.exit(1)
 
-    projects_path = get_file_path_from_config(
-        "projects.projects_json", "data/generated/projects.json"
+    circles_path = get_file_path_from_config(
+        "circles.circles_json", "data/generated/circles.json"
     )
     output_path = get_file_path_from_config(
         "bm25.tf_token", "data/generated/tf_token.json"
     )
 
     try:
-        with open(projects_path, encoding="utf-8") as f:
-            projects = json.load(f)
+        with open(circles_path, encoding="utf-8") as f:
+            circles = json.load(f)
     except Exception as e:
-        log.error(f"projects.jsonの読み込みに失敗しました: {e}")
+        log.error(f"circles.jsonの読み込みに失敗しました: {e}")
         sys.exit(1)
 
     tok, mode = build_tokenizer(sudachi_config_path)
 
-    results: List[tf_token.Project] = []
+    results: List[tf_token.Circle] = []
 
-    for p in projects:
-        project_id = p.get("projectId")
+    for c in circles:
+        circle_id = c.get("circleId")
 
         # 各フィールドのトークン化とTF
         field_objs: Dict[str, tf_token.TfOfField] = {}
@@ -94,7 +94,7 @@ def main():
         doc_token_set: set = set()
 
         for field in target_fields:
-            text = p.get(field) or ""
+            text = c.get(field) or ""
             toks = tokenize(str(text), tok, mode, target_pos_l1, ban_list, stopwords)
             tf = Counter(toks)
             field_objs[field] = tf_token.TfOfField(len=len(toks), tf=dict(tf))
@@ -114,14 +114,14 @@ def main():
             prDetail=get_field("prDetail"),
         )
 
-        project_entry = tf_token.Project(
-            projectId=project_id,
+        circle_entry = tf_token.Circle(
+            circleId=circle_id,
             fields=fields_obj,
             tf=dict(doc_tf_counter),
             # tokens はユニーク語彙の存在フラグ(1)とする
             tokens={t: 1 for t in sorted(doc_token_set)},
         )
-        results.append(project_entry)
+        results.append(circle_entry)
 
     os.makedirs(os.path.dirname(output_path), exist_ok=True)
     json_dumps([r.model_dump() for r in results], output_path)

scripts/7_prepare_circle_names.py

@@ -8,7 +8,7 @@ sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
 
 from utils.logger import setup_logger
 from utils.json import get_file_path_from_config, json_dumps
-from schemas.projects import Project
+from schemas.circles import Circle
 
 log = setup_logger(__name__)
 
@@ -38,7 +38,7 @@ def get_substrings(texts: Dict[any, str]) -> Set[str]:
     """テキストから2文字以上の連続部分文字列をすべて抽出する。"""
     substrings = set()
     for key, text in texts.items():
-        if key == "projectId":
+        if key == "circleId":
             continue
         text = text.replace(" ", "").replace("　", "")
         length = len(text)
@@ -50,11 +50,11 @@ def get_substrings(texts: Dict[any, str]) -> Set[str]:
 
 
 def main():
-    input_file = get_file_path_from_config("projects.projects_json")
+    input_file = get_file_path_from_config("circles.circles_json")
 
     try:
         with open(input_file, encoding="utf-8") as f:
-            projects = json.load(f)
+            circles = json.load(f)
     except FileNotFoundError:
         log.error(f"入力ファイルが見つかりません: {input_file}")
         sys.exit(1)
@@ -64,15 +64,15 @@ def main():
 
     # --- 団体名データを生成 ---
     output_file_names = get_file_path_from_config("substring.circle_names")
-    projects = [Project(**item) for item in projects]
+    circles = [Circle(**item) for item in circles]
     circle_names = [
         {
-            "projectId": p.projectId,
-            "circle": p.circleName,
-            "circleNormalized": normalized_circle_name(p.circleName),
-            "circleKana": p.circleNameKana or "",
+            "circleId": c.circleId,
+            "circle": c.circleName,
+            "circleNormalized": normalized_circle_name(c.circleName),
+            "circleKana": c.circleNameKana or "",
         }
-        for p in projects
+        for c in circles
     ]
 
     # 出力先ディレクトリ作成（念のため）
@@ -84,18 +84,18 @@ def main():
 
     # --- 部分文字列インデックスを生成 ---
     output_file_substring = get_file_path_from_config("substring.substring_index")
-    substring_to_project_ids: Dict[str, List[str]] = defaultdict(list)
-    for proj in circle_names:
-        projectId = proj["projectId"]
-        substrings = get_substrings(proj)
+    substring_to_circle_ids: Dict[str, List[str]] = defaultdict(list)
+    for circle in circle_names:
+        circleId = circle["circleId"]
+        substrings = get_substrings(circle)
         for substr in substrings:
-            substring_to_project_ids[substr].append(projectId)
+            substring_to_circle_ids[substr].append(circleId)
 
     # 出力先ディレクトリ作成（念のため）
     os.makedirs(os.path.dirname(output_file_substring), exist_ok=True)
 
     # JSON に書き出し
-    json_dumps(substring_to_project_ids, output_file_substring)
+    json_dumps(substring_to_circle_ids, output_file_substring)
     log.info(f"部分文字列インデックスを出力しました: {output_file_substring}")
 
 

scripts/build_all.py

@@ -30,8 +30,8 @@ def main():
     # Step 1: Sudachi user dict (optional but recommended before tokenization)
     run_step([sys.executable, "scripts/1_build_dict.py"], allow_fail=True)
 
-    # Step 2: projects.json
-    run_step([sys.executable, "scripts/2_create_projects_data.py"])
+    # Step 2: circles.json
+    run_step([sys.executable, "scripts/2_create_circles_data.py"])
 
     # Step 3: synonyms cache
     run_step([sys.executable, "scripts/3_build_synonyms_from_sudachi.py"])  # idempotent