docent-python 0.1.62a0__tar.gz → 0.1.63a0__tar.gz

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docent-python
-Version: 0.1.62a0
+Version: 0.1.63a0
 Summary: Docent SDK
 Project-URL: Homepage, https://github.com/TransluceAI/docent
 Project-URL: Issues, https://github.com/TransluceAI/docent/issues

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/__init__.py

@@ -4,6 +4,7 @@ __all__ = [
     "load_config_file",
     "AgentRunRef",
     "TranscriptRef",
+    "TranscriptSliceRef",
     "ReadingResultRef",
     "ResultRef",
     "Prompt",
@@ -17,4 +18,5 @@ from docent.sdk.llm_context import (
     ReadingResultRef,
     ResultRef,
     TranscriptRef,
+    TranscriptSliceRef,
 )

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/_llm_util/data_models/exceptions.py

@@ -35,6 +35,11 @@ class ContextWindowException(LLMException):
     user_message = "Context window exceeded."
 
 
+class InvalidPromptException(LLMException):
+    error_type_id = "invalid_prompt"
+    user_message = "The model provider rejected this prompt for safety reasons."
+
+
 class NoResponseException(LLMException):
     error_type_id = "no_response"
     user_message = "The model returned an empty response. Please try again later."
@@ -45,6 +50,17 @@ class DocentUsageLimitException(LLMException):
     user_message = "Free daily usage limit reached. Add your own API key in settings or contact us for increased limits."
 
 
+class ProviderAuthenticationException(LLMException):
+    error_type_id = "provider_authentication"
+
+    def __init__(self, message: str = ""):
+        super().__init__(message)
+        self.user_message = (
+            "The model provider API key could not be authenticated. "
+            "If you added your own key, update it in Settings > Model providers."
+        )
+
+
 class ValidationFailedException(LLMException):
     error_type_id = "validation_failed"
     user_message = "The model returned invalid output that failed validation."
@@ -64,8 +80,10 @@ LLM_ERROR_TYPES: list[type[LLMException]] = [
     CompletionTooLongException,
     RateLimitException,
     ContextWindowException,
+    InvalidPromptException,
     NoResponseException,
     DocentUsageLimitException,
+    ProviderAuthenticationException,
     ValidationFailedException,
     TimeoutException,
 ]

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/_llm_util/data_models/llm_output.py

@@ -154,7 +154,7 @@ class LLMOutput:
         ]
         errors_to_log = [e for e in errors if e not in error_types_to_not_log]
         if errors_to_log:
-            logger.error(f"Loading LLM output with errors: {errors}")
+            logger.error("Loading LLM output with errors: %s", errors)
         errors = [error_type_map.get(e, LLMException)() for e in errors]
 
         completions = data.get("completions", [])

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/_llm_util/llm_svc.py

@@ -208,7 +208,7 @@ async def _parallelize_calls(
                 except asyncio.TimeoutError as e:
                     timeout_exception = TimeoutException(str(e) or "Request timed out")
                     timeout_exception.__cause__ = e
-                    logger.error(f"Call to {model_name} timed out")
+                    logger.error("Call to %s timed out", model_name)
                     result = LLMOutput(
                         model=model_name,
                         completions=[],
@@ -218,7 +218,9 @@ async def _parallelize_calls(
                 except Exception as e:
                     if not isinstance(e, LLMException):
                         logger.error(
-                            f"LLM call raised an exception that is not an LLMException: {e}. Failure traceback:\n{traceback.format_exc()}"
+                            "LLM call raised an exception that is not an LLMException: %s. Failure traceback:\n%s",
+                            e,
+                            traceback.format_exc(),
                         )
                         llm_exception = LLMException(e)
                         llm_exception.__cause__ = e
@@ -346,7 +348,7 @@ class BaseLLMService:
                 return None
 
             new_model_option = model_options[current_model_option_index]
-            logger.warning(f"Switched to next model {new_model_option.model_name}")
+            logger.warning("Switched to next model %s", new_model_option.model_name)
             return new_model_option
 
         while True:
@@ -410,7 +412,7 @@ class BaseLLMService:
                 )
             )
             if num_rotation_errors > 0:
-                logger.warning(f"{model_name}: {num_rotation_errors} API errors")
+                logger.warning("%s: %s API errors", model_name, num_rotation_errors)
                 if not _rotate_model_option():
                     break
             else:

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/_llm_util/model_registry.py

@@ -183,7 +183,7 @@ def get_model_info(model_name: str) -> Optional[ModelInfo]:
 def get_context_window(model_name: str) -> int:
     info = get_model_info(model_name)
     if info is None:
-        logger.warning(f"No context window found for model {model_name}")
+        logger.warning("No context window found for model %s", model_name)
         return 100_000
     return info.context_window
 
@@ -196,11 +196,11 @@ def get_rates_for_model_name(model_name: str) -> Optional[ModelRate]:
 def estimate_cost_cents(model_name: str, token_count: int, token_type: TokenType) -> float:
     rate = get_rates_for_model_name(model_name)
     if rate is None:
-        logger.warning(f"No rate found for model {model_name}")
+        logger.warning("No rate found for model %s", model_name)
         return 0.0
     usd_per_mtok = rate.get(token_type)
     if usd_per_mtok is None:
-        logger.warning(f"No rate found for model {model_name} token type {token_type}")
+        logger.warning("No rate found for model %s token type %s", model_name, token_type)
         return 0.0
     cents_per_token = usd_per_mtok * 100 / 1_000_000.0
     return token_count * cents_per_token

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/_llm_util/providers/anthropic.py

@@ -41,6 +41,7 @@ from docent._llm_util.data_models.exceptions import (
     CompletionTooLongException,
     ContextWindowException,
     NoResponseException,
+    ProviderAuthenticationException,
     RateLimitException,
 )
 from docent._llm_util.data_models.llm_output import (
@@ -78,7 +79,9 @@ ANTHROPIC_STRUCTURED_OUTPUTS_BETA = "structured-outputs-2025-11-13"
 
 def _print_backoff_message(e: Details):
     logger.warning(
-        f"Anthropic backing off for {e['wait']:.2f}s due to {e['exception'].__class__.__name__}"  # type: ignore
+        "Anthropic backing off for %.2fs due to %s",
+        e["wait"],  # type: ignore
+        e["exception"].__class__.__name__,  # type: ignore
     )
 
 
@@ -86,6 +89,7 @@ def _is_retryable_error(e: BaseException) -> bool:
     if (
         isinstance(e, BadRequestError)
         or isinstance(e, ContextWindowException)
+        or isinstance(e, ProviderAuthenticationException)
         or isinstance(e, AuthenticationError)
         or isinstance(e, NotImplementedError)
         or isinstance(e, PermissionDeniedError)
@@ -209,6 +213,8 @@ def _build_output_format(response_format: ResponseFormat | None) -> dict[str, An
 
 
 def _convert_anthropic_error(e: Exception):
+    if isinstance(e, (AuthenticationError, PermissionDeniedError)):
+        return ProviderAuthenticationException(e.message)
     if isinstance(e, BadRequestError):
         if "context limit" in e.message.lower() or "prompt is too long" in e.message.lower():
             return ContextWindowException()
@@ -285,7 +291,7 @@ async def get_anthropic_chat_completion_streaming_async(
                 if llm_output_partial:
                     return finalize_llm_output_partial(llm_output_partial)
                 return LLMOutput(model=model_name, completions=[], errors=[NoResponseException()])
-        except (RateLimitError, BadRequestError) as e:
+        except (RateLimitError, BadRequestError, AuthenticationError, PermissionDeniedError) as e:
             if e2 := _convert_anthropic_error(e):
                 raise e2 from e
             raise
@@ -365,7 +371,7 @@ def update_llm_output(
             ):
                 # This should not happen with a well-behaved API, log and skip
                 logger.warning(
-                    f"Received InputJSONDelta before start event at index {index}, skipping"
+                    "Received InputJSONDelta before start event at index %s, skipping", index
                 )
             else:
                 cur_tool_calls[index] = ToolCallPartial(
@@ -482,7 +488,7 @@ async def get_anthropic_chat_completion_async(
                     )
 
                 return output
-        except (RateLimitError, BadRequestError) as e:
+        except (RateLimitError, BadRequestError, AuthenticationError, PermissionDeniedError) as e:
             if e2 := _convert_anthropic_error(e):
                 raise e2 from e
             raise

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/_llm_util/providers/google.py

@@ -11,6 +11,7 @@ from docent._llm_util.data_models.exceptions import (
     CompletionTooLongException,
     ContextWindowException,
     NoResponseException,
+    ProviderAuthenticationException,
     RateLimitException,
 )
 from docent._llm_util.data_models.llm_output import (
@@ -41,7 +42,9 @@ logger = get_logger(__name__)
 
 
 def _convert_google_error(e: errors.APIError):
-    if e.code in [429, 502, 503, 504]:
+    if e.code in [401, 403]:
+        return ProviderAuthenticationException(str(e))
+    elif e.code in [429, 502, 503, 504]:
         return RateLimitException(e)
     elif e.code == 400 and "maximum number of tokens" in str(e).lower():
         return ContextWindowException()
@@ -50,12 +53,18 @@ def _convert_google_error(e: errors.APIError):
 
 def _print_backoff_message(e: Any):
     logger.warning(
-        f"Google backing off for {e['wait']:.2f}s due to {e['exception'].__class__.__name__}"  # type: ignore
+        "Google backing off for %.2fs due to %s",
+        e["wait"],  # type: ignore
+        e["exception"].__class__.__name__,  # type: ignore
     )
 
 
 def _is_retryable_error(exception: BaseException) -> bool:
     """Checks if the exception is a retryable error based on the criteria."""
+    if isinstance(exception, RateLimitException):
+        return True
+    if isinstance(exception, (ContextWindowException, CompletionTooLongException)):
+        return False
     if isinstance(exception, errors.APIError):
         return exception.code in [429, 500, 502, 503, 504]
     if isinstance(exception, requests.exceptions.ConnectionError):
@@ -112,39 +121,46 @@ async def get_google_chat_completion_async(
             model_name=model_name,
         )
 
-        async with async_timeout_ctx(timeout):
-            thinking_cfg = None
-            if reasoning_effort:
-                thinking_cfg = types.ThinkingConfig(
-                    include_thoughts=True,
-                    thinking_budget=reasoning_budget(max_new_tokens, reasoning_effort),
-                )
+        try:
+            async with async_timeout_ctx(timeout):
+                thinking_cfg = None
+                if reasoning_effort:
+                    thinking_cfg = types.ThinkingConfig(
+                        include_thoughts=True,
+                        thinking_budget=reasoning_budget(max_new_tokens, reasoning_effort),
+                    )
 
-            raw_output = await client.models.generate_content(  # type: ignore
-                model=model_name,
-                contents=input_messages,  # type: ignore
-                config=types.GenerateContentConfig(
-                    temperature=temperature,
-                    thinking_config=thinking_cfg,
-                    max_output_tokens=max_new_tokens,
-                    system_instruction=system,
-                    tools=cast(Any, _parse_tools(tools)) if tools else None,
-                    tool_config=(
-                        types.ToolConfig(function_calling_config=_parse_tool_choice(tool_choice))
-                        if tool_choice is not None
-                        else None
+                raw_output = await client.models.generate_content(  # type: ignore
+                    model=model_name,
+                    contents=input_messages,  # type: ignore
+                    config=types.GenerateContentConfig(
+                        temperature=temperature,
+                        thinking_config=thinking_cfg,
+                        max_output_tokens=max_new_tokens,
+                        system_instruction=system,
+                        tools=cast(Any, _parse_tools(tools)) if tools else None,
+                        tool_config=(
+                            types.ToolConfig(
+                                function_calling_config=_parse_tool_choice(tool_choice)
+                            )
+                            if tool_choice is not None
+                            else None
+                        ),
+                        **response_format_config,
                     ),
-                    **response_format_config,
-                ),
-            )
-
-            output = _parse_google_completion(raw_output, model_name)
-            if output.first and output.first.finish_reason == "length" and output.first.no_text:
-                raise CompletionTooLongException(
-                    f"Completion empty due to truncation. Consider increasing max_new_tokens (currently {max_new_tokens})."
                 )
 
-            return output
+                output = _parse_google_completion(raw_output, model_name)
+                if output.first and output.first.finish_reason == "length" and output.first.no_text:
+                    raise CompletionTooLongException(
+                        f"Completion empty due to truncation. Consider increasing max_new_tokens (currently {max_new_tokens})."
+                    )
+
+                return output
+        except errors.APIError as e:
+            if e2 := _convert_google_error(e):
+                raise e2 from e
+            raise
 
     return await retry_async(
         _call,

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/_llm_util/providers/openai.py

@@ -9,6 +9,7 @@ from backoff.types import Details
 # all errors: https://platform.openai.com/docs/guides/error-codes/api-errors#python-library-error-types
 from openai import (
     APIConnectionError,
+    APITimeoutError,
     AsyncAzureOpenAI,
     AsyncOpenAI,
     AuthenticationError,
@@ -48,8 +49,11 @@ from openai.types.shared_params.response_format_json_schema import (
 from docent._llm_util.data_models.exceptions import (
     CompletionTooLongException,
     ContextWindowException,
+    InvalidPromptException,
     NoResponseException,
+    ProviderAuthenticationException,
     RateLimitException,
+    TimeoutException,
 )
 from docent._llm_util.data_models.llm_output import (
     AsyncEmbeddingStreamingCallback,
@@ -83,7 +87,9 @@ MAX_EMBEDDING_TOKENS = 8000
 
 def _print_backoff_message(e: Details):
     logger.warning(
-        f"OpenAI backing off for {e['wait']:.2f}s due to {e['exception'].__class__.__name__}"  # type: ignore
+        "OpenAI backing off for %.2fs due to %s",
+        e["wait"],  # type: ignore
+        e["exception"].__class__.__name__,  # type: ignore
     )
 
 
@@ -91,6 +97,8 @@ def _is_retryable_error(e: BaseException) -> bool:
     if (
         isinstance(e, BadRequestError)
         or isinstance(e, ContextWindowException)
+        or isinstance(e, InvalidPromptException)
+        or isinstance(e, ProviderAuthenticationException)
         or isinstance(e, AuthenticationError)
         or isinstance(e, PermissionDeniedError)
         or isinstance(e, NotFoundError)
@@ -281,7 +289,13 @@ async def get_openai_chat_completion_streaming_async(
                 if llm_output_partial:
                     return finalize_llm_output_partial(llm_output_partial)
                 return LLMOutput(model=model_name, completions=[], errors=[NoResponseException()])
-        except (RateLimitError, BadRequestError) as e:
+        except (
+            APITimeoutError,
+            RateLimitError,
+            BadRequestError,
+            AuthenticationError,
+            PermissionDeniedError,
+        ) as e:
             if e2 := _convert_openai_error(e):
                 raise e2 from e
             raise
@@ -296,10 +310,19 @@ async def get_openai_chat_completion_streaming_async(
 
 
 def _convert_openai_error(e: Exception):
-    if isinstance(e, RateLimitError):
+    if isinstance(e, (AuthenticationError, PermissionDeniedError)):
+        return ProviderAuthenticationException(e.message)
+    elif isinstance(e, RateLimitError):
         return RateLimitException(e)
-    elif isinstance(e, BadRequestError) and e.code == "context_length_exceeded":
+    elif isinstance(e, APITimeoutError):
+        return TimeoutException(str(e) or "Request timed out")
+    elif isinstance(e, BadRequestError) and e.code in (
+        "context_length_exceeded",
+        "string_above_max_length",
+    ):
         return ContextWindowException()
+    elif isinstance(e, BadRequestError) and e.code == "invalid_prompt":
+        return InvalidPromptException()
     return None
 
 
@@ -473,7 +496,13 @@ async def get_openai_chat_completion_async(
                         )
 
                 return output
-        except (RateLimitError, BadRequestError) as e:
+        except (
+            APITimeoutError,
+            RateLimitError,
+            BadRequestError,
+            AuthenticationError,
+            PermissionDeniedError,
+        ) as e:
             if e2 := _convert_openai_error(e):
                 raise e2 from e
             raise
@@ -549,8 +578,10 @@ async def _get_openai_embeddings_async_one_batch(
             dimensions=dimensions if dimensions is not None else omit,
         )
         return [data.embedding for data in response.data]
-    except RateLimitError as e:
-        raise RateLimitException(e) from e
+    except (RateLimitError, AuthenticationError, PermissionDeniedError) as e:
+        if e2 := _convert_openai_error(e):
+            raise e2 from e
+        raise
 
 
 async def get_chunked_openai_embeddings_async(

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/_llm_util/providers/openrouter.py

@@ -6,7 +6,9 @@ from typing import Literal, cast
 
 from openai import AsyncOpenAI, AuthenticationError, BadRequestError
 
-from docent._llm_util.data_models.exceptions import ContextWindowException
+from docent._llm_util.data_models.exceptions import (
+    ContextWindowException,
+)
 from docent._llm_util.data_models.llm_output import (
     AsyncSingleLLMOutputStreamingCallback,
     LLMOutput,

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/data_models/agent_run.py

@@ -252,7 +252,9 @@ class AgentRunTree(BaseModel):
             # This should never happen, but check anyways for safety; fallback to global root
             if par_id not in nodes:
                 logger.error(
-                    f"Parent {par_id} not found for transcript {t_id}. Assigning to global root as a fallback"
+                    "Parent %s not found for transcript %s. Assigning to global root as a fallback",
+                    par_id,
+                    t_id,
                 )
                 par_id = GLOBAL_ROOT_ID
             nodes[par_id].children_ids.append(t_id)
@@ -264,13 +266,13 @@ class AgentRunTree(BaseModel):
             if obj_type == NodeType.TRANSCRIPT_GROUP:
                 # This should never happen, but check anyways for safety
                 if obj_id not in tg_dict:
-                    logger.error(f"Transcript group {obj_id} not found")
+                    logger.error("Transcript group %s not found", obj_id)
                     return datetime.max
                 return tg_dict[obj_id].created_at or datetime.max
             elif obj_type == NodeType.TRANSCRIPT:
                 # This should never happen, but check anyways for safety
                 if obj_id not in t_dict:
-                    logger.error(f"Transcript {obj_id} not found")
+                    logger.error("Transcript %s not found", obj_id)
                     return datetime.max
                 return t_dict[obj_id].created_at or datetime.max
             else:

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/data_models/citation.py

@@ -1,3 +1,4 @@
+import re
 from datetime import datetime
 from typing import Annotated, Literal, Union
 from uuid import uuid4
@@ -22,6 +23,8 @@ class CitationTarget(BaseModel):
 
 
 class ParsedCitation(BaseModel):
+    """Citation parsed from text. start_idx and end_idx are UTF-16 code unit offsets for browser string slicing."""
+
     start_idx: int
     end_idx: int
     item_alias: str
@@ -107,6 +110,34 @@ RANGE_BEGIN = "<RANGE>"
 RANGE_END = "</RANGE>"
 
 
+# Citation alias grammar (single source of truth).
+# Each regex is anchored so it can be used independently of evaluation order.
+CITATION_BLOCK_RE = re.compile(r"^T(\d+)B(\d+)$")  # [T0B1]
+CITATION_AGENT_RUN_METADATA_RE = re.compile(r"^R(\d+)M\.([^:]+)$")  # [R0M.key]
+CITATION_TRANSCRIPT_METADATA_RE = re.compile(r"^T(\d+)M\.([^:]+)$")  # [T0M.key]
+CITATION_MESSAGE_METADATA_RE = re.compile(r"^T(\d+)B(\d+)M\.([^:]+)$")  # [T0B1M.key]
+CITATION_ANALYSIS_RESULT_RE = re.compile(r"^A(\d+)$")  # [A0]
+
+_CITATION_ALIAS_RES = (
+    CITATION_MESSAGE_METADATA_RE,
+    CITATION_TRANSCRIPT_METADATA_RE,
+    CITATION_AGENT_RUN_METADATA_RE,
+    CITATION_BLOCK_RE,
+    CITATION_ANALYSIS_RESULT_RE,
+)
+
+
+def is_valid_citation_alias(item_alias: str) -> bool:
+    """Whether `item_alias` matches one of the supported citation alias shapes."""
+    return any(rx.match(item_alias) for rx in _CITATION_ALIAS_RES)
+
+
+def _utf16_code_unit_len(text: str) -> int:
+    """Return the number of UTF-16 code units in text. Used to ensure indices match browser string
+    slicing with non-BMP characters"""
+    return len(text.encode("utf-16-le")) // 2
+
+
 def scan_brackets(text: str) -> list[tuple[int, int, str]]:
     """Scan text for bracketed segments, respecting RANGE markers and nested brackets.
 
@@ -160,15 +191,14 @@ def parse_single_citation(part: str) -> tuple[str, CitationTargetTextRange | Non
     """
     Parse a single citation token inside a bracket and return its components.
 
-    Returns ParsedCitation or None if invalid.
-    For metadata citations, transcript_idx may be None (for agent run metadata).
+    Returns (item_alias, text_range) or None if the token is not a syntactically
+    valid citation alias (see `is_valid_citation_alias`).
     Supports optional text range for all valid citation kinds.
     """
     token = part.strip()
     if not token:
         return None
 
-    # Extract optional range part
     item_alias = token
     text_range: CitationTargetTextRange | None = None
     if ":" in token:
@@ -176,6 +206,9 @@ def parse_single_citation(part: str) -> tuple[str, CitationTargetTextRange | Non
         item_alias = left.strip()
         text_range = _extract_range_pattern(right)
 
+    if not is_valid_citation_alias(item_alias):
+        return None
+
     return item_alias, text_range
 
 
@@ -196,9 +229,8 @@ def parse_citations(text: str) -> tuple[str, list[ParsedCitation]]:
         text: The text to parse citations from
 
     Returns:
-        A tuple of (cleaned_text, citations) where cleaned_text has brackets and range markers removed
-        and citations have start_idx and end_idx representing character positions
-        in the cleaned text
+        A tuple of (cleaned_text, citations) where cleaned_text has brackets and range markers removed.
+        Citation start_idx and end_idx are UTF-16 code unit offsets for browser string slicing.
     """
     citations: list[ParsedCitation] = []
 
@@ -212,7 +244,12 @@ def parse_citations(text: str) -> tuple[str, list[ParsedCitation]]:
         label, text_range = parsed
 
         citations.append(
-            ParsedCitation(start_idx=start, end_idx=end, item_alias=label, text_range=text_range)
+            ParsedCitation(
+                start_idx=_utf16_code_unit_len(text[:start]),
+                end_idx=_utf16_code_unit_len(text[:end]),
+                item_alias=label,
+                text_range=text_range,
+            )
         )
 
     # We're not cleaning the text right now but may do that later

{docent_python-0.1.62a0 → docent_python-0.1.63a0}/docent/data_models/reading.py

@@ -323,24 +323,46 @@ class ReadingStepSubmission(BaseModel):
         return _with_legacy_max_new_tokens_default(value)
 
     @model_validator(mode="after")
-    def _validate_dql_source(self) -> "ReadingStepSubmission":
-        if self.source_reading_preset_version is not None and self.source_reading_preset_id is None:
+    def _validate(self) -> "ReadingStepSubmission":
+        # Scripted and template are mutually exclusive
+        if (self.requests is None) == (self.prompt_template_segments is None):
             raise ValueError(
-                "ReadingStepSubmission: source_reading_preset_version cannot be set "
-                "without source_reading_preset_id"
+                "ReadingStepSubmission: must set one of requests / prompt_template_segments"
             )
+
+        # Validate scripted reading
         if self.requests is not None:
-            if self.dql_query is not None or self.dql_step_alias is not None:
+            if (
+                self.dql_query is not None
+                or self.dql_step_alias is not None
+                or self.context_configs is not None
+            ):
                 raise ValueError(
-                    "Scripted reading submissions must not set dql_query or dql_step_alias"
+                    "ReadingStepSubmission: scripted readings must not set dql_query, dql_step_alias, or context_configs"
                 )
-            return self
-        if self.dql_query is not None and self.dql_step_alias is not None:
-            raise ValueError("ReadingStepSubmission: set exactly one of dql_query / dql_step_alias")
-        if self.dql_query is None and self.dql_step_alias is None:
-            raise ValueError(
-                "ReadingStepSubmission: template entries must set one of dql_query / dql_step_alias"
-            )
+            if (
+                self.source_reading_preset_version is not None
+                or self.source_reading_preset_id is not None
+            ):
+                raise ValueError(
+                    "ReadingStepSubmission: scripted readings cannot be associated with a reading preset"
+                )
+
+        # Validate template reading
+        else:
+            if (
+                self.source_reading_preset_version is not None
+                and self.source_reading_preset_id is None
+            ):
+                raise ValueError(
+                    "ReadingStepSubmission: source_reading_preset_version cannot be set "
+                    "without source_reading_preset_id"
+                )
+            if (self.dql_query is None) == (self.dql_step_alias is None):
+                raise ValueError(
+                    "ReadingStepSubmission: template readings must set exactly one of dql_query / dql_step_alias"
+                )
+
         return self
 
 
@@ -362,28 +384,16 @@ class PresetReadingStepSubmission(BaseModel):
     cache_mode: ReadingCacheMode = "reading"
 
     @model_validator(mode="after")
-    def _validate_dql_source(self) -> "PresetReadingStepSubmission":
-        if self.source_reading_preset_id is None and self.source_reading_preset_name is None:
-            raise ValueError(
-                "PresetReadingStepSubmission: set one of "
-                "source_reading_preset_id / source_reading_preset_name"
-            )
-        if (
-            self.source_reading_preset_id is not None
-            and self.source_reading_preset_name is not None
-        ):
+    def _validate(self) -> "PresetReadingStepSubmission":
+        if (self.source_reading_preset_id is None) == (self.source_reading_preset_name is None):
             raise ValueError(
-                "PresetReadingStepSubmission: set only one of "
+                "PresetReadingStepSubmission: set exactly one of "
                 "source_reading_preset_id / source_reading_preset_name"
             )
-        if self.dql_query is not None and self.dql_step_alias is not None:
+        if (self.dql_query is None) == (self.dql_step_alias is None):
             raise ValueError(
                 "PresetReadingStepSubmission: set exactly one of dql_query / dql_step_alias"
             )
-        if self.dql_query is None and self.dql_step_alias is None:
-            raise ValueError(
-                "PresetReadingStepSubmission: must set one of dql_query / dql_step_alias"
-            )
         return self