ummaya 0.2.4 → 0.2.5

package/src/ummaya/tools/documents/validate.py

@@ -0,0 +1,347 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Public-form conformance validation for extracted document artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+from decimal import Decimal
+
+from ummaya.tools.documents.baselines import (
+    BaselineTableGeometry,
+    BaselineTextAnchor,
+    ConformanceBaseline,
+)
+from ummaya.tools.documents.models import (
+    BlockedReason,
+    DocumentExtraction,
+    DocumentToolResult,
+    PublicFormValidationReport,
+    ToolResultStatus,
+    ValidationDecision,
+    ValidationFinding,
+    ValidationReadiness,
+)
+from ummaya.tools.documents.scorecard import compute_public_form_metrics, table_shape
+
+
+def validate_public_form(
+    extraction: DocumentExtraction,
+    *,
+    baseline: ConformanceBaseline,
+    artifact_id: str,
+    correlation_id: str,
+    round_trip_passed: bool = True,
+    render_passed: bool = True,
+    security_passed: bool = True,
+) -> DocumentToolResult:
+    """Validate one extracted derivative against a public-form baseline."""
+    if not baseline.supports_conformance:
+        finding = _finding(
+            code="unsupported_for_conformance",
+            message=baseline.unsupported_reason or "Public-form conformance is not supported.",
+            anchor=f"template:{baseline.template_id}",
+            remediation_hint="Use a promoted editable format with conformance evidence.",
+        )
+        report = _report(
+            extraction,
+            baseline=baseline,
+            artifact_id=artifact_id,
+            findings=[finding],
+            decision=ValidationDecision.blocked,
+            readiness=ValidationReadiness.unsupported,
+            round_trip_passed=round_trip_passed,
+            render_passed=render_passed,
+            security_passed=security_passed,
+        )
+        return _result(
+            report,
+            status=ToolResultStatus.blocked,
+            blocked_reason=BlockedReason.unsupported_operation,
+            summary="Public-form validation blocked: conformance is unsupported.",
+            correlation_id=correlation_id,
+        )
+
+    findings = _hard_rule_findings(extraction, baseline)
+    if not security_passed:
+        findings.append(
+            _finding(
+                code="security_check_failed",
+                message="Security validation failed before public-form readiness.",
+                anchor=f"artifact:{artifact_id}",
+                remediation_hint="Resolve document security findings before validation.",
+            )
+        )
+    if not round_trip_passed:
+        findings.append(
+            _finding(
+                code="round_trip_mismatch",
+                message="Round-trip extraction did not match intended document values.",
+                anchor=f"artifact:{artifact_id}",
+                remediation_hint="Re-read the derivative and repair mismatched values.",
+            )
+        )
+    if not render_passed:
+        findings.append(
+            _finding(
+                code="render_mismatch",
+                message="Rendered derivative evidence did not match the expected layout.",
+                anchor=f"artifact:{artifact_id}",
+                remediation_hint="Repair layout drift and regenerate render evidence.",
+            )
+        )
+
+    metrics = compute_public_form_metrics(extraction, baseline)
+    hard_failure = any(finding.severity == "hard_failure" for finding in findings)
+    decision, readiness = _decision(
+        aggregate_score=metrics.aggregate_score,
+        hard_failure=hard_failure,
+        round_trip_passed=round_trip_passed,
+        render_passed=render_passed,
+        security_passed=security_passed,
+    )
+    report = _report(
+        extraction,
+        baseline=baseline,
+        artifact_id=artifact_id,
+        findings=findings,
+        decision=decision,
+        readiness=readiness,
+        round_trip_passed=round_trip_passed,
+        render_passed=render_passed,
+        security_passed=security_passed,
+    )
+    if decision is ValidationDecision.pass_:
+        return _result(
+            report,
+            status=ToolResultStatus.ok,
+            blocked_reason=None,
+            summary="Public-form validation passed; artifact is ready for human review.",
+            correlation_id=correlation_id,
+        )
+    blocked_reason = (
+        BlockedReason.unsupported_operation
+        if readiness is ValidationReadiness.unsupported
+        else BlockedReason.validation_failed
+    )
+    return _result(
+        report,
+        status=ToolResultStatus.blocked,
+        blocked_reason=blocked_reason,
+        summary="Public-form validation failed; artifact is not ready.",
+        correlation_id=correlation_id,
+    )
+
+
+def _hard_rule_findings(
+    extraction: DocumentExtraction,
+    baseline: ConformanceBaseline,
+) -> list[ValidationFinding]:
+    findings: list[ValidationFinding] = []
+    findings.extend(_required_field_findings(extraction, baseline))
+    findings.extend(
+        _required_text_findings(
+            extraction,
+            baseline.protected_text,
+            "protected_text_missing",
+        )
+    )
+    findings.extend(
+        _required_text_findings(
+            extraction,
+            baseline.required_labels,
+            "required_label_missing",
+        )
+    )
+    findings.extend(_table_geometry_findings(extraction, baseline.table_geometries))
+    findings.extend(
+        _required_text_findings(
+            extraction,
+            baseline.signature_regions,
+            "signature_or_seal_region_missing",
+        )
+    )
+    findings.extend(_metadata_findings(extraction, baseline))
+    return findings
+
+
+def _required_field_findings(
+    extraction: DocumentExtraction,
+    baseline: ConformanceBaseline,
+) -> list[ValidationFinding]:
+    by_field_id = {field.field_id: field for field in extraction.fields}
+    findings: list[ValidationFinding] = []
+    for required in baseline.required_fields:
+        observed = by_field_id.get(required.field_id)
+        if observed is None or observed.current_value in {None, ""}:
+            findings.append(
+                _finding(
+                    code="required_field_missing",
+                    message=f"Required field {required.label!r} is missing or empty.",
+                    anchor=required.path,
+                    remediation_hint=f"Fill the {required.label!r} field before export.",
+                )
+            )
+    return findings
+
+
+def _required_text_findings(
+    extraction: DocumentExtraction,
+    expected: tuple[BaselineTextAnchor, ...],
+    code: str,
+) -> list[ValidationFinding]:
+    observed_text = _combined_text(extraction)
+    findings: list[ValidationFinding] = []
+    for item in expected:
+        if item.text not in observed_text:
+            findings.append(
+                _finding(
+                    code=code,
+                    message=f"Required public-form text {item.text!r} is missing.",
+                    anchor=item.anchor,
+                    remediation_hint=f"Restore required text {item.text!r} at the baseline anchor.",
+                )
+            )
+    return findings
+
+
+def _table_geometry_findings(
+    extraction: DocumentExtraction,
+    expected: tuple[BaselineTableGeometry, ...],
+) -> list[ValidationFinding]:
+    tables_by_id = {table.block_id: table for table in extraction.tables}
+    findings: list[ValidationFinding] = []
+    for geometry in expected:
+        observed = tables_by_id.get(geometry.table_id)
+        observed_rows, observed_columns = table_shape(observed)
+        if observed_rows != geometry.rows or observed_columns != geometry.columns:
+            findings.append(
+                _finding(
+                    code="table_geometry_mismatch",
+                    message=(
+                        f"Table {geometry.table_id!r} shape is "
+                        f"{observed_rows}x{observed_columns}, expected "
+                        f"{geometry.rows}x{geometry.columns}."
+                    ),
+                    anchor=geometry.anchor,
+                    remediation_hint="Restore the protected table row and column geometry.",
+                )
+            )
+    return findings
+
+
+def _metadata_findings(
+    extraction: DocumentExtraction,
+    baseline: ConformanceBaseline,
+) -> list[ValidationFinding]:
+    findings: list[ValidationFinding] = []
+    expected_metadata = dict(baseline.metadata_exact_matches)
+    if baseline.expected_page_count is not None:
+        expected_metadata["page_count"] = baseline.expected_page_count
+    for key, expected in expected_metadata.items():
+        observed = extraction.metadata.get(key)
+        if observed != expected:
+            findings.append(
+                _finding(
+                    code="metadata_mismatch",
+                    message=f"Metadata {key!r} is {observed!r}, expected {expected!r}.",
+                    anchor=f"metadata:{key}",
+                    remediation_hint=f"Restore metadata {key!r} to the baseline value.",
+                )
+            )
+    return findings
+
+
+def _report(
+    extraction: DocumentExtraction,
+    *,
+    baseline: ConformanceBaseline,
+    artifact_id: str,
+    findings: list[ValidationFinding],
+    decision: ValidationDecision,
+    readiness: ValidationReadiness,
+    round_trip_passed: bool,
+    render_passed: bool,
+    security_passed: bool,
+) -> PublicFormValidationReport:
+    metrics = compute_public_form_metrics(extraction, baseline)
+    return PublicFormValidationReport(
+        report_id=f"validation-{artifact_id}-{baseline.template_id}",
+        artifact_id=artifact_id,
+        template_id=baseline.template_id,
+        schema_id=baseline.schema_id,
+        paragraph_block_f1=metrics.paragraph_block_f1,
+        table_cell_f1=metrics.table_cell_f1,
+        image_reference_f1=metrics.image_reference_f1,
+        metadata_exact_match=metrics.metadata_exact_match,
+        aggregate_score=metrics.aggregate_score,
+        round_trip_passed=round_trip_passed,
+        render_passed=render_passed,
+        security_passed=security_passed,
+        findings=findings,
+        decision=decision,
+        readiness=readiness,
+    )
+
+
+def _result(
+    report: PublicFormValidationReport,
+    *,
+    status: ToolResultStatus,
+    blocked_reason: BlockedReason | None,
+    summary: str,
+    correlation_id: str,
+) -> DocumentToolResult:
+    return DocumentToolResult(
+        tool_id="document_validate_public_form",
+        correlation_id=correlation_id,
+        status=status,
+        artifact_refs=[report.artifact_id],
+        validation_report=report,
+        findings=list(report.findings),
+        text_summary=summary,
+        blocked_reason=blocked_reason,
+    )
+
+
+def _decision(
+    *,
+    aggregate_score: Decimal,
+    hard_failure: bool,
+    round_trip_passed: bool,
+    render_passed: bool,
+    security_passed: bool,
+) -> tuple[ValidationDecision, ValidationReadiness]:
+    if not security_passed:
+        return ValidationDecision.blocked, ValidationReadiness.blocked
+    if hard_failure or not round_trip_passed or not render_passed:
+        if not round_trip_passed or not render_passed:
+            return ValidationDecision.needs_manual_review, ValidationReadiness.not_ready
+        return ValidationDecision.fail, ValidationReadiness.not_ready
+    if aggregate_score < Decimal("0.85"):
+        return ValidationDecision.fail, ValidationReadiness.not_ready
+    return ValidationDecision.pass_, ValidationReadiness.ready_for_review
+
+
+def _combined_text(extraction: DocumentExtraction) -> str:
+    parts = [paragraph.text for paragraph in extraction.paragraphs]
+    parts.extend(cell.text for table in extraction.tables for cell in table.cells)
+    parts.extend(field.label for field in extraction.fields)
+    return "\n".join(parts)
+
+
+def _finding(
+    *,
+    code: str,
+    message: str,
+    anchor: str,
+    remediation_hint: str,
+) -> ValidationFinding:
+    digest = hashlib.sha256(f"{code}\0{anchor}\0{message}".encode()).hexdigest()[:12]
+    return ValidationFinding(
+        finding_id=f"validation-{code}-{digest}",
+        severity="hard_failure",
+        code=code,
+        message=message,
+        anchor=anchor,
+        remediation_hint=remediation_hint,
+    )

package/src/ummaya/tools/executor.py

@@ -47,6 +47,7 @@ logger = logging.getLogger(__name__)
 _tracer = trace.get_tracer(__name__)
 
 AdapterFn = Callable[[BaseModel], Awaitable[dict[str, Any]]]
+SessionAwareAdapterFn = Callable[[BaseModel, object | None], Awaitable[dict[str, Any]]]
 
 _LOOKUP_ENVELOPE_KINDS: frozenset[str] = frozenset(
     {"record", "collection", "timeseries", "error", "search"}
@@ -195,6 +196,7 @@ class ToolExecutor:
         """
         self._registry = registry
         self._adapters: dict[str, AdapterFn] = {}
+        self._session_adapters: dict[str, SessionAwareAdapterFn] = {}
         self._recovery_executor = recovery_executor
         self._metrics: MetricsCollector | None = metrics
         self._event_logger: ObservabilityEventLogger | None = event_logger
@@ -211,6 +213,31 @@ class ToolExecutor:
         self._adapters[tool_id] = adapter
         logger.debug("Registered adapter for tool: %s", tool_id)
 
+    def register_session_adapter(self, tool_id: str, adapter: SessionAwareAdapterFn) -> None:
+        """Register an adapter that also receives the caller session identity."""
+
+        async def _without_session(inp: BaseModel) -> dict[str, Any]:
+            return await adapter(inp, None)
+
+        self._adapters[tool_id] = _without_session
+        self._session_adapters[tool_id] = adapter
+        logger.debug("Registered session-aware adapter for tool: %s", tool_id)
+
+    def _adapter_for_session(
+        self,
+        tool_id: str,
+        adapter: AdapterFn,
+        session_identity: object | None,
+    ) -> AdapterFn:
+        session_adapter = self._session_adapters.get(tool_id)
+        if session_adapter is None:
+            return adapter
+
+        async def _with_session(inp: BaseModel) -> dict[str, Any]:
+            return await session_adapter(inp, session_identity)
+
+        return _with_session
+
     async def invoke_raw(  # noqa: C901
         self,
         tool_id: str,
@@ -269,6 +296,7 @@ class ToolExecutor:
                 elapsed_ms=_elapsed(),
                 retryable=False,
             )
+        adapter = self._adapter_for_session(tool_id, adapter, session_identity)
 
         try:
             validated_input = tool.input_schema.model_validate(params)
@@ -458,6 +486,7 @@ class ToolExecutor:
                 elapsed_ms=_elapsed(),
                 retryable=False,
             )
+        adapter = self._adapter_for_session(tool_id, adapter, session_identity)
 
         # --- Input validation ---------------------------------------------------
         try:

package/src/ummaya/tools/live_proxy.py

@@ -117,14 +117,11 @@ async def invoke_live_adapter_proxy(
         )
 
     timeout = _configured_timeout(settings.live_adapter_proxy_timeout_seconds)
-    token = os.environ.get("UMMAYA_LIVE_ADAPTER_PROXY_TOKEN", settings.live_adapter_proxy_token)
     headers = {
         "Accept": "application/json",
         "Content-Type": "application/json",
         "User-Agent": f"UMMAYA/{get_version()} live-adapter-client",
     }
-    if token.strip():
-        headers["Authorization"] = f"Bearer {token.strip()}"
 
     payload: dict[str, object] = {
         "schema_version": "ummaya.live_adapter.v1",

package/src/ummaya/tools/models.py

@@ -31,6 +31,8 @@ _AUTH_TYPE_LEVEL_MAPPING: Final[dict[str, frozenset[str]]] = {
     "oauth": frozenset({"AAL1", "AAL2", "AAL3"}),
 }
 
+MockFidelityGrade = Literal["OPENAPI", "OOS", "HARNESS_ONLY", "unknown", "not_applicable"]
+
 # Spec 1634 (P3 Tool System Wiring) — closed ministry / institution enum.
 # Typed replacement for the former free-form ``provider: str`` field. New
 # institutions are added by enum extension (small dedicated PR, ADR not
@@ -215,8 +217,10 @@ class GovAPITool(BaseModel):
     ``mock`` = adapter returns recorded fixture or shape-compatible synthetic.
     Distinct from ``AdapterRegistration.source_mode`` (mirror fidelity axis)."""
 
+    mock_fidelity_grade: MockFidelityGrade = "not_applicable"
+
     # Spec 031 T032 dual-axis fields — None during pre-v1.2 compatibility window FR-028
-    primitive: Literal["find", "locate", "send", "check"] | None = None
+    primitive: Literal["find", "locate", "send", "check", "document"] | None = None
     """Active primitive surface this adapter binds to (Spec 031 AdapterPrimitive).
 
     Set to the appropriate value during Spec 031 Phase 4 (T033).

package/src/ummaya/tools/register_all.py

@@ -164,6 +164,14 @@ def register_all_tools(registry: ToolRegistry, executor: ToolExecutor) -> Routin
     reg_mock_hometax_simplified(registry, executor)  # T028 — Hometax simplified data
     reg_mock_gov24_cert(registry, executor)  # T029 — Gov24 certificate lookup
 
+    # Spec #2802 — Public AX document harness. These local tools expose
+    # inspect/extract/form-schema/copy/fill/style/render/validate/save through
+    # the existing ToolRegistry and permission gate; no external agency channel
+    # is called at registration time.
+    from ummaya.tools.documents.registry import register_document_tools
+
+    register_document_tools(registry, executor)
+
     # Epic ζ #2297 path B (live smoke 2026-04-30 follow-up) — bridge per-primitive
     # registries (verify/submit) into the main ToolRegistry's BM25 corpus
     # so `lookup(mode="search", query="…")` can surface verify/submit

package/src/ummaya/tools/registry.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 
 import logging
 from enum import StrEnum
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, computed_field, model_validator
 
@@ -32,6 +32,9 @@ from ummaya.tools.search import search_tools
 
 logger = logging.getLogger(__name__)
 
+if TYPE_CHECKING:
+    from ummaya.tools.routing.cards import AdapterCard
+
 
 # ---------------------------------------------------------------------------
 # Spec 031 Phase 2 — active primitive registry metadata (T007–T009).
@@ -49,6 +52,7 @@ class AdapterPrimitive(StrEnum):
     locate = "locate"
     send = "send"
     check = "check"
+    document = "document"
 
 
 class AdapterSourceMode(StrEnum):
@@ -387,6 +391,11 @@ class ToolRegistry:
         """Return non-core, active tools."""
         return [t for tid, t in self._tools.items() if not t.is_core and tid not in self._inactive]
 
+    def adapter_cards(self) -> list[AdapterCard]:
+        from ummaya.tools.routing.cards import build_adapter_cards
+
+        return list(build_adapter_cards(self.all_tools()))
+
     def export_core_tools_openai(self) -> list[dict[str, object]]:
         """Export core tools as OpenAI function-calling definitions.
 

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

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from ummaya.tools.routing.cards import (
+    AdapterCard,
+    AdapterCardError,
+    AdapterCardQualityViolation,
+    SchemaFieldSummary,
+    assert_adapter_card_quality,
+    build_adapter_card,
+    build_adapter_cards,
+    lint_adapter_card,
+)
+from ummaya.tools.routing.decision_service import RouteDecisionService
+from ummaya.tools.routing.decision_types import (
+    FeasibilityStatus,
+    RouteCandidate,
+    RouteClarificationDecision,
+    RouteClarificationReason,
+    RouteDecision,
+    RouteStopReason,
+    SchemaProjectionLevel,
+)
+from ummaya.tools.routing.intent import (
+    ACTIVE_PRIMITIVES,
+    LEGACY_PRIMITIVE_ALIASES,
+    ToolSelectionIntent,
+    extract_tool_selection_intent,
+)
+from ummaya.tools.routing.projection import (
+    AvailableAdaptersProjection,
+    build_available_adapters_projection,
+    selected_concrete_adapter_tools,
+)
+
+__all__ = [
+    "ACTIVE_PRIMITIVES",
+    "AdapterCard",
+    "AdapterCardError",
+    "AdapterCardQualityViolation",
+    "AvailableAdaptersProjection",
+    "FeasibilityStatus",
+    "LEGACY_PRIMITIVE_ALIASES",
+    "RouteCandidate",
+    "RouteClarificationDecision",
+    "RouteClarificationReason",
+    "RouteDecision",
+    "RouteStopReason",
+    "RouteDecisionService",
+    "SchemaFieldSummary",
+    "SchemaProjectionLevel",
+    "ToolSelectionIntent",
+    "assert_adapter_card_quality",
+    "build_adapter_card",
+    "build_adapter_cards",
+    "build_available_adapters_projection",
+    "extract_tool_selection_intent",
+    "lint_adapter_card",
+    "selected_concrete_adapter_tools",
+]

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

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ummaya.tools.models import GovAPITool
+from ummaya.tools.routing.metadata import (
+    capabilities_for_tool,
+    credential_requirements_for_tool,
+    domain_for_tool,
+    entity_types_for_tool,
+    examples_en_for_tool,
+    examples_ko_for_tool,
+    limitations_for_tool,
+    mock_fidelity_grade_for_tool,
+    prerequisite_tools_for_tool,
+    primitive_family,
+    routing_text,
+    safety_annotations_for_tool,
+    side_effect_level_for_tool,
+    source_mode_for_tool,
+)
+from ummaya.tools.routing.schema import model_json_schema, schema_summary, sha256
+from ummaya.tools.routing.types import (
+    INTENT_VERBS,
+    LEGACY_ALIASES,
+    AdapterCard,
+)
+
+
+def build_adapter_cards(tools: Iterable[GovAPITool]) -> tuple[AdapterCard, ...]:
+    return tuple(build_adapter_card(tool) for tool in sorted(tools, key=lambda item: item.id))
+
+
+def build_adapter_card(tool: GovAPITool) -> AdapterCard:
+    primitive = primitive_family(tool.primitive)
+    input_schema = model_json_schema(tool.input_schema)
+    output_schema = model_json_schema(tool.output_schema)
+    input_summary = schema_summary(input_schema)
+    output_summary = schema_summary(output_schema)
+    required_slots = tuple(field.name for field in input_summary if field.required)
+    optional_slots = tuple(field.name for field in input_summary if not field.required)
+    source_mode = source_mode_for_tool(tool)
+    policy_authority_url = tool.policy.real_classification_url if tool.policy is not None else None
+    side_effect_level = side_effect_level_for_tool(tool, primitive)
+    credential_requirements = credential_requirements_for_tool(tool)
+    capabilities = capabilities_for_tool(tool, primitive)
+    entity_types = entity_types_for_tool(input_summary, tool.category)
+    prerequisite_tools = prerequisite_tools_for_tool(tool, primitive)
+    input_schema_hash = sha256(input_schema)
+    manifest_hash = sha256(
+        {
+            "tool_id": tool.id,
+            "primitive_family": primitive,
+            "agency": str(tool.ministry),
+            "source_mode": source_mode,
+            "policy_authority_url": policy_authority_url,
+            "input_schema_hash": input_schema_hash,
+            "output_schema_hash": sha256(output_schema),
+        }
+    )
+    examples_ko = examples_ko_for_tool(tool)
+    examples_en = examples_en_for_tool(tool, primitive)
+    negative_examples = (f"Do not use for requests outside primitive {primitive}.",)
+    limitations = limitations_for_tool(tool, source_mode, policy_authority_url)
+    safety_annotations = safety_annotations_for_tool(tool, side_effect_level)
+
+    return AdapterCard(
+        tool_id=tool.id,
+        primitive_family=primitive,
+        legacy_primitive_aliases=LEGACY_ALIASES[primitive],
+        domain=domain_for_tool(tool),
+        agency=str(tool.ministry),
+        source_mode=source_mode,
+        capabilities=capabilities,
+        intent_verbs=INTENT_VERBS[primitive],
+        entity_types=entity_types,
+        required_slots=required_slots,
+        optional_slots=optional_slots,
+        prerequisite_tools=prerequisite_tools,
+        input_schema_hash=input_schema_hash,
+        input_schema_summary=input_summary,
+        output_schema_summary=output_summary,
+        policy_authority_url=policy_authority_url,
+        safety_annotations=safety_annotations,
+        side_effect_level=side_effect_level,
+        credential_requirements=credential_requirements,
+        mock_fidelity_grade=mock_fidelity_grade_for_tool(tool),
+        examples_ko=examples_ko,
+        examples_en=examples_en,
+        negative_examples=negative_examples,
+        limitations=limitations,
+        manifest_hash=manifest_hash,
+        routing_text=routing_text(
+            tool_id=tool.id,
+            primitive=primitive,
+            agency=str(tool.ministry),
+            domain=domain_for_tool(tool),
+            capabilities=capabilities,
+            required_slots=required_slots,
+            examples_ko=examples_ko,
+            limitations=limitations,
+        ),
+    )

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

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from ummaya.tools.routing.builder import build_adapter_card, build_adapter_cards
+from ummaya.tools.routing.lint import assert_adapter_card_quality, lint_adapter_card
+from ummaya.tools.routing.types import (
+    AdapterCard,
+    AdapterCardError,
+    AdapterCardQualityViolation,
+    PrimitiveFamily,
+    SchemaFieldSummary,
+    SideEffectLevel,
+    SourceMode,
+)
+
+__all__ = [
+    "AdapterCard",
+    "AdapterCardError",
+    "AdapterCardQualityViolation",
+    "PrimitiveFamily",
+    "SchemaFieldSummary",
+    "SideEffectLevel",
+    "SourceMode",
+    "assert_adapter_card_quality",
+    "build_adapter_card",
+    "build_adapter_cards",
+    "lint_adapter_card",
+]