latris 0.3.0__py3-none-any.whl

latris/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

latris/__main__.py

@@ -0,0 +1,4 @@
+from latris.cli.app import app
+
+if __name__ == "__main__":
+    app()

latris/_mutation_signal.py

@@ -0,0 +1,34 @@
+"""Cross-layer signal that a server-initiated mutation just happened.
+
+Lives at the package root (alongside :mod:`latris.perf`) so
+``operations/commit.py`` can fire it from ``auto_commit`` without
+importing from the ``server/`` layer. The file watcher reads this
+signal to suppress redundant ``state_changed`` broadcasts after the
+GUI's own mutation response has already rehydrated its store.
+
+The mechanism is a 2-second wall-clock window: any file change
+detected within :data:`SUPPRESS_SECONDS` of the last
+:func:`mark_own_mutation` call is treated as our own write and
+silently dropped. The window is intentionally short — external
+mutations (CLI runs, another editor) still get a broadcast as soon
+as the window expires.
+"""
+
+from __future__ import annotations
+
+import time
+
+SUPPRESS_SECONDS = 2.0
+
+_last_own_mutation: float = 0.0
+
+
+def mark_own_mutation() -> None:
+    """Stamp the suppression window. Called by ``auto_commit`` on a real commit."""
+    global _last_own_mutation  # noqa: PLW0603
+    _last_own_mutation = time.monotonic()
+
+
+def is_suppressed() -> bool:
+    """True if a server mutation happened within the suppression window."""
+    return (time.monotonic() - _last_own_mutation) < SUPPRESS_SECONDS

latris/ai/adapters/__init__.py

@@ -0,0 +1,43 @@
+"""Chat adapters — how we get a typed proposal out of an LLM.
+
+The rest of the codebase only ever imports ``get_adapter()`` from here.
+Selection is environment-driven so tests and CI can run without network.
+"""
+
+from __future__ import annotations
+
+import os
+
+from latris.ai.adapters.base import ChatAdapter, ChatResult
+from latris.ai.adapters.mock_adapter import MockAdapter
+
+MOCK_ENV_VAR = "LATRIS_AI_MOCK"
+# One-release back-compat: environments exported before the rename (and the
+# private app repo's CI during the transition) may still set the old name.
+_LEGACY_MOCK_ENV_VAR = "GRAPH_TOOLING_AI_MOCK"
+
+
+def mock_enabled() -> bool:
+    """True when AI mocking is requested via env: ``LATRIS_AI_MOCK``, falling
+    back to the pre-rename ``GRAPH_TOOLING_AI_MOCK`` for one release."""
+    value = os.environ.get(MOCK_ENV_VAR) or os.environ.get(_LEGACY_MOCK_ENV_VAR) or ""
+    return value.lower() in ("1", "true", "yes")
+
+
+def get_adapter() -> ChatAdapter:
+    """Return the active chat adapter.
+
+    If ``LATRIS_AI_MOCK`` is truthy, return a ``MockAdapter`` — zero
+    network, deterministic responses from whatever's been registered via
+    ``MockAdapter.register(...)``. Otherwise return the ``LiteLLMAdapter``.
+    """
+    if mock_enabled():
+        return MockAdapter.shared()
+    # Lazy import: litellm is heavy and pulls in several transitive deps on
+    # first import. No reason to pay that cost in mock mode.
+    from latris.ai.adapters.litellm_adapter import LiteLLMAdapter
+
+    return LiteLLMAdapter()
+
+
+__all__ = ["ChatAdapter", "ChatResult", "MockAdapter", "get_adapter", "mock_enabled"]

latris/ai/adapters/base.py

@@ -0,0 +1,88 @@
+"""The chat adapter interface — one chokepoint for every LLM call."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Protocol, TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class LLMCallError(RuntimeError):
+    """Provider-error wrapper with API keys scrubbed from the message.
+
+    Raised by adapters instead of propagating provider-specific exceptions
+    that may contain keys in URLs or headers. The CLI error handler catches
+    this and prints a clean, safe message.
+
+    ``raw_response`` carries the model's last raw output when the adapter
+    can extract it (e.g. instructor's ``InstructorRetryException`` exposes
+    the failed completion under ``last_completion``). It exists so the
+    interaction logger can persist the malformed payload for diagnosis
+    rather than throwing it away with the exception.
+    """
+
+    def __init__(self, message: str, *, raw_response: str | None = None) -> None:
+        super().__init__(message)
+        self.raw_response = raw_response
+
+
+# Known API-key shapes. Order matters — the generic ``sk-`` must come last.
+_KEY_PATTERNS = [
+    re.compile(r"AIza[0-9A-Za-z_-]{20,}"),  # Google AI Studio / Gemini
+    re.compile(r"sk-ant-(?:api\d+-)?[0-9A-Za-z_-]{20,}"),  # Anthropic
+    re.compile(r"sk-proj-[0-9A-Za-z_-]{20,}"),  # OpenAI project keys
+    re.compile(r"sk-svcacct-[0-9A-Za-z_-]{20,}"),  # OpenAI service accounts
+    re.compile(r"gsk_[0-9A-Za-z_-]{20,}"),  # Groq
+    re.compile(r"xai-[0-9A-Za-z_-]{20,}"),  # xAI
+    re.compile(r"[?&]key=[0-9A-Za-z_-]{20,}"),  # any ?key=... in URLs
+    re.compile(r"sk-[0-9A-Za-z_-]{20,}"),  # OpenAI legacy (keep last)
+]
+
+
+def redact_secrets(text: str) -> str:
+    """Scrub anything that looks like an API key. Safe to call on tracebacks."""
+    if not text:
+        return text
+    for pat in _KEY_PATTERNS:
+        text = pat.sub("<REDACTED>", text)
+    return text
+
+
+@dataclass
+class ChatResult:
+    """What every adapter returns.
+
+    - ``parsed`` is the pydantic-validated structured output (what the caller
+      actually wanted — e.g. a ``ChallengeProposal``).
+    - ``raw`` is the model's full text response, stashed for the interaction
+      log so a future retrieval layer has verbatim memory.
+    - ``token_usage`` is provider-reported token counts; shape is free-form
+      but we standardise on ``input_tokens`` / ``output_tokens`` /
+      ``cache_read_tokens`` / ``cache_write_tokens`` where applicable.
+    - ``cost_usd`` is the estimated dollar cost for this call, if available.
+    """
+
+    parsed: BaseModel
+    raw: str
+    model_id: str
+    token_usage: dict[str, Any] = field(default_factory=dict)
+    cost_usd: float | None = None
+
+
+class ChatAdapter(Protocol):
+    """Minimum contract: ask a model for a typed response."""
+
+    def chat(
+        self,
+        *,
+        model: str,
+        system: str,
+        user: str,
+        response_model: type[T],
+        temperature: float = 0.3,
+        max_tokens: int | None = None,
+    ) -> ChatResult: ...

latris/ai/adapters/litellm_adapter.py

@@ -0,0 +1,272 @@
+"""Real LLM calls via litellm + instructor.
+
+litellm normalises the chat-completion API across Anthropic / OpenAI /
+Gemini / Groq / Ollama / etc. Instructor wraps it with pydantic-native
+structured output (JSON schema + validation + retry on bad output).
+
+We never store keys here — litellm reads them from env vars, which the
+call orchestrator populates from keyring just before each call and unsets
+after.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from latris.ai import config as ai_config
+from latris.ai.adapters.base import ChatResult, LLMCallError, redact_secrets
+from latris.perf import span
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def _is_json_parse_error(exc: BaseException) -> bool:
+    """Heuristic: did this exception come from a malformed-JSON response?
+
+    Pydantic's ValidationError for JSON-mode structured output surfaces
+    the message ``"Invalid JSON: ..."`` (see
+    https://errors.pydantic.dev/2.12/v/json_invalid). Instructor wraps
+    the validation error and propagates it; the substring match here is
+    deliberately broad — false positives just spend one extra call,
+    false negatives leak through to fail-loud where Layer 1 records
+    them. Both error message and class name are searched because
+    instructor's wrapper sometimes obscures the inner message.
+    """
+    text = f"{type(exc).__name__}: {exc}".lower()
+    return "invalid json" in text or "jsondecodeerror" in text
+
+
+def _build_repair_messages(
+    *,
+    system: str,
+    user: str,
+    raw_response: str,
+    parser_error: str,
+    response_model: type[BaseModel],
+) -> list[dict[str, str]]:
+    """Construct the message list for a self-correction retry.
+
+    The model gets to see what it produced and the parser's complaint,
+    so it can fix the structural issue (typically an unescaped quote
+    or newline inside a string value) rather than re-generating
+    blindly. We cap the embedded raw response and parser error to
+    keep the repair prompt from approaching the context window in
+    pathological cases.
+    """
+    raw_excerpt = raw_response[:4000]
+    err_excerpt = parser_error[:1000]
+    repair_user = (
+        f"{user}\n\n"
+        "Your previous response could not be parsed as a valid JSON "
+        f"object matching the {response_model.__name__} schema:\n\n"
+        f"<failed_response>\n{raw_excerpt}\n</failed_response>\n\n"
+        "Parser error:\n"
+        f"<parser_error>\n{err_excerpt}\n</parser_error>\n\n"
+        "Re-emit the same intent as a valid JSON object. Common "
+        "issues to check: unescaped double quotes inside string "
+        'values (use \\"), literal newlines inside string values '
+        "(use \\n), stray backslashes (use \\\\), and trailing "
+        "commas. Output only the JSON object, no prose around it."
+    )
+    return [
+        {"role": "system", "content": system},
+        {"role": "user", "content": repair_user},
+    ]
+
+
+class LiteLLMAdapter:
+    """Lazy-imported litellm+instructor. Constructed once per process."""
+
+    def __init__(self) -> None:
+        # Import lazily so mock-mode runs don't pay the litellm import cost.
+        import instructor  # type: ignore[import-untyped]
+        import litellm  # type: ignore[import-untyped]
+
+        self._instructor = instructor
+        self._instructor_client_tools = instructor.from_litellm(litellm.completion)
+        self._instructor_client_json = instructor.from_litellm(
+            litellm.completion,
+            mode=instructor.Mode.JSON,
+        )
+        self._litellm = litellm
+
+    def chat(
+        self,
+        *,
+        model: str,
+        system: str,
+        user: str,
+        response_model: type[T],
+        temperature: float = 0.3,
+        max_tokens: int | None = None,
+    ) -> ChatResult:
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ]
+        # `create_with_completion` returns (parsed_model, raw_completion) so we
+        # can keep the verbatim response for the interaction log. Any provider
+        # error is re-wrapped as an ``LLMCallError`` with API keys scrubbed.
+        #
+        # Gemini models fail with Mode.TOOLS on complex schemas (optional/union
+        # fields return empty completions); Moonshot's thinking models reject
+        # the explicit tool_choice TOOLS mode sends ("tool_choice 'specified'
+        # is incompatible with thinking enabled"). Both use Mode.JSON.
+        lowered = model.lower()
+        uses_json_mode = lowered.startswith("gemini") or lowered.startswith("moonshot")
+        client = self._instructor_client_json if uses_json_mode else self._instructor_client_tools
+
+        try:
+            with span("adapter.chat", model=model):
+                parsed, raw_completion = self._call(
+                    client=client,
+                    model=model,
+                    messages=messages,
+                    response_model=response_model,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                )
+        except Exception as exc:
+            raw_response = self._extract_last_raw_response(exc)
+            # On parse failure, do one self-correction pass: feed the malformed
+            # output back to the model with the parser error and ask for valid
+            # JSON. Instructor's own retry doesn't show the model what it
+            # produced — that's the meaningful step-up.
+            if raw_response and _is_json_parse_error(exc):
+                try:
+                    with span("adapter.chat.repair", model=model):
+                        parsed, raw_completion = self._call(
+                            client=client,
+                            model=model,
+                            messages=_build_repair_messages(
+                                system=system,
+                                user=user,
+                                raw_response=raw_response,
+                                parser_error=str(exc),
+                                response_model=response_model,
+                            ),
+                            response_model=response_model,
+                            temperature=temperature,
+                            max_tokens=max_tokens,
+                        )
+                except Exception as repair_exc:
+                    # Repair pass also failed — raise wrapping the *repair*
+                    # error since that's the most recent (still safe — both
+                    # error messages and raw response are scrubbed).
+                    safe_message = redact_secrets(str(repair_exc))
+                    repair_raw = self._extract_last_raw_response(repair_exc) or raw_response
+                    raise LLMCallError(
+                        f"{type(repair_exc).__name__} from {model} (repair pass): {safe_message}",
+                        raw_response=redact_secrets(repair_raw) or None,
+                    ) from None
+            else:
+                safe_message = redact_secrets(str(exc))
+                raise LLMCallError(
+                    f"{type(exc).__name__} from {model}: {safe_message}",
+                    raw_response=redact_secrets(raw_response or "") or None,
+                ) from None
+
+        token_usage = self._extract_token_usage(raw_completion)
+        cost_usd = self._try_completion_cost(raw_completion)
+        raw_text = self._first_text_content(raw_completion)
+
+        return ChatResult(
+            parsed=parsed,
+            raw=raw_text,
+            model_id=model,
+            token_usage=token_usage,
+            cost_usd=cost_usd,
+        )
+
+    def _call(
+        self,
+        *,
+        client: Any,
+        model: str,
+        messages: list[dict[str, str]],
+        response_model: type[T],
+        temperature: float,
+        max_tokens: int | None,
+    ) -> tuple[T, Any]:
+        """Single instructor invocation. Extracted so the repair pass can
+        reuse the same code path with different messages."""
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "response_model": response_model,
+            "temperature": temperature,
+            # Bumped from 1 → 3 alongside Layer 2's repair pass. Instructor
+            # retries on validation error (missing field, wrong type) — a
+            # higher budget helps with transient hiccups before we burn the
+            # one repair attempt below on actual JSON-parse failures.
+            "max_retries": 3,
+        }
+        if max_tokens is not None:
+            kwargs["max_tokens"] = max_tokens
+        extra_body = ai_config.resolve_extra_body(model)
+        if extra_body:
+            kwargs["extra_body"] = extra_body
+        return client.chat.completions.create_with_completion(**kwargs)
+
+    # ---- helpers ----
+
+    @staticmethod
+    def _extract_token_usage(completion: Any) -> dict[str, Any]:
+        usage = getattr(completion, "usage", None)
+        if usage is None:
+            return {}
+        # Usage fields vary per provider; collect the standard ones.
+        out: dict[str, Any] = {}
+        for src_key, dst_key in (
+            ("prompt_tokens", "input_tokens"),
+            ("completion_tokens", "output_tokens"),
+            ("total_tokens", "total_tokens"),
+            ("cache_read_input_tokens", "cache_read_tokens"),
+            ("cache_creation_input_tokens", "cache_write_tokens"),
+        ):
+            value = getattr(usage, src_key, None)
+            if value is not None:
+                out[dst_key] = value
+        return out
+
+    def _try_completion_cost(self, completion: Any) -> float | None:
+        try:
+            return float(self._litellm.completion_cost(completion_response=completion))
+        except Exception:
+            return None
+
+    @staticmethod
+    def _first_text_content(completion: Any) -> str:
+        try:
+            choices = getattr(completion, "choices", None) or []
+            if not choices:
+                return ""
+            msg = getattr(choices[0], "message", None)
+            return getattr(msg, "content", "") or ""
+        except Exception:
+            return ""
+
+    @classmethod
+    def _extract_last_raw_response(cls, exc: BaseException) -> str | None:
+        """Best-effort pull of the failed model output from instructor's exception.
+
+        Instructor's ``InstructorRetryException`` exposes the last completion
+        under ``last_completion`` (a chat-completion-shaped object). When
+        retries are exhausted on a parse failure, this is the malformed
+        payload we need for diagnosis. Falls back to ``messages`` /
+        ``raw_response`` attribute names other instructor versions use.
+        """
+        for attr in ("last_completion", "raw_response", "completion"):
+            completion = getattr(exc, attr, None)
+            if completion is None:
+                continue
+            text = cls._first_text_content(completion)
+            if text:
+                return text
+        # InstructorRetryException stores the rendered prompt under `messages`
+        # and the parser failure under `n_attempts` / `total_usage`; the raw
+        # text we want isn't always reachable. Last resort: stringify the
+        # exception's traceback tail.
+        return None

latris/ai/adapters/mock_adapter.py

@@ -0,0 +1,105 @@
+"""Deterministic mock adapter — hermetic for tests and demos.
+
+Tests or dev sessions pre-register canned ``ChatResult``s keyed by prompt
+signature; ``chat()`` looks the key up and returns the canned result.
+Falls through to a generic stub if nothing is registered for the key —
+useful for smoke runs where we just want no-network behaviour.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import TypeVar
+
+from pydantic import BaseModel
+
+from latris.ai.adapters.base import ChatResult
+
+T = TypeVar("T", bound=BaseModel)
+
+_SHARED: MockAdapter | None = None
+
+
+def _signature(model: str, system: str, user: str, response_cls: type[BaseModel]) -> str:
+    hasher = hashlib.sha256()
+    hasher.update(model.encode("utf-8"))
+    hasher.update(b"\x00")
+    hasher.update(system.encode("utf-8"))
+    hasher.update(b"\x00")
+    hasher.update(user.encode("utf-8"))
+    hasher.update(b"\x00")
+    hasher.update(response_cls.__name__.encode("utf-8"))
+    return hasher.hexdigest()
+
+
+class MockAdapter:
+    """In-memory fake. Not thread-safe; tests serialise their own state."""
+
+    def __init__(self) -> None:
+        self._registry: dict[str, ChatResult] = {}
+        self._default_by_response_cls: dict[str, ChatResult] = {}
+
+    # ---- registration ----
+
+    def register(
+        self,
+        *,
+        model: str,
+        system: str,
+        user: str,
+        response_cls: type[BaseModel],
+        result: ChatResult,
+    ) -> None:
+        """Bind an exact ``(model, system, user, response_cls)`` to a canned result."""
+        self._registry[_signature(model, system, user, response_cls)] = result
+
+    def register_default(
+        self,
+        *,
+        response_cls: type[BaseModel],
+        result: ChatResult,
+    ) -> None:
+        """Fallback for any call whose response_cls matches, regardless of prompt."""
+        self._default_by_response_cls[response_cls.__name__] = result
+
+    def clear(self) -> None:
+        self._registry.clear()
+        self._default_by_response_cls.clear()
+
+    # ---- adapter protocol ----
+
+    def chat(
+        self,
+        *,
+        model: str,
+        system: str,
+        user: str,
+        response_model: type[T],
+        temperature: float = 0.3,
+        max_tokens: int | None = None,
+    ) -> ChatResult:
+        key = _signature(model, system, user, response_model)
+        if key in self._registry:
+            return self._registry[key]
+        fallback = self._default_by_response_cls.get(response_model.__name__)
+        if fallback is not None:
+            return fallback
+        raise LookupError(
+            f"MockAdapter: no canned response registered for response_model="
+            f"{response_model.__name__} (model={model!r}). Register one via "
+            "MockAdapter.shared().register(...) / register_default(...)."
+        )
+
+    # ---- process-wide singleton ----
+
+    @classmethod
+    def shared(cls) -> MockAdapter:
+        global _SHARED
+        if _SHARED is None:
+            _SHARED = cls()
+        return _SHARED
+
+    @classmethod
+    def reset_shared(cls) -> None:
+        global _SHARED
+        _SHARED = None