skill-self-evolution 0.2.0__tar.gz

skill_self_evolution-0.2.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: skill_self_evolution
+Version: 0.2.0
+Summary: Skill 自进化框架：Pydantic 全链路校验 + 规则执行 + AI 常识判断 + 离线进化的可插拔 Skill 执行引擎
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.25
+Requires-Dist: pymysql>=1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

skill_self_evolution-0.2.0/README.md

@@ -0,0 +1,99 @@
+# skill_self_evolution v0.2.0
+
+Skill 自进化框架：**Pydantic 全链路校验** + 规则执行 + AI 常识判断 + 离线进化的可插拔 Skill 执行引擎。
+
+## v0.2.0 更新
+
+- **Pydantic 全链路覆盖**：12 个源文件，8 个完整 Pydantic 校验（4 个有理据豁免）
+- 新增 11 个 Pydantic 模型，覆盖 AI 中间结果、DeepSeek 响应、JSONL 日志、降级配置、进化提案、Skill 子结构
+- `AiValidationResult` / `AiReselectionResult` 用 `Literal["合理","不合理"]` 替代裸 `dict.get("result")`
+- `DeepSeekChatResponse` 替代 dataclass，字段缺失自动默认值
+- `ConfigVersionManager` 兼容 `dict` 和 `DbConfig` 双路径
+
+## 架构
+
+```
+输入 (SkillInput)       规则执行              AI 校验           AI 重选            日志 & 进化
+  input_data     →    execute()     →    _ai_validate()  →  _ai_reselect()  →  JSONL + Evolver
+    │                     │                   │                  │                  │
+    └─ Pydantic ✅        └─ SkillOutput ✅    └─ AiValidation   └─ AiReselection   └─ LogEntry/Proposal
+                                                 Result ✅          Result ✅            ✅
+```
+
+## Pydantic 模型清单
+
+### 核心框架
+
+| 模型 | 作用 | 校验内容 |
+|---|---|---|
+| `SkillInput[T]` | 入口 | `trace_id` + `input_data`（泛型） |
+| `SkillOutput` | 出口 | `source` + `result` + `ai_validated` + `ai_reselected` |
+
+### AI 中间结果（v0.2.0 新增）
+
+| 模型 | 作用 | 校验约束 |
+|---|---|---|
+| `AiValidationResult` | AI 验证输出 | `Literal["合理","不合理"]` + reason ≤500字 |
+| `AiReselectionResult` | AI 重选输出 | `result: str` + reason ≤500字 |
+
+### 数据层（v0.2.0 新增）
+
+| 模型 | 作用 |
+|---|---|
+| `DeepSeekChatResponse` | HTTP 响应结构校验 |
+| `LogEntry` | JSONL 日志条目（11 字段全默认值容错） |
+| `FallbackConfigModel` | 降级参数（gt/ge/le 约束） |
+| `EvolveProposalModel` | 进化提案序列化 |
+| `NicknameSkillResult` | nickname-selector 子结构示例 |
+| `DeepSeekEnvConfig` | API 连接配置 |
+| `DbConfig` | 数据库连接配置（port ge=1 le=65535） |
+
+## 快速开始
+
+```python
+from skill_self_evolution import SkillExecutor
+
+executor = SkillExecutor(
+    deepseek_api_key="sk-xxx",  # 或设置 DEEPSEEK_API_KEY
+    skill_base_dir="/path/to/skills",
+)
+result = await executor.run("nickname-selector", {
+    "screenshot_id": "scr_004",
+    "metadata_path": "/path/to/metadata.json",
+    "debug_session_derived_path": "/path/to/debug_session_derived.json",
+})
+```
+
+## 安装
+
+```bash
+pip install skill_self_evolution
+```
+
+## 开发
+
+```bash
+# 本地安装（开发模式）
+pip install -e .
+
+# 运行测试
+pytest
+```
+
+## 环境变量
+
+| 变量 | local 默认 | test/prod 默认 |
+|---|---|---|
+| `DEEPSEEK_API_KEY` | DeepSeek 官网 Key | — |
+| `DEEPSEEK_API_BASE` | `https://api.deepseek.com/v1` | — |
+| `WX_MATCH_DEEPSEEK_API_KEY` | — | 华为云 MaaS Key |
+| `WX_MATCH_DEEPSEEK_API_BASE` | — | `https://api.modelarts-maas.com/v2` |
+| `APP_ENV` | `local` | `test` / `prod` |
+| `DB_HOST` | `127.0.0.1` | 环境注入 |
+| `DB_USER` / `DB_PASSWORD` / `DB_NAME` | `root` / (空) / `housekeeping_ai_match_dev` | 同上 |
+| `SKILL_BASE_DIR` | `backend/config/services/skill/` | 同上 |
+| `SKILL_LOG_DIR` | `/data/skill-logs` | 同上 |
+
+## License
+
+MIT

skill_self_evolution-0.2.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skill_self_evolution"
+version = "0.2.0"
+description = "Skill 自进化框架：Pydantic 全链路校验 + 规则执行 + AI 常识判断 + 离线进化的可插拔 Skill 执行引擎"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+    "httpx>=0.25",
+    "pymysql>=1.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+packages = ["skill_self_evolution"]

skill_self_evolution-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

skill_self_evolution-0.2.0/src/skill_self_evolution/__init__.py

@@ -0,0 +1,27 @@
+"""
+Skill Engine — 自进化框架核心。
+
+规则执行 → AI 常识判断 → 合理就过 / 不合理 AI 从原始数据重选 → 日志记录 → 离线进化 → 优化配置
+"""
+
+from skill_self_evolution.executor import SkillExecutor
+from skill_self_evolution.models import SkillInput, SkillOutput
+from skill_self_evolution.context import get_trace_id, set_trace_id
+from skill_self_evolution.logger import SkillLogger
+from skill_self_evolution.fallback import FallbackStrategy
+from skill_self_evolution.config_loader import ConfigVersionManager
+from skill_self_evolution.evolver import Evolver
+from skill_self_evolution.ai_assisted_executor import AiAssistedExecutor
+
+__all__ = [
+    "SkillExecutor",
+    "SkillInput",
+    "SkillOutput",
+    "get_trace_id",
+    "set_trace_id",
+    "SkillLogger",
+    "FallbackStrategy",
+    "ConfigVersionManager",
+    "Evolver",
+    "AiAssistedExecutor",
+]

skill_self_evolution-0.2.0/src/skill_self_evolution/ai_assisted_executor.py

@@ -0,0 +1,244 @@
+"""
+AiAssistedExecutor — 通用 AI 辅助执行基类。
+
+提供「验证 + 重选」的通用流程模板，Skill 只需定义：
+  - ai_validate()：AI 常识判断（correction 角色） → AiValidationResult
+  - ai_reselect()：AI 重新选择/提取（correction 角色） → AiReselectionResult
+  - ai_enhance()：AI 增强（enhancement 角色） → dict | None
+
+框架自动处理：降级、熔断、is_failure 计算、JSONL 日志。
+"""
+
+import logging
+import time
+from abc import ABC, abstractmethod
+from typing import Any
+
+from skill_self_evolution.context import set_trace_id
+from skill_self_evolution.fallback import FallbackConfig, FallbackResult, FallbackStrategy
+from skill_self_evolution.loader import SkillModule
+from skill_self_evolution.logger import SkillLogger
+from skill_self_evolution.models import (
+    AiReselectionResult,
+    AiValidationResult,
+    SkillInput,
+    SkillOutput,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AiAssistedExecutor(ABC):
+    """AI 辅助执行基类。
+
+    子类只需实现 2-3 个抽象方法，框架自动处理流程编排和降级。
+    """
+
+    @abstractmethod
+    async def ai_validate(
+        self,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        prompt_config: dict | None,
+    ) -> AiValidationResult:
+        """AI 常识判断（correction 角色）。
+
+        Returns:
+            AiValidationResult: result=合理/不合理 + reason
+        """
+
+    @abstractmethod
+    async def ai_reselect(
+        self,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        prompt_config: dict | None,
+    ) -> AiReselectionResult:
+        """AI 重新选择/提取（correction 角色）。
+
+        Returns:
+            AiReselectionResult: result=重选值（或"不合理"） + reason
+        """
+
+    async def ai_enhance(
+        self,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        prompt_config: dict | None,
+    ) -> dict | None:
+        """AI 增强（enhancement 角色）。默认不增强，子类按需覆盖。"""
+        return None
+
+    async def run_correction_flow(
+        self,
+        skill: SkillModule,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        prompt_config: dict | None,
+        fallback: FallbackStrategy,
+    ) -> SkillOutput:
+        """correction 角色完整流程：验证 → 重选。"""
+        t0 = time.monotonic()
+        warnings: list[str] = list(rule_output.warnings) if rule_output.warnings else []
+
+        # 1. 熔断检查
+        fb_check = fallback.check_before_ai()
+        if fb_check.skip_ai:
+            warnings.extend(fb_check.warnings)
+            elapsed = (time.monotonic() - t0) * 1000
+            rule_output.warnings = warnings
+            self._log(skill, skill_input, rule_output, None, None, rule_output, warnings, elapsed)
+            return rule_output
+
+        # 2. AI 验证
+        ai_validation: AiValidationResult | None = None
+        try:
+            ai_validation = await self.ai_validate(skill_input, rule_output, prompt_config)
+            rule_output.ai_validated = True
+        except Exception as e:
+            logger.warning("Skill [%s] AI 验证异常: %s", skill.skill_name, e)
+            fb_result = fallback.on_validate_failure(e)
+            warnings.extend(fb_result.warnings)
+            if fb_result.skip_ai:
+                elapsed = (time.monotonic() - t0) * 1000
+                rule_output.ai_validated = False
+                rule_output.warnings = warnings
+                is_failure = self._is_failure(skill.ai_role, rule_output, None, None)
+                self._log(skill, skill_input, rule_output, None, None, rule_output, warnings, elapsed)
+                return rule_output
+
+        # 3. 验证不合理 → 重选
+        if ai_validation and ai_validation.result == "不合理":
+            fb_reselect = fallback.check_before_ai()
+            if fb_reselect.skip_ai:
+                warnings.extend(fb_reselect.warnings)
+                elapsed = (time.monotonic() - t0) * 1000
+                is_failure = self._is_failure(skill.ai_role, rule_output, ai_validation, None)
+                rule_output.warnings = warnings
+                self._log(skill, skill_input, rule_output, ai_validation, None, rule_output, warnings, elapsed)
+                return rule_output
+
+            try:
+                ai_reselection = await self.ai_reselect(skill_input, rule_output, prompt_config)
+                if ai_reselection and ai_reselection.result != "不合理":
+                    final_result = ai_reselection.result
+                    final_output = SkillOutput(
+                        source="ai",
+                        result=final_result if isinstance(final_result, dict) else {"value": final_result},
+                        ai_validated=True,
+                        ai_reselected=True,
+                        warnings=warnings,
+                    )
+                    elapsed = (time.monotonic() - t0) * 1000
+                    is_failure = self._is_failure(skill.ai_role, rule_output, ai_validation, ai_reselection)
+                    self._log(skill, skill_input, rule_output, ai_validation, ai_reselection, final_output, warnings, elapsed)
+                    return final_output
+                else:
+                    warnings.append("AI 重选后仍不合理")
+                    rule_output.ai_reselected = True
+            except Exception as e:
+                logger.warning("Skill [%s] AI 重选异常: %s", skill.skill_name, e)
+                fb_result2 = fallback.on_reselect_failure(e)
+                warnings.extend(fb_result2.warnings)
+
+        # 4. 验证合理或重选失败 → 返回规则结果
+        rule_output.warnings = warnings
+        elapsed = (time.monotonic() - t0) * 1000
+        is_failure = self._is_failure(skill.ai_role, rule_output, ai_validation, None)
+        self._log(skill, skill_input, rule_output, ai_validation, None, rule_output, warnings, elapsed)
+        return rule_output
+
+    async def run_enhancement_flow(
+        self,
+        skill: SkillModule,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        prompt_config: dict | None,
+        fallback: FallbackStrategy,
+    ) -> SkillOutput:
+        """enhancement 角色流程：规则 + AI 增强。"""
+        t0 = time.monotonic()
+        warnings: list[str] = list(rule_output.warnings) if rule_output.warnings else []
+
+        fb_check = fallback.check_before_ai()
+        if fb_check.skip_ai:
+            warnings.extend(fb_check.warnings)
+            elapsed = (time.monotonic() - t0) * 1000
+            rule_output.warnings = warnings
+            self._log(skill, skill_input, rule_output, None, None, rule_output, warnings, elapsed)
+            return rule_output
+
+        try:
+            ai_result = await self.ai_enhance(skill_input, rule_output, prompt_config)
+            merged = {**rule_output.result} if isinstance(rule_output.result, dict) else {}
+            if ai_result:
+                merged.update(ai_result)
+            final_output = SkillOutput(
+                source=rule_output.source,
+                result=merged,
+                ai_validated=True,
+                ai_reselected=False,
+                warnings=warnings,
+            )
+            elapsed = (time.monotonic() - t0) * 1000
+            self._log(skill, skill_input, rule_output, None, None, final_output, warnings, elapsed)
+            return final_output
+        except Exception as e:
+            logger.warning("Skill [%s] AI 增强异常: %s", skill.skill_name, e)
+            elapsed = (time.monotonic() - t0) * 1000
+            rule_output.warnings = warnings
+            self._log(skill, skill_input, rule_output, None, None, rule_output, warnings, elapsed)
+            return rule_output
+
+    @staticmethod
+    def _is_failure(
+        ai_role: str,
+        rule_output: SkillOutput,
+        ai_validation: AiValidationResult | None,
+        ai_reselection: AiReselectionResult | None,
+    ) -> bool:
+        """根据 ai_role 计算 is_failure（Pydantic 属性访问）。"""
+        if ai_role == "enhancement":
+            return False
+        if ai_role == "correction":
+            if ai_validation and ai_validation.result == "不合理":
+                return True
+            if ai_reselection and ai_reselection.result == "不合理":
+                return True
+        return False
+
+    def _log(
+        self,
+        skill: SkillModule,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        ai_validation: AiValidationResult | None,
+        ai_reselection: AiReselectionResult | None,
+        final_output: SkillOutput,
+        warnings: list[str],
+        elapsed_ms: float,
+    ) -> None:
+        """写入 JSONL 日志（Pydantic LogEntry 校验）。"""
+        try:
+            log_writer = SkillLogger(skill.skill_name)
+            if skill.summarize_input:
+                input_summary = skill.summarize_input(skill_input.input_data)
+            elif isinstance(skill_input.input_data, dict):
+                keys = list(skill_input.input_data.keys())[:5]
+                input_summary = {k: str(skill_input.input_data[k])[:100] for k in keys}
+            else:
+                input_summary = {"type": type(skill_input.input_data).__name__}
+
+            log_writer.log_execution(
+                trace_id=skill_input.trace_id or "",
+                is_failure=(ai_validation is not None and ai_validation.result == "不合理"),
+                input_summary=input_summary,
+                rule_output=rule_output.result,
+                ai_validation=ai_validation.model_dump() if ai_validation else None,
+                ai_reselection=ai_reselection.model_dump() if ai_reselection else None,
+                final_output=final_output.result,
+                warnings=warnings,
+                elapsed_ms=elapsed_ms,
+            )
+        except Exception as e:
+            logger.warning("Skill 日志记录失败: %s", e)

skill_self_evolution-0.2.0/src/skill_self_evolution/config.py

@@ -0,0 +1,87 @@
+"""
+?????? ? ? APP_ENV ?? DeepSeek API ???????
+
+- local: DeepSeek ?? API (api.deepseek.com)
+- test/prod: ??? MaaS (api.modelarts-maas.com/v2)
+"""
+
+import os
+
+from pydantic import BaseModel, Field
+
+__all__ = ["DeepSeekEnvConfig", "DbConfig", "get_deepseek_config", "get_db_config"]
+
+
+class DeepSeekEnvConfig(BaseModel):
+    """DeepSeek API ?????Pydantic ????"""
+
+    api_key: str = Field(default="", description="API Key")
+    api_base: str = Field(
+        default="https://api.deepseek.com/v1",
+        description="API ????",
+    )
+    model: str = Field(default="deepseek-chat", description="????")
+
+
+class DbConfig(BaseModel):
+    """????????Pydantic ????"""
+
+    host: str = Field(default="127.0.0.1")
+    port: int = Field(default=3306, ge=1, le=65535)
+    user: str = Field(default="root")
+    password: str = Field(default="")
+    database: str = Field(default="housekeeping_ai_match_dev")
+
+
+def _resolve_app_env() -> str:
+    return os.getenv("APP_ENV", "local").strip().lower()
+
+
+def get_deepseek_config(
+    api_key: str = "",
+    api_base: str = "",
+    model: str = "",
+) -> DeepSeekEnvConfig:
+    env = _resolve_app_env()
+    if api_key and api_base:
+        return DeepSeekEnvConfig(
+            api_key=api_key,
+            api_base=api_base,
+            model=model or "deepseek-chat",
+        )
+    if env == "local":
+        key = api_key or os.getenv("DEEPSEEK_API_KEY", "")
+        base = api_base or os.getenv("DEEPSEEK_API_BASE", "https://api.deepseek.com/v1")
+        m = model or os.getenv("DEEPSEEK_MODEL", "deepseek-chat")
+        return DeepSeekEnvConfig(api_key=key, api_base=base, model=m)
+    else:
+        key = api_key or os.getenv("WX_MATCH_DEEPSEEK_API_KEY", "")
+        base = api_base or os.getenv(
+            "WX_MATCH_DEEPSEEK_API_BASE", "https://api.modelarts-maas.com/v2"
+        )
+        m = model or os.getenv("WX_MATCH_AI_MODEL_NAME", "DeepSeek-V3.2")
+        return DeepSeekEnvConfig(api_key=key, api_base=base, model=m)
+
+
+def get_db_config(
+    host: str = "",
+    port: int = 0,
+    user: str = "",
+    password: str = "",
+    database: str = "",
+) -> DbConfig:
+    if host and user and password:
+        return DbConfig(
+            host=host,
+            port=port or 3306,
+            user=user,
+            password=password,
+            database=database or "housekeeping_ai_match_dev",
+        )
+    return DbConfig(
+        host=host or os.getenv("DB_HOST", "127.0.0.1"),
+        port=port or int(os.getenv("DB_PORT", "3306")),
+        user=user or os.getenv("DB_USER", "root"),
+        password=password or os.getenv("DB_PASSWORD", ""),
+        database=database or os.getenv("DB_NAME", "housekeeping_ai_match_dev"),
+    )