surveycore-py 0.1.0__py3-none-any.whl

surveycore/__init__.py

@@ -0,0 +1,44 @@
+from importlib.metadata import version as _distribution_version
+
+from .client import SurveyClient
+from .config import deserialize_config, dumps_config, loads_config, serialize_config
+from .errors import (
+    ConfigError,
+    SubmissionError,
+    SurveyCoreError,
+    SurveyParseError,
+    SurveyUnavailableError,
+    UnsupportedSurveyError,
+)
+from .models import (
+    AnswerGenerator,
+    QuestionConfig,
+    RunConfig,
+    SubmissionRequest,
+    SubmissionResult,
+    SurveyDefinition,
+    SurveyQuestion,
+)
+
+__version__ = _distribution_version("surveycore-py")
+
+__all__ = [
+    "AnswerGenerator",
+    "ConfigError",
+    "QuestionConfig",
+    "RunConfig",
+    "SubmissionError",
+    "SubmissionRequest",
+    "SubmissionResult",
+    "SurveyClient",
+    "SurveyCoreError",
+    "SurveyDefinition",
+    "SurveyParseError",
+    "SurveyQuestion",
+    "SurveyUnavailableError",
+    "UnsupportedSurveyError",
+    "deserialize_config",
+    "dumps_config",
+    "loads_config",
+    "serialize_config",
+]

surveycore/_question_metas.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .models import SurveyQuestion
+from .providers.contracts import SurveyQuestionMeta
+
+
+def to_question_metas(questions: Iterable[SurveyQuestion]) -> list[SurveyQuestionMeta]:
+    return [
+        SurveyQuestionMeta(
+            num=int(question.num),
+            title=str(question.title),
+            type_code=str(question.type_code),
+            options=int(question.options),
+            rows=int(question.rows),
+            option_texts=list(question.option_texts),
+            row_texts=list(question.row_texts),
+            page=int(question.page),
+            provider_question_id=str(question.provider_question_id),
+            provider_page_id=str(question.provider_page_id),
+            required=bool(question.required),
+            display_num=question.display_num,
+            description=question.description,
+            forced_option_index=question.forced_option_index,
+            forced_option_text=question.forced_option_text,
+            forced_texts=list(question.forced_texts),
+            fillable_options=list(question.fillable_options),
+            attached_option_selects=[dict(item) for item in question.attached_option_selects],
+            has_attached_option_select=question.has_attached_option_select,
+            rating_max=question.rating_max,
+            text_inputs=question.text_inputs,
+            text_input_labels=list(question.text_input_labels),
+            is_multi_text=question.is_multi_text,
+            question_media=[dict(item) for item in question.question_media],
+            slider_min=question.slider_min,
+            slider_max=question.slider_max,
+            slider_step=question.slider_step,
+            multi_min_limit=question.multi_min_limit,
+            multi_max_limit=question.multi_max_limit,
+            provider_type=question.provider_type,
+            provider_page_raw=question.provider_page_raw,
+            is_text_like=bool(question.is_text_like),
+            is_location=bool(question.is_location),
+            is_description=bool(question.is_description),
+            is_rating=bool(question.is_rating),
+            is_slider_matrix=bool(question.is_slider_matrix),
+            has_jump=bool(question.has_jump),
+            jump_rules=[dict(item) for item in question.jump_rules],
+            has_display_condition=bool(question.has_display_condition),
+            display_conditions=[dict(item) for item in question.display_conditions],
+            has_dependent_display_logic=bool(question.has_dependent_display_logic),
+            controls_display_targets=[dict(item) for item in question.controls_display_targets],
+            logic_parse_status=str(question.logic_parse_status),
+            unsupported=bool(question.unsupported),
+            unsupported_reason=str(question.unsupported_reason),
+        )
+        for question in questions
+    ]

surveycore/answers/__init__.py

@@ -0,0 +1,5 @@
+"""Answer strategy extension points."""
+
+from .strategies import choose_weighted, limit_multiple_selection
+
+__all__ = ["choose_weighted", "limit_multiple_selection"]

surveycore/answers/strategies.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import random
+from collections.abc import Sequence
+
+
+def choose_weighted(weights: Sequence[float], *, rng: random.Random | None = None) -> int:
+    """Return an index using non-negative relative weights."""
+    values = [max(0.0, float(value)) for value in weights]
+    if not values or sum(values) <= 0:
+        raise ValueError("至少需要一个正权重")
+    picker = rng or random
+    return picker.choices(range(len(values)), weights=values, k=1)[0]
+
+
+def limit_multiple_selection(indices: Sequence[int], *, minimum: int = 1, maximum: int | None = None) -> tuple[int, ...]:
+    """Normalize multiple-choice selections to a bounded, duplicate-free tuple."""
+    unique = tuple(dict.fromkeys(int(index) for index in indices))
+    if len(unique) < minimum:
+        raise ValueError("多选答案少于最小选择数")
+    if maximum is not None and len(unique) > maximum:
+        return unique[:maximum]
+    return unique

surveycore/app/__init__.py

@@ -0,0 +1 @@
+"""Small compatibility surface used by the migrated provider core."""

surveycore/app/config.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import re
+
+USER_AGENT_PRESETS = {
+    "pc_web": {
+        "label": "电脑网页端",
+        "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+    },
+    "mobile_android": {
+        "label": "安卓手机浏览器",
+        "ua": "Mozilla/5.0 (Linux; Android 16; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Mobile Safari/537.36",
+    },
+    "wechat_android": {
+        "label": "安卓微信端",
+        "ua": "Mozilla/5.0 (Linux; Android 16; Pixel 8; wv) AppleWebKit/537.36 Version/4.0 Chrome/121.0.0.0 Mobile Safari/537.36 MicroMessenger/8.0.43",
+    },
+}
+DEFAULT_USER_AGENT = USER_AGENT_PRESETS["pc_web"]["ua"]
+DEFAULT_HTTP_HEADERS = {
+    "User-Agent": DEFAULT_USER_AGENT,
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+}
+DEFAULT_FILL_TEXT = "无"
+DIMENSION_UNGROUPED = "未分组"
+_HTML_SPACE_RE = re.compile(r"\s+")
+STOP_FORCE_WAIT_SECONDS = 0.3

surveycore/app/runtime_paths.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from importlib.resources import files
+
+
+def get_resource_path(relative_path: str) -> str:
+    """Return a packaged resource path for legacy helpers."""
+    path = files("surveycore").joinpath(str(relative_path).replace("\\", "/"))
+    return str(path)
+
+
+def get_assets_directory() -> str:
+    return str(files("surveycore").joinpath("data"))
+
+
+__all__ = ["get_resource_path", "get_assets_directory"]

surveycore/app/user_paths.py

@@ -0,0 +1,2 @@
+def get_user_logs_directory() -> str:
+    return ""

surveycore/client.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from collections.abc import AsyncIterator
+from dataclasses import replace
+from typing import Any
+
+import httpx
+
+from .core.questions.config import (
+    QuestionEntry,
+    build_default_question_entries,
+    configure_probabilities,
+)
+from .core.task import ExecutionConfig, ExecutionState
+from .errors import SurveyParseError, SurveyUnavailableError, UnsupportedSurveyError
+from .models import (
+    RunConfig,
+    SubmissionRequest,
+    SubmissionResult,
+    SurveyDefinition,
+    SurveyQuestion,
+)
+from .network.http import bind
+from .providers.common import (
+    detect_survey_provider,
+    normalize_survey_parse_url,
+)
+from .providers.registry import fill_survey_http, parse_survey
+from .runtime import completed_results
+from .transport import require_async_client
+
+
+def _question_from_meta(item: Any) -> SurveyQuestion:
+    def dicts(value: Any) -> tuple[dict[str, Any], ...]:
+        return tuple(dict(entry) for entry in list(value or []) if isinstance(entry, dict))
+
+    return SurveyQuestion(
+        num=int(getattr(item, "num", 0) or 0),
+        title=str(getattr(item, "title", "") or ""),
+        type_code=str(getattr(item, "type_code", "0") or "0"),
+        provider_question_id=str(getattr(item, "provider_question_id", "") or ""),
+        provider_page_id=str(getattr(item, "provider_page_id", "") or ""),
+        options=int(getattr(item, "options", 0) or 0),
+        rows=int(getattr(item, "rows", 1) or 1),
+        option_texts=tuple(str(value or "") for value in list(getattr(item, "option_texts", []) or [])),
+        row_texts=tuple(str(value or "") for value in list(getattr(item, "row_texts", []) or [])),
+        page=int(getattr(item, "page", 1) or 1),
+        required=bool(getattr(item, "required", False)),
+        display_num=getattr(item, "display_num", None),
+        description=str(getattr(item, "description", "") or ""),
+        forced_option_index=getattr(item, "forced_option_index", None),
+        forced_option_text=str(getattr(item, "forced_option_text", "") or ""),
+        forced_texts=tuple(str(v or "") for v in (getattr(item, "forced_texts", []) or [])),
+        fillable_options=tuple(int(v) for v in (getattr(item, "fillable_options", []) or [])),
+        attached_option_selects=dicts(getattr(item, "attached_option_selects", [])),
+        has_attached_option_select=bool(getattr(item, "has_attached_option_select", False)),
+        rating_max=int(getattr(item, "rating_max", 0) or 0),
+        text_inputs=int(getattr(item, "text_inputs", 0) or 0),
+        text_input_labels=tuple(str(v or "") for v in (getattr(item, "text_input_labels", []) or [])),
+        is_multi_text=bool(getattr(item, "is_multi_text", False)),
+        question_media=dicts(getattr(item, "question_media", [])),
+        slider_min=getattr(item, "slider_min", None),
+        slider_max=getattr(item, "slider_max", None),
+        slider_step=getattr(item, "slider_step", None),
+        multi_min_limit=getattr(item, "multi_min_limit", None),
+        multi_max_limit=getattr(item, "multi_max_limit", None),
+        provider_type=str(getattr(item, "provider_type", "") or ""),
+        provider_page_raw=getattr(item, "provider_page_raw", None),
+        is_text_like=bool(getattr(item, "is_text_like", False)),
+        is_location=bool(getattr(item, "is_location", False)),
+        is_description=bool(getattr(item, "is_description", False)),
+        is_rating=bool(getattr(item, "is_rating", False)),
+        is_slider_matrix=bool(getattr(item, "is_slider_matrix", False)),
+        has_jump=bool(getattr(item, "has_jump", False)),
+        jump_rules=dicts(getattr(item, "jump_rules", [])),
+        has_display_condition=bool(getattr(item, "has_display_condition", False)),
+        display_conditions=dicts(getattr(item, "display_conditions", [])),
+        has_dependent_display_logic=bool(getattr(item, "has_dependent_display_logic", False)),
+        controls_display_targets=dicts(getattr(item, "controls_display_targets", [])),
+        logic_parse_status=str(getattr(item, "logic_parse_status", "unknown") or "unknown"),
+        unsupported=bool(getattr(item, "unsupported", False)),
+        unsupported_reason=str(getattr(item, "unsupported_reason", "") or ""),
+    )
+
+
+class SurveyClient:
+    """Async survey parser and HTTP submitter using a caller-owned client."""
+
+    def __init__(self, http_client: httpx.AsyncClient) -> None:
+        self.http_client = require_async_client(http_client)
+
+    @staticmethod
+    def _resolve_provider(config: RunConfig) -> str:
+        detected = detect_survey_provider(config.url, default="")
+        provider = config.provider or detected
+        if provider not in {"wjx", "qq", "credamo"}:
+            raise UnsupportedSurveyError(f"不支持的问卷平台：{provider or config.url}")
+        if config.provider and detected and config.provider != detected:
+            raise UnsupportedSurveyError(f"问卷链接平台与配置不一致：{config.provider} != {detected}")
+        return provider
+
+    async def parse(self, url: str) -> SurveyDefinition:
+        normalized = normalize_survey_parse_url(url)
+        provider = detect_survey_provider(normalized, default="")
+        if not provider:
+            raise UnsupportedSurveyError(f"不支持的问卷链接：{url}")
+        try:
+            async with bind(self.http_client):
+                definition = await parse_survey(normalized)
+        except (UnsupportedSurveyError, SurveyUnavailableError):
+            raise
+        except Exception as exc:
+            message = str(exc) or "问卷解析失败"
+            if any(marker in message for marker in ("未开放", "已停止", "已暂停", "到期")):
+                raise SurveyUnavailableError(message) from exc
+            raise SurveyParseError(message) from exc
+        questions = tuple(_question_from_meta(item) for item in definition.questions)
+        return SurveyDefinition(provider=definition.provider, title=definition.title, url=normalized, questions=questions)
+
+    def _execution_config(self, config: RunConfig, survey: SurveyDefinition | None) -> ExecutionConfig:
+        provider = self._resolve_provider(config)
+        from ._question_metas import to_question_metas
+        legacy_questions = to_question_metas(survey.questions if survey else ())
+        entries: list[QuestionEntry] = [QuestionEntry(**{
+            key: getattr(item, key) for key in QuestionEntry.__dataclass_fields__
+            if hasattr(item, key)
+        }) for item in config.questions]
+        if not entries and legacy_questions:
+            entries = list(build_default_question_entries(legacy_questions, survey_url=config.url, existing_entries=[]))
+        execution = ExecutionConfig(
+            url=str(config.url or ""),
+            survey_provider=provider,
+            target_num=max(1, int(config.target)),
+            num_threads=max(1, int(config.concurrency)),
+            answer_duration_range_seconds=(config.answer_duration[0], config.answer_duration[1]),
+            submit_interval_range_seconds=(config.submit_interval[0], config.submit_interval[1]),
+            random_user_agent_enabled=bool(config.random_user_agent),
+            user_agent_ratios=dict(config.user_agent_ratios),
+            answer_rules=list(config.answer_rules),
+            psycho_target_alpha=float(config.target_alpha),
+            stop_on_fail_enabled=False,
+            pause_on_aliyun_captcha=False,
+        )
+        execution.answer_generator = config.answer_generator  # type: ignore[attr-defined]
+        execution.question_entries = entries  # type: ignore[attr-defined]
+        execution.questions_metadata = {int(item.num): item for item in legacy_questions if int(getattr(item, "num", 0) or 0) > 0}
+        configure_probabilities(entries, execution, reliability_mode_enabled=bool(config.reliability_mode))
+        return execution
+
+    async def submit(self, request: SubmissionRequest | RunConfig) -> SubmissionResult:
+        config = request.config if isinstance(request, SubmissionRequest) else request
+        survey = request.survey if isinstance(request, SubmissionRequest) else None
+        started = time.perf_counter()
+        provider = self._resolve_provider(config)
+        execution = self._execution_config(config, survey)
+        state = ExecutionState(config=execution)
+        try:
+            async with bind(self.http_client):
+                success = await fill_survey_http(
+                    execution,
+                    state,
+                    stop_signal=asyncio.Event(),
+                    thread_name="surveycore",
+                    provider=provider,
+                )
+        except Exception as exc:  # noqa: BLE001 - one attempt must become one failed result
+            return SubmissionResult(0, provider, False, time.perf_counter() - started, str(exc) or "提交失败")
+        return SubmissionResult(0, provider, bool(success), time.perf_counter() - started, None if success else "平台未确认提交成功")
+
+    async def run(self, config: RunConfig) -> AsyncIterator[SubmissionResult]:
+        survey = await self.parse(config.url)
+        async def attempt(index: int) -> SubmissionResult:
+            if index > 1:
+                low, high = config.submit_interval
+                if high > 0:
+                    await asyncio.sleep(random.uniform(low, high))
+            result = await self.submit(SubmissionRequest(config=replace(config, target=1), survey=survey))
+            return replace(result, attempt=index)
+
+        async for result in completed_results(config.target, config.concurrency, attempt):
+            yield result
+
+
+__all__ = ["SurveyClient"]

surveycore/config.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import json
+from dataclasses import fields
+from typing import Any
+
+from .errors import ConfigError
+from .models import QuestionConfig, RunConfig
+
+SCHEMA_VERSION = 1
+_RUN_FIELDS = {field.name for field in fields(RunConfig) if field.name != "answer_generator"}
+_QUESTION_FIELDS = {
+    field.name for field in fields(QuestionConfig)
+    if field.name != "ai_enabled"
+}
+
+
+def _reject_unknown(payload: dict[str, Any], allowed: set[str], label: str) -> None:
+    unknown = sorted(set(payload) - allowed)
+    if unknown:
+        raise ConfigError(f"{label}包含未知字段：{', '.join(unknown)}")
+
+
+def _range(value: Any, label: str) -> tuple[int, int]:
+    if not isinstance(value, list) or len(value) != 2:
+        raise ConfigError(f"{label}必须是两个整数组成的数组")
+    if any(isinstance(item, bool) or not isinstance(item, int) for item in value):
+        raise ConfigError(f"{label}必须是整数")
+    low, high = value
+    if low < 0 or high < low:
+        raise ConfigError(f"{label}范围无效")
+    return low, high
+
+
+def _string_range(value: Any, label: str) -> tuple[str, str]:
+    if not isinstance(value, list) or len(value) != 2 or any(not isinstance(item, str) for item in value):
+        raise ConfigError(f"{label}必须是两个字符串组成的数组")
+    return value[0], value[1]
+
+
+def _strict_bool(value: Any, label: str) -> bool:
+    if not isinstance(value, bool):
+        raise ConfigError(f"{label}必须是布尔值")
+    return value
+
+
+def _strict_float(value: Any, label: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ConfigError(f"{label}必须是数字")
+    return float(value)
+
+
+def _mapping(value: Any, label: str) -> dict[str, int]:
+    if not isinstance(value, dict) or any(not isinstance(key, str) or isinstance(item, bool) or not isinstance(item, int) for key, item in value.items()):
+        raise ConfigError(f"{label}必须是字符串到整数的对象")
+    return dict(value)
+
+
+def _list_of_dicts(value: Any, label: str) -> list[dict[str, Any]]:
+    if not isinstance(value, list) or any(not isinstance(item, dict) for item in value):
+        raise ConfigError(f"{label}必须是对象数组")
+    return [dict(item) for item in value]
+
+
+def serialize_config(config: RunConfig) -> dict[str, Any]:
+    if not isinstance(config, RunConfig):
+        raise ConfigError("只支持序列化 RunConfig")
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "url": str(config.url),
+        "questions": [{key: getattr(item, key) for key in sorted(_QUESTION_FIELDS)} for item in config.questions],
+        "target": int(config.target),
+        "concurrency": int(config.concurrency),
+        "provider": config.provider,
+        "answer_duration": list(config.answer_duration),
+        "submit_interval": list(config.submit_interval),
+        "answer_datetime_window": list(config.answer_datetime_window),
+        "random_user_agent": bool(config.random_user_agent),
+        "user_agent_ratios": dict(config.user_agent_ratios),
+        "reliability_mode": bool(config.reliability_mode),
+        "target_alpha": float(config.target_alpha),
+        "answer_rules": list(config.answer_rules),
+        "reverse_fill_enabled": bool(config.reverse_fill_enabled),
+        "reverse_fill_source_path": str(config.reverse_fill_source_path),
+        "reverse_fill_format": str(config.reverse_fill_format),
+        "reverse_fill_start_row": int(config.reverse_fill_start_row),
+        "reverse_fill_threads": int(config.reverse_fill_threads),
+    }
+
+
+def deserialize_config(payload: Any) -> RunConfig:
+    if not isinstance(payload, dict):
+        raise ConfigError("配置顶层必须是对象")
+    version = payload.get("schema_version")
+    if version != SCHEMA_VERSION:
+        raise ConfigError(f"不支持的配置 schema 版本：{version!r}")
+    _reject_unknown(payload, {"schema_version", *_RUN_FIELDS}, "配置")
+    raw_questions = payload.get("questions", [])
+    if not isinstance(raw_questions, list):
+        raise ConfigError("questions 必须是数组")
+    questions: list[QuestionConfig] = []
+    for index, raw in enumerate(raw_questions, start=1):
+        if not isinstance(raw, dict):
+            raise ConfigError(f"questions[{index}] 必须是对象")
+        _reject_unknown(raw, _QUESTION_FIELDS, f"questions[{index}]")
+        if "question_type" not in raw:
+            raise ConfigError(f"questions[{index}] 缺少 question_type")
+        if not isinstance(raw["question_type"], str) or not raw["question_type"].strip():
+            raise ConfigError(f"questions[{index}].question_type 必须是非空字符串")
+        if "probabilities" in raw and raw["probabilities"] is not None and not isinstance(raw["probabilities"], (list, int, float)):
+            raise ConfigError(f"questions[{index}].probabilities 类型无效")
+        questions.append(QuestionConfig(**raw))
+    target = payload.get("target", 1)
+    concurrency = payload.get("concurrency", 1)
+    if any(isinstance(value, bool) or not isinstance(value, int) for value in (target, concurrency)):
+        raise ConfigError("target 和 concurrency 必须是整数")
+    if target < 1 or concurrency < 1:
+        raise ConfigError("target 和 concurrency 必须大于 0")
+    provider = payload.get("provider")
+    if provider is not None and (not isinstance(provider, str) or provider not in {"wjx", "qq", "credamo"}):
+        raise ConfigError("provider 必须是 wjx、qq 或 credamo")
+    reverse_fill_start_row = payload.get("reverse_fill_start_row", 1)
+    reverse_fill_threads = payload.get("reverse_fill_threads", 1)
+    if any(isinstance(value, bool) or not isinstance(value, int) or value < 1 for value in (reverse_fill_start_row, reverse_fill_threads)):
+        raise ConfigError("反填行号和线程数必须是正整数")
+    return RunConfig(
+        url=_required_string(payload.get("url", ""), "url"),
+        questions=questions,
+        target=target,
+        concurrency=concurrency,
+        provider=provider,
+        answer_duration=_range(payload.get("answer_duration", [60, 120]), "answer_duration"),
+        submit_interval=_range(payload.get("submit_interval", [0, 0]), "submit_interval"),
+        answer_datetime_window=_string_range(payload.get("answer_datetime_window", ["", ""]), "answer_datetime_window"),
+        random_user_agent=_strict_bool(payload.get("random_user_agent", False), "random_user_agent"),
+        user_agent_ratios=_mapping(payload.get("user_agent_ratios", {"wechat": 33, "mobile": 33, "pc": 34}), "user_agent_ratios"),
+        reliability_mode=_strict_bool(payload.get("reliability_mode", True), "reliability_mode"),
+        target_alpha=_strict_float(payload.get("target_alpha", 0.85), "target_alpha"),
+        answer_rules=_list_of_dicts(payload.get("answer_rules", []), "answer_rules"),
+        reverse_fill_enabled=_strict_bool(payload.get("reverse_fill_enabled", False), "reverse_fill_enabled"),
+        reverse_fill_source_path=_required_string(payload.get("reverse_fill_source_path", ""), "reverse_fill_source_path", allow_empty=True),
+        reverse_fill_format=_required_string(payload.get("reverse_fill_format", "auto"), "reverse_fill_format"),
+        reverse_fill_start_row=reverse_fill_start_row,
+        reverse_fill_threads=reverse_fill_threads,
+    )
+
+
+def _required_string(value: Any, label: str, *, allow_empty: bool = False) -> str:
+    if not isinstance(value, str) or (not allow_empty and not value.strip()):
+        raise ConfigError(f"{label}必须是字符串")
+    return value.strip()
+
+
+def dumps_config(config: RunConfig, *, indent: int = 2) -> str:
+    return json.dumps(serialize_config(config), ensure_ascii=False, indent=indent)
+
+
+def loads_config(value: str) -> RunConfig:
+    try:
+        payload = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"配置 JSON 无效：{exc}") from exc
+    return deserialize_config(payload)
+
+
+__all__ = ["SCHEMA_VERSION", "deserialize_config", "dumps_config", "loads_config", "serialize_config"]

surveycore/core/ai/__init__.py

@@ -0,0 +1,3 @@
+from .runtime import AIRuntimeError, agenerate_ai_answer
+
+__all__ = ["AIRuntimeError", "agenerate_ai_answer"]

surveycore/core/ai/batch_runtime.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from .runtime import (
+    AIRuntimeError,
+    agenerate_ai_answer,
+    is_free_ai_option_fill_placeholder,
+    is_free_ai_text_placeholder,
+)
+
+
+async def prefill_free_ai_answers_for_questions(questions: Iterable[Any], actions: Iterable[Any], ctx: Any, *, thread_name: str = "") -> None:
+    del questions
+    for action in actions:
+        if not any(is_free_ai_text_placeholder(item) for item in tuple(getattr(action, "text_values", ()) or ())):
+            continue
+        question = next((q for q in list(getattr(ctx.config, "questions_metadata", {}).values()) if int(getattr(q, "num", 0) or 0) == int(getattr(action, "question_num", 0) or 0)), None)
+        if question is None:
+            continue
+        answer = await agenerate_ai_answer(str(getattr(question, "title", "")), question_type="multi_fill_blank" if len(action.text_values) > 1 else "fill_blank", blank_count=len(action.text_values), question_number=action.question_num, ctx=ctx)
+        values = tuple(answer if isinstance(answer, list) else [answer])
+        ctx.set_free_ai_prefill_answers(thread_name, {int(action.question_num): values})
+
+
+def assert_no_free_ai_placeholders_in_actions(actions: Iterable[Any], *, provider_label: str = "问卷") -> None:
+    for action in actions:
+        text_values = tuple(getattr(action, "text_values", ()) or ())
+        raw_option_fill_pairs: Any = getattr(action, "option_fill_texts", ()) or ()
+        option_fill_values = tuple(
+            pair[1]
+            for pair in tuple(raw_option_fill_pairs)
+            if isinstance(pair, (list, tuple)) and len(pair) >= 2
+        )
+        if any(
+            is_free_ai_text_placeholder(item) or is_free_ai_option_fill_placeholder(item)
+            for item in text_values + option_fill_values
+        ):
+            raise AIRuntimeError(f"{provider_label}存在未处理的答案生成占位符")
+
+
+__all__ = ["AIRuntimeError", "assert_no_free_ai_placeholders_in_actions", "prefill_free_ai_answers_for_questions"]

surveycore/core/ai/runtime.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import inspect
+import re
+from typing import Any, List, Optional
+
+
+class AIRuntimeError(RuntimeError):
+    pass
+
+
+def build_ai_question_prompt(question_title: str, *, description: str = "", question_number: int = 0) -> str:
+    title = re.sub(r"^\s*\*?\s*\d+[.、]?\s*", "", str(question_title or "").strip())
+    if not title:
+        title = f"第{int(question_number)}题" if int(question_number or 0) > 0 else ""
+    description = str(description or "").strip()
+    return f"{title}\n补充说明：{description}" if title and description else title
+
+
+def build_ai_option_fill_prompt(*, question_title: str, question_number: int, option_text: str = "") -> str:
+    prompt = build_ai_question_prompt(question_title, question_number=question_number)
+    return f"{prompt}\n当前选择项：{str(option_text or '').strip()}".strip()
+
+
+def build_free_ai_text_placeholder(question_num: int, blank_index: int) -> str:
+    return f"__FREE_AI_TEXT__{int(question_num)}_{int(blank_index)}"
+
+
+def build_free_ai_option_fill_placeholder(question_num: int, option_index: int) -> str:
+    return f"__FREE_AI_OPTION_FILL__{int(question_num)}_{int(option_index)}"
+
+
+def is_free_ai_text_placeholder(value: object) -> bool:
+    return str(value or "").startswith("__FREE_AI_TEXT__")
+
+
+def is_free_ai_option_fill_placeholder(value: object) -> bool:
+    return str(value or "").startswith("__FREE_AI_OPTION_FILL__")
+
+
+async def agenerate_ai_answer(
+    question_title: str,
+    *,
+    question_type: str = "fill_blank",
+    blank_count: Optional[int] = None,
+    description: str = "",
+    question_number: int = 0,
+    ctx: Any = None,
+) -> str | List[str]:
+    callback = getattr(getattr(ctx, "config", None), "answer_generator", None)
+    if not callable(callback):
+        raise AIRuntimeError("文本题需要通过 answer_generator 注入生成器")
+    prompt = build_ai_question_prompt(
+        question_title,
+        description=description,
+        question_number=question_number,
+    )
+    try:
+        value = callback(prompt, question_type=question_type, blank_count=blank_count, question_number=question_number)
+        if inspect.isawaitable(value):
+            value = await value
+    except Exception as exc:
+        raise AIRuntimeError(f"答案生成器调用失败：{exc}") from exc
+    if question_type == "multi_fill_blank":
+        values = value if isinstance(value, list) else [part.strip() for part in str(value or "").split("||")]
+        values = [str(item or "").strip() for item in values if str(item or "").strip()]
+        if blank_count and len(values) != int(blank_count):
+            raise AIRuntimeError(f"答案生成器返回 {len(values)} 项，期望 {int(blank_count)} 项")
+        if not values:
+            raise AIRuntimeError("答案生成器返回空内容")
+        return values
+    text = str(value or "").strip()
+    if not text:
+        raise AIRuntimeError("答案生成器返回空内容")
+    return text
+