langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/task_runtime/store/in_memory.py

@@ -0,0 +1,81 @@
+"""
+task_runtime/store/in_memory.py — TaskStore 内存实现
+
+职责：
+    基于 dict 的任务记录存储；采用 RLock 保证基础并发安全。
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from threading import RLock
+from typing import Iterable, Optional
+
+from ..core.interfaces import TaskStore
+from ..core.types import TaskRecord, TaskStatus
+
+
+class InMemoryTaskStore(TaskStore):
+    def __init__(self) -> None:
+        self._lock = RLock()
+        self._records: dict[str, TaskRecord] = {}
+
+    def create(self, record: TaskRecord) -> None:
+        with self._lock:
+            self._records[record.task_id] = record
+
+    def get(self, task_id: str) -> Optional[TaskRecord]:
+        with self._lock:
+            return self._records.get(task_id)
+
+    def update(self, task_id: str, patch: dict) -> Optional[TaskRecord]:
+        with self._lock:
+            current = self._records.get(task_id)
+            if current is None:
+                return None
+            updated = replace(current, **patch)
+            self._records[task_id] = updated
+            return updated
+
+    def list(self) -> Iterable[TaskRecord]:
+        with self._lock:
+            return list(self._records.values())
+
+    def delete(self, task_id: str) -> None:
+        with self._lock:
+            self._records.pop(task_id, None)
+
+    def evict_expired(self, *, now_ts: float, ttl_sec: float) -> int:
+        if ttl_sec <= 0:
+            return 0
+        terminal = {TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.STOPPED}
+        with self._lock:
+            to_delete = [
+                task_id
+                for task_id, record in self._records.items()
+                if record.status in terminal and (now_ts - float(record.updated_at)) >= ttl_sec
+            ]
+            for task_id in to_delete:
+                self._records.pop(task_id, None)
+            return len(to_delete)
+
+    def evict_over_capacity(self, *, max_records: int) -> int:
+        if max_records < 0:
+            return 0
+        terminal = {TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.STOPPED}
+        with self._lock:
+            total = len(self._records)
+            overflow = total - max_records
+            if overflow <= 0:
+                return 0
+
+            terminal_items = [
+                (task_id, record)
+                for task_id, record in self._records.items()
+                if record.status in terminal
+            ]
+            terminal_items.sort(key=lambda item: float(item[1].updated_at))
+            to_delete = [task_id for task_id, _ in terminal_items[:overflow]]
+            for task_id in to_delete:
+                self._records.pop(task_id, None)
+            return len(to_delete)

langchain_agentx/task_runtime/store/sqlite_store.py

@@ -0,0 +1,281 @@
+"""
+task_runtime/store/sqlite_store.py — Task Runtime SQLite 持久化存储
+
+职责：
+    提供 TaskStore 的最小持久化实现：
+    1. create/get/update/list/delete 的持久化读写
+    2. 任务终态去重字段与元数据的序列化
+
+边界：
+    - 仅实现 TaskStore，不处理队列与 loop 注入
+    - 采用 sqlite3 标准库，便于本地与 CI 使用
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+import json
+import sqlite3
+from threading import RLock
+from typing import Iterable, Optional
+
+from ..core.interfaces import TaskStore
+from ..core.types import TaskRecord, TaskScope, TaskStatus, TaskType
+
+
+class SqliteTaskStore(TaskStore):
+    def __init__(self, db_path: str) -> None:
+        self._lock = RLock()
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._init_schema()
+
+    def _init_schema(self) -> None:
+        with self._conn:
+            self._conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS task_records (
+                    task_id TEXT PRIMARY KEY,
+                    task_type TEXT NOT NULL,
+                    status TEXT NOT NULL,
+                    description TEXT NOT NULL,
+                    scope_agent_id TEXT,
+                    input_json TEXT NOT NULL,
+                    metadata_json TEXT NOT NULL,
+                    created_at REAL NOT NULL,
+                    updated_at REAL NOT NULL,
+                    output_file TEXT,
+                    terminal_emitted_statuses_json TEXT NOT NULL,
+                    notification_consumed INTEGER NOT NULL,
+                    run_id TEXT,
+                    external_ref TEXT,
+                    lease_until_ts REAL,
+                    last_heartbeat_ts REAL,
+                    worker_id TEXT
+                )
+                """
+            )
+            self._migrate_task_columns()
+
+    def _migrate_task_columns(self) -> None:
+        cur = self._conn.execute("PRAGMA table_info(task_records)")
+        cols = {row[1] for row in cur.fetchall()}
+        alters = [
+            ("run_id", "TEXT"),
+            ("external_ref", "TEXT"),
+            ("lease_until_ts", "REAL"),
+            ("last_heartbeat_ts", "REAL"),
+            ("worker_id", "TEXT"),
+        ]
+        for name, sql_type in alters:
+            if name not in cols:
+                self._conn.execute(
+                    f"ALTER TABLE task_records ADD COLUMN {name} {sql_type}"
+                )
+
+    def create(self, record: TaskRecord) -> None:
+        payload = _to_row(record)
+        with self._lock, self._conn:
+            self._conn.execute(
+                """
+                INSERT OR REPLACE INTO task_records (
+                    task_id, task_type, status, description, scope_agent_id,
+                    input_json, metadata_json, created_at, updated_at, output_file,
+                    terminal_emitted_statuses_json, notification_consumed,
+                    run_id, external_ref, lease_until_ts, last_heartbeat_ts, worker_id
+                ) VALUES (
+                    :task_id, :task_type, :status, :description, :scope_agent_id,
+                    :input_json, :metadata_json, :created_at, :updated_at, :output_file,
+                    :terminal_emitted_statuses_json, :notification_consumed,
+                    :run_id, :external_ref, :lease_until_ts, :last_heartbeat_ts, :worker_id
+                )
+                """,
+                payload,
+            )
+
+    def get(self, task_id: str) -> Optional[TaskRecord]:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT * FROM task_records WHERE task_id = ?",
+                (task_id,),
+            ).fetchone()
+        if row is None:
+            return None
+        return _from_row(row)
+
+    def update(self, task_id: str, patch: dict) -> Optional[TaskRecord]:
+        with self._lock:
+            current = self.get(task_id)
+            if current is None:
+                return None
+            data = asdict(current)
+            data.update(patch)
+            # dataclass->dict 后 enums 仍是对象，这里统一规范为 TaskRecord
+            updated = TaskRecord(
+                task_id=data["task_id"],
+                task_type=_coerce_task_type(data["task_type"]),
+                status=_coerce_task_status(data["status"]),
+                description=data["description"],
+                scope=data["scope"] if isinstance(data["scope"], TaskScope) else TaskScope(
+                    agent_id=data["scope"].get("agent_id") if isinstance(data["scope"], dict) else None
+                ),
+                input=data.get("input") or {},
+                metadata=data.get("metadata") or {},
+                created_at=float(data["created_at"]),
+                updated_at=float(data["updated_at"]),
+                output_file=data.get("output_file"),
+                terminal_emitted_statuses=set(
+                    _coerce_task_status(s) for s in (data.get("terminal_emitted_statuses") or set())
+                ),
+                notification_consumed=bool(data.get("notification_consumed", False)),
+                run_id=data.get("run_id"),
+                external_ref=data.get("external_ref"),
+                lease_until_ts=(
+                    float(data["lease_until_ts"])
+                    if data.get("lease_until_ts") is not None
+                    else None
+                ),
+                last_heartbeat_ts=(
+                    float(data["last_heartbeat_ts"])
+                    if data.get("last_heartbeat_ts") is not None
+                    else None
+                ),
+                worker_id=data.get("worker_id"),
+            )
+            self.create(updated)
+            return updated
+
+    def list(self) -> Iterable[TaskRecord]:
+        with self._lock:
+            rows = self._conn.execute("SELECT * FROM task_records").fetchall()
+        return [_from_row(row) for row in rows]
+
+    def delete(self, task_id: str) -> None:
+        with self._lock, self._conn:
+            self._conn.execute("DELETE FROM task_records WHERE task_id = ?", (task_id,))
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+    def evict_expired(self, *, now_ts: float, ttl_sec: float) -> int:
+        if ttl_sec <= 0:
+            return 0
+        cutoff = float(now_ts) - float(ttl_sec)
+        terminal_statuses = (
+            TaskStatus.COMPLETED.value,
+            TaskStatus.FAILED.value,
+            TaskStatus.STOPPED.value,
+        )
+        with self._lock, self._conn:
+            cur = self._conn.execute(
+                """
+                DELETE FROM task_records
+                WHERE status IN (?, ?, ?) AND updated_at <= ?
+                """,
+                (*terminal_statuses, cutoff),
+            )
+            return int(cur.rowcount or 0)
+
+    def evict_over_capacity(self, *, max_records: int) -> int:
+        if max_records < 0:
+            return 0
+        terminal_statuses = (
+            TaskStatus.COMPLETED.value,
+            TaskStatus.FAILED.value,
+            TaskStatus.STOPPED.value,
+        )
+        with self._lock, self._conn:
+            total = int(
+                self._conn.execute("SELECT COUNT(*) FROM task_records").fetchone()[0]
+            )
+            overflow = total - max_records
+            if overflow <= 0:
+                return 0
+            rows = self._conn.execute(
+                """
+                SELECT task_id
+                FROM task_records
+                WHERE status IN (?, ?, ?)
+                ORDER BY updated_at ASC
+                LIMIT ?
+                """,
+                (*terminal_statuses, overflow),
+            ).fetchall()
+            ids = [row["task_id"] for row in rows]
+            if not ids:
+                return 0
+            placeholders = ",".join("?" for _ in ids)
+            cur = self._conn.execute(
+                f"DELETE FROM task_records WHERE task_id IN ({placeholders})",
+                ids,
+            )
+            return int(cur.rowcount or 0)
+
+
+def _to_row(record: TaskRecord) -> dict:
+    return {
+        "task_id": record.task_id,
+        "task_type": record.task_type.value,
+        "status": record.status.value,
+        "description": record.description,
+        "scope_agent_id": record.scope.agent_id,
+        "input_json": json.dumps(record.input, ensure_ascii=True),
+        "metadata_json": json.dumps(record.metadata, ensure_ascii=True),
+        "created_at": float(record.created_at),
+        "updated_at": float(record.updated_at),
+        "output_file": record.output_file,
+        "terminal_emitted_statuses_json": json.dumps(
+            [s.value for s in record.terminal_emitted_statuses], ensure_ascii=True
+        ),
+        "notification_consumed": 1 if record.notification_consumed else 0,
+        "run_id": record.run_id,
+        "external_ref": record.external_ref,
+        "lease_until_ts": record.lease_until_ts,
+        "last_heartbeat_ts": record.last_heartbeat_ts,
+        "worker_id": record.worker_id,
+    }
+
+
+def _from_row(row: sqlite3.Row) -> TaskRecord:
+    emitted_raw = json.loads(row["terminal_emitted_statuses_json"] or "[]")
+    keys = row.keys()
+    return TaskRecord(
+        task_id=row["task_id"],
+        task_type=TaskType(row["task_type"]),
+        status=TaskStatus(row["status"]),
+        description=row["description"],
+        scope=TaskScope(agent_id=row["scope_agent_id"]),
+        input=json.loads(row["input_json"] or "{}"),
+        metadata=json.loads(row["metadata_json"] or "{}"),
+        created_at=float(row["created_at"]),
+        updated_at=float(row["updated_at"]),
+        output_file=row["output_file"],
+        terminal_emitted_statuses=set(TaskStatus(s) for s in emitted_raw),
+        notification_consumed=bool(row["notification_consumed"]),
+        run_id=row["run_id"] if "run_id" in keys else None,
+        external_ref=row["external_ref"] if "external_ref" in keys else None,
+        lease_until_ts=(
+            float(row["lease_until_ts"])
+            if "lease_until_ts" in keys and row["lease_until_ts"] is not None
+            else None
+        ),
+        last_heartbeat_ts=(
+            float(row["last_heartbeat_ts"])
+            if "last_heartbeat_ts" in keys and row["last_heartbeat_ts"] is not None
+            else None
+        ),
+        worker_id=row["worker_id"] if "worker_id" in keys else None,
+    )
+
+
+def _coerce_task_type(value) -> TaskType:
+    if isinstance(value, TaskType):
+        return value
+    return TaskType(str(value))
+
+
+def _coerce_task_status(value) -> TaskStatus:
+    if isinstance(value, TaskStatus):
+        return value
+    return TaskStatus(str(value))

langchain_agentx/task_runtime/tasks/__init__.py

@@ -0,0 +1,76 @@
+"""
+task_runtime/tasks/__init__.py — 按 TaskType 分组的语义与执行器导出
+
+职责：
+    为上层提供 ``TaskExecutor`` 实现与契约类型，隐藏子包细节。
+
+与 CC 对比：
+    CC ``src/tasks/*.ts`` 按文件组织；本仓库按 ``TaskType`` 枚举分目录，
+    每目录内 OOP：``spec`` / ``executor`` / ``notification`` / ``semantics``。
+"""
+
+from .custom import CUSTOM_SEMANTIC, CustomTaskExecutor, CustomTaskInput
+from .dream_task import (
+    DREAM_TASK_SEMANTIC,
+    DreamTaskExecutor,
+    DreamTaskInput,
+    DreamTaskNotificationFormatter,
+    DreamTaskState,
+)
+from .in_process_teammate import (
+    IN_PROCESS_TEAMMATE_SEMANTIC,
+    InProcessTeammateExecutor,
+    InProcessTeammateTaskInput,
+    TeammateIdentity,
+)
+from .local_agent import (
+    LOCAL_AGENT_SEMANTIC,
+    DefaultLocalAgentRunner,
+    LocalAgentExecutor,
+    LocalAgentRunner,
+    LocalAgentTaskInput,
+)
+from .local_bash import (
+    LOCAL_BASH_SEMANTIC,
+    LocalBashExecutor,
+    LocalBashNotificationFormatter,
+    LocalBashTaskInput,
+)
+from .remote_agent import (
+    REMOTE_AGENT_SEMANTIC,
+    ImmediateRemoteAgentBackend,
+    RecordingRemoteAgentBackend,
+    RemoteAgentExecutor,
+    RemoteAgentSessionBackend,
+    RemoteAgentTaskInput,
+)
+
+__all__ = [
+    "LOCAL_BASH_SEMANTIC",
+    "LocalBashExecutor",
+    "LocalBashNotificationFormatter",
+    "LocalBashTaskInput",
+    "LOCAL_AGENT_SEMANTIC",
+    "DefaultLocalAgentRunner",
+    "LocalAgentExecutor",
+    "LocalAgentRunner",
+    "LocalAgentTaskInput",
+    "IN_PROCESS_TEAMMATE_SEMANTIC",
+    "InProcessTeammateExecutor",
+    "InProcessTeammateTaskInput",
+    "TeammateIdentity",
+    "REMOTE_AGENT_SEMANTIC",
+    "ImmediateRemoteAgentBackend",
+    "RecordingRemoteAgentBackend",
+    "RemoteAgentExecutor",
+    "RemoteAgentSessionBackend",
+    "RemoteAgentTaskInput",
+    "CUSTOM_SEMANTIC",
+    "CustomTaskExecutor",
+    "CustomTaskInput",
+    "DREAM_TASK_SEMANTIC",
+    "DreamTaskExecutor",
+    "DreamTaskInput",
+    "DreamTaskNotificationFormatter",
+    "DreamTaskState",
+]

langchain_agentx/task_runtime/tasks/ai_analysis/__init__.py

@@ -0,0 +1,15 @@
+"""后台 AI 分析任务导出。"""
+
+from .base import BackgroundAiTask
+from .evaluation import EvaluationAnalysisTask
+from .registry import BackgroundAiTaskRegistry, registry
+
+# OB-D10：侧载 trace.cleanup 注册（executor 模块尾 registry.register）
+from ..trace_cleanup import executor as _trace_cleanup_executor  # noqa: F401
+
+__all__ = [
+    "BackgroundAiTask",
+    "BackgroundAiTaskRegistry",
+    "registry",
+    "EvaluationAnalysisTask",
+]

langchain_agentx/task_runtime/tasks/ai_analysis/base.py

@@ -0,0 +1,41 @@
+"""
+task_runtime/tasks/ai_analysis/base.py — 后台 AI 分析任务基类。
+
+职责：
+    继承 BaseWorkflow，覆盖 container_type 为 background_task，
+    run() 增加静默降级，避免影响主流程。
+
+链路位置：
+    由后台任务调度器通过队列轮询触发。
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import abstractmethod
+from typing import Any
+
+from ....workflow.base import BaseWorkflow
+
+logger = logging.getLogger(__name__)
+
+
+class BackgroundAiTask(BaseWorkflow):
+    """后台 AI 分析任务基类。失败必须静默降级。"""
+
+    container_type: str = "background_task"
+
+    async def run(self, **kwargs: Any) -> Any:
+        """覆盖 BaseWorkflow.run()，增加静默降级。"""
+        try:
+            return await super().run(**kwargs)
+        except Exception:
+            logger.exception("%s 执行失败，静默降级", self.__class__.__name__)
+            return None
+
+    @abstractmethod
+    async def _execute(self, **kwargs: Any) -> Any:
+        """子类实现具体分析逻辑，结果写回外部存储。"""
+
+
+__all__ = ["BackgroundAiTask"]

langchain_agentx/task_runtime/tasks/ai_analysis/evaluation.py

@@ -0,0 +1,67 @@
+"""
+task_runtime/tasks/ai_analysis/evaluation.py — EvaluationAnalysisTask 内置实现。
+
+职责：
+    对 EvaluationStore 中 check_failed 的 session 进行深度 AI 分析，
+    并将结果写回 EvaluationStore.diagnostic_reports。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.messages import HumanMessage
+
+from ....observability.evaluation.store import DiagnosticReport, EvaluationStore
+from .base import BackgroundAiTask
+from .registry import registry
+
+
+class EvaluationAnalysisTask(BackgroundAiTask):
+    """对 check_failed session 进行深度 AI 分析。"""
+
+    def __init__(self, evaluation_store: EvaluationStore, **workflow_kwargs: Any) -> None:
+        super().__init__(**workflow_kwargs)
+        self._evaluation_store = evaluation_store
+
+    async def _execute(self, session_id: str, **_: Any) -> None:
+        failures = self._evaluation_store.get_results(session_id)
+        fail_results = [result for result in failures if result.status == "fail"]
+        if not fail_results:
+            return
+
+        evidence_summary = "\n".join(
+            f"- [{result.checker_name}] {result.message}  evidence={result.evidence}"
+            for result in fail_results
+        )
+        prompt = (
+            f"以下是 session {session_id} 的评估失败记录：\n"
+            f"{evidence_summary}\n\n"
+            "请分析根因，指出是哪个模块、哪个逻辑路径导致了这些问题。\n"
+            "输出格式：根因 / 涉及模块 / 建议排查点"
+        )
+
+        result = await self._invoke_agent(
+            messages=[HumanMessage(content=prompt)],
+            task_key=session_id,
+        )
+
+        report_text = ""
+        if isinstance(result, dict):
+            messages = result.get("messages", [])
+            if messages:
+                report_text = str(getattr(messages[-1], "content", "") or "")
+
+        self._evaluation_store.save_diagnostic_report(
+            DiagnosticReport(
+                session_id=session_id,
+                checker_names=[result.checker_name for result in fail_results],
+                report=report_text,
+                model="agent",
+            )
+        )
+
+
+registry.register("evaluation.check_failed", EvaluationAnalysisTask)
+
+__all__ = ["EvaluationAnalysisTask"]

langchain_agentx/task_runtime/tasks/ai_analysis/registry.py

@@ -0,0 +1,36 @@
+"""
+task_runtime/tasks/ai_analysis/registry.py — 后台 AI 任务注册表。
+
+职责：
+    维护 trigger -> task_factory 映射，支持内置注册与外部覆盖。
+
+链路位置：
+    调度器通过 registry.get(trigger) 获取任务工厂。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+class BackgroundAiTaskRegistry:
+    """trigger -> task_factory 注册表。"""
+
+    def __init__(self) -> None:
+        self._registry: dict[str, Callable[..., Any]] = {}
+
+    def register(self, trigger: str, task_factory: Callable[..., Any]) -> None:
+        """注册或覆盖触发条件对应的任务工厂。"""
+        self._registry[trigger] = task_factory
+
+    def get(self, trigger: str) -> Callable[..., Any] | None:
+        """按触发条件获取任务工厂，未注册返回 None。"""
+        return self._registry.get(trigger)
+
+    def list_triggers(self) -> list[str]:
+        return list(self._registry.keys())
+
+
+registry = BackgroundAiTaskRegistry()
+
+__all__ = ["BackgroundAiTaskRegistry", "registry"]

langchain_agentx/task_runtime/tasks/ai_analysis/scheduler.py

@@ -0,0 +1,70 @@
+"""
+task_runtime/tasks/ai_analysis/scheduler.py — BackgroundAiTaskScheduler。
+
+职责：
+    定时轮询 EvaluationStore，找出有 fail 且无诊断报告的 session，
+    并通过 registry 获取任务工厂异步触发分析任务。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from ....observability.evaluation.store import EvaluationStore
+from .registry import BackgroundAiTaskRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class BackgroundAiTaskScheduler:
+    """定时轮询 EvaluationStore，触发后台 AI 分析任务。"""
+
+    def __init__(
+        self,
+        evaluation_store: EvaluationStore,
+        registry: BackgroundAiTaskRegistry,
+        task_factory_kwargs: dict[str, Any] | None = None,
+        poll_interval: float = 60.0,
+    ) -> None:
+        self._store = evaluation_store
+        self._registry = registry
+        self._task_factory_kwargs = task_factory_kwargs or {}
+        self._poll_interval = poll_interval
+        self._running = False
+
+    async def start(self) -> None:
+        """启动轮询循环，直到 stop() 被调用。"""
+        self._running = True
+        logger.info("BackgroundAiTaskScheduler 启动，轮询间隔 %ss", self._poll_interval)
+        while self._running:
+            await self._poll_once()
+            await asyncio.sleep(self._poll_interval)
+
+    def stop(self) -> None:
+        self._running = False
+
+    async def _poll_once(self) -> None:
+        try:
+            session_ids = self._store.get_sessions_needing_analysis()
+        except Exception:
+            logger.exception("Scheduler 轮询 EvaluationStore 失败")
+            return
+
+        for session_id in session_ids:
+            task_factory = self._registry.get("evaluation.check_failed")
+            if task_factory is None:
+                continue
+            try:
+                task = task_factory(
+                    evaluation_store=self._store,
+                    **self._task_factory_kwargs,
+                )
+                asyncio.create_task(task.run(session_id=session_id))
+                logger.debug("Scheduler 已触发 session %s 的分析任务", session_id)
+            except Exception:
+                logger.exception("Scheduler 触发 session %s 分析任务失败", session_id)
+
+
+__all__ = ["BackgroundAiTaskScheduler"]

langchain_agentx/task_runtime/tasks/base/__init__.py

@@ -0,0 +1,6 @@
+"""Base semantic contracts for task types."""
+
+from .contracts import TaskSemanticContract
+
+__all__ = ["TaskSemanticContract"]
+