ummaya 0.2.4 → 0.2.5

package/src/ummaya/llm/client.py

@@ -12,6 +12,7 @@ import random
 import time
 from collections.abc import AsyncIterator, Iterator
 from contextvars import Token
+from copy import deepcopy
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, cast
 
@@ -168,6 +169,62 @@ def _compute_prompt_hash(system_text: str) -> str:
     return hashlib.sha256(hashed.encode("utf-8")).hexdigest()
 
 
+def _provider_safe_parameters_schema(schema: dict[str, object]) -> dict[str, object]:
+    """Inline Pydantic-local JSON Schema refs before sending tool schemas."""
+    root = deepcopy(schema)
+    defs_obj = root.get("$defs")
+    defs: dict[str, object] = {}
+    if isinstance(defs_obj, dict):
+        defs = {str(name): value for name, value in defs_obj.items()}
+
+    inlined = _inline_local_json_schema_refs(root, defs, ())
+    if not isinstance(inlined, dict):
+        raise ValueError("OpenAI tool parameters schema must be a JSON object")
+    return cast(dict[str, object], inlined)
+
+
+def _inline_local_json_schema_refs(
+    node: object,
+    defs: dict[str, object],
+    stack: tuple[str, ...],
+) -> object:
+    if isinstance(node, list):
+        return [_inline_local_json_schema_refs(item, defs, stack) for item in node]
+    if not isinstance(node, dict):
+        return node
+
+    ref_name = _local_def_ref_name(node.get("$ref"))
+    if ref_name is not None:
+        if ref_name in stack:
+            raise ValueError(f"Cyclic JSON Schema reference is not supported: #/$defs/{ref_name}")
+        if ref_name not in defs:
+            raise ValueError(f"Unknown JSON Schema reference: #/$defs/{ref_name}")
+
+        target = deepcopy(defs[ref_name])
+        expanded = _inline_local_json_schema_refs(target, defs, (*stack, ref_name))
+        siblings = {str(key): value for key, value in node.items() if key not in {"$ref", "$defs"}}
+        if not siblings:
+            return expanded
+        if not isinstance(expanded, dict):
+            raise ValueError(f"JSON Schema reference target must be an object: #/$defs/{ref_name}")
+        merged = cast(dict[str, object], expanded).copy()
+        for key, value in siblings.items():
+            merged[key] = _inline_local_json_schema_refs(value, defs, stack)
+        return merged
+
+    return {
+        str(key): _inline_local_json_schema_refs(value, defs, stack)
+        for key, value in node.items()
+        if key != "$defs"
+    }
+
+
+def _local_def_ref_name(ref: object) -> str | None:
+    if not isinstance(ref, str) or not ref.startswith("#/$defs/"):
+        return None
+    return ref.removeprefix("#/$defs/").replace("~1", "/").replace("~0", "~")
+
+
 class LLMClient:
     """Async LLM client for FriendliAI Serverless endpoint."""
 
@@ -576,7 +633,38 @@ class LLMClient:
 
                         # Yield events; watch for mid-stream 429 envelopes (T016)
                         rate_limited_mid_stream = False
-                        async for line in response.aiter_lines():
+                        line_iter = response.aiter_lines()
+                        next_data_line_deadline = (
+                            time.monotonic() + self._config.stream_idle_timeout
+                        )
+                        while True:
+                            try:
+                                timeout_remaining = next_data_line_deadline - time.monotonic()
+                                if timeout_remaining <= 0:
+                                    raise TimeoutError
+                                line = await asyncio.wait_for(
+                                    anext(line_iter),
+                                    timeout=timeout_remaining,
+                                )
+                            except StopAsyncIteration:
+                                break
+                            except TimeoutError as exc:
+                                _duration_ms = (time.monotonic() - _stream_start) * 1000
+                                self._metrics_record_call(
+                                    success=False,
+                                    duration_ms=_duration_ms,
+                                )
+                                _metrics_recorded = True
+                                raise StreamInterruptedError(
+                                    "Stream idle timeout after "
+                                    f"{self._config.stream_idle_timeout:g}s "
+                                    "without a new SSE data line"
+                                ) from exc
+                            if not line.startswith("data: "):
+                                continue
+                            next_data_line_deadline = (
+                                time.monotonic() + self._config.stream_idle_timeout
+                            )
                             if self._is_rate_limit_envelope(line):
                                 rate_limited_mid_stream = True
                                 delay = self._compute_rate_limit_delay(response, attempt, policy)
@@ -1104,8 +1192,19 @@ class LLMClient:
         reaches FriendliAI's strict OpenAI-compatible validator.
         """
         if isinstance(tool, ToolDefinition):
-            return cast(dict[str, object], tool.model_dump())
-        return cast(dict[str, object], ToolDefinition.model_validate(tool).model_dump())
+            payload = cast(dict[str, object], tool.model_dump())
+        else:
+            payload = cast(dict[str, object], ToolDefinition.model_validate(tool).model_dump())
+
+        function_obj = payload.get("function")
+        if isinstance(function_obj, dict):
+            function = cast(dict[str, object], function_obj)
+            parameters_obj = function.get("parameters")
+            if isinstance(parameters_obj, dict):
+                function["parameters"] = _provider_safe_parameters_schema(
+                    cast(dict[str, object], parameters_obj)
+                )
+        return payload
 
     # ------------------------------------------------------------------
     # Private retry helpers (T015)

package/src/ummaya/llm/config.py

@@ -16,6 +16,7 @@ class LLMClientConfig(BaseSettings):
         UMMAYA_FRIENDLI_MODEL       — model identifier
         UMMAYA_LLM_SESSION_BUDGET   — per-session token budget
         UMMAYA_LLM_TIMEOUT_SECONDS  — HTTP stream timeout budget
+        UMMAYA_LLM_STREAM_IDLE_TIMEOUT_SECONDS — max idle gap between stream lines
     """
 
     model_config = SettingsConfigDict(
@@ -59,6 +60,11 @@ class LLMClientConfig(BaseSettings):
         ),
         description="HTTP request timeout in seconds.",
     )
+    stream_idle_timeout: float = Field(
+        default=90.0,
+        validation_alias="UMMAYA_LLM_STREAM_IDLE_TIMEOUT_SECONDS",
+        description="Maximum idle time between streaming response lines in seconds.",
+    )
     max_retries: int = Field(
         default=3,
         description="Maximum number of retry attempts on transient failures.",
@@ -80,12 +86,11 @@ class LLMClientConfig(BaseSettings):
             raise ValueError("session_budget must be > 0")
         return value
 
-    @field_validator("timeout")
+    @field_validator("timeout", "stream_idle_timeout")
     @classmethod
     def timeout_must_be_positive(cls, value: float) -> float:
-        """Enforce timeout > 0."""
         if value <= 0:
-            raise ValueError("timeout must be > 0")
+            raise ValueError("timeout values must be > 0")
         return value
 
     @field_validator("max_retries")

package/src/ummaya/primitives/__init__.py

@@ -7,6 +7,7 @@ Exports the active primitive symbols that make up the main-tool surface:
 - ``locate``: geocoding (re-exported from Spec 022).
 - ``send``: write-transaction absorber (Spec 031 US1, T024).
 - ``check``: delegation-only identity binding (Spec 031 US2, T042).
+- ``document``: local public-document authoring and review harness.
 
 ``subscribe`` is intentionally not part of the active surface. National alert
 and notice subscriptions are app/phone push-notification concerns, not a CLI
@@ -18,6 +19,7 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import Any
 
+from ummaya.primitives.document import document
 from ummaya.primitives.submit import send
 from ummaya.primitives.verify import check
 from ummaya.tools.lookup import find
@@ -46,6 +48,7 @@ PRIMITIVE_REGISTRY: dict[str, Callable[..., Any]] = {
     "locate": locate,
     "send": send,
     "check": check,
+    "document": document,
 }
 
 # Subset of ``PRIMITIVE_REGISTRY`` whose invocation requires a Spec 033
@@ -64,9 +67,9 @@ PRIMITIVE_REGISTRY: dict[str, Callable[..., Any]] = {
 #
 # The complement (``PRIMITIVE_REGISTRY.keys() - GATED_PRIMITIVES``) is the
 # fully auto-allowed set: find / locate.
-GATED_PRIMITIVES: frozenset[str] = frozenset({"check", "send"})
+GATED_PRIMITIVES: frozenset[str] = frozenset({"check", "send", "document"})
 LIGHT_GATE_PRIMITIVES: frozenset[str] = frozenset({"check"})
-HEAVY_GATE_PRIMITIVES: frozenset[str] = frozenset({"send"})
+HEAVY_GATE_PRIMITIVES: frozenset[str] = frozenset({"send", "document"})
 
 # ``__all__`` enumerates the LLM-visible primitive *surface* — the active root
 # verbs. The metadata constants ``PRIMITIVE_REGISTRY``
@@ -77,6 +80,7 @@ __all__ = [
     "locate",
     "send",
     "check",
+    "document",
 ]
 # Metadata constants (GATED_PRIMITIVES / LIGHT_GATE_PRIMITIVES /
 # HEAVY_GATE_PRIMITIVES / PRIMITIVE_REGISTRY) are intentionally NOT in __all__

package/src/ummaya/primitives/delegation.py

@@ -36,7 +36,7 @@ logger = logging.getLogger(__name__)
 # Accepts single-scope strings AND comma-joined multi-scope strings for US1.
 # ---------------------------------------------------------------------------
 
-_SCOPE_VERBS = r"find|locate|send|check|lookup|resolve_location|submit|verify"
+_SCOPE_VERBS = r"find|locate|send|check|document|lookup|resolve_location|submit|verify"
 
 _SINGLE_SCOPE_PATTERN: re.Pattern[str] = re.compile(rf"^({_SCOPE_VERBS}):[a-z0-9_]+\.[a-z0-9_-]+$")
 

package/src/ummaya/primitives/document.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Document primitive placeholder.
+
+The model-facing `document` tool is registered as a concrete GovAPITool by the
+document harness. This coroutine exists so primitive registries and IPC guards
+can identify `document` as an allowed top-level primitive name.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+async def document(*_args: object, **_kwargs: object) -> dict[str, Any]:
+    """Document primitive marker.
+
+    Runtime execution is owned by `ummaya.tools.documents.registry` because it
+    needs session-local artifact stores and format-engine adapters.
+    """
+
+    return {
+        "kind": "error",
+        "reason": "direct_document_primitive_not_bound",
+        "message": "The document primitive must be executed through the registered document tool.",
+    }
+
+
+__all__ = ["document"]

package/src/ummaya/settings.py

@@ -104,9 +104,6 @@ class UmmayaSettings(BaseSettings):
     live_adapter_proxy_timeout_seconds: float = Field(default=30.0, gt=0)
     """HTTP timeout for operator-managed live adapter proxy calls."""
 
-    live_adapter_proxy_token: str = Field(default="")
-    """Optional bearer token for private/self-hosted live adapter gateways."""
-
     live_adapter_gateway_token: str = Field(default="")
     """Optional bearer token required by the hosted live adapter gateway server."""
 

package/src/ummaya/tools/discovery_bridge.py

@@ -34,7 +34,7 @@ from typing import TYPE_CHECKING, Any
 
 from pydantic import BaseModel, ConfigDict, Field, RootModel
 
-from ummaya.tools.models import AdapterRealDomainPolicy, GovAPITool
+from ummaya.tools.models import AdapterRealDomainPolicy, GovAPITool, MockFidelityGrade
 
 if TYPE_CHECKING:
     from ummaya.tools.registry import ToolRegistry
@@ -346,6 +346,7 @@ def _verify_to_govapitool(entry: dict[str, Any]) -> GovAPITool:
         rate_limit_per_minute=30,
         is_core=False,  # Discoverable via lookup search; NOT in primary LLM tool list
         primitive="check",
+        adapter_mode="mock",
     )
 
 
@@ -385,9 +386,24 @@ def _submit_to_govapitool(
         rate_limit_per_minute=registration.rate_limit_per_minute,
         is_core=False,  # Discoverable via lookup search; NOT in primary LLM tool list
         primitive="send",
+        adapter_mode="mock",
+        mock_fidelity_grade=_mock_fidelity_from_source_mode(registration.source_mode),
     )
 
 
+def _mock_fidelity_from_source_mode(source_mode: object) -> MockFidelityGrade:
+    raw = str(getattr(source_mode, "value", source_mode))
+    match raw:
+        case "OPENAPI":
+            return "OPENAPI"
+        case "OOS":
+            return "OOS"
+        case "harness-only" | "HARNESS_ONLY":
+            return "HARNESS_ONLY"
+        case _:
+            return "unknown"
+
+
 # ---------------------------------------------------------------------------
 # Public entry point
 # ---------------------------------------------------------------------------

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

@@ -0,0 +1,297 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Public AX document harness package."""
+
+from ummaya.tools.documents.adapter_registry import (
+    DocumentAdapterRegistry,
+    EngineBackedDocumentAdapter,
+    UnsupportedDocumentAdapterError,
+    build_default_document_adapter_registry,
+    build_document_adapter_registry_from_engine_registry,
+)
+from ummaya.tools.documents.artifact_store import (
+    ArtifactStoreConflictError,
+    ArtifactStoreError,
+    ArtifactStoreSecurityError,
+    DocumentArtifactStore,
+)
+from ummaya.tools.documents.baselines import (
+    CONFORMANCE_BASELINE_FIXTURE_PATH,
+    BaselineField,
+    BaselineTableGeometry,
+    BaselineTextAnchor,
+    ConformanceBaseline,
+    ConformanceBaselineCatalog,
+    load_conformance_baselines,
+)
+from ummaya.tools.documents.capability import (
+    FormatCapabilityProfile as CandidateCapabilityProfile,
+)
+from ummaya.tools.documents.capability import (
+    PromotionDecision,
+    PromotionDecisionManifest,
+    PromotionDecisionRecord,
+    build_inspection_read_profile,
+    evaluate_capability_promotion,
+    load_promotion_decision_manifest,
+    persist_promotion_decision_manifest,
+)
+from ummaya.tools.documents.contracts import (
+    DocumentToolContract,
+    DocumentToolContractCatalog,
+    load_document_tool_contracts,
+)
+from ummaya.tools.documents.diff import DocumentChange, DocumentDiff, RenderArtifactRecord
+from ummaya.tools.documents.engines import (
+    DocumentEngineRegistry,
+    DocumentInspectionEngine,
+    DocumentMutationEngine,
+    UnsupportedDocumentEngineError,
+    build_default_document_engine_registry,
+)
+from ummaya.tools.documents.fixtures import (
+    DocumentFixtureManifest,
+    load_fixture_manifest,
+)
+from ummaya.tools.documents.formats.base import DocumentFormatAdapter
+from ummaya.tools.documents.inspection import inspect_document
+from ummaya.tools.documents.intake import (
+    DocumentIntakePolicy,
+    inspect_document_intake,
+)
+from ummaya.tools.documents.models import (
+    KNOWN_DOCUMENT_FORMAT_FAMILIES,
+    PROMOTED_RUNTIME_DOCUMENT_FORMATS,
+    ArtifactLineage,
+    AutonomousFillPlan,
+    AutonomousSaveIntent,
+    AutonomousStyleIntent,
+    BlockedReason,
+    DocumentArtifact,
+    DocumentChangedViewport,
+    DocumentClipRect,
+    DocumentExtraction,
+    DocumentFormat,
+    DocumentFormatFamily,
+    DocumentIntakeResult,
+    DocumentIntent,
+    DocumentIR,
+    DocumentPatch,
+    DocumentPatchOperation,
+    DocumentProtectedRange,
+    DocumentSavedExport,
+    DocumentSecurityFinding,
+    DocumentToolCall,
+    DocumentToolResult,
+    DocumentViewportCamera,
+    FormatCapabilityProfile,
+    FormField,
+    FormSlot,
+    KnownDocumentFormat,
+    OperationType,
+    PermissionState,
+    PrimitiveName,
+    PromotionCapability,
+    PromotionGateResult,
+    PromotionState,
+    ProtectedRangeCategory,
+    PublicFormValidationReport,
+    SecurityState,
+    SourceAnchor,
+    StyleDescriptor,
+    ToolResultStatus,
+    ValidationDecision,
+    ValidationFinding,
+    ValidationReadiness,
+)
+from ummaya.tools.documents.orchestrator import (
+    DocumentInspectionOrchestrator,
+    DocumentOrchestrator,
+)
+from ummaya.tools.documents.patch import (
+    DocumentPatchResult,
+    apply_document_patch,
+    copy_for_edit,
+)
+from ummaya.tools.documents.permissions import (
+    DocumentArtifactPermissionKind,
+    DocumentArtifactPermissionPayload,
+    build_document_artifact_permission,
+    document_permission_denied_result,
+)
+from ummaya.tools.documents.planner import plan_autonomous_fill, public_document_writing_profile
+from ummaya.tools.documents.registry import (
+    DOCUMENT_TOOL_IDS,
+    DocumentToolRuntime,
+    register_document_tools,
+)
+from ummaya.tools.documents.render import (
+    DocumentRenderResult,
+    render_document_evidence,
+)
+from ummaya.tools.documents.reread import (
+    DocumentReReadResult,
+    ReReadMismatch,
+    reread_derivative,
+)
+from ummaya.tools.documents.scorecard import (
+    CapabilityScorecard,
+    PublicFormMetricScore,
+    compute_public_form_metrics,
+)
+from ummaya.tools.documents.style import (
+    DocumentPatchValidationError,
+    validate_document_patch,
+)
+from ummaya.tools.documents.tool_defs import (
+    DocumentApplyFillRequest,
+    DocumentApplyStyleRequest,
+    DocumentCopyForEditRequest,
+    DocumentExtractionResult,
+    DocumentExtractRequest,
+    DocumentFieldPatch,
+    DocumentFormSchemaRequest,
+    DocumentInspectRequest,
+    DocumentInspectResult,
+    DocumentLocator,
+    DocumentMutationResult,
+    DocumentRenderRequest,
+    DocumentSaveRequest,
+    DocumentStylePatch,
+    DocumentValidatePublicFormRequest,
+    DocumentValidationResult,
+    build_document_tool_definitions,
+    needs_input_document_tool_result,
+    unsupported_document_tool_result,
+)
+from ummaya.tools.documents.validate import validate_public_form
+
+__all__ = [
+    "DOCUMENT_TOOL_IDS",
+    "ArtifactLineage",
+    "ArtifactStoreConflictError",
+    "ArtifactStoreError",
+    "ArtifactStoreSecurityError",
+    "AutonomousFillPlan",
+    "AutonomousSaveIntent",
+    "AutonomousStyleIntent",
+    "BlockedReason",
+    "BaselineField",
+    "BaselineTableGeometry",
+    "BaselineTextAnchor",
+    "CONFORMANCE_BASELINE_FIXTURE_PATH",
+    "CandidateCapabilityProfile",
+    "CapabilityScorecard",
+    "ConformanceBaseline",
+    "ConformanceBaselineCatalog",
+    "DocumentArtifact",
+    "DocumentArtifactPermissionKind",
+    "DocumentArtifactPermissionPayload",
+    "DocumentArtifactStore",
+    "DocumentAdapterRegistry",
+    "DocumentApplyFillRequest",
+    "DocumentApplyStyleRequest",
+    "DocumentChangedViewport",
+    "DocumentClipRect",
+    "DocumentCopyForEditRequest",
+    "DocumentEngineRegistry",
+    "DocumentExtractRequest",
+    "DocumentExtraction",
+    "DocumentExtractionResult",
+    "DocumentFieldPatch",
+    "DocumentFixtureManifest",
+    "DocumentFormat",
+    "DocumentFormatAdapter",
+    "DocumentFormatFamily",
+    "DocumentIR",
+    "DocumentFormSchemaRequest",
+    "DocumentIntakePolicy",
+    "DocumentIntakeResult",
+    "DocumentIntent",
+    "DocumentInspectRequest",
+    "DocumentInspectResult",
+    "DocumentInspectionEngine",
+    "DocumentInspectionOrchestrator",
+    "DocumentLocator",
+    "DocumentMutationEngine",
+    "DocumentMutationResult",
+    "DocumentOrchestrator",
+    "DocumentPatch",
+    "DocumentPatchResult",
+    "DocumentPatchOperation",
+    "DocumentPatchValidationError",
+    "DocumentProtectedRange",
+    "DocumentReReadResult",
+    "DocumentRenderResult",
+    "DocumentRenderRequest",
+    "DocumentSaveRequest",
+    "DocumentSavedExport",
+    "DocumentSecurityFinding",
+    "DocumentStylePatch",
+    "DocumentToolCall",
+    "DocumentToolContract",
+    "DocumentToolContractCatalog",
+    "DocumentToolResult",
+    "DocumentToolRuntime",
+    "DocumentViewportCamera",
+    "DocumentValidationResult",
+    "DocumentValidatePublicFormRequest",
+    "DocumentChange",
+    "DocumentDiff",
+    "EngineBackedDocumentAdapter",
+    "FormatCapabilityProfile",
+    "FormField",
+    "FormSlot",
+    "KNOWN_DOCUMENT_FORMAT_FAMILIES",
+    "KnownDocumentFormat",
+    "OperationType",
+    "PermissionState",
+    "PrimitiveName",
+    "ProtectedRangeCategory",
+    "PROMOTED_RUNTIME_DOCUMENT_FORMATS",
+    "PromotionCapability",
+    "PromotionDecision",
+    "PromotionDecisionManifest",
+    "PromotionDecisionRecord",
+    "PromotionGateResult",
+    "PromotionState",
+    "PublicFormValidationReport",
+    "PublicFormMetricScore",
+    "ReReadMismatch",
+    "RenderArtifactRecord",
+    "SecurityState",
+    "SourceAnchor",
+    "StyleDescriptor",
+    "ToolResultStatus",
+    "UnsupportedDocumentAdapterError",
+    "UnsupportedDocumentEngineError",
+    "build_document_adapter_registry_from_engine_registry",
+    "build_default_document_adapter_registry",
+    "build_default_document_engine_registry",
+    "ValidationDecision",
+    "ValidationFinding",
+    "ValidationReadiness",
+    "apply_document_patch",
+    "build_document_artifact_permission",
+    "build_document_tool_definitions",
+    "build_inspection_read_profile",
+    "copy_for_edit",
+    "compute_public_form_metrics",
+    "document_permission_denied_result",
+    "evaluate_capability_promotion",
+    "inspect_document_intake",
+    "inspect_document",
+    "load_document_tool_contracts",
+    "load_fixture_manifest",
+    "load_conformance_baselines",
+    "load_promotion_decision_manifest",
+    "needs_input_document_tool_result",
+    "plan_autonomous_fill",
+    "public_document_writing_profile",
+    "persist_promotion_decision_manifest",
+    "register_document_tools",
+    "render_document_evidence",
+    "reread_derivative",
+    "unsupported_document_tool_result",
+    "validate_document_patch",
+    "validate_public_form",
+]