jev-mcp-python 0.1.0__py3-none-any.whl

jev_mcp/__init__.py

@@ -0,0 +1 @@
+"""Behavior-compatible Python rewrite of the TypeScript reference server 0.5.0 (see ROADMAP.md)."""

jev_mcp/__main__.py

@@ -0,0 +1,3 @@
+from jev_mcp.server import main
+
+main()

jev_mcp/domain/__init__.py

@@ -0,0 +1,32 @@
+"""Canonical questions, answers, and usage owned by jev_mcp, not SDK classes."""
+
+from jev_mcp.domain.answers import ChoiceAnswer, RawAnswer, ScoreAnswer
+from jev_mcp.domain.json import JsonValue, as_number, decode_json, is_json_object
+from jev_mcp.domain.questions import (
+    ChoiceQuestion,
+    Description,
+    NoulCriteria,
+    NoulQuestion,
+    Question,
+    ScoreQuestion,
+    questions_to_wire,
+)
+from jev_mcp.domain.usage import Usage
+
+__all__ = [
+    "ChoiceAnswer",
+    "ChoiceQuestion",
+    "Description",
+    "JsonValue",
+    "NoulCriteria",
+    "NoulQuestion",
+    "Question",
+    "RawAnswer",
+    "ScoreAnswer",
+    "ScoreQuestion",
+    "Usage",
+    "as_number",
+    "decode_json",
+    "is_json_object",
+    "questions_to_wire",
+]

jev_mcp/domain/answers.py

@@ -0,0 +1,25 @@
+"""Validated answers. Raw answers are whatever JSON the provider returned; validation turns them into these."""
+
+from dataclasses import dataclass
+
+type RawAnswer = object
+"""One answer as parsed from the provider envelope, before validation. Anything may arrive."""
+
+
+@dataclass(frozen=True, slots=True)
+class ChoiceAnswer:
+    """A Choice answer that passed `validate_choice`."""
+
+    choice: str
+    probabilities: dict[str, float]
+    """Every expected label, in the provider's key order."""
+    confidence: float | None
+    """`None` when the provider sent none or a malformed one. Unknown never satisfies a threshold."""
+
+
+@dataclass(frozen=True, slots=True)
+class ScoreAnswer:
+    """A Score answer that passed `validate_score`."""
+
+    score: float
+    confidence: float | None

jev_mcp/domain/json.py

@@ -0,0 +1,49 @@
+"""JSON value types, JSON text read as `JSON.parse` reads it, and parsed-JSON value-shape semantics (ADR-0019).
+
+Beyond decoding, this module answers exactly two kinds of question about a parsed JSON value: what
+JS `typeof` would say, and what shape it is. Nothing else belongs here — no answer semantics, no
+provider rules, no normalization; those live above, in `validation/` and `providers/`.
+"""
+
+import json
+import math
+from collections.abc import Mapping, Sequence
+from typing import TypeGuard
+
+type JsonValue = str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None
+
+
+def decode_json(text: str) -> object:
+    """`JSON.parse(text)`, raising `ValueError` where it throws.
+
+    `json.loads` also reads `NaN`, `Infinity`, and `-Infinity`, which `JSON.parse` rejects, so those
+    are refused here. A lone surrogate escape is kept as one code point, as `JSON.parse` keeps it.
+    Nesting too deep for Python's recursion limit is a `ValueError` too.
+    """
+    try:
+        return json.loads(text, parse_constant=_reject_constant)
+    except RecursionError as error:
+        raise ValueError("JSON nesting is too deep") from error
+
+
+def _reject_constant(name: str) -> object:
+    raise ValueError(f"{name} is not JSON")
+
+
+def is_json_object(value: object) -> TypeGuard[dict[str, object]]:
+    """A JSON object: not null, not an array, not a primitive (`index.ts:1170-1172`)."""
+    return isinstance(value, dict)
+
+
+def as_number(value: object) -> float | None:
+    """The float64 a JS `number` would hold, or `None` when `typeof value !== "number"`.
+
+    `bool` is an `int` in Python but a boolean in JS, so it is not a number. An integer too large
+    for a double becomes infinity, as `JSON.parse` would make it.
+    """
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        return None
+    try:
+        return float(value)
+    except OverflowError:
+        return math.inf if value > 0 else -math.inf

jev_mcp/domain/questions.py

@@ -0,0 +1,75 @@
+"""Canonical Choice, Noul, and Score questions, owned here rather than by any provider SDK.
+
+`to_wire()` reproduces the object the reference builds with `@typesafe-ai/sdk` 0.6.0
+`choice`/`noul`/`score`: keys `type`, `instructions`, `criteria`, in that order. The reference
+never omits Noul criteria, so a Noul without criteria is not representable.
+"""
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+from jev_mcp.domain.json import JsonValue
+
+type Description = JsonValue
+"""Text, a JSON object or array, or `None` for an undescribed label (the SDK's `EntryType`)."""
+
+
+@dataclass(frozen=True, slots=True)
+class ChoiceQuestion:
+    """Pick one label; every label gets a probability."""
+
+    instructions: Description
+    criteria: Mapping[str, Description]
+    type: Literal["choice"] = "choice"
+
+    def to_wire(self) -> dict[str, JsonValue]:
+        return {"type": self.type, "instructions": self.instructions, "criteria": dict(self.criteria)}
+
+
+@dataclass(frozen=True, slots=True)
+class NoulCriteria:
+    """Descriptions of the yes (`true`) and no (`false`) outcomes."""
+
+    true: Description
+    false: Description
+
+    def to_wire(self) -> dict[str, JsonValue]:
+        return {"true": self.true, "false": self.false}
+
+
+@dataclass(frozen=True, slots=True)
+class NoulQuestion:
+    """The probability that a yes/no condition holds; near 0.5 means uncertain, not medium."""
+
+    instructions: Description
+    criteria: NoulCriteria
+    type: Literal["noul"] = "noul"
+
+    def to_wire(self) -> dict[str, JsonValue]:
+        return {"type": self.type, "instructions": self.instructions, "criteria": self.criteria.to_wire()}
+
+
+@dataclass(frozen=True, slots=True)
+class ScoreQuestion:
+    """A probability-weighted position on ordered levels, 0-indexed: N levels score 0 to N-1."""
+
+    instructions: Description
+    criteria: Sequence[Description]
+    type: Literal["score"] = "score"
+
+    def __post_init__(self) -> None:
+        # The SDK rejects a score question with fewer than two levels before sending it.
+        if len(self.criteria) < 2:
+            raise ValueError("Score criteria must list at least two levels.")
+
+    def to_wire(self) -> dict[str, JsonValue]:
+        return {"type": self.type, "instructions": self.instructions, "criteria": list(self.criteria)}
+
+
+type Question = ChoiceQuestion | NoulQuestion | ScoreQuestion
+
+
+def questions_to_wire(questions: Mapping[str, Question]) -> dict[str, JsonValue]:
+    """The request body's `questions` object, in the caller's key order."""
+    return {name: question.to_wire() for name, question in questions.items()}

jev_mcp/domain/usage.py

@@ -0,0 +1,16 @@
+"""Token usage reported by a provider."""
+
+from dataclasses import dataclass
+
+from jev_mcp.domain.json import JsonValue
+
+
+@dataclass(frozen=True, slots=True)
+class Usage:
+    """Token counts for one provider request. A provider that reports none yields zeros (`provider.ts:120`)."""
+
+    input_tokens: int | float = 0
+    output_tokens: int | float = 0
+
+    def to_wire(self) -> dict[str, JsonValue]:
+        return {"input_tokens": self.input_tokens, "output_tokens": self.output_tokens}

jev_mcp/errors.py

@@ -0,0 +1,59 @@
+"""Error types and handler error text, and secret redaction (ADR-0008)."""
+
+import logging
+from collections.abc import Iterable
+from urllib.parse import urlsplit
+
+REDACTED = "[redacted]"
+
+
+class Redactor:
+    """Replaces every configured secret with `[redacted]` in MCP-visible text and log lines (ADR-0008).
+
+    Replacement is of the exact value, so `Bearer <secret>` is covered. A secret that is a URL with
+    userinfo also contributes its userinfo and password: an HTTP client may print the URL
+    normalized (lowercased host, added `/`), and the credential must not survive that.
+    """
+
+    def __init__(self, secrets: Iterable[str]) -> None:
+        values = {value for secret in secrets for value in (secret, *_userinfo_parts(secret)) if value}
+        # Longest first, so a secret containing another is replaced whole.
+        self._secrets = sorted(values, key=len, reverse=True)
+
+    def __call__(self, text: str) -> str:
+        for secret in self._secrets:
+            text = text.replace(secret, REDACTED)
+        return text
+
+
+def _userinfo_parts(secret: str) -> tuple[str, ...]:
+    try:
+        parts = urlsplit(secret)
+    except ValueError:
+        return ()
+    if not parts.scheme or "@" not in parts.netloc:
+        return ()
+    userinfo = parts.netloc.rpartition("@")[0]
+    password = userinfo.partition(":")[2]
+    return (userinfo, password)
+
+
+class RedactingFilter(logging.Filter):
+    """A handler filter that redacts the fully formatted message, including exception text."""
+
+    def __init__(self, redact: Redactor) -> None:
+        super().__init__()
+        self._redact = redact
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.msg = self._redact(record.getMessage())
+        record.args = None
+        if record.exc_info is not None:
+            # Render the traceback now, redacted, so the formatter never sees the raw exception.
+            record.exc_text = self._redact(logging.Formatter().formatException(record.exc_info))
+            record.exc_info = None
+        elif record.exc_text:
+            record.exc_text = self._redact(record.exc_text)
+        if record.stack_info:
+            record.stack_info = self._redact(record.stack_info)
+        return True

jev_mcp/extract/__init__.py

@@ -0,0 +1 @@
+"""jev_extract regex dialect gate and killable worker pool (ADR-0004). Populated in P5."""

jev_mcp/extract/candidates.py

@@ -0,0 +1,75 @@
+"""One field's candidate pipeline: caller pattern and flags in, verbatim candidates or a refusal out.
+
+The whole path the reference runs per field (`index.ts:884-903`), for production and the Node
+differential test alike: normalize the flags, translate the dialect (ADR-0004), take the absolute
+deadline before admission (ADR-0016), run the executor, map candidates back from unit space, and
+classify every refusal into its caller-facing reason. Executors return plain results
+(`executor.MatchResult`); the frozen reason text lives only here.
+"""
+
+from dataclasses import dataclass
+from time import monotonic
+from typing import Final, Literal
+
+from jev_mcp.extract.dialect import PatternRejected, from_units, translate
+from jev_mcp.extract.executor import Invalid, Matches, RegexExecutor, Saturated, Timeout, Unavailable
+
+REGEX_TIMEOUT_S: Final = 1.0
+"""`REGEX_TIMEOUT_MS` (`lib.ts:185`)."""
+
+REGEX_TIMEOUT_REASON: Final = "regex timed out after 1000ms; simplify the pattern"
+
+REGEX_POOL_SATURATED_REASON: Final = "regex_pool_saturated"
+"""ADR-0025: a queue-bound refusal is a capacity signal, not a pattern problem — no timeout
+figure, no advice about the pattern, a stable token an agent (or P9) can tell apart."""
+
+_UNAVAILABLE_REASONS: Final = {
+    Unavailable.NO_RESULT: "regex worker exited without a result",
+    Unavailable.NOT_STARTED: "regex worker did not start",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Found:
+    """The field's candidates, verbatim document text in match order."""
+
+    candidates: list[str]
+    truncated: bool
+    too_long: int
+
+
+@dataclass(frozen=True, slots=True)
+class Refused:
+    """No candidates: `reason` is the caller-facing text, `outcome` the telemetry label."""
+
+    outcome: Literal["rejected", "saturated", "timeout", "worker_error"]
+    reason: str
+
+
+def normalize_flags(flags: str) -> str:
+    """`((flags ?? "").replace(/[^a-z]/g, "") + "g").replace(/g+/g, "g")` (`index.ts:992`)."""
+    letters = "".join(char for char in flags if "a" <= char <= "z") + "g"
+    out: list[str] = []
+    for char in letters:
+        if not (char == "g" and out and out[-1] == "g"):
+            out.append(char)
+    return "".join(out)
+
+
+async def find_candidates(executor: RegexExecutor, pattern: str, flags: str, units: str) -> Found | Refused:
+    """Run caller `pattern` with caller `flags` over unit-space `units` (`dialect.to_units`)."""
+    try:
+        translated = translate(pattern, normalize_flags(flags))
+    except PatternRejected as rejected:
+        return Refused("rejected", str(rejected))
+    result = await executor.find(translated, units, deadline=monotonic() + REGEX_TIMEOUT_S)
+    match result:
+        case Matches(candidates, truncated, too_long):
+            return Found([from_units(candidate) for candidate in candidates], truncated, too_long)
+        case Saturated():
+            # Its own reason: the refusal spends no time, so it must not borrow the timeout's voice.
+            return Refused("saturated", REGEX_POOL_SATURATED_REASON)
+        case Timeout():
+            return Refused("timeout", REGEX_TIMEOUT_REASON)
+        case Invalid(cause):
+            return Refused("worker_error", _UNAVAILABLE_REASONS[cause])