annoscript 0.1.0__py3-none-any.whl

annoscript/__init__.py

@@ -0,0 +1 @@
+"""AnnoScript's Python eDSL, compiler, execution plans and API-backed runtime."""

annoscript/_backend_profiles.py

@@ -0,0 +1,17 @@
+"""Generation wire profiles shared by configuration readers; no backend imports."""
+
+GENERATION_PROFILES = ("legacy", "qwen_vllm")
+
+
+def validate_extract_mode(mode, profile):
+    if type(mode) is not str or mode not in ("validated", "substring_chars"):
+        raise ValueError("extract_mode must be validated or substring_chars")
+    if mode == "substring_chars" and profile != "qwen_vllm":
+        raise ValueError("substring_chars requires qwen_vllm")
+    return mode
+
+
+def validate_generation_profile(profile):
+    if type(profile) is not str or profile not in GENERATION_PROFILES:
+        raise ValueError("generation profile must be legacy or qwen_vllm")
+    return profile

annoscript/_client_common.py

@@ -0,0 +1,287 @@
+"""Python 3.10+ contracts shared by local and remote clients; no execution imports."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from types import FunctionType, TracebackType
+from typing import Generic, List, Literal, TypeAlias, TypeVar
+from weakref import WeakKeyDictionary
+
+from annoscript.anno import Anno
+
+
+JSONValue: TypeAlias = (
+    str | int | float | bool | None | list["JSONValue"] | dict[str, "JSONValue"]
+)
+State: TypeAlias = str | list[JSONValue] | dict[str, JSONValue]
+R = TypeVar("R", bound=JSONValue)
+InputCheck: TypeAlias = Callable[[State], None]
+
+# Keep local checks outside the program function's attributes and execution body.
+_PRECONDITIONS: WeakKeyDictionary[
+    Callable[[Anno], JSONValue], tuple[InputCheck, ...]
+] = WeakKeyDictionary()
+# Only this registry's text values are exported as remote program configuration.
+_SYSTEM_PROMPTS: WeakKeyDictionary[Callable[[Anno], JSONValue], str] = WeakKeyDictionary()
+
+
+class InputValidationError(ValueError):
+    """An input failed a client-local precondition, before remote submission."""
+
+
+def require(condition: bool, *, message: str) -> None:
+    """Check an input condition locally; raise InputValidationError on failure.
+
+    This ordinary Python function remains active under optimization. It never
+    invokes inference, repairs inputs, or propagates constraints to the eDSL.
+    """
+    if not condition:
+        raise InputValidationError(message)
+
+
+def precondition(
+    check: InputCheck,
+) -> Callable[[Callable[[Anno], R]], Callable[[Anno], R]]:
+    """Register a client-local input check and return the original program.
+
+    Checks are synchronous, deterministic, read-only Python functions. Return
+    None for success and raise InputValidationError for an invalid input. Other
+    exceptions indicate a checker defect and abort submission. Checks must not
+    invoke models or make network requests.
+
+    Registration does not run checks or wrap the program. Direct program calls
+    do not run checks; AnnoClient implementations run them before any remote
+    submission. Stacked decorators are checked in source order (top to bottom),
+    stopping at the first failed check for each input.
+
+    The registry is local only. Remote program packaging must exclude these
+    decorator declarations, check functions, and their validation dependencies.
+    """
+    if not callable(check):
+        raise TypeError("precondition requires a callable input check")
+
+    def register(program: Callable[[Anno], R]) -> Callable[[Anno], R]:
+        if not isinstance(program, FunctionType):
+            raise TypeError("precondition must decorate a Python function")
+        _PRECONDITIONS[program] = (check,) + _PRECONDITIONS.get(program, ())
+        return program
+
+    return register
+
+
+def system_prompt(
+    prompt: str,
+) -> Callable[[Callable[[Anno], R]], Callable[[Anno], R]]:
+    """Declare shared model instructions and return the original program.
+
+    The client exports this text as program configuration. The runtime binds it
+    to every record's injected AnnoScript and applies it to LLM operations, including
+    calls inside helper functions. Decision requests use their own instructions
+    and requirements. API guarantees and hard constraints remain independently
+    enforced. Mapping shared instructions to a model is the runtime's job.
+
+    Registration neither wraps nor executes the program and creates no context.
+    Direct Python calls do not inject the prompt. Each program may declare one
+    system prompt; any repeated declaration raises ValueError. Empty strings
+    are allowed and preserved. Prompt text is sent as configuration, without
+    executing the decorator remotely or exporting local precondition checks.
+    """
+    if not isinstance(prompt, str):
+        raise TypeError("system_prompt requires a string")
+
+    def register(program: Callable[[Anno], R]) -> Callable[[Anno], R]:
+        if not isinstance(program, FunctionType):
+            raise TypeError("system_prompt must decorate a Python function")
+        if program in _SYSTEM_PROMPTS:
+            raise ValueError("a program may declare only one system_prompt")
+        _SYSTEM_PROMPTS[program] = prompt
+        return program
+
+    return register
+
+
+@dataclass(frozen=True)
+class ResultError:
+    """A per-input failure, including local validation or unsatisfied constraints."""
+
+    code: str
+    message: str
+
+
+@dataclass(frozen=True)
+class Result(Generic[R]):
+    """One terminal outcome, identified by its zero-based input index.
+
+    Success preserves the program's return value, including ``None``. An error
+    carries no value. A list-valued result stays one result, not multiple items.
+    """
+
+    index: int
+    status: Literal["success", "error"]
+    value: R | None = None
+    error: ResultError | None = None
+
+    def __post_init__(self) -> None:
+        if type(self.index) is not int or self.index < 0:
+            raise ValueError("index must be a nonnegative integer")
+        if self.status == "success":
+            if self.error is not None:
+                raise ValueError("a successful result cannot contain an error")
+        elif self.status == "error":
+            if not isinstance(self.error, ResultError) or self.value is not None:
+                raise ValueError("an error result requires ResultError and no value")
+        else:
+            raise ValueError("status must be 'success' or 'error'")
+
+
+class ResultStream(Iterator[Result[R]], ABC):
+    """A single-pass result iterator with explicit resource ownership.
+
+    Use ``with`` when stopping early: breaking a plain ``for`` loop does not
+    close the stream. Exhaustion and iteration errors automatically close it.
+    Concrete transports implement ``_next_result`` and ``_close`` and call
+    ``super().__init__()`` when overriding construction.
+
+    Streams are intended for consumption and closure by a single thread.
+    """
+
+    def __init__(self) -> None:
+        self._closed = False
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    def __iter__(self) -> ResultStream[R]:
+        return self
+
+    def __next__(self) -> Result[R]:
+        if self._closed:
+            raise StopIteration
+        try:
+            return self._next_result()
+        except StopIteration:
+            self.close()
+            raise
+        except BaseException:
+            try:
+                self.close()
+            except BaseException:
+                import logging
+                logging.getLogger(__name__).warning("Result cleanup failed while handling another exception")
+            raise
+
+    def close(self) -> None:
+        """Stop receiving results and release resources; repeated calls are harmless.
+
+        Closing discards undelivered results. No further work may be submitted.
+        The transport should request cancellation of pending
+        work, without promising that already-running remote work can be stopped.
+        The stream stays closed even if transport cleanup raises an exception.
+        """
+        if not self._closed:
+            self._closed = True
+            self._close()
+
+    def __enter__(self) -> ResultStream[R]:
+        if self._closed:
+            raise RuntimeError("cannot enter a closed result stream")
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> Literal[False]:
+        if exc_type is None:
+            self.close()
+        else:
+            try:
+                self.close()
+            except BaseException:
+                import logging
+                logging.getLogger(__name__).warning("Result cleanup failed while handling another exception")
+        return False
+
+    @abstractmethod
+    def _next_result(self) -> Result[R]:
+        """Return the next result, or raise StopIteration when fully exhausted.
+
+        Return per-input failures as error results. Raise submission-level or
+        transport failures as exceptions; the stream will then close itself.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def _close(self) -> None:
+        """Release local resources and request cancellation, at most once.
+
+        This hook must not submit new work or wait for unfinished work to
+        complete. It is also called after normal exhaustion or iteration errors.
+        """
+        raise NotImplementedError
+
+
+def get_program_config(program: Callable[[Anno], R]) -> dict[str, JSONValue]:
+    """Return fresh, JSON-compatible execution settings for remote submission.
+
+    Export system-prompt text only, never local check functions or rules.
+    Programs without a declaration have no system_prompt configuration key.
+    Reading configuration does not execute the program or its preconditions.
+    """
+    prompt = _SYSTEM_PROMPTS.get(program)
+    return {} if prompt is None else {"system_prompt": prompt}
+
+
+def validate_inputs(
+    program: Callable[[Anno], R], inputs: List[State]
+) -> dict[int, ResultError]:
+    """Run the whole batch's preconditions locally, without running program.
+
+    Call before any remote submission. Return invalid-input errors keyed by
+    original list index; the remaining indices passed all registered checks.
+    Only InputValidationError becomes an item error. Unexpected exceptions
+    and non-None check returns abort validation and must prevent submission.
+
+    This helper validates the outer list and program-specific preconditions.
+    Concrete clients also validate the generic JSON input contract.
+    """
+    if not isinstance(inputs, list):
+        raise TypeError("inputs must be a list")
+    checks = _PRECONDITIONS.get(program, ())
+    errors = {}
+    for index, state in enumerate(inputs):
+        try:
+            for check in checks:
+                if check(state) is not None:
+                    raise TypeError("precondition checks must return None on success")
+        except InputValidationError as error:
+            errors[index] = ResultError(code="invalid_input", message=str(error))
+    return errors
+
+
+def prepare_inputs(program, inputs):
+    """Snapshot JSON inputs, then check all valid shapes before any submission.
+
+    Return (indexed states, local errors), retaining the original input indices.
+    Unexpected checker exceptions propagate before either client dispatches work.
+    """
+    from annoscript._data import snapshot
+
+    if not isinstance(inputs, list):
+        raise TypeError("inputs must be a list")
+    errors, valid = {}, []
+    for index, state in enumerate(inputs):
+        try:
+            valid.append((index, snapshot(state, state=True)))
+        except (ValueError, RecursionError):
+            errors[index] = ResultError(
+                "invalid_input",
+                "input must contain finite JSON data and have string, array or object shape",
+            )
+    checked = validate_inputs(program, [state for _, state in valid])
+    errors.update({valid[i][0]: error for i, error in checked.items()})
+    return [item for i, item in enumerate(valid) if i not in checked], errors

annoscript/_data.py

@@ -0,0 +1,37 @@
+"""JSON snapshots and immutable inference payloads; no application code runs here."""
+
+import math
+from types import MappingProxyType
+from collections.abc import Mapping
+
+
+def snapshot(value, path="$", *, state=False):
+    if state and type(value) not in (str, list, dict):
+        raise ValueError(f"{path}: input must be a string, list or object")
+    if value is None or type(value) in (str, bool, int):
+        return value
+    if type(value) is float and math.isfinite(value):
+        return value
+    if type(value) is list:
+        return [snapshot(v, f"{path}[{i}]") for i, v in enumerate(value)]
+    if type(value) is dict:
+        if any(type(k) is not str for k in value):
+            raise ValueError(f"{path}: object keys must be strings")
+        return {k: snapshot(v, f"{path}.{k}") for k, v in value.items()}
+    raise ValueError(f"{path}: expected finite JSON data")
+
+
+def freeze(value):
+    if isinstance(value, Mapping):
+        return MappingProxyType({k: freeze(v) for k, v in value.items()})
+    if isinstance(value, (list, tuple)):
+        return tuple(freeze(v) for v in value)
+    return value
+
+
+def thaw(value):
+    if isinstance(value, Mapping):
+        return {k: thaw(v) for k, v in value.items()}
+    if isinstance(value, tuple):
+        return [thaw(v) for v in value]
+    return value

annoscript/_dispatch_pool.py

@@ -0,0 +1,47 @@
+"""Event-loop-local, FIFO model slots shared by isolated input runtimes.
+
+Waiters contain owner identities and wake callbacks, never model calls or payloads.
+Batch selection therefore happens after admission, using the current ready set.
+"""
+from collections import OrderedDict
+
+
+class RequestSlots:
+    def __init__(self, *, generation, decision):
+        if any(type(v) is not int or v < 1 for v in (generation, decision)):
+            raise ValueError("shared model limits must be positive integers")
+        self.limits = {"llm": generation, "decision": decision}
+        self.active = dict.fromkeys(self.limits, 0)
+        self.peak = dict(self.active)
+        self.waiters = {k: OrderedDict() for k in self.limits}
+
+    def acquire(self, kind, owner, wake):
+        waiting = self.waiters[kind]
+        waiting.setdefault(owner, wake)
+        if self.active[kind] >= self.limits[kind] or next(iter(waiting)) != owner:
+            return None
+        waiting.pop(owner)
+        self.active[kind] += 1
+        self.peak[kind] = max(self.peak[kind], self.active[kind])
+        self._wake(kind)
+        released = False
+
+        def release():
+            nonlocal released
+            if not released:
+                released = True
+                self.active[kind] -= 1
+                self._wake(kind)
+        return release
+
+    def _wake(self, kind):
+        for wake in list(self.waiters[kind].values())[:self.limits[kind] - self.active[kind]]:
+            wake()
+
+    def cancel(self, owner):
+        for kind in self.limits:
+            if self.waiters[kind].pop(owner, None) is not None:
+                self._wake(kind)
+
+    def waiting(self, owner):
+        return any(owner in q for q in self.waiters.values())

annoscript/_env.py

@@ -0,0 +1,19 @@
+"""Canonical ANNO configuration with legacy LEV input compatibility."""
+
+import os
+
+
+def normalize(values):
+    """Normalize one configuration layer before merging higher-priority layers."""
+    result = dict(values)
+    for name, value in values.items():
+        if name.startswith("LEV_"):
+            result.setdefault("ANNO_" + name[4:], value)
+    return result
+
+
+def env_value(name, default=None, *, environ=None):
+    values = os.environ if environ is None else environ
+    if name in values:
+        return values[name]
+    return values.get("LEV_" + name[5:], default)

annoscript/_examples.py

@@ -0,0 +1,34 @@
+"""Portable example data; this module has no runtime/backend dependencies."""
+
+from dataclasses import dataclass
+
+from annoscript._data import freeze, snapshot, thaw
+
+
+def example_data(state, answer):
+    """The closed ``example`` intrinsic: return detached, finite JSON data."""
+    return {"state": snapshot(state, state=True), "answer": snapshot(answer)}
+
+
+@dataclass(frozen=True)
+class Example:
+    """An input and its task answer, using the enclosing operation's parameters.
+
+    Answers contain only the business value, never confidence or probabilities.
+    Nested values are immutable snapshots. Compiled examples carry ordinary JSON,
+    not Python objects. Task/criteria overrides are intentionally unsupported.
+    """
+
+    state: object
+    answer: object
+
+    def __post_init__(self):
+        data = example_data(self.state, self.answer)
+        object.__setattr__(self, "state", freeze(data["state"]))
+        object.__setattr__(self, "answer", freeze(data["answer"]))
+
+    def to_dict(self):
+        return {"state": thaw(self.state), "answer": thaw(self.answer)}
+
+    def __deepcopy__(self, memo):
+        return self

annoscript/_expressions.py

@@ -0,0 +1,93 @@
+"""Closed expression interpreter for the runtime's value bindings."""
+
+import json
+import operator
+
+from annoscript import ir
+from annoscript._examples import example_data
+from annoscript.backends.base import RESPONSE_TYPES
+
+
+_COMPARE = {
+    "eq": operator.eq, "ne": operator.ne, "lt": operator.lt, "le": operator.le,
+    "gt": operator.gt, "ge": operator.ge, "in": lambda a, b: a in b,
+    "not_in": lambda a, b: a not in b, "is": operator.is_, "is_not": operator.is_not,
+}
+
+
+def expression(node, env, state, allocations=None):
+    ev = lambda e: expression(e, env, state, allocations)
+    def allocated(value):
+        if allocations is not None and type(value) in (list, dict):
+            allocations[id(value)] = value
+        return value
+    if isinstance(node, ir.Literal):
+        return node.value
+    if isinstance(node, ir.Var):
+        return env[node.name]
+    if isinstance(node, ir.State):
+        return state
+    if isinstance(node, ir.GetItem):
+        return ev(node.value)[ev(node.index)]
+    if isinstance(node, ir.Field):
+        value = ev(node.value)
+        if type(value) not in RESPONSE_TYPES.values() or node.name not in value.__dataclass_fields__:
+            raise ValueError("field access requires a response field")
+        return getattr(value, node.name)
+    if isinstance(node, ir.ListExpr):
+        return allocated([ev(x) for x in node.items])
+    if isinstance(node, ir.TupleExpr):
+        return tuple(ev(x) for x in node.items)
+    if isinstance(node, ir.DictExpr):
+        return allocated({ev(k): ev(v) for k, v in node.entries})
+    if isinstance(node, ir.Unary):
+        return {"not": operator.not_, "negative": operator.neg, "positive": operator.pos}[node.op](ev(node.value))
+    if isinstance(node, ir.Binary):
+        return allocated(ev(node.left) + ev(node.right))
+    if isinstance(node, ir.Compare):
+        left = ev(node.left)
+        for op, other in zip(node.ops, node.comparators):
+            right = ev(other)
+            if not _COMPARE[op](left, right):
+                return False
+            left = right
+        return True
+    if isinstance(node, ir.BoolOp):
+        value = ev(node.values[0])
+        for other in node.values[1:]:
+            if (node.op == "and" and not value) or (node.op == "or" and value):
+                break
+            value = ev(other)
+        return value
+    if isinstance(node, ir.Intrinsic):
+        fn = {"len": len, "int": int, "range": range, "enumerate": enumerate,
+              "str.strip": str.strip, "json.dumps": json.dumps,
+              "example": example_data}[node.name]
+        return fn(*[ev(x) for x in node.args], **{k: ev(v) for k, v in node.kwargs})
+    if isinstance(node, ir.FormatValue):
+        value = ev(node.value)
+        spec = ev(node.spec) if node.spec is not None else ""
+        if node.conversion != "none":
+            value = {"s": str, "r": repr, "a": ascii}[node.conversion](value)
+        return format(value, spec)
+    if isinstance(node, ir.FormatString):
+        return "".join(ev(x) for x in node.parts)
+    raise ValueError("unsupported expression")
+
+
+def unpack(target, value):
+    if isinstance(target, ir.NameTarget):
+        return [value]
+    # Consume at most one extra item, just like exact Python unpacking.
+    it = iter(value)
+    values = []
+    for _ in target.items:
+        try:
+            values.append(next(it))
+        except StopIteration:
+            raise ValueError("not enough values to unpack") from None
+    try:
+        next(it)
+    except StopIteration:
+        return [v for t, item in zip(target.items, values) for v in unpack(t, item)]
+    raise ValueError("too many values to unpack")