runapprentice 0.1.0__tar.gz

runapprentice-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Node
+node_modules/
+.next/
+out/
+
+# Env / secrets — never commit (AGENTS.md)
+.env
+.env.*
+!.env.example
+!**/.env.example
+*.key
+
+# Data & model artifacts — never commit (AGENTS.md)
+*.csv
+*.jsonl
+datasets/
+apprentice-api/spike/.cache/
+checkpoints/
+optimized_program.json
+
+# Tooling
+.codegraph/
+.DS_Store
+*.log
+apprentice-ui/codex_working.md
+.codex/
+
+# Local dev databases
+*.db

runapprentice-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhishek Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

runapprentice-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: runapprentice
+Version: 0.1.0
+Summary: Cut LLM cost without losing quality: capture traffic, build golden datasets, and optimize prompts.
+Project-URL: Homepage, https://runapprentice.com
+Project-URL: Documentation, https://docs.runapprentice.com
+Author: Abhishek Singh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dspy,evaluation,gepa,langchain,llm,prompt-optimization,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# runapprentice
+
+Capture your LLM traffic, build a golden dataset, and optimize your prompt against it. Training a small model to take over from the frontier model is planned for a later release.
+
+This README documents the **implemented surface** (v0.1). Anything not shown here does not exist yet.
+
+## Install
+
+```bash
+uv add runapprentice[langchain]    # [langchain] extra enables zero-code capture
+```
+
+## Quickstart (the whole trial journey)
+
+```python
+from runapprentice import Apprentice
+
+client = Apprentice(
+    api_key="ap_live_...",   # create once in the console, or env APPRENTICE_API_KEY
+)                            # talks to the hosted API; set base_url only to self-host
+
+# 1. Create a task (a "task" = one repeatable LLM job you want to make cheaper)
+client.tasks.create("ticket-triage")
+
+# 2. Point us at the data you already have (CSV with input/output columns)
+client.datasets.upload(
+    "ticket-triage",
+    path="golden.csv",
+    input_col="input",
+    output_col="output",
+    prompt="...your current system prompt...",   # the baseline to beat
+)
+
+# 3. Optimize the prompt against your data (GEPA, held-out eval)
+job = client.optimize("ticket-triage")
+report = job.wait().report()
+print(report.baseline_score, "->", report.optimized_score)
+
+# 4. Pull the optimized prompt back into your code (versioned)
+best = client.prompts.get("ticket-triage")
+print(best.version, best.text)
+```
+
+## Live capture: LangChain (one line, zero code changes)
+
+```python
+# init_chat_model comes from your LangChain model package (for example
+# langchain[openai]); runapprentice[langchain] only adds langchain-core for
+# the callback.
+from langchain.chat_models import init_chat_model
+from runapprentice.langchain import ApprenticeCallback
+
+model = init_chat_model(
+    "gpt-5.5",   # whatever YOU already use. We observe, we don't choose
+    callbacks=[ApprenticeCallback("ticket-triage", client)],
+)
+# Every call now logs input/output/model/latency/tokens to the task's dataset (raw tier).
+```
+
+**Fail-open guarantee:** the capture path can NEVER break your app. If the
+Apprentice backend is down, unreachable, or slow, your LLM calls proceed
+untouched. The only loss is the trace. First drop logs a WARNING, repeats log
+at DEBUG.
+
+**PII redaction** runs in your process, before anything is transmitted:
+
+```python
+ApprenticeCallback("ticket-triage", client, redact=lambda s: my_scrubber(s))
+```
+
+## RAG quickstart (grounding + refusal-aware)
+
+For retrieval-augmented tasks, each row carries the **exact context the model saw**
+(the retrieved passages), not just the question. Pick the `rag_composite` metric so
+optimization rewards grounding and correct refusals, not just answer overlap.
+
+```python
+from runapprentice import Apprentice
+client = Apprentice(api_key="ap_live_...")
+
+# rag_composite scores answer correctness + faithfulness to context + refusal
+# correctness (it should say "not enough information" when the context lacks it).
+client.tasks.create("support-rag", metric="rag_composite")
+
+client.datasets.upload("support-rag", rows=[
+    {"inputs": {"question": q, "context": retrieved_passages}, "output": gold_answer}
+    for q, retrieved_passages, gold_answer in your_golden_set
+])
+
+client.prompts.register("support-rag", {
+    "format": "f-string",
+    "messages": [
+        {"role": "system", "template":
+            "Answer using only the context. If the context does not contain the "
+            "answer, say you do not have enough information.\n{context}"},
+        {"role": "human", "template": "{question}"},
+    ],
+    "input_variables": ["context", "question"],
+})
+
+report = client.optimize("support-rag").wait().report()
+print(report.baseline_score, "->", report.optimized_score)
+```
+
+**RAG capture for simple chains.** For a standard LangChain RAG chain, the
+`ApprenticeCallback` records the retrieved context from `on_retriever_end`, capturing
+the `{question, context}` shape. For custom formatting, multiple retrievers, or
+non-standard chains, call `client.capture(..., inputs={"question": ..., "context": ...})`
+explicitly.
+
+### Register a LangChain prompt directly
+
+`prompts.register` also accepts a LangChain `ChatPromptTemplate`, no raw dict needed:
+
+```python
+from langchain_core.prompts import ChatPromptTemplate
+client.prompts.register("support-rag", ChatPromptTemplate.from_messages([
+    ("system", "Answer using only the context. If it lacks the answer, refuse.\n{context}"),
+    ("human", "{question}"),
+]))
+# round-trip the optimized prompt back into LangChain:
+optimized = client.prompts.to_langchain("support-rag")
+```
+
+### Metric menu
+
+| `metric=` | Use for | Scored by |
+|---|---|---|
+| `auto` (default) | let the backend infer from your rows | inferred |
+| `json_f1` | JSON / structured extraction | deterministic |
+| `text_f1` | short free-text answers | deterministic |
+| `semantic_f1` | free-text / RAG answers (default for RAG) | LLM judge |
+| `rag_faithfulness` | is every claim supported by the context | LLM judge |
+| `rag_composite` | RAG grounding **and** refusal correctness | LLM judge |
+
+RAG rows auto-route to `semantic_f1`; pass `metric="rag_composite"` explicitly when you
+want grounding + refusal optimized together.
+
+## Feedback (your end-users' signal)
+
+```python
+client.feedback(trace_id, good=True)                  # thumbs
+client.feedback(trace_id, score=0.5, note="partial")  # graded
+```
+
+## Debugging
+
+```python
+import runapprentice
+runapprentice.enable_debug_logging()   # or env APPRENTICE_DEBUG=1
+```
+
+Shows every API call with status + latency, every capture attempt, every job
+poll. Control-plane errors are designed to tell you what to do (e.g. unreachable
+backend includes the URL it tried; optimize with too few rows tells you the
+count and the minimum).
+
+## API reference (implemented surface)
+
+| Call | Returns | Raises |
+|---|---|---|
+| `Apprentice(api_key=, base_url=, timeout=)` | client | `ApprenticeError` on bad config |
+| `client.tasks.create(name, metric="auto")` | dict (`created` bool) | `ApprenticeError` on HTTP failure |
+| `client.datasets.upload(task, path= or rows=, input_col=, output_col=, prompt=)` | `DatasetStatus` | same; also if both/neither of path/rows |
+| `client.datasets.status(task)` | `DatasetStatus(gold, silver, raw, ready_for_optimization)` | same |
+| `client.prompts.register(task, template)` | dict | `ImportError` if a LangChain template is passed without the `[langchain]` extra |
+| `client.prompts.to_langchain(task= or artifact=)` | LangChain prompt | `ImportError` without the `[langchain]` extra |
+| `client.optimize(task)` | `Job` | 400 if fewer than the backend's configured verified-row minimum (20 by default) |
+| `client.job(job_id)` / `job.refresh()` / `job.wait(poll_seconds=, timeout_seconds=)` | `Job` | `ApprenticeError` on timeout |
+| `job.report()` | `OptimizationReport(baseline_score, optimized_score, optimized_prompt, ...)` | if job has no report |
+| `client.prompts.get(task, version=None)` | `PromptVersion(version, text, score)` | 404 if never optimized |
+| `client.prompts.history(task)` | `list[PromptVersion]` | `ApprenticeError` on API failure |
+| `client.feedback(trace_id, good=, score=, note=)` | None | 404 unknown trace |
+| `client.post_trace_failopen(record)` | trace_id or None | **never raises** |
+| `ApprenticeCallback(task, client, redact=None)` | LangChain callback | **never raises into your chain** |
+
+## Data tiers (how your rows are treated)
+
+- **raw**: captured from live traffic, unverified
+- **silver**: uploaded by you (curated) or passed deterministic checks
+- **gold**: human-verified
+- Optimization uses gold + silver; eval gates will use **gold only**.
+
+## For AI coding tools
+
+Module docstrings and this README are the source of truth. Key invariants an
+agent must preserve when editing this package:
+
+1. `post_trace_failopen` and everything in `runapprentice/langchain.py` must never
+   raise into the caller. Capture is fail-open by contract (see `tests/test_failopen.py`).
+2. Control-plane methods must raise `ApprenticeError` with actionable messages.
+3. Dependencies stay minimal: `httpx` + `pydantic`; LangChain only via the
+   `[langchain]` extra; never import from `apprentice-api`.
+4. Required tests for any new method: add a row to `../needed_test.md`.

runapprentice-0.1.0/README.md

@@ -0,0 +1,194 @@
+# runapprentice
+
+Capture your LLM traffic, build a golden dataset, and optimize your prompt against it. Training a small model to take over from the frontier model is planned for a later release.
+
+This README documents the **implemented surface** (v0.1). Anything not shown here does not exist yet.
+
+## Install
+
+```bash
+uv add runapprentice[langchain]    # [langchain] extra enables zero-code capture
+```
+
+## Quickstart (the whole trial journey)
+
+```python
+from runapprentice import Apprentice
+
+client = Apprentice(
+    api_key="ap_live_...",   # create once in the console, or env APPRENTICE_API_KEY
+)                            # talks to the hosted API; set base_url only to self-host
+
+# 1. Create a task (a "task" = one repeatable LLM job you want to make cheaper)
+client.tasks.create("ticket-triage")
+
+# 2. Point us at the data you already have (CSV with input/output columns)
+client.datasets.upload(
+    "ticket-triage",
+    path="golden.csv",
+    input_col="input",
+    output_col="output",
+    prompt="...your current system prompt...",   # the baseline to beat
+)
+
+# 3. Optimize the prompt against your data (GEPA, held-out eval)
+job = client.optimize("ticket-triage")
+report = job.wait().report()
+print(report.baseline_score, "->", report.optimized_score)
+
+# 4. Pull the optimized prompt back into your code (versioned)
+best = client.prompts.get("ticket-triage")
+print(best.version, best.text)
+```
+
+## Live capture: LangChain (one line, zero code changes)
+
+```python
+# init_chat_model comes from your LangChain model package (for example
+# langchain[openai]); runapprentice[langchain] only adds langchain-core for
+# the callback.
+from langchain.chat_models import init_chat_model
+from runapprentice.langchain import ApprenticeCallback
+
+model = init_chat_model(
+    "gpt-5.5",   # whatever YOU already use. We observe, we don't choose
+    callbacks=[ApprenticeCallback("ticket-triage", client)],
+)
+# Every call now logs input/output/model/latency/tokens to the task's dataset (raw tier).
+```
+
+**Fail-open guarantee:** the capture path can NEVER break your app. If the
+Apprentice backend is down, unreachable, or slow, your LLM calls proceed
+untouched. The only loss is the trace. First drop logs a WARNING, repeats log
+at DEBUG.
+
+**PII redaction** runs in your process, before anything is transmitted:
+
+```python
+ApprenticeCallback("ticket-triage", client, redact=lambda s: my_scrubber(s))
+```
+
+## RAG quickstart (grounding + refusal-aware)
+
+For retrieval-augmented tasks, each row carries the **exact context the model saw**
+(the retrieved passages), not just the question. Pick the `rag_composite` metric so
+optimization rewards grounding and correct refusals, not just answer overlap.
+
+```python
+from runapprentice import Apprentice
+client = Apprentice(api_key="ap_live_...")
+
+# rag_composite scores answer correctness + faithfulness to context + refusal
+# correctness (it should say "not enough information" when the context lacks it).
+client.tasks.create("support-rag", metric="rag_composite")
+
+client.datasets.upload("support-rag", rows=[
+    {"inputs": {"question": q, "context": retrieved_passages}, "output": gold_answer}
+    for q, retrieved_passages, gold_answer in your_golden_set
+])
+
+client.prompts.register("support-rag", {
+    "format": "f-string",
+    "messages": [
+        {"role": "system", "template":
+            "Answer using only the context. If the context does not contain the "
+            "answer, say you do not have enough information.\n{context}"},
+        {"role": "human", "template": "{question}"},
+    ],
+    "input_variables": ["context", "question"],
+})
+
+report = client.optimize("support-rag").wait().report()
+print(report.baseline_score, "->", report.optimized_score)
+```
+
+**RAG capture for simple chains.** For a standard LangChain RAG chain, the
+`ApprenticeCallback` records the retrieved context from `on_retriever_end`, capturing
+the `{question, context}` shape. For custom formatting, multiple retrievers, or
+non-standard chains, call `client.capture(..., inputs={"question": ..., "context": ...})`
+explicitly.
+
+### Register a LangChain prompt directly
+
+`prompts.register` also accepts a LangChain `ChatPromptTemplate`, no raw dict needed:
+
+```python
+from langchain_core.prompts import ChatPromptTemplate
+client.prompts.register("support-rag", ChatPromptTemplate.from_messages([
+    ("system", "Answer using only the context. If it lacks the answer, refuse.\n{context}"),
+    ("human", "{question}"),
+]))
+# round-trip the optimized prompt back into LangChain:
+optimized = client.prompts.to_langchain("support-rag")
+```
+
+### Metric menu
+
+| `metric=` | Use for | Scored by |
+|---|---|---|
+| `auto` (default) | let the backend infer from your rows | inferred |
+| `json_f1` | JSON / structured extraction | deterministic |
+| `text_f1` | short free-text answers | deterministic |
+| `semantic_f1` | free-text / RAG answers (default for RAG) | LLM judge |
+| `rag_faithfulness` | is every claim supported by the context | LLM judge |
+| `rag_composite` | RAG grounding **and** refusal correctness | LLM judge |
+
+RAG rows auto-route to `semantic_f1`; pass `metric="rag_composite"` explicitly when you
+want grounding + refusal optimized together.
+
+## Feedback (your end-users' signal)
+
+```python
+client.feedback(trace_id, good=True)                  # thumbs
+client.feedback(trace_id, score=0.5, note="partial")  # graded
+```
+
+## Debugging
+
+```python
+import runapprentice
+runapprentice.enable_debug_logging()   # or env APPRENTICE_DEBUG=1
+```
+
+Shows every API call with status + latency, every capture attempt, every job
+poll. Control-plane errors are designed to tell you what to do (e.g. unreachable
+backend includes the URL it tried; optimize with too few rows tells you the
+count and the minimum).
+
+## API reference (implemented surface)
+
+| Call | Returns | Raises |
+|---|---|---|
+| `Apprentice(api_key=, base_url=, timeout=)` | client | `ApprenticeError` on bad config |
+| `client.tasks.create(name, metric="auto")` | dict (`created` bool) | `ApprenticeError` on HTTP failure |
+| `client.datasets.upload(task, path= or rows=, input_col=, output_col=, prompt=)` | `DatasetStatus` | same; also if both/neither of path/rows |
+| `client.datasets.status(task)` | `DatasetStatus(gold, silver, raw, ready_for_optimization)` | same |
+| `client.prompts.register(task, template)` | dict | `ImportError` if a LangChain template is passed without the `[langchain]` extra |
+| `client.prompts.to_langchain(task= or artifact=)` | LangChain prompt | `ImportError` without the `[langchain]` extra |
+| `client.optimize(task)` | `Job` | 400 if fewer than the backend's configured verified-row minimum (20 by default) |
+| `client.job(job_id)` / `job.refresh()` / `job.wait(poll_seconds=, timeout_seconds=)` | `Job` | `ApprenticeError` on timeout |
+| `job.report()` | `OptimizationReport(baseline_score, optimized_score, optimized_prompt, ...)` | if job has no report |
+| `client.prompts.get(task, version=None)` | `PromptVersion(version, text, score)` | 404 if never optimized |
+| `client.prompts.history(task)` | `list[PromptVersion]` | `ApprenticeError` on API failure |
+| `client.feedback(trace_id, good=, score=, note=)` | None | 404 unknown trace |
+| `client.post_trace_failopen(record)` | trace_id or None | **never raises** |
+| `ApprenticeCallback(task, client, redact=None)` | LangChain callback | **never raises into your chain** |
+
+## Data tiers (how your rows are treated)
+
+- **raw**: captured from live traffic, unverified
+- **silver**: uploaded by you (curated) or passed deterministic checks
+- **gold**: human-verified
+- Optimization uses gold + silver; eval gates will use **gold only**.
+
+## For AI coding tools
+
+Module docstrings and this README are the source of truth. Key invariants an
+agent must preserve when editing this package:
+
+1. `post_trace_failopen` and everything in `runapprentice/langchain.py` must never
+   raise into the caller. Capture is fail-open by contract (see `tests/test_failopen.py`).
+2. Control-plane methods must raise `ApprenticeError` with actionable messages.
+3. Dependencies stay minimal: `httpx` + `pydantic`; LangChain only via the
+   `[langchain]` extra; never import from `apprentice-api`.
+4. Required tests for any new method: add a row to `../needed_test.md`.

runapprentice-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "runapprentice"
+version = "0.1.0"
+description = "Cut LLM cost without losing quality: capture traffic, build golden datasets, and optimize prompts."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Abhishek Singh" }]
+keywords = ["llm", "prompt-optimization", "dspy", "gepa", "rag", "evaluation", "langchain"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://runapprentice.com"
+Documentation = "https://docs.runapprentice.com"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "mypy>=1.10",
+    "ruff>=0.5",
+    "langchain-core>=0.3",
+]
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/runapprentice"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/runapprentice", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

runapprentice-0.1.0/src/runapprentice/__init__.py

@@ -0,0 +1,26 @@
+"""Apprentice SDK: capture LLM traffic, build golden datasets, and optimize prompts."""
+
+from runapprentice.client import Apprentice, ApprenticeError, Job, enable_debug_logging
+from runapprentice.models import (
+    DatasetRow,
+    DatasetStatus,
+    JobInfo,
+    OptimizationReport,
+    PromptVersion,
+    TraceRecord,
+)
+
+__all__ = [
+    "Apprentice",
+    "ApprenticeError",
+    "enable_debug_logging",
+    "Job",
+    "DatasetRow",
+    "DatasetStatus",
+    "JobInfo",
+    "OptimizationReport",
+    "PromptVersion",
+    "TraceRecord",
+]
+
+__version__ = "0.1.0"

runapprentice-0.1.0/src/runapprentice/_capture.py

@@ -0,0 +1,117 @@
+"""Background capture dispatcher.
+
+Capture runs inside the customer's production request path, so it must be both
+NON-BLOCKING (never add latency to their call) and RESILIENT (a transient network
+blip must not silently drop a trace on the first try). This dispatcher gives both:
+
+- `submit()` enqueues and returns immediately (the customer's thread never waits on
+  Apprentice's network).
+- A single daemon worker drains the queue and delivers each trace with bounded
+  retry + exponential backoff.
+- The queue is bounded; if Apprentice's backend is down long enough to fill it, the
+  oldest pending traces are dropped (fail-open — the customer app is never affected).
+- `flush()` (also run at interpreter exit) drains in-flight traces so short scripts
+  don't lose their last captures.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import queue
+import random
+import threading
+import time
+from typing import Callable
+
+from runapprentice.models import TraceRecord
+
+logger = logging.getLogger("runapprentice")
+
+# send(record) -> True if delivered, False if permanently rejected (do not retry);
+# raises on a transient failure (network/5xx) that should be retried.
+SendFn = Callable[[TraceRecord], bool]
+_SHUTDOWN = object()
+
+
+class CaptureDispatcher:
+    def __init__(
+        self,
+        send: SendFn,
+        on_exhausted: Callable[[str], None],
+        max_queue: int = 1000,
+        retries: int = 2,
+        backoff_base: float = 0.5,
+    ) -> None:
+        self._send = send
+        self._on_exhausted = on_exhausted
+        self._retries = retries
+        self._backoff_base = backoff_base
+        self._queue: queue.Queue[object] = queue.Queue(maxsize=max_queue)
+        self._dropped = 0
+        self._worker = threading.Thread(
+            target=self._run, name="apprentice-capture", daemon=True
+        )
+        self._worker.start()
+        atexit.register(self.flush)
+
+    def submit(self, record: TraceRecord) -> None:
+        """Enqueue a trace without blocking. Drops the oldest if the queue is full."""
+        try:
+            self._queue.put_nowait(record)
+        except queue.Full:
+            # Backend is unreachable and the buffer is full — drop the oldest pending
+            # trace to make room for the newest, so we keep the freshest signal.
+            try:
+                self._queue.get_nowait()
+                self._queue.task_done()
+            except queue.Empty:
+                pass
+            self._dropped += 1
+            if self._dropped == 1 or self._dropped % 100 == 0:
+                logger.warning(
+                    "runapprentice: capture buffer full, dropped %d trace(s) "
+                    "(backend unreachable; app unaffected)",
+                    self._dropped,
+                )
+            try:
+                self._queue.put_nowait(record)
+            except queue.Full:
+                pass
+
+    def _run(self) -> None:
+        while True:
+            item = self._queue.get()
+            try:
+                if item is _SHUTDOWN:
+                    return
+                assert isinstance(item, TraceRecord)
+                self._deliver(item)
+            finally:
+                self._queue.task_done()
+
+    def _deliver(self, record: TraceRecord) -> None:
+        last_error: Exception | None = None
+        for attempt in range(self._retries + 1):
+            try:
+                self._send(record)  # True=delivered, False=permanent reject
+                return
+            except Exception as exc:  # noqa: BLE001 — transient; retry then give up
+                last_error = exc
+                if attempt < self._retries:
+                    time.sleep(self._backoff_base * (2**attempt) + random.uniform(0, 0.1))
+        if last_error is not None:
+            self._on_exhausted(f"capture failed after {self._retries + 1} attempts: {last_error}")
+
+    def flush(self, timeout: float = 2.0) -> None:
+        """Wait up to `timeout` seconds for in-flight traces to finish delivering.
+
+        Counts items as done only after the worker calls `task_done()` (i.e. after
+        delivery + any retries complete), not merely when they leave the queue.
+        """
+        deadline = time.monotonic() + timeout
+        while self._queue.unfinished_tasks > 0 and time.monotonic() < deadline:
+            time.sleep(0.02)
+
+    def close(self) -> None:
+        self._queue.put(_SHUTDOWN)