technical-answer-validator 0.1.0__tar.gz

technical_answer_validator-0.1.0/.dockerignore

@@ -0,0 +1,8 @@
+.git
+.venv
+.uv-cache
+__pycache__
+tests
+.env
+*.db
+*.sqlite*

technical_answer_validator-0.1.0/.env.example

@@ -0,0 +1,6 @@
+# Local single-key mode only. Generate a different secret with a password manager.
+# For a hosted multi-caller deployment, configure TAV_API_KEYS in the secret manager instead.
+TAV_API_KEY=replace-with-a-unique-random-secret-at-least-32-characters
+TAV_HOST=127.0.0.1
+TAV_PORT=8080
+# TAV_API_KEYS={"client-id":"64-character-sha256-hex-digest"}

technical_answer_validator-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run python -m unittest discover -s tests -v
+      - run: uv run python -m py_compile tav_core.py tav_api.py mcp_server.py scripts/create_api_key.py
+      - run: docker build --tag technical-answer-validator:ci .

technical_answer_validator-0.1.0/.github/workflows/publish-container.yml

@@ -0,0 +1,39 @@
+name: Publish REST API image
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/metadata-action@v5
+        id: meta
+        with:
+          images: ghcr.io/${{ github.repository }}-api
+          tags: |
+            type=ref,event=tag
+            type=raw,value=latest
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

technical_answer_validator-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,23 @@
+name: Publish MCP package to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/technical-answer-validator/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

technical_answer_validator-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.uv-cache/
+__pycache__/
+*.py[cod]
+.env
+dist/
+build/
+*.sqlite*

technical_answer_validator-0.1.0/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    TAV_HOST=0.0.0.0 \
+    TAV_PORT=8080 \
+    TAV_USAGE_DB=/data/usage.sqlite3
+
+WORKDIR /app
+COPY tav_api.py tav_core.py ./
+RUN useradd --system --uid 10001 --no-create-home tav && mkdir /data && chown 10001:10001 /data
+VOLUME ["/data"]
+USER 10001:10001
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/healthz', timeout=2)"
+CMD ["python", "-m", "tav_api"]

technical_answer_validator-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 JAMUS
+
+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.

technical_answer_validator-0.1.0/NOTICE.md

@@ -0,0 +1,7 @@
+# Notice
+
+Technical Answer Validator is an experimental, keyword-based assistive tool. It does not provide official exam grades, professional advice, or a guarantee of correctness. Operators and callers must review rubrics and outputs before relying on them.
+
+No SafetyExam question bank, answer corpus, study database, or personal study history is included in this project. The caller supplies the rubric and answer for every request.
+
+The project is licensed under the MIT License; see `LICENSE`. The release owner should still confirm that all included project code and assets are eligible for that license before public distribution.

technical_answer_validator-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: technical-answer-validator
+Version: 0.1.0
+Summary: MCP and REST tools for deterministic rubric-based technical answer review
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp==2.2.0
+Description-Content-Type: text/markdown
+
+# Technical Answer Validator
+
+<!-- mcp-name: io.github.christofer566/technical-answer-validator -->
+
+A tiny, deterministic answer review tool for AI agents, available over **MCP stdio** and as a REST API. Each caller supplies the concepts, accepted synonyms, numeric requirements, and answer text for a single evaluation. It does not include a question bank or answer corpus.
+
+This is an **assistive practice tool**, not an official certification exam grader. Keyword matching can miss semantically correct paraphrases and can accept misleading surface matches. Users should review the supplied rubric and every result.
+
+## Run locally
+
+Python 3.10+; the REST server uses the standard library. The MCP adapter uses the official Python SDK 2.2.0.
+
+```powershell
+$env:TAV_API_KEY = "replace-with-a-long-random-secret-at-least-24-characters"
+python -m tav_api
+```
+
+The service listens on `127.0.0.1:8080` by default. To change it, set `TAV_HOST` and `TAV_PORT`. Local single-key mode refuses to start without a `TAV_API_KEY` of at least 24 characters. For deployment, create a distinct key per caller with `python scripts/create_api_key.py CLIENT_ID` and configure `TAV_API_KEYS` as a JSON object mapping each client ID to the generated SHA-256 digest. Store the one-time raw key with that client; do not store or commit it in this repository. When `TAV_API_KEYS` is set, it takes precedence over `TAV_API_KEY`.
+
+## MCP for AI agents
+
+Install the pinned MCP SDK 2.2.0 in a virtual environment from the committed lockfile:
+
+```powershell
+uv sync --locked
+.\.venv\Scripts\Activate.ps1
+```
+
+The stdio MCP server exposes one tool: `evaluate_answer(rubric, answer)`. Configure an MCP host with the absolute path to the environment's Python and `mcp_server.py`. Example Claude Desktop configuration (replace paths):
+
+```json
+{
+  "mcpServers": {
+    "technical-answer-validator": {
+      "command": "C:\\path\\to\\technical-answer-validator\\.venv\\Scripts\\python.exe",
+      "args": ["C:\\path\\to\\technical-answer-validator\\mcp_server.py"]
+    }
+  }
+}
+```
+
+After publishing to PyPI, run with `uvx --from technical-answer-validator tav-mcp`. For local development use the `.venv` Python plus `mcp_server.py`. For Codex CLI or another MCP host, use its stdio server configuration with that command and script path. Restart the host, then ask it to list tools and call `evaluate_answer`. The stdio transport is local to the user's agent host and needs no internet endpoint or API key.
+
+The Codex TOML template is `codex-mcp-config.example.toml`; the Claude Desktop JSON template is `claude-mcp-config.example.json`. Replace both placeholder paths with absolute paths. Merge the block into the host configuration; do not overwrite other MCP servers or global settings.
+
+## Request
+
+`POST /v1/evaluate`
+
+```json
+{
+  "rubric": {
+    "required_concepts": ["isolation", "lockout tag"],
+    "accepted_synonyms": {"isolation": ["energy isolation"]},
+    "numeric_requirements": [],
+    "required_count": 2
+  },
+  "answer": "Apply energy isolation and attach a lockout tag."
+}
+```
+
+`accepted_synonyms` keys must exactly match a concept. `numeric_requirements` is an optional array such as `[{"value":"10","unit":"kN","tolerance":"0"}]`. Numbers in an answer are only checked when explicit requirements are provided. Concept score is matched concepts / required_count (defaults to the number of concepts), capped at 1.0; numeric failures apply a 50% score penalty. The verdict thresholds are `correct >= 0.8`, `partial >= 0.4`, otherwise `wrong`.
+
+## Response and errors
+
+Successful requests return `api_version`, `status`, `score`, `verdict`, matched/missing concepts, numeric check details, and `review_required: true`.
+
+Errors use JSON `{ "error": { "code": "...", "message": "..." } }`. Statuses include 400 (invalid request), 401 (missing/invalid key), 404, 405, 413 (body over 64 KiB), and 429 (over 60 requests/minute per client ID). The rate limit is 60 requests/minute per authenticated client ID, in memory, and resets when the process restarts. Daily request/success/client-error/rate-limited counters are persisted in SQLite without answer text and expire after 90 days. `GET /v1/usage` returns only the caller's current UTC-day counts. Retain and back up the usage volume as desired; it contains client IDs and aggregates only.
+
+## Privacy and deployment limits
+
+The server does not log request bodies or answers. It stores daily counts keyed by client ID and request timestamps in process memory for REST rate limiting. The **stdio MCP option runs locally inside the agent host** and sends no requests to this HTTP server. The REST API is containerized and keeps usage counters in a persistent volume. Before public service, terminate TLS at a reverse proxy, set proxy-level rate/concurrency limits, deploy from a secret manager, monitor the host, and publish a data-retention/contact policy. The app-level per-client rate limit resets on restart and is not a substitute for edge controls.
+
+## Verify
+
+```powershell
+python -m unittest discover -s tests -v
+```
+
+The OpenAPI contract is in `openapi.yaml`; the draft official MCP Registry descriptor is `server.json`, with publication steps in `PUBLISHING.md`. Run locally with Docker Compose after copying `.env.example` to `.env` and adding a private key; Compose publishes the service only on loopback, so configure an HTTPS reverse proxy separately. `compose.yaml` persists aggregate usage in a named volume and applies a read-only root filesystem, dropped Linux capabilities, and resource limits.
+
+These tests check API and grading behavior; they do not establish professional exam accuracy.

technical_answer_validator-0.1.0/PUBLISHING.md

@@ -0,0 +1,31 @@
+# Public release runbook
+
+The package contains two delivery paths: local MCP stdio for an agent that can spawn a local process, and a REST API container for hosted agents. No public artifact has been uploaded and no service is deployed by this preparation.
+
+## Local MCP package
+
+1. MIT was selected and is included in `LICENSE` and the Python package metadata. Confirm that all included source/assets are eligible for MIT before public release.
+2. The public GitHub repository exists at `https://github.com/Christofer566/technical-answer-validator`; source is on `main`. Keep `.venv`, `.uv-cache`, `.env`, usage databases, and generated state out of commits.
+3. Build and inspect the wheel/sdist: `uv build`; test the wheel in a clean virtual environment; `uv run python -m unittest discover -s tests -v`.
+4. PyPI JSON lookup returned HTTP 404 on 2026-10-02. In the PyPI account, register a pending GitHub Actions Trusted Publisher for project `technical-answer-validator`, owner `Christofer566`, repository `technical-answer-validator`, workflow `.github/workflows/publish-pypi.yml`, environment `pypi`. The GitHub `pypi` environment already exists. Publish version `0.1.0` by pushing a `v0.1.0` tag only after ownership/IP approval.
+5. Confirm the built PyPI README contains the exact `mcp-name` marker and that package metadata, repository URL, license, and author are correct.
+6. Validate `server.json` against the current MCP Registry schema and verify the GitHub/PyPI namespace, package name, and version. Then publish with the official MCP Registry CLI using the owner's GitHub identity.
+7. Test installation from the published package in a clean environment with `uvx --from technical-answer-validator tav-mcp`; connect it in target agent hosts and call `evaluate_answer`.
+
+## Hosted REST API
+
+1. Choose the VPS/host, public domain, TLS reverse proxy, budget ceiling, operator contact, and retention policy. These account/domain choices are not present in the workspace.
+2. Set `TAV_API_KEYS` in the host's secret manager to `{client_id: sha256_hex}` entries generated by `python scripts/create_api_key.py CLIENT_ID`. Deliver each raw key privately to its intended agent operator; only the digest belongs in deployment configuration.
+3. Push an approved `v0.1.0` tag to build and publish `ghcr.io/<owner>/<repo>-api` via `.github/workflows/publish-container.yml`. Pull that image on the host or build directly from the reviewed repository; deploy with `compose.yaml` and retain the `/data` volume. Keep the app bound to loopback behind the HTTPS proxy. Add proxy-level connection/time/body limits and rate limiting; app-level rate buckets reset on restart.
+4. Monitor `/healthz`, per-customer `/v1/usage`, host availability, disk space for SQLite aggregates, and spend. Define key rotation/revocation by removing the corresponding digest and restarting/redeploying.
+5. Verify external HTTPS from a separate network with unauthenticated rejection, valid client isolation, 64 KiB limit, rate limits, no answer logging, and accurate OpenAPI docs before announcing a URL.
+
+## Blocks that require owner-controlled decisions/actions
+
+- Public source repository exists and `server.json` points to it.
+- PyPI name was not registered at the 2026-10-02 lookup (HTTP 404). PyPI account authentication is required to register its pending publisher; no package has been uploaded.
+- MIT is selected. The owner must still confirm project ownership and third-party rights for included files before publication.
+- No production URL, host account, budget, or service operator contact has been supplied; therefore the container remains local and has not been deployed.
+- The tool's keyword/numeric decisions are not validated against independent subject-matter gold data. Position it as assistive agent feedback, not a trustworthy final grader.
+
+

technical_answer_validator-0.1.0/README.md

@@ -0,0 +1,82 @@
+# Technical Answer Validator
+
+<!-- mcp-name: io.github.christofer566/technical-answer-validator -->
+
+A tiny, deterministic answer review tool for AI agents, available over **MCP stdio** and as a REST API. Each caller supplies the concepts, accepted synonyms, numeric requirements, and answer text for a single evaluation. It does not include a question bank or answer corpus.
+
+This is an **assistive practice tool**, not an official certification exam grader. Keyword matching can miss semantically correct paraphrases and can accept misleading surface matches. Users should review the supplied rubric and every result.
+
+## Run locally
+
+Python 3.10+; the REST server uses the standard library. The MCP adapter uses the official Python SDK 2.2.0.
+
+```powershell
+$env:TAV_API_KEY = "replace-with-a-long-random-secret-at-least-24-characters"
+python -m tav_api
+```
+
+The service listens on `127.0.0.1:8080` by default. To change it, set `TAV_HOST` and `TAV_PORT`. Local single-key mode refuses to start without a `TAV_API_KEY` of at least 24 characters. For deployment, create a distinct key per caller with `python scripts/create_api_key.py CLIENT_ID` and configure `TAV_API_KEYS` as a JSON object mapping each client ID to the generated SHA-256 digest. Store the one-time raw key with that client; do not store or commit it in this repository. When `TAV_API_KEYS` is set, it takes precedence over `TAV_API_KEY`.
+
+## MCP for AI agents
+
+Install the pinned MCP SDK 2.2.0 in a virtual environment from the committed lockfile:
+
+```powershell
+uv sync --locked
+.\.venv\Scripts\Activate.ps1
+```
+
+The stdio MCP server exposes one tool: `evaluate_answer(rubric, answer)`. Configure an MCP host with the absolute path to the environment's Python and `mcp_server.py`. Example Claude Desktop configuration (replace paths):
+
+```json
+{
+  "mcpServers": {
+    "technical-answer-validator": {
+      "command": "C:\\path\\to\\technical-answer-validator\\.venv\\Scripts\\python.exe",
+      "args": ["C:\\path\\to\\technical-answer-validator\\mcp_server.py"]
+    }
+  }
+}
+```
+
+After publishing to PyPI, run with `uvx --from technical-answer-validator tav-mcp`. For local development use the `.venv` Python plus `mcp_server.py`. For Codex CLI or another MCP host, use its stdio server configuration with that command and script path. Restart the host, then ask it to list tools and call `evaluate_answer`. The stdio transport is local to the user's agent host and needs no internet endpoint or API key.
+
+The Codex TOML template is `codex-mcp-config.example.toml`; the Claude Desktop JSON template is `claude-mcp-config.example.json`. Replace both placeholder paths with absolute paths. Merge the block into the host configuration; do not overwrite other MCP servers or global settings.
+
+## Request
+
+`POST /v1/evaluate`
+
+```json
+{
+  "rubric": {
+    "required_concepts": ["isolation", "lockout tag"],
+    "accepted_synonyms": {"isolation": ["energy isolation"]},
+    "numeric_requirements": [],
+    "required_count": 2
+  },
+  "answer": "Apply energy isolation and attach a lockout tag."
+}
+```
+
+`accepted_synonyms` keys must exactly match a concept. `numeric_requirements` is an optional array such as `[{"value":"10","unit":"kN","tolerance":"0"}]`. Numbers in an answer are only checked when explicit requirements are provided. Concept score is matched concepts / required_count (defaults to the number of concepts), capped at 1.0; numeric failures apply a 50% score penalty. The verdict thresholds are `correct >= 0.8`, `partial >= 0.4`, otherwise `wrong`.
+
+## Response and errors
+
+Successful requests return `api_version`, `status`, `score`, `verdict`, matched/missing concepts, numeric check details, and `review_required: true`.
+
+Errors use JSON `{ "error": { "code": "...", "message": "..." } }`. Statuses include 400 (invalid request), 401 (missing/invalid key), 404, 405, 413 (body over 64 KiB), and 429 (over 60 requests/minute per client ID). The rate limit is 60 requests/minute per authenticated client ID, in memory, and resets when the process restarts. Daily request/success/client-error/rate-limited counters are persisted in SQLite without answer text and expire after 90 days. `GET /v1/usage` returns only the caller's current UTC-day counts. Retain and back up the usage volume as desired; it contains client IDs and aggregates only.
+
+## Privacy and deployment limits
+
+The server does not log request bodies or answers. It stores daily counts keyed by client ID and request timestamps in process memory for REST rate limiting. The **stdio MCP option runs locally inside the agent host** and sends no requests to this HTTP server. The REST API is containerized and keeps usage counters in a persistent volume. Before public service, terminate TLS at a reverse proxy, set proxy-level rate/concurrency limits, deploy from a secret manager, monitor the host, and publish a data-retention/contact policy. The app-level per-client rate limit resets on restart and is not a substitute for edge controls.
+
+## Verify
+
+```powershell
+python -m unittest discover -s tests -v
+```
+
+The OpenAPI contract is in `openapi.yaml`; the draft official MCP Registry descriptor is `server.json`, with publication steps in `PUBLISHING.md`. Run locally with Docker Compose after copying `.env.example` to `.env` and adding a private key; Compose publishes the service only on loopback, so configure an HTTPS reverse proxy separately. `compose.yaml` persists aggregate usage in a named volume and applies a read-only root filesystem, dropped Linux capabilities, and resource limits.
+
+These tests check API and grading behavior; they do not establish professional exam accuracy.

technical_answer_validator-0.1.0/claude-mcp-config.example.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "technical-answer-validator": {
+      "command": "C:\\absolute\\path\\technical-answer-validator\\.venv\\Scripts\\python.exe",
+      "args": ["C:\\absolute\\path\\technical-answer-validator\\mcp_server.py"]
+    }
+  }
+}

technical_answer_validator-0.1.0/codex-mcp-config.example.toml

@@ -0,0 +1,8 @@
+# Merge this server block into the user's Codex MCP configuration.
+# Replace the absolute path for the machine where the server is installed.
+
+[mcp_servers.technical_answer_validator]
+command = "C:/absolute/path/technical-answer-validator/.venv/Scripts/python.exe"
+args = ["C:/absolute/path/technical-answer-validator/mcp_server.py"]
+startup_timeout_sec = 30
+tool_timeout_sec = 30

technical_answer_validator-0.1.0/compose.yaml

@@ -0,0 +1,29 @@
+services:
+  tav-api:
+    build: .
+    image: technical-answer-validator:0.1.0
+    restart: unless-stopped
+    env_file: .env
+    ports:
+      - "127.0.0.1:8080:8080"
+    volumes:
+      - tav-usage:/data
+    read_only: true
+    tmpfs:
+      - /tmp:size=8m,noexec,nosuid
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    pids_limit: 64
+    mem_limit: 128m
+    cpus: 0.50
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/healthz', timeout=2)"]
+      interval: 30s
+      timeout: 3s
+      retries: 3
+      start_period: 5s
+
+volumes:
+  tav-usage:

technical_answer_validator-0.1.0/mcp_server.py

@@ -0,0 +1,46 @@
+"""MCP stdio server exposing the answer evaluator as an agent tool."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from mcp.server import MCPServer
+
+from tav_core import RequestError, evaluate
+
+logging.basicConfig(level=logging.WARNING, format="%(levelname)s %(message)s")
+mcp = MCPServer(
+    "Technical Answer Validator",
+    instructions=(
+        "Evaluate a user's technical answer against a rubric supplied for this call. "
+        "Always pass the caller's rubric and answer. Explain that results are keyword-based "
+        "assistive feedback, never official exam grades; preserve review_required in your response."
+    ),
+)
+
+
+@mcp.tool()
+def evaluate_answer(rubric: dict[str, Any], answer: str) -> dict[str, Any]:
+    """Check an answer against caller-provided concepts, synonyms, and numeric requirements.
+
+    Rubric fields: required_concepts (1-50 strings), optional accepted_synonyms keyed by
+    concept, optional numeric_requirements [{value, unit?, tolerance?}], and optional
+    required_count. No question bank is bundled. Review the returned result; it is not
+    an official exam grade.
+    """
+    try:
+        return evaluate({"rubric": rubric, "answer": answer})
+    except RequestError as exc:
+        # Return a structured error result so the agent can repair its inputs.
+        return {"status": "invalid_request", "error": str(exc), "review_required": True}
+
+
+def main() -> None:
+    # FastMCP stdio transport uses stdout for protocol messages; keep diagnostics on stderr.
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

technical_answer_validator-0.1.0/openapi.yaml

@@ -0,0 +1,137 @@
+openapi: 3.1.0
+info:
+  title: Technical Answer Validator API
+  version: 0.1.0
+  description: Deterministic, rubric-based assistive review for AI agents. Not an official exam grade.
+servers:
+  - url: http://127.0.0.1:8080
+    description: Local development only; production must use HTTPS.
+security:
+  - bearerAuth: []
+paths:
+  /healthz:
+    get:
+      security: []
+      summary: Health check
+      responses:
+        "200":
+          description: Healthy
+  /v1/evaluate:
+    post:
+      summary: Evaluate one answer against a caller-supplied rubric
+      operationId: evaluateAnswer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EvaluationRequest"
+            example:
+              rubric:
+                required_concepts: [isolation, lockout tag]
+                accepted_synonyms:
+                  isolation: [energy isolation]
+                numeric_requirements: []
+                required_count: 2
+              answer: Apply energy isolation and attach a lockout tag.
+      responses:
+        "200":
+          description: Evaluation result; review is always required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvaluationResult"
+        "400":
+          $ref: "#/components/responses/ClientError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "413":
+          description: Body exceeds 64 KiB
+        "415":
+          description: Content-Type must be application/json
+        "429":
+          description: Per-client request limit exceeded
+  /v1/usage:
+    get:
+      summary: Read this API key's UTC daily aggregate usage
+      operationId: getUsage
+      responses:
+        "200":
+          description: Aggregated counters; answer content is never included
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  date_utc: {type: string, format: date}
+                  requests: {type: integer}
+                  successful: {type: integer}
+                  client_errors: {type: integer}
+                  rate_limited: {type: integer}
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: API key
+  schemas:
+    NumericRequirement:
+      type: object
+      additionalProperties: false
+      required: [value]
+      properties:
+        value: {type: [string, number]}
+        unit: {type: string, maxLength: 24}
+        tolerance: {type: [string, number], default: 0}
+    Rubric:
+      type: object
+      additionalProperties: false
+      required: [required_concepts]
+      properties:
+        required_concepts:
+          type: array
+          minItems: 1
+          maxItems: 50
+          items: {type: string, minLength: 1, maxLength: 120}
+        accepted_synonyms:
+          type: object
+          additionalProperties:
+            type: array
+            maxItems: 20
+            items: {type: string, minLength: 1, maxLength: 120}
+        numeric_requirements:
+          type: array
+          maxItems: 20
+          items: {$ref: "#/components/schemas/NumericRequirement"}
+        required_count:
+          type: integer
+          minimum: 1
+          maximum: 50
+    EvaluationRequest:
+      type: object
+      additionalProperties: false
+      required: [rubric, answer]
+      properties:
+        rubric: {$ref: "#/components/schemas/Rubric"}
+        answer: {type: string, minLength: 1, maxLength: 8000}
+    EvaluationResult:
+      type: object
+      required: [api_version, status, score, verdict, matched_concepts, missing_concepts, numeric_checks, review_required, limitations]
+      properties:
+        api_version: {const: v1}
+        status: {const: graded}
+        score: {type: number, minimum: 0, maximum: 1}
+        verdict: {enum: [correct, partial, wrong]}
+        matched_concepts: {type: array, items: {type: string}}
+        missing_concepts: {type: array, items: {type: string}}
+        numeric_checks: {type: array, items: {type: object}}
+        notes: {type: array, items: {type: string}}
+        review_required: {const: true}
+        limitations: {type: array, items: {type: string}}
+  responses:
+    Unauthorized:
+      description: Missing or invalid bearer API key
+    ClientError:
+      description: Invalid request JSON or rubric

technical_answer_validator-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "technical-answer-validator"
+version = "0.1.0"
+description = "MCP and REST tools for deterministic rubric-based technical answer review"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["mcp==2.2.0"]
+
+[project.scripts]
+tav-mcp = "mcp_server:main"
+tav-api = "tav_api:main"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["mcp_server.py", "tav_core.py", "tav_api.py"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"mcp_server.py" = "mcp_server.py"
+"tav_core.py" = "tav_core.py"
+"tav_api.py" = "tav_api.py"
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+  ".dockerignore", ".env.example", ".gitignore", "Dockerfile", "NOTICE.md",
+  "PUBLISHING.md", "README.md", "claude-mcp-config.example.json",
+  "codex-mcp-config.example.toml", "compose.yaml", "mcp_server.py",
+  "openapi.yaml", "pyproject.toml", "requirements.txt", "server.json",
+  "tav_api.py", "tav_core.py", "uv.lock", ".github", "scripts", "tests"
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

technical_answer_validator-0.1.0/requirements.txt

@@ -0,0 +1 @@
+mcp==2.2.0

technical_answer_validator-0.1.0/scripts/create_api_key.py

@@ -0,0 +1,15 @@
+"""Generate a one-time API credential and its TAV_API_KEYS SHA-256 entry."""
+import hashlib
+import json
+import re
+import secrets
+import sys
+
+if len(sys.argv) != 2 or not re.fullmatch(r"[A-Za-z0-9_-]{1,48}", sys.argv[1]):
+    raise SystemExit("Usage: python scripts/create_api_key.py CLIENT_ID (letters, digits, _ or -; max 48)")
+client_id = sys.argv[1]
+token = "tav_" + secrets.token_urlsafe(36)
+digest = hashlib.sha256(token.encode("utf-8")).hexdigest()
+print("Save this API key now; it is shown only once:\n" + token)
+print("Add this entry to your secret manager's TAV_API_KEYS JSON:")
+print(json.dumps({client_id: digest}, separators=(",", ":")))