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

langchain_agentx/task_runtime/integrations/provider_factory.py

@@ -0,0 +1,103 @@
+"""
+task_runtime/integrations/provider_factory.py — queued provider 统一配置入口
+
+职责：
+    为 task 侧提供一个统一的 provider 装配工厂，减少调用方手工拼装成本。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+from .prefetch_providers import MemoryPrefetchProvider
+from ..skill_prefetch import SkillPrefetchProvider
+from .queued_command_provider import InMemoryQueuedCommandProvider
+from .sqlite_queued_command_provider import SqliteQueuedCommandProvider
+from .tool_use_summary_provider import ToolUseSummaryProvider
+
+
+BackendType = Literal["in_memory", "sqlite"]
+
+
+@dataclass(frozen=True)
+class ProviderFactoryConfig:
+    backend_type: BackendType = "in_memory"
+    sqlite_db_path: str | None = None
+    workspace_root: str | None = None
+    agent_home: str = ".langchain_agentx"
+    max_queue_size: int | None = None
+    ttl_sec: float | None = None
+    enable_memory_prefetch: bool = True
+    enable_skill_prefetch: bool = True
+    enable_tool_summary: bool = True
+    summary_error_ratio_now_threshold: float = 0.5
+    summary_avg_latency_now_threshold_ms: int = 2000
+
+
+@dataclass(frozen=True)
+class ProviderBundle:
+    memory_prefetch: MemoryPrefetchProvider | None
+    skill_prefetch: SkillPrefetchProvider | None
+    tool_summary: ToolUseSummaryProvider | None
+
+    def as_list(self) -> list:
+        return [item for item in [self.memory_prefetch, self.skill_prefetch, self.tool_summary] if item is not None]
+
+
+def build_provider_bundle(config: ProviderFactoryConfig) -> ProviderBundle:
+    workspace_cfg = resolve_agent_workspace_config(
+        workspace_root=config.workspace_root or Path.cwd(),
+        agent_home=config.agent_home,
+    )
+    backend = _build_backend(config)
+    memory_prefetch = (
+        MemoryPrefetchProvider(backend=backend)
+        if config.enable_memory_prefetch
+        else None
+    )
+    skill_prefetch = (
+        SkillPrefetchProvider(
+            workspace_root=workspace_cfg.workspace_root,
+            agent_home=workspace_cfg.agent_home,
+        )
+        if config.enable_skill_prefetch
+        else None
+    )
+    tool_summary = (
+        ToolUseSummaryProvider(
+            backend=backend,
+            error_ratio_now_threshold=config.summary_error_ratio_now_threshold,
+            avg_latency_now_threshold_ms=config.summary_avg_latency_now_threshold_ms,
+        )
+        if config.enable_tool_summary
+        else None
+    )
+    return ProviderBundle(
+        memory_prefetch=memory_prefetch,
+        skill_prefetch=skill_prefetch,
+        tool_summary=tool_summary,
+    )
+
+
+def _build_backend(config: ProviderFactoryConfig):
+    if config.backend_type == "sqlite":
+        workspace_cfg = resolve_agent_workspace_config(
+            workspace_root=config.workspace_root or Path.cwd(),
+            agent_home=config.agent_home,
+        )
+        db_path = config.sqlite_db_path or str(workspace_cfg.task_runtime_db_path)
+        Path(db_path).expanduser().resolve().parent.mkdir(parents=True, exist_ok=True)
+        return SqliteQueuedCommandProvider(
+            db_path,
+            max_queue_size=config.max_queue_size,
+            ttl_sec=config.ttl_sec,
+            recover_reserved_on_startup=True,
+        )
+    return InMemoryQueuedCommandProvider(
+        max_queue_size=config.max_queue_size,
+        ttl_sec=config.ttl_sec,
+    )
+

langchain_agentx/task_runtime/integrations/queued_command_provider.py

@@ -0,0 +1,184 @@
+"""
+task_runtime/integrations/queued_command_provider.py — 通用 queued-command provider
+
+职责：
+    为 memory/skill prefetch 等“非 task_runtime 来源”提供统一的队列能力：
+    1. enqueue：写入待注入命令
+    2. build_batch：按 scope/priority reserve 批次
+    3. ack_batch / nack_batch：两阶段确认
+    4. has_pending：供 loop_controller 退出守卫探测
+
+边界：
+    - 仅负责 queued-command 的队列与批次确认
+    - 不依赖 TaskRuntime，不参与任务生命周期状态机
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from dataclasses import dataclass, field
+from threading import RLock
+from uuid import uuid4
+import time
+
+from ..core.types import QueuePriority, TaskScope
+from .loop_adapter import LoopInjectionBatch
+
+
+_PRIORITY_ORDER = {
+    QueuePriority.NOW: 0,
+    QueuePriority.NEXT: 1,
+    QueuePriority.LATER: 2,
+}
+
+
+@dataclass(frozen=True)
+class QueuedCommandEnvelope:
+    command_id: str
+    source: str
+    summary: str
+    scope: TaskScope
+    priority: QueuePriority = QueuePriority.NEXT
+    payload: dict = field(default_factory=dict)
+    dedup_key: str | None = None
+    created_at: float = field(default_factory=time.time)
+
+
+class InMemoryQueuedCommandProvider:
+    """最小可用 queued-command provider（内存版）。"""
+
+    def __init__(
+        self,
+        *,
+        max_queue_size: int | None = None,
+        ttl_sec: float | None = None,
+    ) -> None:
+        self._lock = RLock()
+        self._queue: list[QueuedCommandEnvelope] = []
+        self._reserved_batches: dict[str, list[QueuedCommandEnvelope]] = {}
+        self._max_queue_size = max_queue_size
+        self._ttl_sec = ttl_sec
+
+    def enqueue(self, env: QueuedCommandEnvelope) -> None:
+        with self._lock:
+            self._evict_expired_locked(now_ts=time.time())
+            # 可选去重：同 scope + dedup_key 仅保留最新一条
+            if env.dedup_key:
+                self._queue = [
+                    item
+                    for item in self._queue
+                    if not (
+                        item.scope.agent_id == env.scope.agent_id
+                        and item.dedup_key == env.dedup_key
+                    )
+                ]
+            self._queue.append(env)
+            self._evict_over_capacity_locked()
+
+    def build_batch(
+        self,
+        scope: TaskScope,
+        max_priority: QueuePriority = QueuePriority.NEXT,
+        *,
+        limit: int = 8,
+    ) -> LoopInjectionBatch:
+        if limit <= 0:
+            return LoopInjectionBatch(batch_id="", command_ids=[], attachment_messages=[])
+        threshold = _PRIORITY_ORDER[max_priority]
+        with self._lock:
+            self._evict_expired_locked(now_ts=time.time())
+            candidates = [
+                item
+                for item in self._queue
+                if item.scope.agent_id == scope.agent_id
+                and _PRIORITY_ORDER[item.priority] <= threshold
+            ]
+            candidates.sort(key=lambda item: _PRIORITY_ORDER[item.priority])
+            selected = candidates[:limit]
+            if not selected:
+                return LoopInjectionBatch(batch_id="", command_ids=[], attachment_messages=[])
+
+            selected_ids = {item.command_id for item in selected}
+            self._queue = [item for item in self._queue if item.command_id not in selected_ids]
+            batch_id = f"qbatch_{uuid4().hex[:10]}"
+            self._reserved_batches[batch_id] = selected
+            return LoopInjectionBatch(
+                batch_id=batch_id,
+                command_ids=[item.command_id for item in selected],
+                attachment_messages=[_to_attachment_message(item) for item in selected],
+            )
+
+    def ack_batch(self, batch: LoopInjectionBatch) -> None:
+        if not batch.batch_id:
+            return
+        with self._lock:
+            self._reserved_batches.pop(batch.batch_id, None)
+
+    def nack_batch(self, batch: LoopInjectionBatch, *, requeue: bool = True) -> None:
+        if not batch.batch_id:
+            return
+        with self._lock:
+            reserved = self._reserved_batches.pop(batch.batch_id, None)
+            if reserved and requeue:
+                self._queue.extend(reserved)
+
+    def has_pending(
+        self, scope: TaskScope, max_priority: QueuePriority = QueuePriority.NEXT
+    ) -> bool:
+        threshold = _PRIORITY_ORDER[max_priority]
+        with self._lock:
+            self._evict_expired_locked(now_ts=time.time())
+            return any(
+                item.scope.agent_id == scope.agent_id
+                and _PRIORITY_ORDER[item.priority] <= threshold
+                for item in self._queue
+            )
+
+    def ingest_from_messages(self, *, scope: TaskScope, messages: list[Any]) -> int:
+        """默认无 loop messages 桥接；子类或包装 provider 可覆盖。"""
+        return 0
+
+    def evict_expired(self, *, now_ts: float | None = None) -> int:
+        with self._lock:
+            return self._evict_expired_locked(now_ts=time.time() if now_ts is None else now_ts)
+
+    def _evict_over_capacity_locked(self) -> None:
+        if self._max_queue_size is None:
+            return
+        if self._max_queue_size < 0:
+            return
+        overflow = len(self._queue) - self._max_queue_size
+        if overflow <= 0:
+            return
+        # 保留高优先级：按优先级+创建时间排序，淘汰最不重要且最老的记录
+        self._queue.sort(
+            key=lambda item: (_PRIORITY_ORDER[item.priority], item.created_at)
+        )
+        # 末尾是低优先级；从末尾逆向淘汰 overflow 个
+        self._queue = self._queue[: self._max_queue_size]
+
+    def _evict_expired_locked(self, *, now_ts: float) -> int:
+        if self._ttl_sec is None or self._ttl_sec <= 0:
+            return 0
+        before = len(self._queue)
+        self._queue = [
+            item for item in self._queue if (now_ts - float(item.created_at)) < self._ttl_sec
+        ]
+        return before - len(self._queue)
+
+
+def _to_attachment_message(env: QueuedCommandEnvelope) -> dict:
+    text = f"[queued_command][{env.source}] {env.summary}"
+    return {
+        "role": "user",
+        "content": [{"type": "text", "text": text}],
+        "metadata": {
+            "queued_command": {
+                "command_id": env.command_id,
+                "source": env.source,
+                "priority": env.priority.value,
+                "payload": env.payload,
+            }
+        },
+    }
+

langchain_agentx/task_runtime/integrations/sqlite_queued_command_provider.py

@@ -0,0 +1,338 @@
+"""
+task_runtime/integrations/sqlite_queued_command_provider.py — 持久化 queued-command provider
+
+职责：
+    提供 queued command 的 SQLite 持久化实现，支持：
+    1. enqueue/build_batch/ack/nack/has_pending
+    2. TTL 回收与容量回收
+    3. 进程重启后的 reserved 恢复（crash-recovery）
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from threading import RLock
+from typing import Any
+from uuid import uuid4
+
+from ..core.types import QueuePriority, TaskScope
+from .loop_adapter import LoopInjectionBatch
+from .queued_command_provider import QueuedCommandEnvelope
+
+
+_PRIORITY_ORDER = {
+    QueuePriority.NOW: 0,
+    QueuePriority.NEXT: 1,
+    QueuePriority.LATER: 2,
+}
+
+
+class SqliteQueuedCommandProvider:
+    def __init__(
+        self,
+        db_path: str,
+        *,
+        max_queue_size: int | None = None,
+        ttl_sec: float | None = None,
+        recover_reserved_on_startup: bool = True,
+    ) -> None:
+        self._lock = RLock()
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._max_queue_size = max_queue_size
+        self._ttl_sec = ttl_sec
+        self._init_schema()
+        if recover_reserved_on_startup:
+            self._recover_reserved()
+
+    def _init_schema(self) -> None:
+        with self._conn:
+            self._conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS queued_commands (
+                    command_id TEXT PRIMARY KEY,
+                    source TEXT NOT NULL,
+                    summary TEXT NOT NULL,
+                    scope_agent_id TEXT,
+                    priority TEXT NOT NULL,
+                    payload_json TEXT NOT NULL,
+                    dedup_key TEXT,
+                    created_at REAL NOT NULL
+                )
+                """
+            )
+            self._conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS reserved_commands (
+                    batch_id TEXT NOT NULL,
+                    command_id TEXT NOT NULL,
+                    source TEXT NOT NULL,
+                    summary TEXT NOT NULL,
+                    scope_agent_id TEXT,
+                    priority TEXT NOT NULL,
+                    payload_json TEXT NOT NULL,
+                    dedup_key TEXT,
+                    created_at REAL NOT NULL,
+                    PRIMARY KEY (batch_id, command_id)
+                )
+                """
+            )
+
+    def enqueue(self, env: QueuedCommandEnvelope) -> None:
+        with self._lock, self._conn:
+            self._evict_expired_locked(now_ts=time.time())
+            if env.dedup_key:
+                self._conn.execute(
+                    "DELETE FROM queued_commands WHERE scope_agent_id IS ? AND dedup_key = ?",
+                    (env.scope.agent_id, env.dedup_key),
+                )
+            self._conn.execute(
+                """
+                INSERT OR REPLACE INTO queued_commands(
+                    command_id, source, summary, scope_agent_id, priority, payload_json, dedup_key, created_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    env.command_id,
+                    env.source,
+                    env.summary,
+                    env.scope.agent_id,
+                    env.priority.value,
+                    json.dumps(env.payload, ensure_ascii=True),
+                    env.dedup_key,
+                    float(env.created_at),
+                ),
+            )
+            self._evict_over_capacity_locked()
+
+    def build_batch(
+        self,
+        scope: TaskScope,
+        max_priority: QueuePriority = QueuePriority.NEXT,
+        *,
+        limit: int = 8,
+    ) -> LoopInjectionBatch:
+        if limit <= 0:
+            return LoopInjectionBatch(batch_id="", command_ids=[], attachment_messages=[])
+        threshold = _PRIORITY_ORDER[max_priority]
+        with self._lock, self._conn:
+            self._evict_expired_locked(now_ts=time.time())
+            rows = self._conn.execute(
+                """
+                SELECT * FROM queued_commands
+                WHERE scope_agent_id IS ?
+                ORDER BY
+                    CASE priority
+                        WHEN 'now' THEN 0
+                        WHEN 'next' THEN 1
+                        ELSE 2
+                    END ASC,
+                    created_at ASC
+                """,
+                (scope.agent_id,),
+            ).fetchall()
+            selected = [
+                row
+                for row in rows
+                if _PRIORITY_ORDER[QueuePriority(str(row["priority"]))] <= threshold
+            ][:limit]
+            if not selected:
+                return LoopInjectionBatch(batch_id="", command_ids=[], attachment_messages=[])
+
+            batch_id = f"sqbatch_{uuid4().hex[:10]}"
+            command_ids = [str(item["command_id"]) for item in selected]
+            for row in selected:
+                self._conn.execute(
+                    """
+                    INSERT OR REPLACE INTO reserved_commands(
+                        batch_id, command_id, source, summary, scope_agent_id, priority, payload_json, dedup_key, created_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        batch_id,
+                        row["command_id"],
+                        row["source"],
+                        row["summary"],
+                        row["scope_agent_id"],
+                        row["priority"],
+                        row["payload_json"],
+                        row["dedup_key"],
+                        row["created_at"],
+                    ),
+                )
+            placeholders = ",".join("?" for _ in command_ids)
+            self._conn.execute(
+                f"DELETE FROM queued_commands WHERE command_id IN ({placeholders})",
+                command_ids,
+            )
+            messages = [
+                _to_attachment_message(_row_to_env(row))
+                for row in selected
+            ]
+            return LoopInjectionBatch(
+                batch_id=batch_id,
+                command_ids=command_ids,
+                attachment_messages=messages,
+            )
+
+    def ack_batch(self, batch: LoopInjectionBatch) -> None:
+        if not batch.batch_id:
+            return
+        with self._lock, self._conn:
+            self._conn.execute(
+                "DELETE FROM reserved_commands WHERE batch_id = ?",
+                (batch.batch_id,),
+            )
+
+    def nack_batch(self, batch: LoopInjectionBatch, *, requeue: bool = True) -> None:
+        if not batch.batch_id:
+            return
+        with self._lock, self._conn:
+            rows = self._conn.execute(
+                "SELECT * FROM reserved_commands WHERE batch_id = ?",
+                (batch.batch_id,),
+            ).fetchall()
+            if requeue:
+                for row in rows:
+                    self._conn.execute(
+                        """
+                        INSERT OR REPLACE INTO queued_commands(
+                            command_id, source, summary, scope_agent_id, priority, payload_json, dedup_key, created_at
+                        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                        """,
+                        (
+                            row["command_id"],
+                            row["source"],
+                            row["summary"],
+                            row["scope_agent_id"],
+                            row["priority"],
+                            row["payload_json"],
+                            row["dedup_key"],
+                            row["created_at"],
+                        ),
+                    )
+            self._conn.execute(
+                "DELETE FROM reserved_commands WHERE batch_id = ?",
+                (batch.batch_id,),
+            )
+
+    def has_pending(
+        self, scope: TaskScope, max_priority: QueuePriority = QueuePriority.NEXT
+    ) -> bool:
+        threshold = _PRIORITY_ORDER[max_priority]
+        with self._lock:
+            self._evict_expired_locked(now_ts=time.time())
+            rows = self._conn.execute(
+                "SELECT priority FROM queued_commands WHERE scope_agent_id IS ?",
+                (scope.agent_id,),
+            ).fetchall()
+            return any(
+                _PRIORITY_ORDER[QueuePriority(str(item["priority"]))] <= threshold
+                for item in rows
+            )
+
+    def ingest_from_messages(self, *, scope: TaskScope, messages: list[Any]) -> int:
+        return 0
+
+    def evict_expired(self, *, now_ts: float | None = None) -> int:
+        with self._lock:
+            return self._evict_expired_locked(now_ts=time.time() if now_ts is None else now_ts)
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+    def _recover_reserved(self) -> None:
+        with self._lock, self._conn:
+            rows = self._conn.execute("SELECT * FROM reserved_commands").fetchall()
+            for row in rows:
+                self._conn.execute(
+                    """
+                    INSERT OR REPLACE INTO queued_commands(
+                        command_id, source, summary, scope_agent_id, priority, payload_json, dedup_key, created_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        row["command_id"],
+                        row["source"],
+                        row["summary"],
+                        row["scope_agent_id"],
+                        row["priority"],
+                        row["payload_json"],
+                        row["dedup_key"],
+                        row["created_at"],
+                    ),
+                )
+            self._conn.execute("DELETE FROM reserved_commands")
+
+    def _evict_expired_locked(self, *, now_ts: float) -> int:
+        if self._ttl_sec is None or self._ttl_sec <= 0:
+            return 0
+        cutoff = float(now_ts) - float(self._ttl_sec)
+        with self._conn:
+            cur = self._conn.execute(
+                "DELETE FROM queued_commands WHERE created_at <= ?",
+                (cutoff,),
+            )
+            return int(cur.rowcount or 0)
+
+    def _evict_over_capacity_locked(self) -> None:
+        if self._max_queue_size is None or self._max_queue_size < 0:
+            return
+        total = int(self._conn.execute("SELECT COUNT(*) FROM queued_commands").fetchone()[0])
+        overflow = total - self._max_queue_size
+        if overflow <= 0:
+            return
+        rows = self._conn.execute(
+            """
+            SELECT command_id
+            FROM queued_commands
+            ORDER BY
+                CASE priority
+                    WHEN 'now' THEN 0
+                    WHEN 'next' THEN 1
+                    ELSE 2
+                END ASC,
+                created_at ASC
+            """
+        ).fetchall()
+        keep_ids = [str(item["command_id"]) for item in rows[: self._max_queue_size]]
+        if not keep_ids:
+            self._conn.execute("DELETE FROM queued_commands")
+            return
+        placeholders = ",".join("?" for _ in keep_ids)
+        self._conn.execute(
+            f"DELETE FROM queued_commands WHERE command_id NOT IN ({placeholders})",
+            keep_ids,
+        )
+
+
+def _row_to_env(row: sqlite3.Row) -> QueuedCommandEnvelope:
+    return QueuedCommandEnvelope(
+        command_id=str(row["command_id"]),
+        source=str(row["source"]),
+        summary=str(row["summary"]),
+        scope=TaskScope(agent_id=row["scope_agent_id"]),
+        priority=QueuePriority(str(row["priority"])),
+        payload=json.loads(row["payload_json"] or "{}"),
+        dedup_key=row["dedup_key"],
+        created_at=float(row["created_at"]),
+    )
+
+
+def _to_attachment_message(env: QueuedCommandEnvelope) -> dict:
+    text = f"[queued_command][{env.source}] {env.summary}"
+    return {
+        "role": "user",
+        "content": [{"type": "text", "text": text}],
+        "metadata": {
+            "queued_command": {
+                "command_id": env.command_id,
+                "source": env.source,
+                "priority": env.priority.value,
+                "payload": env.payload,
+            }
+        },
+    }
+