v0.53.0: vstack-import gains LangSmith + Phoenix formats

- from_langsmith_runs + --format langsmith: LangSmith run tree / list -> AgentTrace
  (run_type -> step type; inputs/outputs/error -> content; root-run goal/outcome).
- --format phoenix + extended from_otel_spans: read OpenInference attrs
  (openinference.span.kind, input.value/output.value, llm.*_messages) so Arize
  Phoenix exports import cleanly.

vstack-import now covers the dominant LLM-observability exports. 3,249 tests.

Author: valani9

CHANGELOG.md

@@ -6,6 +6,28 @@ project adheres to [Semantic Versioning](https://semver.org/) from
 `1.0.0` onward. During the `0.x` series, minor bumps may include
 breaking changes (see API stability promise in `vstack/__init__.py`).
 
+## [0.53.0] — 2026-06-23
+
+`vstack-import` now reads the two dominant LLM-observability exports.
+
+### Added
+
+- **`vstack.ingest.from_langsmith_runs`** + **`vstack-import --format
+  langsmith`** — convert a LangSmith run (with nested `child_runs` — a run
+  tree) or a flat list of runs into an `AgentTrace`. Maps `run_type`
+  (llm→message, tool→tool_call, chain→thought, retriever→observation, …);
+  uses `inputs`/`outputs`/`error` as step content; infers goal/outcome from
+  the root run. The CLI accepts a single run, a list, or `{"runs": [...]}`.
+- **`vstack-import --format phoenix`** + extended `from_otel_spans` — reads
+  OpenInference attributes (`openinference.span.kind`, `input.value`/
+  `output.value`, `llm.input_messages`/`llm.output_messages`), so Arize
+  Phoenix span exports import cleanly (the generic `otel` format now covers
+  them too).
+
+### Compatibility
+
+- All tests pass. Additive only; no breaking changes.
+
 ## [0.52.0] — 2026-06-23
 
 The Action's CI UX is now complete: gate · annotate · comment.

README.md

@@ -130,11 +130,13 @@ vstack-recipes                                   # browse named bundles (stuck_i
 vstack-diagnose --trace trace.json --recipe stuck_in_loop --client anthropic
 ```
 
-Don't have a vstack trace yet? Import the logs you already have — `vstack-import` converts OpenAI/Anthropic chat-message logs or OpenTelemetry spans into a trace, ready to pipe straight in:
+Don't have a vstack trace yet? Import the logs you already have — `vstack-import` converts OpenAI/Anthropic chat-message logs, OpenTelemetry spans, **Arize Phoenix** (OpenInference) spans, or **LangSmith** runs into a trace, ready to pipe straight in:
 
 ```bash
-vstack-import --format messages chat.json | vstack-diagnose --trace - --client anthropic
-vstack-import --format otel spans.json --goal "ship auth" | vstack-diagnose --trace -
+vstack-import --format messages  chat.json   | vstack-diagnose --trace - --client anthropic
+vstack-import --format otel       spans.json | vstack-diagnose --trace -
+vstack-import --format phoenix    spans.json | vstack-diagnose --trace -
+vstack-import --format langsmith  run.json   | vstack-diagnose --trace -
 ```
 
 ## Install

_ingest/lib/__init__.py

@@ -9,18 +9,23 @@
 Public API:
 
 * :func:`from_chat_messages` — a list of ``{role, content, tool_calls?}`` dicts.
-* :func:`from_otel_spans` — a list of OpenTelemetry span dicts (best-effort,
-  reads ``gen_ai.*`` attributes).
+* :func:`from_otel_spans` — a list of OpenTelemetry / OpenInference span dicts
+  (best-effort; reads ``gen_ai.*`` and OpenInference ``llm.*`` attributes —
+  also covers Arize Phoenix exports).
+* :func:`from_langsmith_runs` — a LangSmith run (tree) or list of runs.
 """
 
 from __future__ import annotations
 
+import json
 from datetime import datetime, timedelta, timezone
-from typing import Any
+from typing import Any, Literal
 
 from vstack.aar import AgentTrace, TraceStep
 
-__all__ = ["from_chat_messages", "from_otel_spans"]
+__all__ = ["from_chat_messages", "from_langsmith_runs", "from_otel_spans"]
+
+StepType = Literal["tool_call", "message", "decision", "observation", "thought"]
 
 _BASE_TS = datetime(2026, 1, 1, tzinfo=timezone.utc)
 
@@ -133,25 +138,37 @@ def from_otel_spans(
     """Build an ``AgentTrace`` from OpenTelemetry spans (best-effort).
 
     Spans are ordered by start time. Each span becomes a step: GenAI/LLM spans
-    (a ``gen_ai.*`` attribute or an ``llm``/``chat`` name) → ``tool_call``;
-    others → ``observation``. Reads ``attributes`` either as a dict or as a
-    list of ``{key, value}`` (OTLP-JSON form).
+    (a ``gen_ai.*`` attribute, an OpenInference ``llm.*`` attribute or
+    ``openinference.span.kind == LLM``, or an ``llm``/``chat`` name) →
+    ``tool_call``; others → ``observation``. Reads ``attributes`` either as a
+    dict or as a list of ``{key, value}`` (OTLP-JSON form). Also handles
+    OpenInference spans (the format Arize Phoenix exports).
     """
     ordered = sorted(spans, key=_span_start)
     steps: list[TraceStep] = []
 
     for i, span in enumerate(ordered):
         attrs = _otel_attrs(span)
         name = str(span.get("name", "span"))
-        is_genai = name.lower().startswith(("llm", "chat", "gen_ai")) or any(
-            k.startswith("gen_ai") for k in attrs
+        kind = str(attrs.get("openinference.span.kind", "")).upper()
+        is_genai = (
+            name.lower().startswith(("llm", "chat", "gen_ai"))
+            or kind in ("LLM", "CHAIN", "AGENT")
+            or any(k.startswith(("gen_ai", "llm.")) for k in attrs)
         )
         completion = (
             attrs.get("gen_ai.completion")
             or attrs.get("gen_ai.response.content")
             or attrs.get("llm.output")
+            or attrs.get("llm.output_messages")
+            or attrs.get("output.value")  # OpenInference / Phoenix
+        )
+        prompt = (
+            attrs.get("gen_ai.prompt")
+            or attrs.get("llm.input")
+            or attrs.get("llm.input_messages")
+            or attrs.get("input.value")  # OpenInference / Phoenix
         )
-        prompt = attrs.get("gen_ai.prompt") or attrs.get("llm.input")
         detail = str(completion or prompt or "")
         content = f"{name}: {detail}" if detail else name
         steps.append(
@@ -187,3 +204,95 @@ def _otel_attrs(span: dict[str, Any]) -> dict[str, Any]:
                     val = next(iter(val.values()), val)
                 out[str(item["key"])] = val
     return out
+
+
+# LangSmith run_type → trace step type.
+_LANGSMITH_STEP_TYPE: dict[str, StepType] = {
+    "llm": "message",
+    "chat": "message",
+    "tool": "tool_call",
+    "retriever": "observation",
+    "chain": "thought",
+    "agent": "decision",
+    "prompt": "thought",
+    "parser": "observation",
+}
+
+
+def _short(obj: Any, limit: int = 300) -> str:
+    """Compact one-line rendering of a run's inputs/outputs."""
+    if obj is None:
+        return ""
+    text = obj if isinstance(obj, str) else json.dumps(obj, default=str, ensure_ascii=False)
+    text = " ".join(text.split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def _flatten_runs(runs: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Depth-first flatten of LangSmith run trees, then order by start time."""
+    out: list[dict[str, Any]] = []
+
+    def visit(run: dict[str, Any]) -> None:
+        out.append(run)
+        for child in run.get("child_runs") or []:
+            if isinstance(child, dict):
+                visit(child)
+
+    for run in runs:
+        visit(run)
+    return sorted(out, key=lambda r: str(r.get("start_time") or ""))
+
+
+def _ls_content(run: dict[str, Any]) -> str:
+    name = str(run.get("name", "run"))
+    parts: list[str] = []
+    if run.get("inputs"):
+        parts.append(f"in: {_short(run.get('inputs'))}")
+    if run.get("outputs"):
+        parts.append(f"out: {_short(run.get('outputs'))}")
+    if run.get("error"):
+        parts.append(f"ERROR: {_short(run.get('error'))}")
+    body = " | ".join(parts)
+    return f"{name} — {body}" if body else name
+
+
+def from_langsmith_runs(
+    runs: list[dict[str, Any]] | dict[str, Any],
+    *,
+    goal: str = "",
+    outcome: str = "",
+    success: bool = False,
+    agent_id: str | None = None,
+    agent_framework: str = "langsmith",
+    metadata: dict[str, Any] | None = None,
+) -> AgentTrace:
+    """Build an ``AgentTrace`` from LangSmith runs.
+
+    Accepts a single run (with nested ``child_runs`` — a run tree) or a flat
+    list of runs. ``run_type`` maps to the step type (``llm``→message,
+    ``tool``→tool_call, ``chain``→thought, ``retriever``→observation, …);
+    ``inputs``/``outputs``/``error`` become the step content. ``goal`` defaults
+    to the root run's inputs and ``outcome`` to its outputs.
+    """
+    run_list = [runs] if isinstance(runs, dict) else list(runs)
+    flat = _flatten_runs(run_list)
+    steps = [
+        TraceStep(
+            timestamp=_ts(i),
+            type=_LANGSMITH_STEP_TYPE.get(str(run.get("run_type", "")).lower(), "observation"),
+            content=_ls_content(run),
+            metadata={"run_type": str(run.get("run_type", "")), "name": str(run.get("name", ""))},
+        )
+        for i, run in enumerate(flat)
+    ]
+
+    root = run_list[0] if run_list else {}
+    return AgentTrace(
+        agent_id=agent_id,
+        agent_framework=agent_framework,
+        goal=goal or _short(root.get("inputs")) or "(goal not provided)",
+        steps=steps,
+        outcome=outcome or _short(root.get("outputs")) or "(outcome not provided)",
+        success=success,
+        metadata=metadata or {},
+    )

_ingest/lib/_cli.py

@@ -15,7 +15,7 @@
 from pathlib import Path
 from typing import Any, Sequence
 
-from . import from_chat_messages, from_otel_spans
+from . import from_chat_messages, from_langsmith_runs, from_otel_spans
 
 
 def _load(path: str | None) -> Any:
@@ -53,9 +53,12 @@ def main(argv: Sequence[str] | None = None) -> int:
     parser.add_argument(
         "--format",
         "-f",
-        choices=("messages", "otel"),
+        choices=("messages", "otel", "phoenix", "langsmith"),
         required=True,
-        help="messages = OpenAI/Anthropic chat log; otel = OpenTelemetry spans.",
+        help=(
+            "messages = OpenAI/Anthropic chat log; otel = OpenTelemetry spans; "
+            "phoenix = Arize Phoenix / OpenInference spans; langsmith = LangSmith run(s)."
+        ),
     )
     parser.add_argument("--goal", default="", help="The agent's goal (else inferred).")
     parser.add_argument("--outcome", default="", help="What happened (else inferred).")
@@ -68,24 +71,24 @@ def main(argv: Sequence[str] | None = None) -> int:
     parser.add_argument("--out", "-o", default=None, help="Write to a file (default: stdout).")
     args = parser.parse_args(argv)
 
+    common = {
+        "goal": args.goal,
+        "outcome": args.outcome,
+        "success": args.success,
+        "agent_id": args.agent_id,
+    }
     try:
         payload = _load(args.input)
         if args.format == "messages":
-            trace = from_chat_messages(
-                _items(payload, "messages"),
-                goal=args.goal,
-                outcome=args.outcome,
-                success=args.success,
-                agent_id=args.agent_id,
-            )
-        else:
-            trace = from_otel_spans(
-                _items(payload, "spans"),
-                goal=args.goal,
-                outcome=args.outcome,
-                success=args.success,
-                agent_id=args.agent_id,
-            )
+            trace = from_chat_messages(_items(payload, "messages"), **common)
+        elif args.format in ("otel", "phoenix"):
+            trace = from_otel_spans(_items(payload, "spans"), **common)
+        else:  # langsmith — accept a single run (tree), a list, or {"runs": [...]}
+            if isinstance(payload, dict) and not isinstance(payload.get("runs"), list):
+                runs: Any = payload  # a single run / run tree
+            else:
+                runs = _items(payload, "runs")
+            trace = from_langsmith_runs(runs, **common)
     except (OSError, ValueError, json.JSONDecodeError) as e:
         print(f"vstack-import: {e}", file=sys.stderr)
         return 2

_ingest/tests/test_ingest.py

@@ -125,3 +125,72 @@ def test_cli_bad_shape_returns_2() -> None:
     code, _out, err = _run_cli(["--format", "messages"], stdin=json.dumps({"nope": 1}))
     assert code == 2
     assert "vstack-import" in err
+
+
+# --- LangSmith ------------------------------------------------------------
+
+
+def test_from_langsmith_run_tree() -> None:
+    from vstack.ingest import from_langsmith_runs
+
+    tree = {
+        "name": "My Chat Bot",
+        "run_type": "chain",
+        "start_time": "2026-01-01T00:00:00",
+        "inputs": {"text": "summarize meetings"},
+        "outputs": {"output": "done"},
+        "child_runs": [
+            {
+                "name": "My LLM",
+                "run_type": "llm",
+                "start_time": "2026-01-01T00:00:01",
+                "inputs": {"prompts": ["..."]},
+                "outputs": {"generations": ["use the tool"]},
+            },
+            {
+                "name": "loader",
+                "run_type": "tool",
+                "start_time": "2026-01-01T00:00:02",
+                "inputs": {"date": "x"},
+                "error": "boom",
+            },
+        ],
+    }
+    trace = from_langsmith_runs(tree)
+    types = [s.type for s in trace.steps]
+    assert types == ["thought", "message", "tool_call"]  # chain, llm, tool
+    assert trace.goal.startswith("") and "summarize meetings" in trace.goal
+    assert "ERROR: boom" in trace.steps[2].content
+
+
+def test_from_langsmith_flat_list_orders_by_start() -> None:
+    from vstack.ingest import from_langsmith_runs
+
+    runs = [
+        {"name": "b", "run_type": "tool", "start_time": "2026-01-01T00:00:05"},
+        {"name": "a", "run_type": "llm", "start_time": "2026-01-01T00:00:01"},
+    ]
+    trace = from_langsmith_runs(runs)
+    assert [s.metadata["name"] for s in trace.steps] == ["a", "b"]
+
+
+def test_cli_langsmith_single_run() -> None:
+    run = {"name": "root", "run_type": "chain", "inputs": {"q": "hi"}, "outputs": {"a": "ok"}}
+    code, out, _ = _run_cli(["--format", "langsmith"], stdin=json.dumps(run))
+    assert code == 0
+    assert json.loads(out)["agent_framework"] == "langsmith"
+
+
+def test_cli_phoenix_openinference_span() -> None:
+    spans = [
+        {
+            "name": "llm",
+            "start_time": 1,
+            "attributes": {"openinference.span.kind": "LLM", "output.value": "the answer"},
+        }
+    ]
+    code, out, _ = _run_cli(["--format", "phoenix"], stdin=json.dumps(spans))
+    assert code == 0
+    trace = json.loads(out)
+    assert trace["steps"][0]["type"] == "tool_call"
+    assert "the answer" in trace["steps"][0]["content"]

_packaging/vstack/__init__.py

@@ -73,7 +73,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.52.0"
+__version__ = "0.53.0"
 
 # The diagnose() function and PATTERNS registry are lazy-imported below
 # so that ``import vstack`` itself stays cheap. Pattern sub-packages

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "valanistack"
-version = "0.52.0"
+version = "0.53.0"
 description = "Organizational behavior, practiced on AI agents."
 readme = "README.md"
 requires-python = ">=3.11"