tdqs 0.1.0__tar.gz

tdqs-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: tdqs
+Version: 0.1.0
+Summary: Reference implementation of the Tool Definition Quality Score (TDQS): score how well an MCP tool definition communicates to an AI agent.
+Keywords: lint,mcp,model-context-protocol,quality,tdqs,tool-definition
+Author: Glama
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Dist: anyio>=4.0
+Requires-Dist: exceptiongroup>=1.2 ; python_full_version < '3.11'
+Requires-Dist: httpx>=0.28
+Requires-Dist: mcp>=2.0,<3
+Requires-Dist: pydantic>=2.11
+Requires-Dist: typing-extensions>=4.12
+Requires-Python: >=3.10
+Project-URL: Homepage, https://tdqs.dev
+Project-URL: Repository, https://github.com/glama-ai/tdqs
+Project-URL: Specification, https://github.com/glama-ai/tool-definition-quality-score
+Description-Content-Type: text/markdown
+
+# tdqs
+
+The [Tool Definition Quality Score](https://github.com/glama-ai/tool-definition-quality-score) (TDQS) for Python: a CLI and a library that score how well an MCP tool definition communicates to an AI agent, exactly as the specification defines it. It is the same reference implementation that ships for Node as the `tdqs` npm package, stage for stage, and the two produce the same numbers, the same hashes and the same prompts.
+
+TDQS scores a **definition**, not behaviour. The inputs are what an MCP client sees from `tools/list` — name, title, description, input schema, output schema, annotations — and the output is a score from 1.0 to 5.0 with a letter tier, per tool and per server, with a justification for every dimension.
+
+## Install
+
+```bash
+pip install tdqs
+# or run it without installing
+uvx tdqs --help
+```
+
+Python 3.10 or newer.
+
+## Lint: deterministic, no model, no key
+
+```bash
+tdqs lint --file tools.json
+tdqs lint --command "uvx my-mcp-server"
+tdqs lint --url https://mcp.example.com/mcp --header "Authorization: Bearer …"
+```
+
+`lint` runs the stages of the pipeline that need no model: the context signals (parameter counts, schema description coverage, annotation values, invocation cost, the definition's hash and byte size), the hard gates (no description, tautological description), the shadow prefilter across the tool set, and the checklist the specification ranks highest. It exits `1` on an error-level finding, which makes it a pull request check:
+
+```bash
+tdqs lint --file tools.json --fail-on warning --format markdown --output tdqs-lint.md
+```
+
+A lint finding names a fix. It is not a score, and it never pretends to be one.
+
+## Score: the full rubric
+
+```bash
+export TDQS_BASE_URL=https://api.openai.com/v1   # any OpenAI-compatible endpoint
+export TDQS_API_KEY=…
+export TDQS_MODEL=…
+
+tdqs score --file tools.json
+tdqs score --command "uvx my-mcp-server" --fail-under B --format markdown
+```
+
+`score` sends every tool through the rubric (six dimensions, 1–5 each, with the specification's system prompt verbatim), runs the server coherence evaluation (four dimensions plus shadowing-risk confirmation), and rolls both up into the server score with integer arithmetic. The report is stamped with the specification version and the model, because a score is calibrated to a rubric+model pair and is not comparable to anything without both.
+
+Turn extended reasoning off. The reference model reasons before it answers unless told not to, which makes a call take a minute instead of seconds — and the specification's calibration examples reproduce with reasoning **off**. How to say so is provider-specific, so it is an opaque JSON object merged into every request:
+
+```bash
+tdqs score --file tools.json --request-overrides '{"reasoning":{"enabled":false}}'   # OpenRouter
+# or TDQS_REQUEST_OVERRIDES in the environment; DeepSeek directly takes {"thinking":{"type":"disabled"}}
+```
+
+`--hosted https://tdqs.dev` scores through a hosted TDQS site instead of a model key of your own, and prints the report's URL. It takes that site's API key as `--api-key` or `TDQS_API_KEY`; the site's account page is where keys come from.
+
+Input is exactly one of `--file` (a `tools/list` result, an array of tools, or a single tool; `-` reads stdin), `--command` (a stdio server) or `--url` (a Streamable HTTP server).
+
+| Exit code | Meaning                                                                    |
+| --------- | -------------------------------------------------------------------------- |
+| `0`       | done                                                                       |
+| `1`       | the threshold was not met (`--fail-on` for lint, `--fail-under` for score) |
+| `2`       | usage error, unreadable input, unreachable server, or a model failure      |
+
+`--format` is `text` (default), `markdown` or `json`. The JSON formats are the ones the npm package publishes as JSON Schema, `schemas/score-report.json` and `schemas/lint-report.json`.
+
+## Library
+
+```python
+from tdqs import create_llm_client, lint_server, parse_tool_definitions, score_server
+
+parsed = parse_tool_definitions(response.json())
+server_name = parsed.server_name or "my-server"
+
+# No model involved.
+lint = lint_server(server_name=server_name, tools=parsed.tools)
+
+# The full pipeline.
+report = score_server(
+    llm=create_llm_client(
+        api_key=api_key,
+        base_url=base_url,
+        model=model,
+        request_overrides={"reasoning": {"enabled": False}},
+    ),
+    server_name=server_name,
+    tools=parsed.tools,
+)
+
+report.server_score.overall_tier  # "A" | "B" | "C" | "D" | "F"
+report.tools[0].justifications["usage_guidelines"]  # Justification(score=…, justification=…)
+report.model_dump()  # the specification's JSON, camelCase keys
+```
+
+Every stage is exported on its own — `compute_context_signals`, `evaluate_hard_gates`, `compute_tdqs`, `find_shadow_candidates`, `build_tool_scoring_prompt`, `score_tool_definition`, `score_server_coherence`, `rollup_server_score` — along with the specification's metadata (`TOOL_DIMENSIONS`, `COHERENCE_DIMENSIONS`, `FLAGS`, `TIERS`, `LINT_RULES`, `SPEC_VERSION`) and the two system prompts, so a registry or a gateway can build on the same pieces. Reports are pydantic models; `model_dump()` is the specification's JSON and `ScoreReport.model_validate()` reads it back.
+
+`request_hosted_report(...)` is the hosted mode as a function: it submits the definitions to a TDQS site and polls until the report is done.
+
+## What is deterministic and what is not
+
+Stages 1, 2 and 4 of the pipeline, the shadow prefilter, and every rollup are deterministic and reproducible from the definitions alone; `inputHash` is computed the same way the Glama registry computes it, so a hash here matches the one on a server's public score page. Stage 3 — the rubric — and the coherence evaluation are model calls. The specification pins the prompts, the output contract and the calibration examples; the model is the remaining variable, which is why every report names it. Swap models and expect to re-score.
+
+## Specification
+
+This package follows TDQS **1.2**. The prompts are compared byte for byte against the specification in the test suite, and the deterministic stages are compared against the Node reference implementation's fixtures, so the implementations cannot drift apart silently.

tdqs-0.1.0/README.md

@@ -0,0 +1,103 @@
+# tdqs
+
+The [Tool Definition Quality Score](https://github.com/glama-ai/tool-definition-quality-score) (TDQS) for Python: a CLI and a library that score how well an MCP tool definition communicates to an AI agent, exactly as the specification defines it. It is the same reference implementation that ships for Node as the `tdqs` npm package, stage for stage, and the two produce the same numbers, the same hashes and the same prompts.
+
+TDQS scores a **definition**, not behaviour. The inputs are what an MCP client sees from `tools/list` — name, title, description, input schema, output schema, annotations — and the output is a score from 1.0 to 5.0 with a letter tier, per tool and per server, with a justification for every dimension.
+
+## Install
+
+```bash
+pip install tdqs
+# or run it without installing
+uvx tdqs --help
+```
+
+Python 3.10 or newer.
+
+## Lint: deterministic, no model, no key
+
+```bash
+tdqs lint --file tools.json
+tdqs lint --command "uvx my-mcp-server"
+tdqs lint --url https://mcp.example.com/mcp --header "Authorization: Bearer …"
+```
+
+`lint` runs the stages of the pipeline that need no model: the context signals (parameter counts, schema description coverage, annotation values, invocation cost, the definition's hash and byte size), the hard gates (no description, tautological description), the shadow prefilter across the tool set, and the checklist the specification ranks highest. It exits `1` on an error-level finding, which makes it a pull request check:
+
+```bash
+tdqs lint --file tools.json --fail-on warning --format markdown --output tdqs-lint.md
+```
+
+A lint finding names a fix. It is not a score, and it never pretends to be one.
+
+## Score: the full rubric
+
+```bash
+export TDQS_BASE_URL=https://api.openai.com/v1   # any OpenAI-compatible endpoint
+export TDQS_API_KEY=…
+export TDQS_MODEL=…
+
+tdqs score --file tools.json
+tdqs score --command "uvx my-mcp-server" --fail-under B --format markdown
+```
+
+`score` sends every tool through the rubric (six dimensions, 1–5 each, with the specification's system prompt verbatim), runs the server coherence evaluation (four dimensions plus shadowing-risk confirmation), and rolls both up into the server score with integer arithmetic. The report is stamped with the specification version and the model, because a score is calibrated to a rubric+model pair and is not comparable to anything without both.
+
+Turn extended reasoning off. The reference model reasons before it answers unless told not to, which makes a call take a minute instead of seconds — and the specification's calibration examples reproduce with reasoning **off**. How to say so is provider-specific, so it is an opaque JSON object merged into every request:
+
+```bash
+tdqs score --file tools.json --request-overrides '{"reasoning":{"enabled":false}}'   # OpenRouter
+# or TDQS_REQUEST_OVERRIDES in the environment; DeepSeek directly takes {"thinking":{"type":"disabled"}}
+```
+
+`--hosted https://tdqs.dev` scores through a hosted TDQS site instead of a model key of your own, and prints the report's URL. It takes that site's API key as `--api-key` or `TDQS_API_KEY`; the site's account page is where keys come from.
+
+Input is exactly one of `--file` (a `tools/list` result, an array of tools, or a single tool; `-` reads stdin), `--command` (a stdio server) or `--url` (a Streamable HTTP server).
+
+| Exit code | Meaning                                                                    |
+| --------- | -------------------------------------------------------------------------- |
+| `0`       | done                                                                       |
+| `1`       | the threshold was not met (`--fail-on` for lint, `--fail-under` for score) |
+| `2`       | usage error, unreadable input, unreachable server, or a model failure      |
+
+`--format` is `text` (default), `markdown` or `json`. The JSON formats are the ones the npm package publishes as JSON Schema, `schemas/score-report.json` and `schemas/lint-report.json`.
+
+## Library
+
+```python
+from tdqs import create_llm_client, lint_server, parse_tool_definitions, score_server
+
+parsed = parse_tool_definitions(response.json())
+server_name = parsed.server_name or "my-server"
+
+# No model involved.
+lint = lint_server(server_name=server_name, tools=parsed.tools)
+
+# The full pipeline.
+report = score_server(
+    llm=create_llm_client(
+        api_key=api_key,
+        base_url=base_url,
+        model=model,
+        request_overrides={"reasoning": {"enabled": False}},
+    ),
+    server_name=server_name,
+    tools=parsed.tools,
+)
+
+report.server_score.overall_tier  # "A" | "B" | "C" | "D" | "F"
+report.tools[0].justifications["usage_guidelines"]  # Justification(score=…, justification=…)
+report.model_dump()  # the specification's JSON, camelCase keys
+```
+
+Every stage is exported on its own — `compute_context_signals`, `evaluate_hard_gates`, `compute_tdqs`, `find_shadow_candidates`, `build_tool_scoring_prompt`, `score_tool_definition`, `score_server_coherence`, `rollup_server_score` — along with the specification's metadata (`TOOL_DIMENSIONS`, `COHERENCE_DIMENSIONS`, `FLAGS`, `TIERS`, `LINT_RULES`, `SPEC_VERSION`) and the two system prompts, so a registry or a gateway can build on the same pieces. Reports are pydantic models; `model_dump()` is the specification's JSON and `ScoreReport.model_validate()` reads it back.
+
+`request_hosted_report(...)` is the hosted mode as a function: it submits the definitions to a TDQS site and polls until the report is done.
+
+## What is deterministic and what is not
+
+Stages 1, 2 and 4 of the pipeline, the shadow prefilter, and every rollup are deterministic and reproducible from the definitions alone; `inputHash` is computed the same way the Glama registry computes it, so a hash here matches the one on a server's public score page. Stage 3 — the rubric — and the coherence evaluation are model calls. The specification pins the prompts, the output contract and the calibration examples; the model is the remaining variable, which is why every report names it. Swap models and expect to re-score.
+
+## Specification
+
+This package follows TDQS **1.2**. The prompts are compared byte for byte against the specification in the test suite, and the deterministic stages are compared against the Node reference implementation's fixtures, so the implementations cannot drift apart silently.

tdqs-0.1.0/pyproject.toml

@@ -0,0 +1,120 @@
+[project]
+name = "tdqs"
+version = "0.1.0"
+description = "Reference implementation of the Tool Definition Quality Score (TDQS): score how well an MCP tool definition communicates to an AI agent."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+keywords = [
+    "lint",
+    "mcp",
+    "model-context-protocol",
+    "quality",
+    "tdqs",
+    "tool-definition",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+dependencies = [
+    "anyio>=4.0",
+    "exceptiongroup>=1.2; python_version < '3.11'",
+    "httpx>=0.28",
+    "mcp>=2.0,<3",
+    "pydantic>=2.11",
+    "typing-extensions>=4.12",
+]
+
+[[project.authors]]
+name = "Glama"
+
+[project.urls]
+Homepage = "https://tdqs.dev"
+Repository = "https://github.com/glama-ai/tdqs"
+Specification = "https://github.com/glama-ai/tool-definition-quality-score"
+
+[project.scripts]
+tdqs = "tdqs.cli.main:main"
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "exceptiongroup>=1.2",
+    "mypy>=2.0",
+    "pytest>=9.0",
+    "ruff>=0.16",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "ARG",
+    "B",
+    "C4",
+    "E",
+    "ERA",
+    "F",
+    "I",
+    "ISC",
+    "N",
+    "PERF",
+    "PIE",
+    "PL",
+    "PT",
+    "PTH",
+    "RET",
+    "RUF",
+    "SIM",
+    "TRY",
+    "UP",
+    "W",
+]
+ignore = [
+    "E501",
+    "PLR0911",
+    "PLR0912",
+    "PLR0913",
+    "PLR0915",
+    "PLR2004",
+    "RUF001",
+    "RUF002",
+    "RUF003",
+    "TRY003",
+    "TRY301",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "PLR0917",
+    "PLR2004",
+]
+
+[tool.mypy]
+files = [
+    "src",
+    "tests",
+]
+plugins = ["pydantic.mypy"]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tdqs-0.1.0/pyproject.toml.orig

@@ -0,0 +1,104 @@
+[project]
+name = "tdqs"
+version = "0.1.0"
+description = "Reference implementation of the Tool Definition Quality Score (TDQS): score how well an MCP tool definition communicates to an AI agent."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "Glama" }]
+keywords = ["lint", "mcp", "model-context-protocol", "quality", "tdqs", "tool-definition"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Quality Assurance",
+  "Typing :: Typed",
+]
+# `mcp` is the official client, used to read `tools/list` from a live server; `httpx` and
+# `pydantic` are what it is built on, declared here because this package imports them directly.
+dependencies = [
+  "anyio>=4.0",
+  "exceptiongroup>=1.2; python_version < '3.11'",
+  "httpx>=0.28",
+  "mcp>=2.0,<3",
+  "pydantic>=2.11",
+  "typing-extensions>=4.12",
+]
+
+[project.urls]
+Homepage = "https://tdqs.dev"
+Repository = "https://github.com/glama-ai/tdqs"
+Specification = "https://github.com/glama-ai/tool-definition-quality-score"
+
+[project.scripts]
+tdqs = "tdqs.cli.main:main"
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+# `exceptiongroup` is only a runtime dependency below Python 3.11, but mypy checks that branch
+# on every interpreter and needs its types.
+dev = ["exceptiongroup>=1.2", "mypy>=2.0", "pytest>=9.0", "ruff>=0.16"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+  "A",    # shadowed builtins
+  "ARG",  # unused arguments
+  "B",    # bugbear
+  "C4",   # comprehensions
+  "E",    # pycodestyle errors
+  "ERA",  # commented-out code
+  "F",    # pyflakes
+  "I",    # import order
+  "ISC",  # implicit string concatenation
+  "N",    # naming
+  "PERF", # performance
+  "PIE",  # misc lints
+  "PL",   # pylint
+  "PT",   # pytest style
+  "PTH",  # pathlib
+  "RET",  # return statements
+  "RUF",  # ruff's own
+  "SIM",  # simplification
+  "TRY",  # exception handling
+  "UP",   # modern syntax
+  "W",    # pycodestyle warnings
+]
+ignore = [
+  "E501",    # line length: the formatter lays code out, and the specification's strings are long
+  "PLR0911", # too many return statements: the parsers are dispatch tables
+  "PLR0912", # too many branches: the CLI parser and the schema traversal are long by nature
+  "PLR0913", # too many arguments: keyword-only signatures are the interface, like the TS package
+  "PLR0915", # too many statements
+  "PLR2004", # magic values: the specification's constants are documented where they are used
+  "RUF001",  # ambiguous unicode: the specification's own text uses dashes and arrows, verbatim
+  "RUF002",
+  "RUF003",
+  "TRY003",  # long exception messages: the messages are the interface
+  "TRY301",  # raise inside try: the CLI raises usage errors where the usage handler catches them
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["PLR0917", "PLR2004"]
+
+[tool.mypy]
+files = ["src", "tests"]
+plugins = ["pydantic.mypy"]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tdqs-0.1.0/src/tdqs/__init__.py

@@ -0,0 +1,153 @@
+"""The reference implementation of the Tool Definition Quality Score, for Python.
+
+The package's public surface. The modules are one export each; this is the one stable entry
+point, so `from tdqs import score_server` keeps working when a module moves.
+"""
+
+from tdqs.build_server_coherence_prompt import CoherencePromptTool, build_server_coherence_prompt
+from tdqs.build_tool_scoring_prompt import build_tool_scoring_prompt
+from tdqs.compute_context_signals import compute_context_signals
+from tdqs.compute_input_hash import compute_input_hash
+from tdqs.compute_invocation_cost import compute_invocation_cost
+from tdqs.compute_smells import compute_smells
+from tdqs.compute_tdqs import compute_tdqs
+from tdqs.compute_tier import compute_tier
+from tdqs.context_signals import AnnotationValues, ContextSignals
+from tdqs.create_llm_client import OpenAiCompatibleLlmClient, create_llm_client
+from tdqs.evaluate_hard_gates import HardGateResult, evaluate_hard_gates
+from tdqs.find_shadow_candidates import CostedTool, ShadowCandidate, find_shadow_candidates
+from tdqs.format_lint_report_markdown import format_lint_report_markdown
+from tdqs.format_score_report_markdown import format_score_report_markdown
+from tdqs.lint_report import LintedTool, LintFinding, LintReport, ServerSummary
+from tdqs.lint_rules import LINT_RULES, LintRule, LintRuleKey, LintSeverity
+from tdqs.lint_server import lint_server
+from tdqs.llm_client import LlmClient
+from tdqs.load_tool_definitions import load_tool_definitions
+from tdqs.package_version import PACKAGE_VERSION
+from tdqs.parse_tool_definitions import ParsedToolDefinitions, parse_tool_definitions
+from tdqs.prompts.server_coherence_system_prompt import SERVER_COHERENCE_SYSTEM_PROMPT
+from tdqs.prompts.tool_scoring_system_prompt import TOOL_SCORING_SYSTEM_PROMPT
+from tdqs.request_hosted_report import HostedReport, HostedReportStatus, request_hosted_report
+from tdqs.rollup_server_score import rollup_server_score
+from tdqs.round1 import round1
+from tdqs.score_report import ScoreReport
+from tdqs.score_server import score_server
+from tdqs.score_server_coherence import ServerCoherence, score_server_coherence
+from tdqs.score_tool_definition import score_tool_definition
+from tdqs.serialize_tool_definition import serialize_tool_definition
+from tdqs.server_score import (
+    CoherenceJustifications,
+    CoherenceScores,
+    ServerScore,
+    ShadowingRisk,
+)
+from tdqs.spec.coherence_dimensions import (
+    COHERENCE_DIMENSIONS,
+    CoherenceDimension,
+    CoherenceDimensionKey,
+)
+from tdqs.spec.flags import FLAGS, Flag, HardGateFlag, ServerFlag, ToolFlag
+from tdqs.spec.spec_version import SPEC_VERSION
+from tdqs.spec.tiers import TIERS, Tier, TierDefinition
+from tdqs.spec.tool_dimensions import (
+    TOOL_DIMENSIONS,
+    DimensionScore,
+    ToolDimension,
+    ToolDimensionKey,
+)
+from tdqs.stringify_json import stringify_json
+from tdqs.tdqs_input_error import TdqsInputError
+from tdqs.tdqs_llm_error import TdqsLlmError
+from tdqs.tool_definition import ToolDefinition
+from tdqs.tool_definitions_source import (
+    CommandSource,
+    FileSource,
+    ToolDefinitionsSource,
+    UrlSource,
+)
+from tdqs.tool_score import DimensionJustifications, DimensionScores, Justification, ToolScore
+from tdqs.traverse_required_subtree import RequiredSubtreeSignals, traverse_required_subtree
+
+__all__ = [
+    "COHERENCE_DIMENSIONS",
+    "FLAGS",
+    "LINT_RULES",
+    "PACKAGE_VERSION",
+    "SERVER_COHERENCE_SYSTEM_PROMPT",
+    "SPEC_VERSION",
+    "TIERS",
+    "TOOL_DIMENSIONS",
+    "TOOL_SCORING_SYSTEM_PROMPT",
+    "AnnotationValues",
+    "CoherenceDimension",
+    "CoherenceDimensionKey",
+    "CoherenceJustifications",
+    "CoherencePromptTool",
+    "CoherenceScores",
+    "CommandSource",
+    "ContextSignals",
+    "CostedTool",
+    "DimensionJustifications",
+    "DimensionScore",
+    "DimensionScores",
+    "FileSource",
+    "Flag",
+    "HardGateFlag",
+    "HardGateResult",
+    "HostedReport",
+    "HostedReportStatus",
+    "Justification",
+    "LintFinding",
+    "LintReport",
+    "LintRule",
+    "LintRuleKey",
+    "LintSeverity",
+    "LintedTool",
+    "LlmClient",
+    "OpenAiCompatibleLlmClient",
+    "ParsedToolDefinitions",
+    "RequiredSubtreeSignals",
+    "ScoreReport",
+    "ServerCoherence",
+    "ServerFlag",
+    "ServerScore",
+    "ServerSummary",
+    "ShadowCandidate",
+    "ShadowingRisk",
+    "TdqsInputError",
+    "TdqsLlmError",
+    "Tier",
+    "TierDefinition",
+    "ToolDefinition",
+    "ToolDefinitionsSource",
+    "ToolDimension",
+    "ToolDimensionKey",
+    "ToolFlag",
+    "ToolScore",
+    "UrlSource",
+    "build_server_coherence_prompt",
+    "build_tool_scoring_prompt",
+    "compute_context_signals",
+    "compute_input_hash",
+    "compute_invocation_cost",
+    "compute_smells",
+    "compute_tdqs",
+    "compute_tier",
+    "create_llm_client",
+    "evaluate_hard_gates",
+    "find_shadow_candidates",
+    "format_lint_report_markdown",
+    "format_score_report_markdown",
+    "lint_server",
+    "load_tool_definitions",
+    "parse_tool_definitions",
+    "request_hosted_report",
+    "rollup_server_score",
+    "round1",
+    "score_server",
+    "score_server_coherence",
+    "score_tool_definition",
+    "serialize_tool_definition",
+    "stringify_json",
+    "traverse_required_subtree",
+]

tdqs-0.1.0/src/tdqs/__main__.py

@@ -0,0 +1,3 @@
+from tdqs.cli.main import main
+
+main()

tdqs-0.1.0/src/tdqs/build_server_coherence_prompt.py

@@ -0,0 +1,63 @@
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from tdqs.context_signals import ContextSignals
+from tdqs.find_shadow_candidates import ShadowCandidate
+from tdqs.sanitize_for_prompt import sanitize_for_prompt
+
+
+@dataclass(frozen=True)
+class CoherencePromptTool:
+    context_signals: ContextSignals
+    description: str | None
+    name: str
+
+
+def build_server_coherence_prompt(
+    *,
+    server_name: str,
+    shadow_candidates: Sequence[ShadowCandidate],
+    tools: Sequence[CoherencePromptTool],
+) -> str:
+    """The user message of the coherence call, in the specification's template: every tool with
+    its invocation cost and the three signals behind it, then the candidate pairs the prefilter
+    emitted. The model is told to judge only those pairs, which is why they are spelled out rather
+    than left for it to find."""
+    tool_lines: list[str] = []
+
+    for tool in tools:
+        signals = tool.context_signals
+        cost = (
+            f"cost {signals.invocation_cost}: {signals.required_field_count} required, "
+            f"depth {signals.schema_depth}, {signals.union_choice_count} union choices"
+        )
+        text = (
+            "(no description)"
+            if tool.description is None
+            else str(sanitize_for_prompt(tool.description))
+        )
+
+        tool_lines.append(f"- {tool.name} [{cost}]: {text}")
+
+    candidate_lines = [
+        f"{candidate.tool} (cost {candidate.invocation_cost}) may be shadowed by "
+        f"{candidate.cheaper_sibling} (cost {candidate.cheaper_sibling_invocation_cost})"
+        for candidate in shadow_candidates
+    ]
+
+    return "\n".join(
+        [
+            f"SERVER NAME: {sanitize_for_prompt(server_name)}",
+            f"TOOL COUNT: {len(tools)}",
+            "",
+            "<tools>",
+            *tool_lines,
+            "</tools>",
+            "",
+            "<shadow-candidates>",
+            "\n".join(candidate_lines) if len(candidate_lines) > 0 else "None",
+            "</shadow-candidates>",
+            "",
+            "Respond with JSON only.",
+        ]
+    )