Skip to content

Commit 71fa285

Browse files
rboni-dkclaude
rboni-dk
and
claude
committed
refactor(mcp,api): run-kind labels, shared status labels, API schema hygiene
- Label run identifiers by kind (Test Run / Profiling Run) in MCP output instead of "Job ID" - Single JOB_STATUS_LABEL in common.enums; run-summary models alias it - Strip enum descriptions from the OpenAPI schema so enum docstrings don't leak into the public docs - Add PublicJobKey so the API exposes only externally-triggerable job kinds; remove dead backfill job source - Generalize an OAuth route docstring; drop an incidental JobKey re-export TG-1116 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 7235fde commit 71fa285

15 files changed

Lines changed: 99 additions & 54 deletions

File tree

‎testgen/api/deps.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,9 @@
77
from sqlalchemy import select
88

99
from testgen.common.auth import authorize_token, decode_jwt_token
10+
from testgen.common.enums import PublicJobKey
1011
from testgen.common.models import Session, _current_session_wrapper, get_current_session
11-
from testgen.common.models.job_execution import PUBLIC_JOB_KEYS, JobExecution
12+
from testgen.common.models.job_execution import JobExecution
1213
from testgen.common.models.project_membership import ProjectMembership
1314
from testgen.common.models.table_group import TableGroup
1415
from testgen.common.models.test_suite import TestSuite
@@ -122,15 +123,15 @@ def dependency(test_suite_id: UUID, user: User = _require_user) -> TestSuite:
122123
def resolve_job(permission: str, *extra_filters):
123124
"""Resolve a JobExecution by ``job_id`` path param and verify project permission.
124125
125-
Only jobs whose ``job_key`` is in ``PUBLIC_JOB_KEYS`` are exposed via the API.
126+
Only externally-triggerable jobs (``PublicJobKey``) are exposed via the API.
126127
Internal kinds (score rollups, recalculations, monitor runs) are filtered out
127128
by construction. Extra ORM clauses are appended to the WHERE clause to further
128129
restrict by job_key when a caller wants a single kind.
129130
"""
130131
def dependency(job_id: UUID, user: User = _require_user) -> JobExecution:
131132
query = select(JobExecution).where(
132133
JobExecution.id == job_id,
133-
JobExecution.job_key.in_(PUBLIC_JOB_KEYS),
134+
JobExecution.job_key.in_(list(PublicJobKey)),
134135
*extra_filters,
135136
)
136137
return _check_access(get_current_session().scalars(query).first(), user, permission)

‎testgen/api/jobs.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@
1111
resolve_test_suite,
1212
)
1313
from testgen.api.schemas import ErrorResponse, JobListResponse, JobResponse, JobSubmittedResponse
14-
from testgen.common.enums import JobKey, JobSource, JobStatus
15-
from testgen.common.models.job_execution import PUBLIC_JOB_KEYS, JobExecution
14+
from testgen.common.enums import JobKey, JobSource, JobStatus, PublicJobKey
15+
from testgen.common.models.job_execution import JobExecution
1616
from testgen.common.models.table_group import TableGroup
1717
from testgen.common.models.test_suite import TestSuite
1818

@@ -98,15 +98,15 @@ def cancel_job(job: JobExecution = resolve_job("edit")): # noqa: B008
9898
)
9999
def list_jobs(
100100
project_code: str = resolve_project_code("view"),
101-
job_key: JobKey | None = Query(default=None), # noqa: B008
101+
job_key: PublicJobKey | None = Query(default=None), # noqa: B008
102102
status: JobStatus | None = Query(default=None), # noqa: B008
103103
page: int = Query(default=1, ge=1),
104104
limit: int = Query(default=20, ge=1, le=100),
105105
):
106106
"""List job executions for a project, with optional filters and pagination."""
107107
items, total = JobExecution.list_for_project(
108108
project_code,
109-
JobExecution.job_key.in_(PUBLIC_JOB_KEYS),
109+
JobExecution.job_key.in_(list(PublicJobKey)),
110110
job_key=job_key,
111111
status=status,
112112
page=page,

‎testgen/api/oauth/metadata.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
def authorization_server_metadata():
1313
"""Return OAuth 2.1 Authorization Server Metadata per RFC 8414.
1414
15-
MCP clients use this for server discovery.
15+
OAuth clients use this for server discovery.
1616
"""
1717
base_url = settings.BASE_URL.rstrip("/")
1818

‎testgen/api/runs.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,13 @@
77
from testgen.api.schemas import (
88
ErrorResponse,
99
IssueBreakdown,
10-
JobKey,
1110
ProfilingRunResponse,
1211
ProfilingRunResult,
1312
TestBreakdown,
1413
TestRunResponse,
1514
TestRunResult,
1615
)
16+
from testgen.common.enums import JobKey
1717
from testgen.common.models import get_current_session
1818
from testgen.common.models.hygiene_issue import HygieneIssue
1919
from testgen.common.models.job_execution import JobExecution

‎testgen/api/schemas.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
from pydantic import BaseModel, field_validator
88

9-
from testgen.common.enums import JobKey, JobSource, JobStatus
9+
from testgen.common.enums import JobSource, JobStatus, PublicJobKey
1010

1111
# --- Jobs ---
1212

@@ -24,7 +24,7 @@ class JobResponse(BaseModel):
2424
"""Full job execution record returned by status and cancel endpoints."""
2525

2626
id: UUID
27-
job_key: JobKey
27+
job_key: PublicJobKey
2828
status: JobStatus
2929
source: JobSource
3030
created_at: datetime

‎testgen/common/enums.py‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,14 +40,21 @@ class JobKey(StrEnum):
4040
run_data_cleanup = "run-data-cleanup"
4141

4242

43+
class PublicJobKey(StrEnum):
44+
"""``job_key`` values exposed through the public API — the externally-triggerable
45+
subset of ``JobKey``. Internal maintenance kinds are intentionally absent."""
46+
run_profile = JobKey.run_profile.value
47+
run_tests = JobKey.run_tests.value
48+
run_test_generation = JobKey.run_test_generation.value
49+
50+
4351
class JobSource(StrEnum):
4452
"""``source`` column values for ``job_executions``."""
4553
api = "api"
4654
ui = "ui"
4755
scheduler = "scheduler"
4856
mcp = "mcp"
4957
cli = "cli"
50-
backfill = "backfill"
5158
system = "system"
5259

5360

@@ -63,6 +70,18 @@ class JobStatus(StrEnum):
6370
CANCELED = "canceled"
6471

6572

73+
# User-facing display labels for JobStatus values.
74+
JOB_STATUS_LABEL: dict[str, str] = {
75+
JobStatus.COMPLETED: "Completed",
76+
JobStatus.CANCELED: "Canceled",
77+
JobStatus.CANCEL_REQUESTED: "Canceling",
78+
JobStatus.PENDING: "Pending",
79+
JobStatus.CLAIMED: "Starting",
80+
JobStatus.RUNNING: "Running",
81+
JobStatus.ERROR: "Error",
82+
}
83+
84+
6685
class Disposition(StrEnum):
6786
"""Stored disposition values for ``profile_anomaly_results.disposition`` and
6887
``test_results.disposition``. The user-facing label for ``INACTIVE`` is "Muted"."""

‎testgen/common/models/job_execution.py‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,12 @@
66
from sqlalchemy import Column, String, Text, case, delete, func, select, text, update
77
from sqlalchemy.dialects import postgresql
88

9-
from testgen.common.enums import JobKey, JobSource, JobStatus
9+
from testgen.common.enums import JobSource, JobStatus
1010
from testgen.common.models import Base, database_session, get_current_session
1111

1212
LOG = logging.getLogger("testgen")
1313

1414

15-
# Job kinds that are externally triggerable. Internal kinds (run-score-update,
16-
# recalculate-project-scores, ...) are absent and filtered out by construction.
17-
PUBLIC_JOB_KEYS: frozenset[JobKey] = frozenset({
18-
JobKey.run_profile,
19-
JobKey.run_tests,
20-
JobKey.run_test_generation,
21-
})
22-
23-
2415
_VALID_TRANSITIONS: dict[JobStatus, frozenset[JobStatus]] = {
2516
JobStatus.PENDING: frozenset({JobStatus.CLAIMED, JobStatus.CANCEL_REQUESTED}),
2617
JobStatus.CLAIMED: frozenset({JobStatus.RUNNING, JobStatus.ERROR, JobStatus.CANCEL_REQUESTED}),

‎testgen/common/models/profiling_run.py‎

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
from sqlalchemy.orm.attributes import flag_modified
1111
from sqlalchemy.sql.expression import case
1212

13-
from testgen.common.enums import Disposition, JobStatus
13+
from testgen.common.enums import JOB_STATUS_LABEL, Disposition, JobStatus
1414
from testgen.common.models import database_session, get_current_session
1515
from testgen.common.models.connection import Connection
1616
from testgen.common.models.entity import Entity, EntityMinimal
@@ -71,15 +71,7 @@ class ProfilingRunSummary(EntityMinimal):
7171
dq_score_profiling: float | None
7272
total_count: int
7373

74-
STATUS_LABEL: ClassVar[dict[str, str]] = {
75-
JobStatus.COMPLETED: "Completed",
76-
JobStatus.CANCELED: "Canceled",
77-
JobStatus.CANCEL_REQUESTED: "Canceling",
78-
JobStatus.PENDING: "Pending",
79-
JobStatus.CLAIMED: "Starting",
80-
JobStatus.RUNNING: "Running",
81-
JobStatus.ERROR: "Error",
82-
}
74+
STATUS_LABEL: ClassVar[dict[str, str]] = JOB_STATUS_LABEL
8375

8476
@property
8577
def status_label(self) -> str:

‎testgen/common/models/test_run.py‎

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
from sqlalchemy.orm.attributes import flag_modified
99
from sqlalchemy.sql.expression import case
1010

11-
from testgen.common.enums import JobStatus
11+
from testgen.common.enums import JOB_STATUS_LABEL, JobStatus
1212
from testgen.common.models import database_session, get_current_session
1313
from testgen.common.models.connection import Connection
1414
from testgen.common.models.entity import Entity, EntityMinimal
@@ -70,15 +70,7 @@ class TestRunSummary(EntityMinimal):
7070
dq_score_testing: float | None
7171
total_count: int
7272

73-
STATUS_LABEL: ClassVar[dict[str, str]] = {
74-
JobStatus.COMPLETED: "Completed",
75-
JobStatus.CANCELED: "Canceled",
76-
JobStatus.CANCEL_REQUESTED: "Canceling",
77-
JobStatus.PENDING: "Pending",
78-
JobStatus.CLAIMED: "Starting",
79-
JobStatus.RUNNING: "Running",
80-
JobStatus.ERROR: "Error",
81-
}
73+
STATUS_LABEL: ClassVar[dict[str, str]] = JOB_STATUS_LABEL
8274

8375
@property
8476
def status_label(self) -> str:

‎testgen/mcp/tools/execution.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,7 @@ def _render_submission(
133133
) -> str:
134134
doc = MdDoc()
135135
doc.heading(1, f"{kind} submitted for `{scope_name}`")
136-
doc.field("Job ID", job.id, code=True)
136+
doc.field(kind.title(), job.id, code=True)
137137
doc.field(scope_label, scope_name)
138138
doc.field("Status", "Pending")
139139
doc.text(f"Use `{poll_tool}` {poll_hint}.")
@@ -147,7 +147,7 @@ def _render_cancel(job: JobExecution, kind: str, poll_tool: str) -> str:
147147
)
148148
doc = MdDoc()
149149
doc.heading(1, f"{kind} cancellation requested")
150-
doc.field("Job ID", job.id, code=True)
150+
doc.field(kind.title(), job.id, code=True)
151151
doc.field("Status", job.status)
152152
doc.text(f"Use `{poll_tool}` to confirm cancellation.")
153153
return doc.render()

0 commit comments

Comments
 (0)