cellium-agent 1.4.0__py3-none-any.whl

app/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""
+Cellium Agent - 应用根包
+"""

app/agent/control/__init__.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+"""
+Control Loop Harness - LLM 控制环
+
+核心组件：
+  - LoopState: 控制环状态快照
+  - ControlDecision: Action-based 决策
+  - FeedbackEvaluator: 分段式反馈评估
+  - ActionBandit: Action 选择器
+  - ControlLoop: 统一控制入口
+  - DecisionRenderer: 软约束渲染器（默认）
+  - HardConstraintRenderer: 强约束渲染器（PromptBuilder v3）
+  - ThoughtParser: 思考解析器
+  - HybridController: Plan-Execute-Observe-RePlan 混合控制器
+
+Gene 相关（constraint_gene 子模块）：
+  - TaskSignalMatcher: 任务信号匹配器
+  - GeneEvolution: Gene 进化系统
+  - GeneComposer: Gene 组合器
+"""
+
+from .loop_state import LoopState, ControlDecision
+from .feedback_evaluator import FeedbackEvaluator
+from .action_bandit import ActionBandit
+from .control_loop import ControlLoop, create_control_loop
+from .decision_renderer import DecisionRenderer, RenderedPrompt
+from .hard_constraints import (
+    HardConstraint,
+    HardConstraintRenderer,
+    HardConstraintTemplates,
+    ActionFusion,
+)
+from .thought_parser import (
+    ThoughtParser,
+    ParsedThought,
+    ThoughtStep,
+    ActionType,
+    THOUGHT_SCHEMA,
+)
+from .hybrid_controller import (
+    HybridController,
+    HybridPhase,
+    HybridState,
+    Observation,
+    create_hybrid_controller,
+)
+
+from .constraint_gene import TaskSignalMatcher, GeneEvolution, GeneComposer
+from .gene_post_session import GenePostSessionAnalyzer, analyze_session_for_gene
+
+__all__ = [
+    "LoopState",
+    "ControlDecision",
+    "FeedbackEvaluator",
+    "ActionBandit",
+    "ControlLoop",
+    "create_control_loop",
+    "DecisionRenderer",
+    "RenderedPrompt",
+    # 强约束版
+    "HardConstraint",
+    "HardConstraintRenderer",
+    "HardConstraintTemplates",
+    "ActionFusion",
+    # 思考系统
+    "ThoughtParser",
+    "ParsedThought",
+    "ThoughtStep",
+    "ActionType",
+    "THOUGHT_SCHEMA",
+    # Hybrid 控制器
+    "HybridController",
+    "HybridPhase",
+    "HybridState",
+    "Observation",
+    "create_hybrid_controller",
+    # Gene 相关
+    "TaskSignalMatcher",
+    "GeneEvolution",
+    "GeneComposer",
+    # 会话后 Gene 分析
+    "GenePostSessionAnalyzer",
+    "analyze_session_for_gene",
+]

app/agent/control/action_bandit.py

@@ -0,0 +1,336 @@
+# -*- coding: utf-8 -*-
+"""
+ActionBandit - Action-based Bandit
+"""
+
+import json
+import logging
+import os
+from collections import deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+ACTION_TYPES = ["continue", "retry", "redirect", "compress", "terminate"]
+ACTION_PRIORITY = ["continue", "retry", "compress", "redirect", "terminate"]
+
+
+@dataclass
+class ActionStats:
+    """单个 Action 的统计数据"""
+    alpha: float = 2.0
+    beta: float = 2.0
+    count: int = 0
+
+    def to_dict(self) -> Dict:
+        return {"alpha": self.alpha, "beta": self.beta, "count": self.count}
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> "ActionStats":
+        return cls(
+            alpha=data.get("alpha", 2.0),
+            beta=data.get("beta", 2.0),
+            count=data.get("count", 0),
+        )
+
+
+class ActionBandit:
+    """
+    Action-based Bandit
+    """
+
+    def __init__(self, memory_path: Optional[str] = None, n_step: int = 3):
+        """
+        初始化
+
+        Args:
+            memory_path: 统计数据持久化路径
+            n_step: n-step return 窗口大小
+        """
+        self.memory_path = memory_path
+        self.n_step = n_step
+
+        self._stats: Dict[str, ActionStats] = {
+            action: ActionStats() for action in ACTION_TYPES
+        }
+
+        self._decay_factor = 0.99
+        self._decay_interval = 50
+        self._session_count = 0
+
+        self._policy_thresholds: Dict[str, Any] = {}
+        self._reward_buffer: deque = deque(maxlen=n_step)
+        self._last_actions: deque = deque(maxlen=n_step)
+
+        if memory_path:
+            self._load()
+
+    def select_action(
+        self,
+        features: Any,
+        candidate_actions: Optional[List[str]] = None,
+    ) -> str:
+        """
+        选择 Action。
+
+        当前策略：
+          1. 规则/控制环先给出候选 action
+          2. Bandit 只在候选集合内部做 tie-break
+          3. terminate 仍保留硬规则保护
+        """
+        is_terminate_hard = (
+            hasattr(features, 'is_output_loop')
+            and features.is_output_loop
+            and hasattr(features, 'exact_repetition_count')
+            and features.exact_repetition_count >= 5
+        )
+
+        if is_terminate_hard:
+            logger.info(
+                "[ActionBandit] 硬规则: terminate (output_loop=%d)",
+                features.exact_repetition_count
+            )
+            return "terminate"
+
+        candidates = self._normalize_candidates(candidate_actions)
+        if not candidates:
+            return "continue"
+
+        if len(candidates) == 1:
+            return candidates[0]
+
+        action = self._thompson_with_bias(features, candidate_actions=candidates)
+        logger.debug("[ActionBandit] tie-break: %s | candidates=%s", action, candidates)
+        return action
+
+    def _normalize_candidates(self, candidate_actions: Optional[List[str]]) -> List[str]:
+        if not candidate_actions:
+            return [action for action in ACTION_TYPES if action != "terminate"]
+
+        candidates = []
+        for action in candidate_actions:
+            if action in ACTION_TYPES and action not in candidates:
+                candidates.append(action)
+
+        return candidates
+
+    def _thompson_with_bias(self, features: Any, candidate_actions: Optional[List[str]] = None) -> str:
+        """
+        Thompson Sampling + Heuristic Bias
+
+        原理：
+          - 每个 action 从 Beta 分布采样
+          - 加上 Heuristic 提供的 bias
+          - 选择分数最高的 action
+        """
+        import random
+
+        candidates = self._normalize_candidates(candidate_actions) or list(self._stats.keys())
+
+        scores = {}
+        for action in candidates:
+            stats = self._stats[action]
+
+            try:
+                import numpy as np
+                sample = np.random.beta(stats.alpha, stats.beta)
+            except ImportError:
+                mean = stats.alpha / (stats.alpha + stats.beta) if (stats.alpha + stats.beta) > 0 else 0.5
+                noise = random.gauss(0, 0.1)
+                sample = max(0, min(1, mean + noise))
+
+            bias = self._heuristic_bias(action, features)
+
+            scores[action] = sample + bias
+
+        if not scores:
+            return "continue"
+
+        max_score = max(scores.values())
+        best_actions = [a for a, s in scores.items() if s == max_score]
+
+        # 优先级：continue > retry > compress > redirect > terminate
+        for priority_action in ACTION_PRIORITY:
+            if priority_action in best_actions:
+                return priority_action
+
+        return best_actions[0]
+
+    def _heuristic_bias(self, action: str, features: Any) -> float:
+        """
+        Heuristic Bias 计算
+
+        原理：
+          - Heuristic 不决定 action，只调整分数
+          - bias > 0 表示"推荐"，但 Bandit 仍可选择其他
+          - 不同 action 有不同的触发条件
+          - 使用 Policy 阈值动态调整判断条件
+          - 冷启动保护：统计不足时自动放大 bias，让启发式兜底
+
+        Returns:
+            bias 值 [0, 1]
+        """
+        bias = 0.0
+
+        stuck_threshold = self._policy_thresholds.get("stuck_iterations", 5)
+        repetition_threshold = self._policy_thresholds.get("repetition_threshold", 4)
+        repetition_score_threshold = self._policy_thresholds.get("repetition_score", 0.7)
+
+        if action == "redirect":
+            if hasattr(features, 'repetition_score') and features.repetition_score > repetition_score_threshold:
+                bias = max(bias, 0.03 * features.repetition_score)
+            if hasattr(features, 'stuck_iterations') and features.stuck_iterations >= stuck_threshold:
+                bias = max(bias, 0.04)
+
+        if action == "retry":
+            if hasattr(features, 'stuck_iterations') and 1 <= features.stuck_iterations < stuck_threshold:
+                bias = max(bias, 0.02)
+            if hasattr(features, 'progress_trend') and 0 < features.progress_trend < 0.3:
+                bias = max(bias, 0.01)
+
+        if action == "compress":
+            if hasattr(features, 'context_saturation') and features.context_saturation > 0.6:
+                bias = max(bias, 0.03)
+            if hasattr(features, 'stuck_iterations') and features.stuck_iterations >= stuck_threshold // 2:
+                bias = max(bias, 0.02)
+
+        if action == "continue":
+            if hasattr(features, 'progress_score') and features.progress_score > 0.5:
+                bias = max(bias, 0.02)
+            if hasattr(features, 'stuck_iterations') and features.stuck_iterations == 0:
+                bias = max(bias, 0.03)
+
+        # 冷启动保护：该 action 统计不足时放大 bias，退回启发式主导
+        if action in self._stats and self._stats[action].count < 5:
+            bias *= 5
+
+        return bias
+
+    def set_policy_thresholds(self, thresholds: Dict[str, Any]):
+        """设置 Policy 阈值约束"""
+        self._policy_thresholds = thresholds
+        logger.info("[ActionBandit] Policy 阈值已设置: %s", list(thresholds.keys()))
+
+    def update(self, action: str, reward: float):
+        if action not in self._stats:
+            logger.warning("[ActionBandit] 未知 action: %s", action)
+            return
+
+        self._reward_buffer.append(reward)
+        self._last_actions.append(action)
+
+        n_step_reward = self._compute_n_step_return()
+
+        stats = self._stats[action]
+        stats.count += 1
+
+        if n_step_reward > 0.5:
+            stats.alpha += n_step_reward
+        else:
+            stats.beta += (1 - n_step_reward)
+
+        logger.debug(
+            "[ActionBandit] 更新 %s | reward=%.2f | n_step=%.2f | alpha=%.1f beta=%.1f",
+            action, reward, n_step_reward, stats.alpha, stats.beta
+        )
+
+        if self.memory_path:
+            self._save()
+
+    def _compute_n_step_return(self) -> float:
+        """
+        计算 n-step return
+        G_t = (r_t + r_{t+1} + ... + r_{t+n-1}) / n
+
+        """
+        if not self._reward_buffer:
+            return 0.5  # 默认中性
+
+        return sum(self._reward_buffer) / len(self._reward_buffer)
+
+    def end_session(self):
+        self._session_count += 1
+
+        if self._session_count >= self._decay_interval:
+            self._decay()
+            self._session_count = 0
+
+        self._reward_buffer.clear()
+        self._last_actions.clear()
+
+    def _decay(self):
+        for action, stats in self._stats.items():
+            stats.alpha = 1 + (stats.alpha - 1) * self._decay_factor
+            stats.beta = 1 + (stats.beta - 1) * self._decay_factor
+
+        logger.info("[ActionBandit] 统计已衰减 (factor=%.2f)", self._decay_factor)
+
+    def get_stats(self) -> Dict[str, Dict]:
+        return {
+            action: stats.to_dict()
+            for action, stats in self._stats.items()
+        }
+
+    def get_summary(self) -> Dict[str, Any]:
+        summary = {
+            "total_actions": sum(s.count for s in self._stats.values()),
+            "actions": {},
+        }
+
+        for action, stats in self._stats.items():
+            mean = stats.alpha / (stats.alpha + stats.beta) if (stats.alpha + stats.beta) > 0 else 0.5
+            summary["actions"][action] = {
+                "count": stats.count,
+                "success_rate": mean,
+            }
+
+        return summary
+
+    def _load(self):
+        if not self.memory_path or not os.path.exists(self.memory_path):
+            return
+
+        try:
+            with open(self.memory_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+
+            for action, stats_data in data.get("actions", {}).items():
+                if action in self._stats:
+                    self._stats[action] = ActionStats.from_dict(stats_data)
+
+            logger.info("[ActionBandit] 加载统计数据: %s", self.memory_path)
+
+        except Exception as e:
+            logger.warning("[ActionBandit] 加载失败: %s", e)
+
+    def _save(self):
+        if not self.memory_path:
+            return
+
+        try:
+            Path(self.memory_path).parent.mkdir(parents=True, exist_ok=True)
+
+            data = {
+                "actions": self.get_stats(),
+                "session_count": self._session_count,
+            }
+
+            with open(self.memory_path, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2, ensure_ascii=False)
+
+        except Exception as e:
+            logger.warning("[ActionBandit] 保存失败: %s", e)
+
+    def reset(self):
+        for action in self._stats:
+            self._stats[action] = ActionStats()
+        self._session_count = 0
+        self._reward_buffer.clear()
+        self._last_actions.clear()
+
+        if self.memory_path:
+            self._save()
+
+        logger.info("[ActionBandit] 统计已重置")

app/agent/control/constraint_gene/__init__.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+"""
+Constraint Gene - 控制约束 Gene 子模块
+
+包含：
+  - TaskSignalMatcher: 任务信号匹配器
+  - GeneEvolution: Gene 进化系统
+  - GeneComposer: Gene 组合器
+"""
+
+from .matcher import TaskSignalMatcher
+from .evolution import GeneEvolution
+from .composer import GeneComposer
+
+__all__ = ["TaskSignalMatcher", "GeneEvolution", "GeneComposer"]

app/agent/control/constraint_gene/composer.py

@@ -0,0 +1,158 @@
+# -*- coding: utf-8 -*-
+"""
+GeneComposer - Gene 组合器
+
+职责：
+  1. 多任务匹配
+  2. Gene 组合与合并
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .matcher import TaskSignalMatcher
+
+logger = logging.getLogger(__name__)
+
+
+class GeneComposer:
+    """Gene 组合器 - 处理多任务匹配和组合"""
+
+    TASK_PRIORITY = {
+        "code_debug": 100,
+        "file_operation": 90,
+        "web_search": 80,
+    }
+
+    @classmethod
+    def match_multiple(cls, user_input: str) -> List[Dict[str, Any]]:
+        if not user_input:
+            return []
+
+        user_lower = user_input.lower()
+        matches = []
+
+        for task_type, config in TaskSignalMatcher._cache.items():
+            signals = config.get("signals", [])
+            if any(signal in user_lower for signal in signals):
+                matches.append({
+                    "task_type": task_type,
+                    "gene_template": config["gene_template"],
+                    "forbidden_tools": config["forbidden_tools"],
+                    "preferred_tools": config["preferred_tools"],
+                    "priority": cls.TASK_PRIORITY.get(task_type, 50),
+                })
+
+        for task_type, config in TaskSignalMatcher.TASK_PATTERNS.items():
+            if any(signal in user_lower for signal in config["signals"]):
+                if not any(m["task_type"] == task_type for m in matches):
+                    matches.append({
+                        "task_type": task_type,
+                        "gene_template": config["gene_template"],
+                        "forbidden_tools": config["forbidden_tools"],
+                        "preferred_tools": config["preferred_tools"],
+                        "priority": cls.TASK_PRIORITY.get(task_type, 50),
+                    })
+
+        matches.sort(key=lambda x: x["priority"], reverse=True)
+        return matches
+
+    @classmethod
+    def compose(cls, matches: List[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+        if not matches:
+            return None
+
+        if len(matches) == 1:
+            return matches[0]
+
+        task_types = [m["task_type"] for m in matches]
+        combined_forbidden = list(set(
+            tool for m in matches for tool in m["forbidden_tools"]
+        ))
+        combined_preferred = list(set(
+            tool for m in matches for tool in m["preferred_tools"]
+        ))
+
+        hard_constraints = cls._build_combined_constraints(matches)
+
+        return {
+            "task_type": f"combined:{','.join(task_types)}",
+            "gene_template": hard_constraints,
+            "forbidden_tools": combined_forbidden,
+            "preferred_tools": combined_preferred,
+            "component_tasks": task_types,
+        }
+
+    @classmethod
+    def _build_combined_constraints(cls, matches: List[Dict[str, Any]]) -> str:
+        task_types = [m["task_type"] for m in matches]
+
+        lines = [
+            "[HARD CONSTRAINTS]",
+            f"Multi-task: {' + '.join(task_types)}",
+            "",
+            "[CONTROL ACTION]",
+        ]
+
+        for i, match in enumerate(matches, 1):
+            task_type = match["task_type"]
+            template = match["gene_template"]
+
+            must_section = cls._extract_section(template, "MUST:")
+            must_not_section = cls._extract_section(template, "MUST NOT:")
+
+            lines.append(f"STEP {i} [{task_type}]:")
+            if must_section:
+                lines.append(f"  MUST: {must_section}")
+            if must_not_section:
+                lines.append(f"  MUST NOT: {must_not_section}")
+            lines.append("")
+
+        avoid_items = set()
+        for match in matches:
+            template = match["gene_template"]
+            items = cls._extract_avoid_items(template)
+            avoid_items.update(items)
+
+        if avoid_items:
+            lines.append("[AVOID]")
+            for item in sorted(avoid_items):
+                lines.append(f"- {item}")
+
+        return "\n".join(lines)
+
+    @classmethod
+    def _extract_section(cls, template: str, marker: str) -> str:
+        lines = template.split("\n")
+        result = []
+        capturing = False
+
+        for line in lines:
+            if marker in line:
+                capturing = True
+                result.append(line.split(marker, 1)[-1].strip())
+            elif capturing:
+                if line.strip().startswith("MUST") or line.strip().startswith("["):
+                    break
+                if line.strip():
+                    result.append(line.strip())
+
+        return " ".join(result) if result else ""
+
+    @classmethod
+    def _extract_avoid_items(cls, template: str) -> List[str]:
+        lines = template.split("\n")
+        items = []
+        in_avoid = False
+
+        for line in lines:
+            if "[AVOID]" in line:
+                in_avoid = True
+                continue
+            if in_avoid:
+                if line.strip().startswith("["):
+                    break
+                if line.strip().startswith("-"):
+                    items.append(line.strip()[1:].strip())
+
+        return items