ummaya 0.2.1 → 0.2.3

package/tui/src/tools/AdapterTool/AdapterTool.ts

@@ -23,6 +23,8 @@ type AdapterPrimitive = 'find' | 'locate' | 'send' | 'check'
 
 type InputSchema = z.ZodType<{ [key: string]: unknown }>
 
+const ROOT_PRIMITIVE_TOOL_NAMES = new Set(['locate', 'find', 'check', 'send'])
+
 const fallbackInputSchema = z.object({}).passthrough() as InputSchema
 
 type JsonObject = Record<string, unknown>
@@ -214,6 +216,10 @@ export function isAdapterToolName(name: string): boolean {
   return resolveAdapter(name) !== undefined
 }
 
+export function isRootPrimitiveToolName(name: string): boolean {
+  return ROOT_PRIMITIVE_TOOL_NAMES.has(name)
+}
+
 export function getAdapterToolByName(name: string): Tool | undefined {
   const entry = resolveAdapter(name)
   return entry ? buildAdapterTool(entry) : undefined
@@ -223,6 +229,258 @@ export function getAdapterTools(): Tools {
   return listAdapters().map(buildAdapterTool)
 }
 
+function searchTokens(text: string): string[] {
+  return text.toLowerCase().match(/[\p{L}\p{N}_-]+/gu) ?? []
+}
+
+function expandedQueryTokens(query: string): Set<string> {
+  const tokens = new Set(searchTokens(query))
+  const compact = query.toLowerCase()
+  if (/[날씨기상비강수기온습도풍속예보관측실황]/u.test(compact)) {
+    for (const token of [
+      '날씨',
+      '기상',
+      '현재',
+      '관측',
+      '실황',
+      'weather',
+      'current',
+      'observation',
+      'forecast',
+      'temperature',
+      'precipitation',
+      'humidity',
+      'wind',
+    ]) {
+      tokens.add(token)
+    }
+  }
+  if (/(응급|응급실|er|emergency)/u.test(compact)) {
+    for (const token of [
+      '응급',
+      '응급실',
+      '응급의료',
+      '응급의료센터',
+      '실시간',
+      '병상',
+      '야간',
+      'emergency',
+      'room',
+      'er',
+      'nmc',
+    ]) {
+      tokens.add(token)
+    }
+  }
+  if (/(병원|의료|진료|약국|hospital|clinic|medical)/u.test(compact)) {
+    for (const token of [
+      '병원',
+      '의료기관',
+      '진료',
+      '진료과목',
+      '야간',
+      '약국',
+      'hospital',
+      'clinic',
+      'medical',
+      'nearby',
+    ]) {
+      tokens.add(token)
+    }
+  }
+  if (/(aed|자동심장|심장충격|제세동)/u.test(compact)) {
+    for (const token of ['aed', '자동심장충격기', '자동제세동기', '심장충격기', '위치']) {
+      tokens.add(token)
+    }
+  }
+  if (/(미세먼지|초미세|대기질|공기질|airquality|air quality)/u.test(compact)) {
+    for (const token of ['미세먼지', '대기질', '대기오염', 'airkorea', 'air', 'quality']) {
+      tokens.add(token)
+    }
+  }
+  if (/(법률|변호사|무료상담|상담)/u.test(compact)) {
+    for (const token of ['법률', '변호사', '마을변호사', '상담', 'legal', 'lawyer']) {
+      tokens.add(token)
+    }
+  }
+  if (/(장례|화장|봉안|장사|funeral)/u.test(compact)) {
+    for (const token of ['장례', '장례식장', '시설사용료', 'funeral', 'fee']) {
+      tokens.add(token)
+    }
+  }
+  if (/(취업|채용|공고|공무원|job|recruit)/u.test(compact)) {
+    for (const token of ['취업', '채용', '공고', '공무원', 'public', 'job']) {
+      tokens.add(token)
+    }
+  }
+  if (/(대학|등록금|유학생|tuition|university)/u.test(compact)) {
+    for (const token of ['대학', '등록금', '유학생', '대학알리미', 'tuition', 'university']) {
+      tokens.add(token)
+    }
+  }
+  if (/(전력|전기|한전|계약종별|power|kepco)/u.test(compact)) {
+    for (const token of ['전력', '전기사용량', '계약종별', '한전', 'kepco', 'power', 'usage']) {
+      tokens.add(token)
+    }
+  }
+  if (/(특보|예비특보|경보|주의보|태풍|warning|alert)/u.test(compact)) {
+    for (const token of ['특보', '예비특보', '경보', '주의보', '기상청', 'weather', 'alert']) {
+      tokens.add(token)
+    }
+  }
+  if (/(교통사고|사고\s*위험|사고다발|위험\s*(구간|도로|지점)|어린이보호구역|보호구역|도로\s*구간|accident|hazard|hotspot)/u.test(compact)) {
+    for (const token of [
+      '교통사고',
+      '사고',
+      '위험',
+      '위험지점',
+      '사고다발',
+      '사고다발구역',
+      '어린이보호구역',
+      '행정동코드',
+      'koroad',
+      'accident',
+      'hazard',
+      'hotspot',
+    ]) {
+      tokens.add(token)
+    }
+  }
+  if (/(주소|위치|좌표|행정|[가-힣]+(시|군|구|동|읍|면|로|길))/u.test(compact)) {
+    for (const token of [
+      'locate',
+      '위치',
+      '주소',
+      '좌표',
+      '행정동',
+      '법정동',
+      'geocode',
+      'address',
+      'kakao',
+    ]) {
+      tokens.add(token)
+    }
+  }
+  if (/(근처|주변|인근|가까운|역|터미널|공항|캠퍼스|대학교|대학|해수욕장|시장|공원|랜드마크|nearby|around)/u.test(compact)) {
+    for (const token of [
+      '장소',
+      '키워드',
+      'poi',
+      '랜드마크',
+      '역',
+      'keyword',
+      'station',
+      'place',
+    ]) {
+      tokens.add(token)
+    }
+  }
+  return tokens
+}
+
+type ScoredAdapterEntry = {
+  entry: AdapterManifestEntry
+  score: number
+}
+
+function queryExplicitlyMentionsCoordinates(query: string): boolean {
+  return /좌표|위도|경도|\blat\b|\blon\b|\blongitude\b|\blatitude\b|wgs84|coord|coord2region|reverse geocode|q0|q1/i.test(query)
+}
+
+function isReverseGeocodeAdapter(toolId: string): boolean {
+  return toolId === 'kakao_coord_to_region' || toolId === 'sgis_adm_cd_lookup'
+}
+
+function queryTargetsKoroadHazardDataset(query: string): boolean {
+  return /(사고\s*위험|위험\s*(구간|도로|지점)|도로\s*구간|어린이보호구역|보호구역|스쿨존|행정동코드|adm_cd|hazard|hotspot)/iu.test(query)
+}
+
+function scoreAdapterEntry(
+  entry: AdapterManifestEntry,
+  queryTokens: Set<string>,
+  query: string,
+): number {
+  const searchHint = entry.search_hint.toLowerCase()
+  const description = (entry.llm_description ?? '').toLowerCase()
+  const haystack = [
+    entry.tool_id,
+    entry.name,
+    entry.primitive,
+    searchHint,
+    description,
+  ].join(' ').toLowerCase()
+  const hintTokens = new Set(searchTokens(searchHint))
+  let score = 0
+  for (const token of queryTokens) {
+    if (!token) continue
+    if (entry.tool_id.toLowerCase().includes(token)) score += 12
+    if (hintTokens.has(token)) score += 8
+    else if (searchHint.includes(token)) score += 4
+    if (description.includes(token)) score += 2
+    if (haystack.includes(token)) score += 1
+  }
+  if (
+    isReverseGeocodeAdapter(entry.tool_id) &&
+    !queryExplicitlyMentionsCoordinates(query)
+  ) {
+    score = Math.max(0, score - 24)
+  }
+  if (queryTargetsKoroadHazardDataset(query)) {
+    if (entry.tool_id === 'koroad_accident_hazard_search') score += 32
+    if (entry.tool_id === 'koroad_accident_search') score = 0
+  }
+  return score
+}
+
+export function selectTopKAdapterToolNamesForQuery(
+  query: string,
+  maxResults = 5,
+): string[] {
+  const normalizedQuery = query.trim()
+  if (!normalizedQuery || maxResults <= 0) return []
+  const queryTokens = expandedQueryTokens(normalizedQuery)
+  const ranked = listAdapters()
+    .filter(entry => !ROOT_PRIMITIVE_TOOL_NAMES.has(entry.tool_id))
+    .map(entry => ({
+      entry,
+      score: scoreAdapterEntry(entry, queryTokens, normalizedQuery),
+    }))
+    .filter(candidate => candidate.score > 0)
+    .sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score
+      return a.entry.tool_id.localeCompare(b.entry.tool_id)
+    })
+
+  return pickDiverseAdapterToolNames(ranked, maxResults)
+}
+
+function pickDiverseAdapterToolNames(
+  ranked: ScoredAdapterEntry[],
+  maxResults: number,
+): string[] {
+  const selected: string[] = []
+  const seen = new Set<string>()
+  const add = (candidate: ScoredAdapterEntry): void => {
+    if (selected.length >= maxResults || seen.has(candidate.entry.tool_id)) return
+    selected.push(candidate.entry.tool_id)
+    seen.add(candidate.entry.tool_id)
+  }
+
+  const locateCandidates = ranked.filter(candidate => candidate.entry.primitive === 'locate')
+  const actionCandidates = ranked.filter(candidate => candidate.entry.primitive !== 'locate')
+
+  if (actionCandidates.length > 0) {
+    const locateBudget = Math.min(2, Math.max(1, maxResults - 1))
+    for (const candidate of locateCandidates.slice(0, locateBudget)) add(candidate)
+    for (const candidate of actionCandidates) add(candidate)
+  } else {
+    for (const candidate of ranked) add(candidate)
+  }
+
+  for (const candidate of ranked) add(candidate)
+  return selected
+}
+
 function buildAdapterTool(entry: AdapterManifestEntry): Tool {
   const primitive = primitiveFor(entry)
   const primitiveTool = primitiveToolFor(primitive)
@@ -231,10 +489,10 @@ function buildAdapterTool(entry: AdapterManifestEntry): Tool {
 
   return buildTool({
     name: entry.tool_id,
-    // K-EXAONE runs through FriendliAI's OpenAI-compatible function calling,
-    // not Anthropic tool_reference. Keep CC's Tool object shape, but make the
-    // concrete public-service adapter schemas visible on the first turn.
-    alwaysLoad: true,
+    // Keep concrete public-service adapters in CC's Tool object shape, but do
+    // not inline every synced adapter schema into the first LLM request. The
+    // ToolSearch path loads the few adapters relevant to the citizen request.
+    shouldDefer: true,
     searchHint: [entry.search_hint, entry.name, entry.tool_id, primitive]
       .filter(Boolean)
       .join(' '),

package/tui/src/tools/LookupPrimitive/prompt.ts

@@ -1,44 +1,33 @@
 // SPDX-License-Identifier: Apache-2.0
 // UMMAYA-original — Epic #1634 P3 · FindPrimitive prompt strings.
-// Spec 2521 (2026-05-01) — fetch-only surface; BM25 adapter discovery is a
-// backend-internal mechanism (auto-injected into the system prompt's
-// <available_adapters> dynamic suffix), not an LLM-callable mode. Older
-// "search/fetch two-mode" copy was the source of phantom tool-UI noise the
-// user surfaced via Layer 5 frame capture (specs/2521 frames/raw.cast).
+// 2026 migration note: root primitives are lightweight category descriptors
+// and legacy transcript compatibility wrappers. Concrete adapter functions are
+// loaded through CC ToolSearch/deferred schema expansion or backend top-K
+// retrieval, then called directly with adapter schema arguments.
 // Contract: specs/1634-tool-system-wiring/contracts/primitive-envelope.md § 2
 
 export const FIND_TOOL_NAME = 'find'
 
 /** Citizen-facing English description shown to the LLM (<= 240 chars). */
 export const DESCRIPTION =
-  'Invoke one concrete Korean public-service adapter. Use the function named find, but set tool_id to a listed adapter id from <available_adapters>, never to find/locate/check/send.'
+  'Discover Korean public-service lookup adapters. Prefer concrete adapter functions loaded by ToolSearch or backend retrieval; find is a legacy wrapper only.'
 
 /** Extended prompt included in the system-prompt tool-use section. */
-export const FIND_TOOL_PROMPT = `Invoke Korean public-service adapters registered in the UMMAYA tool registry.
+export const FIND_TOOL_PROMPT = `Discover Korean public-service lookup adapters registered in the UMMAYA tool registry.
 
-Single mode (Spec 2521 fetch-only):
+Preferred path:
+- Call concrete adapter functions directly after their schemas are loaded.
+- Example: kma_current_observation({ base_date: "YYYYMMDD", base_time: "HH00", nx: 97, ny: 74 })
+- Adapter schemas are progressively disclosed by ToolSearch or by backend top-K retrieval for the current citizen request.
+- Only top candidates should be loaded; do not expect every adapter schema in the prompt.
 
-  Input:  { tool_id: string, params: object }
-  Output: { tool_id: string, result: object }
-
-Adapter discovery
-─────────────────
-Adapter discovery is a BACKEND-INTERNAL function — NOT a callable mode.
-For every citizen turn the backend runs BM25 against the registry and
-injects the top-K candidates into the system prompt's
-<available_adapters> dynamic suffix. The LLM picks a tool_id from that
-block and calls find directly.
+Legacy root wrapper:
+- If a concrete adapter function is not loaded and only the root primitive is available, find accepts { tool_id, params } for old transcripts and compatibility paths.
+- tool_id must be a concrete adapter id from <available_adapters>, never "find", "locate", "check", or "send".
+- Invalid: find({ tool_id: "find", params: {...} })
+- Compatibility-only: find({ tool_id: "kma_current_observation", params: { base_date: "YYYYMMDD", base_time: "HH00", nx: 97, ny: 74 } })
 
 Rules:
-- The function name is find. The tool_id argument is NOT the function name.
-- tool_id must be a concrete adapter id listed in <available_adapters>, for example "kma_current_observation" or "kma_forecast_fetch".
-- Never set tool_id to a root primitive name: "find", "locate", "check", or "send".
-- Invalid: find({ tool_id: "find", params: {...} })
-- Valid:   find({ tool_id: "kma_current_observation", params: {...} })
-- Pick tool_id only from <available_adapters>. Never guess an id.
-- Do NOT call find with mode='search' / query — those payloads are
-  rejected with LookupErrorReason.invalid_params (Spec 2521).
-- Do NOT call the same tool_id twice in a single turn — answer with the
-  result you already have, or pick a different tool_id from the list.
-- params shape mirrors the adapter's Pydantic input_schema (see the
-  <available_adapters> hint for required keys).`
+- Do not call find with mode='search' or query; discovery is handled outside the primitive call.
+- Do not call the same adapter twice in a single turn unless a validation error requires corrected arguments.
+- Use the concrete adapter schema fields exactly; never invent required keys.`

package/tui/src/tools/ResolveLocationPrimitive/prompt.ts

@@ -5,21 +5,23 @@ export const LOCATE_TOOL_NAME = 'locate'
 
 /** Citizen-facing English description shown to the LLM. */
 export const DESCRIPTION =
-  'Invoke one concrete Korean location adapter. Use the function named locate, but set tool_id to a listed locate adapter id from <available_adapters>, never to locate/find/check/send.'
+  'Discover Korean location adapters. Prefer concrete location adapter functions loaded by ToolSearch or backend retrieval; locate is a legacy wrapper only.'
 
 /** Extended prompt included in the system-prompt tool-use section. */
-export const LOCATE_TOOL_PROMPT = `Resolve a Korean location phrase into structured location identifiers.
+export const LOCATE_TOOL_PROMPT = `Resolve Korean location phrases with concrete location adapters.
 
-Input:
-  { tool_id: string, params: object }
+Preferred path:
+- Call concrete adapter functions directly after their schemas are loaded.
+- Examples: kakao_keyword_search({ query: "부산 사하구 다대1동" }) or kakao_coord_to_region({ lat: 35.115446, lon: 128.967669 })
+- Adapter schemas are progressively disclosed by ToolSearch or by backend top-K retrieval for the current citizen request.
 
-Rules:
-- The function name is locate. The tool_id argument is NOT the function name.
-- tool_id must be a concrete locate adapter id listed in <available_adapters>, for example "kakao_address_search" or "kakao_coord_to_region".
-- Never set tool_id to a root primitive name: "locate", "find", "check", or "send".
+Legacy root wrapper:
+- If a concrete adapter function is not loaded and only the root primitive is available, locate accepts { tool_id, params } for old transcripts and compatibility paths.
+- tool_id must be a concrete locate adapter id from <available_adapters>, never "locate", "find", "check", or "send".
 - Invalid: locate({ tool_id: "locate", params: {...} })
-- Valid:   locate({ tool_id: "kakao_address_search", params: { query: "부산 사하구 다대1동" } })
-- Pick tool_id only from <available_adapters> entries whose primitive is locate.
+- Compatibility-only: locate({ tool_id: "kakao_address_search", params: { query: "부산 사하구 다대1동" } })
+
+Rules:
 - Use kakao_keyword_search for named places, campuses, stations, landmarks, hospitals, and POIs.
 - Coordinate-producing locate results may include KMA nx/ny; pass those exact values to KMA weather adapters that require nx and ny.
 - Use kakao_address_search or juso_adm_cd_lookup for structured road/jibun addresses and district text.

package/tui/src/tools/SubmitPrimitive/prompt.ts

@@ -6,14 +6,19 @@ export const SEND_TOOL_NAME = 'send'
 
 /** One-line English description (<= 240 chars). */
 export const DESCRIPTION =
-  'Send a citizen action such as an application, report, or submission to a public-service adapter. This can have side effects; choose an adapter from <available_adapters>.'
+  'Discover side-effecting public-service send adapters. Prefer concrete adapter functions loaded by retrieval; send is a permission-gated legacy wrapper.'
 
 /** Extended prompt included in the system-prompt tool-use section. */
-export const SEND_TOOL_PROMPT = `Send a side-effecting citizen action to a registered UMMAYA adapter.
+export const SEND_TOOL_PROMPT = `Send a side-effecting citizen action through a concrete UMMAYA adapter.
 
-Input: { tool_id: string, params: object }
-  - tool_id: the adapter identifier from <available_adapters>
-  - params: adapter-defined Pydantic-validated parameter body
+Preferred path:
+- Call concrete adapter functions directly after their schemas are loaded.
+- Adapter schemas are progressively disclosed by ToolSearch or backend top-K retrieval for the current citizen request.
+- Use the adapter's exact schema fields and cite the resulting receipt in the citizen-facing answer.
+
+Legacy root wrapper:
+- If a concrete adapter function is not loaded and only the root primitive is available, send accepts { tool_id, params } for old transcripts and compatibility paths.
+- tool_id must be a registered send adapter id, not "send", "find", "locate", or "check".
 
 Output: { transaction_id: string, status: string, adapter_receipt: object }
   - transaction_id: deterministically derived identifier for idempotency reasoning
@@ -21,7 +26,6 @@ Output: { transaction_id: string, status: string, adapter_receipt: object }
   - adapter_receipt: adapter-specific confirmation payload
 
 Rules:
-- Pick the send adapter from <available_adapters>; BM25 discovery is backend-internal.
 - send is IRREVERSIBLE — confirm intent clearly before calling.
 - The permission gauntlet (Layer 2 orange ⓶) executes before adapter dispatch.
 - Use transaction_id to reason about idempotency (same input → same ID).

package/tui/src/tools/VerifyPrimitive/prompt.ts

@@ -7,14 +7,19 @@ export const CHECK_TOOL_NAME = 'check'
 
 /** One-line citizen-facing English description shown to the LLM (<= 240 chars). */
 export const DESCRIPTION =
-  'Delegate credential verification to an auth adapter. Use tool_id for registered methods such as certificates, simple auth, or mobile ID; UMMAYA never mints or stores credentials.'
+  'Discover credential-check adapters. Prefer concrete adapter functions loaded by retrieval; check never mints or stores credentials.'
 
 /** Extended prompt included in the system-prompt tool-use section. */
-export const CHECK_TOOL_PROMPT = `Delegate credential checking to a registered UMMAYA auth adapter.
+export const CHECK_TOOL_PROMPT = `Delegate credential checking to a concrete UMMAYA auth adapter.
 
-Input: { tool_id: string, params: object }
-  - tool_id: the auth adapter identifier (e.g. "gongdong_injeungseo", "mobile_id")
-  - params: adapter-defined credential parameter body
+Preferred path:
+- Call concrete adapter functions directly after their schemas are loaded.
+- Adapter schemas are progressively disclosed by ToolSearch or backend top-K retrieval for the current citizen request.
+- Use the adapter's exact schema fields for scope, purpose, and session-bound evidence.
+
+Legacy root wrapper:
+- If a concrete adapter function is not loaded and only the root primitive is available, check accepts { tool_id, params } for old transcripts and compatibility paths.
+- tool_id must be a registered check adapter id, not "check", "find", "locate", or "send".
 
 Output (discriminated by auth_family):
   - auth_family: "gongdong_injeungseo" | "geumyung_injeungseo" | "ganpyeon_injeung" | "digital_onepass" | "mobile_id" | "mydata"

package/uv.lock

@@ -2725,7 +2725,7 @@ wheels = [
 
 [[package]]
 name = "ummaya"
-version = "0.2.1"
+version = "0.2.3"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },