agent-tracedown-server 0.3.0__py3-none-any.whl

agent_tracedown_server-0.3.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: agent-tracedown-server
+Version: 0.3.0
+Summary: Tracedown server and CLI: root-cause analysis for AI agent runs, importers for Langfuse and OpenTelemetry, replay planning and a web viewer.
+Author: Naveen Nair
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/nbn07/agent-tracedown
+Project-URL: Source, https://github.com/nbn07/agent-tracedown
+Project-URL: Issues, https://github.com/nbn07/agent-tracedown/issues
+Keywords: ai-agents,llm,observability,debugging,root-cause-analysis,opentelemetry,tracing,langfuse
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agent-tracedown<0.4,>=0.3.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.29
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: chdb>=2; extra == "dev"
+Requires-Dist: pyjwt[crypto]>=2.8; extra == "dev"
+Requires-Dist: psycopg[binary]>=3.1; extra == "dev"
+Requires-Dist: psycopg-pool>=3.2; extra == "dev"
+Requires-Dist: redis>=5; extra == "dev"
+Provides-Extra: sso
+Requires-Dist: pyjwt[crypto]>=2.8; extra == "sso"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
+Requires-Dist: psycopg-pool>=3.2; extra == "postgres"
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == "redis"
+Provides-Extra: clickhouse
+Provides-Extra: kafka
+Requires-Dist: confluent-kafka>=2.3; extra == "kafka"
+Provides-Extra: enterprise
+Requires-Dist: pyjwt[crypto]>=2.8; extra == "enterprise"
+Requires-Dist: confluent-kafka>=2.3; extra == "enterprise"
+Requires-Dist: psycopg[binary]>=3.1; extra == "enterprise"
+Requires-Dist: psycopg-pool>=3.2; extra == "enterprise"
+Requires-Dist: redis>=5; extra == "enterprise"
+Dynamic: license-file
+
+# agent-tracedown-server
+
+The analysis side of [Tracedown](https://github.com/nbn07/agent-tracedown), the flight recorder for AI agents:
+
+- **Root-cause analysis.** AI stack traces that name the step that caused a failure, with an optional LLM judge.
+- **A "who is at fault" verdict** for every failed run: the agent, the user, or nobody yet.
+- **`tracedown-import`.** Diagnose runs you already record in Langfuse, Arize Phoenix or any OpenTelemetry exporter, with no code changes.
+- **`tracedown-server`.** Ingest API, web viewer, incidents, drift reports, analytics and replay diffs.
+
+```bash
+pip install agent-tracedown-server
+tracedown-import langfuse --errors-since 24h      # uses LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY
+tracedown-import otlp traces.json --failed
+tracedown-server --db tracedown.db                # http://localhost:7070
+```
+
+Benchmarks, including the cases where Tracedown loses to simple baselines, are in the [repository](https://github.com/nbn07/agent-tracedown#how-well-does-it-work). Licensed under Apache-2.0.

agent_tracedown_server-0.3.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+agent_tracedown_server-0.3.0.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+tracedown_server/__init__.py,sha256=KAb9rBSUUpJRSEK8Ufl0JT-6Nw_ScnL6d1L0QqStmpA,46
+tracedown_server/__main__.py,sha256=sow1hZbMzp1uHUPkhCuh4WmFO6VJDY8su3oFUFytOhs,2359
+tracedown_server/analytics.py,sha256=HVdNl2NmgYKpVwx2GQmWHJgnVgziUFdzig41diqJ-6M,11129
+tracedown_server/cache.py,sha256=ycaV4_gYQACatZ8rEVz7L9xh7q9f3ISYzkHEAKRMI_g,11355
+tracedown_server/otlp.py,sha256=mtZY_7dxY6zoLWkSCDK6Wzof_O1Ws832bYlmRh2OwNQ,3757
+tracedown_server/pipeline.py,sha256=eXPBPozIiDNwcK8nKjlLoC_XUKZaWxXSVrEu5a-h5ck,7866
+tracedown_server/pricing.py,sha256=SuajeBx56WTPP2uyoPcOQaIDGXK9W19Zs-AgxwLVrNQ,16634
+tracedown_server/api/__init__.py,sha256=JibMOrtPxJ1A48o1eZDb8-EjJelYlqhOIzJVLoXNwQs,33397
+tracedown_server/api/views.py,sha256=B9OIbcbO3WM5252UAkNy43hGFdIDOco2-pdVuvOi9f8,4407
+tracedown_server/claims/__init__.py,sha256=hFcf9PLY7lkCEsUonK--s-TUGYd27DE9aW4GTU5Vjt8,15252
+tracedown_server/drift/__init__.py,sha256=azul5u2laHHNSkaoTXH8RRWrPcgrj3VY8A73yqTaeGU,15975
+tracedown_server/enterprise/__init__.py,sha256=_NbSijRAhxSI-jgRMJttfAxkAbWBTML6lWadMzVbufU,2310
+tracedown_server/enterprise/audit.py,sha256=XcKLLLflgqlOItry_iUlaWlCCngb2TzoFw2pUnjDQrM,4538
+tracedown_server/enterprise/clickhouse.py,sha256=FLRUQdLrBrGDK5fg8_u3bhQq_r7Rh_67HsDrjSIo-eU,13517
+tracedown_server/enterprise/pii.py,sha256=EJr_mm7Ne6O7FHPc8RXIpYDmLIvMGnyUn2y8D_9HN98,7173
+tracedown_server/enterprise/queue.py,sha256=9f2QhAXjLsrH147pmF4B1Op7SO6ybCoGYGo65C9pLig,12497
+tracedown_server/enterprise/rbac.py,sha256=QtOgGXCDV7tTylq2Rzz_0EPXCCuXZlZqQvKpUFKI85o,11949
+tracedown_server/enterprise/sso.py,sha256=neBIMYNe0zB-0UK86G9mVZtsdM1lCtcn-n-tq1_WboQ,8443
+tracedown_server/importers/__init__.py,sha256=MGzl8wjMfzlXFFyWc2B9FAxRoBIoc7U1L0ycHaFsx3I,276
+tracedown_server/importers/cli.py,sha256=cyrNqs4oRIEFGsJzu8eFCOMTFrxhSXMq5WxsnsbYD6E,6676
+tracedown_server/importers/common.py,sha256=7RrUer1kHjimGluRYdi6AuZVXkKbjFYvOiKZUb0df3Q,9766
+tracedown_server/importers/langfuse.py,sha256=-xjMxIExm7VzkKk7m_0d4OfNfVaJVSpAgKhXheuKlE8,11358
+tracedown_server/importers/otel.py,sha256=Rfvjf0eWjV3zIttPW0HKmP-JCNRlozb0BRjoF1UbBAE,13747
+tracedown_server/incidents/__init__.py,sha256=EAf7RjEmXEm7cJIiiZ-RpXNc3LqsYT1Cx29WoNjVj0U,12454
+tracedown_server/incidents/hooks.py,sha256=gD7dlOl3RL5dMhTLIMzNebDg5jw1g_EPdpoVJEKlXI8,12467
+tracedown_server/rca/__init__.py,sha256=k86-9vIqdpUbK6LQ6TOpSdHlgpwJEB_qOTjIAmDPz2I,370
+tracedown_server/rca/detectors.py,sha256=_7G10EGrgM0pp71INlkxPsNb2cz0Hpj_Y9OQSI6psV8,20350
+tracedown_server/rca/engine.py,sha256=mor5mPUvgxWKcT8II912HiCQMHIdCPVu-oeMK7lDXg0,14319
+tracedown_server/rca/fault.py,sha256=7I4RK9F3U-703bCjqb33d_B1Nruov22Fo7rqXSmisic,9000
+tracedown_server/rca/judge.py,sha256=KwuFVU73bAlZ-A87jqS2D8QcGn2u6nhJUv_wUMLThDM,7243
+tracedown_server/replay/__init__.py,sha256=av5UEIVJNV-VrxgxdoR4GY-u-lIINzzx8ZK0NsIZbv4,4199
+tracedown_server/static/index.html,sha256=mQ6ueigxtdOgGNQM4lRpioynx1FAER9YRXDlHIU_fCQ,35683
+tracedown_server/storage/__init__.py,sha256=fPJNMztIqhdq86LJXXsm3PdKR0eRoddimNpT7JsrxP0,13719
+tracedown_server/storage/postgres.py,sha256=Y37J5ImEx7WqrMfZeU2gSCFFC6d6KXJ-M26d0I0pFfg,23359
+agent_tracedown_server-0.3.0.dist-info/METADATA,sha256=iAuuDvcK9lnoAR1PQhBmnaWLhVTk6A4Lg0Znbsx4hYc,3208
+agent_tracedown_server-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+agent_tracedown_server-0.3.0.dist-info/entry_points.txt,sha256=B9LeAn421uFAKY1sciQqidbi-AL0Dd7-TxFog5TJphY,181
+agent_tracedown_server-0.3.0.dist-info/top_level.txt,sha256=o97qBD5naLup63kOZtm3FEExDvp7pzxx0T0XPwnCTNM,17
+agent_tracedown_server-0.3.0.dist-info/RECORD,,

agent_tracedown_server-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_tracedown_server-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+tracedown-import = tracedown_server.importers.cli:main
+tracedown-server = tracedown_server.__main__:main
+tracedown-worker = tracedown_server.enterprise.queue:main

agent_tracedown_server-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

agent_tracedown_server-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tracedown_server

tracedown_server/__init__.py

@@ -0,0 +1,2 @@
+"""Tracedown server."""
+__version__ = "0.3.0"

tracedown_server/__main__.py

@@ -0,0 +1,47 @@
+"""``python -m tracedown_server`` / ``tracedown-server``.
+
+Dev profile: one process, SQLite (``--db``). Production profile: ``--database-url`` (Postgres),
+``--redis-url`` (shared cache and live feed) and ``--workers N``; any number of replicas behind
+a load balancer then behave as one server.
+"""
+import argparse
+import os
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="tracedown-server", description="Tracedown server")
+    p.add_argument("--host", default=os.environ.get("TDN_HOST", "127.0.0.1"))
+    p.add_argument("--port", type=int, default=int(os.environ.get("TDN_PORT", "7070")))
+    p.add_argument("--db", default=os.environ.get("TDN_DB", "agent_tracedown.db"),
+                   help="SQLite file (dev profile); ':memory:' for ephemeral")
+    p.add_argument("--database-url", default=os.environ.get("TDN_DATABASE_URL"),
+                   help="postgresql://user:pass@host:5432/db (production metadata store)")
+    p.add_argument("--redis-url", default=os.environ.get("TDN_REDIS_URL"),
+                   help="redis://host:6379/0 (shared cache, live feed and rate limits across replicas)")
+    p.add_argument("--workers", type=int, default=int(os.environ.get("TDN_WORKERS", "1")),
+                   help="server processes; more than 1 needs --database-url and --redis-url")
+    args = p.parse_args()
+    os.environ["TDN_DB"] = args.db
+    if args.database_url:
+        os.environ["TDN_DATABASE_URL"] = args.database_url
+    if args.redis_url:
+        os.environ["TDN_REDIS_URL"] = args.redis_url
+    if args.workers > 1 and not (args.database_url and args.redis_url):
+        p.error("--workers > 1 needs --database-url (Postgres) and --redis-url: SQLite and the in-process "
+                "live feed are per process")
+
+    import uvicorn
+
+    store = "Postgres" if args.database_url else f"SQLite {args.db}"
+    extra = ", Redis" if args.redis_url else ""
+    print(f"Tracedown listening on http://{args.host}:{args.port}  ({store}{extra}, {args.workers} worker(s))")
+    if args.workers > 1:
+        uvicorn.run("tracedown_server.api:create_app", factory=True, host=args.host, port=args.port,
+                    workers=args.workers, log_level="warning")
+    else:
+        from .api import create_app
+        uvicorn.run(create_app(), host=args.host, port=args.port, log_level="warning")
+
+
+if __name__ == "__main__":
+    main()

tracedown_server/analytics.py

@@ -0,0 +1,222 @@
+"""Agent performance analytics and Prometheus metrics.
+
+Computed from run profiles (written by the pipeline when a run finishes) and the
+span table:
+
+* success and failure rate, latency p50/p95, steps per run;
+* tokens and cost per task (and per *successful* task);
+* hallucination rate and response quality (share of answer claims that sources support);
+* tool reliability: calls, error rate, latency per tool;
+* retrieval effectiveness: empty and low-score rates, stale-chunk rate, and how often a
+  retrieval actually reached the final answer;
+* user feedback score when the SDK reports one (``run.feedback(score)``);
+* daily time series.
+
+Cost: see ``pricing``. A reported ``tdn.llm.cost_usd`` wins; otherwise tokens × the
+built-in price table for current Anthropic, OpenAI and Google models, overridden by
+``TDN_PRICES`` and ``PUT /api/v1/settings/prices``. Runs that used a model with no known
+price report their cost as unknown rather than zero.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections import Counter, defaultdict
+from typing import Any, Dict, List, Optional
+
+from . import pricing
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS settings (
+    key    TEXT PRIMARY KEY,
+    value  TEXT NOT NULL
+);
+"""
+
+
+def user_prices(store) -> Dict[str, Dict[str, Any]]:
+    """Prices saved through the API (they override the built-in table and ``TDN_PRICES``)."""
+    try:
+        rows = store.query("SELECT value FROM settings WHERE key='prices'")
+    except Exception:  # noqa: BLE001 - a bare store without the settings table
+        return {}
+    return json.loads(rows[0]["value"]) if rows else {}
+
+
+def get_prices(store) -> Dict[str, Dict[str, Any]]:
+    """Effective price table: built-in, then ``TDN_PRICES``, then saved prices."""
+    return pricing.merged(user_prices(store))
+
+
+def set_prices(store, prices: Dict[str, Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
+    """Save price overrides (merged over the built-in table; an empty object clears them)."""
+    pricing.validate(prices)
+    store.execute("INSERT INTO settings(key, value) VALUES ('prices', ?) "
+                  "ON CONFLICT(key) DO UPDATE SET value=excluded.value", (json.dumps(prices),))
+    return prices
+
+
+def _price_for(prices: Dict[str, Dict[str, Any]], model: Optional[str]) -> Optional[Dict[str, Any]]:
+    return pricing.price_for(prices, model)
+
+
+def run_cost(profile: Dict[str, Any], prices: Dict[str, Dict[str, Any]],
+             at_ns: Optional[int] = None) -> Optional[float]:
+    """Cost of a run in USD, or None when any model call in it has no known price."""
+    c = pricing.run_cost_from_profile(profile, prices, at_ns)
+    return c["cost_usd"] if c["cost_complete"] else None
+
+
+def _pct(xs: List[float], q: float) -> Optional[float]:
+    if not xs:
+        return None
+    xs = sorted(xs)
+    k = (len(xs) - 1) * q
+    lo, hi = int(k), min(int(k) + 1, len(xs) - 1)
+    return round(xs[lo] + (xs[hi] - xs[lo]) * (k - lo), 2)
+
+
+def overview(store, project: Optional[str] = None, agent: Optional[str] = None,
+             days: int = 7) -> Dict[str, Any]:
+    since = time.time_ns() - days * 86400 * 10 ** 9
+    runs = store.run_profiles(agent=agent, project=project, since_ns=since)
+    prices = get_prices(store)
+
+    by_agent: Dict[str, List[Dict[str, Any]]] = defaultdict(list)
+    for r in runs:
+        by_agent[r["agent_name"]].append(r)
+
+    def summarize(rs: List[Dict[str, Any]]) -> Dict[str, Any]:
+        f = [r["profile"]["features"] for r in rs]
+        n = len(f)
+        ok = sum(x["outcome"] == "success" for x in f)
+        costs = [run_cost(r["profile"], prices, r["started_at"]) for r in rs]
+        known = [c for c in costs if c is not None]
+        answered = [x["claims"] for x in f if x.get("claims") and x["claims"]["claims"] > 0
+                    and x["claims"]["evidence_units"] > 1]
+        halluc = sum(1 for c in answered if c["unsupported"] + c["contradicted"] > 0)
+        quality = [c["supported"] / c["claims"] for c in answered]
+        fb = [x["feedback"] for x in f if isinstance(x.get("feedback"), (int, float))]
+        return {
+            "runs": n, "successes": ok, "failures": n - ok,
+            "success_rate": round(ok / n, 4) if n else None,
+            "failure_rate": round(1 - ok / n, 4) if n else None,
+            "latency_ms": {"p50": _pct([x["duration_ms"] for x in f], 0.5), "p95": _pct([x["duration_ms"] for x in f], 0.95)},
+            "steps_per_run": round(sum(x["steps"] for x in f) / n, 2) if n else None,
+            "tokens": {"total": sum(x["tokens"] for x in f), "per_run": round(sum(x["tokens"] for x in f) / n, 1) if n else None},
+            "cost_usd": {
+                "total": round(sum(known), 6) if known else None,
+                "per_task": round(sum(known) / len(known), 6) if known else None,
+                "per_successful_task": round(sum(known) / ok, 6) if known and ok and len(known) == n else None,
+                "runs_without_price": n - len(known),
+            },
+            "hallucination_rate": round(halluc / len(answered), 4) if answered else None,
+            "response_quality": round(sum(quality) / len(quality), 4) if quality else None,
+            "feedback_score": round(sum(fb) / len(fb), 3) if fb else None,
+            "top_root_causes": Counter(x["root_cause"] for x in f if x.get("root_cause")).most_common(5),
+        }
+
+    # Retrieval effectiveness, per retriever source.
+    retr: Dict[str, Dict[str, Any]] = defaultdict(lambda: {"queries": 0, "empty": 0, "low_score": 0,
+                                                          "stale_hits": 0, "used": 0, "used_known": 0, "scores": []})
+    for r in runs:
+        for x in r["profile"]["features"].get("retrieval", []):
+            e = retr[x["source"]]
+            e["queries"] += 1
+            e["empty"] += x["chunks"] == 0
+            if isinstance(x.get("max_score"), (int, float)):
+                e["scores"].append(x["max_score"])
+                e["low_score"] += x["max_score"] < 0.5
+            e["stale_hits"] += x["stale"] > 0
+            if x.get("used") is not None:
+                e["used_known"] += 1
+                e["used"] += bool(x["used"])
+    retrieval = [{
+        "source": src, "queries": e["queries"],
+        "empty_rate": round(e["empty"] / e["queries"], 4), "low_score_rate": round(e["low_score"] / e["queries"], 4),
+        "stale_rate": round(e["stale_hits"] / e["queries"], 4),
+        "avg_max_score": round(sum(e["scores"]) / len(e["scores"]), 3) if e["scores"] else None,
+        "reached_answer_rate": round(e["used"] / e["used_known"], 4) if e["used_known"] else None,
+    } for src, e in sorted(retr.items())]
+
+    daily: Dict[str, Dict[str, Any]] = defaultdict(lambda: {"runs": 0, "failures": 0, "cost_usd": 0.0,
+                                                           "cost_by_agent": defaultdict(float)})
+    for r in runs:
+        day = time.strftime("%Y-%m-%d", time.gmtime(r["started_at"] / 1e9))
+        d = daily[day]
+        d["runs"] += 1
+        d["failures"] += r["profile"]["features"]["outcome"] == "failure"
+        # priced steps count even when another step in the run has no price
+        c = pricing.run_cost_from_profile(r["profile"], prices, r["started_at"])["cost_usd"] or 0
+        d["cost_usd"] = round(d["cost_usd"] + c, 6)
+        d["cost_by_agent"][r["agent_name"]] += c
+    for d in daily.values():
+        d["cost_by_agent"] = {a: round(v, 6) for a, v in sorted(d["cost_by_agent"].items())}
+
+    return {
+        "window_days": days, "project": project, "agent": agent,
+        "overall": summarize(runs),
+        "agents": {a: summarize(rs) for a, rs in sorted(by_agent.items())},
+        "tools": store.tool_stats(project, since),
+        "retrieval": retrieval,
+        "daily": [{"day": k, **v} for k, v in sorted(daily.items())],
+        "models": pricing.by_model(runs, prices),
+        "prices_configured": sorted(prices),
+    }
+
+
+# ----------------------------------------------------------------------------- Prometheus
+
+def _esc(v: Any) -> str:
+    return str(v).replace("\\", "\\\\").replace('"', '\\"').replace("\n", " ")
+
+
+def prometheus(store, project: Optional[str] = None) -> str:
+    """Prometheus text exposition (cumulative over retained data)."""
+    runs = store.run_profiles(project=project)
+    prices = get_prices(store)
+    lines: List[str] = []
+
+    def metric(name, kind, help_, samples):
+        lines.append(f"# HELP {name} {help_}")
+        lines.append(f"# TYPE {name} {kind}")
+        for labels, value in samples:
+            lab = ",".join(f'{k}="{_esc(v)}"' for k, v in labels.items())
+            lines.append(f"{name}{{{lab}}} {value}" if lab else f"{name} {value}")
+
+    c_runs, c_tok, c_cost, c_hall, c_rc = Counter(), Counter(), Counter(), Counter(), Counter()
+    for r in runs:
+        f = r["profile"]["features"]
+        c_runs[(r["project"], r["agent_name"], f["outcome"])] += 1
+        for call in f.get("llm", []):
+            c_tok[(call.get("model") or "unknown", "input")] += call["input_tokens"]
+            c_tok[(call.get("model") or "unknown", "output")] += call["output_tokens"]
+            usd, _ = pricing.call_cost(call, prices, call.get("at_ns") or r.get("started_at"))
+            if usd is not None:
+                c_cost[call.get("model") or "unknown"] += usd
+        cl = f.get("claims")
+        if cl and cl["unsupported"] + cl["contradicted"] > 0:
+            c_hall[(r["project"], r["agent_name"])] += 1
+        for cat in f.get("categories", []):
+            c_rc[(r["agent_name"], cat)] += 1
+    metric("tdn_runs_total", "counter", "Agent runs by outcome.",
+           [({"project": p, "agent": a, "outcome": o}, n) for (p, a, o), n in sorted(c_runs.items())])
+    metric("tdn_llm_tokens_total", "counter", "LLM tokens by model and direction.",
+           [({"model": m, "direction": d}, n) for (m, d), n in sorted(c_tok.items())])
+    metric("tdn_llm_cost_usd_total", "counter", "LLM cost in USD (priced models only).",
+           [({"model": m}, round(v, 6)) for m, v in sorted(c_cost.items())])
+    metric("tdn_hallucination_runs_total", "counter", "Runs with at least one unsupported or contradicted claim.",
+           [({"project": p, "agent": a}, n) for (p, a), n in sorted(c_hall.items())])
+    metric("tdn_rca_findings_total", "counter", "Runs with a finding of each root-cause category.",
+           [({"agent": a, "category": c}, n) for (a, c), n in sorted(c_rc.items())])
+    tools = store.tool_stats(project, None)
+    metric("tdn_tool_calls_total", "counter", "Tool calls.", [({"tool": t["tool"]}, t["calls"]) for t in tools])
+    metric("tdn_tool_errors_total", "counter", "Tool calls that failed.", [({"tool": t["tool"]}, t["errors"]) for t in tools])
+    try:
+        open_inc = store.query("SELECT severity, COUNT(*) n FROM incidents WHERE status != 'resolved' GROUP BY severity")
+    except Exception:  # noqa: BLE001 - incidents table may not exist on a bare store
+        open_inc = []
+    metric("tdn_incidents_open", "gauge", "Open incidents by severity.",
+           [({"severity": r["severity"]}, r["n"]) for r in open_inc])
+    return "\n".join(lines) + "\n"