precis-cli 0.1.3__py3-none-any.whl

app/shared/services/ai/streaming/sse_response.py

@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview SSE 响应封装
+
+把 EventJournal 的事件序列转换为 SSE (Server-Sent Events) 帧流。
+支持断线续传(Last-Event-ID)和已完成任务的完整回放。
+
+SSE 帧格式:
+    id: 5
+    event: delta
+    data: {"text": "你好"}
+
+(空行分隔帧)
+
+设计要点:
+- 续传: 先从 journal 读取 id > last_event_id 的事件快速回放,再切到实时推送
+- 终止: 遇到终止事件(completed/error/cancelled)后自动结束流
+- 心跳: 每隔一段时间发 :keep-alive 注释行,防止代理超时断开
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import AsyncIterator
+from typing import Any, cast
+
+from .event_journal import EventJournal
+
+logger = logging.getLogger(__name__)
+
+# 默认实时等待超时(秒):无新事件时的心跳间隔
+DEFAULT_LIVE_TIMEOUT = 15.0
+
+
+def format_sse_event(
+    event_id: int | None,
+    event: str | None,
+    data: dict[str, Any] | None,
+    heartbeat: bool = False,
+) -> str:
+    """
+    @methoddesc 格式化一个 SSE 帧
+
+    参数:
+        event_id: 事件 id,None 则不输出 id 行
+        event: 事件类型,None 则不输出 event 行(默认 message)
+        data: 事件数据(将被 JSON 序列化),None 则不输出 data 行
+        heartbeat: True 时返回心跳注释行(:keep-alive),忽略其他参数
+
+    返回:
+        SSE 帧字符串(以 \\n\\n 结尾)
+    """
+    if heartbeat:
+        return ":keep-alive\n\n"
+
+    lines: list[str] = []
+    if event_id is not None:
+        lines.append(f"id: {event_id}")
+    if event is not None:
+        lines.append(f"event: {event}")
+    if data is not None:
+        lines.append(f"data: {json.dumps(data, ensure_ascii=False)}")
+    return "\n".join(lines) + "\n\n"
+
+
+async def sse_event_stream(
+    journal: EventJournal,
+    last_event_id: int,
+    live_timeout: float = DEFAULT_LIVE_TIMEOUT,
+    event_queue: asyncio.Queue[dict[str, Any]] | None = None,
+) -> AsyncIterator[str]:
+    """
+    @methoddesc 生成 SSE 事件流
+
+    流程:
+    1. 从 journal 回放 id > last_event_id 的已有事件(快速,无延时)
+    2. 若回放的最后一条已是终止事件,直接结束(任务已完成的重连场景)
+    3. 否则切到实时模式: 从 event_queue 等待新事件,超时发心跳
+    4. 收到终止事件后结束
+
+    参数:
+        journal: 事件日志
+        last_event_id: 客户端最后收到的事件 id(0 表示从头)
+        live_timeout: 实时模式心跳间隔(秒)
+        event_queue: 实时事件队列,None 时只回放不实时(适合已完成任务)
+
+    返回:
+        AsyncIterator[str]: SSE 帧字符串
+    """
+    # 阶段 1: 回放 journal 中已有事件(从 last_event_id+1 开始)
+    replayed = journal.read_since(last_event_id)
+    terminated = False
+    for eid, event, data in replayed:
+        yield format_sse_event(event_id=eid, event=event, data=data)
+
+    # 记录回放水位：emit 先写 journal 再入队，回放期间队列中可能已积压同批事件，
+    # 实时消费时跳过 id <= 水位的事件，避免回放与实时重叠导致重复投递
+    last_replayed_id = replayed[-1][0] if replayed else last_event_id
+
+    # 阶段 2: 若回放的最后一条是终止事件,任务已结束,直接关闭流
+    from .types import TERMINAL_EVENTS
+
+    if replayed and replayed[-1][1] in TERMINAL_EVENTS:
+        return
+
+    # 若 journal 整体已终止(但 replayed 为空,即 last_event_id 已是最新),也关闭
+    if journal.is_terminated() and not replayed:
+        return
+
+    # 阶段 3: 实时模式(需要 event_queue)
+    if event_queue is None:
+        # 无队列(纯回放模式),若未终止则等待 journal 出现终止事件(轮询)
+        # 这种情况通常用于测试或已完成任务的重连
+        return
+
+    while not terminated:
+        try:
+            entry = await asyncio.wait_for(event_queue.get(), timeout=live_timeout)
+        except TimeoutError:
+            # 心跳: 防止代理超时
+            yield format_sse_event(event_id=None, event=None, data=None, heartbeat=True)
+            continue
+
+        rt_eid = cast("int | None", entry.get("id"))
+        rt_event = cast("str | None", entry.get("event"))
+        rt_data = cast("dict[str, Any] | None", entry.get("data"))
+        # 跳过回放阶段已投递过的事件（含已回放的终止事件——阶段 2 未退出说明该终止事件
+        # 必然也在回放末尾被投递过，直接丢弃即可，不会漏终止信号）
+        if isinstance(rt_eid, int) and rt_eid <= last_replayed_id:
+            continue
+        yield format_sse_event(event_id=rt_eid, event=rt_event, data=rt_data)
+        if rt_event in TERMINAL_EVENTS:
+            terminated = True

app/shared/services/ai/streaming/types.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview 流式事件类型与常量
+
+定义统一的 SSE 事件类型常量与终止事件集合。
+三个场景(chat/generate/migrate)共享同一套事件类型。
+"""
+
+from __future__ import annotations
+
+# 非终止事件类型
+EVENT_STARTED = "started"  # 任务启动，携带 job_id/kind
+EVENT_PROGRESS = "progress"  # 阶段进度（画像/分块/合并等），仅 generate/migrate
+EVENT_TURN_START = "turn_start"  # Agent 新一轮开始
+EVENT_DELTA = "delta"  # 流式文本块（增量，前端累积）
+EVENT_TOOL_CALL = "tool_call"  # 工具调用开始
+EVENT_TOOL_RESULT = "tool_result"  # 工具执行完成
+
+# 非终止事件类型：流式画布生长（Agent 模式）
+# apply_actions 落盘后，逐条 emit 单条 frontend_instruction，
+# 前端收到即立即执行 processFrontendInstructions + fitView，实现画布实时生长。
+# completed 事件仍携带全量 instructions 作为兜底。
+EVENT_FRONTEND_INSTRUCTION = "frontend_instruction"  # 单条前端指令已落盘
+
+# 非终止事件类型：apply_actions 两阶段确认
+EVENT_APPLY_PENDING = "apply_pending"  # dry-run diff 已就绪，等待用户确认
+EVENT_APPLY_CONFIRMED = "apply_confirmed"  # 用户确认，已落盘
+EVENT_APPLY_REJECTED = "apply_rejected"  # 用户拒绝，未落盘
+
+# 非终止事件类型：ask_user 交互问答
+EVENT_USER_INPUT_REQUESTED = "user_input_requested"  # agent 提问，等待用户输入
+EVENT_USER_RESPONDED = "user_responded"  # 用户已回答（或超时/skip），前端清态
+
+# 终止事件类型（发出后关闭 SSE 连接）
+EVENT_COMPLETED = "completed"  # 成功完成（含完整快照）
+EVENT_ERROR = "error"  # 失败
+EVENT_CANCELLED = "cancelled"  # 软取消确认
+
+# 终止事件集合：用于 is_terminated 判定
+# 注意: apply_pending/confirmed/rejected 是非终止事件，不加入此集合
+TERMINAL_EVENTS: frozenset[str] = frozenset({EVENT_COMPLETED, EVENT_ERROR, EVENT_CANCELLED})
+
+__all__ = [
+    "EVENT_STARTED",
+    "EVENT_PROGRESS",
+    "EVENT_TURN_START",
+    "EVENT_DELTA",
+    "EVENT_TOOL_CALL",
+    "EVENT_TOOL_RESULT",
+    "EVENT_FRONTEND_INSTRUCTION",
+    "EVENT_APPLY_PENDING",
+    "EVENT_APPLY_CONFIRMED",
+    "EVENT_APPLY_REJECTED",
+    "EVENT_USER_INPUT_REQUESTED",
+    "EVENT_USER_RESPONDED",
+    "EVENT_COMPLETED",
+    "EVENT_ERROR",
+    "EVENT_CANCELLED",
+    "TERMINAL_EVENTS",
+]

app/shared/services/ai/types.py

@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview AI 服务类型定义模块
+
+功能概述:
+- 定义 AI 配置生成所需的数据类型（ProfilingOptions、GenerateOptions 等）
+- 提供 LLM Provider 配置和 Chat 相关数据类
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# =============================================================================
+# 模块常量
+# =============================================================================
+
+# Precis V2 项目清单文件名
+# 所有 V2 项目使用统一的清单文件名称，便于识别和加载
+V2_MANIFEST_FILENAME = "project.precis.yaml"
+
+
+# =============================================================================
+# 数据画像选项
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class ProfilingOptions:
+    """
+    @classdesc 数据画像选项配置类
+
+    用于控制数据分析和样本提取的行为参数。这些选项决定了：
+    - 从每个数据文件读取多少行进行分析
+    - 每列提取多少样本值用于了解数据分布
+    - 最多处理多少个数据文件
+    - 单元格文本截断到多长
+
+    设计考虑：
+    - 使用 frozen=True 确保实例不可变，天然线程安全
+    - 所有字段有默认值，支持最小化配置
+    - 数值型默认值经过实践验证，在内存使用和分析精度间取得平衡
+
+    Attributes:
+        sample_rows: 从每个数据文件读取的最大行数
+                     用于生成数据画像供 AI 分析
+                     默认值 50 行 - 在内存使用和代表性之间取得平衡
+                     较大值可获得更准确的分析，但消耗更多内存
+        sample_values_per_column: 每列提取的样本值数量
+                                  用于了解数据分布和枚举值
+                                  默认值 10 个样本
+                                  对于枚举型字段可适当增加
+        max_files: 最多处理的数据文件数量
+                   防止资源耗尽和过长处理时间
+                   默认值 50 个文件
+                   批量处理大量文件时可调整
+        max_cell_chars: 单个单元格文本的最大保留字符数
+                        超过部分将被截断为 "..."
+                        默认值 200 字符
+                        长文本分析可适当增加
+
+    Example:
+        >>> # 使用默认选项
+        >>> opts = ProfilingOptions()
+        >>>
+        >>> # 自定义选项
+        >>> opts = ProfilingOptions(
+        ...     sample_rows=100,
+        ...     sample_values_per_column=20,
+        ...     max_files=10,
+        ...     max_cell_chars=500
+        ... )
+    """
+
+    sample_rows: int = 50
+    sample_values_per_column: int = 10
+    max_files: int = 50
+    max_cell_chars: int = 200
+
+
+# =============================================================================
+# 配置生成选项
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class GenerateOptions:
+    """
+    @classdesc 配置生成选项配置类
+
+    用于控制 V2 配置生成的行为参数。这些选项决定：
+    - 生成哪些类型的配置（schema、约束、正则节点）
+    - 如何处理现有配置（保留或覆盖）
+    - 使用哪个 AI 模型
+    - 仅处理哪些文件
+
+    设计考虑：
+    - 使用 frozen=True 确保实例不可变，天然线程安全
+    - 生成类选项默认为 True，保留现有配置默认为 True
+    - 提供细粒度控制能力
+
+    Attributes:
+        generate_schemas: 是否生成表结构定义（schema）
+                          启用后将为每个数据文件创建 TableSchemaFileV2
+                          包含列名、数据类型等信息
+                          默认值 True
+        generate_constraints: 是否生成约束规则
+                             启用后将调用 AI 生成约束建议
+                             注意：当前版本约束生成功能未完全实现
+                             默认值 True
+        generate_regex_nodes: 是否生成正则节点
+                              启用后将调用 AI 生成正则建议
+                              注意：当前版本正则节点生成功能未完全实现
+                              默认值 True
+        keep_existing: 是否保留现有配置
+                       True 时会合并现有配置，新生成内容将追加到现有内容
+                       False 时会清空并重新生成所有内容
+                       适用于增量更新特定文件的场景
+                       默认值 True
+        model: 使用的 Ollama 模型名称
+               用于生成约束和正则节点建议
+               未指定时使用环境变量 PRECIS_OLLAMA_MODEL
+               需要确保指定的模型已在本地安装
+               默认值 None（使用环境变量）
+        target_files: 仅处理指定的数据文件列表
+                      用于增量更新特定文件
+                      如果为 None 或空列表，则处理所有文件
+                      路径应为绝对路径或相对于工作目录的路径
+                      默认值 None（处理所有文件）
+
+    Example:
+        >>> # 使用默认选项
+        >>> opts = GenerateOptions()
+        >>>
+        >>> # 仅生成 schema
+        >>> opts = GenerateOptions(
+        ...     generate_schemas=True,
+        ...     generate_constraints=False,
+        ...     generate_regex_nodes=False
+        ... )
+        >>>
+        >>> # 使用特定模型并处理指定文件
+        >>> opts = GenerateOptions(
+        ...     model="qwen:7b",
+        ...     target_files=["/data/users.csv", "/data/orders.csv"]
+        ... )
+    """
+
+    generate_schemas: bool = True
+    generate_constraints: bool = True
+    generate_regex_nodes: bool = True
+    keep_existing: bool = True
+    model: str | None = None
+    target_files: list[str] | None = None
+
+
+# =============================================================================
+# AI Chat 相关类型
+# =============================================================================
+
+
+@dataclass
+class ChatContext:
+    """
+    @classdesc AI Chat 上下文数据类
+
+    用于传递项目上下文信息给 AI。
+
+    Attributes:
+        has_context: 是否有上下文
+        selected_nodes: 选中的节点列表
+        project_overview: 项目概览（表结构和约束）
+    """
+
+    has_context: bool = False
+    selected_nodes: list[dict[str, Any]] = field(default_factory=list)
+    project_overview: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ChatResult:
+    """
+    @classdesc AI Chat 执行结果数据类
+
+    统一 API 和 CLI 的结果格式。
+
+    Attributes:
+        success: 是否成功
+        reply: AI 回复文本
+        actions: 解析出的动作列表
+        frontend_instructions: 前端渲染指令
+        error: 错误信息（如果有）
+    """
+
+    success: bool
+    reply: str
+    actions: list[dict[str, Any]] = field(default_factory=list)
+    frontend_instructions: list[Any] = field(default_factory=list)
+    error: str | None = None