precis-cli 0.1.3__py3-none-any.whl

app/shared/services/llm/discovery/scanner.py

@@ -0,0 +1,181 @@
+# 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 服务（Ollama、OpenAI 兼容服务）
+- 扫描常用端口：Ollama(11434)、OpenAI 兼容(1234, 8080, 8000)
+- 检测服务健康状态并获取可用模型列表
+- 返回结构化的服务发现结果
+
+架构设计:
+- 配置驱动扫描：SCANS 字典定义各服务类型的检测规则
+- 异步 IO：使用 aiohttp 并发检测多个端口
+- 单例模式：全局 scanner 实例供 API 层调用
+
+输入示例:
+    services = await scanner.scan()
+    # 或指定主机
+    services = await scanner.scan(["localhost", "192.168.1.100"])
+
+输出示例:
+    [
+        DiscoveredService(
+            id="detected-ollama-11434",
+            name="Ollama @ :11434",
+            type="ollama",
+            base_url="http://localhost:11434",
+            models=["llama3.2", "qwen2.5"],
+            status="available"
+        )
+    ]
+"""
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class DiscoveredService:
+    """
+    @classdesc 发现的服务数据类
+
+    封装本地扫描到的 AI 服务信息，包括服务类型、URL、可用模型和状态。
+
+    字段:
+        id: 服务唯一标识
+        name: 服务显示名称
+        type: 服务类型（openai / ollama）
+        base_url: API 基础 URL
+        models: 可用模型列表
+        status: 服务状态（available / unavailable）
+    """
+
+    id: str
+    name: str
+    type: str  # openai / ollama
+    base_url: str
+    models: list[str]
+    status: str  # available / unavailable
+
+
+class ServiceScanner:
+    """
+    @classdesc 本地服务扫描器
+
+    自动发现本地运行的 AI 服务（Ollama、OpenAI 兼容服务）。
+    扫描常用端口：Ollama(11434)、OpenAI 兼容(1234, 8080, 8000)。
+    """
+
+    # 服务类型 -> 检测配置
+    SCANS: dict[str, dict[str, Any]] = {
+        "ollama": {"ports": [11434], "health_path": "/api/tags", "model_field": "models", "model_name_field": "name"},
+        "openai": {
+            "ports": [1234, 8080, 8000],
+            "health_path": "/v1/models",
+            "model_field": "data",
+            "model_name_field": "id",
+        },
+    }
+
+    async def scan(self, hosts: list[str] | None = None) -> list[DiscoveredService]:
+        """
+        @methoddesc 扫描本地运行的 AI 服务
+
+        遍历预定义的端口列表，尝试连接并识别 Ollama 和 OpenAI 兼容服务。
+
+        参数:
+            hosts: 要扫描的主机列表，默认扫描 localhost 和 127.0.0.1
+
+        返回:
+            发现的服务列表（DiscoveredService 对象列表）
+        """
+        if hosts is None:
+            hosts = ["localhost", "127.0.0.1"]
+
+        # 收集所有 (svc_type, host, port) 探测任务，并发执行（替代串行三层嵌套循环）
+        tasks = []
+        for svc_type, cfg in self.SCANS.items():
+            for host in hosts:
+                for port in cfg["ports"]:
+                    tasks.append(
+                        self._detect(
+                            svc_type, host, port, cfg["health_path"], cfg["model_field"], cfg["model_name_field"]
+                        )
+                    )
+
+        # 并发探测所有地址，过滤掉未发现的（None）
+        raw_results = await asyncio.gather(*tasks, return_exceptions=True)
+        results = [r for r in raw_results if isinstance(r, DiscoveredService)]
+
+        return results
+
+    async def _detect(
+        self, svc_type: str, host: str, port: int, path: str, model_field: str, name_field: str
+    ) -> DiscoveredService | None:
+        """
+        @methoddesc 检测单个地址是否运行着指定的 AI 服务
+
+        通过发送 GET 请求到健康检查路径，根据响应格式判断服务类型并提取模型列表。
+
+        参数:
+            svc_type: 服务类型标识（"ollama" 或 "openai"）
+            host: 主机名或 IP 地址
+            port: 端口号
+            path: 健康检查路径（如 /api/tags 或 /v1/models）
+            model_field: 响应 JSON 中模型列表的字段名
+            name_field: 模型对象中名称的字段名
+
+        返回:
+            如果发现服务返回 DiscoveredService，否则 None
+        """
+        url = f"http://{host}:{port}"
+        try:
+            # aiohttp 是 [ai]/[full] 可选依赖，按需延迟导入
+            import aiohttp
+
+            # 使用 aiohttp 发送异步 GET 请求，超时 5 秒
+            timeout = aiohttp.ClientTimeout(total=5)
+            async with aiohttp.ClientSession() as session:
+                async with session.get(f"{url}{path}", timeout=timeout) as resp:
+                    if resp.status != 200:
+                        return None
+
+                    data = await resp.json()
+                    # 从响应中提取模型名称列表
+                    models = [m[name_field] for m in data.get(model_field, [])]
+
+                    # 根据类型生成友好名称
+                    name_map = {"ollama": "Ollama", "openai": "OpenAI-Compatible"}
+                    base_name = name_map.get(svc_type, svc_type)
+
+                    return DiscoveredService(
+                        id=f"detected-{svc_type}-{port}",
+                        name=f"{base_name} @ :{port}",
+                        type=svc_type,
+                        base_url=url,
+                        models=models,
+                        status="available",
+                    )
+        except Exception:
+            # 连接失败、超时或响应格式不对，都视为未检测到服务
+            return None
+
+
+# 全局实例
+scanner = ServiceScanner()

app/shared/services/llm/generation/__init__.py

@@ -0,0 +1,42 @@
+# 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 LLM 配置生成服务模块入口
+
+功能概述:
+- 导出配置生成服务（ConfigGenerationService）及选项类
+- 供上层业务调用以生成 Precis 项目配置
+
+架构设计:
+- 聚合导出 service.py 中的公共类和异常
+- 通过 __all__ 控制对外暴露的接口
+
+输入示例:
+    from app.shared.services.llm.generation import ConfigGenerationService, GenerationOptions
+
+输出示例:
+    service = ConfigGenerationService(provider_id="openai")
+    result = await service.generate(...)
+"""
+
+from .service import CancelledError, ConfigGenerationService, GenerationOptions, GenerationParseError, ProfilingOptions
+
+__all__ = [
+    "ConfigGenerationService",
+    "GenerationOptions",
+    "ProfilingOptions",
+    "CancelledError",
+    "GenerationParseError",
+]

app/shared/services/llm/generation/agent_wiring.py

@@ -0,0 +1,156 @@
+# 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 Agent 模式装配（工具注册表 + 提示词构建）
+
+把 ConfigGenerationService 中与 AgentExecutor 装配相关的纯构建逻辑
+抽出为无状态函数：工具注册表创建、系统提示词与任务消息构建。
+注册表中的 generate/refine 工具持有 service 实例引用（工具内部回调
+service 的生成/精修能力），故 create_agent_registry 以 service 为参数。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .profiler import format_profiling_for_agent
+
+if TYPE_CHECKING:
+    from app.shared.services.ai.agent.tool_registry import ToolRegistry
+
+    from .service import ConfigGenerationService
+
+
+def create_agent_registry(
+    service: ConfigGenerationService,
+    validation_sample_size: int,
+    chunk_max_columns: int,
+    chunk_max_files: int,
+) -> ToolRegistry:
+    """创建 Agent 工具注册表。
+
+    参数:
+        service: 配置生成服务实例（generate/refine 工具的执行宿主）
+        validation_sample_size: validate_config 工具的抽样行数
+        chunk_max_columns: 分块列数上限（plan_chunks 工具）
+        chunk_max_files: 分块文件数上限（plan_chunks 工具）
+
+    返回:
+        已注册全部五个工具的 ToolRegistry
+    """
+    from app.shared.services.ai.agent.tool_registry import ToolRegistry
+    from app.shared.services.ai.agent.tools import (
+        ConfigGenerateTool,
+        ConfigRefineTool,
+        ConfigValidateTool,
+        MergeResultsTool,
+        PlanChunksTool,
+    )
+
+    registry = ToolRegistry()
+
+    # 工具注册统一走 register_tool（name/description/parameters/handler 自动提取）
+    registry.register_tool(
+        PlanChunksTool(
+            profiling_data=service._profiling_data,
+            file_paths=service._file_paths,
+            chunk_max_columns=chunk_max_columns,
+            chunk_max_files=chunk_max_files,
+        )
+    )
+    registry.register_tool(MergeResultsTool())
+    # generate/refine 工具持有 service 引用（工具内部回调 service 的生成/精修能力）
+    registry.register_tool(ConfigGenerateTool(service))
+    registry.register_tool(
+        ConfigValidateTool(
+            file_paths=service._file_paths,
+            profiling_data=service._profiling_data,
+            sample_size=validation_sample_size,
+        )
+    )
+    registry.register_tool(ConfigRefineTool(service))
+
+    return registry
+
+
+def build_agent_system_prompt() -> str:
+    """构建 Agent 系统提示词。"""
+    return """你是一个数据治理专家 Agent，擅长分析数据文件并生成 Precis V2 数据验证配置。
+
+你的任务是根据用户提供的数据文件画像，生成高质量的 schemas、constraints、regex_nodes 配置。
+
+可用工具：
+1. plan_chunks: 根据数据画像生成分块计划（大数据量时先调用）。
+2. generate_config: 根据画像生成完整配置。这是最终输出工具，工具返回的 config 会被作为 Agent 最终结果，调用后任务即结束。
+3. merge_results: 合并多个局部配置为一个完整配置（分块生成后使用）。
+4. validate_config: 对配置做抽样校验，返回问题列表（中间工具）。
+5. refine_config: 根据校验问题修正配置（中间工具）。
+
+工作原则：
+- 最终必须通过调用 generate_config 工具输出配置，不要直接输出 JSON 文本。
+- 如果数据量小，直接调用 generate_config 生成完整配置。
+- 如果用户开启了 auto_chunking 且数据量大（文件数 > chunk_max_files 或列数 > chunk_max_columns），先调用 plan_chunks，然后按 chunk 多次调用 generate_config，最后用 merge_results 合并，再调用一次 generate_config 输出最终配置。
+- 可选流程：generate_config → validate_config → refine_config → generate_config（最终）。
+- 你最多只能调用有限次工具，不要把大量时间浪费在反复校验上。"""
+
+
+def build_agent_task_message(
+    profiling_data: list[dict],
+    project_name: str,
+    project_id: str,
+    keep_existing: bool,
+    auto_chunking: bool,
+    chunk_max_columns: int,
+    chunk_max_files: int,
+) -> str:
+    """构建 Agent 任务消息。
+
+    参数:
+        profiling_data: 数据画像结果
+        project_name: 项目显示名
+        project_id: 项目标识符
+        keep_existing: 是否保留既有配置
+        auto_chunking: 是否开启自动分块
+        chunk_max_columns: 分块列数上限
+        chunk_max_files: 分块文件数上限
+
+    返回:
+        拼装完成的任务消息文本
+    """
+    parts = [
+        f"为项目 '{project_name}' (id={project_id}) 生成数据验证配置。",
+        "",
+        "## 数据画像",
+        format_profiling_for_agent(profiling_data),
+        "",
+        "## 要求",
+        "- 生成 schemas、constraints、regex_nodes",
+        f"- keep_existing={'true' if keep_existing else 'false'}",
+        f"- auto_chunking={'true' if auto_chunking else 'false'}",
+    ]
+    if auto_chunking:
+        parts.extend(
+            [
+                f"- chunk_max_columns={chunk_max_columns}",
+                f"- chunk_max_files={chunk_max_files}",
+            ]
+        )
+    parts.extend(
+        [
+            "- 工作流建议：直接调用 generate_config 生成完整配置；如果希望更可靠，可以生成后调用 validate_config 校验，再调用 refine_config 修正，最后再次调用 generate_config 输出最终配置。",
+            "- 最终必须调用 generate_config 工具，其返回的 config 即为最终结果。",
+        ]
+    )
+    return "\n".join(parts)