ummaya 0.2.2 → 0.2.4

package/src/ummaya/llm/client.py

@@ -10,7 +10,7 @@ import logging
 import os
 import random
 import time
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Iterator
 from contextvars import Token
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, cast
@@ -39,6 +39,7 @@ from ummaya.llm.models import (
     ToolCall,
     ToolDefinition,
 )
+from ummaya.llm.reasoning import ReasoningMode, resolve_reasoning_policy
 from ummaya.llm.usage import UsageTracker
 from ummaya.observability.semconv import (
     ERROR_TYPE,
@@ -238,6 +239,7 @@ class LLMClient:
         presence_penalty: float = 0.0,
         max_tokens: int = 1024,
         stop: list[str] | None = None,
+        reasoning_mode: ReasoningMode | str | None = None,
     ) -> ChatCompletionResponse:
         """Send a non-streaming chat completion request.
 
@@ -271,6 +273,7 @@ class LLMClient:
             tools=tools,
             tool_choice=tool_choice,
             stream=False,
+            reasoning_mode=reasoning_mode,
         )
 
         logger.debug(
@@ -365,6 +368,7 @@ class LLMClient:
         presence_penalty: float = 0.0,
         max_tokens: int = 1024,
         stop: list[str] | None = None,
+        reasoning_mode: ReasoningMode | str | None = None,
     ) -> AsyncIterator[StreamEvent]:
         """Send a streaming chat completion request.
 
@@ -403,7 +407,9 @@ class LLMClient:
             tools=tools,
             tool_choice=tool_choice,
             stream=True,
+            reasoning_mode=reasoning_mode,
         )
+        allow_reasoning = payload.get("include_reasoning") is True
 
         logger.debug(
             "LLM stream request: model=%s messages=%d",
@@ -447,7 +453,11 @@ class LLMClient:
         _finalize: dict[str, object] = {}
 
         try:
-            async for event in self._stream_with_retry(payload, _finalize):
+            async for event in self._stream_with_retry(
+                payload,
+                _finalize,
+                allow_reasoning=allow_reasoning,
+            ):
                 active_span.detach()
                 yield event
                 active_span.attach()
@@ -490,6 +500,8 @@ class LLMClient:
         self,
         payload: dict[str, object],
         _finalize: dict[str, object],
+        *,
+        allow_reasoning: bool,
     ) -> AsyncIterator[StreamEvent]:
         """Execute stream() with Retry-After-first backoff loop (T015/T016).
 
@@ -607,7 +619,10 @@ class LLMClient:
                             if chunk_info.get("model"):
                                 _response_model = chunk_info["model"]
 
-                            async for event in self._parse_sse_line(line):
+                            async for event in self._parse_sse_line(
+                                line,
+                                allow_reasoning=allow_reasoning,
+                            ):
                                 yield event
                                 if event.type == "done":
                                     _duration_ms = (time.monotonic() - _stream_start) * 1000
@@ -848,7 +863,12 @@ class LLMClient:
             if i + step < n:
                 await asyncio.sleep(_LLM_STREAM_PACE_S)
 
-    async def _parse_sse_line(self, line: str) -> AsyncIterator[StreamEvent]:  # noqa: C901
+    async def _parse_sse_line(
+        self,
+        line: str,
+        *,
+        allow_reasoning: bool = False,
+    ) -> AsyncIterator[StreamEvent]:
         """Parse a single SSE line and yield corresponding StreamEvent(s)."""
         if not line or not line.startswith("data: "):
             return
@@ -859,14 +879,35 @@ class LLMClient:
             yield StreamEvent(type="done")
             return
 
+        chunk = self._decode_sse_payload(payload_text)
+        if chunk is None:
+            return
+
+        usage_event = self._usage_event_from_chunk(chunk)
+        if usage_event is not None:
+            yield usage_event
+
+        async for event in self._events_from_sse_choices(
+            chunk,
+            allow_reasoning=allow_reasoning,
+        ):
+            yield event
+
+    def _decode_sse_payload(self, payload_text: str) -> dict[str, object] | None:
+        """Decode a JSON SSE payload, returning None for malformed chunks."""
         try:
             chunk = json.loads(payload_text)
         except json.JSONDecodeError:
             logger.warning("Failed to parse SSE chunk: %r", payload_text)
-            return
+            return None
+        return chunk if isinstance(chunk, dict) else None
 
+    def _usage_event_from_chunk(self, chunk: dict[str, object]) -> StreamEvent | None:
+        """Debit usage from a stream chunk and return the corresponding event."""
         if "usage" in chunk and chunk["usage"] is not None:
             raw_usage = chunk["usage"]
+            if not isinstance(raw_usage, dict):
+                return None
             usage = TokenUsage(
                 input_tokens=raw_usage.get("prompt_tokens", 0),
                 output_tokens=raw_usage.get("completion_tokens", 0),
@@ -877,66 +918,104 @@ class LLMClient:
                 usage.output_tokens,
             )
             self._usage.debit(usage)
-            yield StreamEvent(type="usage", usage=usage)
+            return StreamEvent(type="usage", usage=usage)
+        return None
 
+    async def _events_from_sse_choices(
+        self,
+        chunk: dict[str, object],
+        *,
+        allow_reasoning: bool,
+    ) -> AsyncIterator[StreamEvent]:
+        """Yield stream events for the first OpenAI-compatible choice delta."""
         choices = chunk.get("choices")
         if not choices:
             return
+        if not isinstance(choices, list):
+            return
 
         choice = choices[0]
+        if not isinstance(choice, dict):
+            return
         delta = choice.get("delta", {})
+        if not isinstance(delta, dict):
+            return
 
+        async for event in self._events_from_sse_delta(
+            delta,
+            allow_reasoning=allow_reasoning,
+        ):
+            yield event
+
+    async def _events_from_sse_delta(
+        self,
+        delta: dict[str, object],
+        *,
+        allow_reasoning: bool,
+    ) -> AsyncIterator[StreamEvent]:
+        """Yield content, reasoning, and tool-call events from a delta object."""
         if "content" in delta and delta["content"] is not None:
             # CC reference: services/api/claude.ts:2113 (text_delta content_block_delta).
-            content = delta["content"]
+            content = str(delta["content"])
             async for sub in self._pace_text_chunk(content, "content"):
                 yield sub
         elif "reasoning_content" in delta and delta["reasoning_content"] is not None:
-            # CC reference: services/api/claude.ts:2148-2161 (thinking_delta
-            # content_block_delta) — K-EXAONE emits chain-of-thought on a
-            # separate ``delta.reasoning_content`` channel. Forwarding the
-            # same StreamEvent shape on UMMAYA lets the TUI's
-            # ``AssistantThinkingMessage`` component render the reasoning
-            # inline instead of swallowing it. Log only the chunk length —
-            # never the raw content (CoT may contain user PII or sensitive
-            # reasoning about user input).
-            reasoning_text = delta["reasoning_content"]
+            async for sub in self._events_from_reasoning_delta(
+                str(delta["reasoning_content"]),
+                allow_reasoning=allow_reasoning,
+            ):
+                yield sub
+
+        if "tool_calls" in delta and delta["tool_calls"]:
+            for event in self._events_from_tool_call_deltas(delta["tool_calls"]):
+                yield event
+
+    async def _events_from_reasoning_delta(
+        self,
+        reasoning_text: str,
+        *,
+        allow_reasoning: bool,
+    ) -> AsyncIterator[StreamEvent]:
+        """Yield reasoning text only when the request opted into reasoning parsing."""
+        if not allow_reasoning:
             logger.debug(
-                "Forwarding reasoning_content as thinking_delta (len=%d)",
+                "Suppressed unexpected reasoning_content while include_reasoning=false (len=%d)",
                 len(reasoning_text),
             )
-            async for sub in self._pace_text_chunk(reasoning_text, "thinking"):
-                yield sub
+            return
+        logger.debug(
+            "Forwarding reasoning_content as thinking_delta (len=%d)",
+            len(reasoning_text),
+        )
+        async for sub in self._pace_text_chunk(reasoning_text, "thinking"):
+            yield sub
 
-        if "tool_calls" in delta and delta["tool_calls"]:
-            # CC reference: services/api/claude.ts:1997 (tool_use content_block_start)
-            # + services/api/claude.ts:2087 (input_json_delta content_block_delta).
-            # FriendliAI's OpenAI-compatible streaming buffers tool_call argument
-            # JSON across multiple deltas (matching OpenAI's incremental parser).
-            # UMMAYA mirrors CC's pattern by emitting one StreamEvent per delta;
-            # the IPC bridge (stdio.py) accumulates them into the final
-            # ToolCallFrame.
-            for tc_delta in delta["tool_calls"]:
-                func = tc_delta.get("function", {})
-                # Log only tool metadata (index/id/name + arg length).
-                # Raw `arguments` often carries user-provided location strings
-                # or other PII — never log them.
-                _args_field = func.get("arguments")
-                _args_len = len(_args_field) if isinstance(_args_field, str) else 0
-                logger.debug(
-                    "tool_call_delta idx=%s id=%s name=%r args_len=%d",
-                    tc_delta.get("index"),
-                    tc_delta.get("id"),
-                    func.get("name"),
-                    _args_len,
-                )
-                yield StreamEvent(
-                    type="tool_call_delta",
-                    tool_call_index=tc_delta.get("index"),
-                    tool_call_id=tc_delta.get("id"),
-                    function_name=func.get("name"),
-                    function_args_delta=func.get("arguments"),
-                )
+    def _events_from_tool_call_deltas(self, tool_calls: object) -> Iterator[StreamEvent]:
+        """Yield tool-call deltas without logging raw argument content."""
+        if not isinstance(tool_calls, list):
+            return
+        for tc_delta in tool_calls:
+            if not isinstance(tc_delta, dict):
+                continue
+            func = tc_delta.get("function", {})
+            if not isinstance(func, dict):
+                func = {}
+            _args_field = func.get("arguments")
+            _args_len = len(_args_field) if isinstance(_args_field, str) else 0
+            logger.debug(
+                "tool_call_delta idx=%s id=%s name=%r args_len=%d",
+                tc_delta.get("index"),
+                tc_delta.get("id"),
+                func.get("name"),
+                _args_len,
+            )
+            yield StreamEvent(
+                type="tool_call_delta",
+                tool_call_index=tc_delta.get("index"),
+                tool_call_id=tc_delta.get("id"),
+                function_name=func.get("name"),
+                function_args_delta=func.get("arguments"),
+            )
 
     def _build_payload(
         self,
@@ -950,6 +1029,7 @@ class LLMClient:
         tools: list[ToolDefinition | dict[str, object]] | None = None,
         tool_choice: str | dict[str, object] | None = None,
         stream: bool,
+        reasoning_mode: ReasoningMode | str | None = None,
     ) -> dict[str, object]:
         """Construct the JSON payload for a chat completions request.
 
@@ -979,13 +1059,7 @@ class LLMClient:
         is not treated as normal assistant text and is never required for the
         default CLI/TUI path.
         """
-        import os  # noqa: PLC0415 — local import keeps top-level imports thin
-
-        enable_thinking = os.environ.get("UMMAYA_K_EXAONE_THINKING", "false").lower() in (
-            "true",
-            "1",
-            "yes",
-        )
+        reasoning = resolve_reasoning_policy(reasoning_mode)
 
         payload: dict[str, object] = {
             "model": self._config.model,
@@ -999,7 +1073,9 @@ class LLMClient:
             # enable_thinking=False the model emits an answer directly
             # without the <think>...</think> trace, dropping first-token
             # latency from ~60-180s to <10s for typical citizen prompts.
-            "chat_template_kwargs": {"enable_thinking": enable_thinking},
+            "chat_template_kwargs": {"enable_thinking": reasoning.enable_thinking},
+            "parse_reasoning": reasoning.parse_reasoning,
+            "include_reasoning": reasoning.include_reasoning,
         }
         if stop is not None:
             payload["stop"] = stop

package/src/ummaya/llm/reasoning.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: Apache-2.0
+"""K-EXAONE/FriendliAI reasoning payload policy."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+ReasoningMode = Literal["fast", "balanced", "deep", "diagnostic", "auto"]
+ReasoningModeSource = Literal["env", "session", "legacy-env", "default"]
+
+_MODES: set[str] = {"fast", "balanced", "deep", "diagnostic", "auto"}
+
+
+@dataclass(frozen=True)
+class ResolvedReasoningPolicy:
+    """Provider-facing reasoning policy for one request."""
+
+    mode: ReasoningMode
+    source: ReasoningModeSource
+    enable_thinking: bool
+    parse_reasoning: bool
+    include_reasoning: bool
+    persist_thinking: bool = False
+
+
+def parse_reasoning_mode(value: object) -> ReasoningMode | None:
+    """Return a valid reasoning mode from an untrusted value."""
+    if value is None:
+        return None
+    normalized = str(value).lower()
+    if normalized in _MODES:
+        return normalized  # type: ignore[return-value]
+    return None
+
+
+def resolve_reasoning_policy(
+    reasoning_mode: ReasoningMode | str | None = None,
+    *,
+    env: Mapping[str, str] | None = None,
+) -> ResolvedReasoningPolicy:
+    """Resolve request, settings, and env state into FriendliAI payload fields."""
+    effective_env = os.environ if env is None else env
+    env_mode = parse_reasoning_mode(effective_env.get("UMMAYA_K_EXAONE_REASONING_MODE"))
+    if env_mode is not None:
+        return _policy_for(env_mode, "env")
+
+    explicit_mode = parse_reasoning_mode(reasoning_mode)
+    if explicit_mode is not None:
+        return _policy_for(explicit_mode, "session")
+
+    legacy_mode = _legacy_thinking_mode(effective_env)
+    if legacy_mode is not None:
+        return _policy_for(legacy_mode, "legacy-env")
+
+    return _policy_for("balanced", "default")
+
+
+def _legacy_thinking_mode(env: Mapping[str, str]) -> ReasoningMode | None:
+    raw = env.get("UMMAYA_K_EXAONE_THINKING")
+    if raw is None:
+        return None
+    normalized = raw.lower()
+    if normalized in {"1", "true", "yes"}:
+        return "deep"
+    if normalized in {"0", "false", "no"}:
+        return "fast"
+    return None
+
+
+def _policy_for(
+    mode: ReasoningMode,
+    source: ReasoningModeSource,
+) -> ResolvedReasoningPolicy:
+    enable_thinking = mode in {"deep", "diagnostic"}
+    return ResolvedReasoningPolicy(
+        mode=mode,
+        source=source,
+        enable_thinking=enable_thinking,
+        parse_reasoning=True,
+        include_reasoning=enable_thinking,
+    )

package/src/ummaya/tools/discovery_bridge.py

@@ -138,7 +138,11 @@ _VERIFY_FAMILIES: list[dict[str, Any]] = [
             "네이버인증",
             "토스인증",
             "정부24",
+            "홈택스",
+            "국세청",
             "민원",
+            "증명원",
+            "소득금액증명원",
             "주민등록등본",
             "발급",
         ],
@@ -149,12 +153,20 @@ _VERIFY_FAMILIES: list[dict[str, Any]] = [
             "Naver",
             "Toss",
             "gov24",
+            "hometax",
+            "national tax service",
             "civil petition",
+            "income certificate",
             "resident registration certificate",
             "issuance",
         ],
         "endpoint": "https://api.gateway.ummaya.gov.kr/v1/verify/simple",
         "policy_authority": "https://www.kftc.or.kr/",
+        "scope_rules": (
+            "Scope rule: simple-auth module verification uses the canonical "
+            "check tool_id 'mock_verify_module_simple_auth'. Do not set tool_id "
+            "to 'simple_auth_module'; that string is only the internal family_hint."
+        ),
     },
     {
         "tool_id": "mock_verify_module_any_id_sso",
@@ -221,7 +233,9 @@ _VERIFY_FAMILIES: list[dict[str, Any]] = [
         "scope_rules": (
             "Scope rule: mobile ID identity verification uses exactly scope_list "
             "['check:mobile_id.identity']; do not invent find:identity.info "
-            "or find:identity.verify scopes."
+            "or find:identity.verify scopes. Use the canonical check tool_id "
+            "'mock_verify_mobile_id'. Do not set tool_id to 'mobile_id'; that "
+            "string is only the internal family_hint."
         ),
     },
     {
@@ -304,6 +318,8 @@ def _verify_to_govapitool(entry: dict[str, Any]) -> GovAPITool:
         output_schema=_OpaqueOutput,
         llm_description=(
             "Use only through the core check primitive: "
+            f"check({{tool_id: '{entry['tool_id']}', params: {{...}}}}). "
+            "Canonical action-scope form: "
             f"check(tool_id='{entry['tool_id']}', params={{...}}). "
             "Do not call this adapter through find.\n\n"
             f"{scope_clause}"

package/src/ummaya/tools/executor.py

@@ -30,6 +30,7 @@ from ummaya.tools.envelope import make_error_envelope, normalize
 from ummaya.tools.errors import (
     EnvelopeNormalizationError,
     LookupErrorReason,
+    ToolExecutionError,
     ToolNotFoundError,
     UmmayaToolError,
 )
@@ -79,6 +80,11 @@ def _classify_adapter_exception(exc: Exception) -> tuple[LookupErrorReason, bool
     if isinstance(exc, Layer3GateViolation):
         # Programming error: stub handler was reached despite auth-gate — never retry.
         return (LookupErrorReason.upstream_unavailable, False)
+    if isinstance(exc, ToolExecutionError) and isinstance(exc.cause, httpx.HTTPStatusError):
+        status_code = exc.cause.response.status_code
+        if status_code in {400, 401, 403, 404}:
+            return (LookupErrorReason.upstream_unavailable, False)
+        return (LookupErrorReason.upstream_unavailable, True)
     if isinstance(exc, LiveAdapterProxyConfigurationError):
         return (LookupErrorReason.upstream_unavailable, False)
     if isinstance(exc, (ValueError, TypeError, KMADomainError)):
@@ -118,6 +124,19 @@ def _adapter_validation_recovery_hint(tool_id: str) -> str:
             " prefer nmc_emergency_search when authenticated, or a location POI"
             " search when no authenticated NMC session is present."
         )
+    if tool_id == "nmc_aed_site_locate":
+        return (
+            " REGION FILTER ONLY: this AED adapter uses official NMC Q0/Q1"
+            " region filters, not ER-search mode. If you have"
+            " a place name, call kakao_keyword_search({query:'<장소명>'}), then"
+            " kakao_coord_to_region({lat:<lat>, lon:<lon>}). Re-invoke this"
+            " tool as nmc_aed_site_locate({q0:region.region_1depth_name,"
+            " q1:region.region_2depth_name, page_no:1, num_of_rows:10,"
+            " origin_lat:<original place lat>, origin_lon:<original place lon>})."
+            " origin_lat/origin_lon are optional client-side distance-sort fields;"
+            " copy them from the coordinate-producing locate result when available."
+            " Do NOT pass mode, lat/lon, or ER-only fields."
+        )
     if tool_id in {"kakao_coord_to_region", "sgis_adm_cd_lookup"}:
         return (
             " COPY EXACT COORDINATES: call this reverse-geocode adapter with"
@@ -311,8 +330,9 @@ class ToolExecutor:
                 reason=reason,
                 message=(
                     f"Adapter '{tool_id}' raised {type(exc).__name__}: {str(exc)[:240]}. "
-                    "Do NOT fabricate a response from prior knowledge; use another "
-                    "appropriate adapter or explain that the lookup failed."
+                    "Do NOT fabricate a response from prior knowledge; explain that "
+                    "the lookup failed, cite the official agency channel, and ask "
+                    "before trying a different adapter."
                 ),
                 request_id=request_id,
                 elapsed_ms=_elapsed(),
@@ -480,20 +500,20 @@ class ToolExecutor:
             recovery_hint = _adapter_validation_recovery_hint(tool_id)
             if not recovery_hint and tool_id == "nmc_emergency_search":
                 recovery_hint = (
-                    " LOCATE FIRST: call locate with a locate adapter from"
+                    " LOCATE FIRST: call a concrete locate adapter from"
                     " <available_adapters>. For a named place use"
-                    " locate({tool_id:'kakao_keyword_search', params:{query:'<지역명>'}}),"
-                    " then call locate({tool_id:'kakao_coord_to_region',"
-                    " params:{lat:<lat>, lon:<lon>}}). Re-invoke this tool with"
-                    " params {mode:'region', q0:region.region_1depth_name,"
+                    " kakao_keyword_search({query:'<지역명>'}), then call"
+                    " kakao_coord_to_region({lat:<lat>, lon:<lon>}). Re-invoke"
+                    " this tool as nmc_emergency_search({mode:'region',"
+                    " q0:region.region_1depth_name,"
                     " q1:region.region_2depth_name, origin_lat:<lat>, origin_lon:<lon>,"
-                    " limit:<N>}. Copy decimal WGS-84 coordinates exactly from locate;"
+                    " limit:<N>}). Copy decimal WGS-84 coordinates exactly from locate;"
                     " do NOT round, guess coordinates, or set QN unless the citizen"
                     " gave a specific institution name."
                 )
             elif not recovery_hint and need_resolve:
                 recovery_hint = (
-                    " LOCATE FIRST: call locate with the appropriate locate adapter"
+                    " LOCATE FIRST: call the appropriate concrete locate adapter"
                     " from <available_adapters> to obtain the missing coordinates /"
                     " admin code, then re-invoke this tool with the returned values."
                     " Do NOT guess coordinates or codes from prior knowledge."
@@ -566,8 +586,8 @@ class ToolExecutor:
                     f"Adapter '{tool_id}' raised an exception during upstream call. "
                     f"Detail: {_exc_summary}. "
                     "Do NOT fabricate a response from prior knowledge — tell the citizen "
-                    "the lookup failed, cite the official agency channel, and offer to "
-                    "retry or try a different tool."
+                    "the lookup failed, cite the official agency channel, and ask "
+                    "before retrying or trying a different tool."
                 ),
                 request_id=request_id,
                 elapsed_ms=_elapsed(),
@@ -637,7 +657,7 @@ class ToolExecutor:
                     f"expected envelope schema. Detail: {_exc_detail}. "
                     "Do NOT fabricate a response from prior knowledge — tell the citizen "
                     "the data could not be parsed, cite the official agency channel, and "
-                    "offer to retry or try a different tool."
+                    "ask before retrying or trying a different tool."
                 ),
                 request_id=request_id,
                 elapsed_ms=_elapsed(),

package/src/ummaya/tools/geocoding/kakao_client.py

@@ -19,8 +19,7 @@ business logic. Reference: PyKakao 1.x ``Local`` class
 endpoints as six methods on a single facade — the industry-standard
 Korean wrapper for this API. UMMAYA originally shipped only
 ``search_address`` (Spec 022); ``search_keyword`` is added here to close
-the POI-coverage gap captured in
-``specs/integration-verification/donga-univ-poi-bug/``.
+the POI-coverage gap captured during historical live-location debugging.
 
 Authentication: REST API key via ``Authorization: KakaoAK {key}`` header.
 Key source: ``UMMAYA_KAKAO_API_KEY`` environment variable.