surveycore-py 0.1.0__py3-none-any.whl

surveycore/core/engine/async_events.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+from surveycore.core.task import ExecutionState
+
+
+class AsyncRunContext:
+    
+
+    def __init__(
+        self,
+        *,
+        state: ExecutionState,
+        stop_event: asyncio.Event,
+        pause_event: asyncio.Event,
+        status_sink: Optional[Callable[[dict[str, Any]], None]] = None,
+    ) -> None:
+        self.state = state
+        self.stop_event = stop_event
+        self.pause_event = pause_event
+        self.status_sink = status_sink
+
+    def stop_requested(self) -> bool:
+        return bool(self.stop_event.is_set())
+
+    async def wait_if_paused(self) -> None:
+        while self.pause_event.is_set() and not self.stop_event.is_set():
+            await asyncio.sleep(0.1)
+
+    def emit(self, event: dict[str, Any]) -> None:
+        sink = self.status_sink
+        if callable(sink):
+            sink(dict(event or {}))
+
+
+class ThreadEventProxy:
+    
+
+    def __init__(self, event: asyncio.Event, *, loop: asyncio.AbstractEventLoop) -> None:
+        self._event = event
+        self._loop = loop
+
+    def is_set(self) -> bool:
+        return bool(self._event.is_set())
+
+    def set(self) -> None:
+        if self._loop.is_closed():
+            return
+        self._loop.call_soon_threadsafe(self._event.set)
+
+    def clear(self) -> None:
+        if self._loop.is_closed():
+            return
+        self._loop.call_soon_threadsafe(self._event.clear)
+
+    def wait(self, timeout: Optional[float] = None) -> bool:
+        if self.is_set():
+            return True
+        try:
+            running_loop = asyncio.get_running_loop()
+        except RuntimeError:
+            running_loop = None
+        if running_loop is self._loop:
+            raise RuntimeError("ThreadEventProxy.wait() 不能在绑定的事件循环线程里阻塞调用")
+
+        async def _wait() -> bool:
+            try:
+                if timeout is None:
+                    await self._event.wait()
+                    return True
+                await asyncio.wait_for(self._event.wait(), timeout=max(0.0, float(timeout)))
+                return True
+            except asyncio.TimeoutError:
+                return bool(self._event.is_set())
+
+        future = asyncio.run_coroutine_threadsafe(_wait(), self._loop)
+        return bool(future.result())
+
+
+@dataclass(frozen=True)
+class AsyncSlotResult:
+    slot_id: int
+    completed: bool
+    error: Optional[BaseException] = None
+
+
+__all__ = ["AsyncRunContext", "AsyncSlotResult", "ThreadEventProxy"]

surveycore/core/engine/async_scheduler.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import asyncio
+import heapq
+import itertools
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(order=True)
+class _ScheduledToken:
+    ready_at: float
+    order: int
+    token_id: int = field(compare=False)
+
+
+class AsyncScheduler:
+    
+
+    def __init__(self, *, concurrency: int) -> None:
+        self._concurrency = max(1, int(concurrency or 1))
+        self._ready: deque[int] = deque()
+        self._delayed: list[_ScheduledToken] = []
+        self._order = itertools.count()
+        self._condition = asyncio.Condition()
+        self._closed = False
+        self._waker_task: Optional[asyncio.Task[None]] = None
+        for token_id in range(self._concurrency):
+            self._ready.append(token_id)
+
+    async def start(self) -> None:
+        if self._waker_task is None:
+            self._waker_task = asyncio.create_task(self._wake_delayed_tokens(), name="AsyncSchedulerWake")
+
+    async def acquire(self) -> Optional[int]:
+        await self.start()
+        async with self._condition:
+            while True:
+                if self._closed:
+                    return None
+                if self._ready:
+                    return self._ready.popleft()
+                await self._condition.wait()
+
+    async def release(self, token_id: int, *, requeue: bool, delay_seconds: float = 0.0) -> None:
+        if not requeue:
+            return
+        delay = max(0.0, float(delay_seconds or 0.0))
+        async with self._condition:
+            if self._closed:
+                return
+            if delay <= 0:
+                self._ready.append(int(token_id))
+                self._condition.notify_all()
+                return
+            heapq.heappush(
+                self._delayed,
+                _ScheduledToken(time.monotonic() + delay, next(self._order), int(token_id)),
+            )
+            self._condition.notify_all()
+
+    async def _wake_delayed_tokens(self) -> None:
+        while True:
+            async with self._condition:
+                if self._closed:
+                    return
+                now = time.monotonic()
+                moved = False
+                while self._delayed and self._delayed[0].ready_at <= now:
+                    token = heapq.heappop(self._delayed)
+                    self._ready.append(token.token_id)
+                    moved = True
+                if moved:
+                    self._condition.notify_all()
+                    continue
+                sleep_for = 0.1
+                if self._delayed:
+                    sleep_for = min(0.1, max(0.0, self._delayed[0].ready_at - now))
+            try:
+                await asyncio.sleep(sleep_for)
+            except asyncio.CancelledError:
+                break
+
+    async def close(self) -> None:
+        self._closed = True
+        if self._waker_task is not None:
+            self._waker_task.cancel()
+            await asyncio.gather(self._waker_task, return_exceptions=True)
+            self._waker_task = None
+        async with self._condition:
+            self._condition.notify_all()
+
+
+__all__ = ["AsyncScheduler"]

surveycore/core/engine/async_status_bus.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections import defaultdict
+from typing import Any, Callable, DefaultDict, Optional
+
+
+class AsyncStatusBus:
+    
+
+    def __init__(
+        self,
+        *,
+        dispatcher: Optional[Callable[[Callable[[], Any]], Any]] = None,
+        throttle_seconds: float = 0.075,
+    ) -> None:
+        self._dispatcher = dispatcher
+        self._throttle_seconds = max(0.0, float(throttle_seconds or 0.0))
+        self._lock = threading.Lock()
+        self._sequence_by_slot: DefaultDict[str, int] = defaultdict(int)
+        self._last_emit_by_slot: dict[str, float] = {}
+
+    def emit(self, event: dict[str, Any]) -> None:
+        payload = dict(event or {})
+        slot_id = str(payload.get("slot_id") or payload.get("slot_label") or "global")
+        now = time.monotonic()
+        with self._lock:
+            self._sequence_by_slot[slot_id] += 1
+            payload["sequence"] = self._sequence_by_slot[slot_id]
+            event_type = str(payload.get("type") or "")
+            high_frequency = event_type in {"progress", "status"}
+            last_emit = self._last_emit_by_slot.get(slot_id, 0.0)
+            if high_frequency and self._throttle_seconds > 0 and (now - last_emit) < self._throttle_seconds:
+                return
+            self._last_emit_by_slot[slot_id] = now
+
+        dispatcher = self._dispatcher
+        if not callable(dispatcher):
+            return
+
+        def _deliver() -> None:
+            callback = payload.get("callback")
+            if callable(callback):
+                callback()
+
+        dispatcher(_deliver)
+
+
+__all__ = ["AsyncStatusBus"]

surveycore/core/engine/async_wait.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Optional
+
+
+def is_stop_requested(stop_signal: Any) -> bool:
+    if stop_signal is None:
+        return False
+    checker = getattr(stop_signal, "is_set", None)
+    if callable(checker):
+        try:
+            return bool(checker())
+        except Exception:
+            return False
+    return False
+
+
+def _resolve_async_event(stop_signal: Any) -> Optional[asyncio.Event]:
+    if isinstance(stop_signal, asyncio.Event):
+        return stop_signal
+    event = getattr(stop_signal, "_event", None)
+    if isinstance(event, asyncio.Event):
+        return event
+    return None
+
+
+async def sleep_or_stop(stop_signal: Any, seconds: float) -> bool:
+    delay = max(0.0, float(seconds or 0.0))
+    if delay <= 0:
+        return is_stop_requested(stop_signal)
+
+    async_event = _resolve_async_event(stop_signal)
+    if async_event is not None:
+        if async_event.is_set():
+            return True
+        try:
+            await asyncio.wait_for(async_event.wait(), timeout=delay)
+            return True
+        except asyncio.TimeoutError:
+            return bool(async_event.is_set())
+
+    if stop_signal is None:
+        await asyncio.sleep(delay)
+        return False
+
+    waiter = getattr(stop_signal, "wait", None)
+    if callable(waiter):
+        try:
+            return bool(await asyncio.to_thread(waiter, delay))
+        except Exception:
+            pass
+
+    await asyncio.sleep(delay)
+    return is_stop_requested(stop_signal)
+
+
+__all__ = ["is_stop_requested", "sleep_or_stop"]

surveycore/core/engine/provider_common.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from typing import Any, Dict, Iterator, List, Optional
+
+from surveycore.core.persona.context import reset_context as _reset_answer_context
+from surveycore.core.persona.generator import generate_persona, reset_persona, set_current_persona
+from surveycore.core.psychometrics import (
+    CombinedPsychometricPlan,
+    build_dimension_psychometric_plan,
+    build_joint_psychometric_answer_plan,
+    build_psychometric_blueprint,
+)
+from surveycore.core.psychometrics.psychometric import normalize_target_alpha
+from surveycore.core.questions.config import GLOBAL_RELIABILITY_DIMENSION
+from surveycore.core.questions.consistency import reset_consistency_context
+from surveycore.core.questions.tendency import reset_tendency
+from surveycore.core.task import ExecutionConfig, ExecutionState
+
+
+def _build_grouped_runtime_items(
+    config: ExecutionConfig,
+) -> Dict[str, List[Any]]:
+    grouped_items: Dict[str, List[Any]] = {}
+    for dimension, items in build_psychometric_blueprint(config).items():
+        normalized_dimension = str(dimension or "").strip()
+        if not normalized_dimension:
+            continue
+        bucket = grouped_items.setdefault(normalized_dimension, [])
+        for item in items:
+            bucket.append(item.to_runtime_item())
+    return grouped_items
+
+
+def build_psychometric_plan_for_run(config: ExecutionConfig) -> Optional[Any]:
+    
+    grouped_items = _build_grouped_runtime_items(config)
+
+    if not grouped_items:
+        return None
+
+    try:
+        target_alpha = normalize_target_alpha(getattr(config, "psycho_target_alpha", None))
+    except Exception:
+        target_alpha = normalize_target_alpha(None)
+
+    return build_dimension_psychometric_plan(
+        grouped_items=grouped_items,
+        target_alpha=target_alpha,
+    )
+
+
+def ensure_joint_psychometric_answer_plan(config: ExecutionConfig) -> Optional[Any]:
+    cached = getattr(config, "joint_psychometric_answer_plan", None)
+    if cached is not None:
+        return cached
+    plan = build_joint_psychometric_answer_plan(config)
+    config.joint_psychometric_answer_plan = plan
+    return plan
+
+
+@contextmanager
+def provider_run_context(
+    config: ExecutionConfig,
+    *,
+    state: Optional[ExecutionState] = None,
+    thread_name: str = "",
+    psycho_plan: Optional[Any] = None,
+) -> Iterator[Optional[Any]]:
+    
+    persona = generate_persona()
+    set_current_persona(persona)
+    _reset_answer_context()
+    reset_tendency()
+    reset_consistency_context(config.answer_rules, list((config.questions_metadata or {}).values()))
+
+    resolved_plan = psycho_plan
+    fallback_plan: Optional[Any] = None
+    joint_sample_plan: Optional[Any] = None
+    reserved_sample_index: Optional[int] = None
+    if resolved_plan is None:
+        fallback_plan = build_psychometric_plan_for_run(config)
+        joint_answer_plan = ensure_joint_psychometric_answer_plan(config)
+        if joint_answer_plan is not None and state is not None:
+            reserved_sample_index = state.peek_reserved_joint_sample(thread_name)
+            if reserved_sample_index is not None:
+                joint_sample_plan = joint_answer_plan.build_sample_plan(reserved_sample_index)
+            else:
+                logging.warning("线程[%s]存在联合信效度计划但未预留样本槽位，已回退常规逻辑", thread_name or "Worker-?")
+        if joint_sample_plan is not None and fallback_plan is not None:
+            resolved_plan = CombinedPsychometricPlan(primary=joint_sample_plan, fallback=fallback_plan)
+        elif joint_sample_plan is not None:
+            resolved_plan = joint_sample_plan
+        else:
+            resolved_plan = fallback_plan
+
+    if joint_sample_plan is not None:
+        diagnostics = dict(getattr(joint_sample_plan, "diagnostics_by_dimension", {}) or {})
+        active_dimensions = [
+            name
+            for name, diagnostic in diagnostics.items()
+            if not bool(getattr(diagnostic, "skipped", False))
+        ]
+        logging.debug(
+            "本轮启用联合信效度计划：样本槽位=%d，维度数=%d，锁定题目数=%d，目标α=%.2f，维度=%s",
+            int(reserved_sample_index or 0) + 1,
+            len(active_dimensions),
+            len(getattr(joint_sample_plan, "choices", {}) or {}),
+            float(getattr(config, "psycho_target_alpha", 0.85) or 0.85),
+            ",".join(active_dimensions[:5]) if active_dimensions else "无",
+        )
+        for diagnostic in diagnostics.values():
+            if bool(getattr(diagnostic, "skipped", False)):
+                continue
+            if not bool(getattr(diagnostic, "degraded_for_ratio", False)):
+                continue
+            logging.warning(
+                "维度[%s]已保比例优先，实际α=%.3f 低于目标α=%.3f，主方向=%s，反向题=%d，锚点明确=%s",
+                getattr(diagnostic, "dimension", ""),
+                float(getattr(diagnostic, "actual_alpha", 0.0) or 0.0),
+                float(getattr(diagnostic, "target_alpha", 0.0) or 0.0),
+                str(getattr(diagnostic, "anchor_direction", "center") or "center"),
+                int(getattr(diagnostic, "reverse_item_count", 0) or 0),
+                "否" if bool(getattr(diagnostic, "ambiguous_anchor", False)) else "是",
+            )
+    elif resolved_plan is not None:
+        dimension_count = len(getattr(resolved_plan, "plans", {}) or {})
+        plan_names = list((getattr(resolved_plan, "plans", {}) or {}).keys())
+        if plan_names == [GLOBAL_RELIABILITY_DIMENSION]:
+            dimension_summary = "全局未分组问卷"
+        else:
+            dimension_summary = ",".join(plan_names[:5]) if plan_names else "无"
+        logging.info(
+            "本轮启用心理测量计划：维度数=%d，题目数=%d，目标α=%.2f，维度=%s",
+            dimension_count,
+            len(getattr(resolved_plan, "items", []) or []),
+            float(getattr(config, "psycho_target_alpha", 0.85) or 0.85),
+            dimension_summary,
+        )
+
+    try:
+        yield resolved_plan
+    finally:
+        reset_persona()
+__all__ = [
+    "build_psychometric_plan_for_run",
+    "ensure_joint_psychometric_answer_plan",
+    "provider_run_context",
+]

surveycore/core/engine/runtime_actions.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Iterable, Optional, Tuple
+
+
+class RuntimeActionKind(str, Enum):
+    PAUSE_RUN = "pause_run"
+    SHOW_MESSAGE = "show_message"
+    CONFIRM_ENABLE_RANDOM_IP = "confirm_enable_random_ip"
+    SET_RANDOM_IP_ENABLED = "set_random_ip_enabled"
+    REFRESH_RANDOM_IP_COUNTER = "refresh_random_ip_counter"
+
+
+@dataclass(frozen=True)
+class RuntimeActionRequest:
+    kind: RuntimeActionKind
+    title: str = ""
+    message: str = ""
+    level: str = "info"
+    reason: str = ""
+    enabled: Optional[bool] = None
+
+
+@dataclass(frozen=True)
+class RuntimeActionResult:
+    actions: Tuple[RuntimeActionRequest, ...] = ()
+    should_stop: bool = False
+
+    @classmethod
+    def empty(cls) -> "RuntimeActionResult":
+        return cls()
+
+    @classmethod
+    def from_actions(
+        cls,
+        actions: Iterable[RuntimeActionRequest],
+        *,
+        should_stop: bool = False,
+    ) -> "RuntimeActionResult":
+        return cls(tuple(actions or ()), bool(should_stop))
+
+
+def ensure_runtime_action_result(value: object) -> RuntimeActionResult:
+    if isinstance(value, RuntimeActionResult):
+        return value
+    if value is None:
+        return RuntimeActionResult.empty()
+    if isinstance(value, RuntimeActionRequest):
+        return RuntimeActionResult((value,))
+    if isinstance(value, (list, tuple)):
+        actions = tuple(item for item in value if isinstance(item, RuntimeActionRequest))
+        return RuntimeActionResult(actions)
+    return RuntimeActionResult.empty()
+
+
+__all__ = [
+    "RuntimeActionKind",
+    "RuntimeActionRequest",
+    "RuntimeActionResult",
+    "ensure_runtime_action_result",
+]

surveycore/core/engine/stop_signal.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Optional, Protocol
+
+
+class StopSignalLike(Protocol):
+    def is_set(self) -> bool: ...
+
+    def set(self) -> None: ...
+
+    def wait(self, timeout: Optional[float] = None) -> bool: ...
+
+
+__all__ = ["StopSignalLike"]

surveycore/core/modes/__init__.py

@@ -0,0 +1 @@
+__all__: list[str] = []