Skip to content

API_SURFACE.md

Latest commit

 

History

History
224 lines (173 loc) · 10.3 KB

API_SURFACE.md

File metadata and controls

224 lines (173 loc) · 10.3 KB

API Surface

Purpose

This document describes the stable Comptextv7 API, dashboard, export, and report surfaces that future benchmark/regression summaries can reference. It also records integration expectations for sanitized outputs from ProfRandom92/Comptext-Daimler-Experiment- without introducing runtime coupling.

Comptextv7 should remain the main runtime/dashboard/API repository. Experiment outputs should influence review decisions through lightweight Markdown, JSON, or CSV summaries only.

Agent workflow guardrails

API, dashboard, and export contract changes should start with python scripts/repo_intake.py so reviewers can see the detected repository shape and likely API/dashboard/report areas before implementation. After making changes, run python scripts/run_checks.py, python scripts/validate_contracts.py, python scripts/generate_contract_fixtures.py, python scripts/validate_api_exports.py, and python scripts/generate_dashboard_health_summary.py to perform deterministic local validation without installing dependencies, using real Daimler data, or requiring network access.

The .github/workflows/agent-checks.yml workflow mirrors these steps for pull requests on Python 3.11 and uploads the generated docs/reports/ artifacts when available. This guardrail is intentionally lightweight: it validates helper scripts, available local checks, and contract examples while benchmark/regression evidence remains a sanitized report handoff from ProfRandom92/Comptext-Daimler-Experiment-, not a runtime dependency of Comptextv7.

Branch discipline remains part of the API contract process: create a feature branch from main when available, open a PR, request review, and never push directly to main.

Stable API routes

The stdlib dashboard backend currently treats these routes as stable review surfaces:

Route Format Stability Purpose
GET /api/dashboard JSON Stable Primary operations payload containing audit summary, benchmark rows, forensic findings, replay summary, incidents, and service health.
GET /export.json JSON Stable Machine-readable export of the same dashboard evidence for CI or air-gapped review.
GET /export.csv CSV Stable Spreadsheet-friendly review artifact with benchmark and forensic rows.
GET /replay JSON Stable Replay-oriented evidence view using the dashboard payload shape.
GET /dashboard-health-summary.json JSON Stable Static release health summary artifact loaded from docs/reports/dashboard-health-summary.json for dashboard release-readiness badges and fallback-safe UI rendering.
GET / HTML or React app Stable Human dashboard entry point; falls back to a stdlib HTML view when the React build is unavailable.

All stable routes should preserve no-store cache headers, avoid exposing raw sensitive inputs, and remain usable without heavy runtime dependencies.

Dashboard routes/views

The dashboard boundary has two layers:

  1. Backend API/export routes provide sanitized operational evidence.
  2. The React or fallback HTML dashboard renders that evidence for review.

Dashboard views that should be compatible with benchmark and regression summaries include:

  • Audit summary cards for latency, replay determinism, tokenizer state, forensic failures, and active incidents.
  • Service health tables for compression, replay, and validation components.
  • Incident/finding views for high and critical regression or forensic blockers.
  • Benchmark tables or charts for p50, p95, p99, RPS, error rate, and payload size.
  • Export links for JSON and CSV evidence handoff.
  • Release health summary panel sourced from docs/reports/dashboard-health-summary.json, with fallback messaging when that artifact is unavailable.

Export/report endpoints

/export.json and /export.csv are the primary report handoff endpoints inside Comptextv7. They should remain deterministic enough for review, small enough for PR artifacts, and explicit about any schema changes.

docs/reports/dashboard-health-summary.json is the dashboard-facing static release-readiness artifact generated by python scripts/generate_dashboard_health_summary.py. The React dashboard copies docs/reports/ into the Vite static bundle and also accepts the stdlib backend route at /dashboard-health-summary.json, allowing the UI to render status badges, missing-artifact callouts, and next-action lists without an external service or real Daimler data. The companion Markdown report, docs/reports/dashboard-health-summary.md, provides the human-readable review summary.

Future report endpoints such as /reports/benchmark-summary, /reports/regression-summary, or /reports/sanitization-summary should not be added until a schema, security review, and issue scope approve them. If added, they should consume sanitized summaries only and should not execute experiment repository workloads from the Comptextv7 runtime.

Payload and report contract expectations

Accepted report summaries should be:

  • Synthetic in documentation examples.
  • Sanitized before being copied into Comptextv7.
  • Small enough to review in a pull request.
  • Text-based: Markdown, JSON, or CSV.
  • Explicit about source_repo, target_repo, report_type, status, timestamp or baseline/candidate references, and whether the content is synthetic.
  • Focused on p50, p95, p99, RPS, error rate, payload size, route name, review status, and remediation notes.

Machine-readable contract files

Machine-readable contract schemas now live under contracts/ and are written as lightweight JSON Schema-like documents that future agents and CI can inspect without adding runtime dependencies:

  • contracts/api-dashboard.schema.json describes Comptextv7 API routes, dashboard views, export formats, sanitized report integration points, and security notes.
  • contracts/benchmark-summary.schema.json describes synthetic benchmark handoff summaries for p50/p95/p99, RPS, error rate, and payload size.
  • contracts/regression-summary.schema.json describes baseline/candidate comparison summaries, thresholds, decisions, and notes.
  • contracts/sanitization-summary.schema.json describes sanitization scan summaries for handoff artifacts.

Synthetic examples live under contracts/examples/:

  • contracts/examples/api-dashboard.example.json
  • contracts/examples/benchmark-summary.example.json
  • contracts/examples/regression-summary.example.json
  • contracts/examples/sanitization-summary.example.json

Validate the schema files and examples with:

python scripts/validate_contracts.py

The validator uses only the Python standard library, checks required fields and simple structural types, and writes docs/reports/contract-validation-report.md for review artifacts. The examples are synthetic only and must not be replaced with real Daimler payloads, customer data, secrets, raw production logs, or proprietary documents.

API/export fixture enforcement

API/dashboard/export payload shapes are enforced with deterministic synthetic fixtures rather than a live server. Run:

python scripts/generate_contract_fixtures.py
python scripts/validate_api_exports.py

scripts/generate_contract_fixtures.py writes contracts/examples/api-dashboard.example.json and records generation evidence in docs/reports/contract-fixture-generation-report.md. scripts/validate_api_exports.py loads contracts/api-dashboard.schema.json and the generated example, checks required fields, simple field types, the synthetic: true marker, and array-shaped API/export collections, then writes docs/reports/api-export-validation-report.md. These checks use only the Python standard library, require no live server, and must remain limited to synthetic values.

Dashboard release health summary

Run the dashboard health summary generator after local validation artifacts are available:

python scripts/generate_dashboard_health_summary.py

The generator inspects local report/check artifact existence under docs/reports/ and writes both docs/reports/dashboard-health-summary.md and docs/reports/dashboard-health-summary.json with deterministic synthetic metadata. The JSON includes overall_status, named validation checks, required_artifacts_present, missing_artifacts, next_recommended_actions, and safety_notes, so future UI work can consume one compact artifact instead of reimplementing release-readiness logic.

Compatibility with benchmark/regression reports

Benchmark summaries should map to Comptextv7 review surfaces this way:

Report type Expected Comptextv7 use
benchmark_summary Compare p50/p95/p99, RPS, error rate, and payload size for dashboard/API routes.
regression_summary Decide whether a PR should merge, require remediation, or split into smaller changes.
sanitization_summary Prove that attached benchmark evidence excludes secrets, raw logs, customer data, and proprietary documents.
forensic_replay_note Identify semantic retention, determinism, replay, or export-contract findings for follow-up fixes.

Reviewers should block or request changes when summaries show unexplained tail latency growth, payload-size growth, error-rate increases, determinism failures, or high/critical forensic findings.

Dashboard/API boundaries

Comptextv7 may:

  • Display sanitized benchmark/regression status.
  • Export local dashboard evidence as JSON or CSV.
  • Document future report contracts.
  • Add small schema-version fields in future PRs.

Comptextv7 should not yet:

  • Import code from ProfRandom92/Comptext-Daimler-Experiment-.
  • Run experiment repository workloads as part of normal dashboard/API startup.
  • Store real Daimler payloads, customer data, raw production logs, cookies, tokens, or proprietary documents.
  • Treat benchmark pass/fail as a replacement for forensic replay and semantic retention review.

Security and data handling notes

  • Treat Daimler-related context as sensitive even when the repository uses public or synthetic examples.
  • Prefer synthetic examples in documentation and tests.
  • Redact VIN/FIN, customer identifiers, employee names, plant identifiers, account IDs, tokens, cookies, and proprietary terms before handoff.
  • Keep report artifacts small and human-reviewable.
  • Do not add heavy dependencies for report parsing unless a future issue approves them.