flare-kernel 0.2.13__tar.gz → 0.2.15__tar.gz

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flare-kernel
-Version: 0.2.13
+Version: 0.2.15
 Summary: FLARE kernel runtime package
 License: Proprietary
 Classifier: Development Status :: 3 - Alpha

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flare-kernel"
-version = "0.2.13"
+version = "0.2.15"
 description = "FLARE kernel runtime package"
 readme = "README.md"
 requires-python = ">=3.11"

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/src/flare_kernel/router/streaming/draft/finalize.py

@@ -14,6 +14,9 @@ from __future__ import annotations
 from typing import Any
 
 from flare_kernel.runtime.llm.llm_provider import LLMCompletion
+from flare_kernel.runtime.orchestration.mode.canvas_state import (
+    build_analysis_canvas_signal_state,
+)
 from flare_kernel.router.completion.analysis_policy import (
     apply_analysis_completion_policy,
 )
@@ -106,6 +109,15 @@ def iter_canonical_finalize_events(
             )
         )
         events.append(emitter.emit_patch("analysis.canvas_payload", analysis_payload))
+        events.append(
+            emitter.emit_event(
+                "canvas_state",
+                build_analysis_canvas_signal_state(
+                    session_id=session_id,
+                    project_id=str(canonical.get("project_id") or ""),
+                ),
+            )
+        )
     slot_patches = canonical.get("analysis_slot_patches")
     if isinstance(slot_patches, list) and slot_patches:
         events.append(emitter.emit_event("analysis_slot_patch", {"patches": slot_patches}))

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/src/flare_kernel/router/streaming/draft/phase.py

@@ -94,7 +94,9 @@ async def iter_draft_generation_events(
             trace_id=trace_id,
             session_id=session_id,
             request_id=request_id,
+            project_id=project_id,
             resolved_mode=resolved_mode,
+            effective_command=effective_command,
             emitter=emitter,
             build_llm_execution_trace_fn=build_llm_execution_trace_fn,
         ):

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/src/flare_kernel/router/streaming/draft/post_completion.py

@@ -29,6 +29,7 @@ from flare_kernel.router.streaming.draft.finalize import (
 from flare_kernel.router.streaming.event_emitter import StreamingEventEmitter
 from flare_kernel.runtime.context.analysis_application import build_context_patch_from_analysis
 from flare_kernel.runtime.context.intake_application import build_context_patch_from_intake_commit
+from flare_kernel.runtime.context.reasoning_application import build_context_patch_from_reasoning
 from flare_kernel.runtime.orchestration.mode.intake_summary_artifact import (
     build_model_authored_requirement_summary_event,
 )
@@ -63,6 +64,18 @@ def _resolve_analysis_payload(
     return {}
 
 
+def _resolve_reasoning_result(runtime_snapshot: dict[str, Any]) -> dict[str, Any]:
+    payload = runtime_snapshot.get("payload") if isinstance(runtime_snapshot.get("payload"), dict) else {}
+    for candidate in (
+        payload.get("structured_reasoning"),
+        runtime_snapshot.get("structured_reasoning"),
+        runtime_snapshot.get("reasoning_result"),
+    ):
+        if isinstance(candidate, dict):
+            return candidate
+    return {}
+
+
 def _resolve_context_patch(
     *,
     runtime_snapshot: dict[str, Any],
@@ -71,6 +84,7 @@ def _resolve_context_patch(
 ) -> dict[str, Any]:
     payload = runtime_snapshot.get("payload") if isinstance(runtime_snapshot.get("payload"), dict) else {}
     context_patch = payload.get("context_patch") if isinstance(payload.get("context_patch"), dict) else {}
+    reasoning_patch = build_context_patch_from_reasoning(_resolve_reasoning_result(runtime_snapshot))
     analysis_patch = build_context_patch_from_analysis(
         _resolve_analysis_payload(
             runtime_snapshot=runtime_snapshot,
@@ -82,7 +96,7 @@ def _resolve_context_patch(
         orchestration_status=orchestration_status,
         command=command,
     )
-    return _merge_context_patches(context_patch, analysis_patch, intake_patch)
+    return _merge_context_patches(reasoning_patch, context_patch, analysis_patch, intake_patch)
 
 
 def _is_requirement_summary_submission_turn(

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/src/flare_kernel/router/streaming/draft/prologue.py

@@ -5,6 +5,9 @@ from __future__ import annotations
 from typing import Any, Callable
 
 from flare_kernel.contracts import KernelRequest
+from flare_kernel.runtime.orchestration.mode.canvas_state import (
+    build_analysis_canvas_signal_state,
+)
 from flare_kernel.router.streaming.event_emitter import StreamingEventEmitter
 
 
@@ -15,6 +18,8 @@ def build_draft_prologue_events(
     session_id: str,
     request_id: str,
     resolved_mode: str,
+    project_id: str = "",
+    effective_command: str = "",
     emitter: StreamingEventEmitter,
     build_llm_execution_trace_fn: Callable[..., dict[str, Any]],
 ) -> list[str]:
@@ -41,6 +46,16 @@ def build_draft_prologue_events(
             },
         )
     )
+    if str(effective_command or "").strip() == "generate_analysis":
+        events.append(
+            emitter.emit_event(
+                "canvas_state",
+                build_analysis_canvas_signal_state(
+                    session_id=session_id,
+                    project_id=project_id,
+                ),
+            )
+        )
     llm_start_trace = build_llm_execution_trace_fn(
         trace_id=trace_id,
         session_id=req.session_id,

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/src/flare_kernel/runtime/context/reasoning_application.py

@@ -21,6 +21,16 @@ def _as_list(value: Any) -> list[Any]:
     return value if isinstance(value, list) else []
 
 
+def _as_mapping(value: Any) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def _coerce_confidence(value: Any) -> float | None:
+    if not isinstance(value, (int, float)):
+        return None
+    return max(0.0, min(1.0, float(value)))
+
+
 def _normalize_claims(items: Any) -> list[dict[str, Any]]:
     claims: list[dict[str, Any]] = []
     for item in _as_list(items):
@@ -50,6 +60,66 @@ def _normalize_text_list(items: Any) -> list[str]:
     return [_clean_text(item) for item in _as_list(items) if _clean_text(item)]
 
 
+def _normalize_confirmed_field_items(result: dict[str, Any]) -> list[dict[str, Any]]:
+    extraction = _as_mapping(result.get("field_extraction"))
+    raw_items = extraction.get("confirmed_fields")
+    if raw_items is None:
+        raw_items = result.get("confirmed_fields")
+    if isinstance(raw_items, dict):
+        items = [{"field_key": key, "value": value} for key, value in raw_items.items()]
+    else:
+        items = _as_list(raw_items)
+
+    fields: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for item in items:
+        payload = item if isinstance(item, dict) else {}
+        field_key = _clean_text(
+            payload.get("field_key")
+            or payload.get("key")
+            or payload.get("field")
+            or payload.get("target_field_key")
+        )
+        value = _clean_text(payload.get("value") or payload.get("field_value"))
+        if not field_key or not value or field_key in seen:
+            continue
+        seen.add(field_key)
+        fields.append(
+            {
+                "field_key": field_key,
+                "value": value,
+                "source": _clean_text(payload.get("source")),
+                "evidence": _clean_text(payload.get("evidence") or payload.get("quote")),
+                "confidence": _coerce_confidence(payload.get("confidence")),
+            }
+        )
+    return fields
+
+
+def _facts_from_confirmed_fields(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    facts: list[dict[str, Any]] = []
+    for item in items:
+        field_key = _clean_text(item.get("field_key"))
+        value = _clean_text(item.get("value"))
+        if not field_key or not value:
+            continue
+        facts.append(
+            {
+                "id": f"reasoning_field::{field_key}",
+                "text": f"{field_key}: {value}",
+                "source_id": _clean_text(item.get("source")),
+                "evidence_ids": [],
+                "confidence": item.get("confidence"),
+                "meta": {
+                    "field_key": field_key,
+                    "source": _clean_text(item.get("source")),
+                    "evidence": _clean_text(item.get("evidence")),
+                },
+            }
+        )
+    return facts
+
+
 def _normalize_evidence(result: dict[str, Any]) -> list[dict[str, Any]]:
     metadata = result.get("metadata") if isinstance(result.get("metadata"), dict) else {}
     raw_evidence = metadata.get("evidence") if isinstance(metadata.get("evidence"), list) else []
@@ -85,6 +155,16 @@ def build_context_patch_from_reasoning(reasoning_result: dict[str, Any] | None)
             values = _normalize_text_list(result.get(source_key))
         if values:
             patch[target_key] = values
+    confirmed_field_items = _normalize_confirmed_field_items(result)
+    if confirmed_field_items:
+        patch["confirmed_fields"] = {
+            item["field_key"]: item["value"]
+            for item in confirmed_field_items
+        }
+        patch["facts"] = [
+            *(patch.get("facts") if isinstance(patch.get("facts"), list) else []),
+            *_facts_from_confirmed_fields(confirmed_field_items),
+        ]
     evidence = _normalize_evidence(result)
     if evidence:
         patch["evidence"] = evidence

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/src/flare_kernel/runtime/context/session_context.py

@@ -155,7 +155,11 @@ def merge_session_context(
     document_patch = build_context_patch_from_document(document_result)
     track_patch = build_context_patch_from_track(track_result)
     for key in _CONTEXT_DICT_KEYS:
-        base[key] = {**(base.get(key) if isinstance(base.get(key), dict) else {}), **(patch.get(key) if isinstance(patch.get(key), dict) else {})}
+        base[key] = {
+            **(base.get(key) if isinstance(base.get(key), dict) else {}),
+            **(reasoning_patch.get(key) if isinstance(reasoning_patch.get(key), dict) else {}),
+            **(patch.get(key) if isinstance(patch.get(key), dict) else {}),
+        }
     for key in _CONTEXT_LIST_KEYS:
         base[key] = _merge_list(base.get(key), patch.get(key))
     for key in _CONTEXT_LIST_KEYS:

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/src/flare_kernel/runtime/orchestration/mode/canvas_state.py

@@ -110,4 +110,31 @@ def _build_canvas_revision_payload(
     }
 
 
-__all__ = ["_build_canvas_revision_payload", "_build_canvas_state_payload"]
+def build_analysis_canvas_signal_state(*, session_id: str, project_id: str = "") -> dict[str, Any]:
+    return {
+        "mode_key": "analysis_mode",
+        "session_id": session_id,
+        "project_id": project_id,
+        "render_hint": "canvas_state",
+        "canvas_state": {
+            "version": 1,
+            "confirmed": True,
+            "progress": 1.0,
+            "collected": [],
+            "missing": [],
+            "revision_suggestions": [],
+            "versions": [],
+        },
+        "ui_signal": {
+            "open_canvas_panel": True,
+            "active_tab": "analysis",
+            "reason": "analysis_payload_ready",
+        },
+    }
+
+
+__all__ = [
+    "_build_canvas_revision_payload",
+    "_build_canvas_state_payload",
+    "build_analysis_canvas_signal_state",
+]

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/src/flare_kernel/runtime/orchestration/mode/intake_canvas.py

@@ -74,7 +74,7 @@ def enrich_intake_canvas_state(
         model_plan=model_question_plan if isinstance(model_question_plan, list) else [],
     )
     del understanding_summary
-    canvas_content = build_intake_canvas_content(collected_rows=collected_rows)
+    canvas_content = build_intake_canvas_content(collected_rows=collected_rows, missing_rows=missing_rows)
 
     versions = _replace_latest_content(canvas_state.get("versions"), canvas_content)
     toolbar_actions = build_canvas_toolbar_actions(

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/src/flare_kernel/runtime/orchestration/mode/intake_canvas_content.py

@@ -1,8 +1,8 @@
 """Prompt-ready requirement-intake Canvas content projection.
 
-This module only formats canonical collected fields into reviewable prompt
-context. It must not ask new questions, decide readiness, or invent missing
-business details.
+This module only formats canonical collected/missing fields into reviewable
+prompt context. It must not ask new questions, decide readiness, or invent
+missing business details.
 """
 
 from __future__ import annotations
@@ -12,6 +12,7 @@ from typing import Any
 _CANVAS_TITLE = "需求梳理草稿"
 _PROMPT_SECTION_TITLE = "完整提示词："
 _CONFIRMED_SECTION_TITLE = "已确认需求信息："
+_PENDING_SECTION_TITLE = "待确认需求信息："
 _RULES_SECTION_TITLE = "处理规则："
 _OUTPUT_SECTION_TITLE = "输出格式："
 
@@ -33,6 +34,18 @@ def _confirmed_lines(rows: list[dict[str, Any]]) -> list[str]:
     return [line for line in lines if line] or ["- 暂无已确认字段。"]
 
 
+def _pending_lines(rows: list[dict[str, Any]]) -> list[str]:
+    lines = [_pending_row_line(row) for row in rows if isinstance(row, dict)]
+    return [line for line in lines if line] or ["- 暂无待确认字段。"]
+
+
+def _pending_row_line(row: dict[str, Any]) -> str:
+    label = _clean_text(row.get("label") or row.get("field_key"))
+    if not label:
+        return ""
+    return f"- {label}：待确认"
+
+
 def _prompt_preamble() -> list[str]:
     return [
         "你是需求执行助手。请基于以下已确认需求信息推进后续任务；未明确的信息不要自行假设，请标记为“待确认”。",
@@ -56,14 +69,19 @@ def _prompt_output_format() -> list[str]:
     ]
 
 
-def build_intake_canvas_content(*, collected_rows: list[dict[str, Any]]) -> str:
-    """Build a stable prompt-ready draft from canonical collected fields.
+def build_intake_canvas_content(
+    *,
+    collected_rows: list[dict[str, Any]],
+    missing_rows: list[dict[str, Any]] | None = None,
+) -> str:
+    """Build a stable prompt-ready draft from canonical collected/missing fields.
 
     Field rows are supplied by orchestration after normalization. This function
     only renders them; no field coverage or workflow decisions belong here.
     """
 
     rows = collected_rows if isinstance(collected_rows, list) else []
+    pending_rows = missing_rows if isinstance(missing_rows, list) else []
     sections = [
         _CANVAS_TITLE,
         _PROMPT_SECTION_TITLE,
@@ -72,6 +90,9 @@ def build_intake_canvas_content(*, collected_rows: list[dict[str, Any]]) -> str:
         _CONFIRMED_SECTION_TITLE,
         *_confirmed_lines(rows),
         "",
+        _PENDING_SECTION_TITLE,
+        *_pending_lines(pending_rows),
+        "",
         _RULES_SECTION_TITLE,
         *_prompt_rules(),
         "",

{flare_kernel-0.2.13 → flare_kernel-0.2.15}/src/flare_kernel/runtime/orchestration/mode/intake_context.py

@@ -15,6 +15,9 @@ from flare_kernel.runtime.orchestration.mode.field_definitions import (
     _derive_field_lists,
     _normalize_field_definitions,
 )
+from flare_kernel.runtime.orchestration.mode.intake_field_hydration import (
+    hydrate_intake_fields,
+)
 from flare_kernel.runtime.orchestration.mode.shared import (
     _coerce_mapping,
     _coerce_message_excerpt,
@@ -152,6 +155,15 @@ def build_intake_context(
             **structured_reasoning,
             "result_text": result_text_from_payload,
         }
+    hydration = hydrate_intake_fields(
+        fields=fields,
+        sources=sources,
+        payload=payload,
+        field_definitions=field_definitions,
+        structured_reasoning=structured_reasoning,
+    )
+    fields = hydration["fields"]
+    sources = hydration["sources"]
     question_context = _build_question_context(payload)
     reasoning_state = {
         "confirmed_fields": fields,

flare_kernel-0.2.15/src/flare_kernel/runtime/orchestration/mode/intake_field_hydration.py

@@ -0,0 +1,121 @@
+"""Requirement-intake canonical field hydration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _clean_text(value: Any) -> str:
+    return " ".join(str(value or "").split()).strip()
+
+
+def _coerce_mapping(value: Any) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def _coerce_list(value: Any) -> list[Any]:
+    return value if isinstance(value, list) else []
+
+
+def _has_value(value: Any) -> bool:
+    return value not in (None, "", [], {})
+
+
+def _allowed_field_keys(field_definitions: list[dict[str, Any]]) -> set[str]:
+    return {
+        field_key
+        for field_key in (
+            _clean_text(_coerce_mapping(item).get("key"))
+            for item in field_definitions
+        )
+        if field_key
+    }
+
+
+def _field_candidates_from_mapping(
+    values: dict[str, Any],
+    *,
+    source: str,
+) -> list[dict[str, Any]]:
+    candidates: list[dict[str, Any]] = []
+    for key, value in values.items():
+        field_key = _clean_text(key)
+        if field_key and _has_value(value):
+            candidates.append({"field_key": field_key, "value": value, "source": source})
+    return candidates
+
+
+def _session_context_candidates(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    context = _coerce_mapping(payload.get("session_context") or payload.get("context"))
+    candidates = _field_candidates_from_mapping(
+        _coerce_mapping(context.get("confirmed_fields")),
+        source="session_context",
+    )
+    for artifact in _coerce_list(context.get("artifact_context")):
+        artifact_fields = _coerce_mapping(_coerce_mapping(artifact).get("fields"))
+        candidates.extend(_field_candidates_from_mapping(artifact_fields, source="artifact_context"))
+    return candidates
+
+
+def _structured_reasoning_candidates(structured_reasoning: dict[str, Any]) -> list[dict[str, Any]]:
+    extraction = _coerce_mapping(structured_reasoning.get("field_extraction"))
+    raw_confirmed = extraction.get("confirmed_fields")
+    if isinstance(raw_confirmed, dict):
+        return _field_candidates_from_mapping(raw_confirmed, source="structured_reasoning")
+    candidates: list[dict[str, Any]] = []
+    for item in _coerce_list(raw_confirmed):
+        payload = _coerce_mapping(item)
+        field_key = _clean_text(payload.get("field_key") or payload.get("key"))
+        value = payload.get("value") or payload.get("field_value")
+        if field_key and _has_value(value):
+            candidates.append(
+                {
+                    "field_key": field_key,
+                    "value": value,
+                    "source": _clean_text(payload.get("source")) or "structured_reasoning",
+                    "evidence": _clean_text(payload.get("evidence")),
+                    "confidence": payload.get("confidence"),
+                }
+            )
+    return candidates
+
+
+def hydrate_intake_fields(
+    *,
+    fields: dict[str, Any],
+    sources: dict[str, Any],
+    payload: dict[str, Any],
+    field_definitions: list[dict[str, Any]],
+    structured_reasoning: dict[str, Any],
+) -> dict[str, Any]:
+    """Hydrate missing canonical fields from existing context before scoring."""
+
+    allowed_keys = _allowed_field_keys(field_definitions)
+    hydrated_fields = dict(fields)
+    hydrated_sources = dict(sources)
+    hydrated_keys: list[str] = []
+    for candidate in [
+        *_session_context_candidates(payload),
+        *_structured_reasoning_candidates(structured_reasoning),
+    ]:
+        field_key = _clean_text(candidate.get("field_key"))
+        value = candidate.get("value")
+        if not field_key or field_key not in allowed_keys:
+            continue
+        if _has_value(hydrated_fields.get(field_key)) or not _has_value(value):
+            continue
+        hydrated_fields[field_key] = value
+        hydrated_sources[field_key] = {
+            "source": _clean_text(candidate.get("source")) or "context_hydration",
+            "evidence": _clean_text(candidate.get("evidence")),
+            "confidence": candidate.get("confidence"),
+        }
+        hydrated_keys.append(field_key)
+    return {
+        "fields": hydrated_fields,
+        "sources": hydrated_sources,
+        "hydrated_fields": hydrated_keys,
+    }
+
+
+__all__ = ["hydrate_intake_fields"]

flare_kernel-0.2.15/src/flare_kernel/runtime/orchestration/structured_reasoning.py

@@ -0,0 +1,156 @@
+"""Structured reasoning generation for kernel orchestration."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Awaitable, Callable
+
+from flare_kernel.runtime.infrastructure.logging import get_logger
+from flare_kernel.runtime.orchestration.structured_prompt_context import build_structured_prompt_context
+from flare_kernel.runtime.orchestration.structured_reasoning_normalization import (
+    _clean_text,
+    _coerce_mapping,
+    _extract_json_object,
+    _normalize_structured_output,
+)
+
+logger = get_logger("flare_kernel.runtime.orchestration.structured_reasoning")
+
+
+def build_structured_reasoning_prompt(
+    *,
+    message: str,
+    mode_key: str,
+    payload: dict[str, Any],
+    retrieved_knowledge: list[dict[str, Any]],
+    instance_profile: dict[str, Any] | None,
+) -> str:
+    compact_payload = build_structured_prompt_context(
+        message=message,
+        mode_key=mode_key,
+        payload=payload,
+        retrieved_knowledge=retrieved_knowledge,
+        instance_profile=instance_profile,
+    )
+    schema = {
+        "result_summary": "short summary of what the user wants",
+        "field_extraction": {
+            "confirmed_fields": [
+                {
+                    "field_key": "nearest writable field_contract key",
+                    "value": "grounded value from message/context/retrieved_knowledge",
+                    "source": "message|known_fields|session_context|retrieved_knowledge",
+                    "evidence": "short supporting quote or summary",
+                    "confidence": 0.0,
+                }
+            ]
+        },
+        "hypothesis_inference": {"hypotheses": [{"id": "goal hypothesis", "score": 0.0, "rationale": "why"}]},
+        "field_activation": {"active_fields": ["question_target_key"]},
+        "gap_detection": {"candidate_information_gaps": [{"key": "question_target_key", "importance": 1.0, "reason": "why missing"}]},
+        "question_planner": {
+            "question_plan": [
+                {
+                    "question_key": "specific information-gap key",
+                    "target_field_keys": ["nearest writable field_contract key"],
+                    "question_text": "user-facing follow-up question",
+                    "rationale": "why this question improves the target artifact",
+                    "expected_answer_type": "enum_or_text",
+                    "priority": 1,
+                    "blocking": False,
+                    "options": [],
+                }
+            ],
+            "next_question": {
+                "question_key": "specific information-gap key",
+                "target_field_keys": ["nearest writable field_contract key"],
+                "question_text": "one best user-facing follow-up question",
+                "rationale": "why this question is next",
+                "expected_answer_type": "enum_or_text",
+                "priority": 1,
+                "blocking": False,
+                "options": [],
+            }
+        },
+    }
+    return (
+        "你是 FLARE 的结构化 reasoning 层，不是最终回答层。\n"
+        "你的任务是先理解用户目标，再产出一个可由系统校验和投影的 JSON 中间结果。\n"
+        "field_contracts 只定义可写入的字段 key/label/type，不定义用户问题和候选答案。"
+        "如果 message、known_fields、context_summary 或 retrieved_knowledge 已明确给出字段答案，"
+        "必须写入 field_extraction.confirmed_fields。"
+        "field_extraction.confirmed_fields 只允许使用 field_contracts 中存在的 key，"
+        "并且必须有 source/evidence；不能基于常识或偏好猜测。"
+        "已经能确认的字段不要再作为 question_plan 的问题目标。"
+        "你必须基于用户输入、已知字段和上下文生成 question_text。"
+        "如果 Input.track_context 存在，必须优先用 goal、workflow_steps、current_step_id、readiness 和 unknowns 判断当前轨道；"
+        "question_plan 不是字段清单，而是围绕最终目标和当前轨道的高价值信息缺口；"
+        "当中文量词与上下文对象轻微不一致、但上下文能唯一推导对象或动作时，按上下文校准为当前假设，"
+        "不要把量词口误升级成阻塞性二选一问题；"
+        "当用户已提供足以形成初步假设的信息时，不要把所有 missing_fields 都列为阻塞项，只选一个最能提升后续判断的问题作为 next_question。"
+        "question_key 表示更具体的信息缺口，target_field_keys 必须指向最接近的可写字段。"
+        "如果你的结果需要提出校准问题，必须放入 question_planner.next_question，不能只写入摘要正文。"
+        "优先选择真正提升当前交付质量的下一项信息缺口。"
+        "不要把未在 field_contracts、missing_fields 或 instance_profile 中声明的字段当成必填项。"
+        "blocking 只能在字段被明确标记为 blocker/required 或 missing_fields 明确列出时为 true。"
+        "question_plan 是可选的；只有当输入上下文明确需要批量计划时才输出多项计划。"
+        "options 不是必填默认值；只有当用户输入、已知字段、上下文、instance_profile 或检索证据能支撑明确候选答案时才输出。"
+        "不得为了填充 UI 候选项而编造选项；没有可靠来源时输出空数组。"
+        "不得输出“其他”“暂不确定”等占位选项；自定义输入由 UI 处理。"
+        "不要输出 Markdown，不要解释，只输出 JSON。\n"
+        f"JSON schema example: {json.dumps(schema, ensure_ascii=False, default=str)}\n"
+        f"Input: {json.dumps(compact_payload, ensure_ascii=False, default=str)}"
+    )
+
+
+async def generate_structured_reasoning(
+    *,
+    trace_id: str,
+    session_id: str,
+    message: str,
+    mode_key: str,
+    payload: dict[str, Any],
+    retrieved_knowledge: list[dict[str, Any]],
+    instance_profile: dict[str, Any] | None,
+    generate_llm_completion_fn: Callable[..., Awaitable[Any]] | None,
+) -> dict[str, Any]:
+    if not callable(generate_llm_completion_fn) or not _clean_text(message):
+        return {}
+    prompt = build_structured_reasoning_prompt(
+        message=message,
+        mode_key=mode_key,
+        payload=payload,
+        retrieved_knowledge=retrieved_knowledge,
+        instance_profile=instance_profile,
+    )
+    completion = await generate_llm_completion_fn(
+        prompt,
+        trace_id=trace_id,
+        session_id=session_id,
+        intent="structured_reasoning",
+    )
+    status = _clean_text(getattr(completion, "status", ""))
+    content = _clean_text(getattr(completion, "content", ""))
+    parsed = _extract_json_object(content)
+    normalized = _normalize_structured_output(parsed)
+    logger.info(
+        "structured_reasoning.generated trace_id=%s session_id=%s mode=%s status=%s has_question=%s",
+        trace_id,
+        session_id,
+        mode_key,
+        status,
+        bool(_coerce_mapping(_coerce_mapping(normalized.get("question_planner")).get("next_question")).get("question_text")),
+    )
+    if not normalized:
+        return {}
+    return {
+        **normalized,
+        "metadata": {
+            **_coerce_mapping(normalized.get("metadata")),
+            "provider_status": status,
+            "source": "llm_structured_reasoning",
+        },
+    }
+
+
+__all__ = ["build_structured_reasoning_prompt", "generate_structured_reasoning"]