flare-kernel 0.1.0__py3-none-any.whl

flare_kernel/runtime/mode_orchestration.py

@@ -0,0 +1,330 @@
+"""Mode orchestration helpers for the kernel runtime."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+_REQUIREMENT_CANVAS_NEXT_ACTIONS: list[dict[str, Any]] = [
+    {
+        "action_key": "continue_collection",
+        "label": "继续梳理",
+        "target_mode": "requirement_canvas",
+        "priority": 1,
+        "status": "blocked",
+        "reason": "字段已完整，当前可以直接进入下一步。",
+        "description": "继续补齐字段，提升需求结构化完整度。",
+    },
+    {
+        "action_key": "handoff_to_sourcing",
+        "label": "进入智能寻源",
+        "target_mode": "intelligent_sourcing",
+        "priority": 2,
+        "status": "available",
+        "reason": "必填字段已补齐，可以进入智能寻源。",
+        "description": "在必填字段完整后切换到候选匹配与风险摘要。",
+    },
+]
+
+
+def _coerce_message_excerpt(payload: dict[str, Any]) -> str:
+    message = payload.get("message")
+    if isinstance(message, str):
+        return message.strip()
+    return ""
+
+
+def _coerce_mapping(value: Any) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def _build_requirement_canvas_events(
+    *,
+    mode_key: str,
+    session_id: str,
+    payload: dict[str, Any],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], str]:
+    fields = _coerce_mapping(payload.get("fields"))
+    sources = _coerce_mapping(payload.get("field_sources"))
+    required_fields = payload.get("required_fields")
+    if not isinstance(required_fields, list):
+        required_fields = []
+
+    collected = [key for key, value in fields.items() if value not in (None, "", [], {})]
+    missing = [field for field in required_fields if field not in collected]
+    progress = 0.0
+    if required_fields:
+        progress = len(collected) / len(required_fields)
+
+    field_progress_payload = {
+        "mode_key": mode_key,
+        "session_id": session_id,
+        "project_id": payload.get("project_id"),
+        "message_excerpt": _coerce_message_excerpt(payload),
+        "fields": fields,
+        "sources": sources,
+        "field_entries": payload.get("field_entries", []),
+        "field_groups": payload.get("field_groups", {}),
+        "extra_fields": payload.get("extra_fields", []),
+        "progress": progress,
+        "required_progress": payload.get("required_progress", progress),
+        "recommended_progress": payload.get("recommended_progress"),
+        "optional_progress": payload.get("optional_progress"),
+        "collected": collected,
+        "missing": missing,
+        "required_collected": payload.get("required_collected", []),
+        "required_missing": payload.get("required_missing", missing),
+        "recommended_collected": payload.get("recommended_collected", []),
+        "recommended_missing": payload.get("recommended_missing", []),
+        "optional_collected": payload.get("optional_collected", []),
+        "optional_missing": payload.get("optional_missing", []),
+        "last_field": payload.get("last_field"),
+        "refresh_reason": payload.get("refresh_reason"),
+        "field_definitions": payload.get("field_definitions", []),
+        "required_fields": required_fields,
+        "recommended_fields": payload.get("recommended_fields", []),
+        "optional_fields": payload.get("optional_fields", []),
+        "field_priorities": payload.get("field_priorities", {}),
+        "mode_state": "collecting",
+        "render_hint": "field_progress",
+    }
+
+    requirement_draft_payload = {
+        "mode_key": mode_key,
+        "session_id": session_id,
+        "project_id": payload.get("project_id"),
+        "message_excerpt": _coerce_message_excerpt(payload),
+        "draft": {
+            "fields": fields,
+            "summary": payload.get("summary") or payload.get("draft_summary") or "",
+            "status": payload.get("draft_status") or "collecting",
+        },
+        "mode_state": "drafting",
+        "render_hint": "requirement_draft",
+    }
+
+    next_actions_payload = {
+        "mode_key": mode_key,
+        "session_id": session_id,
+        "project_id": payload.get("project_id"),
+        "message_excerpt": _coerce_message_excerpt(payload),
+        "actions": _REQUIREMENT_CANVAS_NEXT_ACTIONS,
+        "next_actions": _REQUIREMENT_CANVAS_NEXT_ACTIONS,
+        "completion_state": "collecting",
+        "required_missing": missing,
+        "recommended_missing": payload.get("recommended_missing", []),
+        "optional_missing": payload.get("optional_missing", []),
+        "ready_for_sourcing": True,
+        "status": "available",
+        "reason": "必填字段已补齐，可以进入智能寻源。",
+        "mode_state": "collecting",
+        "render_hint": "next_actions",
+    }
+
+    events = [
+        {
+            "event_type": "field_progress",
+            "step_id": "field_progress",
+            "agent": "ModeOrchestration",
+            "mode_key": mode_key,
+            "payload": field_progress_payload,
+        },
+        {
+            "event_type": "requirement_draft",
+            "step_id": "requirement_draft",
+            "agent": "ModeOrchestration",
+            "mode_key": mode_key,
+            "payload": requirement_draft_payload,
+        },
+        {
+            "event_type": "next_actions",
+            "step_id": "next_actions",
+            "agent": "ModeOrchestration",
+            "mode_key": mode_key,
+            "payload": next_actions_payload,
+        },
+    ]
+    return events, _REQUIREMENT_CANVAS_NEXT_ACTIONS, "collecting"
+
+
+def _build_intelligent_sourcing_events(
+    *,
+    mode_key: str,
+    session_id: str,
+    payload: dict[str, Any],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], str]:
+    base_fields = _coerce_mapping(payload.get("base_fields"))
+    base_collected = [key for key, value in base_fields.items() if value not in (None, "", [], {})]
+    base_missing = [key for key in ("category", "region") if key not in base_fields]
+    base_total = max(len(base_fields), len(base_collected) + len(base_missing))
+    base_progress = len(base_collected) / base_total if base_total else 0.0
+
+    candidates_payload = {
+        "mode_key": mode_key,
+        "session_id": session_id,
+        "project_id": payload.get("project_id"),
+        "message_excerpt": _coerce_message_excerpt(payload),
+        "missing": base_missing,
+        "base_fields": list(base_fields.keys()),
+        "base_collected": base_collected,
+        "base_missing": base_missing,
+        "base_total": base_total,
+        "base_progress": base_progress,
+        "base_ready_for_matching": True,
+        "mode_state": payload.get("mode_state") or "matching",
+        "candidate_count": len(payload.get("candidates", [])) if isinstance(payload.get("candidates"), list) else None,
+        "is_placeholder": False,
+        "required_missing": payload.get("required_missing", []),
+        "recommended_missing": payload.get("recommended_missing", []),
+        "optional_missing": payload.get("optional_missing", []),
+        "actions": payload.get("actions", []),
+        "candidates": payload.get("candidates", payload.get("sourcing_candidates", [])),
+        "reasoning": payload.get("reasoning", []),
+        "summary": payload.get("summary") or payload.get("sourcing_summary"),
+        "render_hint": "sourcing_candidates",
+    }
+
+    risk_summary_payload = {
+        "mode_key": mode_key,
+        "session_id": session_id,
+        "project_id": payload.get("project_id"),
+        "message_excerpt": _coerce_message_excerpt(payload),
+        "mode_state": "screening",
+        "base_fields": list(base_fields.keys()),
+        "base_collected": base_collected,
+        "base_missing": base_missing,
+        "base_total": base_total,
+        "base_progress": base_progress,
+        "base_ready_for_matching": True,
+        "is_placeholder": False,
+        "actions": payload.get("actions", []),
+        "risks": payload.get("risks", payload.get("risk_items", [])),
+        "sources": payload.get("sources", payload.get("references", [])),
+        "summary": payload.get("risk_summary") or payload.get("summary") or "",
+        "render_hint": "risk_summary",
+    }
+
+    shortlist = payload.get("shortlist")
+    if not isinstance(shortlist, list):
+        shortlist = payload.get("shortlist_updated")
+    if not isinstance(shortlist, list):
+        shortlist = payload.get("selected_candidates", [])
+    if not isinstance(shortlist, list):
+        shortlist = []
+
+    shortlist_payload = {
+        "mode_key": mode_key,
+        "session_id": session_id,
+        "project_id": payload.get("project_id"),
+        "message_excerpt": _coerce_message_excerpt(payload),
+        "mode_state": "shortlisted",
+        "base_fields": list(base_fields.keys()),
+        "base_collected": base_collected,
+        "base_missing": base_missing,
+        "base_total": base_total,
+        "base_progress": base_progress,
+        "base_ready_for_matching": True,
+        "shortlist": shortlist,
+        "status": payload.get("status") or payload.get("state") or "available",
+        "reason": payload.get("reason") or payload.get("message") or "",
+        "selected_count": len(shortlist),
+        "is_placeholder": False,
+        "actions": payload.get("actions", []),
+        "render_hint": "shortlist_updated",
+    }
+
+    report = payload.get("report")
+    if not isinstance(report, dict):
+        report = payload.get("evaluation_report_ready") if isinstance(payload.get("evaluation_report_ready"), dict) else {}
+
+    evaluation_report_ready_payload = {
+        "mode_key": mode_key,
+        "session_id": session_id,
+        "project_id": payload.get("project_id"),
+        "message_excerpt": _coerce_message_excerpt(payload),
+        "mode_state": "report_ready",
+        "base_fields": list(base_fields.keys()),
+        "base_collected": base_collected,
+        "base_missing": base_missing,
+        "base_total": base_total,
+        "base_progress": base_progress,
+        "base_ready_for_matching": True,
+        "is_placeholder": False,
+        "actions": payload.get("actions", []),
+        "report": {
+            **report,
+            "sections": report.get("sections", []) if isinstance(report.get("sections"), list) else [],
+        },
+        "compare_table": payload.get("compare_table") or payload.get("comparison_table") or payload.get("compare_rows"),
+        "render_hint": "evaluation_report_ready",
+    }
+
+    events = [
+        {
+            "event_type": "sourcing_candidates",
+            "step_id": "sourcing_candidates",
+            "agent": "ModeOrchestration",
+            "mode_key": mode_key,
+            "payload": candidates_payload,
+        },
+        {
+            "event_type": "risk_summary",
+            "step_id": "risk_summary",
+            "agent": "ModeOrchestration",
+            "mode_key": mode_key,
+            "payload": risk_summary_payload,
+        },
+        {
+            "event_type": "shortlist_updated",
+            "step_id": "shortlist_updated",
+            "agent": "ModeOrchestration",
+            "mode_key": mode_key,
+            "payload": shortlist_payload,
+        },
+        {
+            "event_type": "evaluation_report_ready",
+            "step_id": "evaluation_report_ready",
+            "agent": "ModeOrchestration",
+            "mode_key": mode_key,
+            "payload": evaluation_report_ready_payload,
+        },
+    ]
+    return events, [], "report_ready"
+
+
+def build_mode_orchestration(
+    *,
+    trace_id: str,
+    session_id: str,
+    payload: dict[str, Any],
+    mode_runtime: dict[str, str],
+    agent_runtime: dict[str, Any],
+    skill_runtime: dict[str, Any],
+    domain_pack: dict[str, Any] | None,
+) -> dict[str, Any]:
+    del trace_id, agent_runtime, skill_runtime, domain_pack
+
+    mode_key = mode_runtime.get("mode_key", "unknown")
+    if mode_key == "requirement_canvas":
+        mode_events, next_actions, mode_state = _build_requirement_canvas_events(
+            mode_key=mode_key,
+            session_id=session_id,
+            payload=payload,
+        )
+    elif mode_key == "intelligent_sourcing":
+        mode_events, next_actions, mode_state = _build_intelligent_sourcing_events(
+            mode_key=mode_key,
+            session_id=session_id,
+            payload=payload,
+        )
+    else:
+        mode_events = []
+        next_actions = []
+        mode_state = mode_runtime.get("mode_state", "unknown")
+
+    return {
+        "mode_key": mode_key,
+        "mode_state": mode_state,
+        "mode_events": mode_events,
+        "next_actions": next_actions,
+    }

flare_kernel/runtime/mode_runtime.py

@@ -0,0 +1,262 @@
+"""Placeholder mode/context runtime helpers for the kernel."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+from functools import lru_cache
+from typing import Any
+
+from flare_kernel.runtime.domain_pack_loader import load_requirement_schema
+
+_MODE_STATE_BY_KEY = {
+    "requirement_canvas": "collecting",
+    "intelligent_sourcing": "collecting",
+}
+
+_MODE_ALIASES = {
+    "requirement_canvas": "requirement_canvas",
+    "requirement_refinement": "requirement_canvas",
+    "需求梳理": "requirement_canvas",
+    "intelligent_sourcing": "intelligent_sourcing",
+    "智能寻源": "intelligent_sourcing",
+}
+
+_SYSTEM_INSTRUCTION = "You are FLARE kernel. Respond concisely and helpfully."
+
+
+def _env(name: str, default: str | None = None) -> str | None:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    value = raw.strip()
+    return value if value else default
+
+
+def _int_env(name: str, default: int) -> int:
+    raw = _env(name)
+    if raw is None:
+        return default
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return default
+
+
+def _coerce_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, (dict, list, tuple)):
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    return str(value).strip()
+
+
+def _estimate_tokens(value: Any) -> int:
+    text = _coerce_text(value)
+    if not text:
+        return 0
+    return max(1, math.ceil(len(text) / 4))
+
+
+@lru_cache(maxsize=1)
+def get_context_budget_config() -> dict[str, int]:
+    return {
+        "total_tokens": _int_env("FLARE_KERNEL_CONTEXT_BUDGET_TOTAL_TOKENS", 2048),
+        "current_input_tokens": _int_env("FLARE_KERNEL_CONTEXT_BUDGET_CURRENT_INPUT_TOKENS", 256),
+        "session_state_tokens": _int_env("FLARE_KERNEL_CONTEXT_BUDGET_SESSION_STATE_TOKENS", 256),
+        "history_summary_tokens": _int_env("FLARE_KERNEL_CONTEXT_BUDGET_HISTORY_SUMMARY_TOKENS", 384),
+        "system_instruction_tokens": _int_env("FLARE_KERNEL_CONTEXT_BUDGET_SYSTEM_INSTRUCTION_TOKENS", 256),
+        "retrieved_knowledge_tokens": _int_env("FLARE_KERNEL_CONTEXT_BUDGET_RETRIEVED_KNOWLEDGE_TOKENS", 512),
+        "memory_recall_tokens": _int_env("FLARE_KERNEL_CONTEXT_BUDGET_MEMORY_RECALL_TOKENS", 256),
+    }
+
+
+def _resolve_mode_key(intent: str, function_type: str | None) -> str:
+    candidate = function_type or intent
+    if not isinstance(candidate, str):
+        return "unknown"
+    normalized = candidate.strip()
+    return _MODE_ALIASES.get(normalized, "unknown")
+
+
+def _resolve_mode_state(mode_key: str) -> str:
+    return _MODE_STATE_BY_KEY.get(mode_key, "unknown")
+
+
+def _resolve_function_type(req_payload: dict[str, Any]) -> str | None:
+    raw_function_type = req_payload.get("function_type")
+    if isinstance(raw_function_type, str):
+        value = raw_function_type.strip()
+        return value or None
+    return None
+
+
+def _build_session_state(
+    *,
+    trace_id: str,
+    tenant_id: str,
+    instance_id: str,
+    domain_pack_version: str,
+    session_id: str,
+    intent: str,
+    function_type: str | None,
+    mode_key: str,
+    mode_state: str,
+    instance_profile: dict[str, Any] | None,
+) -> dict[str, Any]:
+    session_state: dict[str, Any] = {
+        "trace_id": trace_id,
+        "tenant_id": tenant_id,
+        "instance_id": instance_id,
+        "domain_pack_version": domain_pack_version,
+        "session_id": session_id,
+        "intent": intent,
+        "function_type": function_type,
+        "mode_key": mode_key,
+        "mode_state": mode_state,
+    }
+    if isinstance(instance_profile, dict):
+        product_name = instance_profile.get("product_name")
+        if isinstance(product_name, str) and product_name.strip():
+            session_state["product_name"] = product_name.strip()
+    return session_state
+
+
+def build_mode_runtime(*, intent: str, function_type: str | None) -> dict[str, str]:
+    mode_key = _resolve_mode_key(intent, function_type)
+    return {
+        "mode_key": mode_key,
+        "mode_state": _resolve_mode_state(mode_key),
+    }
+
+
+def build_context_usage(
+    *,
+    trace_id: str,
+    tenant_id: str,
+    instance_id: str,
+    domain_pack_version: str,
+    session_id: str,
+    intent: str,
+    function_type: str | None,
+    payload: dict[str, Any],
+    instance_profile: dict[str, Any] | None,
+    mode_runtime: dict[str, str],
+) -> dict[str, Any]:
+    session_state = _build_session_state(
+        trace_id=trace_id,
+        tenant_id=tenant_id,
+        instance_id=instance_id,
+        domain_pack_version=domain_pack_version,
+        session_id=session_id,
+        intent=intent,
+        function_type=function_type,
+        mode_key=mode_runtime["mode_key"],
+        mode_state=mode_runtime["mode_state"],
+        instance_profile=instance_profile,
+    )
+    current_input = payload.get("message") if isinstance(payload.get("message"), str) else ""
+    history_summary = payload.get("history_summary")
+    retrieved_knowledge = payload.get("retrieved_knowledge")
+    memory_recall = payload.get("memory_recall")
+
+    token_estimate = {
+        "current_input": _estimate_tokens(current_input),
+        "session_state": _estimate_tokens(session_state),
+        "history_summary": _estimate_tokens(history_summary),
+        "system_instruction": _estimate_tokens(_SYSTEM_INSTRUCTION),
+        "retrieved_knowledge": _estimate_tokens(retrieved_knowledge),
+        "memory_recall": _estimate_tokens(memory_recall),
+    }
+    token_estimate["total_prompt_tokens_estimate"] = sum(token_estimate.values())
+
+    budget = get_context_budget_config()
+    total_tokens = budget["total_tokens"]
+    total_estimate = token_estimate["total_prompt_tokens_estimate"]
+    if total_tokens <= 0:
+        profile = "unknown"
+    else:
+        ratio = total_estimate / total_tokens
+        if ratio <= 0.33:
+            profile = "light"
+        elif ratio <= 0.66:
+            profile = "medium"
+        else:
+            profile = "heavy"
+
+    return {
+        "trace_id": trace_id,
+        "session_id": session_id,
+        "intent": intent,
+        "function_type": function_type,
+        "mode_key": mode_runtime["mode_key"],
+        "mode_state": mode_runtime["mode_state"],
+        "profile": profile,
+        "token_estimate": token_estimate,
+        "budget_tokens": budget,
+}
+
+
+def build_kernel_runtime(
+    *,
+    trace_id: str,
+    tenant_id: str,
+    instance_id: str,
+    domain_pack_version: str,
+    session_id: str,
+    intent: str,
+    payload: dict[str, Any],
+    instance_profile: dict[str, Any] | None,
+) -> dict[str, Any]:
+    from flare_kernel.runtime.agent_runtime import build_agent_runtime
+    from flare_kernel.runtime.skill_runtime import build_skill_runtime
+    from flare_kernel.runtime.mode_orchestration import build_mode_orchestration
+
+    function_type = _resolve_function_type(payload)
+    domain_pack_schema = load_requirement_schema(instance_id)
+    mode_runtime = build_mode_runtime(intent=intent, function_type=function_type)
+    context_usage = build_context_usage(
+        trace_id=trace_id,
+        tenant_id=tenant_id,
+        instance_id=instance_id,
+        domain_pack_version=domain_pack_version,
+        session_id=session_id,
+        intent=intent,
+        function_type=function_type,
+        payload=payload,
+        instance_profile=instance_profile,
+        mode_runtime=mode_runtime,
+    )
+    agent_runtime = build_agent_runtime(
+        trace_id=trace_id,
+        session_id=session_id,
+        intent=intent,
+        function_type=function_type,
+        mode_runtime=mode_runtime,
+    )
+    skill_runtime = build_skill_runtime(
+        trace_id=trace_id,
+        session_id=session_id,
+        intent=intent,
+        function_type=function_type,
+        mode_runtime=mode_runtime,
+    )
+    mode_orchestration = build_mode_orchestration(
+        trace_id=trace_id,
+        session_id=session_id,
+        payload=payload,
+        mode_runtime=mode_runtime,
+        agent_runtime=agent_runtime,
+        skill_runtime=skill_runtime,
+        domain_pack=domain_pack_schema,
+    )
+    return {
+        "mode_runtime": mode_runtime,
+        "context_usage": context_usage,
+        "agent_runtime": agent_runtime,
+        "skill_runtime": skill_runtime,
+        **mode_orchestration,
+    }

flare_kernel/runtime/skill_runtime.py

@@ -0,0 +1,105 @@
+"""Placeholder skill runtime helpers for the kernel."""
+
+from __future__ import annotations
+
+from typing import Any
+
+_SKILL_CALLS_BY_MODE = {
+    "requirement_canvas": [
+        {
+            "skill_id": "mode_routing",
+            "agent_id": "intent_router_agent",
+            "status": "planned",
+            "permission_scope": "read_only",
+            "side_effect": "none",
+            "reason": "route the request into the active mode",
+        },
+        {
+            "skill_id": "requirement_field_capture",
+            "agent_id": "requirement_collector_agent",
+            "status": "planned",
+            "permission_scope": "read_only",
+            "side_effect": "none",
+            "reason": "capture the current requirement fields",
+        },
+        {
+            "skill_id": "knowledge_injection",
+            "agent_id": "knowledge_injector_agent",
+            "status": "planned",
+            "permission_scope": "read_only",
+            "side_effect": "none",
+            "reason": "inject supporting knowledge when needed",
+        },
+    ],
+    "intelligent_sourcing": [
+        {
+            "skill_id": "mode_routing",
+            "agent_id": "intent_router_agent",
+            "status": "planned",
+            "permission_scope": "read_only",
+            "side_effect": "none",
+            "reason": "route the request into the active mode",
+        },
+        {
+            "skill_id": "candidate_matching",
+            "agent_id": "sourcing_matcher_agent",
+            "status": "planned",
+            "permission_scope": "read_only",
+            "side_effect": "none",
+            "reason": "produce a candidate set from the current context",
+        },
+        {
+            "skill_id": "risk_summary",
+            "agent_id": "risk_summarizer_agent",
+            "status": "planned",
+            "permission_scope": "read_only",
+            "side_effect": "none",
+            "reason": "summarize sourcing risks for the candidate set",
+        },
+        {
+            "skill_id": "report_building",
+            "agent_id": "report_builder_agent",
+            "status": "planned",
+            "permission_scope": "read_only",
+            "side_effect": "none",
+            "reason": "assemble a structured sourcing report",
+        },
+    ],
+    "unknown": [
+        {
+            "skill_id": "mode_routing",
+            "agent_id": "intent_router_agent",
+            "status": "planned",
+            "permission_scope": "read_only",
+            "side_effect": "none",
+            "reason": "hold the request until a mode can be inferred",
+        }
+    ],
+}
+
+
+def _skill_calls_for_mode(mode_key: str) -> list[dict[str, Any]]:
+    return [dict(skill_call, call_index=index) for index, skill_call in enumerate(_SKILL_CALLS_BY_MODE.get(mode_key, _SKILL_CALLS_BY_MODE["unknown"]))]
+
+
+def build_skill_runtime(
+    *,
+    trace_id: str,
+    session_id: str,
+    intent: str,
+    function_type: str | None,
+    mode_runtime: dict[str, str],
+) -> dict[str, Any]:
+    mode_key = mode_runtime.get("mode_key", "unknown")
+    mode_state = mode_runtime.get("mode_state", "unknown")
+    skill_call = _skill_calls_for_mode(mode_key)
+    return {
+        "trace_id": trace_id,
+        "session_id": session_id,
+        "intent": intent,
+        "function_type": function_type,
+        "mode_key": mode_key,
+        "mode_state": mode_state,
+        "skill_call": skill_call,
+        "skill_call_count": len(skill_call),
+    }