cmpnd 0.4.3__tar.gz → 0.5.0__tar.gz

{cmpnd-0.4.3 → cmpnd-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmpnd
-Version: 0.4.3
+Version: 0.5.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>

{cmpnd-0.4.3 → cmpnd-0.5.0}/cmpnd/callback.py

@@ -64,12 +64,17 @@ class _CallbackBase:
         capture_prompts: bool | None = None,
         max_input_field_size: int | None = None,
         max_output_field_size: int | None = None,
+        stream_trace_starts: bool | None = None,
     ) -> None:
         # Resolve feature flags: explicit param > config > default
         config = configuration.get_config()
         self._capture_inputs = (
             capture_inputs if capture_inputs is not None else (config.capture_inputs if config else True)
         )
+        # Emit an in_progress start for every root trace, not just RLM (CMP-257).
+        self._stream_trace_starts = (
+            stream_trace_starts if stream_trace_starts is not None else (config.stream_trace_starts if config else True)
+        )
         self._capture_outputs = (
             capture_outputs if capture_outputs is not None else (config.capture_outputs if config else True)
         )
@@ -186,13 +191,22 @@ class _ModuleMixin(_CallbackBase):
             # start (CMP-537) — before any span lands — instead of inferring it
             # from span shape later.
             trace.root_span_type = span_type.value
-            # RLM traces use streaming export; everything else batches
+            # RLM traces use streaming export (per-span); everything else
+            # batches its spans and sends the whole trace at finalize.
             if span_type == models.SpanType.RLM:
                 trace.streaming = True
             self._streaming_traces[str(trace.trace_id)] = trace.streaming
 
-            # Only stream trace_start for streaming traces
-            if trace.streaming:
+            # Emit an in_progress start row for EVERY root trace (CMP-257), not
+            # just streaming/RLM ones, so a non-RLM program is visible the moment
+            # it starts (`traces search --status in_progress`, a lookupable id)
+            # instead of only appearing at finalize. `trace.streaming` still
+            # governs per-span vs batch export below — only the start emission is
+            # generalized. The batch finalize upserts this same row (serve
+            # traceUpsertSQL, ON CONFLICT org_id,trace_id,start_time), and the
+            # exporter coalesces a start with its batch trace in one flush, so a
+            # fast trace pays a single insert, not two.
+            if self._stream_trace_starts:
                 exp = exporter.get_exporter()
                 if exp:
                     exp.export_trace_start(trace)

cmpnd-0.5.0/cmpnd/cli/commands/traces.py

@@ -0,0 +1,159 @@
+"""Traces commands."""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from argparse import ArgumentParser, _SubParsersAction
+from typing import Any
+
+from .. import api_client, trace_render
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser("traces", help="Browse traces")
+    sub = parser.add_subparsers(dest="action")
+
+    search = sub.add_parser("search", help="Search traces")
+    search.add_argument("--status", help="Filter by status (ok, error, incomplete, in_progress)")
+    search.add_argument("--program", dest="program_name", help="Filter by program name")
+    search.add_argument("--hash", dest="program_signature_hash", help="Filter by program signature hash")
+    search.add_argument("--deployment", dest="deployment_id", help="Filter by deployment id (UUID)")
+    search.add_argument(
+        "--tag",
+        dest="tags",
+        action="append",
+        help="Filter by project tag (the sidebar 'Tags' filter); repeat for any-of",
+    )
+    search.add_argument("--from", dest="start_time_from", help="Start time from (ISO 8601)")
+    search.add_argument("--to", dest="start_time_to", help="Start time to (ISO 8601)")
+    search.add_argument("--page", type=int, default=1)
+    search.add_argument("--per-page", type=int, default=50)
+    search.set_defaults(func=handle_search)
+
+    show = sub.add_parser("show", help="Show a trace (raw JSON by default; --tree / --timeline for human views)")
+    show.add_argument("id", help="Trace ID (UUID)")
+    view = show.add_mutually_exclusive_group()
+    view.add_argument("--tree", action="store_true", help="Colorized span tree (Tree view)")
+    view.add_argument("--timeline", action="store_true", help="Gantt-style timeline (mirrors the web Timeline view)")
+    view.add_argument(
+        "--notebook", action="store_true", help="Emit the RLM trace's Jupyter .ipynb to stdout (errors if not RLM)"
+    )
+    show.set_defaults(func=handle_show)
+
+    follow = sub.add_parser("follow", help="Tail a trace's spans live as they land, until it finishes")
+    follow.add_argument("id", help="Trace ID (UUID)")
+    # JSON-first, like the rest of `traces`: the default is NDJSON (one compact
+    # span per line, flushed as it lands); --tree opts into the human view.
+    follow.add_argument("--tree", action="store_true", help="Human view: one span line as it lands, then the full tree")
+    follow.add_argument("--interval", type=float, default=1.0, help="Poll interval in seconds (default 1.0)")
+    follow.add_argument(
+        "--timeout",
+        type=float,
+        default=0.0,
+        help="Stop after N seconds if the trace hasn't finished. Default 0 = follow until it finishes (or Ctrl-C)",
+    )
+    follow.set_defaults(func=handle_follow)
+
+
+def handle_search(client: api_client.ApiClient, args: Any) -> Any:
+    body: dict[str, Any] = {"page": args.page, "per_page": args.per_page}
+    for attr, key in [
+        ("status", "status"),
+        ("program_name", "program_name"),
+        ("program_signature_hash", "program_signature_hash"),
+        ("deployment_id", "deployment_id"),
+        ("tags", "tags"),
+        ("start_time_from", "start_time_from"),
+        ("start_time_to", "start_time_to"),
+    ]:
+        val = getattr(args, attr, None)
+        if val is not None:
+            body[key] = val
+    resp = client.post("/api/v1/traces/search", json=body)
+
+    # Servers that predate the deployment_id filter silently drop the
+    # unknown key and return whole-org traces. If the user asked for a
+    # deployment filter and we got back traces with no deployment_id
+    # field, warn — otherwise the count looks legitimate but isn't.
+    if getattr(args, "deployment_id", None) and resp.get("traces"):
+        first = resp["traces"][0]
+        if first.get("deployment_id") in (None, ""):
+            print(
+                "warning: server does not support the deployment_id filter; results are unfiltered",
+                file=sys.stderr,
+            )
+
+    return resp
+
+
+def handle_show(client: api_client.ApiClient, args: Any) -> Any:
+    if getattr(args, "notebook", False):
+        # Reconstructed .ipynb straight to stdout (the framework pretty-prints
+        # the returned dict as JSON — a valid notebook file). A non-RLM or
+        # missing trace 404s, which ApiClient raises → non-zero exit; a valid
+        # RLM trace returns the notebook → exit 0.
+        return client.get(f"/api/v1/traces/{args.id}/notebook.ipynb")
+    resp = client.get(f"/api/v1/traces/{args.id}")
+    trace = resp.get("trace") or {}
+    spans = resp.get("spans") or []
+    if getattr(args, "tree", False):
+        # Color for readability, but only on a TTY (a pipe/file/CI gets plain).
+        print(trace_render.render_tree(trace, spans, color=trace_render.use_color(sys.stdout)))
+        return None
+    if getattr(args, "timeline", False):
+        print(trace_render.render_timeline(trace, spans, color=trace_render.use_color(sys.stdout)))
+        return None
+    # Default: raw trace+spans JSON — the CLI framework pretty-prints the dict,
+    # matching `traces search` (JSON-first). Human views are opt-in above.
+    return resp
+
+
+def handle_follow(client: api_client.ApiClient, args: Any) -> Any:
+    """Tail a trace's spans as they land, exiting when it reaches a terminal
+    status. Polls GET /api/v1/traces/{id}, emits only spans not seen before
+    (ordered by start time), and owns its output — NDJSON by default (one
+    compact span per line, flushed), or a human span-line stream + closing tree
+    under --tree. `tail -f` semantics: no timeout unless --timeout asks for one,
+    and Ctrl-C is a clean stop."""
+    trace_id = args.id
+    interval = max(0.0, getattr(args, "interval", 1.0))
+    timeout = getattr(args, "timeout", 0.0) or 0.0
+    as_human = getattr(args, "tree", False)
+    color = trace_render.use_color(sys.stdout) if as_human else False
+
+    seen: set[str] = set()
+    started = time.monotonic()
+    trace: dict[str, Any] = {}
+    spans: list[dict[str, Any]] = []
+    settled = False
+    try:
+        while True:
+            resp = client.get(f"/api/v1/traces/{trace_id}")
+            trace = resp.get("trace") or {}
+            spans = resp.get("spans") or []
+            # Emit spans not seen yet, in arrival (start-time) order.
+            for s in sorted(spans, key=lambda x: (str(x.get("start_time") or ""), str(x.get("span_id") or ""))):
+                sid = str(s.get("span_id") or "")
+                if not sid or sid in seen:
+                    continue
+                seen.add(sid)
+                if as_human:
+                    print(trace_render.span_line(s, color=color), flush=True)
+                else:
+                    print(json.dumps(s, separators=(",", ":")), flush=True)
+            status = str(trace.get("status") or "")
+            if status and status != "in_progress":
+                settled = True  # terminal: ok / error / incomplete
+                break
+            if timeout > 0 and (time.monotonic() - started) >= timeout:
+                raise api_client.CliError(f"traces follow: {trace_id} still in progress after {timeout:g}s")
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        # tail -f semantics: Ctrl-C is a normal stop, not an error.
+        return None
+    # Human view closes with the full tree once the trace settles.
+    if as_human and settled:
+        print(trace_render.render_tree(trace, spans, color=color))
+    return None

cmpnd-0.5.0/cmpnd/cli/trace_render.py

@@ -0,0 +1,352 @@
+"""Render a trace's span forest as a tree or an ASCII timeline.
+
+Consumed by ``cmpnd traces show <id>`` (CMP-260). The raw
+``GET /api/v1/traces/{id}`` response — ``{"trace": {...}, "spans": [...]}``
+with flat, raw-column-named spans — is turned into something readable when the
+caller opts into ``--tree`` / ``--timeline`` (``show`` is JSON by default, like
+``traces search``).
+
+The span-type labels and duration strings mirror serve's trace views verbatim
+— ``spanLabel`` and ``DurationClock`` in
+``serve/internal/web/views/traces.templ`` /
+``serve/internal/platform/displayfmt`` — so the CLI and the web UI print the
+same words for the same span. Structure is carried by indentation +
+box-drawing glyphs (UTF-8 output is assumed).
+
+Color: the **tree** view tints for readability, gated on a TTY without
+``NO_COLOR`` (the CLI convention shared with ``cli/commands/top.py``) so a
+pipe/file/CI gets clean plain text. The timeline is always plain — its bars
+already carry the signal.
+"""
+
+from __future__ import annotations
+
+import datetime
+import os
+import re
+import sys
+from typing import Any, TextIO
+
+# --- color (tree only; TTY + no NO_COLOR) --------------------------------
+
+_ANSI = {
+    "reset": "\x1b[0m",
+    "bold": "\x1b[1m",
+    "dim": "\x1b[2m",
+    "red": "\x1b[31m",
+    "green": "\x1b[32m",
+    "yellow": "\x1b[33m",
+    "grey": "\x1b[90m",
+}
+
+
+def use_color(stream: TextIO | None = None) -> bool:
+    """Color only when writing to a TTY and NO_COLOR is unset
+    (https://no-color.org) — same gate as cli/commands/top.py."""
+    stream = stream or sys.stdout
+    isatty = getattr(stream, "isatty", None)
+    return bool(isatty and isatty()) and os.environ.get("NO_COLOR") is None
+
+
+def _paint(text: str, color: str, enabled: bool) -> str:
+    if not enabled or not color:
+        return text
+    return f"{_ANSI[color]}{text}{_ANSI['reset']}"
+
+
+def _status_color(status: Any) -> str:
+    s = str(status or "").lower()
+    if s == "error":
+        return "red"
+    if s in ("incomplete", "in_progress"):
+        return "yellow"
+    return "green"
+
+
+# --- serve string parity -------------------------------------------------
+
+# Span-type → display label, verbatim from serve's spanLabel
+# (serve/internal/web/views/traces.templ). An unmapped type (e.g. "rlm")
+# falls through to itself, matching serve.
+_SPAN_LABELS = {
+    "predict": "Predict",
+    "lm_call": "LM Call",
+    "adapter_format": "Format",
+    "adapter_parse": "Parse",
+    "module": "Module",
+    "retrieve": "Retrieve",
+    "tool": "Tool",
+    "chain_of_thought": "Chain of Thought",
+    "react": "ReAct",
+    "program_of_thought": "Program of Thought",
+    "subcall": "Subcall",
+}
+
+
+def span_label(span_type: Any) -> str:
+    st = str(span_type or "")
+    return _SPAN_LABELS.get(st, st)
+
+
+def duration_clock(ns: Any) -> str:
+    """Nanoseconds → serve's DurationClock string: ``3.0s`` / ``0.0s`` /
+    ``1:05.8s`` / ``1:02:03.4s``. Ported byte-for-byte from
+    serve/internal/platform/displayfmt/displayfmt.go so the CLI matches the
+    web timeline exactly (including ``0.0s`` for a zero-duration span)."""
+    try:
+        n = int(ns)
+    except (TypeError, ValueError):
+        n = 0
+    if n < 0:
+        n = 0
+    ns_per_tenth = 100_000_000  # 100ms
+    total_tenths = (n + ns_per_tenth // 2) // ns_per_tenth
+    tenth = total_tenths % 10
+    total_sec = total_tenths // 10
+    sec = total_sec % 60
+    total_min = total_sec // 60
+    minute = total_min % 60
+    hr = total_min // 60
+    if hr > 0:
+        return f"{hr}:{minute:02d}:{sec:02d}.{tenth}s"
+    if minute > 0:
+        return f"{minute}:{sec:02d}.{tenth}s"
+    return f"{sec}.{tenth}s"
+
+
+# --- span forest ---------------------------------------------------------
+
+
+class Node:
+    """A span plus its ordered children in the reconstructed forest."""
+
+    __slots__ = ("span", "children")
+
+    def __init__(self, span: dict[str, Any]) -> None:
+        self.span = span
+        self.children: list[Node] = []
+
+
+def build_forest(spans: list[dict[str, Any]]) -> list[Node]:
+    """Group flat spans into a parent→child forest, children ordered by
+    start_time (span_id as a stable tiebreak).
+
+    A span whose parent_span_id is null/missing, or points at a span not in
+    this set (an orphan — e.g. a mid-run RLM trace whose parent lands last),
+    is treated as a root, so no span is ever dropped. A parent cycle can't
+    wedge the walk: each span is attached at most once.
+    """
+    nodes: dict[str, Node] = {}
+    for s in spans:
+        sid = str(s.get("span_id") or "")
+        if sid:
+            nodes[sid] = Node(s)
+
+    def _would_cycle(node: Node, parent: Node) -> bool:
+        # Attaching node under parent would close a cycle if node is already an
+        # ancestor of parent (walking parent's parent_span_id chain), or that
+        # chain itself already loops. Keep node a root in either case so the
+        # children graph stays acyclic — otherwise a mutual/reachable cycle
+        # yields an empty tree or unbounded _sort/walk recursion (Greptile P1).
+        seen: set[str] = set()
+        cur: Node | None = parent
+        while cur is not None:
+            if cur is node:
+                return True
+            csid = str(cur.span.get("span_id") or "")
+            if csid in seen:
+                return True
+            seen.add(csid)
+            pid = cur.span.get("parent_span_id")
+            cur = nodes.get(str(pid)) if pid else None
+        return False
+
+    roots: list[Node] = []
+    for s in spans:
+        sid = str(s.get("span_id") or "")
+        node = nodes.get(sid)
+        if node is None:
+            continue
+        parent_id = s.get("parent_span_id")
+        parent = nodes.get(str(parent_id)) if parent_id else None
+        if parent is not None and parent is not node and not _would_cycle(node, parent):
+            parent.children.append(node)
+        else:
+            roots.append(node)
+
+    def _sort_key(n: Node) -> tuple[str, str]:
+        return (str(n.span.get("start_time") or ""), str(n.span.get("span_id") or ""))
+
+    def _sort(node_list: list[Node]) -> None:
+        node_list.sort(key=_sort_key)
+        for n in node_list:
+            _sort(n.children)
+
+    _sort(roots)
+    return roots
+
+
+# --- helpers -------------------------------------------------------------
+
+_TS_RE = re.compile(r"^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(\.\d+)?(Z|[+-]\d{2}:?\d{2})?$")
+
+
+def _parse_ts(value: Any) -> datetime.datetime | None:
+    """Parse an RFC3339 timestamp tolerantly. Server emits nanosecond (9-digit)
+    fractions that datetime.fromisoformat rejects, so truncate the fraction to
+    microseconds and normalize a trailing Z. Returns None on anything unparsable
+    — the caller degrades (offset 0) rather than crashing."""
+    if not isinstance(value, str):
+        return None
+    m = _TS_RE.match(value.strip())
+    if not m:
+        return None
+    base, frac, tz = m.group(1), m.group(2), m.group(3)
+    micros = ""
+    if frac:
+        micros = "." + frac[1:7].ljust(6, "0")
+    if tz in (None, "Z"):
+        tz = "+00:00"
+    elif len(tz) == 5:  # +0000 → +00:00
+        tz = tz[:3] + ":" + tz[3:]
+    try:
+        return datetime.datetime.fromisoformat(f"{base}{micros}{tz}")
+    except ValueError:
+        return None
+
+
+def _int(v: Any) -> int:
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _header(trace: dict[str, Any], span_total: int, color: bool) -> str:
+    program = trace.get("program_name") or trace.get("signature_name") or "trace"
+    tid = str(trace.get("trace_id") or "")
+    status = trace.get("status")
+    meta = [
+        _paint(str(status or "—"), _status_color(status), color),
+        duration_clock(trace.get("duration_ns")),
+        f"{span_total} spans",
+    ]
+    if _int(trace.get("total_tokens")) > 0:
+        meta.append(f"{_int(trace.get('total_tokens'))} tokens")
+    line1 = (_paint(str(program), "bold", color) + "  " + _paint(tid, "grey", color)).rstrip()
+    return line1 + "\n" + " · ".join(meta)
+
+
+def span_line(span: dict[str, Any], *, color: bool) -> str:
+    """One span rendered as a single line: '<type label>  <name> · <duration> ·
+    <tokens> · <model>', mirroring serve's span-badge + span-name, then the same
+    duration string. Used both as a tree node body and as `traces follow`'s
+    per-span line (CMP-258)."""
+    # Two visually distinct segments: the span-type label carries the status
+    # hue (green/red/yellow), the span name is bold default-foreground. Bold on
+    # the terminal's own fg reads on any background; the two never share a color.
+    label = span_label(span.get("span_type"))
+    name = str(span.get("name") or "")
+    label_c = _paint(label, _status_color(span.get("status")), color)
+    if label and name and name != label:
+        head = label_c + "  " + _paint(name, "bold", color)
+    elif label:
+        head = label_c
+    elif name:
+        head = _paint(name, "bold", color)
+    else:
+        head = "span"
+
+    meta = [duration_clock(span.get("duration_ns"))]
+    if _int(span.get("total_tokens")) > 0:
+        meta.append(f"{_int(span.get('total_tokens'))} tokens")
+    model = span.get("model_name")
+    if model:
+        meta.append(str(model))
+    line = head + "  " + _paint("· " + " · ".join(meta), "dim", color)
+    err = span.get("error_message")
+    if err:
+        line += "  " + _paint(f"! {err}", "red", color)
+    return line
+
+
+# --- tree ----------------------------------------------------------------
+
+
+def render_tree(trace: dict[str, Any], spans: list[dict[str, Any]], *, color: bool) -> str:
+    """Header + an indented span tree; box-drawing glyphs carry the structure,
+    color (when enabled) tints for readability only."""
+    roots = build_forest(spans)
+    lines = [_header(trace, len(spans), color)]
+    if not spans:
+        lines.append("(no spans yet)")
+        return "\n".join(lines)
+
+    def walk(node: Node, prefix: str, is_last: bool, is_root: bool) -> None:
+        connector = "" if is_root else ("└─ " if is_last else "├─ ")
+        child_prefix = "" if is_root else prefix + ("   " if is_last else "│  ")
+        lines.append(prefix + _paint(connector, "grey", color) + span_line(node.span, color=color))
+        for i, child in enumerate(node.children):
+            walk(child, child_prefix, i == len(node.children) - 1, False)
+
+    for i, root in enumerate(roots):
+        walk(root, "", i == len(roots) - 1, True)
+    return "\n".join(lines)
+
+
+# --- timeline (always plain) ---------------------------------------------
+
+_BAR_WIDTH = 40
+
+
+def render_timeline(trace: dict[str, Any], spans: list[dict[str, Any]], *, color: bool) -> str:
+    """A gantt-style timeline mirroring serve's Timeline view: each span a row
+    with a right-aligned type label, a bar offset + scaled to the trace window,
+    and the DurationClock duration right-aligned in its own column (like the UI).
+    Uses the tree's color choices for the label (status hue) and duration
+    (dimmed); the bars stay the terminal's default foreground (neutral — reads
+    black on a light theme, white on a dark one — status-green on every bar
+    looked bad). Spans are flattened and ordered by start time so the time axis
+    reads top-to-bottom."""
+    lines = [_header(trace, len(spans), color)]
+    if not spans:
+        lines.append("(no spans yet)")
+        return "\n".join(lines)
+
+    parsed = [(_parse_ts(s.get("start_time")), s) for s in spans]
+    parsed_ok = [(t, s) for t, s in parsed if t is not None]
+    # Timestamped spans first (in time order), then any with a missing/malformed
+    # start_time appended at offset 0 — degrade, never drop a span (Greptile P1).
+    ordered = [s for _, s in sorted(parsed_ok, key=lambda p: p[0])]
+    ordered.extend(s for t, s in parsed if t is None)
+    t0 = min((t for t, _ in parsed_ok), default=None)
+
+    def _end_offset_s(span: dict[str, Any]) -> float:
+        start = _parse_ts(span.get("start_time"))
+        if start is None or t0 is None:
+            return _int(span.get("duration_ns")) / 1e9
+        return (start - t0).total_seconds() + _int(span.get("duration_ns")) / 1e9
+
+    window = max((_end_offset_s(s) for s in spans), default=0.0)
+    if window <= 0:
+        window = 1.0  # avoid divide-by-zero; every bar renders at column 0
+
+    label_w = min(18, max((len(span_label(s.get("span_type"))) for s in ordered), default=0))
+    # Right-align the duration column (UI parity): pad every value to the widest.
+    durs = {id(s): duration_clock(s.get("duration_ns")) for s in ordered}
+    dur_w = max((len(v) for v in durs.values()), default=0)
+
+    for s in ordered:
+        start = _parse_ts(s.get("start_time"))
+        dur_s = _int(s.get("duration_ns")) / 1e9
+        offset_s = (start - t0).total_seconds() if (start is not None and t0 is not None) else 0.0
+        start_col = min(int((offset_s / window) * _BAR_WIDTH), _BAR_WIDTH - 1)
+        bar_len = min(max(1, int((dur_s / window) * _BAR_WIDTH)), _BAR_WIDTH - start_col)
+        hue = _status_color(s.get("status"))
+        # rjust/ljust on the plain text FIRST, then paint — escape codes must
+        # not count toward column width. The bar is left unpainted (neutral fg).
+        label = _paint(span_label(s.get("span_type"))[:label_w].rjust(label_w), hue, color)
+        track = (" " * start_col + "█" * bar_len).ljust(_BAR_WIDTH)
+        dur = _paint(durs[id(s)].rjust(dur_w), "dim", color)
+        lines.append(f"{label}   │ {track} │   {dur}")
+    return "\n".join(lines)

{cmpnd-0.4.3 → cmpnd-0.5.0}/cmpnd/configuration.py

@@ -78,6 +78,14 @@ class Config:
     max_queue_size: int = 10000
     max_export_workers: int = 4
 
+    # Emit an in_progress trace_start for every root trace (CMP-257), not just
+    # RLM, so non-RLM programs (Predict/ReAct/CoT/optimizer students) are
+    # visible while running instead of appearing only at finalize. The exporter
+    # coalesces start + batch in one flush, so a fast trace still pays a single
+    # insert. Set False to opt out of the extra start (traces then reappear only
+    # at finalize, the pre-CMP-257 behavior).
+    stream_trace_starts: bool = True
+
     # Feature flags
     capture_inputs: bool = True
     capture_outputs: bool = True

{cmpnd-0.4.3 → cmpnd-0.5.0}/cmpnd/exporter.py

@@ -495,6 +495,17 @@ class BatchExporter:
                     new_spans[trace_id] = []
                 new_spans[trace_id].append(span_dict)
 
+        # Coalesce start + batch within one flush (CMP-257): if a trace's full
+        # batch trace is in this same flush, sending it upserts the row to its
+        # final status directly (serve traceUpsertSQL, ON CONFLICT on
+        # org_id,trace_id,start_time), so the in_progress start POST is
+        # redundant — drop it to save the round-trip for a fast trace. A start
+        # whose finalize lands in a LATER flush still ships, which is the whole
+        # point: the trace is visible while it runs.
+        if trace_starts and traces_to_send:
+            batched_ids = {str(t.get("trace_id")) for t in traces_to_send}
+            trace_starts = [pair for pair in trace_starts if pair[0] not in batched_ids]
+
         # Add new spans to pending buffer
         with self._pending_spans_lock:
             for trace_id, spans in new_spans.items():

{cmpnd-0.4.3 → cmpnd-0.5.0}/docs/sdk-instrumentation.md

@@ -149,6 +149,17 @@ Override any of these by passing kwargs to `cmpnd.configure(...)`.
 
 A span can arrive at `_flush_batch` before its parent trace has been exported — this happens whenever the exporter ticks in the middle of a DSPy call. The exporter holds those loose spans in `self._pending_spans` (`exporter.py:65`) keyed by `trace_id`, and when the trace finally arrives it attaches the buffered spans before shipping. Spans for which the trace never arrives get flushed as a bare spans batch via `/api/v1/traces/:id/spans` — see `_send_spans` at `exporter.py:431`.
 
+### In-progress trace starts (CMP-257)
+
+`on_module_start` emits a `trace_start` for **every** root trace (gated by `Config.stream_trace_starts`, default `True`), not just streaming (RLM) traces. This writes an `in_progress` placeholder row the moment a program starts, so a non-RLM program (Predict / ChainOfThought / ReAct / optimizer students) is visible while it runs — `cmpnd traces search --status in_progress` returns it and it has a lookupable id — instead of appearing only at finalize.
+
+`trace.streaming` (set only for RLM) is a separate axis: it still governs whether individual spans stream (`export_span`) and whether finalize goes through `/finalize` (streaming) vs a bundled `export_trace` (batch). CMP-257 generalized only the start emission, not the whole streaming model.
+
+Two things keep the extra start cheap and correct:
+
+- **Upsert, not duplicate.** The batch finalize (`export_trace`) and the start write the same row: serve's `traceUpsertSQL` keys `ON CONFLICT (org_id, trace_id, start_time)`, and the SDK's `start_time` is immutable across a trace's life, so the batch overwrites the `in_progress` row with the final status. A trace that never finalizes (crash / cancel) correctly stays `in_progress`.
+- **Coalescing.** When a trace's `trace_start` and its full batch `trace` land in the **same** flush, `_flush_batch` drops the redundant `/start` POST (the batch upserts the final row directly), so a fast trace pays one insert, not two. A start whose finalize lands in a later flush still ships — that visibility is the point. Set `stream_trace_starts=False` to opt out entirely (traces then reappear only at finalize, the pre-CMP-257 behavior).
+
 ---
 
 ## Dataset capture sidecar
@@ -184,7 +195,7 @@ The exporter POSTs to a handful of endpoints, all under `/api/v1/` on the cmpnd-
 - `POST /api/v1/traces` — single trace with bundled spans.
 - `POST /api/v1/traces/batch` — multiple traces with bundled spans, used whenever a flush contains more than one trace (`exporter.py:391`).
 - `POST /api/v1/traces/:id/spans` — loose spans whose trace was exported earlier.
-- `POST /api/v1/traces/:id/start` and `/finalize` — two-tier ingestion for long-running traces.
+- `POST /api/v1/traces/:id/start` and `/finalize` — two-tier ingestion. `/start` writes an `in_progress` placeholder row; `/finalize` closes a streaming (RLM) trace.
 - `POST /api/v1/eval_runs`, `POST /api/v1/optimization_runs`, and related progress endpoints.
 
 The trace payload is built in `python-sdk/cmpnd/models.py` by `TraceBuilder.to_api_dict()` (`models.py:398`) and `SpanBuilder.to_api_dict()` (`models.py:300`). A span's dict looks roughly like this, with every field mirrored verbatim to the Postgres `spans` schema documented in [`serve/DB.md`](../../serve/DB.md) ("Analytics tables"):

{cmpnd-0.4.3 → cmpnd-0.5.0}/pyproject.toml

@@ -5,7 +5,7 @@ name = "cmpnd"
 # it's new) — no git tags. Bump with `uv version --bump {minor,patch}` or by
 # hand. Runtime `cmpnd.__version__` reads installed metadata, so it tracks
 # this automatically. See docs/plans/2026-07-02-sdk-pypi-tag-free-publish.md.
-version = "0.4.3"
+version = "0.5.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"