jumpstart-mode 1.1.13 → 1.1.14

package/copilot-observability/scripts/ingest_otel.py

@@ -0,0 +1,394 @@
+#!/usr/bin/env python3
+"""Ingest VS Code Copilot Chat OpenTelemetry JSONL into SQLite."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sqlite3
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+from rebuild_daily_usage import rebuild_daily_usage
+from redact import load_rules, redact_text
+
+ROOT_DIR = SCRIPT_DIR.parent
+DEFAULT_SCHEMA = ROOT_DIR / "sql" / "schema.sql"
+DEFAULT_REDACTIONS = ROOT_DIR / "config" / "redaction-rules.yml"
+
+ATTRIBUTE_KEYS = {
+    "session": ["session.id", "copilot.session.id", "conversation.id", "chat.session.id", "request.session_id"],
+    "workspace": ["workspace", "workspace.name", "vscode.workspace.name", "repository.name", "repo.name"],
+    "repo_path": ["repo.path", "repository.path", "workspace.folder", "cwd", "process.cwd"],
+    "model": ["gen_ai.request.model", "gen_ai.response.model", "llm.model_name", "model", "ai.model"],
+    "provider": ["gen_ai.system", "llm.provider", "provider", "ai.provider"],
+    "input_tokens": ["gen_ai.usage.input_tokens", "llm.usage.prompt_tokens", "input_tokens", "prompt_tokens"],
+    "output_tokens": ["gen_ai.usage.output_tokens", "llm.usage.completion_tokens", "output_tokens", "completion_tokens"],
+    "cached_tokens": ["gen_ai.usage.cached_tokens", "cached_tokens", "cache_read_input_tokens"],
+    "prompt": ["gen_ai.prompt", "prompt", "user.prompt", "input", "input.value", "request.prompt"],
+    "response": ["gen_ai.completion", "completion", "response", "response.text", "output", "output.value"],
+    "tool_name": ["tool.name", "gen_ai.tool.name", "function.name", "command", "tool"],
+    "tool_input": ["tool.input", "function.arguments", "command.arguments", "input.summary"],
+    "tool_output": ["tool.output", "output.summary", "result", "result.summary"],
+    "status": ["status", "otel.status_code", "span.status", "error.type"],
+    "mode": ["copilot.mode", "chat.mode", "interaction.mode", "mode"],
+}
+
+
+def init_db(db_path: str | Path, schema_path: str | Path = DEFAULT_SCHEMA) -> None:
+    Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(db_path)
+    conn.execute("PRAGMA foreign_keys = ON")
+    try:
+        conn.executescript(Path(schema_path).read_text(encoding="utf-8"))
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def value_from_otel(value: Any) -> Any:
+    if isinstance(value, dict):
+        for key in ("stringValue", "intValue", "doubleValue", "boolValue"):
+            if key in value:
+                return value[key]
+        if "arrayValue" in value:
+            return value["arrayValue"].get("values", [])
+        if "kvlistValue" in value:
+            return attrs_to_dict(value["kvlistValue"].get("values", []))
+    return value
+
+
+def attrs_to_dict(attributes: Any) -> dict[str, Any]:
+    if isinstance(attributes, dict):
+        return {str(k): value_from_otel(v) for k, v in attributes.items()}
+    result: dict[str, Any] = {}
+    for item in attributes or []:
+        if isinstance(item, dict) and "key" in item:
+            result[str(item["key"])] = value_from_otel(item.get("value"))
+    return result
+
+
+def pick(attrs: dict[str, Any], candidates: Iterable[str]) -> Any:
+    lower = {key.lower(): key for key in attrs}
+    for candidate in candidates:
+        if candidate in attrs:
+            return attrs[candidate]
+        found = lower.get(candidate.lower())
+        if found:
+            return attrs[found]
+    for candidate in candidates:
+        candidate_lower = candidate.lower()
+        for key, value in attrs.items():
+            if key.lower().endswith(candidate_lower):
+                return value
+    return None
+
+
+def to_int(value: Any) -> int:
+    try:
+        if value is None or value == "":
+            return 0
+        return int(float(value))
+    except (TypeError, ValueError):
+        return 0
+
+
+def iso_from_nanos(value: Any) -> str | None:
+    number = to_int(value)
+    if not number:
+        return None
+    return datetime.fromtimestamp(number / 1_000_000_000, tz=timezone.utc).isoformat()
+
+
+def normalize_timestamp(record: dict[str, Any]) -> str:
+    for key in ("timestamp", "time", "timeUnixNano", "startTimeUnixNano", "observedTimeUnixNano"):
+        value = record.get(key)
+        if not value:
+            continue
+        if str(value).isdigit() and len(str(value)) > 12:
+            converted = iso_from_nanos(value)
+            if converted:
+                return converted
+        try:
+            return datetime.fromisoformat(str(value).replace("Z", "+00:00")).isoformat()
+        except ValueError:
+            continue
+    return datetime.now(timezone.utc).isoformat()
+
+
+def duration_ms(span: dict[str, Any], attrs: dict[str, Any]) -> int:
+    direct = pick(attrs, ["duration_ms", "duration.ms", "elapsed_ms"])
+    if direct is not None:
+        return to_int(direct)
+    start = to_int(span.get("startTimeUnixNano"))
+    end = to_int(span.get("endTimeUnixNano"))
+    if start and end and end >= start:
+        return int((end - start) / 1_000_000)
+    return 0
+
+
+def stable_id(*parts: Any) -> str:
+    joined = "|".join(str(part or "") for part in parts)
+    return hashlib.sha256(joined.encode("utf-8")).hexdigest()
+
+
+def text_hash(value: str | None) -> str | None:
+    if not value:
+        return None
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def classify_mode(name: str, attrs: dict[str, Any]) -> str:
+    explicit = pick(attrs, ATTRIBUTE_KEYS["mode"])
+    if explicit:
+        value = str(explicit).lower()
+    else:
+        value = " ".join([name, json.dumps(attrs, default=str)[:500]]).lower()
+    for mode in ("agent", "edit", "plan", "ask"):
+        if mode in value:
+            return mode
+    return "unknown"
+
+
+def normalize_status(span: dict[str, Any], attrs: dict[str, Any]) -> str:
+    status = pick(attrs, ATTRIBUTE_KEYS["status"])
+    if not status and isinstance(span.get("status"), dict):
+        status = span["status"].get("code") or span["status"].get("message")
+    value = str(status or "success").lower()
+    if "error" in value or "fail" in value:
+        return "error"
+    if "interrupt" in value or "cancel" in value:
+        return "interrupted"
+    return "success"
+
+
+def is_llm_span(name: str, attrs: dict[str, Any]) -> bool:
+    haystack = " ".join([name, " ".join(attrs.keys())]).lower()
+    return any(term in haystack for term in ("llm", "chat", "completion", "gen_ai", "model")) or bool(pick(attrs, ATTRIBUTE_KEYS["model"]))
+
+
+def is_tool_span(name: str, attrs: dict[str, Any]) -> bool:
+    haystack = " ".join([name, " ".join(attrs.keys())]).lower()
+    return "tool" in haystack or "function" in haystack or bool(pick(attrs, ATTRIBUTE_KEYS["tool_name"]))
+
+
+def iter_spans(payload: dict[str, Any]) -> Iterable[tuple[dict[str, Any], dict[str, Any]]]:
+    if "resourceSpans" not in payload:
+        yield payload, {}
+        return
+    for resource_span in payload.get("resourceSpans", []):
+        resource_attrs = attrs_to_dict(resource_span.get("resource", {}).get("attributes", []))
+        for scope_span in resource_span.get("scopeSpans", []) + resource_span.get("instrumentationLibrarySpans", []):
+            scope_attrs = attrs_to_dict(scope_span.get("scope", {}).get("attributes", []))
+            for span in scope_span.get("spans", []):
+                yield span, {**resource_attrs, **scope_attrs}
+
+
+def ensure_session(conn: sqlite3.Connection, session: dict[str, Any]) -> None:
+    conn.execute(
+        """
+        INSERT INTO sessions (session_id, trace_id, started_at, ended_at, workspace, repo_hash, mode, primary_model, status)
+        VALUES (:session_id, :trace_id, :started_at, :ended_at, :workspace, :repo_hash, :mode, :primary_model, :status)
+        ON CONFLICT(session_id) DO UPDATE SET
+            started_at = MIN(COALESCE(started_at, excluded.started_at), excluded.started_at),
+            ended_at = MAX(COALESCE(ended_at, excluded.ended_at), excluded.ended_at),
+            workspace = COALESCE(NULLIF(excluded.workspace, 'unknown'), workspace, excluded.workspace),
+            repo_hash = COALESCE(excluded.repo_hash, repo_hash),
+            mode = CASE WHEN mode = 'unknown' THEN excluded.mode ELSE mode END,
+            primary_model = COALESCE(NULLIF(excluded.primary_model, 'unknown'), primary_model, excluded.primary_model),
+            status = CASE WHEN excluded.status = 'error' THEN 'error' ELSE COALESCE(status, excluded.status) END
+        """,
+        session,
+    )
+
+
+def recompute_sessions(conn: sqlite3.Connection) -> None:
+    conn.executescript(
+        """
+        UPDATE sessions
+        SET
+            total_input_tokens = COALESCE((SELECT SUM(input_tokens) FROM llm_calls WHERE llm_calls.session_id = sessions.session_id), 0),
+            total_output_tokens = COALESCE((SELECT SUM(output_tokens) FROM llm_calls WHERE llm_calls.session_id = sessions.session_id), 0),
+            total_cached_tokens = COALESCE((SELECT SUM(cached_tokens) FROM llm_calls WHERE llm_calls.session_id = sessions.session_id), 0),
+            total_duration_ms = COALESCE((SELECT SUM(duration_ms) FROM llm_calls WHERE llm_calls.session_id = sessions.session_id), 0)
+                + COALESCE((SELECT SUM(duration_ms) FROM tool_calls WHERE tool_calls.session_id = sessions.session_id), 0),
+            prompt_count = COALESCE((SELECT COUNT(*) FROM messages WHERE messages.session_id = sessions.session_id AND role = 'user'), 0),
+            tool_call_count = COALESCE((SELECT COUNT(*) FROM tool_calls WHERE tool_calls.session_id = sessions.session_id), 0),
+            error_count = COALESCE((SELECT COUNT(*) FROM llm_calls WHERE llm_calls.session_id = sessions.session_id AND status = 'error'), 0)
+                + COALESCE((SELECT COUNT(*) FROM tool_calls WHERE tool_calls.session_id = sessions.session_id AND status = 'error'), 0),
+            primary_model = COALESCE((
+                SELECT model FROM llm_calls
+                WHERE llm_calls.session_id = sessions.session_id AND model IS NOT NULL AND model != 'unknown'
+                GROUP BY model ORDER BY COUNT(*) DESC LIMIT 1
+            ), primary_model)
+        """
+    )
+
+
+def ingest_file(input_path: str | Path, db_path: str | Path, redaction_config: str | Path = DEFAULT_REDACTIONS) -> int:
+    init_db(db_path)
+    rules = load_rules(redaction_config)
+    conn = sqlite3.connect(db_path)
+    conn.execute("PRAGMA foreign_keys = ON")
+    ingested = 0
+    try:
+        with Path(input_path).open("r", encoding="utf-8") as handle:
+            for line_number, line in enumerate(handle, start=1):
+                if not line.strip():
+                    continue
+                try:
+                    payload = json.loads(line)
+                except json.JSONDecodeError as exc:
+                    print(f"Skipping invalid JSON on line {line_number}: {exc}", file=sys.stderr)
+                    continue
+                for span, inherited_attrs in iter_spans(payload):
+                    span_attrs = attrs_to_dict(span.get("attributes", {}))
+                    attrs = {**inherited_attrs, **span_attrs}
+                    name = str(span.get("name") or attrs.get("name") or payload.get("name") or "unknown")
+                    trace_id = str(span.get("traceId") or span.get("trace_id") or attrs.get("trace_id") or stable_id(input_path, line_number))
+                    span_id = str(span.get("spanId") or span.get("span_id") or attrs.get("span_id") or stable_id(trace_id, line_number, name))
+                    timestamp = normalize_timestamp(span)
+                    ended_at = normalize_timestamp({"timestamp": span.get("endTimeUnixNano") or span.get("timestamp") or timestamp})
+                    session_id = str(pick(attrs, ATTRIBUTE_KEYS["session"]) or trace_id)
+                    workspace = str(pick(attrs, ATTRIBUTE_KEYS["workspace"]) or "unknown")
+                    repo_path = pick(attrs, ATTRIBUTE_KEYS["repo_path"])
+                    repo_hash = stable_id(repo_path) if repo_path else None
+                    mode = classify_mode(name, attrs)
+                    model = str(pick(attrs, ATTRIBUTE_KEYS["model"]) or "unknown")
+                    provider = str(pick(attrs, ATTRIBUTE_KEYS["provider"]) or "unknown")
+                    status = normalize_status(span, attrs)
+                    duration = duration_ms(span, attrs)
+
+                    ensure_session(
+                        conn,
+                        {
+                            "session_id": session_id,
+                            "trace_id": trace_id,
+                            "started_at": timestamp,
+                            "ended_at": ended_at,
+                            "workspace": workspace,
+                            "repo_hash": repo_hash,
+                            "mode": mode,
+                            "primary_model": model,
+                            "status": status,
+                        },
+                    )
+
+                    tool_like = is_tool_span(name, attrs)
+                    llm_like = is_llm_span(name, attrs)
+                    prompt = pick(attrs, ATTRIBUTE_KEYS["prompt"])
+                    if prompt and not tool_like:
+                        content, redacted = redact_text(str(prompt), rules)
+                        conn.execute(
+                            """
+                            INSERT INTO messages
+                            (message_id, session_id, timestamp, role, content, content_hash, token_count, redacted)
+                            VALUES (?, ?, ?, 'user', ?, ?, ?, ?)
+                            ON CONFLICT(message_id) DO UPDATE SET
+                                session_id = excluded.session_id,
+                                timestamp = excluded.timestamp,
+                                role = excluded.role,
+                                content = excluded.content,
+                                content_hash = excluded.content_hash,
+                                token_count = excluded.token_count,
+                                redacted = excluded.redacted
+                            """,
+                            (stable_id(span_id, "user"), session_id, timestamp, content, text_hash(content), to_int(pick(attrs, ATTRIBUTE_KEYS["input_tokens"])), int(redacted)),
+                        )
+                    response = pick(attrs, ATTRIBUTE_KEYS["response"])
+                    if response:
+                        content, redacted = redact_text(str(response), rules)
+                        conn.execute(
+                            """
+                            INSERT INTO messages
+                            (message_id, session_id, timestamp, role, content, content_hash, token_count, redacted)
+                            VALUES (?, ?, ?, 'assistant', ?, ?, ?, ?)
+                            ON CONFLICT(message_id) DO UPDATE SET
+                                session_id = excluded.session_id,
+                                timestamp = excluded.timestamp,
+                                role = excluded.role,
+                                content = excluded.content,
+                                content_hash = excluded.content_hash,
+                                token_count = excluded.token_count,
+                                redacted = excluded.redacted
+                            """,
+                            (stable_id(span_id, "assistant"), session_id, ended_at, content, text_hash(content), to_int(pick(attrs, ATTRIBUTE_KEYS["output_tokens"])), int(redacted)),
+                        )
+
+                    if llm_like:
+                        conn.execute(
+                            """
+                            INSERT INTO llm_calls
+                            (call_id, session_id, timestamp, model, provider, input_tokens, output_tokens, cached_tokens, duration_ms, status)
+                            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                            ON CONFLICT(call_id) DO UPDATE SET
+                                session_id = excluded.session_id,
+                                timestamp = excluded.timestamp,
+                                model = excluded.model,
+                                provider = excluded.provider,
+                                input_tokens = excluded.input_tokens,
+                                output_tokens = excluded.output_tokens,
+                                cached_tokens = excluded.cached_tokens,
+                                duration_ms = excluded.duration_ms,
+                                status = excluded.status
+                            """,
+                            (
+                                stable_id(span_id, "llm"), session_id, timestamp, model, provider,
+                                to_int(pick(attrs, ATTRIBUTE_KEYS["input_tokens"])),
+                                to_int(pick(attrs, ATTRIBUTE_KEYS["output_tokens"])),
+                                to_int(pick(attrs, ATTRIBUTE_KEYS["cached_tokens"])),
+                                duration, status,
+                            ),
+                        )
+                    if tool_like:
+                        redacted_input, _ = redact_text(str(pick(attrs, ATTRIBUTE_KEYS["tool_input"]) or ""), rules)
+                        redacted_output, _ = redact_text(str(pick(attrs, ATTRIBUTE_KEYS["tool_output"]) or ""), rules)
+                        conn.execute(
+                            """
+                            INSERT INTO tool_calls
+                            (tool_call_id, session_id, timestamp, tool_name, input_summary, output_summary, duration_ms, status)
+                            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                            ON CONFLICT(tool_call_id) DO UPDATE SET
+                                session_id = excluded.session_id,
+                                timestamp = excluded.timestamp,
+                                tool_name = excluded.tool_name,
+                                input_summary = excluded.input_summary,
+                                output_summary = excluded.output_summary,
+                                duration_ms = excluded.duration_ms,
+                                status = excluded.status
+                            """,
+                            (
+                                stable_id(span_id, "tool"), session_id, timestamp,
+                                str(pick(attrs, ATTRIBUTE_KEYS["tool_name"]) or name),
+                                redacted_input if redacted_input else None,
+                                redacted_output if redacted_output else None,
+                                duration, status,
+                            ),
+                        )
+                    ingested += 1
+        recompute_sessions(conn)
+        conn.commit()
+    finally:
+        conn.close()
+    rebuild_daily_usage(db_path)
+    return ingested
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Ingest Copilot OpenTelemetry JSONL into SQLite.")
+    parser.add_argument("--input", required=True, help="Path to copilot-otel.jsonl")
+    parser.add_argument("--db", required=True, help="Path to SQLite database")
+    parser.add_argument("--redactions", default=str(DEFAULT_REDACTIONS), help="Path to redaction-rules.yml")
+    args = parser.parse_args()
+    count = ingest_file(args.input, args.db, args.redactions)
+    print(f"Ingested {count} telemetry records into {args.db}")
+
+
+if __name__ == "__main__":
+    main()

package/copilot-observability/scripts/rate_session.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Apply a manual usefulness rating and outcome to a session."""
+from __future__ import annotations
+
+import argparse
+import sqlite3
+
+OUTCOMES = {
+    "Accepted as-is",
+    "Accepted with edits",
+    "Useful explanation",
+    "Wrong direction",
+    "Too verbose",
+    "Hallucinated",
+    "Failed tool execution",
+    "Security concern",
+    "Abandoned",
+}
+
+
+def rate_session(db_path: str, session_id: str, rating: int, outcome: str, notes: str = "") -> None:
+    if rating < 1 or rating > 5:
+        raise ValueError("rating must be between 1 and 5")
+    if outcome not in OUTCOMES:
+        raise ValueError(f"outcome must be one of: {', '.join(sorted(OUTCOMES))}")
+    conn = sqlite3.connect(db_path)
+    try:
+        cursor = conn.execute(
+            "UPDATE sessions SET usefulness_rating = ?, outcome = ?, notes = ? WHERE session_id = ?",
+            (rating, outcome, notes, session_id),
+        )
+        if cursor.rowcount == 0:
+            raise ValueError(f"session not found: {session_id}")
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Rate a Copilot session.")
+    parser.add_argument("--db", required=True)
+    parser.add_argument("--session-id", required=True)
+    parser.add_argument("--rating", type=int, required=True)
+    parser.add_argument("--outcome", required=True, choices=sorted(OUTCOMES))
+    parser.add_argument("--notes", default="")
+    args = parser.parse_args()
+    rate_session(args.db, args.session_id, args.rating, args.outcome, args.notes)
+    print(f"Updated rating for {args.session_id}")
+
+
+if __name__ == "__main__":
+    main()

package/copilot-observability/scripts/rebuild_daily_usage.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Rebuild pre-aggregated daily usage metrics."""
+from __future__ import annotations
+
+import argparse
+import sqlite3
+from pathlib import Path
+
+
+def rebuild_daily_usage(db_path: str | Path) -> None:
+    conn = sqlite3.connect(db_path)
+    conn.execute("PRAGMA foreign_keys = ON")
+    try:
+        conn.executescript(
+            """
+            DELETE FROM daily_usage;
+            INSERT INTO daily_usage (
+                usage_date, prompt_count, session_count, llm_call_count, tool_call_count,
+                input_tokens, output_tokens, cached_tokens, total_tokens, total_duration_ms, error_count
+            )
+            SELECT
+                day,
+                COALESCE(prompt_count, 0),
+                COALESCE(session_count, 0),
+                COALESCE(llm_call_count, 0),
+                COALESCE(tool_call_count, 0),
+                COALESCE(input_tokens, 0),
+                COALESCE(output_tokens, 0),
+                COALESCE(cached_tokens, 0),
+                COALESCE(input_tokens, 0) + COALESCE(output_tokens, 0) + COALESCE(cached_tokens, 0),
+                COALESCE(total_duration_ms, 0),
+                COALESCE(error_count, 0)
+            FROM (
+                SELECT date(started_at) AS day, COUNT(*) AS session_count,
+                       SUM(total_duration_ms) AS total_duration_ms,
+                       SUM(error_count) AS error_count
+                FROM sessions
+                WHERE started_at IS NOT NULL
+                GROUP BY date(started_at)
+            ) s
+            LEFT JOIN (
+                SELECT date(timestamp) AS message_day, COUNT(*) AS prompt_count
+                FROM messages
+                WHERE role = 'user'
+                GROUP BY date(timestamp)
+            ) m ON m.message_day = s.day
+            LEFT JOIN (
+                SELECT date(timestamp) AS llm_day, COUNT(*) AS llm_call_count,
+                       SUM(input_tokens) AS input_tokens,
+                       SUM(output_tokens) AS output_tokens,
+                       SUM(cached_tokens) AS cached_tokens
+                FROM llm_calls
+                GROUP BY date(timestamp)
+            ) l ON l.llm_day = s.day
+            LEFT JOIN (
+                SELECT date(timestamp) AS tool_day, COUNT(*) AS tool_call_count
+                FROM tool_calls
+                GROUP BY date(timestamp)
+            ) t ON t.tool_day = s.day;
+            """
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Rebuild daily_usage aggregates.")
+    parser.add_argument("--db", required=True)
+    args = parser.parse_args()
+    rebuild_daily_usage(args.db)
+
+
+if __name__ == "__main__":
+    main()

package/copilot-observability/scripts/redact.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Redaction helpers for Copilot OpenTelemetry ingestion."""
+from __future__ import annotations
+
+import argparse
+import ast
+import re
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover - fallback supports the bundled config shape
+    yaml = None
+
+
+@dataclass(frozen=True)
+class RedactionRule:
+    name: str
+    pattern: str
+    replacement: str
+
+
+def _fallback_yaml_rules(text: str) -> list[RedactionRule]:
+    rules: list[dict[str, str]] = []
+    current: dict[str, str] | None = None
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or line == "redactions:":
+            continue
+        if line.startswith("- name:"):
+            if current:
+                rules.append(current)
+            current = {"name": _parse_scalar(line.split(":", 1)[1].strip())}
+        elif current and ":" in line:
+            key, value = line.split(":", 1)
+            current[key.strip()] = _parse_scalar(value.strip())
+    if current:
+        rules.append(current)
+    return [RedactionRule(r["name"], r["pattern"], r["replacement"]) for r in rules]
+
+
+def _parse_scalar(value: str) -> str:
+    if len(value) >= 2 and value[0] in {"'", '"'} and value[-1] == value[0]:
+        try:
+            return str(ast.literal_eval(value))
+        except (SyntaxError, ValueError):
+            warnings.warn(
+                f"could not parse quoted redaction scalar {value!r}; using the unquoted value instead. Check YAML quoting and escape syntax.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+            return value[1:-1]
+    return value
+
+
+def load_rules(path: str | Path) -> list[RedactionRule]:
+    config_path = Path(path)
+    if not config_path.exists():
+        return []
+    text = config_path.read_text(encoding="utf-8")
+    if yaml:
+        data = yaml.safe_load(text) or {}
+        return [
+            RedactionRule(
+                name=str(item.get("name", "unnamed")),
+                pattern=str(item["pattern"]),
+                replacement=str(item.get("replacement", "[REDACTED]")),
+            )
+            for item in data.get("redactions", [])
+            if item.get("pattern")
+        ]
+    return _fallback_yaml_rules(text)
+
+
+def redact_text(value: str | None, rules: Iterable[RedactionRule]) -> tuple[str | None, bool]:
+    if value is None:
+        return None, False
+    redacted = value
+    applied = False
+    for rule in rules:
+        updated = re.sub(rule.pattern, rule.replacement, redacted)
+        if updated != redacted:
+            applied = True
+            redacted = updated
+    return redacted, applied
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Redact text using configured rules.")
+    parser.add_argument("--config", default="config/redaction-rules.yml")
+    parser.add_argument("text", nargs="?")
+    args = parser.parse_args()
+    rules = load_rules(args.config)
+    result, _ = redact_text(args.text or "", rules)
+    print(result or "")
+
+
+if __name__ == "__main__":
+    main()