ummaya 0.2.1 → 0.2.3

package/bin/ummaya

@@ -7,9 +7,27 @@ import { delimiter, dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const MINIMUM_BUN_VERSION = '1.3.0'
-const launcherPath = realpathSync(fileURLToPath(import.meta.url))
+const PACKAGED_PRIMITIVE_TIMEOUT_MS = '90000'
 
-function bunVersionAtLeast(version, minimum) {
+function currentLauncherPath() {
+  return realpathSync(fileURLToPath(import.meta.url))
+}
+
+function invokedLauncherPath() {
+  const argvPath = process.argv[1]
+  if (!argvPath) return null
+  try {
+    return realpathSync(argvPath)
+  } catch {
+    return null
+  }
+}
+
+function isDirectLaunch() {
+  return invokedLauncherPath() === currentLauncherPath()
+}
+
+export function bunVersionAtLeast(version, minimum) {
   const current = String(version)
     .split('.')
     .map((part) => Number.parseInt(part, 10))
@@ -62,7 +80,7 @@ function probeBunVersion(candidate) {
   return (result.stdout || result.stderr).trim()
 }
 
-function launchWithCompatibleBun(currentVersion = null) {
+function launchWithCompatibleBun(launcherPath, currentVersion = null) {
   const checked = []
   for (const candidate of collectBunCandidates()) {
     const version = probeBunVersion(candidate)
@@ -94,17 +112,7 @@ function launchWithCompatibleBun(currentVersion = null) {
   process.exit(1)
 }
 
-const runningBun = globalThis.Bun
-if (!runningBun) {
-  launchWithCompatibleBun()
-}
-if (!bunVersionAtLeast(runningBun.version, MINIMUM_BUN_VERSION)) {
-  launchWithCompatibleBun(runningBun.version)
-}
-
-const packageRoot = dirname(dirname(launcherPath))
-
-function loadPackageDotenv(root) {
+export function loadPackageDotenv(root, env = process.env) {
   const envPath = join(root, '.env')
   if (!existsSync(envPath)) return
   const lines = readFileSync(envPath, 'utf8').split(/\r?\n/)
@@ -114,29 +122,66 @@ function loadPackageDotenv(root) {
     const index = line.indexOf('=')
     const key = line.slice(0, index).trim()
     let value = line.slice(index + 1).trim()
-    if (!key || process.env[key] !== undefined) continue
+    if (!key || env[key] !== undefined) continue
     if (
       (value.startsWith('"') && value.endsWith('"')) ||
       (value.startsWith("'") && value.endsWith("'"))
     ) {
       value = value.slice(1, -1)
     }
-    process.env[key] = value
+    env[key] = value
+  }
+}
+
+export function buildBackendCommand(root) {
+  const packagedPython = join(root, '.venv', 'bin', 'python')
+  if (existsSync(packagedPython)) {
+    return [packagedPython, '-m', 'ummaya.cli', '--ipc', 'stdio']
   }
+
+  return ['uv', '--directory', root, 'run', '--frozen', '--no-dev', 'ummaya', '--ipc', 'stdio']
+}
+
+export function configurePackageEnv(root, env = process.env) {
+  env.UMMAYA_PACKAGE_ROOT = root
+  if (env.UMMAYA_ALLOW_BACKEND_CMD_OVERRIDE !== '1' || !env.UMMAYA_BACKEND_CMD_JSON) {
+    env.UMMAYA_BACKEND_CMD_JSON = JSON.stringify(buildBackendCommand(root))
+  }
+  env.UMMAYA_TUI_PRIMITIVE_TIMEOUT_MS ??= PACKAGED_PRIMITIVE_TIMEOUT_MS
+  return env
+}
+
+function inspectLauncherAndExit() {
+  if (process.env.UMMAYA_LAUNCHER_INSPECT !== '1') return
+  process.stdout.write(
+    `${JSON.stringify({
+      packageRoot: process.env.UMMAYA_PACKAGE_ROOT,
+      backendCommand: JSON.parse(process.env.UMMAYA_BACKEND_CMD_JSON ?? '[]'),
+      primitiveTimeoutMs: process.env.UMMAYA_TUI_PRIMITIVE_TIMEOUT_MS,
+    })}\n`,
+  )
+  process.exit(0)
 }
 
-loadPackageDotenv(packageRoot)
-
-process.env.UMMAYA_PACKAGE_ROOT ??= packageRoot
-process.env.UMMAYA_BACKEND_CMD_JSON ??= JSON.stringify([
-  'uv',
-  '--directory',
-  packageRoot,
-  'run',
-  'ummaya',
-  '--ipc',
-  'stdio',
-])
-
-await import(join(packageRoot, 'tui/src/stubs/macro-preload.ts'))
-await import(join(packageRoot, 'tui/src/entrypoints/cli.tsx'))
+export async function main() {
+  const launcherPath = currentLauncherPath()
+  const runningBun = globalThis.Bun
+  if (!runningBun) {
+    launchWithCompatibleBun(launcherPath)
+  }
+  if (!bunVersionAtLeast(runningBun.version, MINIMUM_BUN_VERSION)) {
+    launchWithCompatibleBun(launcherPath, runningBun.version)
+  }
+
+  const packageRoot = dirname(dirname(launcherPath))
+  loadPackageDotenv(packageRoot)
+  configurePackageEnv(packageRoot)
+  inspectLauncherAndExit()
+
+  await import(join(packageRoot, 'tui/src/stubs/macro-preload.ts'))
+  await import(join(packageRoot, 'tui/src/entrypoints/cli.tsx'))
+}
+
+if (isDirectLaunch()) {
+  await main()
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "ummaya",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "ummaya",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "license": "Apache-2.0",
       "dependencies": {
         "@alcalzone/ansi-tokenize": "^0.3.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ummaya",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Conversational multi-agent harness for Korean public-service channels",
   "license": "Apache-2.0",
   "type": "module",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ummaya"
-version = "0.2.1"
+version = "0.2.3"
 description = "Conversational multi-agent platform for Korean public APIs"
 readme = "README.md"
 license = "Apache-2.0"
@@ -314,7 +314,7 @@ min_confidence = 80
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.2.1"
+version = "0.2.3"
 tag_format = "v$version"
 
 # PyTorch CPU-only wheel for Docker image size discipline (SC-1: ≤ 2 GB).

package/src/ummaya/engine/engine.py

@@ -75,17 +75,6 @@ def _contains_location_dependent_key(value: object) -> bool:
     return False
 
 
-def _allowed_core_tools_for_available_adapters(
-    visible_primitives: set[str],
-    has_location_dependent_schema: bool,
-) -> frozenset[str] | None:
-    """Constrain root primitive exposure for location-independent find turns."""
-
-    if visible_primitives == {"find"} and not has_location_dependent_schema:
-        return frozenset({"find"})
-    return None
-
-
 class QueryEngine:
     """Per-session orchestrator for the UMMAYA query engine.
 
@@ -216,7 +205,7 @@ class QueryEngine:
                 ChatMessage(role="user", content=assembled.turn_attachment.content),
             )
 
-        dynamic_adapter_message, allowed_core_tool_ids = self._build_available_adapters_context(
+        dynamic_adapter_message, turn_tool_ids = self._build_available_adapters_context(
             user_message
         )
         if dynamic_adapter_message is not None:
@@ -235,7 +224,7 @@ class QueryEngine:
             tool_registry=self._tool_registry,
             config=self._config,
             session_context=self._permission_session,
-            allowed_core_tool_ids=allowed_core_tool_ids,
+            turn_tool_ids=turn_tool_ids,
             turn_start_message_index=turn_start_message_index,
         )
 
@@ -281,13 +270,13 @@ class QueryEngine:
     def _build_available_adapters_message(self, user_message: str) -> ChatMessage | None:
         """Inject BM25 adapter candidates for the current citizen utterance."""
 
-        message, _allowed_core_tool_ids = self._build_available_adapters_context(user_message)
+        message, _turn_tool_ids = self._build_available_adapters_context(user_message)
         return message
 
     def _build_available_adapters_context(
         self, user_message: str
-    ) -> tuple[ChatMessage | None, frozenset[str] | None]:
-        """Build dynamic adapter context and per-turn primitive exposure."""
+    ) -> tuple[ChatMessage | None, tuple[str, ...]]:
+        """Build dynamic adapter context and per-turn concrete tool exposure."""
 
         try:
             from ummaya.tools.search import search  # noqa: PLC0415
@@ -300,11 +289,10 @@ class QueryEngine:
             )
         except Exception:  # noqa: BLE001
             logger.exception("available_adapters auto-inject failed")
-            return None, None
+            return None, ()
 
         adapter_lines: list[str] = []
-        visible_primitives: set[str] = set()
-        has_location_dependent_schema = False
+        selected_tool_ids: list[str] = []
         primary_find_without_location = False
         visible_count = 0
         for candidate in candidates:
@@ -312,6 +300,8 @@ class QueryEngine:
                 tool = self._tool_registry.find(candidate.tool_id)
             except ToolNotFoundError:
                 continue
+            if candidate.score <= 0:
+                continue
             if tool.is_core or tool.ministry == "UMMAYA":
                 continue
             primitive = candidate.primitive if isinstance(candidate.primitive, str) else None
@@ -324,15 +314,12 @@ class QueryEngine:
             )
             if visible_count > 0 and primary_find_without_location and requires_location:
                 continue
-            if primitive is not None:
-                visible_primitives.add(primitive)
-            if requires_location:
-                has_location_dependent_schema = True
             schema_json = json.dumps(
                 candidate.input_schema_json,
                 ensure_ascii=False,
                 sort_keys=True,
             )
+            selected_tool_ids.append(candidate.tool_id)
             adapter_lines.extend(
                 [
                     f"- tool_id: {candidate.tool_id}",
@@ -340,8 +327,7 @@ class QueryEngine:
                     f"  description: {candidate.llm_description or tool.name_ko}",
                     f"  required_params: {candidate.required_params}",
                     f"  input_schema_json: {schema_json}",
-                    f"  call_hint: {candidate.primitive}("
-                    f'{{"tool_id":"{candidate.tool_id}","params":{{...}}}})',
+                    f"  call_hint: {candidate.tool_id}({{...}})",
                     f"  policy_url: {candidate.real_classification_url or ''}",
                 ]
             )
@@ -350,19 +336,16 @@ class QueryEngine:
                 break
 
         if not adapter_lines:
-            return None, None
-
-        allowed_core_tool_ids = _allowed_core_tools_for_available_adapters(
-            visible_primitives,
-            has_location_dependent_schema,
-        )
+            return None, ()
 
         content = "\n".join(
             [
                 "<available_adapters>",
                 "Use these adapter candidates for this citizen request. "
-                "For public-data lookup/list/statistics requests, call "
-                "find({tool_id, params}) with a tool_id from this block. "
+                "Call the function named exactly as tool_id with that adapter's "
+                "schema arguments. Do not wrap adapter calls in root primitives "
+                "such as find({tool_id, params}), locate({tool_id, params}), "
+                "check({tool_id, params}), or send({tool_id, params}). "
                 "Do not call locate just because the citizen text contains a "
                 "city/province name; treat that as the dataset/filter term. "
                 "Call locate only when the selected adapter schema requires "
@@ -371,7 +354,7 @@ class QueryEngine:
                 "</available_adapters>",
             ]
         )
-        return ChatMessage(role="system", content=content), allowed_core_tool_ids
+        return ChatMessage(role="system", content=content), tuple(selected_tool_ids)
 
     def set_permission_session(self, session: SessionContext | None) -> None:
         """Update the permission-pipeline session used for subsequent turns.

package/src/ummaya/engine/models.py

@@ -121,11 +121,17 @@ class QueryContext(BaseModel):
     """
 
     allowed_core_tool_ids: frozenset[str] | None = None
-    """Optional per-turn provider tool allow-list for root primitives.
+    """Legacy per-turn allow-list for primitive wrappers.
 
-    Used by the Rich REPL path when BM25 has already selected location-independent
-    public-data adapters. It keeps the exposed provider surface aligned with the
-    selected adapter primitive instead of letting unrelated root primitives race.
+    Preserved for callers that still expose the old root primitives. New turns
+    should prefer ``turn_tool_ids`` so the model sees concrete adapter schemas.
+    """
+
+    turn_tool_ids: tuple[str, ...] = ()
+    """Concrete adapter tool IDs selected for this citizen turn.
+
+    When populated, the query loop exports these concrete adapter schemas as the
+    provider tool surface instead of dumping the root primitive wrappers.
     """
 
     turn_start_message_index: int = 0

package/src/ummaya/engine/query.py

@@ -82,7 +82,7 @@ def _assemble_tool_calls(
 
 
 def _tool_definition_name(tool_def: ToolDefinition | dict[str, object]) -> str | None:
-    """Extract a root primitive name from an OpenAI tool definition."""
+    """Extract a function name from an OpenAI tool definition."""
 
     if isinstance(tool_def, ToolDefinition):
         return tool_def.function.name
@@ -93,6 +93,27 @@ def _tool_definition_name(tool_def: ToolDefinition | dict[str, object]) -> str |
     return name if isinstance(name, str) else None
 
 
+def _export_turn_tool_definitions(
+    tool_registry: ToolRegistry,
+    tool_ids: tuple[str, ...],
+) -> list[dict[str, object]]:
+    """Export selected concrete adapter schemas in ranking order."""
+
+    tool_defs: list[dict[str, object]] = []
+    seen: set[str] = set()
+    for tool_id in tool_ids:
+        if tool_id in seen:
+            continue
+        seen.add(tool_id)
+        try:
+            tool = tool_registry.find(tool_id)
+        except ToolNotFoundError:
+            logger.warning("Selected turn tool disappeared from registry: %s", tool_id)
+            continue
+        tool_defs.append(tool.to_openai_tool())
+    return tool_defs
+
+
 def _latest_successful_tool_payload(messages: list[ChatMessage]) -> dict[str, object] | None:
     """Return the latest non-error tool-result JSON payload, if present."""
 
@@ -296,14 +317,38 @@ async def dispatch_tool_calls(  # noqa: C901
 
     async def _dispatch_one(tc: ToolCall) -> ToolResult:
         """Dispatch a single tool call via the executor."""
-        if tc.function.name in {"find", "locate"}:
+        if tc.function.name in {"find", "locate", "check", "send"}:
             return await _dispatch_root_primitive(
                 tc,
                 tool_registry,
                 tool_executor,
                 session_context=session_context,
             )
-        return await tool_executor.dispatch(tc.function.name, tc.function.arguments)
+        try:
+            tool = tool_registry.find(tc.function.name)
+        except ToolNotFoundError:
+            return await tool_executor.dispatch(tc.function.name, tc.function.arguments)
+        gate = tool.policy.citizen_facing_gate if tool.policy is not None else None
+        if gate in {None, "read-only"}:
+            return await tool_executor.dispatch(
+                tc.function.name,
+                tc.function.arguments,
+                tool_call_id=tc.id,
+            )
+        primitive = tool.primitive
+        if primitive is None:
+            return ToolResult(
+                tool_id=tc.function.name,
+                success=False,
+                error=f"{tc.function.name} is missing primitive metadata for gated dispatch.",
+                error_type="schema_mismatch",
+            )
+        return await _dispatch_concrete_adapter(
+            tc,
+            primitive,
+            tool_executor,
+            session_context=session_context,
+        )
 
     async def _flush_group(items: list[tuple[int, ToolCall]], safe: bool) -> None:
         """Execute a group of tool calls, concurrently if safe."""
@@ -407,6 +452,59 @@ async def _dispatch_root_primitive(
     return ToolResult(tool_id=primitive, success=True, data=data)
 
 
+async def _dispatch_concrete_adapter(
+    tc: ToolCall,
+    primitive: str,
+    tool_executor: ToolExecutor,
+    *,
+    session_context: SessionContext | None,
+) -> ToolResult:
+    """Dispatch a directly model-facing concrete adapter call."""
+
+    try:
+        raw_args = json.loads(tc.function.arguments)
+    except (TypeError, json.JSONDecodeError) as exc:
+        return ToolResult(
+            tool_id=tc.function.name,
+            success=False,
+            error=str(exc),
+            error_type="validation",
+        )
+    if not isinstance(raw_args, dict):
+        return ToolResult(
+            tool_id=tc.function.name,
+            success=False,
+            error=f"{tc.function.name} requires a JSON object argument.",
+            error_type="validation",
+        )
+
+    request_id = tc.id or f"{tc.function.name}-call"
+    if primitive == "find":
+        output = await tool_executor.invoke(
+            tc.function.name,
+            raw_args,
+            request_id=request_id,
+            session_identity=session_context,
+        )
+    else:
+        output = await tool_executor.invoke_raw(
+            tc.function.name,
+            raw_args,
+            request_id=request_id,
+            session_identity=session_context,
+        )
+
+    data = _primitive_output_dict(output)
+    if data.get("kind") == "error":
+        return ToolResult(
+            tool_id=tc.function.name,
+            success=False,
+            error=str(data.get("message") or data),
+            error_type="execution",
+        )
+    return ToolResult(tool_id=tc.function.name, success=True, data=data)
+
+
 def _primitive_output_dict(output: object) -> dict[str, object]:
     """Convert primitive facade output to ToolResult data."""
 
@@ -532,8 +630,13 @@ async def _query_inner(ctx: QueryContext) -> AsyncIterator[QueryEvent]:  # noqa:
             tool_defs: list[ToolDefinition | dict[str, object]] | None = None
             force_no_tools_next_turn = False
         else:
-            raw_defs = ctx.tool_registry.export_core_tools_openai()
-            if ctx.allowed_core_tool_ids is not None:
+            raw_defs = _export_turn_tool_definitions(
+                ctx.tool_registry,
+                ctx.turn_tool_ids,
+            )
+            if not raw_defs:
+                raw_defs = ctx.tool_registry.export_core_tools_openai()
+            if ctx.allowed_core_tool_ids is not None and not ctx.turn_tool_ids:
                 raw_defs = [
                     tool_def
                     for tool_def in raw_defs