ummaya 0.2.3 → 0.2.5

package/src/ummaya/_canonical/__init__.py

@@ -12,6 +12,8 @@ depending on the source-tree layout:
 * ``checklist_manifest.yaml`` — 50-row plugin validation checklist.
   Loaded by :mod:`ummaya.plugins.checks.framework` and the
   ``ummaya-plugin-validate`` CLI.
+* ``document-tools.schema.json`` — Public AX document harness tool
+  contract. Loaded by :mod:`ummaya.tools.documents.contracts`.
 
 The mapping is in pyproject.toml under
 ``[tool.hatch.build.targets.wheel.force-include]``.

package/src/ummaya/context/builder.py

@@ -20,6 +20,8 @@ import json
 import logging
 from typing import TYPE_CHECKING
 
+from ummaya.context.attachments import AttachmentCollector
+from ummaya.context.budget import BudgetEstimator
 from ummaya.context.compact_models import CompactionConfig, CompactionResult
 from ummaya.context.models import (
     AssembledContext,
@@ -57,6 +59,10 @@ class ContextBuilder:
         self._registry = registry
         self._compaction_config = compaction_config
         self._assembler = SystemPromptAssembler()
+        self._attachment_collector = AttachmentCollector(config=self._config)
+        self._budget_estimator = BudgetEstimator()
+        self._core_tool_defs_cache_key: tuple[str, ...] | None = None
+        self._core_tool_defs_cache: list[dict[str, object]] = []
 
         # Cached assembled ChatMessage (set on first build_system_message() call).
         self._system_message: ChatMessage | None = None
@@ -106,11 +112,7 @@ class ContextBuilder:
             ``ContextLayer(role='user', layer_name='turn_attachment', content=…)``
             or ``None`` when no attachment content exists.
         """
-        # Import here to avoid circular imports between builder and attachments.
-        from ummaya.context.attachments import AttachmentCollector  # noqa: PLC0415
-
-        collector = AttachmentCollector(config=self._config)
-        collected = collector.collect(state=state, api_health=api_health)
+        collected = self._attachment_collector.collect(state=state, api_health=api_health)
         if collected is None:
             return None
         return ContextLayer(role="user", layer_name="turn_attachment", content=collected)
@@ -161,15 +163,12 @@ class ContextBuilder:
         tool_definitions = self._build_tool_definitions(state)
 
         # --- Budget (US4) ---
-        from ummaya.context.budget import BudgetEstimator  # noqa: PLC0415
-
-        estimator = BudgetEstimator()
         assembled_no_budget = AssembledContext(
             system_layer=system_layer,
             turn_attachment=turn_attachment,
             tool_definitions=tool_definitions,
         )
-        budget = estimator.estimate(
+        budget = self._budget_estimator.estimate(
             context=assembled_no_budget,
             hard_limit=hard_limit,
             soft_limit=int(hard_limit * 0.80),
@@ -232,8 +231,15 @@ class ContextBuilder:
         if self._registry is None:
             return []
 
-        # Core prefix (deterministic, sorted by id — FR-004)
-        core_defs = self._registry.export_core_tools_openai()
+        # Core prefix (deterministic, sorted by id — FR-004).  Core tool
+        # schemas are stable across turns, so cache the expensive Pydantic JSON
+        # schema export and invalidate only when the active core id set changes.
+        core_tools = self._registry.core_tools()
+        core_cache_key = tuple(tool.id for tool in core_tools)
+        if core_cache_key != self._core_tool_defs_cache_key:
+            self._core_tool_defs_cache = [tool.to_openai_tool() for tool in core_tools]
+            self._core_tool_defs_cache_key = core_cache_key
+        core_defs = self._core_tool_defs_cache
 
         # Situational suffix (dynamic, sorted by id — FR-004)
         situational_defs: list[dict[str, object]] = []

package/src/ummaya/engine/engine.py

@@ -8,7 +8,6 @@ the standalone ``query()`` async generator.
 
 from __future__ import annotations
 
-import json
 import logging
 from collections.abc import AsyncIterator
 from typing import TYPE_CHECKING
@@ -20,59 +19,20 @@ from ummaya.engine.models import QueryContext, QueryState, SessionBudget
 from ummaya.engine.query import query
 from ummaya.llm.client import LLMClient
 from ummaya.llm.models import ChatMessage
-from ummaya.tools.errors import ToolNotFoundError
 from ummaya.tools.executor import ToolExecutor
 from ummaya.tools.registry import ToolRegistry
+from ummaya.tools.routing import (
+    RouteDecisionService,
+    build_available_adapters_projection,
+    selected_concrete_adapter_tools,
+)
 
 if TYPE_CHECKING:
     from ummaya.permissions.models import SessionContext
 
 logger = logging.getLogger(__name__)
 
-_LOCATION_DEPENDENT_SCHEMA_KEYS = frozenset(
-    {
-        "adm_cd",
-        "admcd",
-        "admin_code",
-        "administrative_code",
-        "latitude",
-        "lat",
-        "longitude",
-        "lon",
-        "lng",
-        "nx",
-        "ny",
-        "region_cd",
-        "region_code",
-    }
-)
-
-
-def _schema_requires_location_resolution(
-    input_schema_json: object,
-    required_params: object,
-) -> bool:
-    """Return True when an adapter schema needs prior locate output."""
-
-    return _contains_location_dependent_key(input_schema_json) or _contains_location_dependent_key(
-        required_params
-    )
-
-
-def _contains_location_dependent_key(value: object) -> bool:
-    """Recursively detect coordinate/admin-code schema fields."""
-
-    if isinstance(value, dict):
-        for key, nested in value.items():
-            if str(key).lower() in _LOCATION_DEPENDENT_SCHEMA_KEYS:
-                return True
-            if _contains_location_dependent_key(nested):
-                return True
-    elif isinstance(value, list):
-        return any(_contains_location_dependent_key(item) for item in value)
-    elif isinstance(value, str):
-        return value.lower() in _LOCATION_DEPENDENT_SCHEMA_KEYS
-    return False
+_INTERNAL_CONTEXT_TOOL_IDS = frozenset({"find", "locate", "check", "send", "search_tools"})
 
 
 class QueryEngine:
@@ -279,82 +239,39 @@ class QueryEngine:
         """Build dynamic adapter context and per-turn concrete tool exposure."""
 
         try:
-            from ummaya.tools.search import search  # noqa: PLC0415
-
-            candidates = search(
+            decision = RouteDecisionService(self._tool_registry).select_adapters(
                 user_message,
-                self._tool_registry.bm25_index,
-                self._tool_registry,
                 top_k=15,
+                max_selected=5,
             )
-        except Exception:  # noqa: BLE001
-            logger.exception("available_adapters auto-inject failed")
-            return None, ()
-
-        adapter_lines: list[str] = []
-        selected_tool_ids: list[str] = []
-        primary_find_without_location = False
-        visible_count = 0
-        for candidate in candidates:
-            try:
-                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
-            requires_location = _schema_requires_location_resolution(
-                candidate.input_schema_json,
-                candidate.required_params,
-            )
-            primary_find_without_location = primary_find_without_location or (
-                visible_count == 0 and primitive == "find" and not requires_location
+            concrete_tools = selected_concrete_adapter_tools(
+                decision,
+                self._tool_registry,
+                exclude_tool_ids=_INTERNAL_CONTEXT_TOOL_IDS,
+                max_tools=5,
             )
-            if visible_count > 0 and primary_find_without_location and requires_location:
-                continue
-            schema_json = json.dumps(
-                candidate.input_schema_json,
-                ensure_ascii=False,
-                sort_keys=True,
+            tool_ids = tuple(tool.id for tool in concrete_tools)
+            if not tool_ids:
+                return None, ()
+            projection_level = (
+                decision.schema_projection_level if decision.selected_tools else "summary"
             )
-            selected_tool_ids.append(candidate.tool_id)
-            adapter_lines.extend(
-                [
-                    f"- tool_id: {candidate.tool_id}",
-                    f"  primitive: {candidate.primitive}",
-                    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.tool_id}({{...}})",
-                    f"  policy_url: {candidate.real_classification_url or ''}",
-                ]
+            projection = build_available_adapters_projection(
+                decision,
+                self._tool_registry,
+                query=user_message,
+                projection_level=projection_level,
+                max_visible=len(tool_ids),
+                visible_tool_ids=tool_ids,
             )
-            visible_count += 1
-            if visible_count >= 5:
-                break
+        except Exception:  # noqa: BLE001
+            logger.exception("available_adapters auto-inject failed")
+            return None, ()
 
-        if not adapter_lines:
+        if projection.content is None:
             return None, ()
 
-        content = "\n".join(
-            [
-                "<available_adapters>",
-                "Use these adapter candidates for this citizen request. "
-                "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 "
-                "coordinates, administrative codes, or a place-to-region conversion.",
-                *adapter_lines,
-                "</available_adapters>",
-            ]
-        )
-        return ChatMessage(role="system", content=content), tuple(selected_tool_ids)
+        return ChatMessage(role="system", content=projection.content), tool_ids
 
     def set_permission_session(self, session: SessionContext | None) -> None:
         """Update the permission-pipeline session used for subsequent turns.

package/src/ummaya/engine/query.py

@@ -424,6 +424,11 @@ async def _dispatch_root_primitive(
             error=f"{primitive} cannot target itself.",
             error_type="validation",
         )
+    params = _normalize_root_primitive_adapter_params(
+        primitive=primitive,
+        target_tool_id=target_tool_id,
+        params=params,
+    )
 
     request_id = tc.id or f"{primitive}-call"
     if primitive == "find":
@@ -452,6 +457,21 @@ async def _dispatch_root_primitive(
     return ToolResult(tool_id=primitive, success=True, data=data)
 
 
+def _normalize_root_primitive_adapter_params(
+    *,
+    primitive: str,
+    target_tool_id: str,
+    params: dict[str, object],
+) -> dict[str, object]:
+    """Remove wrapper metadata accidentally duplicated inside adapter params."""
+    nested_tool_id = params.get("tool_id")
+    if nested_tool_id == target_tool_id:
+        return {key: value for key, value in params.items() if key != "tool_id"}
+    if target_tool_id == primitive and isinstance(nested_tool_id, str):
+        return {key: value for key, value in params.items() if key != "tool_id"}
+    return params
+
+
 async def _dispatch_concrete_adapter(
     tc: ToolCall,
     primitive: str,

package/src/ummaya/evidence/__init__.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Evidence Fabric v2 public API."""
+
+from ummaya.evidence.dataset_contract import EvidenceContractError
+from ummaya.evidence.models import (
+    EvidenceGate,
+    EvidenceStatus,
+    RunEvidence,
+)
+from ummaya.evidence.runner import run_dataset
+from ummaya.evidence.source_provenance import (
+    SourceProvenanceDecision,
+    SourceProvenanceLedger,
+    SourceProvenanceRecord,
+    SourceRedactionMetadata,
+    build_source_provenance_record,
+)
+from ummaya.evidence.task_registry import (
+    EvidenceDatasetRef,
+    EvidenceTask,
+    EvidenceTaskRegistry,
+    TaskRegistryError,
+    load_task_registry,
+)
+from ummaya.evidence.tool_layer_models import ToolLayerEvidenceEvent
+
+__all__ = [
+    "EvidenceDatasetRef",
+    "EvidenceContractError",
+    "EvidenceGate",
+    "EvidenceStatus",
+    "EvidenceTask",
+    "EvidenceTaskRegistry",
+    "RunEvidence",
+    "SourceProvenanceDecision",
+    "SourceProvenanceLedger",
+    "SourceProvenanceRecord",
+    "SourceRedactionMetadata",
+    "TaskRegistryError",
+    "ToolLayerEvidenceEvent",
+    "build_source_provenance_record",
+    "load_task_registry",
+    "run_dataset",
+]

package/src/ummaya/evidence/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Command line entrypoint for Evidence Fabric v2."""
+
+from ummaya.evidence.runner import main
+
+if __name__ == "__main__":
+    main()

package/src/ummaya/evidence/dataset_contract.py

@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Scenario dataset parsing for Evidence Fabric v2."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import assert_never
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from ummaya.evidence.json_types import JsonObject, JsonValue, parse_json_object
+
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+DEFAULT_SCENARIO_PATH = _REPO_ROOT / "evidence/scenarios/national_ax_citizen_requests_v1.yaml"
+DEFAULT_TASK_REGISTRY_PATH = _REPO_ROOT / "evidence/registry.yaml"
+DEFAULT_DATASET_REF = "ummaya/national-ax-core@local"
+BANNED_MODEL_VISIBLE_KEYS = frozenset(
+    {
+        "adapter_id",
+        "adapter_ids",
+        "adapter_family",
+        "expected_adapter_id",
+        "tool_id",
+        "tool_ids",
+        "expected_tool_id",
+        "expected_tool_ids",
+        "expected_adapter_family",
+        "expected_route_trace",
+        "route_trace",
+        "route_selection_assertion",
+        "route_selection_assertions",
+        "route_adapter_family",
+        "selected_adapter_family",
+        "selected_adapter_id",
+        "selected_tool",
+        "selected_tool_id",
+        "selected_tool_ids",
+        "selected_tools",
+        "fixture_refs",
+        "fixture_ref",
+        "current_adapter_id",
+        "assertion_events",
+        "assertion_kind",
+        "argument_feasibility",
+        "clarification_expected",
+        "clarification_reason",
+        "correlation_id",
+        "coverage_tags",
+        "evidence_events",
+        "expected_domain",
+        "expected_primitives",
+        "failure_recovery",
+        "manifest_hash",
+        "prompt_manifest_hash",
+        "query_hash",
+        "route_source",
+        "selected_domain",
+        "selected_primitives",
+        "status",
+        "stop_reason",
+        "tool_catalog_hash",
+        "trace_id",
+        "trace_kind",
+    }
+)
+REQUIRED_DOMAINS = frozenset(
+    {
+        "tax",
+        "civil_affairs",
+        "payments",
+        "utilities",
+        "identity",
+        "welfare",
+        "healthcare",
+        "housing",
+        "mobility",
+        "business",
+        "labor",
+        "education",
+        "safety",
+        "immigration",
+        "legal",
+        "personal_data",
+        "public_data",
+    }
+)
+
+
+class EvidenceContractError(ValueError):
+    """Raised when a scenario dataset violates the Evidence Fabric contract."""
+
+
+class ExpectedStep(BaseModel):
+    """One expected public-service loop step in a scenario."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    primitive: str
+    purpose: str
+
+
+class PermissionRequirements(BaseModel):
+    """Permission requirements attached to a citizen scenario."""
+
+    model_config = ConfigDict(frozen=True, extra="allow")
+
+    identity_assurance: str
+    user_confirmations: tuple[str, ...] = Field(default_factory=tuple)
+    sensitive_data: tuple[str, ...] = Field(default_factory=tuple)
+
+
+class Scenario(BaseModel):
+    """Minimum scenario shape needed by Evidence Fabric v2."""
+
+    model_config = ConfigDict(frozen=True, extra="allow")
+
+    id: str
+    priority: str = "P2"
+    lifecycle_domain: str
+    request_ko: str
+    request_en: str | None = None
+    agencies_or_infrastructure: tuple[str, ...] = Field(default_factory=tuple)
+    citizen_intent_verbs: tuple[str, ...] = Field(default_factory=tuple)
+    expected_ax_chain: tuple[ExpectedStep, ...]
+    permission_requirements: PermissionRequirements
+    expected_system_behavior: tuple[str, ...] = Field(default_factory=tuple)
+    evaluation_focus: tuple[str, ...] = Field(default_factory=tuple)
+
+
+class ScenarioDataset(BaseModel):
+    """Versioned citizen-demand scenario dataset."""
+
+    model_config = ConfigDict(frozen=True, extra="allow")
+
+    version: int
+    dataset_id: str
+    source_basis: str | None = None
+    target_system: str | None = None
+    allowed_primitives: tuple[str, ...] = Field(default_factory=tuple)
+    coverage_domains: tuple[str, ...]
+    scenarios: tuple[Scenario, ...]
+
+
+def parse_dataset(path: Path) -> ScenarioDataset:
+    """Parse and validate a scenario dataset file."""
+    raw = _load_yaml_mapping(path)
+    banned = _find_banned_keys(raw)
+    if banned:
+        raise EvidenceContractError(
+            "model-visible scenario dataset contains banned implementation keys: "
+            + ", ".join(banned)
+        )
+    try:
+        return ScenarioDataset.model_validate(raw)
+    except ValidationError as exc:
+        raise EvidenceContractError(str(exc)) from exc
+
+
+def resolve_repo_path(path: Path) -> Path:
+    """Resolve a repository-relative path from the Evidence Fabric root."""
+    return path if path.is_absolute() else _REPO_ROOT / path
+
+
+def _load_yaml_mapping(path: Path) -> JsonObject:
+    if not path.exists():
+        raise EvidenceContractError(f"scenario dataset not found: {path}")
+    loaded = yaml.safe_load(path.read_text(encoding="utf-8"))
+    try:
+        return parse_json_object(loaded)
+    except ValidationError as exc:
+        raise EvidenceContractError(f"scenario dataset must be a JSON mapping: {path}") from exc
+
+
+def _find_banned_keys(value: JsonValue, path: str = "$") -> tuple[str, ...]:
+    match value:
+        case dict():
+            hits: list[str] = []
+            for key, nested in value.items():
+                nested_path = f"{path}.{key}"
+                if key in BANNED_MODEL_VISIBLE_KEYS:
+                    hits.append(nested_path)
+                hits.extend(_find_banned_keys(nested, nested_path))
+            return tuple(hits)
+        case list():
+            hits = []
+            for index, nested in enumerate(value):
+                hits.extend(_find_banned_keys(nested, f"{path}[{index}]"))
+            return tuple(hits)
+        case str() | int() | float() | bool() | None:
+            return ()
+        case unreachable:
+            assert_never(unreachable)

package/src/ummaya/evidence/document_authoring_cases.py

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+DocumentAuthoringScenarioClass = Literal[
+    "public_form_completion",
+    "narrative_authoring",
+    "unsupported_plausible_writing",
+    "protected_field",
+    "direct_hwp_path",
+    "render_comparison",
+]
+DocumentAuthoringStatus = Literal["ready_for_review", "needs_input", "blocked"]
+DocumentHwpDirectWriteState = Literal["blocked", "promoted", "not_applicable"]
+
+
+class DocumentAuthoringCase(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    case_id: str
+    scenario_class: DocumentAuthoringScenarioClass
+    correlation_id: str
+    expected_status: DocumentAuthoringStatus
+    requires_socratic_loop: bool
+    requires_user_approval: bool
+    mutation_allowed: bool
+    render_comparison_required: bool
+    hwp_direct_write_state: DocumentHwpDirectWriteState = "not_applicable"
+    fixture_id: str | None = None
+    evidence_ref: str