semdex 1.5.6__tar.gz

semdex-1.5.6/.claude/skills/bench-rerun/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: bench-rerun
+description: Use when semdex components were updated (extractor/store container images, fastembed or other embedding models, chunker libraries, ollama models) or on a periodic re-test, and the benchmarks must be re-run, compared against the committed baseline, and the bench_*.md rankings refreshed.
+---
+
+# Re-run the semdex benchmarks after component updates
+
+Everything runs against the **fixed slice** the baseline was seeded with - a different slice
+makes the comparison apples-to-oranges. One-off scale references (the MSMARCO tables in
+`bench_database.md`) are NOT part of this loop; re-measure those deliberately.
+
+## 1. Update what actually changed
+
+```bash
+# Containers: docker run reuses the cached tag - a stale image silently tests nothing new.
+docker pull <image>            # then record: docker inspect --format '{{index .RepoDigests 0}}' <image>
+# Python deps: upgrade IN THE BENCHMARK VENV (the one with all extras, see
+# COMPONENT_SETUP.md "Benchmark prerequisites"), not some other venv.
+uv pip install -U <package>
+# ollama models: ollama pull <model> on your server (endpoint via SEMDEX_BENCH_OLLAMA_URL
+# from .env - never hardcode a host anywhere in the repo).
+```
+
+## 2. Re-run at the fixed slice - ONE pytest session
+
+Result cells accumulate into one `benchmark-results.json` per pytest **process**; a second
+invocation overwrites it. Run all needed files in a single session:
+
+```bash
+SEMDEX_BENCH_CORPORA=nfcorpus SEMDEX_BENCH_MAX_DOCS=150 SEMDEX_BENCH_MAX_QUERIES=20 \
+  pytest -p no:cacheprovider -o addopts="" -s \
+  tests/test_e2e_matrix.py tests/test_e2e_extractor_matrix.py::test_extractor_fixture_matrix
+```
+
+Scope a partial re-check to the changed axis with the env filters
+(`SEMDEX_BENCH_CHUNKERS/_EMBEDDINGS/_STORES/_EXTRACTORS/_EMBED_MODELS`); untouched cells show
+as non-gating "not_run". Cells whose container/server is down record `skip` - the comparator
+flags `ok -> skip`, so fix the service rather than accepting it.
+
+## 3. Compare - and root-cause before touching the baseline
+
+```bash
+python scripts/benchmark_compare.py benchmark-results.json
+```
+
+On a regression, **never `--update` to make red green.** Attribute it first: status flip ->
+diff the recorded image digest vs the baseline's; quality drop -> what changed in the model
+(re-run once to confirm - fastembed is deterministic); adapter error -> upstream API change,
+fix the adapter + its tests. A semdex-side fix ends with the slice green; an upstream
+regression ends with a pin + upstream issue; a genuine accepted change moves on to step 4.
+
+## 4. Adopt and re-rank
+
+```bash
+python scripts/benchmark_compare.py benchmark-results.json --update
+```
+
+Then regenerate every published number in that same commit, never by hand. Run
+`python scripts/export_bench_raw.py`, then `python scripts/gen_bench_tables.py` and
+`python scripts/gen_bench_charts.py`: every published table and chart under `docs/benchmarks/`
+is generated from `tests/benchmarks/raw/`, and
+`pytest tests/test_bench_tables_current.py tests/test_bench_charts_current.py` fails if a
+published number no longer matches its data.
+
+What a human still writes, in the same commit: the PROSE around a table, if a verdict changed;
+the new component versions/digests, named in the commit message; a `CHANGELOG.md` entry; a
+`pyproject.toml` constraint if a floor or pin changed. The quality-table numbers come from the
+4-corpus run (`SEMDEX_BENCH_CORPORA=nfcorpus,cqadupstack,scifact,fiqa`) - re-run that before
+re-ranking chunker/embedding tables.
+
+## 5. Gate before pushing
+
+```bash
+grep -rnE "192\.168\.|[0-9]{1,3}(\.[0-9]{1,3}){3}|\.local\." docs/ tests/benchmarks/ .claude/skills/ || echo leak-clean
+make test
+```
+
+Done when: every flagged cell has a written root cause, `make test` is green, the baseline
+refresh and the docs regenerated from it are one reviewable commit of their own (no semdex code
+fix from step 3 in it) naming the component versions/digests that justify it, and the doc tables
+cite the new numbers.

semdex-1.5.6/.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+  "image": "mcr.microsoft.com/devcontainers/python:3.13",
+
+  "postCreateCommand": "bash -lc '\nPY=/usr/local/bin/python;\n$PY -m pip install -U pip && \\\n$PY -m pip install ipykernel && \\\n$PY -m pip install -e . && \\\n# register kernel using this exact interpreter\n$PY -m ipykernel install --name=python3 --display-name=\"Python 3 (3.13)\" --user && \\\n# patch the notebook to point to the python3 kernelspec (VS Code will bind to /usr/local/bin/python)\n$PY - <<\"PY\"\nimport json, pathlib\np = pathlib.Path(\"notebooks/Quickstart.ipynb\")\nif p.exists():\n    nb = json.loads(p.read_text(encoding=\"utf-8\"))\n    md = nb.setdefault(\"metadata\", {})\n    md[\"kernelspec\"] = {\n        \"name\": \"python3\",\n        \"display_name\": \"Python 3 (3.13)\",\n        \"language\": \"python\"\n    }\n    md[\"language_info\"] = {\"name\": \"python\"}\n    p.write_text(json.dumps(nb, ensure_ascii=False, indent=1), encoding=\"utf-8\")\n    print(\"Pinned kernelspec to python3 in\", p)\nelse:\n    print(\"Notebook not found:\", p)\nPY'\n",
+
+  "customizations": {
+    "vscode": {
+      "extensions": ["ms-toolsai.jupyter", "ms-python.python"],
+      "settings": {
+        "workbench.startupEditor": "none",
+        "jupyter.alwaysTrustNotebooks": true,
+        "jupyter.kernelPickerType": "OnlyRecommended",
+        "python.defaultInterpreterPath": "/usr/local/bin/python"
+      }
+    },
+    "codespaces": {
+      "openFiles": ["README.md"]
+    }
+  },
+
+  "postAttachCommand": "bash -lc 'if [ -f notebooks/Quickstart.ipynb ]; then code -r notebooks/Quickstart.ipynb; fi'"
+}

semdex-1.5.6/.devcontainer/settings.json

@@ -0,0 +1,6 @@
+{
+  "python.defaultInterpreterPath": "/usr/local/bin/python3.13",
+  "jupyter.alwaysTrustNotebooks": true,
+  "jupyter.kernelPickerType": "OnlyRecommended",
+  "jupyter.askForKernelRestart": false
+}

semdex-1.5.6/.env.example

@@ -0,0 +1,468 @@
+# Copy to .env and fill values as needed.
+
+# Codecov upload token (required for private repos; optional for public repos)
+CODECOV_TOKEN=
+
+# PyPI API token for the release workflow (.github/workflows/default_release_public.yml).
+# Leave it empty when PyPI has a Trusted Publisher for this repo: the workflow then
+# publishes via OIDC instead of the token.
+# Format: pypi-AgENdGVzdC5weXBpLm9yZwIk...
+PYPI_API_TOKEN=
+
+# Optional: GitHub token for API-limited tasks
+GITHUB_TOKEN=
+
+
+# ==============================================================================
+# Email Configuration (SMTP)
+# ==============================================================================
+#
+# Naming Convention
+# -----------------
+# Format: <SECTION>__<KEY>=value (double underscore separates section from key)
+# An unquoted value is converted (in .env and in the environment alike): true/false become
+# booleans, null/none become None (except for secret keys such as passwords, which keep the
+# text), a JSON array or object is parsed, and a number becomes a number only when it converts
+# back to the same text (007 and 1.50 stay text). Quote a .env value to keep it as text; the
+# quotes are removed. A list is a JSON array, written UNQUOTED: EMAIL__RECIPIENTS=["a@example.com","b@example.com"].
+# Or give one key per entry: EMAIL__RECIPIENTS__0=a@example.com, EMAIL__RECIPIENTS__1=b@example.com.
+# A comma-separated value is NOT a list: it arrives as ONE string.
+#
+# Full environment variable (outside .env):
+#   SEMDEX___EMAIL__<KEY>=value
+#   (triple underscore separates the application slug from the section)
+#   The environment converts values the same way; an environment variable has no quoting
+#   of its own (quotes stay part of the value), so the single quotes below are only for the
+#   shell: SEMDEX___EMAIL__RECIPIENTS='["a@example.com","b@example.com"]'
+
+# Purpose: SMTP servers for email delivery, tried in order (host:port)
+# Type: list of strings in "host[:port]" format; a single string is one host
+# Default: (empty, must be configured to send email)
+# Environment Variable: SEMDEX___EMAIL__SMTP_HOSTS='["smtp.example.com:587","smtp-backup.example.com:587"]'
+# .env: EMAIL__SMTP_HOSTS=["smtp.example.com:587","smtp-backup.example.com:587"]
+# .env, one key per host: EMAIL__SMTP_HOSTS__0=smtp.example.com:587 and EMAIL__SMTP_HOSTS__1=smtp-backup.example.com:587
+# EMAIL__SMTP_HOSTS=["smtp.example.com:587"]
+
+# Purpose: Default sender address for outgoing emails
+# Type: string (valid email address)
+# Default: (empty, must be configured or passed via --from)
+# Environment Variable: SEMDEX___EMAIL__FROM_ADDRESS=noreply@example.com
+# .env: EMAIL__FROM_ADDRESS=noreply@example.com
+# EMAIL__FROM_ADDRESS=noreply@example.com
+
+# Purpose: Default recipient addresses
+# Type: list of strings (valid email addresses); a single string is one address
+# Default: (empty, must be configured or passed via --to)
+# Environment Variable: SEMDEX___EMAIL__RECIPIENTS='["admin@example.com","ops@example.com"]'
+# .env: EMAIL__RECIPIENTS=["admin@example.com","ops@example.com"]
+# .env, one key per address: EMAIL__RECIPIENTS__0=admin@example.com and EMAIL__RECIPIENTS__1=ops@example.com
+# EMAIL__RECIPIENTS=["admin@example.com","ops@example.com"]
+
+# Purpose: SMTP authentication username
+# Type: string
+# Default: (empty, no authentication)
+# Environment Variable: SEMDEX___EMAIL__SMTP_USERNAME=noreply@example.com
+# .env: EMAIL__SMTP_USERNAME=noreply@example.com
+# EMAIL__SMTP_USERNAME=noreply@example.com
+
+# Purpose: SMTP authentication password
+# Type: string
+# Default: (empty, no authentication)
+# Environment Variable: SEMDEX___EMAIL__SMTP_PASSWORD=your-app-password
+# .env: EMAIL__SMTP_PASSWORD=your-app-password
+# EMAIL__SMTP_PASSWORD=your-app-password
+
+# Purpose: Enable STARTTLS negotiation before authentication
+# Type: boolean (true/false)
+# Default: true
+# Environment Variable: SEMDEX___EMAIL__USE_STARTTLS=true
+# .env: EMAIL__USE_STARTTLS=true
+# EMAIL__USE_STARTTLS=true
+
+# Purpose: Socket timeout in seconds for SMTP operations
+# Type: float
+# Default: 30.0
+# Environment Variable: SEMDEX___EMAIL__TIMEOUT=30.0
+# .env: EMAIL__TIMEOUT=30.0
+# EMAIL__TIMEOUT=30.0
+
+# Purpose: Verify the SMTP server's TLS certificate after STARTTLS
+# Type: boolean (true/false)
+# Default: true
+# Note: false accepts ANY certificate; use it only for a known internal relay
+# Environment Variable: SEMDEX___EMAIL__STARTTLS_VERIFY=true
+# .env: EMAIL__STARTTLS_VERIFY=true
+# EMAIL__STARTTLS_VERIFY=true
+
+# Purpose: Host name announced in the SMTP greeting (EHLO); set it where reverse DNS is slow
+# Type: string
+# Default: unset (looked up once per process)
+# Environment Variable: SEMDEX___EMAIL__LOCAL_HOSTNAME=mail.example.com
+# .env: EMAIL__LOCAL_HOSTNAME=mail.example.com
+# EMAIL__LOCAL_HOSTNAME=mail.example.com
+
+# Purpose: Upper bound in seconds for one SMTP session (connect to QUIT); 0 for none
+# Type: float
+# Default: 0 (none)
+# Environment Variable: SEMDEX___EMAIL__DELIVERY_DEADLINE=300
+# .env: EMAIL__DELIVERY_DEADLINE=300
+# EMAIL__DELIVERY_DEADLINE=300
+
+# Purpose: Most recipients one send accepts; 0 for no limit
+# Type: integer
+# Default: 1000
+# Environment Variable: SEMDEX___EMAIL__RECIPIENT_MAX_COUNT=1000
+# .env: EMAIL__RECIPIENT_MAX_COUNT=1000
+# EMAIL__RECIPIENT_MAX_COUNT=1000
+
+# Purpose: Raise FileNotFoundError when attachment files are missing
+# Type: boolean (true/false)
+# Default: true
+# Environment Variable: SEMDEX___EMAIL__RAISE_ON_MISSING_ATTACHMENTS=true
+# .env: EMAIL__RAISE_ON_MISSING_ATTACHMENTS=true
+# EMAIL__RAISE_ON_MISSING_ATTACHMENTS=true
+
+# Purpose: Raise ValueError when recipient addresses are invalid
+# Type: boolean (true/false)
+# Default: true
+# Environment Variable: SEMDEX___EMAIL__RAISE_ON_INVALID_RECIPIENT=true
+# .env: EMAIL__RAISE_ON_INVALID_RECIPIENT=true
+# EMAIL__RAISE_ON_INVALID_RECIPIENT=true
+
+
+# ==============================================================================
+# Logging Configuration (lib_log_rich)
+# ==============================================================================
+#
+# Naming Convention
+# -----------------
+# Format: <SECTION>__<KEY>=value (double underscore separates section from key)
+# Strings need no quotes. An unquoted value is converted: true/false become booleans,
+# null/none become None, a JSON array or object is parsed, and a number becomes a number only
+# when it converts back to the same text; quote a value to keep it as text. A table is a JSON object, written unquoted
+# (LIB_LOG_RICH__CONSOLE_STYLES={"ERROR":"bold red"}), or one key per entry
+# (LIB_LOG_RICH__SCRUB_PATTERNS__API_KEY=.+). Comma-separated pairs are NOT a table: they
+# arrive as ONE string and are refused.
+#
+# Full environment variable (outside .env):
+#   SEMDEX___LIB_LOG_RICH__<KEY>=value
+#
+# For nested subsections (e.g. payload_limits):
+#   SEMDEX___LIB_LOG_RICH__PAYLOAD_LIMITS__<KEY>=value
+#   .env: LIB_LOG_RICH__PAYLOAD_LIMITS__<KEY>=value
+
+# --- Core Identity ---
+
+# Purpose: Logical service name recorded in each log event
+# Type: string (non-empty)
+# Default: "semdex"
+# Environment Variable: SEMDEX___LIB_LOG_RICH__SERVICE=my-application
+# .env: LIB_LOG_RICH__SERVICE=my-application
+# LIB_LOG_RICH__SERVICE=my-application
+
+# Purpose: Deployment environment label
+# Type: string (non-empty)
+# Default: "prod"
+# Environment Variable: SEMDEX___LIB_LOG_RICH__ENVIRONMENT=dev
+# .env: LIB_LOG_RICH__ENVIRONMENT=dev
+# LIB_LOG_RICH__ENVIRONMENT=dev
+
+# --- Console Output ---
+
+# Purpose: Minimum severity level emitted to Rich console
+# Type: string (case-insensitive): "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+# Default: "INFO"
+# Environment Variable: SEMDEX___LIB_LOG_RICH__CONSOLE_LEVEL=DEBUG
+# .env: LIB_LOG_RICH__CONSOLE_LEVEL=DEBUG
+# LIB_LOG_RICH__CONSOLE_LEVEL=DEBUG
+
+# Purpose: Where to send console output
+# Type: string: "stdout", "stderr", "both", "custom", "none"
+# Default: "stderr"
+# Environment Variable: SEMDEX___LIB_LOG_RICH__CONSOLE_STREAM=stderr
+# .env: LIB_LOG_RICH__CONSOLE_STREAM=stderr
+# LIB_LOG_RICH__CONSOLE_STREAM=stderr
+
+# Purpose: Console line layout preset
+# Type: string (case-insensitive): "full", "short", "full_loc", "short_loc"
+# Default: "short_loc"
+# Environment Variable: SEMDEX___LIB_LOG_RICH__CONSOLE_FORMAT_PRESET=short_loc
+# .env: LIB_LOG_RICH__CONSOLE_FORMAT_PRESET=short_loc
+# LIB_LOG_RICH__CONSOLE_FORMAT_PRESET=short_loc
+
+# Purpose: Custom console output template (overrides preset)
+# Type: string (Python str.format template); empty = uses preset
+# Default: (empty, uses preset)
+# Environment Variable: SEMDEX___LIB_LOG_RICH__CONSOLE_FORMAT_TEMPLATE={timestamp_trimmed_naive_loc} {level_code} {message}
+# .env: LIB_LOG_RICH__CONSOLE_FORMAT_TEMPLATE={timestamp_trimmed_naive_loc} {level_code} {message}
+# LIB_LOG_RICH__CONSOLE_FORMAT_TEMPLATE={timestamp_trimmed_naive_loc} {level_code} {message}
+
+# Purpose: Rich color palette for console output
+# Type: string: "classic", "dark", "neon", "pastel"
+# Default: "dark"
+# Environment Variable: SEMDEX___LIB_LOG_RICH__CONSOLE_THEME=dark
+# .env: LIB_LOG_RICH__CONSOLE_THEME=dark
+# LIB_LOG_RICH__CONSOLE_THEME=dark
+
+# Purpose: Override Rich styles per severity level
+# Type: table of LEVEL = style (a JSON object keeps the level names upper case)
+# Default: (empty, uses theme defaults)
+# Environment Variable: SEMDEX___LIB_LOG_RICH__CONSOLE_STYLES='{"DEBUG":"dim","ERROR":"bold red"}'
+# .env: LIB_LOG_RICH__CONSOLE_STYLES={"DEBUG":"dim","ERROR":"bold red"}
+# LIB_LOG_RICH__CONSOLE_STYLES={"DEBUG":"dim","ERROR":"bold red"}
+
+# Purpose: Force ANSI color output even when stderr is not a TTY
+# Type: boolean (true/false)
+# Default: false
+# Environment Variable: SEMDEX___LIB_LOG_RICH__FORCE_COLOR=true
+# .env: LIB_LOG_RICH__FORCE_COLOR=true
+# LIB_LOG_RICH__FORCE_COLOR=true
+
+# Purpose: Disable color output entirely (overrides force_color)
+# Type: boolean (true/false)
+# Default: false
+# Environment Variable: SEMDEX___LIB_LOG_RICH__NO_COLOR=false
+# .env: LIB_LOG_RICH__NO_COLOR=false
+# LIB_LOG_RICH__NO_COLOR=false
+
+# --- Backend Adapters ---
+
+# Purpose: Minimum severity threshold for journald and Windows Event Log
+# Type: string (case-insensitive): "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+# Default: "WARNING"
+# Environment Variable: SEMDEX___LIB_LOG_RICH__BACKEND_LEVEL=WARNING
+# .env: LIB_LOG_RICH__BACKEND_LEVEL=WARNING
+# LIB_LOG_RICH__BACKEND_LEVEL=WARNING
+
+# Purpose: Enable systemd journald adapter (Linux only; requires python3-systemd)
+# Type: boolean (true/false)
+# Default: false
+# Environment Variable: SEMDEX___LIB_LOG_RICH__ENABLE_JOURNALD=true
+# .env: LIB_LOG_RICH__ENABLE_JOURNALD=true
+# LIB_LOG_RICH__ENABLE_JOURNALD=true
+
+# Purpose: Enable Windows Event Log adapter (Windows only)
+# Type: boolean (true/false)
+# Default: false
+# Environment Variable: SEMDEX___LIB_LOG_RICH__ENABLE_EVENTLOG=false
+# .env: LIB_LOG_RICH__ENABLE_EVENTLOG=false
+# LIB_LOG_RICH__ENABLE_EVENTLOG=false
+
+# --- Graylog / GELF ---
+
+# Purpose: Enable Graylog adapter for centralized logging
+# Type: boolean (true/false)
+# Default: false
+# Environment Variable: SEMDEX___LIB_LOG_RICH__ENABLE_GRAYLOG=true
+# .env: LIB_LOG_RICH__ENABLE_GRAYLOG=true
+# LIB_LOG_RICH__ENABLE_GRAYLOG=true
+
+# Purpose: Graylog server address
+# Type: JSON array [host, port]; a "host:port" string is refused (config, index, search,
+#   serve, send-email and send-notification exit 78; only the native LOG_GRAYLOG_ENDPOINT
+#   variable takes host:port)
+# Default: (none, must be configured to enable Graylog)
+# Environment Variable: SEMDEX___LIB_LOG_RICH__GRAYLOG_ENDPOINT='["graylog.example.com",12201]'
+# .env: LIB_LOG_RICH__GRAYLOG_ENDPOINT=["graylog.example.com",12201]
+# LIB_LOG_RICH__GRAYLOG_ENDPOINT=["graylog.example.com",12201]
+
+# Purpose: Transport protocol for Graylog (tcp, udp); TLS only supported with tcp
+# Type: string: "tcp", "udp"
+# Default: "tcp"
+# Environment Variable: SEMDEX___LIB_LOG_RICH__GRAYLOG_PROTOCOL=tcp
+# .env: LIB_LOG_RICH__GRAYLOG_PROTOCOL=tcp
+# LIB_LOG_RICH__GRAYLOG_PROTOCOL=tcp
+
+# Purpose: Wrap Graylog TCP connection in TLS
+# Type: boolean (true/false)
+# Default: false
+# Environment Variable: SEMDEX___LIB_LOG_RICH__GRAYLOG_TLS=true
+# .env: LIB_LOG_RICH__GRAYLOG_TLS=true
+# LIB_LOG_RICH__GRAYLOG_TLS=true
+
+# Purpose: Minimum severity level sent to Graylog
+# Type: string (case-insensitive): "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+# Default: "WARNING"
+# Environment Variable: SEMDEX___LIB_LOG_RICH__GRAYLOG_LEVEL=WARNING
+# .env: LIB_LOG_RICH__GRAYLOG_LEVEL=WARNING
+# LIB_LOG_RICH__GRAYLOG_LEVEL=WARNING
+
+# --- Queue Settings ---
+
+# Purpose: Route log events through background queue worker (false = synchronous, blocks on I/O)
+# Type: boolean (true/false)
+# Default: true
+# Environment Variable: SEMDEX___LIB_LOG_RICH__QUEUE_ENABLED=true
+# .env: LIB_LOG_RICH__QUEUE_ENABLED=true
+# LIB_LOG_RICH__QUEUE_ENABLED=true
+
+# Purpose: Maximum pending events before queue full policy applies
+# Type: integer (> 0)
+# Default: 2048
+# Environment Variable: SEMDEX___LIB_LOG_RICH__QUEUE_MAXSIZE=2048
+# .env: LIB_LOG_RICH__QUEUE_MAXSIZE=2048
+# LIB_LOG_RICH__QUEUE_MAXSIZE=2048
+
+# Purpose: Behavior when queue is full
+# Type: string: "block" (wait for space), "drop" (discard events)
+# Default: "block"
+# Environment Variable: SEMDEX___LIB_LOG_RICH__QUEUE_FULL_POLICY=block
+# .env: LIB_LOG_RICH__QUEUE_FULL_POLICY=block
+# LIB_LOG_RICH__QUEUE_FULL_POLICY=block
+
+# Purpose: Timeout in seconds for blocking queue puts (0 = infinite wait)
+# Type: float (>= 0)
+# Default: 1.0
+# Environment Variable: SEMDEX___LIB_LOG_RICH__QUEUE_PUT_TIMEOUT=1.0
+# .env: LIB_LOG_RICH__QUEUE_PUT_TIMEOUT=1.0
+# LIB_LOG_RICH__QUEUE_PUT_TIMEOUT=1.0
+
+# Purpose: Maximum wait in seconds for queue drain during shutdown
+# Type: float (> 0)
+# Default: 5.0
+# Environment Variable: SEMDEX___LIB_LOG_RICH__QUEUE_STOP_TIMEOUT=5.0
+# .env: LIB_LOG_RICH__QUEUE_STOP_TIMEOUT=5.0
+# LIB_LOG_RICH__QUEUE_STOP_TIMEOUT=5.0
+
+# --- Ring Buffer ---
+
+# Purpose: Enable in-memory circular buffer for log history (enables log.dump())
+# Type: boolean (true/false)
+# Default: true
+# Environment Variable: SEMDEX___LIB_LOG_RICH__ENABLE_RING_BUFFER=true
+# .env: LIB_LOG_RICH__ENABLE_RING_BUFFER=true
+# LIB_LOG_RICH__ENABLE_RING_BUFFER=true
+
+# Purpose: Maximum events retained in ring buffer
+# Type: integer (> 0)
+# Default: 25000
+# Environment Variable: SEMDEX___LIB_LOG_RICH__RING_BUFFER_SIZE=25000
+# .env: LIB_LOG_RICH__RING_BUFFER_SIZE=25000
+# LIB_LOG_RICH__RING_BUFFER_SIZE=25000
+
+# --- Dump Format ---
+
+# Purpose: Default layout for text dumps
+# Type: string (case-insensitive): "full", "short", "full_loc", "short_loc"
+# Default: "full"
+# Environment Variable: SEMDEX___LIB_LOG_RICH__DUMP_FORMAT_PRESET=full
+# .env: LIB_LOG_RICH__DUMP_FORMAT_PRESET=full
+# LIB_LOG_RICH__DUMP_FORMAT_PRESET=full
+
+# Purpose: Custom template for text dumps (overrides preset)
+# Type: string (Python str.format template); empty = uses preset
+# Default: (empty, uses preset)
+# Environment Variable: SEMDEX___LIB_LOG_RICH__DUMP_FORMAT_TEMPLATE={timestamp_trimmed_naive_loc} {level_code} {message}
+# .env: LIB_LOG_RICH__DUMP_FORMAT_TEMPLATE={timestamp_trimmed_naive_loc} {level_code} {message}
+# LIB_LOG_RICH__DUMP_FORMAT_TEMPLATE={timestamp_trimmed_naive_loc} {level_code} {message}
+
+# --- Security & Payload ---
+
+# Purpose: Regex patterns to redact sensitive data (field = regex)
+# Type: table of field = regex; merged with the defaults
+# Default: password = .+, secret = .+, token = .+
+# Environment Variable, one key per field: SEMDEX___LIB_LOG_RICH__SCRUB_PATTERNS__API_KEY=.+
+# .env, one key per field: LIB_LOG_RICH__SCRUB_PATTERNS__API_KEY=.+
+# LIB_LOG_RICH__SCRUB_PATTERNS__API_KEY=.+
+
+# Purpose: Throttle log emissions (max_events per window_seconds)
+# Type: JSON array [max_events, window_seconds]; a "100:60" string is refused (config, index,
+#   search, serve, send-email and send-notification exit 78; only the native LOG_RATE_LIMIT
+#   variable takes MAX:WINDOW_SECONDS)
+# Default: (none, no rate limiting)
+# Environment Variable: SEMDEX___LIB_LOG_RICH__RATE_LIMIT='[100,60]'
+# .env: LIB_LOG_RICH__RATE_LIMIT=[100,60]
+# LIB_LOG_RICH__RATE_LIMIT=[100,60]
+
+# --- Payload Limits ---
+
+# Purpose: Truncate vs reject oversized messages
+# Type: boolean (true/false)
+# Default: true
+# Environment Variable: SEMDEX___LIB_LOG_RICH__PAYLOAD_LIMITS__TRUNCATE_MESSAGE=true
+# .env: LIB_LOG_RICH__PAYLOAD_LIMITS__TRUNCATE_MESSAGE=true
+# LIB_LOG_RICH__PAYLOAD_LIMITS__TRUNCATE_MESSAGE=true
+
+# Purpose: Maximum characters in primary log message
+# Type: integer
+# Default: 4096
+# Environment Variable: SEMDEX___LIB_LOG_RICH__PAYLOAD_LIMITS__MESSAGE_MAX_CHARS=4096
+# .env: LIB_LOG_RICH__PAYLOAD_LIMITS__MESSAGE_MAX_CHARS=4096
+# LIB_LOG_RICH__PAYLOAD_LIMITS__MESSAGE_MAX_CHARS=4096
+
+# Purpose: Maximum keys in extra metadata dict
+# Type: integer
+# Default: 25
+# Environment Variable: SEMDEX___LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_KEYS=25
+# .env: LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_KEYS=25
+# LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_KEYS=25
+
+# Purpose: Maximum characters per extra value (after stringify)
+# Type: integer
+# Default: 512
+# Environment Variable: SEMDEX___LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_VALUE_CHARS=512
+# .env: LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_VALUE_CHARS=512
+# LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_VALUE_CHARS=512
+
+# Purpose: Maximum nesting depth for extra structures
+# Type: integer
+# Default: 3
+# Environment Variable: SEMDEX___LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_DEPTH=3
+# .env: LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_DEPTH=3
+# LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_DEPTH=3
+
+# Purpose: Total UTF-8 byte limit for sanitized extra payload
+# Type: integer
+# Default: 8192
+# Environment Variable: SEMDEX___LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_TOTAL_BYTES=8192
+# .env: LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_TOTAL_BYTES=8192
+# LIB_LOG_RICH__PAYLOAD_LIMITS__EXTRA_MAX_TOTAL_BYTES=8192
+
+# Purpose: Maximum keys in LogContext.extra
+# Type: integer
+# Default: 20
+# Environment Variable: SEMDEX___LIB_LOG_RICH__PAYLOAD_LIMITS__CONTEXT_MAX_KEYS=20
+# .env: LIB_LOG_RICH__PAYLOAD_LIMITS__CONTEXT_MAX_KEYS=20
+# LIB_LOG_RICH__PAYLOAD_LIMITS__CONTEXT_MAX_KEYS=20
+
+# Purpose: Maximum characters per context value
+# Type: integer
+# Default: 256
+# Environment Variable: SEMDEX___LIB_LOG_RICH__PAYLOAD_LIMITS__CONTEXT_MAX_VALUE_CHARS=256
+# .env: LIB_LOG_RICH__PAYLOAD_LIMITS__CONTEXT_MAX_VALUE_CHARS=256
+# LIB_LOG_RICH__PAYLOAD_LIMITS__CONTEXT_MAX_VALUE_CHARS=256
+
+# Purpose: Number of frames preserved in exception tracebacks
+# Type: integer
+# Default: 10
+# Environment Variable: SEMDEX___LIB_LOG_RICH__PAYLOAD_LIMITS__STACKTRACE_MAX_FRAMES=10
+# .env: LIB_LOG_RICH__PAYLOAD_LIMITS__STACKTRACE_MAX_FRAMES=10
+# LIB_LOG_RICH__PAYLOAD_LIMITS__STACKTRACE_MAX_FRAMES=10
+
+
+# ==============================================================================
+# Cloud-embedder live E2E keys (test-only)
+# ==============================================================================
+#
+# Real-API keys for the gemini / cohere embedding end-to-end cells in
+# tests/test_e2e_mcp_knowledge_matrix.py (marked local_only, excluded from CI).
+#
+# These are PLAIN environment variables, NOT the layered SEMDEX___ form: the
+# tests read them directly via os.environ (conftest loads .env into the process
+# environment), so the name is the SAME full literal in the shell and in .env.
+# They are deliberately DISTINCT from the production SEMDEX___EMBEDDING__API_KEY
+# so running the suite never touches a deployed key.
+#
+# A cell SKIPS when its key is unset, and also skips on a vendor 429 (free-tier
+# quota), so an unused key is fine. Leave it COMMENTED OUT: a bare name with no
+# "=" breaks the strict .env parser (LayerLoadError: Malformed line).
+
+# Google Gemini (gemini-embedding-001). Key from Google AI Studio.
+# SEMDEX_TEST_GEMINI_API_KEY=
+# Optional model override (default: gemini-embedding-001)
+# SEMDEX_TEST_GEMINI_MODEL=gemini-embedding-001
+
+# Cohere (embed-v4.0). Key from the Cohere dashboard.
+# SEMDEX_TEST_COHERE_API_KEY=
+# Optional model override (default: embed-v4.0)
+# SEMDEX_TEST_COHERE_MODEL=embed-v4.0