loopx 0.4.8__py3-none-any.whl

loopx/capabilities/periodic_report/extension_envelope.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ...extensions.execution_envelope import (
+    build_extension_execution_envelope,
+    validate_extension_execution_envelope,
+)
+
+
+PERIODIC_REPORT_CAPABILITY_ID = "periodic-report"
+OPENVIKING_PERIODIC_REPORT_EXTENSION_ID = "openviking-periodic-report"
+OPENVIKING_PERIODIC_REPORT_PERMISSION = "openviking_context_write"
+PERIODIC_REPORT_SINK_PROTOCOL = "periodic_report_sink_v0"
+OPENVIKING_PERIODIC_REPORT_ACTION = "report.archive.write"
+
+
+def _effect_scope(request: Mapping[str, Any]) -> dict[str, str]:
+    context = request.get("context")
+    if not isinstance(context, Mapping):
+        raise ValueError("request.context must be an object")
+    scope = {
+        "sink_id": str(context.get("sink_id") or "").strip(),
+        "archive_root_uri": str(context.get("archive_root_uri") or "").strip(),
+        "idempotency_key": str(context.get("idempotency_key") or "").strip(),
+    }
+    missing = [key for key, value in scope.items() if not value]
+    if missing:
+        raise ValueError(f"extension execution scope is missing {missing}")
+    return scope
+
+
+def build_openviking_archive_execution_envelope(
+    request: Mapping[str, Any],
+    *,
+    extension_revision: str,
+) -> dict[str, Any]:
+    envelope = build_extension_execution_envelope(
+        action=OPENVIKING_PERIODIC_REPORT_ACTION,
+        scope=_effect_scope(request),
+        extension_id=OPENVIKING_PERIODIC_REPORT_EXTENSION_ID,
+        extension_revision=extension_revision,
+        request=request,
+    )
+    return validate_openviking_archive_execution_envelope(
+        envelope,
+        request=request,
+        extension_revision=extension_revision,
+    )
+
+
+def validate_openviking_archive_execution_envelope(
+    raw: Mapping[str, Any],
+    *,
+    request: Mapping[str, Any],
+    extension_revision: str,
+) -> dict[str, Any]:
+    return validate_extension_execution_envelope(
+        raw,
+        action=OPENVIKING_PERIODIC_REPORT_ACTION,
+        scope=_effect_scope(request),
+        extension_id=OPENVIKING_PERIODIC_REPORT_EXTENSION_ID,
+        extension_revision=extension_revision,
+        request=request,
+    )

loopx/capabilities/periodic_report/presets.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from .profile import (
+    build_periodic_report_activation,
+    normalize_periodic_report_profile,
+)
+from .project_progress import (
+    PROJECT_PROGRESS_ADAPTER_ID,
+    PROJECT_PROGRESS_SOURCE_ID,
+    PROJECT_PROGRESS_SOURCE_KIND,
+)
+
+
+WEEKLY_PROGRESS_PRESET_ID = "weekly-progress"
+PERIODIC_REPORT_PROFILE_PRESET_IDS = (WEEKLY_PROGRESS_PRESET_ID,)
+PERIODIC_REPORT_PROFILE_PRESET_ALIASES = {
+    "weekly": WEEKLY_PROGRESS_PRESET_ID,
+    "weekly-progress": WEEKLY_PROGRESS_PRESET_ID,
+    "weekly-report": WEEKLY_PROGRESS_PRESET_ID,
+}
+
+_WEEKLY_PROGRESS_PROFILE: dict[str, Any] = {
+    "schema_version": "periodic_report_profile_v0",
+    "enabled": True,
+    "profile_id": "weekly_progress",
+    "profile_version": "v1",
+    "trigger_policy": {
+        "enabled_kinds": [
+            "manual",
+            "cadence_due",
+            "primary_goal_outcome",
+            "vision_closed",
+            "material_decision",
+            "material_blocker",
+            "material_recovery",
+        ],
+        "minimum_interval_seconds": 0,
+    },
+    "source_bindings": [
+        {
+            "source_id": PROJECT_PROGRESS_SOURCE_ID,
+            "source_kind": PROJECT_PROGRESS_SOURCE_KIND,
+            "adapter_id": PROJECT_PROGRESS_ADAPTER_ID,
+            "provider": {"kind": "builtin"},
+        }
+    ],
+    "renderer_bindings": [
+        {
+            "renderer_id": "html",
+            "renderer_kind": "html",
+            "adapter_id": "html_artifact_v0",
+            "provider": {"kind": "builtin"},
+        },
+        {
+            "renderer_id": "markdown",
+            "renderer_kind": "markdown",
+            "adapter_id": "markdown_v0",
+            "provider": {"kind": "builtin"},
+        },
+    ],
+    "sink_bindings": [],
+}
+
+
+def resolve_periodic_report_profile_preset(preset_id: str) -> dict[str, Any]:
+    """Resolve a short user-facing alias into one normalized built-in profile."""
+
+    requested = str(preset_id or "").strip().lower().replace("_", "-")
+    canonical = PERIODIC_REPORT_PROFILE_PRESET_ALIASES.get(requested)
+    if canonical != WEEKLY_PROGRESS_PRESET_ID:
+        supported = ", ".join(PERIODIC_REPORT_PROFILE_PRESET_IDS)
+        raise ValueError(
+            f"unknown periodic report profile preset {preset_id!r}; "
+            f"supported presets: {supported}"
+        )
+    return normalize_periodic_report_profile(deepcopy(_WEEKLY_PROGRESS_PROFILE))
+
+
+def build_periodic_report_preset_activation(preset_id: str) -> dict[str, Any]:
+    """Return an agent-readable activation packet for one built-in preset."""
+
+    requested = str(preset_id or "").strip().lower().replace("_", "-")
+    profile = resolve_periodic_report_profile_preset(requested)
+    activation = build_periodic_report_activation(profile)
+    activation["profile_preset"] = {
+        "requested_id": requested,
+        "resolved_id": WEEKLY_PROGRESS_PRESET_ID,
+        "aliases": sorted(PERIODIC_REPORT_PROFILE_PRESET_ALIASES),
+    }
+    activation["interaction_contract"] = {
+        "mode": "in_session_local_preview",
+        "explicit_user_request_sufficient": True,
+        "project_profile_file_required": False,
+        "automation_required": False,
+        "schedule_created": False,
+        "source_scope": "current_project_public_safe_loopx_state",
+        "renderer_adapter_ids": ["markdown_v0", "html_artifact_v0"],
+        "external_write_allowed": False,
+    }
+    return activation

loopx/capabilities/periodic_report/profile.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from .bindings import (
+    _boolean,
+    _mapping,
+    _sequence,
+    _sha256,
+    _text,
+    _token,
+    _version,
+    normalize_periodic_report_sink_bindings,
+)
+from .core import _reject_raw_keys
+from .triggers import normalize_periodic_report_trigger_policy
+
+
+PROFILE_SCHEMA = "periodic_report_profile_v0"
+ACTIVATION_SCHEMA = "periodic_report_activation_v0"
+SOURCE_BINDING_SCHEMA = "periodic_report_source_binding_v0"
+RENDERER_BINDING_SCHEMA = "periodic_report_renderer_binding_v0"
+SCHEDULE_SCHEMA = "periodic_report_schedule_v0"
+
+_PROVIDER_KINDS = {"builtin", "extension"}
+_TIMEZONE_RE = re.compile(r"^[A-Za-z_+-]+(?:/[A-Za-z0-9_+-]+)*$")
+_PROFILE_FIELDS = {
+    "schema_version",
+    "enabled",
+    "profile_id",
+    "profile_version",
+    "trigger_policy",
+    "schedule",
+    "source_bindings",
+    "renderer_bindings",
+    "sink_bindings",
+}
+
+
+def _reject_unknown_fields(
+    value: Mapping[str, Any], *, allowed: set[str], label: str
+) -> None:
+    unknown = sorted(set(value) - allowed)
+    if unknown:
+        raise ValueError(f"{label} contains unsupported fields: {', '.join(unknown)}")
+
+
+def _normalize_adapter_bindings(
+    raw: Sequence[Mapping[str, Any]], *, kind: str
+) -> list[dict[str, Any]]:
+    if kind == "source":
+        schema = SOURCE_BINDING_SCHEMA
+        id_field = "source_id"
+        kind_field = "source_kind"
+    else:
+        schema = RENDERER_BINDING_SCHEMA
+        id_field = "renderer_id"
+        kind_field = "renderer_kind"
+    bindings: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for index, raw_item in enumerate(raw):
+        label = f"{kind}_bindings[{index}]"
+        item = _mapping(raw_item, label)
+        _reject_raw_keys(item, label)
+        _reject_unknown_fields(
+            item,
+            allowed={
+                "schema_version",
+                id_field,
+                kind_field,
+                "adapter_id",
+                "provider",
+            },
+            label=label,
+        )
+        if item.get("schema_version", schema) != schema:
+            raise ValueError(f"{label} must use {schema}")
+        binding_id = _token(item.get(id_field), f"{label}.{id_field}")
+        if binding_id in seen:
+            raise ValueError(f"duplicate {id_field} {binding_id!r}")
+        seen.add(binding_id)
+        provider = _mapping(
+            item.get("provider", {"kind": "builtin"}), f"{label}.provider"
+        )
+        _reject_unknown_fields(
+            provider,
+            allowed={"kind", "provider_id", "provider_version"},
+            label=f"{label}.provider",
+        )
+        provider_kind = _token(
+            provider.get("kind", "builtin"), f"{label}.provider.kind"
+        )
+        if provider_kind not in _PROVIDER_KINDS:
+            raise ValueError(f"{label}.provider.kind must be builtin or extension")
+        normalized_provider: dict[str, str] = {"kind": provider_kind}
+        if provider_kind == "extension":
+            normalized_provider.update(
+                {
+                    "provider_id": _token(
+                        provider.get("provider_id"),
+                        f"{label}.provider.provider_id",
+                    ),
+                    "provider_version": _version(
+                        provider.get("provider_version"),
+                        f"{label}.provider.provider_version",
+                    ),
+                }
+            )
+        elif provider.get("provider_id") or provider.get("provider_version"):
+            raise ValueError(
+                f"{label}.provider builtin must not declare extension identity"
+            )
+        bindings.append(
+            {
+                "schema_version": schema,
+                id_field: binding_id,
+                kind_field: _token(item.get(kind_field), f"{label}.{kind_field}"),
+                "adapter_id": _token(item.get("adapter_id"), f"{label}.adapter_id"),
+                "provider": normalized_provider,
+            }
+        )
+    return sorted(bindings, key=lambda item: str(item[id_field]))
+
+
+def _normalize_schedule(raw: object) -> dict[str, str] | None:
+    if raw is None:
+        return None
+    schedule = _mapping(raw, "schedule")
+    _reject_raw_keys(schedule, "schedule")
+    _reject_unknown_fields(
+        schedule,
+        allowed={"schema_version", "schedule_id", "rrule", "timezone"},
+        label="schedule",
+    )
+    if schedule.get("schema_version", SCHEDULE_SCHEMA) != SCHEDULE_SCHEMA:
+        raise ValueError(f"schedule must use {SCHEDULE_SCHEMA}")
+    rrule = _text(schedule.get("rrule"), "schedule.rrule", maximum=500).upper()
+    if not rrule.startswith("FREQ="):
+        raise ValueError("schedule.rrule must start with FREQ=")
+    timezone = _text(schedule.get("timezone"), "schedule.timezone", maximum=80)
+    if not _TIMEZONE_RE.fullmatch(timezone):
+        raise ValueError("schedule.timezone must be an IANA-like timezone name")
+    return {
+        "schema_version": SCHEDULE_SCHEMA,
+        "schedule_id": _token(schedule.get("schedule_id"), "schedule.schedule_id"),
+        "rrule": rrule,
+        "timezone": timezone,
+    }
+
+
+def normalize_periodic_report_profile(raw: Mapping[str, Any]) -> dict[str, Any]:
+    """Normalize one default-off, domain-neutral project reporting profile."""
+
+    profile = _mapping(raw, "profile")
+    _reject_raw_keys(profile, "profile")
+    _reject_unknown_fields(profile, allowed=_PROFILE_FIELDS, label="profile")
+    if profile.get("schema_version") != PROFILE_SCHEMA:
+        raise ValueError(f"profile must use {PROFILE_SCHEMA}")
+    enabled = _boolean(profile.get("enabled", False), "profile.enabled")
+    sources = _normalize_adapter_bindings(
+        _sequence(profile.get("source_bindings", []), "profile.source_bindings"),
+        kind="source",
+    )
+    renderers = _normalize_adapter_bindings(
+        _sequence(profile.get("renderer_bindings", []), "profile.renderer_bindings"),
+        kind="renderer",
+    )
+    sinks = normalize_periodic_report_sink_bindings(
+        _sequence(profile.get("sink_bindings", []), "profile.sink_bindings")
+    )
+    if enabled and not sources:
+        raise ValueError("enabled profile requires at least one source binding")
+    if enabled and not renderers:
+        raise ValueError("enabled profile requires at least one renderer binding")
+    normalized: dict[str, Any] = {
+        "schema_version": PROFILE_SCHEMA,
+        "enabled": enabled,
+        "profile_id": _token(profile.get("profile_id"), "profile.profile_id"),
+        "profile_version": _version(
+            profile.get("profile_version"), "profile.profile_version"
+        ),
+        "trigger_policy": normalize_periodic_report_trigger_policy(
+            profile.get("trigger_policy", {})
+        ),
+        "source_bindings": sources,
+        "renderer_bindings": renderers,
+        "sink_bindings": sinks,
+    }
+    schedule = _normalize_schedule(profile.get("schedule"))
+    if schedule is not None:
+        normalized["schedule"] = schedule
+    return normalized
+
+
+def build_periodic_report_activation(raw: Mapping[str, Any]) -> dict[str, Any]:
+    """Return a deterministic activation receipt without invoking adapters."""
+
+    profile = normalize_periodic_report_profile(raw)
+    enabled_sinks = [
+        item
+        for item in profile["sink_bindings"]
+        if item["dependency_policy"] != "disabled"
+    ]
+    required_sinks = [
+        item for item in enabled_sinks if item["dependency_policy"] == "required"
+    ]
+    if not enabled_sinks:
+        mode = "portable"
+    elif required_sinks:
+        mode = "durable"
+    else:
+        mode = "enhanced"
+    return {
+        "ok": True,
+        "schema_version": ACTIVATION_SCHEMA,
+        "status": "enabled" if profile["enabled"] else "disabled",
+        "active": profile["enabled"],
+        "generation_allowed": profile["enabled"],
+        "profile_digest": _sha256(profile),
+        "profile": profile,
+        "extension_mode": mode,
+        "required_extension_count": len(required_sinks),
+        "optional_extension_count": sum(
+            item["dependency_policy"] == "optional" for item in enabled_sinks
+        ),
+        "boundary": {
+            "default_enabled": False,
+            "business_semantics_owned_by_sources": True,
+            "schedule_application_owned_by_host": True,
+            "extension_effects_performed": False,
+            "external_writes_performed": False,
+        },
+    }

loopx/capabilities/periodic_report/project_progress.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from .adapters import (
+    PeriodicReportSourceAdapter,
+    build_periodic_report_source_result,
+)
+
+
+PROJECT_PROGRESS_PROJECTION_SCHEMA = "periodic_report_project_progress_projection_v0"
+PROJECT_PROGRESS_SOURCE_ID = "project_progress"
+PROJECT_PROGRESS_SOURCE_KIND = "validated_project_progress"
+PROJECT_PROGRESS_ADAPTER_ID = "project_progress_v0"
+
+_SECTION_BY_CONTENT_KIND = {
+    "outcome": ("progress", 10),
+    "decision": ("progress", 10),
+    "progress": ("progress", 10),
+    "capability_change": ("capability_evolution", 20),
+    "risk": ("risks", 30),
+    "next_action": ("next_actions", 40),
+    "runtime": ("supporting_evidence", 50),
+    "delivery_receipt": ("supporting_evidence", 50),
+}
+_SECTION_TITLES = {
+    "en": {
+        "progress": "Progress and outcomes",
+        "capability_evolution": "Capability evolution",
+        "risks": "Risks and blockers",
+        "next_actions": "Next actions",
+        "supporting_evidence": "Supporting evidence",
+    },
+    "zh": {
+        "progress": "进展与成果",
+        "capability_evolution": "能力演进",
+        "risks": "风险与阻塞",
+        "next_actions": "下一步",
+        "supporting_evidence": "支撑证据",
+    },
+}
+_LANGUAGE_RE = re.compile(r"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$")
+_SUPPORTING_CONTENT_KINDS = {"runtime", "delivery_receipt"}
+_MAX_PRIMARY_ITEMS = 8
+_MAX_SUPPORTING_ITEMS = 16
+
+
+def _mapping(value: object, label: str) -> dict[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{label} must be an object")
+    return {str(key): item for key, item in value.items()}
+
+
+def _sequence(value: object, label: str) -> list[Any]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        raise ValueError(f"{label} must be a list")
+    return list(value)
+
+
+def _snapshot_ref(projection: Mapping[str, Any], *, language: str) -> str:
+    identity = {
+        "goal_id": str(projection.get("goal_id") or "project"),
+        "observed_at": str(projection.get("observed_at") or ""),
+        "language": language,
+        "items": projection.get("items"),
+    }
+    encoded = json.dumps(
+        identity,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return f"loopx-progress:{hashlib.sha256(encoded).hexdigest()[:24]}"
+
+
+def _language(value: object) -> str:
+    language = str(value or "en").strip()
+    if not _LANGUAGE_RE.fullmatch(language):
+        raise ValueError(
+            "project_progress.language must be a BCP-47-like language tag"
+        )
+    return language.lower()
+
+
+def _section_title(section_id: str, *, language: str) -> str:
+    vocabulary = "zh" if language.lower().startswith("zh") else "en"
+    return _SECTION_TITLES[vocabulary][section_id]
+
+
+def build_project_progress_periodic_report_source(
+    projection: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Normalize concise, domain-neutral project progress into report sections."""
+
+    packet = _mapping(projection, "project_progress")
+    if packet.get("schema_version") != PROJECT_PROGRESS_PROJECTION_SCHEMA:
+        raise ValueError(
+            f"project_progress must use {PROJECT_PROGRESS_PROJECTION_SCHEMA}"
+        )
+    language = _language(packet.get("language"))
+    raw_items = _sequence(packet.get("items"), "project_progress.items")
+    if not raw_items:
+        raise ValueError("project_progress.items must not be empty")
+
+    sections: dict[str, dict[str, Any]] = {}
+    seen_item_ids: set[str] = set()
+    primary_count = 0
+    supporting_count = 0
+    for index, raw_item in enumerate(raw_items):
+        label = f"project_progress.items[{index}]"
+        item = _mapping(raw_item, label)
+        item_id = str(item.get("item_id") or "").strip().lower()
+        if not item_id:
+            raise ValueError(f"{label}.item_id is required")
+        if item_id in seen_item_ids:
+            raise ValueError(f"duplicate project progress item_id {item_id!r}")
+        seen_item_ids.add(item_id)
+
+        content_kind = str(item.get("content_kind") or "").strip().lower()
+        section_spec = _SECTION_BY_CONTENT_KIND.get(content_kind)
+        if section_spec is None:
+            raise ValueError(f"{label}.content_kind is invalid")
+        visibility = str(item.get("visibility") or "primary").strip().lower()
+        if content_kind in _SUPPORTING_CONTENT_KINDS:
+            supporting_count += 1
+        elif visibility == "supporting":
+            supporting_count += 1
+        else:
+            primary_count += 1
+
+        section_id, order = section_spec
+        section = sections.setdefault(
+            section_id,
+            {
+                "section_id": section_id,
+                "title": _section_title(section_id, language=language),
+                "order": order,
+                "items": [],
+            },
+        )
+        section["items"].append(item)
+
+    if primary_count > _MAX_PRIMARY_ITEMS:
+        raise ValueError(
+            f"project_progress contains {primary_count} primary items; "
+            f"summarize to at most {_MAX_PRIMARY_ITEMS}"
+        )
+    if supporting_count > _MAX_SUPPORTING_ITEMS:
+        raise ValueError(
+            f"project_progress contains {supporting_count} supporting items; "
+            f"keep at most {_MAX_SUPPORTING_ITEMS}"
+        )
+
+    warnings = _sequence(packet.get("warnings", []), "project_progress.warnings")
+    retryable = packet.get("retryable", bool(warnings))
+    if not isinstance(retryable, bool):
+        raise ValueError("project_progress.retryable must be a boolean")
+    status = str(packet.get("status") or ("partial" if warnings else "complete"))
+    return build_periodic_report_source_result(
+        source_id=PROJECT_PROGRESS_SOURCE_ID,
+        source_kind=PROJECT_PROGRESS_SOURCE_KIND,
+        status=status,
+        observed_at=str(packet.get("observed_at") or ""),
+        sections=list(sections.values()),
+        snapshot_ref=_snapshot_ref(packet, language=language),
+        retryable=retryable,
+    )
+
+
+def project_progress_periodic_report_source_adapter() -> PeriodicReportSourceAdapter:
+    return PeriodicReportSourceAdapter(
+        source_id=PROJECT_PROGRESS_SOURCE_ID,
+        source_kind=PROJECT_PROGRESS_SOURCE_KIND,
+        collect=build_project_progress_periodic_report_source,
+    )