ummaya 0.2.4 → 0.2.5

package/src/ummaya/tools/routing/intent_types.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Final, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+ActivePrimitive = Literal["find", "locate", "send", "check"]
+
+ACTIVE_PRIMITIVES: Final[tuple[ActivePrimitive, ...]] = ("find", "locate", "send", "check")
+LEGACY_PRIMITIVE_ALIASES: Final[dict[str, ActivePrimitive]] = {
+    "lookup": "find",
+    "resolve_location": "locate",
+    "submit": "send",
+    "verify": "check",
+}
+
+
+class ToolSelectionIntent(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    raw_query: str
+    normalized_query: str
+    intent_verbs: tuple[ActivePrimitive, ...]
+    entities: tuple[str, ...]
+    document_refs: tuple[str, ...]
+    location_refs: tuple[str, ...]
+    time_refs: tuple[str, ...]
+    public_data_refs: tuple[str, ...]
+    credential_refs: tuple[str, ...]
+    side_effect_markers: tuple[str, ...]
+    explicit_tool_ids: tuple[str, ...]
+    explicit_artifact_ids: tuple[str, ...]
+    candidate_primitives: tuple[ActivePrimitive, ...]
+    missing_slots: tuple[str, ...]
+    unsafe_assumptions: tuple[str, ...]
+    requires_clarification: bool
+    requires_permission: bool
+
+    def has_location_ref(self, value: str) -> bool:
+        return value in self.location_refs
+
+    def has_public_data_ref(self, value: str) -> bool:
+        return value in self.public_data_refs
+
+    def has_document_ref(self, value: str) -> bool:
+        return value in self.document_refs

package/src/ummaya/tools/routing/lint.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from ummaya.tools.routing.types import (
+    RAW_SCHEMA_MARKERS,
+    AdapterCard,
+    AdapterCardQualityViolation,
+)
+
+
+def lint_adapter_card(card: AdapterCard) -> tuple[AdapterCardQualityViolation, ...]:
+    violations: list[AdapterCardQualityViolation] = []
+    if card.source_mode in ("live", "mock") and not card.policy_authority_url:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_policy_citation",
+                message="live/mock adapter cards must cite an agency policy URL",
+            )
+        )
+    if not card.input_schema_summary:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_required_slot_metadata",
+                message="adapter cards must summarize input slots",
+            )
+        )
+    if not card.safety_annotations:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_safety_annotations",
+                message="adapter cards must expose safety annotations",
+            )
+        )
+    if not card.credential_requirements:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_credential_requirements",
+                message="adapter cards must expose credential requirements",
+            )
+        )
+    if not card.examples_ko or not card.examples_en:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_examples",
+                message="adapter cards must include Korean and English examples",
+            )
+        )
+    if not card.negative_examples:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_negative_examples",
+                message="adapter cards must include negative examples",
+            )
+        )
+    if not card.limitations:
+        violations.append(
+            AdapterCardQualityViolation(
+                code="missing_limitations",
+                message="adapter cards must state routing limitations",
+            )
+        )
+    if any(marker in card.routing_text for marker in RAW_SCHEMA_MARKERS):
+        violations.append(
+            AdapterCardQualityViolation(
+                code="raw_schema_leakage",
+                message="routing_text must not embed raw JSON schema",
+            )
+        )
+    return tuple(violations)
+
+
+def assert_adapter_card_quality(card: AdapterCard) -> None:
+    violations = lint_adapter_card(card)
+    if not violations:
+        return
+    detail = ", ".join(f"{violation.code}: {violation.message}" for violation in violations)
+    raise ValueError(f"AdapterCard quality violations: {detail}")

package/src/ummaya/tools/routing/metadata.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import assert_never
+
+from ummaya.tools.models import GovAPITool, MockFidelityGrade
+from ummaya.tools.routing.schema import unique
+from ummaya.tools.routing.types import (
+    AdapterCardError,
+    PrimitiveFamily,
+    SchemaFieldSummary,
+    SideEffectLevel,
+    SourceMode,
+)
+
+
+def primitive_family(value: str | None) -> PrimitiveFamily:
+    match value:
+        case "find":
+            return "find"
+        case "locate":
+            return "locate"
+        case "send":
+            return "send"
+        case "check":
+            return "check"
+        case "document":
+            return "document"
+        case None:
+            raise AdapterCardError("AdapterCard requires GovAPITool.primitive to be declared")
+        case _:
+            raise AdapterCardError(f"Unsupported adapter primitive for AdapterCard: {value!r}")
+
+
+def source_mode_for_tool(tool: GovAPITool) -> SourceMode:
+    return "mock" if tool.adapter_mode == "mock" else "live"
+
+
+def side_effect_level_for_tool(
+    tool: GovAPITool,
+    primitive: PrimitiveFamily,
+) -> SideEffectLevel:
+    if tool.policy is not None:
+        match tool.policy.citizen_facing_gate:
+            case "read-only":
+                return "read_only"
+            case "login":
+                return "login"
+            case "action":
+                return "action"
+            case "sign":
+                return "sign"
+            case "send":
+                return "send"
+            case unreachable_gate:
+                assert_never(unreachable_gate)
+    match primitive:
+        case "send":
+            return "send"
+        case "check":
+            return "verify"
+        case "find" | "locate" | "document":
+            return "read_only"
+        case unreachable_primitive:
+            assert_never(unreachable_primitive)
+
+
+def mock_fidelity_grade_for_tool(tool: GovAPITool) -> MockFidelityGrade:
+    if tool.adapter_mode != "mock":
+        return "not_applicable"
+    if tool.mock_fidelity_grade == "not_applicable":
+        return "unknown"
+    return tool.mock_fidelity_grade
+
+
+def credential_requirements_for_tool(tool: GovAPITool) -> tuple[str, ...]:
+    requirements: list[str] = [tool.auth_type]
+    if tool.published_tier_minimum is not None:
+        requirements.append(tool.published_tier_minimum)
+    if tool.nist_aal_hint is not None:
+        requirements.append(tool.nist_aal_hint)
+    return tuple(unique(requirements))
+
+
+def capabilities_for_tool(tool: GovAPITool, primitive: PrimitiveFamily) -> tuple[str, ...]:
+    return tuple(unique([primitive, *tool.category, tool.name_ko]))
+
+
+def entity_types_for_tool(
+    input_summary: Sequence[SchemaFieldSummary],
+    categories: Sequence[str],
+) -> tuple[str, ...]:
+    names = [field.name for field in input_summary]
+    if names:
+        return tuple(names)
+    return tuple(unique(categories))
+
+
+def prerequisite_tools_for_tool(tool: GovAPITool, primitive: PrimitiveFamily) -> tuple[str, ...]:
+    description = (tool.llm_description or "").lower()
+    if primitive == "send" or "prior check" in description or "delegation" in description:
+        return ("check",)
+    return ()
+
+
+def examples_ko_for_tool(tool: GovAPITool) -> tuple[str, ...]:
+    if tool.trigger_examples:
+        return tuple(tool.trigger_examples)
+    return (tool.name_ko,)
+
+
+def examples_en_for_tool(tool: GovAPITool, primitive: PrimitiveFamily) -> tuple[str, ...]:
+    domain = tool.category[0] if tool.category else tool.id
+    return (f"Use {tool.id} to {primitive} {domain} information.",)
+
+
+def limitations_for_tool(
+    tool: GovAPITool,
+    source_mode: SourceMode,
+    policy_authority_url: str | None,
+) -> tuple[str, ...]:
+    limitations = [f"Requires registry source_mode {source_mode} and auth_type {tool.auth_type}."]
+    if source_mode == "mock":
+        limitations.append("Mock output may mirror shape without live upstream freshness.")
+    if policy_authority_url is None:
+        limitations.append("No agency policy citation is registered for this adapter.")
+    return tuple(limitations)
+
+
+def safety_annotations_for_tool(
+    tool: GovAPITool,
+    side_effect_level: SideEffectLevel,
+) -> tuple[str, ...]:
+    values = [
+        f"side_effect_level:{side_effect_level}",
+        f"auth_type:{tool.auth_type}",
+        f"concurrency_safe:{str(tool.is_concurrency_safe).lower()}",
+    ]
+    if tool.policy is not None:
+        values.append(f"citizen_gate:{tool.policy.citizen_facing_gate}")
+    return tuple(values)
+
+
+def domain_for_tool(tool: GovAPITool) -> str:
+    if tool.category:
+        return tool.category[0]
+    return tool.id
+
+
+def routing_text(
+    *,
+    tool_id: str,
+    primitive: PrimitiveFamily,
+    agency: str,
+    domain: str,
+    capabilities: Sequence[str],
+    required_slots: Sequence[str],
+    examples_ko: Sequence[str],
+    limitations: Sequence[str],
+) -> str:
+    return " | ".join(
+        (
+            f"tool_id={tool_id}",
+            f"primitive={primitive}",
+            f"agency={agency}",
+            f"domain={domain}",
+            f"capabilities={', '.join(capabilities)}",
+            f"required_slots={', '.join(required_slots) or 'none'}",
+            f"examples_ko={'; '.join(examples_ko)}",
+            f"limitations={'; '.join(limitations)}",
+        )
+    )

package/src/ummaya/tools/routing/projection.py

@@ -0,0 +1,340 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict
+
+from ummaya.tools.errors import ToolNotFoundError
+from ummaya.tools.models import GovAPITool
+from ummaya.tools.routing.decision_types import RouteCandidate, RouteDecision, SchemaProjectionLevel
+from ummaya.tools.routing.schema import model_json_schema
+
+if TYPE_CHECKING:
+    from ummaya.tools.registry import ToolRegistry
+
+
+class AvailableAdaptersProjection(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    content: str | None
+    tool_ids: tuple[str, ...]
+    schema_projection_level: SchemaProjectionLevel
+
+
+def build_available_adapters_projection(
+    decision: RouteDecision,
+    registry: ToolRegistry,
+    *,
+    query: str,
+    projection_level: SchemaProjectionLevel | None = None,
+    max_visible: int = 5,
+    visible_tool_ids: Iterable[str] | None = None,
+    exclude_tool_ids: Iterable[str] = (),
+) -> AvailableAdaptersProjection:
+    level = projection_level or decision.schema_projection_level
+    if level == "none":
+        return AvailableAdaptersProjection(
+            content=None,
+            tool_ids=(),
+            schema_projection_level=level,
+        )
+
+    visible = _selected_candidates(
+        decision,
+        max_visible=max_visible,
+        visible_tool_ids=visible_tool_ids,
+        exclude_tool_ids=exclude_tool_ids,
+    )
+    if not visible:
+        return AvailableAdaptersProjection(
+            content=None,
+            tool_ids=(),
+            schema_projection_level="none",
+        )
+
+    tool_ids = tuple(candidate.tool_id for candidate in visible)
+    lines: list[str] = [
+        (
+            f'<available_adapters query="{_xml_attr(query[:120])}" '
+            f'decision_id="{decision.decision_id}" '
+            f'backend="{_xml_attr(decision.backend_label)}" '
+            f'schema_projection="{level}">'
+        ),
+        (
+            f"RouteDecision candidates (top {len(visible)}, backend={decision.backend_label}, "
+            f"manifest_hash={decision.manifest_hash[:12]})."
+        ),
+        "Use concrete adapter function names when they are present in tools[].",
+    ]
+    if decision.degradation_reason:
+        lines.append(f"degradation_reason: {decision.degradation_reason}")
+    if decision.permission_gate:
+        lines.append("permission_gate: true")
+    if level == "name_only":
+        lines.extend(f"- {candidate.tool_id}" for candidate in visible)
+        lines.append("</available_adapters>")
+        return AvailableAdaptersProjection(
+            content="\n".join(lines),
+            tool_ids=tool_ids,
+            schema_projection_level=level,
+        )
+
+    for candidate in visible:
+        lines.extend(_candidate_lines(candidate, registry, projection_level=level))
+    lines.extend(_route_rules(visible))
+    lines.append("</available_adapters>")
+    return AvailableAdaptersProjection(
+        content="\n".join(lines),
+        tool_ids=tool_ids,
+        schema_projection_level=level,
+    )
+
+
+def selected_concrete_adapter_tools(
+    decision: RouteDecision,
+    registry: ToolRegistry,
+    *,
+    exclude_tool_ids: Iterable[str] = (),
+    max_tools: int = 5,
+) -> tuple[GovAPITool, ...]:
+    excluded = frozenset(exclude_tool_ids)
+    tools: list[GovAPITool] = []
+    for tool_id in _decision_tool_ids(decision):
+        if tool_id in excluded:
+            continue
+        try:
+            tools.append(registry.find(tool_id))
+        except ToolNotFoundError:
+            continue
+        if len(tools) >= max_tools:
+            break
+    return tuple(tools)
+
+
+def _selected_candidates(
+    decision: RouteDecision,
+    *,
+    max_visible: int,
+    visible_tool_ids: Iterable[str] | None = None,
+    exclude_tool_ids: Iterable[str] = (),
+) -> tuple[RouteCandidate, ...]:
+    excluded = frozenset(exclude_tool_ids)
+    selected = (
+        tuple(tool_id for tool_id in visible_tool_ids if tool_id not in excluded)
+        if visible_tool_ids is not None
+        else tuple(tool_id for tool_id in _decision_tool_ids(decision) if tool_id not in excluded)
+    )
+    selected_rank = {tool_id: index for index, tool_id in enumerate(selected)}
+    candidates_by_id = {
+        candidate.tool_id: candidate
+        for candidate in decision.candidate_set
+        if candidate.tool_id in selected_rank
+    }
+    ordered = tuple(
+        candidates_by_id[tool_id] for tool_id in selected if tool_id in candidates_by_id
+    )
+    return ordered[: max(0, max_visible)]
+
+
+def _decision_tool_ids(decision: RouteDecision) -> tuple[str, ...]:
+    if decision.selected_tools:
+        return decision.selected_tools
+    if (
+        decision.clarification is not None
+        and decision.clarification.reason == "side_effect_confirmation"
+    ):
+        return ()
+    return tuple(candidate.tool_id for candidate in decision.candidate_set)
+
+
+def _candidate_lines(
+    candidate: RouteCandidate,
+    registry: ToolRegistry,
+    *,
+    projection_level: SchemaProjectionLevel,
+) -> list[str]:
+    card = candidate.card
+    lines = [
+        f"- tool_id: {card.tool_id}",
+        f"  primitive: {card.primitive_family}",
+        f"  source_mode: {card.source_mode}",
+        f"  agency: {card.agency}",
+        f"  domain: {card.domain}",
+        f"  score: {candidate.retrieval_score:.4f}",
+        f"  description: {_one_line(card.routing_text)}",
+        f"  required_params: {list(card.required_slots)}",
+        f"  optional_params: {list(card.optional_slots)}",
+        f"  call_hint: {card.tool_id}({{...schema fields...}})",
+        f"  policy_url: {card.policy_authority_url or ''}",
+    ]
+    llm_description = _tool_llm_description(card.tool_id, registry)
+    if llm_description:
+        lines.append(f"  usage: {_one_line(llm_description)}")
+    if projection_level in {"summary", "full_schema"}:
+        lines.append("  input_schema_summary:")
+        lines.extend(_schema_summary_lines(candidate, registry))
+    if projection_level == "full_schema":
+        try:
+            tool = registry.find(card.tool_id)
+            schema_json = json.dumps(
+                model_json_schema(tool.input_schema),
+                ensure_ascii=False,
+                sort_keys=True,
+            )
+        except ToolNotFoundError:
+            schema_json = "{}"
+        lines.append(f"  input_schema_json: {schema_json}")
+    return lines
+
+
+def _tool_llm_description(tool_id: str, registry: ToolRegistry) -> str | None:
+    try:
+        value = registry.find(tool_id).llm_description
+    except ToolNotFoundError:
+        return None
+    return value if isinstance(value, str) and value.strip() else None
+
+
+def _schema_summary_lines(candidate: RouteCandidate, registry: ToolRegistry) -> list[str]:
+    card = candidate.card
+    try:
+        schema = model_json_schema(registry.find(card.tool_id).input_schema)
+    except ToolNotFoundError:
+        schema = {}
+    properties = _mapping(schema.get("properties"))
+    defs = _mapping(schema.get("$defs"))
+    required = frozenset(card.required_slots)
+    lines: list[str] = []
+    for field in card.input_schema_summary:
+        flag = "required" if field.required else "optional"
+        description = f" - {_one_line(field.description)}" if field.description else ""
+        lines.append(f"    - {field.name} ({field.type}, {flag}){description}")
+        field_schema = _mapping(properties.get(field.name))
+        for nested_name, nested_schema in _nested_properties(field.name, field_schema, defs):
+            nested_description = _description(nested_schema)
+            nested_suffix = f" - {_one_line(nested_description)}" if nested_description else ""
+            nested_required = _nested_required(field.name, nested_name, field_schema, defs)
+            nested_flag = "required" if field.name in required and nested_required else "optional"
+            lines.append(
+                f"      - {nested_name} ({_schema_type(nested_schema)}, {nested_flag})"
+                f"{nested_suffix}"
+            )
+    return lines
+
+
+def _route_rules(candidates: tuple[RouteCandidate, ...]) -> tuple[str, ...]:
+    primitives = frozenset(candidate.card.primitive_family for candidate in candidates)
+    lines = [
+        "Rules:",
+        (
+            "  - Concrete adapter functions accept only their own schema fields; "
+            "do not wrap tool_id/params inside concrete adapter calls."
+        ),
+        (
+            "  - Use root primitives find/locate/check/send only when the concrete "
+            "adapter function is not loaded."
+        ),
+        (
+            "  - Preserve explicit citizen constraints such as count, radius, date, "
+            "time, category, institution type, and administrative region when a "
+            "selected schema exposes the matching field."
+        ),
+    ]
+    if primitives == {"find"}:
+        lines.append(
+            "  - All selected adapters are read/fetch candidates; do not switch to "
+            "check/send unless the citizen explicitly asks for authentication, "
+            "consent, submission, payment, report, or filing."
+        )
+    return tuple(lines)
+
+
+def _one_line(value: str | None, *, limit: int = 900) -> str:
+    compact = " ".join((value or "").split())
+    if len(compact) <= limit:
+        return compact
+    return compact[: limit - 3] + "..."
+
+
+def _xml_attr(value: str) -> str:
+    return (
+        value.replace("&", "&amp;").replace('"', "&quot;").replace("<", "&lt;").replace(">", "&gt;")
+    )
+
+
+def _nested_properties(
+    parent_name: str,
+    field_schema: Mapping[str, object],
+    defs: Mapping[str, object],
+) -> tuple[tuple[str, Mapping[str, object]], ...]:
+    target = _resolve_ref(field_schema, defs)
+    if target:
+        return _properties_with_prefix(parent_name, target)
+    raw_items = field_schema.get("items")
+    item_schema = _mapping(raw_items)
+    item_target = _resolve_ref(item_schema, defs)
+    if item_target:
+        return _properties_with_prefix(f"{parent_name}[]", item_target)
+    return ()
+
+
+def _properties_with_prefix(
+    prefix: str, schema: Mapping[str, object]
+) -> tuple[tuple[str, Mapping[str, object]], ...]:
+    properties = _mapping(schema.get("properties"))
+    return tuple(
+        (f"{prefix}.{name}", _mapping(spec)) for name, spec in properties.items() if str(name)
+    )
+
+
+def _nested_required(
+    parent_name: str,
+    nested_name: str,
+    field_schema: Mapping[str, object],
+    defs: Mapping[str, object],
+) -> bool:
+    target = _resolve_ref(field_schema, defs)
+    nested_key = nested_name.removeprefix(f"{parent_name}.")
+    if not target:
+        item_schema = _mapping(field_schema.get("items"))
+        target = _resolve_ref(item_schema, defs)
+        nested_key = nested_name.removeprefix(f"{parent_name}[].")
+    raw_required = target.get("required") if target else None
+    if not isinstance(raw_required, list):
+        return False
+    return nested_key in {str(item) for item in raw_required if isinstance(item, str)}
+
+
+def _resolve_ref(schema: Mapping[str, object], defs: Mapping[str, object]) -> Mapping[str, object]:
+    ref = schema.get("$ref")
+    if not isinstance(ref, str) or not ref.startswith("#/$defs/"):
+        return {}
+    return _mapping(defs.get(ref.removeprefix("#/$defs/")))
+
+
+def _mapping(value: object) -> Mapping[str, object]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _description(schema: Mapping[str, object]) -> str | None:
+    value = schema.get("description")
+    return value if isinstance(value, str) and value.strip() else None
+
+
+def _schema_type(schema: Mapping[str, object]) -> str:
+    raw_type = schema.get("type")
+    if isinstance(raw_type, str):
+        return raw_type
+    if isinstance(raw_type, list):
+        return "|".join(str(item) for item in raw_type)
+    if "$ref" in schema:
+        return "ref"
+    if "anyOf" in schema:
+        return "anyOf"
+    if "oneOf" in schema:
+        return "oneOf"
+    return "unknown"