release: 2.6.0 — TruLens observability

Add TruLens recording for swarm runs and agent calls, telemetry config
keys, optional devsper[trulens] extra, and devsper observe dashboard CLI.

Bump version and update changelog.

Made-with: Cursor

Author: rithulkamesh

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.6.0] — 2026-04-06
+
+### Added
+
+- **TruLens observability integration** — Added first-class TruLens instrumentation for swarm runs and agent calls, with configurable runtime toggles in `[telemetry]` (`trulens_enabled`, `trulens_database_url`) and recorder/session exports in `devsper.telemetry`.
+- **CLI observability dashboard command** — Added `devsper observe` to launch the TruLens dashboard locally with optional `--port` and `--db` overrides.
+- **Optional `trulens` extra** — Added `devsper[trulens]` dependency group for straightforward TruLens installation.
+
+### Changed
+
+- **Swarm execution path** — `Swarm.run` now records via a TruLens custom app wrapper when enabled, with safe fallback to the standard runtime path if TruLens initialization or recorder setup fails.
+- **Agent call capture** — `Agent.run` is instrumented for per-call telemetry capture when TruLens is installed.
+- **Telemetry defaults and examples** — Updated default config template to include TruLens options and local database guidance.
+
 ## [2.5.0] — 2026-04-06
 
 ### Added

devsper.toml

@@ -24,6 +24,8 @@ enabled = true
 top_k = 12
 
 [telemetry]
+trulens_enabled = true
+trulens_database_url = ""   # empty = sqlite:///.devsper/trulens.sqlite
 otel_enabled = true
 otel_endpoint = ""
 cost_tracking = true

devsper/agents/agent.py

@@ -15,6 +15,7 @@
     ClarificationField,
     ClarificationRequest,
 )
+from devsper.telemetry.trulens import instrument as _tru_instrument
 
 log = logging.getLogger(__name__)
 
@@ -765,6 +766,7 @@ def _auto_web_collection_answers(
             answers[f.question] = self._default_answer_for_field(f)
         return answers
 
+    @_tru_instrument
     def run(self, request: AgentRequest) -> AgentResponse:
         """Stateless run: all context in AgentRequest, all output in AgentResponse."""
         import time

devsper/cli/main.py

@@ -2068,6 +2068,33 @@ def _run_analytics() -> int:
     return 0
 
 
+def _run_observe(port: int = 8501, db: str = "") -> int:
+    """Launch the TruLens observability dashboard."""
+    try:
+        from devsper.telemetry.trulens import init_trulens, get_session
+    except ImportError:
+        print("TruLens is not installed. Run: uv pip install 'devsper[trulens]'")
+        return 1
+
+    session = get_session() or init_trulens(database_url=db)
+    if session is None:
+        print(
+            "TruLens is not installed or failed to initialize.\n"
+            "Run: uv pip install 'devsper[trulens]'"
+        )
+        return 1
+
+    db_url = getattr(session, "connector", None)
+    db_label = str(db or ".devsper/trulens.sqlite")
+    print(f"Opening TruLens dashboard — db: {db_label}  port: {port}")
+    print("Press Ctrl-C to stop.")
+    try:
+        session.run_dashboard(port=port)
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
 def _run_tools(args: object) -> int:
     """List tools with reliability scores, or reset score history."""
     from rich.console import Console
@@ -4032,6 +4059,29 @@ def main() -> int:
     )
     version_parser.set_defaults(func=_run_version)
 
+    observe_parser = subparsers.add_parser(
+        "observe",
+        help="Launch TruLens observability dashboard",
+        description="Open the TruLens dashboard for browsing run records, traces, and feedback.",
+        epilog="""
+Examples:
+  devsper observe
+  devsper observe --port 8502
+  devsper observe --db sqlite:///custom.sqlite
+""",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    observe_parser.add_argument(
+        "--port", type=int, default=8501, help="Dashboard port (default: 8501)"
+    )
+    observe_parser.add_argument(
+        "--db",
+        default="",
+        metavar="URL",
+        help="TruLens database URL (default: sqlite:///.devsper/trulens.sqlite)",
+    )
+    observe_parser.set_defaults(func=lambda a: _run_observe(a.port, a.db))
+
     health_parser = subparsers.add_parser(
         "health",
         help="Health and readiness check",

devsper/config/schema.py

@@ -109,6 +109,8 @@ class TelemetryConfig(BaseModel):
     otel_endpoint: str = ""
     otel_headers: dict[str, str] = Field(default_factory=dict)
     cost_tracking: bool = True
+    trulens_enabled: bool = True
+    trulens_database_url: str = ""  # empty = SQLite default (~/.trulens/)
 
 
 class BudgetConfig(BaseModel):

devsper/swarm/swarm.py

@@ -11,11 +11,14 @@
 
 import asyncio
 import json
+import logging
 import os
 import threading
 from pathlib import Path
 from datetime import datetime, timezone
 
+log = logging.getLogger(__name__)
+
 from devsper.types.task import Task
 from devsper.types.event import Event, events
 from devsper.utils.event_logger import EventLog
@@ -28,6 +31,12 @@
 from devsper.agents.registry import AgentRegistry
 from devsper.budget import BudgetManager
 from devsper.telemetry import instrument_swarm_run, record_exception
+from devsper.telemetry.trulens import (
+    init_trulens,
+    get_session,
+    make_recorder,
+    instrument as _tru_instrument,
+)
 
 
 def _fake_config():
@@ -79,6 +88,22 @@ def _persist_dag(scheduler: Scheduler, event_log: EventLog, execution_graph: obj
         json.dump({"nodes": nodes, "edges": edges}, f, indent=0)
 
 
+class _TruSwarmApp:
+    """Thin TruLens-instrumented wrapper for swarm execution.
+
+    TruLens @instrument marks this method so every call is captured as a record
+    when a TruCustomApp recorder is active.  The Swarm delegates to this wrapper
+    only when TruLens is enabled; otherwise _run_core() is called directly.
+    """
+
+    def __init__(self, swarm: "Swarm") -> None:
+        self._swarm = swarm
+
+    @_tru_instrument
+    def execute(self, user_task: str, hitl_resolver: object = None) -> dict:
+        return self._swarm._run_core(user_task, hitl_resolver)
+
+
 class RunResult(dict):
     """Backward-compatible run result map with optional metadata."""
 
@@ -200,6 +225,18 @@ def __init__(
         self._last_reasoning_store = None
         self._pause_event = threading.Event()
         self._pause_event.set()
+        # Initialize TruLens session if enabled in config
+        _tele = getattr(cfg, "telemetry", None) if cfg is not None else None
+        if getattr(_tele, "trulens_enabled", True):
+            try:
+                from devsper import __version__
+
+                init_trulens(
+                    database_url=str(getattr(_tele, "trulens_database_url", "") or ""),
+                    app_version=__version__,
+                )
+            except Exception as _tlu_exc:
+                log.warning("TruLens init skipped: %s", _tlu_exc)
 
     def pause(self) -> None:
         """Pause the executor: currently-running tasks finish, no new tasks start."""
@@ -209,11 +246,35 @@ def resume(self) -> None:
         """Resume the executor so new tasks can be picked."""
         self._pause_event.set()
 
+    def _trulens_enabled(self) -> bool:
+        """Return True if TruLens recording is configured and a session exists."""
+        tele = getattr(self._config, "telemetry", None)
+        enabled = bool(getattr(tele, "trulens_enabled", True)) if tele else True
+        return enabled and get_session() is not None
+
     def run(self, user_task: str, hitl_resolver: object = None) -> dict[str, str]:
         """
         Create root task → plan subtasks → add to scheduler → run executor → return task_id → result.
         hitl_resolver: optional (approval, policy) -> bool for in-process approval prompts.
+
+        When TruLens is enabled the run is recorded via TruCustomApp so inputs,
+        outputs, and per-agent calls are stored in the TruLens database.
         """
+        if self._trulens_enabled():
+            try:
+                from devsper import __version__
+
+                _app = _TruSwarmApp(self)
+                recorder = make_recorder(_app, app_name="devsper", app_version=__version__)
+                if recorder is not None:
+                    with recorder as _recording:
+                        return _app.execute(user_task, hitl_resolver)
+            except Exception as _tru_exc:
+                log.warning("TruLens recording setup failed, falling back: %s", _tru_exc)
+        return self._run_core(user_task, hitl_resolver)
+
+    def _run_core(self, user_task: str, hitl_resolver: object = None) -> dict[str, str]:
+        """Internal run implementation (called directly or via TruLens wrapper)."""
         run_id = getattr(self.event_log, "run_id", "") or ""
         with instrument_swarm_run(run_id, user_task) as span:
             if span is not None:

devsper/telemetry/__init__.py

@@ -7,13 +7,21 @@
     record_exception,
 )
 from devsper.telemetry.pricing import PRICING, estimate_cost_usd
+from devsper.telemetry.trulens import (
+    get_session as get_trulens_session,
+    init_trulens,
+    make_recorder as make_trulens_recorder,
+)
 
 __all__ = [
     "PRICING",
     "annotate_span",
     "estimate_cost_usd",
     "get_tracer",
+    "get_trulens_session",
+    "init_trulens",
     "instrument_swarm_run",
+    "make_trulens_recorder",
     "record_exception",
 ]
 

devsper/telemetry/trulens.py

@@ -0,0 +1,119 @@
+"""TruLens observability — default for devsper 2.6.0+.
+
+TruLens records every swarm run (input task → output results) and every agent
+call (prompt → completion) into a local SQLite database at
+``.devsper/trulens.sqlite`` (same directory as memory.db and tool_analytics.db).
+
+The TruLens dashboard can be launched with::
+
+    from devsper.telemetry import get_trulens_session
+    get_trulens_session().run_dashboard()
+
+OTEL spans are still emitted alongside TruLens records — they are complementary.
+TruLens is the new *default* export layer; OTEL remains available for
+infrastructure-level tracing (Grafana, Jaeger, etc.).
+
+Configuration (devsper.toml):
+
+    [telemetry]
+    trulens_enabled = true
+    trulens_database_url = ""   # empty = sqlite:///.devsper/trulens.sqlite
+
+Install::
+
+    uv pip install "devsper[trulens]"
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+# Default SQLite path — mirrors memory.db / tool_analytics.db location.
+_DEFAULT_DB_PATH = ".devsper/trulens.sqlite"
+_DEFAULT_DB_URL = f"sqlite:///{_DEFAULT_DB_PATH}"
+
+try:
+    from trulens.core import TruSession
+    from trulens.apps.custom import TruCustomApp, instrument
+
+    _TRULENS_AVAILABLE = True
+except ImportError:
+    _TRULENS_AVAILABLE = False
+    TruSession = None  # type: ignore[assignment,misc]
+    TruCustomApp = None  # type: ignore[assignment,misc]
+
+    def instrument(fn):  # type: ignore[misc]  # noqa: E306
+        """No-op fallback when trulens-core is not installed."""
+        return fn
+
+
+_session: Any = None  # TruSession | None
+
+
+def init_trulens(
+    *,
+    database_url: str = "",
+    app_name: str = "devsper",
+    app_version: str = "",
+) -> Any:
+    """Initialize global TruLens session (idempotent).
+
+    Defaults to ``sqlite:///.devsper/trulens.sqlite`` — the same ``.devsper/``
+    directory used by ``memory.db`` and ``tool_analytics.db``.
+
+    Returns the session on success, or None if trulens-core is not installed
+    or initialization fails.
+    """
+    global _session
+    if not _TRULENS_AVAILABLE:
+        log.debug("trulens-core not installed; TruLens observability skipped")
+        return None
+    if _session is not None:
+        return _session
+    url = database_url.strip() if database_url else _DEFAULT_DB_URL
+    # Ensure the .devsper/ directory exists for the default SQLite path.
+    if url == _DEFAULT_DB_URL:
+        os.makedirs(os.path.dirname(_DEFAULT_DB_PATH), exist_ok=True)
+    try:
+        _session = TruSession(database_url=url)
+        log.info(
+            "TruLens session initialized (app=%s v%s db=%s)",
+            app_name,
+            app_version or "?",
+            url,
+        )
+    except Exception as exc:
+        log.warning("TruLens init failed: %s", exc)
+    return _session
+
+
+def get_session() -> Any:
+    """Return the active TruLens session, or None."""
+    return _session
+
+
+def make_recorder(
+    app: Any,
+    *,
+    app_name: str = "devsper",
+    app_version: str = "",
+) -> Any:
+    """Wrap an instrumented app with TruCustomApp for recording.
+
+    Returns a TruCustomApp recorder, or None if TruLens is unavailable /
+    the session has not been initialized.
+    """
+    if not _TRULENS_AVAILABLE or _session is None or TruCustomApp is None:
+        return None
+    try:
+        kwargs: dict[str, Any] = {"app_name": app_name}
+        if app_version:
+            kwargs["app_version"] = app_version
+        return TruCustomApp(app, **kwargs)
+    except Exception as exc:
+        log.warning("TruLens make_recorder failed: %s", exc)
+        return None

pyproject.toml

@@ -7,7 +7,7 @@ packages = ["devsper"]
 
 [project]
 name = "devsper"
-version = "2.5.0"
+version = "2.6.0"
 description = "Orchestrate distributed swarms of AI agents that collaboratively solve complex tasks."
 readme = "README.md"
 license = "GPL-3.0-or-later"
@@ -70,6 +70,9 @@ distributed = [
     "uvicorn>=0.29.0",
     "hiredis>=2.3.0",
 ]
+# TruLens observability (default since 2.6.0).
+# trulens-core pins rich<14; we override that constraint via [tool.uv.override-dependencies].
+trulens = ["trulens-core>=1.0"]
 # Pin LangGraph explicitly for integrators (also pulled in via langchain).
 langgraph = ["langgraph>=1.0.0,<2"]
 worker = []  # distributed worker is a separate Rust binary (devsper-worker)
@@ -88,3 +91,9 @@ dev = [
     "respx>=0.22.0",
     "ruff>=0.15.5",
 ]
+
+[tool.uv]
+# trulens-core pins rich<14; textual (and devsper's TUI) requires rich>=14.
+# Override so uv resolves to the version we actually need — rich 14.x is
+# backward-compatible with the Console/Table APIs trulens uses.
+override-dependencies = ["rich>=14.3.3"]