Consolidate trace tooling under traces package

README.md

@@ -139,15 +139,15 @@ the shard pending for a later retry and do not affect scam analysis.
 Operator commands:
 
 ```bash
-python scripts/seed_trace_dataset.py
-python scripts/validate_traces.py data/trace_samples.jsonl
-python scripts/create_trace_dataset.py --dry-run
-python scripts/create_trace_dataset.py
-python scripts/export_pending_traces.py --dry-run
-python scripts/upload_trace_shards.py --dry-run
+python -m traces.scripts.seed_trace_dataset
+python -m traces.scripts.validate_traces
+python -m traces.scripts.create_trace_dataset --dry-run
+python -m traces.scripts.create_trace_dataset
+python -m traces.scripts.export_pending_traces --dry-run
+python -m traces.scripts.upload_trace_shards --dry-run
 ```
 
-See [the dataset card](docs/trace_dataset_card.md) for the schema, privacy
+See [the dataset card](traces/dataset_card.md) for the schema, privacy
 policy, provenance, and limitations.
 
 ## Hugging Face Spaces
@@ -182,14 +182,17 @@ docs/
   model_experiment_notes.md
 data/
   example_assessments.json
-  trace_samples.jsonl
 traces/
-scripts/
-  create_trace_dataset.py
-  seed_trace_dataset.py
-  validate_traces.py
-  export_pending_traces.py
-  upload_trace_shards.py
+  runtime.py
+  dataset_card.md
+  data/
+    trace_samples.jsonl
+  scripts/
+    create_trace_dataset.py
+    seed_trace_dataset.py
+    validate_traces.py
+    export_pending_traces.py
+    upload_trace_shards.py
 static/
   index.html
   styles.css

app.py

@@ -15,7 +15,7 @@ from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
 from gradio import Server
 from openai import APIConnectionError, APIStatusError, APITimeoutError, OpenAI
-from trace_runtime import queue_trace, start_trace_worker, trace_status
+from traces.runtime import queue_trace, start_trace_worker, trace_status
 
 ROOT = Path(__file__).resolve().parent
 STATIC_DIR = ROOT / "static"

scripts/__init__.py

@@ -1 +0,0 @@
-"""Trace dataset administration scripts."""

tests/test_tracing.py

@@ -14,7 +14,7 @@ import httpx
 from openai import APIStatusError, APITimeoutError
 
 import app
-import trace_runtime
+from traces import runtime as trace_runtime
 
 
 class TraceTests(unittest.TestCase):
@@ -281,7 +281,7 @@ class TraceTests(unittest.TestCase):
         ), patch.dict("os.environ", {"HF_TOKEN": "test-token"}), patch(
             "huggingface_hub.HfApi.upload_file",
             side_effect=RuntimeError("offline"),
-        ), patch("trace_runtime.time.sleep"):
+        ), patch("traces.runtime.time.sleep"):
             publisher._persist_batch([self.sample_record()])
             publisher._upload_pending()
             self.assertEqual(len(list(Path(directory).glob("*.jsonl"))), 1)

traces/.gitkeep

@@ -1 +0,0 @@
-

traces/__init__.py

@@ -0,0 +1 @@
+"""Deterministic privacy-safe tracing for the application."""

trace_runtime.py → traces/runtime.py

@@ -13,7 +13,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-ROOT = Path(__file__).resolve().parent
+ROOT = Path(__file__).resolve().parents[1]
 TRACE_ROOT = Path(os.getenv("TRACE_DIR", ROOT / "traces"))
 PENDING_DIR = TRACE_ROOT / "pending"
 DATASET_REPO = os.getenv(

traces/scripts/__init__.py

@@ -0,0 +1 @@
+"""Trace dataset administration commands."""

{scripts → traces/scripts}/create_trace_dataset.py

@@ -8,7 +8,8 @@ from pathlib import Path
 
 from huggingface_hub import HfApi
 
-ROOT = Path(__file__).resolve().parents[1]
+ROOT = Path(__file__).resolve().parents[2]
+TRACE_DIR = Path(__file__).resolve().parents[1]
 DEFAULT_REPO = "build-small-hackathon/pakistan-notice-helper-traces"
 
 
@@ -21,8 +22,8 @@ def main() -> int:
     parser.add_argument("--dry-run", action="store_true")
     args = parser.parse_args()
     files = {
-        ROOT / "docs" / "trace_dataset_card.md": "README.md",
-        ROOT / "data" / "trace_samples.jsonl": "data/seed/trace_samples.jsonl",
+        TRACE_DIR / "dataset_card.md": "README.md",
+        TRACE_DIR / "data" / "trace_samples.jsonl": "data/seed/trace_samples.jsonl",
     }
     if args.dry_run:
         print(f"Would create public dataset: {args.repo_id}")

{scripts → traces/scripts}/export_pending_traces.py

@@ -7,10 +7,10 @@ import json
 import sys
 from pathlib import Path
 
-ROOT = Path(__file__).resolve().parents[1]
+ROOT = Path(__file__).resolve().parents[2]
 sys.path.insert(0, str(ROOT))
 
-from trace_runtime import PENDING_DIR, validate_trace
+from traces.runtime import PENDING_DIR, validate_trace
 
 
 def main() -> int:

{scripts → traces/scripts}/seed_trace_dataset.py

@@ -7,10 +7,11 @@ import json
 import sys
 from pathlib import Path
 
-ROOT = Path(__file__).resolve().parents[1]
+ROOT = Path(__file__).resolve().parents[2]
+TRACE_DIR = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(ROOT))
 
-from trace_runtime import PIPELINE_STEPS, build_trace_record, validate_trace
+from traces.runtime import PIPELINE_STEPS, build_trace_record, validate_trace
 
 TEXT_EXAMPLES = {
     "text-courier": (
@@ -84,7 +85,7 @@ def main() -> int:
     parser.add_argument(
         "--output",
         type=Path,
-        default=ROOT / "data" / "trace_samples.jsonl",
+        default=TRACE_DIR / "data" / "trace_samples.jsonl",
     )
     parser.add_argument("--dry-run", action="store_true")
     args = parser.parse_args()

{scripts → traces/scripts}/upload_trace_shards.py

@@ -10,11 +10,11 @@ from pathlib import Path
 
 from huggingface_hub import HfApi
 
-ROOT = Path(__file__).resolve().parents[1]
+ROOT = Path(__file__).resolve().parents[2]
 sys.path.insert(0, str(ROOT))
 
-from scripts.validate_traces import validate_file
-from trace_runtime import DATASET_REPO, PENDING_DIR
+from traces.runtime import DATASET_REPO, PENDING_DIR
+from traces.scripts.validate_traces import validate_file
 
 
 def main() -> int:

{scripts → traces/scripts}/validate_traces.py

@@ -7,10 +7,11 @@ import json
 import sys
 from pathlib import Path
 
-ROOT = Path(__file__).resolve().parents[1]
+ROOT = Path(__file__).resolve().parents[2]
+TRACE_DIR = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(ROOT))
 
-from trace_runtime import validate_trace
+from traces.runtime import validate_trace
 
 
 def validate_file(path: Path) -> tuple[int, list[str]]:
@@ -37,7 +38,7 @@ def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("paths", nargs="*", type=Path)
     args = parser.parse_args()
-    paths = args.paths or [ROOT / "data" / "trace_samples.jsonl"]
+    paths = args.paths or [TRACE_DIR / "data" / "trace_samples.jsonl"]
     total = 0
     all_errors: list[str] = []
     for path in paths: