devsper 2.4.1__tar.gz → 2.5.0__tar.gz

{devsper-2.4.1 → devsper-2.5.0}/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.0] — 2026-04-06
+
+### Added
+
+- **LangChain / LangGraph integrations** — `devsper.integrations.langchain_adapter` and `langgraph_adapter` for wrapping LangChain runnables as Devsper tasks and running compiled LangGraph nodes with Devsper DAG scheduling; CLI-friendly examples under `examples/langchain_agent.py` and `examples/langgraph_swarm.py`; optional extra `pip install 'devsper[langgraph]'` to pin LangGraph.
+
 ## [2.4.1] — 2026-03-31
 
 ### Fixed

{devsper-2.4.1 → devsper-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devsper
-Version: 2.4.1
+Version: 2.5.0
 Summary: Orchestrate distributed swarms of AI agents that collaboratively solve complex tasks.
 Project-URL: Homepage, https://github.com/devsper-com/runtime
 Project-URL: Documentation, https://docs.devsper.com
@@ -62,6 +62,8 @@ Requires-Dist: sentence-transformers>=3.0.0; extra == 'embeddings'
 Provides-Extra: explainability
 Provides-Extra: hitl
 Requires-Dist: httpx>=0.27; extra == 'hitl'
+Provides-Extra: langgraph
+Requires-Dist: langgraph<2,>=1.0.0; extra == 'langgraph'
 Provides-Extra: mcp
 Requires-Dist: anyio>=4.0; extra == 'mcp'
 Requires-Dist: httpx>=0.27; extra == 'mcp'
@@ -72,6 +74,7 @@ Provides-Extra: server
 Requires-Dist: fastapi>=0.110; extra == 'server'
 Requires-Dist: sse-starlette>=2.0; extra == 'server'
 Requires-Dist: uvicorn>=0.29; extra == 'server'
+Requires-Dist: vektori>=0.1.1; extra == 'server'
 Provides-Extra: worker
 Description-Content-Type: text/markdown
 
@@ -206,6 +209,28 @@ Credentials are injected from the keyring (or env) when config is resolved—no
 
 ---
 
+## LangChain integration
+
+Devsper ships a **small adapter layer** (not a parallel orchestration stack) so you can keep building in **LangChain** and **LangGraph** while aligning execution with Devsper’s **task / DAG** mental model.
+
+| Module | Purpose |
+|--------|---------|
+| `devsper.integrations.langchain_adapter` | Wrap LangChain runnables and agents as tagged `Task`s; `run_langchain_runnable()` runs `ainvoke` / `invoke` and normalizes output for `Task.result`. |
+| `devsper.integrations.langgraph_adapter` | Derive a Devsper task graph from a compiled LangGraph graph (`compiled_graph_to_tasks`); `run_compiled_graph_as_devsper_tasks()` runs each node with bounded concurrency and pluggable state merge (default: concatenate list fields—good for `MessagesState`). |
+
+**Install:** `langchain` is a core dependency of the `devsper` package; **LangGraph** is pulled in transitively. To pin it explicitly: `pip install 'devsper[langgraph]'`.
+
+**Examples (from the runtime repo root):**
+
+```bash
+uv run python examples/langchain_agent.py --prompt "Say hi in one sentence."
+uv run python examples/langgraph_swarm.py --workers 4
+```
+
+Docs: [LangChain integration](https://docs.devsper.com/docs/langchain-integration) (source: `docs/docs/langchain-integration.md` in the docs tree).
+
+---
+
 ## Credentials
 
 API keys are **not** stored in config files. Use the **credential store** (OS keychain) or environment variables.
@@ -363,6 +388,8 @@ Rust workers: set `DEVSPER_WORKER_MODEL=github:gpt-4o` (or your model), `DEVSPER
 | Dataset analysis | `uv run python examples/data_science/dataset_analysis.py [path-to.csv]` |
 | Document intelligence | `uv run python examples/documents/analyze_documents.py [dir]` |
 | Parameter sweep | `uv run python examples/experiments/parameter_sweep.py --params '{"lr":[0.01,0.1]}'` |
+| LangChain agent (adapter) | `uv run python examples/langchain_agent.py [--live] [--prompt "..."]` |
+| LangGraph DAG (as Devsper tasks) | `uv run python examples/langgraph_swarm.py [--workers N]` |
 
 Outputs under `examples/output/`. Run from project root when using script paths.
 

{devsper-2.4.1 → devsper-2.5.0}/README.md

@@ -129,6 +129,28 @@ Credentials are injected from the keyring (or env) when config is resolved—no
 
 ---
 
+## LangChain integration
+
+Devsper ships a **small adapter layer** (not a parallel orchestration stack) so you can keep building in **LangChain** and **LangGraph** while aligning execution with Devsper’s **task / DAG** mental model.
+
+| Module | Purpose |
+|--------|---------|
+| `devsper.integrations.langchain_adapter` | Wrap LangChain runnables and agents as tagged `Task`s; `run_langchain_runnable()` runs `ainvoke` / `invoke` and normalizes output for `Task.result`. |
+| `devsper.integrations.langgraph_adapter` | Derive a Devsper task graph from a compiled LangGraph graph (`compiled_graph_to_tasks`); `run_compiled_graph_as_devsper_tasks()` runs each node with bounded concurrency and pluggable state merge (default: concatenate list fields—good for `MessagesState`). |
+
+**Install:** `langchain` is a core dependency of the `devsper` package; **LangGraph** is pulled in transitively. To pin it explicitly: `pip install 'devsper[langgraph]'`.
+
+**Examples (from the runtime repo root):**
+
+```bash
+uv run python examples/langchain_agent.py --prompt "Say hi in one sentence."
+uv run python examples/langgraph_swarm.py --workers 4
+```
+
+Docs: [LangChain integration](https://docs.devsper.com/docs/langchain-integration) (source: `docs/docs/langchain-integration.md` in the docs tree).
+
+---
+
 ## Credentials
 
 API keys are **not** stored in config files. Use the **credential store** (OS keychain) or environment variables.
@@ -286,6 +308,8 @@ Rust workers: set `DEVSPER_WORKER_MODEL=github:gpt-4o` (or your model), `DEVSPER
 | Dataset analysis | `uv run python examples/data_science/dataset_analysis.py [path-to.csv]` |
 | Document intelligence | `uv run python examples/documents/analyze_documents.py [dir]` |
 | Parameter sweep | `uv run python examples/experiments/parameter_sweep.py --params '{"lr":[0.01,0.1]}'` |
+| LangChain agent (adapter) | `uv run python examples/langchain_agent.py [--live] [--prompt "..."]` |
+| LangGraph DAG (as Devsper tasks) | `uv run python examples/langgraph_swarm.py [--workers N]` |
 
 Outputs under `examples/output/`. Run from project root when using script paths.
 

devsper-2.5.0/devsper/contracts/__init__.py

@@ -0,0 +1,5 @@
+"""Shared contracts between runtime and platform (event type strings, etc.)."""
+
+from devsper.contracts.platform_event_type import DEVSPER_TO_PLATFORM, PlatformEventType
+
+__all__ = ["DEVSPER_TO_PLATFORM", "PlatformEventType"]

devsper-2.5.0/devsper/contracts/platform_event_type.py

@@ -0,0 +1,68 @@
+"""
+Canonical `event_type` strings accepted by the platform runtime ingest API and
+emitted by the runtime forwarder.
+
+**Single source of truth for Python.** Mirror:
+`platform/services/api/internal/contracts/runtime_events.go`
+"""
+
+from __future__ import annotations
+
+
+class PlatformEventType:
+    """Platform SSE / run_events.event_type values (string constants only)."""
+
+    RUN_STARTED = "run_started"
+    STEP_STARTED = "step_started"
+    STEP_COMPLETED = "step_completed"
+    AGENT_STARTED = "agent_started"
+    AGENT_FINISHED = "agent_finished"
+    RUN_PROGRESS = "run_progress"
+    TOOL_CALLED = "tool_called"
+    RUN_COMPLETED = "run_completed"
+    RUN_FAILED = "run_failed"
+    CLARIFICATION_REQUESTED = "clarification_requested"
+    CLARIFICATION_ANSWERED = "clarification_answered"
+    RUN_PAUSED = "run_paused"
+    RUN_RESUMED = "run_resumed"
+    LOG = "log"
+    EXECUTION_GRAPH_UPDATED = "EXECUTION_GRAPH_UPDATED"
+    SPECULATIVE_TASK_STARTED = "SPECULATIVE_TASK_STARTED"
+    SPECULATIVE_TASK_CANCELLED = "SPECULATIVE_TASK_CANCELLED"
+    HITL_REQUESTED = "HITL_REQUESTED"
+    HITL_RESOLVED = "HITL_RESOLVED"
+    WORKER_ASSIGNED = "WORKER_ASSIGNED"
+    AGENT_POOL_USED = "AGENT_POOL_USED"
+    EXECUTOR_FINISHED = "executor_finished"
+
+
+# DevSper `events` enum value (as string) -> platform ingest type
+DEVSPER_TO_PLATFORM: dict[str, str] = {
+    "swarm_started": PlatformEventType.RUN_STARTED,
+    "executor_started": PlatformEventType.RUN_STARTED,
+    "task_started": PlatformEventType.STEP_STARTED,
+    "task_completed": PlatformEventType.STEP_COMPLETED,
+    "agent_started": PlatformEventType.AGENT_STARTED,
+    "agent_finished": PlatformEventType.AGENT_FINISHED,
+    "run_completed": PlatformEventType.RUN_COMPLETED,
+    "task_failed": PlatformEventType.RUN_FAILED,
+    "run_failed": PlatformEventType.RUN_FAILED,
+    "tool_called": PlatformEventType.TOOL_CALLED,
+    "clarification_requested": PlatformEventType.CLARIFICATION_REQUESTED,
+    "clarification_needed": PlatformEventType.CLARIFICATION_REQUESTED,
+    "clarification_received": PlatformEventType.CLARIFICATION_ANSWERED,
+    "planner_started": PlatformEventType.RUN_PROGRESS,
+    "planner_finished": PlatformEventType.RUN_PROGRESS,
+    "reasoning_node_added": PlatformEventType.RUN_PROGRESS,
+    "budget_warning": PlatformEventType.RUN_PROGRESS,
+    "task_created": PlatformEventType.RUN_PROGRESS,
+    "task_model_selected": PlatformEventType.RUN_PROGRESS,
+    "agent_broadcast": PlatformEventType.RUN_PROGRESS,
+    "run_manifest_emitted": PlatformEventType.RUN_PROGRESS,
+    "worker_assigned": PlatformEventType.WORKER_ASSIGNED,
+    "speculative_started": PlatformEventType.SPECULATIVE_TASK_STARTED,
+    "speculative_cancelled": PlatformEventType.SPECULATIVE_TASK_CANCELLED,
+    "hitl_requested": PlatformEventType.HITL_REQUESTED,
+    "hitl_resolved": PlatformEventType.HITL_RESOLVED,
+    "executor_finished": PlatformEventType.EXECUTOR_FINISHED,
+}

devsper-2.5.0/devsper/debug_events.py

@@ -0,0 +1,38 @@
+"""DEVSPER_DEBUG_EVENTS=1 — log runtime → platform → delivery trail (stderr / logging)."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+_LOG = logging.getLogger("devsper.debug_events")
+
+
+def debug_events_enabled() -> bool:
+    return os.environ.get("DEVSPER_DEBUG_EVENTS", "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    )
+
+
+def log_runtime_emit(stage: str, payload: dict[str, Any]) -> None:
+    if not debug_events_enabled():
+        return
+    try:
+        line = json.dumps({"debug_events": stage, **payload}, default=str)
+    except TypeError:
+        line = str(payload)
+    _LOG.info(line)
+
+
+def log_platform_body(body: dict[str, Any]) -> None:
+    if not debug_events_enabled():
+        return
+    try:
+        _LOG.info("[platform_event] %s", json.dumps(body, default=str))
+    except TypeError:
+        _LOG.info("[platform_event] %s", body)

{devsper-2.4.1 → devsper-2.5.0}/devsper/docs/architecture/execution-model.md

@@ -6,7 +6,7 @@ The canonical execution model document lives under **docs**:
 
 That document is the source of truth for DAG execution, task state machine, HITL clarification (single-node and distributed, including Rust worker), bus topics, TUI lifecycle, and headless mode.
 
-For the latest runtime release notes (including 2.4.1 stabilization fixes), see:
+For the latest runtime release notes (including 2.5.0 LangChain/LangGraph adapters), see:
 
 - `https://docs.devsper.com/docs/release_notes`
 - `https://devsper.com/blog/distributed-runtime-upgrade-2-4-0`

devsper-2.5.0/devsper/integrations/__init__.py

@@ -0,0 +1,34 @@
+"""Optional bridges between Devsper and popular agent frameworks (LangChain, LangGraph)."""
+
+from __future__ import annotations
+
+__all__ = [
+    "langchain_task",
+    "run_langchain_runnable",
+    "stringify_langchain_output",
+    "LANGCHAIN_TASK_PREFIX",
+    "compiled_graph_to_tasks",
+    "default_list_merge_state",
+    "run_compiled_graph_as_devsper_tasks",
+]
+
+
+def __getattr__(name: str):
+    if name in (
+        "langchain_task",
+        "run_langchain_runnable",
+        "stringify_langchain_output",
+        "LANGCHAIN_TASK_PREFIX",
+    ):
+        from devsper.integrations import langchain_adapter as m
+
+        return getattr(m, name)
+    if name in (
+        "compiled_graph_to_tasks",
+        "default_list_merge_state",
+        "run_compiled_graph_as_devsper_tasks",
+    ):
+        from devsper.integrations import langgraph_adapter as m
+
+        return getattr(m, name)
+    raise AttributeError(name)

devsper-2.5.0/devsper/integrations/langchain_adapter.py

@@ -0,0 +1,80 @@
+"""Wrap LangChain runnables and agent pipelines as Devsper tasks (minimal surface, no extra framework)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from devsper.types.task import Task, TaskStatus
+
+LANGCHAIN_TASK_PREFIX = "[devsper:langchain]"
+
+
+def langchain_task(
+    task_id: str,
+    *,
+    description: str = "",
+    dependencies: list[str] | None = None,
+    role: str | None = None,
+) -> Task:
+    """Return a Devsper `Task` tagged for LangChain execution (visible in logs and DAG exports)."""
+    desc = (description or "").strip() or f"LangChain runnable ({task_id})"
+    if LANGCHAIN_TASK_PREFIX not in desc:
+        desc = f"{LANGCHAIN_TASK_PREFIX} {desc}"
+    return Task(
+        id=task_id,
+        description=desc,
+        dependencies=list(dependencies or []),
+        status=TaskStatus.PENDING,
+        role=role,
+    )
+
+
+def stringify_langchain_output(value: Any, *, max_len: int = 32000) -> str:
+    """Normalize LangChain/LangGraph outputs to a string suitable for `Task.result`."""
+    if value is None:
+        return ""
+    if hasattr(value, "content"):
+        text = getattr(value, "content", value)
+        return str(text)[:max_len]
+    if isinstance(value, dict):
+        if "output" in value:
+            return stringify_langchain_output(value["output"], max_len=max_len)
+        if "messages" in value:
+            parts: list[str] = []
+            for m in value["messages"]:
+                if hasattr(m, "content"):
+                    parts.append(str(getattr(m, "content", m)))
+                else:
+                    parts.append(str(m))
+            return "\n".join(parts).strip()[:max_len]
+        try:
+            return json.dumps(value, default=str)[:max_len]
+        except TypeError:
+            return str(value)[:max_len]
+    if isinstance(value, str):
+        return value[:max_len]
+    return str(value)[:max_len]
+
+
+async def run_langchain_runnable(
+    task: Task,
+    runnable: Any,
+    input_data: dict[str, Any] | str | list[Any],
+    *,
+    config: Any | None = None,
+) -> str:
+    """
+    Run a LangChain `Runnable`, agent, or legacy executor with async `ainvoke` when available.
+
+    `input_data` may be a string (wrapped as `{"input": ...}`), a message list (chat models), or a dict.
+    """
+    inp: Any = input_data
+    if isinstance(inp, str):
+        inp = {"input": inp}
+    if hasattr(runnable, "ainvoke"):
+        out = await runnable.ainvoke(inp, config=config)
+    else:
+        out = await asyncio.to_thread(runnable.invoke, inp, config)
+    return stringify_langchain_output(out)

devsper-2.5.0/devsper/integrations/langgraph_adapter.py

@@ -0,0 +1,151 @@
+"""Map LangGraph compiled graphs to Devsper task DAGs and run nodes with bounded concurrency."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from devsper.swarm.scheduler import Scheduler
+from devsper.types.task import Task, TaskStatus
+
+log = logging.getLogger(__name__)
+
+_SKIP = frozenset({"__start__", "__end__"})
+
+
+def default_list_merge_state(state: dict[str, Any], patch: dict[str, Any]) -> dict[str, Any]:
+    """
+    Merge a node patch into accumulated graph state.
+
+    For keys present in both sides with list values, lists are concatenated (typical for `MessagesState`).
+    Otherwise values from `patch` replace.
+    """
+    out = dict(state)
+    for k, v in patch.items():
+        if k in out and isinstance(out[k], list) and isinstance(v, list):
+            out[k] = list(out[k]) + list(v)
+        else:
+            out[k] = v
+    return out
+
+
+def _patch_summary(patch: dict[str, Any], *, max_len: int = 2000) -> str:
+    try:
+        return json.dumps(patch, default=str)[:max_len]
+    except TypeError:
+        return str(patch)[:max_len]
+
+
+def compiled_graph_to_tasks(compiled: Any, *, description_fmt: str | None = None) -> list[Task]:
+    """
+    Build a list of Devsper `Task` objects from a compiled LangGraph graph's static topology.
+
+    Task ids match LangGraph node names. Dependencies follow edges, ignoring `__start__` / `__end__`.
+    Raises if the topology is not a DAG (same validation as `Scheduler.add_tasks`).
+    """
+    try:
+        G = compiled.get_graph()
+    except Exception as exc:
+        raise TypeError("object must be a compiled LangGraph graph with get_graph()") from exc
+    fmt = description_fmt or "LangGraph node `{name}`"
+    predecessors: dict[str, list[str]] = {}
+    for edge in G.edges:
+        predecessors.setdefault(edge.target, []).append(edge.source)
+    tasks: list[Task] = []
+    for name in G.nodes:
+        if name in _SKIP:
+            continue
+        preds = [p for p in predecessors.get(name, []) if p not in _SKIP]
+        desc = fmt.format(name=name)
+        tasks.append(
+            Task(
+                id=str(name),
+                description=desc,
+                dependencies=list(preds),
+                status=TaskStatus.PENDING,
+            )
+        )
+    if not tasks:
+        raise ValueError("no executable LangGraph nodes found (excluding __start__/__end__)")
+    probe = Scheduler()
+    probe.add_tasks(tasks)
+    return tasks
+
+
+async def run_compiled_graph_as_devsper_tasks(
+    compiled: Any,
+    initial_state: dict[str, Any],
+    *,
+    worker_count: int = 4,
+    state_merge: Callable[[dict[str, Any], dict[str, Any]], dict[str, Any]] | None = None,
+    on_node_complete: Callable[[str, dict[str, Any]], Awaitable[None] | None] | None = None,
+) -> dict[str, Any]:
+    """
+    Execute a compiled LangGraph using Devsper's task DAG semantics: each node is one schedulable unit.
+
+    Ready nodes (dependencies satisfied) run concurrently up to `worker_count`. Shared graph state is
+    updated under a lock so parallel branches merge safely; use a custom `state_merge` if your
+    schema needs different rules than `default_list_merge_state`.
+    """
+    merge = state_merge or default_list_merge_state
+    nodes_map = getattr(compiled, "nodes", None)
+    if not isinstance(nodes_map, dict):
+        raise TypeError("compiled graph has no nodes mapping")
+
+    tasks = compiled_graph_to_tasks(compiled)
+    scheduler = Scheduler()
+    scheduler.add_tasks(tasks)
+
+    state: dict[str, Any] = dict(initial_state)
+    lock = asyncio.Lock()
+    sem = asyncio.Semaphore(max(1, int(worker_count)))
+    failures: list[BaseException] = []
+
+    async def run_one(task: Task) -> None:
+        name = task.id
+        node = nodes_map.get(name)
+        if node is None:
+            async with lock:
+                scheduler.mark_failed(name, f"no Pregel node for {name!r}")
+            failures.append(KeyError(name))
+            return
+        try:
+            async with sem:
+                async with lock:
+                    snapshot = dict(state)
+                patch = await node.ainvoke(snapshot)
+                if not isinstance(patch, dict):
+                    patch = {"output": patch}
+                async with lock:
+                    merged = merge(state, patch)
+                    state.clear()
+                    state.update(merged)
+                    scheduler.mark_completed(name, _patch_summary(patch))
+            if on_node_complete is not None:
+                async with lock:
+                    snap = dict(state)
+                await on_node_complete(name, snap)
+        except Exception as exc:  # noqa: BLE001 — surface as task failure + aggregate
+            log.exception("langgraph node %s failed", name)
+            async with lock:
+                scheduler.mark_failed(name, f"{type(exc).__name__}: {exc}")
+            failures.append(exc)
+
+    while not scheduler.is_finished():
+        if any(t.status == TaskStatus.FAILED for t in scheduler.get_all_tasks()):
+            for t in scheduler.get_all_tasks():
+                if t.status == TaskStatus.PENDING:
+                    scheduler.mark_failed(t.id, "aborted: upstream LangGraph node failure")
+            break
+        ready = scheduler.get_ready_tasks()
+        if not ready:
+            await asyncio.sleep(0.01)
+            continue
+        await asyncio.gather(*(run_one(t) for t in ready))
+
+    if failures:
+        raise failures[0]
+    return dict(state)

devsper-2.5.0/devsper/platform/__init__.py

@@ -0,0 +1 @@
+"""Platform integration helpers (swarmworker, metrics, run context)."""

devsper-2.5.0/devsper/platform/run_context.py

@@ -0,0 +1,53 @@
+"""
+Per-request execution context for platform swarmworker (thread-local).
+Used for org-scoped tool metrics in Redis.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+
+logger = logging.getLogger(__name__)
+
+_tls = threading.local()
+
+
+def set_execution_org(org_id: str) -> None:
+    _tls.org_id = (org_id or "").strip()
+
+
+def clear_execution_org() -> None:
+    _tls.org_id = ""
+
+
+def get_execution_org_id() -> str:
+    return getattr(_tls, "org_id", "") or ""
+
+
+def record_tool_call(tool_name: str, ok: bool, latency_ms: int) -> None:
+    """Best-effort Redis counters: devsper:tool_metrics:{org_id} hash fields {tool}:calls, :fail, :lat_ms."""
+    oid = get_execution_org_id()
+    if not oid or not tool_name:
+        return
+    url = (os.environ.get("REDIS_URL") or "").strip()
+    if not url:
+        return
+    try:
+        import redis  # type: ignore[import-untyped]
+    except ImportError:
+        return
+    key = f"devsper:tool_metrics:{oid}"
+    prefix = f"{tool_name}:"
+    try:
+        r = redis.Redis.from_url(url, decode_responses=True)
+        p = r.pipeline()
+        p.hincrby(key, prefix + "calls", 1)
+        if not ok:
+            p.hincrby(key, prefix + "fail", 1)
+        p.hincrby(key, prefix + "lat_ms", max(0, int(latency_ms)))
+        p.expire(key, 86400 * 30)  # 30d retention
+        p.execute()
+    except Exception as ex:
+        logger.debug("tool metrics redis skipped: %s", ex)