convilyn-edge 0.1.0b3__py3-none-any.whl

convilyn_edge/__init__.py

@@ -0,0 +1,132 @@
+"""Convilyn Edge — the Edge AI Workflow SDK (``convilyn-edge``).
+
+The Device Data Plane + Edge Runtime SPI: seven typed Protocols that let a
+developer compose device events, environment state, deterministic rules, models,
+human confirmation and gated actions into an auditable, offline-capable edge AI
+workflow — without the substrate ever encoding one vertical scenario.
+
+Quick start — define a Source and drive it (v0.1 is the SPI; the retail pack +
+simulator land in PR4/PR5)::
+
+    from convilyn_edge import EventEnvelope, EventSource, new_envelope
+
+    async for event in my_source.start(ctx):   # my_source: EventSource
+        ...   # event is an EventEnvelope
+
+Design invariants (the binding principles, expressed in code):
+
+* The device is never a second source of truth — the server holds the 7 hard
+  zones and re-grounds every device value. The edge SPI *inherits* that contract.
+* One envelope shape, one Result type, one observability convention.
+* No LLM in the deterministic operators; no ``if scenario == ...`` in the
+  substrate. Scenario logic lives in a removable Solution Pack.
+
+``convilyn_edge`` (this top level) is the stable public surface — everything here
+follows the reference-architecture's independent-versioning rule (§十六). Nothing
+in this package imports ``backend-api`` or any other SDK at import time; runtime
+dependencies are zero.
+"""
+
+from __future__ import annotations
+
+from convilyn_edge._version import __version__
+from convilyn_edge.envelope import (
+    SPEC_VERSION,
+    Correlation,
+    EventEnvelope,
+    EventSourceRef,
+    new_envelope,
+)
+from convilyn_edge.probe import (
+    Capability,
+    DeviceCapabilityManifest,
+    InstalledAsset,
+    QualityTier,
+    probe_device,
+)
+from convilyn_edge.result import Err, Ok, Result
+from convilyn_edge.spi import (
+    ActionAuthorization,
+    ActionDescriptor,
+    ActionResult,
+    ActionSink,
+    ActionStatus,
+    DefaultAction,
+    DeterministicOperator,
+    DeviceHealth,
+    EventContext,
+    EventSource,
+    Evidence,
+    ExecutionContext,
+    HealthStatus,
+    HumanReview,
+    ModelOperator,
+    ModelResult,
+    ModelStatus,
+    NormalizeError,
+    Normalizer,
+    OperatorError,
+    Placement,
+    ReviewChoice,
+    ReviewDecision,
+    ReviewOutcome,
+    ReviewRequest,
+    RiskLevel,
+    SourceContext,
+    StateProvider,
+)
+
+__all__ = [
+    "__version__",
+    # Result
+    "Ok",
+    "Err",
+    "Result",
+    # Envelope
+    "EventEnvelope",
+    "EventSourceRef",
+    "Correlation",
+    "new_envelope",
+    "SPEC_VERSION",
+    # Device-capability probe (Epic #2556 — multi-device IoT readiness)
+    "probe_device",
+    "DeviceCapabilityManifest",
+    "InstalledAsset",
+    "Capability",
+    "QualityTier",
+    # SPI — 1. Source
+    "EventSource",
+    "SourceContext",
+    "DeviceHealth",
+    "HealthStatus",
+    # SPI — 2. Normalizer
+    "Normalizer",
+    "NormalizeError",
+    # SPI — 3. StateProvider
+    "StateProvider",
+    "EventContext",
+    # SPI — 4. DeterministicOperator
+    "DeterministicOperator",
+    "ExecutionContext",
+    "OperatorError",
+    # SPI — 5. ModelOperator
+    "ModelOperator",
+    "ModelResult",
+    "Evidence",
+    "Placement",
+    "ModelStatus",
+    # SPI — 6. HumanReview
+    "HumanReview",
+    "ReviewRequest",
+    "ReviewChoice",
+    "ReviewOutcome",
+    "DefaultAction",
+    "ReviewDecision",
+    # SPI — 7. ActionSink
+    "ActionSink",
+    "ActionDescriptor",
+    "ActionAuthorization",
+    "ActionResult",
+    "RiskLevel",
+    "ActionStatus",
+]

convilyn_edge/_version.py

@@ -0,0 +1,15 @@
+"""Single source of truth for ``convilyn-edge``'s package version.
+
+Read by both:
+
+* ``pyproject.toml`` via ``[tool.hatch.version]`` (so the wheel metadata +
+  ``importlib.metadata.version("convilyn-edge")`` agree)
+* ``convilyn_edge.__init__`` for the in-process ``__version__`` attribute.
+
+The SDK versions its *surface* independently of any device / adapter /
+workflow / runtime version (reference-architecture §十六) — this is only the
+Core API + SPI version. Bump in CHANGELOG-bumping commits; never edit a
+hardcoded constant in two places.
+"""
+
+__version__ = "0.1.0b3"

convilyn_edge/cli/__init__.py

@@ -0,0 +1,7 @@
+"""The ``convilyn-edge`` command-line interface (stdlib argparse, zero deps)."""
+
+from __future__ import annotations
+
+from convilyn_edge.cli.main import main
+
+__all__ = ["main"]

convilyn_edge/cli/main.py

@@ -0,0 +1,97 @@
+"""The ``convilyn-edge`` CLI (stdlib ``argparse`` — zero dependencies).
+
+Commands:
+
+* ``simulate <scenario.json> [--no-delay]`` — replay a scenario through the
+  :class:`~convilyn_edge.simulator.SimulatedSource`, printing each
+  ``EventEnvelope`` as a wire-JSON line (drive a workflow with no hardware).
+* ``init adapter|workflow <name> [--path DIR]`` — scaffold a device-adapter or
+  workflow skeleton.
+
+``dev run`` and ``trace replay`` are deferred to v0.2 (they need the workflow
+executor + a trace-export format that are out of the v0.1 scope); ``simulate``
+is the v0.1 device-plane dev-run, and ``--no-delay`` gives a deterministic replay.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+from convilyn_edge._version import __version__
+from convilyn_edge.cli.scaffold import scaffold_adapter, scaffold_workflow
+from convilyn_edge.simulator import Scenario, SimulatedSource
+from convilyn_edge.spi.source import SourceContext
+
+
+async def _drive(scenario: Scenario, no_delay: bool) -> int:
+    source = SimulatedSource(scenario, no_delay=no_delay)
+    ctx = SourceContext(device_id=scenario.source.device_id, site_id=scenario.site_id)
+    count = 0
+    async for envelope in source.start(ctx):
+        print(json.dumps(envelope.to_wire(), ensure_ascii=False))
+        count += 1
+    return count
+
+
+def cmd_simulate(args: argparse.Namespace) -> int:
+    scenario_path = Path(args.scenario)
+    if not scenario_path.is_file():
+        print(f"no such scenario file: {scenario_path}", file=sys.stderr)
+        return 2
+    try:
+        scenario = Scenario.load(scenario_path)
+    except (json.JSONDecodeError, KeyError, ValueError) as exc:
+        print(f"malformed scenario {scenario_path.name}: {exc}", file=sys.stderr)
+        return 2
+    count = asyncio.run(_drive(scenario, args.no_delay))
+    print(f"simulated {count} event(s) from {scenario_path.name}", file=sys.stderr)
+    return 0
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    root = Path(args.path) if args.path else Path.cwd()
+    scaffold = scaffold_adapter if args.kind == "adapter" else scaffold_workflow
+    try:
+        created = scaffold(root, args.name)
+    except (ValueError, FileExistsError) as exc:
+        print(f"cannot scaffold {args.kind} '{args.name}': {exc}", file=sys.stderr)
+        return 2
+    print(f"scaffolded {args.kind} '{args.name}' at {created}", file=sys.stderr)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="convilyn-edge",
+        description="Convilyn Edge AI Workflow SDK — device simulator + scaffolds.",
+    )
+    parser.add_argument("--version", action="version", version=f"convilyn-edge {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    simulate = sub.add_parser("simulate", help="replay a scenario through the simulator")
+    simulate.add_argument("scenario", help="path to a scenario JSON file")
+    simulate.add_argument(
+        "--no-delay", action="store_true", help="ignore per-event delays (deterministic replay)"
+    )
+    simulate.set_defaults(func=cmd_simulate)
+
+    init = sub.add_parser("init", help="scaffold an adapter or workflow skeleton")
+    init.add_argument("kind", choices=["adapter", "workflow"])
+    init.add_argument("name", help="the adapter / workflow name")
+    init.add_argument("--path", default=None, help="root directory (default: cwd)")
+    init.set_defaults(func=cmd_init)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

convilyn_edge/cli/scaffold.py

@@ -0,0 +1,137 @@
+"""Scaffold generators for ``convilyn-edge init adapter|workflow`` (reference §十四).
+
+Writes a conventional skeleton so a developer adding a device adapter or a
+workflow starts from a consistent layout, not a blank directory. Pure stdlib
+(pathlib); every file is a commented placeholder the author fills in.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+# A scaffold name is a single path component: alnum-led, then [A-Za-z0-9._-]. This
+# rejects path separators, ``..``, absolute/anchored names (which would escape the
+# target root — ``root / "adapters" / "/tmp/x"`` == ``/tmp/x``), and newlines / ``: ``
+# that would inject into the generated YAML.
+_SAFE_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+def _validate_name(name: str) -> None:
+    if not _SAFE_NAME.match(name):
+        raise ValueError(
+            f"invalid name {name!r}: use [A-Za-z0-9._-] (alnum-led), no path separators or '..'"
+        )
+
+
+_ADAPTER_YAML = """\
+# Device adapter manifest for '{name}' (reference §二 Device Capability Manifest).
+apiVersion: convilyn.io/v1alpha1
+kind: DeviceProfile
+metadata:
+  name: {name}
+  vendor: generic
+  model: "*"
+capabilities:
+  properties: {{}}
+  events: {{}}
+  actions: {{}}
+bindings: []
+"""
+
+_ADAPTER_README = """\
+# {name} adapter
+
+An `EventSource` (+ `Normalizer`) that turns this device's raw output into the
+canonical `EventEnvelope`. Implement `convilyn_edge.spi.EventSource` in `src/`.
+
+- `schemas/`         — the canonical event schema(s) this adapter emits
+- `src/`             — the adapter implementation
+- `fixtures/`        — recorded raw payloads for tests
+- `contract-tests/`  — assert the adapter emits the canonical envelope
+"""
+
+_WORKFLOW_YAML = """\
+# Edge workflow '{name}' (reference §五 — a typed DAG, never an agent prompt).
+apiVersion: convilyn.io/v1alpha1
+kind: EdgeWorkflow
+metadata:
+  name: {name}
+  version: 0.1.0
+trigger:
+  event: device.example.received
+steps: []
+"""
+
+_WORKFLOW_README = """\
+# {name} workflow
+
+Compose deterministic operators, a model operator, human review and gated
+actions over device events. Each step declares its input/output schema,
+placement, deadline and required permissions.
+
+- `schemas/`       — input/output schemas
+- `policies/`      — retry / timeout / human-review / fallback policy
+- `prompts/`       — model-operator prompt(s)
+- `tests/`         — unit tests
+- `golden-cases/`  — recorded input → expected decision
+- `deployment/`    — resource limits + kill-switch config
+"""
+
+_ADAPTER_DIRS = ("schemas", "src", "fixtures", "contract-tests")
+_WORKFLOW_DIRS = ("schemas", "policies", "prompts", "tests", "golden-cases", "deployment")
+
+
+def _write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _scaffold(base: Path, dirs: tuple[str, ...], files: dict[str, str]) -> Path:
+    for directory in dirs:
+        (base / directory).mkdir(parents=True, exist_ok=True)
+        (base / directory / ".gitkeep").write_text("", encoding="utf-8")
+    for filename, content in files.items():
+        _write(base / filename, content)
+    return base
+
+
+def scaffold_adapter(root: Path, name: str) -> Path:
+    """Create ``<root>/adapters/<name>/`` with the adapter skeleton. Returns it.
+
+    Raises ``ValueError`` for an unsafe ``name`` and ``FileExistsError`` if the
+    target already exists (a scaffold never silently overwrites authored files)."""
+    _validate_name(name)
+    base = root / "adapters" / name
+    if base.exists():
+        raise FileExistsError(f"{base} already exists — remove it or choose another name")
+    return _scaffold(
+        base,
+        _ADAPTER_DIRS,
+        {
+            "adapter.yaml": _ADAPTER_YAML.format(name=name),
+            "README.md": _ADAPTER_README.format(name=name),
+        },
+    )
+
+
+def scaffold_workflow(root: Path, name: str) -> Path:
+    """Create ``<root>/workflows/<name>/`` with the workflow skeleton. Returns it.
+
+    Raises ``ValueError`` for an unsafe ``name`` and ``FileExistsError`` if the
+    target already exists."""
+    _validate_name(name)
+    base = root / "workflows" / name
+    if base.exists():
+        raise FileExistsError(f"{base} already exists — remove it or choose another name")
+    return _scaffold(
+        base,
+        _WORKFLOW_DIRS,
+        {
+            "workflow.yaml": _WORKFLOW_YAML.format(name=name),
+            "README.md": _WORKFLOW_README.format(name=name),
+        },
+    )
+
+
+__all__ = ["scaffold_adapter", "scaffold_workflow"]

convilyn_edge/clientcompute/__init__.py

@@ -0,0 +1,74 @@
+"""Client-compute — the on-device extractor keystone (contract v1 consumer).
+
+Productizes the device half of the frozen ``client_compute`` interrupt contract:
+the cloud delegates the extractor role to the device, the device runs a local
+model over its OWN copy of the file and returns grounded anchors, the server
+re-grounds them. ``convilyn-edge`` **confirms-and-consumes** the contract.
+
+    from convilyn_edge.clientcompute import (
+        ClientComputeBridge, EdgeModelOperator, HttpLocalExtractor,
+    )
+
+    operator = EdgeModelOperator(HttpLocalExtractor.from_env(os.environ))
+    bridge = ClientComputeBridge(operator, my_file_resolver)
+    job = await bridge.handle_if_present(client.goals, job)   # client: AsyncConvilyn
+"""
+
+from __future__ import annotations
+
+from convilyn_edge.clientcompute.bridge import (
+    ClientComputeBridge,
+    ClientComputeError,
+    FileTextResolver,
+    GoalClientPort,
+    GoalJobLike,
+    MissingLocalSourceError,
+    find_client_compute_interrupt,
+)
+from convilyn_edge.clientcompute.contract import (
+    DEFAULT_MAX_TOTAL_CHARS,
+    DEFAULT_MAX_VALUE_CHARS,
+    INTERRUPT_TYPE,
+    MISSING_SENTINEL,
+    STRATEGY_V1,
+    AnchorsContract,
+    ClientComputeRequest,
+    build_resume_answer,
+    ground_anchors,
+)
+from convilyn_edge.clientcompute.engine import (
+    HttpLocalExtractor,
+    LocalExtractor,
+    build_extract_messages,
+    resolve_local_model_tag,
+)
+from convilyn_edge.clientcompute.operator import EdgeModelOperator, ExtractInput
+
+__all__ = [
+    # contract
+    "INTERRUPT_TYPE",
+    "STRATEGY_V1",
+    "MISSING_SENTINEL",
+    "DEFAULT_MAX_VALUE_CHARS",
+    "DEFAULT_MAX_TOTAL_CHARS",
+    "AnchorsContract",
+    "ClientComputeRequest",
+    "ground_anchors",
+    "build_resume_answer",
+    # engine
+    "LocalExtractor",
+    "HttpLocalExtractor",
+    "resolve_local_model_tag",
+    "build_extract_messages",
+    # operator
+    "EdgeModelOperator",
+    "ExtractInput",
+    # bridge
+    "ClientComputeBridge",
+    "ClientComputeError",
+    "MissingLocalSourceError",
+    "FileTextResolver",
+    "GoalJobLike",
+    "GoalClientPort",
+    "find_client_compute_interrupt",
+]

convilyn_edge/clientcompute/bridge.py

@@ -0,0 +1,184 @@
+"""``ClientComputeBridge`` — drive one ``client_compute`` interrupt to resume.
+
+The round-trip the keystone proves, end to end:
+
+    cloud pauses with a client_compute interrupt
+      → bridge parses the frozen payload (contract.py)
+      → resolves each file_id to the device's OWN local text (FileTextResolver)
+      → EdgeModelOperator.infer runs the local model + grounds (operator.py)
+      → bridge submits {anchors, nonce} via the consumer SDK's fill_slots
+      → server re-grounds and resumes
+
+The bridge depends only on **narrow Protocols** (DIP) — never on the consumer SDK
+package — so ``convilyn-edge`` stays zero-dependency: the caller injects a live
+``AsyncConvilyn().goals`` (which satisfies :class:`GoalClientPort` structurally)
+and a resolver that maps a ``file_id`` to the local file's text. Privacy invariant
+(contract §5.2): the interrupt carries file *references* only; the device reads its
+own copy — file bytes never leave the device.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Protocol
+
+from convilyn_edge.clientcompute.contract import (
+    INTERRUPT_TYPE,
+    ClientComputeRequest,
+    build_resume_answer,
+)
+from convilyn_edge.clientcompute.operator import EdgeModelOperator, ExtractInput
+
+
+class ClientComputeError(Exception):
+    """The bridge could not fulfil a client_compute interrupt."""
+
+
+class MissingLocalSourceError(ClientComputeError):
+    """The interrupt referenced files but none resolved to local text on this
+    device — a fail-loud misconfiguration (the extraction cannot be meaningful),
+    never a silent all-sentinel submission."""
+
+
+class FileTextResolver(Protocol):
+    """Maps a delegation ``file_id`` to the device's own local copy of its text.
+
+    The device reads its OWN file (the point of on-device compute); returning
+    ``None`` means "this device has no local copy of that file"."""
+
+    def resolve(self, file_id: str) -> str | None:
+        """Return the local text for ``file_id``, or ``None`` if unavailable."""
+        ...
+
+
+class GoalJobLike(Protocol):
+    """The subset of a consumer-SDK ``GoalJob`` the bridge reads."""
+
+    job_spec_id: str
+    item_version: int | None
+    pending_interrupts: Sequence[Mapping[str, Any]]
+
+
+class GoalClientPort(Protocol):
+    """The subset of the consumer SDK's ``goals`` surface the bridge drives.
+
+    A live ``AsyncConvilyn().goals`` satisfies this structurally."""
+
+    async def fill_slots(
+        self,
+        job_spec_id: str,
+        answers: Mapping[str, Any],
+        *,
+        expected_version: int | None = None,
+    ) -> GoalJobLike:
+        """Submit slot/interrupt answers, returning the updated job."""
+        ...
+
+
+def find_client_compute_interrupt(job: GoalJobLike) -> Mapping[str, Any] | None:
+    """Return the first pending ``client_compute`` interrupt on ``job``, or None."""
+    for entry in job.pending_interrupts:
+        if entry.get("interruptType") == INTERRUPT_TYPE and entry.get("status") == "pending":
+            return entry
+    return None
+
+
+def _anchor_schema(required_anchors: Sequence[str]) -> dict[str, Any]:
+    """A minimal JSON Schema for the anchor object (SPI conformance)."""
+    return {
+        "type": "object",
+        "properties": {key: {"type": "string"} for key in required_anchors},
+        "required": list(required_anchors),
+    }
+
+
+class ClientComputeBridge:
+    """Fulfil ``client_compute`` interrupts with a device-local model."""
+
+    def __init__(
+        self,
+        operator: EdgeModelOperator,
+        file_resolver: FileTextResolver,
+    ) -> None:
+        self._operator = operator
+        self._file_resolver = file_resolver
+
+    def _resolve_sources(self, request: ClientComputeRequest) -> dict[str, str]:
+        """Map each referenced ``file_id`` to its local text. Raises
+        :class:`MissingLocalSourceError` if files were referenced but none
+        resolved."""
+        sources: dict[str, str] = {}
+        for file_id in request.file_ids:
+            text = self._file_resolver.resolve(file_id)
+            if text is not None:
+                sources[file_id] = text
+        if request.file_ids and not sources:
+            raise MissingLocalSourceError(
+                f"client_compute referenced {len(request.file_ids)} file(s) but none "
+                "resolved to local text on this device"
+            )
+        return sources
+
+    async def handle_interrupt(
+        self,
+        client: GoalClientPort,
+        job: GoalJobLike,
+        interrupt: Mapping[str, Any],
+        *,
+        deadline_ms: int | None = None,
+    ) -> GoalJobLike:
+        """Run the local extractor for one ``client_compute`` ``interrupt`` and
+        submit the grounded anchors via ``client.fill_slots``. Returns the updated
+        job."""
+        request = ClientComputeRequest.from_payload(interrupt.get("payload") or {})
+        sources = self._resolve_sources(request)
+
+        result = await self._operator.infer(
+            ExtractInput(
+                prompt=request.extractor_prompt,
+                sources=sources,
+                required_anchors=request.required_anchors,
+                contract=request.anchors_contract,
+            ),
+            schema=_anchor_schema(request.required_anchors),
+            deadline_ms=deadline_ms,
+            placement="edge",
+        )
+        # Even an "unavailable" result yields a total all-sentinel answer, so the
+        # server can re-ground (→ all indeterminate) and resume rather than hang.
+        anchors = result.output or {
+            key: request.anchors_contract.missing_sentinel for key in request.required_anchors
+        }
+        answer = build_resume_answer(anchors, request.nonce)
+        interrupt_id = interrupt["interruptId"]
+        return await client.fill_slots(
+            job.job_spec_id,
+            {interrupt_id: answer},
+            expected_version=job.item_version,
+        )
+
+    async def handle_if_present(
+        self,
+        client: GoalClientPort,
+        job: GoalJobLike,
+        *,
+        deadline_ms: int | None = None,
+    ) -> GoalJobLike | None:
+        """If ``job`` has a pending client_compute interrupt, fulfil it and return
+        the updated job; otherwise return ``None`` (nothing to do — e.g. the
+        server-side delegation kill-switch is OFF)."""
+        interrupt = find_client_compute_interrupt(job)
+        if interrupt is None:
+            return None
+        return await self.handle_interrupt(client, job, interrupt, deadline_ms=deadline_ms)
+
+
+__all__ = [
+    "ClientComputeError",
+    "MissingLocalSourceError",
+    "FileTextResolver",
+    "GoalJobLike",
+    "GoalClientPort",
+    "ClientComputeBridge",
+    "find_client_compute_interrupt",
+]