Merge pull request #248 from thrcle/feat/layer-rename

refactor: rename semantic layers (guild→org, channel→team, member→user)

Author: seyoung4503

docs/ARCHITECTURE.md

@@ -99,7 +99,7 @@
 - [`run_sql.py`](../src/lang2sql/tools/run_sql.py) — safety 통과 후 explorer로 실행
 - [`explore_schema.py`](../src/lang2sql/tools/explore_schema.py) — 테이블/컬럼 introspection
 - [`enrich_schema.py`](../src/lang2sql/tools/enrich_schema.py) — LLM으로 컬럼 메타데이터 자동 보강
-- [`semantic_federation.py`](../src/lang2sql/tools/semantic_federation.py) — `term_custom`: guild/channel/member 계층 용어 사전 (KV 기반, narrow→wide lookup)
+- [`semantic_federation.py`](../src/lang2sql/tools/semantic_federation.py) — `term_custom`: org/team/user 계층 용어 사전 (KV 기반, narrow→wide lookup)
 - [`org_setup.py`](../src/lang2sql/tools/org_setup.py) — 전사/팀 단위 용어 일괄 등록
 - [`remember.py`](../src/lang2sql/tools/remember.py) — fact 저장
 - [`ask_user.py`](../src/lang2sql/tools/ask_user.py) — 모호하면 사용자에게 질문

docs/USAGE.md

@@ -26,7 +26,6 @@ DB가 연결되지 않으면 SQL을 실행할 수 없습니다.
 
 DB 종류(PostgreSQL, MySQL, SQLite 등)를 선택하는 안내가 나타납니다. 접속 정보를 입력하면 연결됩니다. DSN을 직접 알고 있다면 `/connect dsn:...`으로 바로 입력할 수도 있습니다.
 
-> 관리자 권한이 필요합니다.
 
 ---
 
@@ -87,7 +86,7 @@ DB 스키마를 분석해 비즈니스 용어 후보를 자동으로 뽑습니
 같은 용어가 여러 레이어에 등록된 경우 **좁은 범위가 우선** 적용됩니다.
 
 ```
-개인(member) > 채널(channel) > 전사(guild)
+개인(member) > 채널(channel) > 전사(org)
 ```
 
 예를 들어 "활성고객"을 전사에서는 "30일 내 로그인"으로 정의했더라도, 마케팅 채널에서 "14일 내 로그인"으로 따로 등록하면 마케팅 채널 안에서만 그 정의가 우선 적용됩니다. 다른 채널에는 영향이 없습니다.
@@ -98,10 +97,9 @@ DB 스키마를 분석해 비즈니스 용어 후보를 자동으로 뽑습니
 
 | 커맨드 | 설명 |
 |---|---|
-| `/setup` | DB 연결 마법사 (관리자) |
+| `/setup` | DB 연결 마법사 |
 | `/connect dsn:...` | DSN으로 직접 DB 연결 |
 | `/ingest content:...` | 텍스트에서 용어 후보 추출 |
-| `/ingest ref:파일명` | 서버 파일에서 용어 후보 추출 |
 | `/confirm_ingest ref:... accept:... layer:...` | 추출된 후보 검토 후 등록 |
 | `/term_custom` | 용어 직접 등록 (위저드) |
 | `/term_custom action:show` | 등록된 용어 전체 조회 |
@@ -111,6 +109,7 @@ DB 스키마를 분석해 비즈니스 용어 후보를 자동으로 뽑습니
 | `/enrich` | DB 컬럼 메타데이터 자동 보강 |
 | `/remember text:...` | 사실 기억 저장 |
 | `/audit_me` | 내 활동 이력 조회 |
+| `/help` | 사용 방법 안내 |
 
 ---
 
@@ -119,8 +118,8 @@ DB 스키마를 분석해 비즈니스 용어 후보를 자동으로 뽑습니
 **Q. 질문했는데 엉뚱한 SQL이 나와요.**
 등록된 용어가 없거나 DB 메타데이터가 부족한 경우입니다. `/enrich`로 컬럼 설명을 보강하거나 `/term_custom`으로 관련 용어를 등록해보세요.
 
-**Q. "guild 용어는 관리자만 등록 가능" 오류가 나요.**
-`layer:guild`는 관리자 권한이 필요합니다. `layer:channel`로 채널 범위로 등록하거나 관리자에게 요청하세요.
+**Q. "org 용어는 관리자만 등록 가능" 오류가 나요.**
+`layer:org`는 관리자 권한이 필요합니다. `layer:team`으로 채널 범위로 등록하거나 관리자에게 요청하세요.
 
 **Q. 이전 대화 내용을 기억하나요?**
 같은 채널(또는 DM 스레드)에서 이어지는 대화는 맥락이 유지됩니다. `/remember`로 중요한 사실을 명시적으로 저장할 수도 있습니다.

src/lang2sql/adapters/storage/okf_bundle.py

@@ -105,7 +105,7 @@ def import_(self, store: "SqliteStore", kv_scope: str) -> int:
     # ------------------------------------------------------------------
 
     def _scope_dir(self, entry: FedEntry) -> Path:
-        label = "guild" if entry.layer == "guild" else f"{entry.layer}:{entry.entity}"
+        label = "org" if entry.layer == "org" else f"{entry.layer}:{entry.entity}"
         return self.base_dir / label
 
     def _concept_path(self, entry: FedEntry) -> Path:
@@ -172,7 +172,7 @@ def _md_to_entry(path: Path) -> FedEntry | None:
 
     return FedEntry(
         term=str(fm.get("title", path.stem)),
-        layer=str(fm.get("layer", "guild")),
+        layer=str(fm.get("layer", "org")),
         entity=str(fm.get("entity", "")),
         definition=str(fm.get("description", "")),
         synonyms=fm.get("synonyms") or [],

src/lang2sql/core/identity.py

@@ -21,8 +21,8 @@ class ScopeLevel(str, Enum):
     """
 
     THREAD = "thread"
-    CHANNEL = "channel"
-    GUILD = "guild"
+    CHANNEL = "team"
+    GUILD = "org"
     BUILTIN = "builtin"
 
 

src/lang2sql/frontends/discord/bot.py

@@ -176,7 +176,7 @@ async def confirm_ingest(
             interaction: discord.Interaction,
             ref: str,
             accept: str = "all",
-            layer: str = "channel",
+            layer: str = "team",
         ) -> None:
             await self._run(
                 interaction,
@@ -219,7 +219,7 @@ async def term_custom(
             interaction: discord.Interaction,
             action: str = "",
             term: str = "",
-            layer: str = "member",
+            layer: str = "team",
         ) -> None:
             ident = to_identity(_interaction_context(interaction))
             if action == "show":

src/lang2sql/frontends/discord/commands.py

@@ -179,7 +179,7 @@ async def term_custom(
         identity: Identity,
         term: str = "",
         definition: str = "",
-        layer: str = "member",
+        layer: str = "team",
         synonyms: str = "",
         inferred: bool = False,
         scan: bool = False,
@@ -252,7 +252,7 @@ async def confirm_ingest(
         identity: Identity,
         ref: str,
         accept: str = "all",
-        layer: str = "channel",
+        layer: str = "team",
     ) -> OutboundMessage:
         """ingest_doc로 추출한 후보를 검토 후 시멘틱 레이어에 등록."""
         ctx = await self._concierge.build_context(identity)
@@ -270,24 +270,24 @@ async def help(self) -> OutboundMessage:
 **Lang2SQL 사용 가이드**
 
 **📊 질문하기**
-봇을 멘션하거나 채널에서 자연어로 질문하세요.
+봇을 멘션하거나 스레드에서 자연어로 질문하세요.
 > @Lang2SQL 이번 달 매출 상위 고객 10명 알려줘
 
-**🗄️ DB 연결** (관리자)
+**🗄️ DB 연결**
 `/setup` — 안내에 따라 DB 접속 정보 입력
 `/connect dsn:...` — DSN 직접 입력
 
 **📖 비즈니스 용어 등록**
 `/ingest content:월매출은 SUM(orders.amount), 활성고객은 30일 내 로그인`
 → 후보 추출 후 아래 커맨드로 확정
-`/confirm_ingest ref:inline:xxxx accept:all layer:channel`
+`/confirm_ingest ref:inline:xxxx accept:all layer:team`
 
 `/term_custom` — 용어 직접 등록 (위저드)
 `/term_custom action:show` — 등록된 용어 조회
 `/org_setup org:회사명` — DB 스캔으로 용어 자동 추출
 
 **🏷️ 용어 우선순위**
-개인(member) > 채널(channel) > 전사(guild)
+개인(user) > 팀(team) > 전사(org)
 같은 채널 안에서 등록한 정의가 전사 정의보다 우선 적용됩니다.
 
 **🔧 기타**

src/lang2sql/frontends/discord/term_wizard.py

@@ -1,6 +1,6 @@
 """term_wizard.py — /term_custom 등록 폼 (2단계 UI).
 
-Step 1: Select — 전사(guild) / 채널·팀(channel) / 개인(member) 선택
+Step 1: Select — 전사(org) / 채널·팀(channel) / 개인(member) 선택
 Step 2: Modal — 용어명·정의·동의어 입력
 
 채널이 팀 경계 역할을 하므로 entity 직접 입력 불필요.
@@ -23,17 +23,17 @@
 _LAYER_OPTIONS = [
     discord.SelectOption(
         label="전사 (Guild) — 회사 공통 정의",
-        value="guild",
+        value="org",
         description="모든 채널에서 기본값으로 사용",
     ),
     discord.SelectOption(
         label="채널 (팀) — 이 채널 전용 정의",
-        value="channel",
+        value="team",
         description="다른 채널과 충돌 없이 이 채널에서만 유효",
     ),
     discord.SelectOption(
         label="개인 — 나만 사용하는 정의",
-        value="member",
+        value="user",
         description="전사·채널 정의를 조용히 덮어씀",
     ),
 ]

src/lang2sql/harness/system_prompt.py

@@ -21,6 +21,10 @@
 - Discover schema with explore_schema before guessing table or column names.
 - Prefer definitions from the semantic layer below over your own assumptions.
 - Answer concisely. Show only the final successful SQL you ran, not intermediate attempts.
+
+Clarification rule:
+- If the user's query contains business terms (e.g. '활성고객', '월매출', '신규유저') that are NOT defined in the semantic layer and whose meaning is ambiguous, ask ONE concise clarifying question BEFORE running any SQL. Do not guess.
+- After answering with SQL results, if you had to infer a term's meaning yourself, suggest the user save it: "이 정의를 저장하려면 `/term_custom`으로 등록해두세요. 다음 질문부터 자동 적용됩니다."
 """
 
 

src/lang2sql/tenancy/concierge.py

@@ -150,12 +150,13 @@ def _default_llm() -> LLMPort:
         model = os.environ.get("LANG2SQL_LLM_MODEL", "default")
         # Local servers (vLLM, Ollama) speak OpenAI-compatible API; dummy key satisfies the header.
         api_key = os.environ.get("OPENAI_API_KEY") or "local"
+        timeout = float(os.environ.get("LANG2SQL_LLM_TIMEOUT", "120"))
         url = base_url.rstrip("/")
         if not url.endswith("/chat/completions"):
             if not url.endswith("/v1"):
                 url = url + "/v1"
             url = url + "/chat/completions"
-        return OpenAILLM(model=model, api_key=api_key, base_url=url)
+        return OpenAILLM(model=model, api_key=api_key, base_url=url, timeout=timeout)
     if os.environ.get("OPENAI_API_KEY"):
         return OpenAILLM()
     return FakeLLM()

src/lang2sql/tools/confirm_ingest.py

@@ -58,9 +58,9 @@ def spec(self) -> ToolSpec:
                     },
                     "layer": {
                         "type": "string",
-                        "enum": ["guild", "channel", "member"],
+                        "enum": ["org", "team", "user"],
                         "description": "scope to register under (default: channel)",
-                        "default": "channel",
+                        "default": "team",
                     },
                 },
                 "required": ["ref"],
@@ -70,7 +70,7 @@ def spec(self) -> ToolSpec:
     async def run(self, args: dict[str, Any], ctx: "HarnessContext") -> ToolResult:
         ref = (args.get("ref") or "").strip()
         accept = (args.get("accept") or "all").strip()
-        layer_raw = (args.get("layer") or "channel").strip()
+        layer_raw = (args.get("layer") or "team").strip()
 
         if not ref:
             return ToolResult(call_id="", content="'ref' is required.", is_error=True)
@@ -113,8 +113,8 @@ async def run(self, args: dict[str, Any], ctx: "HarnessContext") -> ToolResult:
 
         entity = (
             ""
-            if layer == "guild"
-            else (channel_id if layer == "channel" else ctx.identity.user_id)
+            if layer == "org"
+            else (channel_id if layer == "team" else ctx.identity.user_id)
         )
         registered: list[str] = []
         for cand in selected: