feat(llm-obs): export annotated interaction data

Cargo.toml

@@ -28,6 +28,7 @@ native = [
     "dep:uuid",
     "dep:chrono",
     "dep:regex",
+    "dep:tempfile",
     "dep:clap",
     "dep:clap_complete",
     "tokio/full",
@@ -53,6 +54,7 @@ wasi = [
     "dep:uuid",
     "dep:chrono",
     "dep:regex",
+    "dep:tempfile",
     "dep:clap",
     "dep:clap_complete",
     "tokio/rt",
@@ -93,6 +95,7 @@ http = "1"
 
 # Error handling
 anyhow = "1"
+tempfile = { version = "3", optional = true }
 
 # POSIX shell word splitting (used for alias expansion)
 shell-words = "1"

docs/COMMANDS.md

@@ -66,7 +66,7 @@ pup <domain> <subgroup> <action> [options] # Nested commands
 | data-deletion | requests (list, create, cancel) | src/commands/data_deletion.rs | ✅ |
 | data-governance | scanner-rules (list) | src/commands/data_governance.rs | ✅ |
 | obs-pipelines | list, get, create, update, diff, delete, validate | src/commands/obs_pipelines.rs | ✅ |
-| llm-obs | projects (create, list), experiments (create, list, update, delete, summary, events (list, get, submit), metric-values, dimension-values), datasets (create, list, batch-update, clone, restore, records, records-add, records-all, records-full), spans (search), patterns (configs (list, get), runs (list, status), topics, topics-with-points, points), agent-insights (list, get, update-status, submit-feedback), annotation-queues (create, list, update, delete, interactions (add, delete, list), schema (get, update), annotations (upsert, delete)), model-pricing | src/commands/llm_obs.rs | ✅ |
+| llm-obs | projects (create, list), experiments (create, list, update, delete, summary, events (list, get, submit), metric-values, dimension-values), datasets (create, list, batch-update, clone, restore, records, records-add, records-all, records-full), spans (search), patterns (configs (list, get), runs (list, status), topics, topics-with-points, points), agent-insights (list, get, update-status, submit-feedback), annotations (export), annotation-queues (create, list, update, delete, interactions (add, delete, list), schema (get, update), annotations (upsert, delete)), model-pricing | src/commands/llm_obs.rs | ✅ |
 | reference-tables | list, get, create, batch-query | src/commands/reference_tables.rs | ✅ |
 | network | flows list, devices (list, get, interfaces, tags), interfaces (list, update) | src/commands/network.rs | ✅ |
 | cloud | aws, gcp, azure, oci | src/commands/cloud.rs | ✅ |
@@ -94,6 +94,18 @@ pup <domain> <subgroup> <action> [options] # Nested commands
 
 ## Common Patterns
 
+### Export an LLM Observability annotated interaction
+
+Export one annotation together with its complete interaction data. Event-backed interactions are fetched across every cursor page, while stored-content interactions retain their `content` payload. `--queue` accepts either the queue ID or its exact name. Without `--out`, the command uses Pup's standard output formatter (JSON by default) and honors global `--output` and `--jq` flags. File exports default to JSON; pass `--format jsonl` for JSONL. Existing files are not replaced unless `--force` is provided. Use repeatable `--header KEY:VALUE` / `-H KEY:VALUE` flags for request-routing headers such as Rapid test drives.
+
+```bash
+pup llm-obs annotations export \
+  --queue quality-review \
+  --interaction-id 23851556-a8c7-41c1-be75-03eb665a132f \
+  --format jsonl \
+  --out interaction.jsonl
+```
+
 ### List Operations
 ```bash
 pup <domain> list [--flags]

docs/EXAMPLES.md

@@ -26,6 +26,34 @@ export DD_APP_KEY="your-app-key"
 export DD_SITE="datadoghq.com"
 ```
 
+## LLM Observability
+
+### Export an Annotated Interaction
+```bash
+# Print the annotation and complete interaction data as JSON
+pup llm-obs annotations export \
+  --queue quality-review \
+  --interaction-id 23851556-a8c7-41c1-be75-03eb665a132f
+
+# Select part of the standard JSON output
+pup --jq '.interaction_data.events' llm-obs annotations export \
+  --queue 13851556-a8c7-41c1-be75-03eb665a132f \
+  --interaction-id 23851556-a8c7-41c1-be75-03eb665a132f
+
+# Write JSONL to a file; --force is required to replace an existing file
+pup llm-obs annotations export \
+  --queue quality-review \
+  --interaction-id 23851556-a8c7-41c1-be75-03eb665a132f \
+  --out interaction.jsonl \
+  --format jsonl
+
+# Route every queue lookup and pagination request through a Rapid test drive
+pup llm-obs annotations export \
+  --queue 13851556-a8c7-41c1-be75-03eb665a132f \
+  --interaction-id 23851556-a8c7-41c1-be75-03eb665a132f \
+  --header 'test-drive-scion-s60: 1'
+```
+
 ## Metrics
 
 ### List Metrics

skills/dd-pup/SKILL.md

@@ -249,6 +249,7 @@ pup llm-obs experiments update <experiment-id> --file experiment.json
 pup llm-obs experiments delete --file delete-request.json
 pup llm-obs datasets list --project-id <project-id>
 pup llm-obs datasets create --project-id <project-id> --file dataset.json
+pup llm-obs annotations export --queue <queue-id-or-name> --interaction-id <interaction-id>
 ```
 
 ### Reference Tables
@@ -324,4 +325,3 @@ pup auth status
 | EU1 | `datadoghq.eu` |
 | AP1 | `ap1.datadoghq.com` |
 | US1-FED | `ddog-gov.com` |
-

src/commands/api.rs

@@ -14,7 +14,7 @@ fn parse_kv(s: &str) -> Result<(String, String)> {
 }
 
 /// Parse `key:value` into (key, value). Splits on the first `:` only.
-fn parse_header_str(s: &str) -> Result<(String, String)> {
+pub(crate) fn parse_header_str(s: &str) -> Result<(String, String)> {
     let pos = s
         .find(':')
         .ok_or_else(|| anyhow::anyhow!("expected KEY:VALUE, got {s:?}"))?;