docent-python 0.1.60a0__tar.gz → 0.1.61a0__tar.gz

{docent_python-0.1.60a0 → docent_python-0.1.61a0}/PKG-INFO

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

{docent_python-0.1.60a0 → docent_python-0.1.61a0}/docent/data_models/reading.py

@@ -2,7 +2,7 @@ from datetime import datetime
 from typing import Annotated, Any, Literal, TypeAlias
 from uuid import uuid4
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 
 from docent._llm_util.providers.preference_types import ModelOption
 
@@ -177,6 +177,7 @@ class ReadingStep(BaseModel):
     name: str | None = None
     reading_id: str | None = None
     dql_query: str | None = None
+    dql_step_alias: str | None = None
     prompt_template_segments: list[Any] | None = None
     context_config: dict[str, Any] | None = None
     model: ModelOption
@@ -191,7 +192,11 @@ class ReadingStep(BaseModel):
     def to_submission(self, *, dql_query: str | None = None) -> "ReadingStepSubmission":
         """Convert to a ReadingStepSubmission for resolve_reading_entry.
 
-        Optionally overrides dql_query (e.g. after alias substitution).
+        Optionally overrides dql_query (e.g. after alias substitution). The
+        stored step's own dql_query may be None when dql_step_alias is set;
+        callers are expected to pass the resolved DQL explicitly in that case.
+        When a concrete DQL is supplied, clear dql_step_alias so the
+        submission continues to satisfy the "exactly one DQL source" contract.
         """
         return ReadingStepSubmission(
             alias=self.alias,
@@ -203,6 +208,7 @@ class ReadingStep(BaseModel):
             prompt_template_segments=self.prompt_template_segments,
             context_config=self.context_config,
             dql_query=dql_query if dql_query is not None else self.dql_query,
+            dql_step_alias=None if dql_query is not None else self.dql_step_alias,
             source_reading_preset_id=self.source_reading_preset_id,
             cache_mode=self.cache_mode,
         )
@@ -272,10 +278,29 @@ class ReadingStepSubmission(BaseModel):
     prompt_template_segments: list[Any] | None = None
     context_config: dict[str, ParameterContextConfig] | None = None
     dql_query: str | None = None
+    # References a DqlOnlyStep in the same plan whose rows feed this reading.
+    # Mutually exclusive with dql_query for template entries.
+    dql_step_alias: str | None = None
 
     # Scripted reading fields (mutually exclusive with template fields)
     requests: list[ScriptedRequest] | None = None
 
+    @model_validator(mode="after")
+    def _validate_dql_source(self) -> "ReadingStepSubmission":
+        if self.requests is not None:
+            if self.dql_query is not None or self.dql_step_alias is not None:
+                raise ValueError(
+                    "Scripted reading submissions must not set dql_query or dql_step_alias"
+                )
+            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"
+            )
+        return self
+
 
 class PresetReadingStepSubmission(BaseModel):
     entry_type: Literal["preset_reading"] = "preset_reading"
@@ -284,8 +309,21 @@ class PresetReadingStepSubmission(BaseModel):
     source_reading_preset_id: str
     user_metadata: dict[str, Any] | None = None
     dql_query: str | None = None
+    dql_step_alias: str | None = None
     cache_mode: ReadingCacheMode = "reading"
 
+    @model_validator(mode="after")
+    def _validate_dql_source(self) -> "PresetReadingStepSubmission":
+        if self.dql_query is not None and self.dql_step_alias is not 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
+
 
 class DqlOnlyStepSubmission(BaseModel):
     entry_type: Literal["dql_only"] = "dql_only"

{docent_python-0.1.60a0 → docent_python-0.1.61a0}/docent/sdk/_base.py

@@ -174,7 +174,7 @@ class DocentBase:
         self._plan_id: str | None = None
         self._flushed_collection_id: str | None = None
         self._pending: list[PendingEntry] = []
-        self._alias_counter: int = 0
+        self._alias_counter: int = 1
         self._auto_flush: bool = True
         self._atexit_registered: bool = False
         self._crash_detected: bool = False

{docent_python-0.1.60a0 → docent_python-0.1.61a0}/docent/sdk/_dql.py

@@ -156,20 +156,27 @@ class DocentDqlMixin(DocentBase):
 
         return agent_run_ids
 
-    def list_agent_run_ids(self, collection_id: str) -> list[str]:
+    def list_agent_run_ids(
+        self,
+        collection_id: str,
+        *,
+        apply_base_filter: bool = False,
+    ) -> list[str]:
         """Get all agent run IDs for a collection.
 
         Args:
             collection_id: ID of the Collection.
+            apply_base_filter: Whether to apply the collection view's base filter.
 
         Returns:
-            str: JSON string containing the list of agent run IDs.
+            list[str]: Agent run IDs for the collection.
 
         Raises:
             requests.exceptions.HTTPError: If the API request fails.
         """
         url = f"{self._api_url}/{collection_id}/agent_run_ids"
-        response = self._session.get(url)
+        params = {"apply_base_filter": "true"} if apply_base_filter else None
+        response = self._session.get(url, params=params)
         self._handle_response_errors(response)
         return response.json()
 

{docent_python-0.1.60a0 → docent_python-0.1.61a0}/docent/sdk/_readings.py

@@ -158,8 +158,8 @@ class DocentReadingsMixin(DocentBase):
 
     # ────────────────────────── Reading Plans ──────────────────────────
 
-    def _next_alias(self, prefix: str = "r") -> str:
-        alias = f"{prefix}{self._alias_counter}"
+    def _next_alias(self) -> str:
+        alias = str(self._alias_counter)
         self._alias_counter += 1
         return alias
 
@@ -222,17 +222,39 @@ class DocentReadingsMixin(DocentBase):
             return Path(main_file).name
         return None
 
-    def query(self, collection_id: str, dql: str) -> QueryResult:
-        """Create a lazy DQL query handle.
+    def query(
+        self,
+        collection_id: str,
+        dql: str,
+        *,
+        name: str | None = None,
+    ) -> QueryResult:
+        """Create a lazy DQL query handle backed by a plan step.
+
+        A corresponding ``dql_only`` step is appended to the pending plan
+        immediately so the query is visible in the plan UI, even if the
+        QueryResult is never consumed by a reading.
 
         Args:
             collection_id: Collection ID.
             dql: DQL query string.
+            name: Optional display name for the dql-only step.
 
         Returns:
             QueryResult handle. Access attributes to get ColumnRef objects.
         """
-        return QueryResult(collection_id, dedent(dql).strip())
+        alias = self._next_alias()
+        resolved_dql = dedent(dql).strip()
+        self._enqueue_pending(
+            _PendingDqlOnlyStep(
+                alias=alias,
+                collection_id=collection_id,
+                dql_query=resolved_dql,
+                name=name,
+            )
+        )
+        self._register_atexit()
+        return QueryResult(collection_id, resolved_dql, plan_alias=alias)
 
     def read(
         self,
@@ -289,11 +311,11 @@ class DocentReadingsMixin(DocentBase):
             provider=provider, model_name=model_name, reasoning_effort=reasoning_effort
         )
 
-        alias = self._next_alias("r")
+        alias = self._next_alias()
         handle = Reading(client=self, alias=alias)
 
         if prompt_template is not None:
-            template_segments, dql_query, ctx_config, inferred_cid = (
+            template_segments, dql_step_alias, ctx_config, inferred_cid = (
                 self._serialize_template_prompt(prompt_template, context_config)
             )
             resolved_cid = collection_id or inferred_cid
@@ -310,7 +332,8 @@ class DocentReadingsMixin(DocentBase):
                 cache_mode=cache_mode,
                 prompt_template_segments=template_segments,
                 context_config=ctx_config,
-                dql_query=dql_query,
+                dql_query=None,
+                dql_step_alias=dql_step_alias,
                 requests=None,
             )
         else:
@@ -330,6 +353,7 @@ class DocentReadingsMixin(DocentBase):
                 prompt_template_segments=None,
                 context_config=None,
                 dql_query=None,
+                dql_step_alias=None,
                 requests=scripted_reqs,
             )
 
@@ -344,28 +368,27 @@ class DocentReadingsMixin(DocentBase):
     ) -> tuple[list[Any], str | None, dict[str, ParameterContextConfig] | None, str | None]:
         """Convert prompt segments into template format.
 
-        Returns (segments_json, dql_query, context_config_dict, collection_id).
+        Returns (segments_json, dql_step_alias, context_config_dict, collection_id).
+        The reading is bound to the single QueryResult used in the prompt via
+        its plan alias; if none is present the returned alias is ``None``.
         """
         segments: list[Any] = []
-        dql_query: str | None = None
+        seen_qr: QueryResult | None = None
         inferred_collection_id: str | None = None
         param_configs: dict[str, ParameterContextConfig] = {}
-        seen_query_results: dict[int, QueryResult] = {}
 
         for seg in prompt:
             if isinstance(seg, str):
                 segments.append(dedent(seg))
             elif isinstance(seg, ColumnRef):
                 qr = seg.query_result
-                qr_id = id(qr)
-                if qr_id not in seen_query_results:
-                    seen_query_results[qr_id] = qr
-                    if dql_query is not None and dql_query != qr.dql:
-                        raise ValueError(
-                            "All ColumnRefs in a prompt must reference the same QueryResult"
-                        )
-                    dql_query = qr.dql
+                if seen_qr is None:
+                    seen_qr = qr
                     inferred_collection_id = qr.collection_id
+                elif qr is not seen_qr:
+                    raise ValueError(
+                        "All ColumnRefs in a prompt must reference the same QueryResult"
+                    )
 
                 param_name = seg.column_name
                 param_type = seg.type_annotation or "unknown"
@@ -392,7 +415,13 @@ class DocentReadingsMixin(DocentBase):
                 segments[i] = segments[i].rstrip()
                 break
 
-        return segments, dql_query, param_configs if param_configs else None, inferred_collection_id
+        dql_step_alias = seen_qr.plan_alias if seen_qr is not None else None
+        return (
+            segments,
+            dql_step_alias,
+            param_configs if param_configs else None,
+            inferred_collection_id,
+        )
 
     def _serialize_scripted_requests(
         self,
@@ -434,29 +463,32 @@ class DocentReadingsMixin(DocentBase):
         return result
 
     def show_query_result(self, query_result: QueryResult, *, name: str | None = None) -> None:
-        """Register a DQL-only preview step.
-
-        The DQL results will be shown in the UI but not persisted.
+        """Deprecated: `client.query(...)` now auto-registers a dql-only step.
 
-        Args:
-            query_result: A QueryResult handle from client.query().
-            name: Optional display name.
+        Retained as a no-op for backwards compatibility. If ``name`` is
+        provided and the query's dql-only step has no name yet, we update
+        it so the preview still gets a human-readable label.
         """
-        alias = self._next_alias("d")
-        self._enqueue_pending(
-            _PendingDqlOnlyStep(
-                alias=alias,
-                collection_id=query_result.collection_id,
-                dql_query=query_result.dql,
-                name=name,
-            )
+        import warnings
+
+        warnings.warn(
+            "show_query_result() is deprecated; client.query() already registers a "
+            "dql-only plan step. Pass name= to client.query() to label it.",
+            DeprecationWarning,
+            stacklevel=2,
         )
-        self._register_atexit()
+        if name is None or query_result.plan_alias is None:
+            return
+        for p in self._pending:
+            if isinstance(p, _PendingDqlOnlyStep) and p.alias == query_result.plan_alias:
+                if p.name is None:
+                    p.name = name
+                break
 
     def preset_reading(
         self,
         preset_id: str,
-        query_result: QueryResult | None = None,
+        query_result: QueryResult | None,
         *,
         name: str | None = None,
         user_metadata: dict[str, Any] | None = None,
@@ -468,16 +500,19 @@ class DocentReadingsMixin(DocentBase):
 
         Args:
             preset_id: The reading preset ID to use.
-            query_result: Optional QueryResult for the DQL query.
+            query_result: QueryResult supplying the preset's input rows.
             name: Optional display name for the step.
             user_metadata: Optional metadata stored on the reading row and used in reading deduplication.
 
         Returns:
             A Reading handle that will be populated with results after flush().
         """
-        alias = self._next_alias("r")
-        collection_id = query_result.collection_id if query_result else None
-        dql_query = query_result.dql if query_result else None
+        if query_result is None:
+            raise ValueError("preset_reading requires a QueryResult")
+
+        alias = self._next_alias()
+        collection_id = query_result.collection_id
+        dql_step_alias = query_result.plan_alias
         handle = Reading(client=self, alias=alias)
         self._enqueue_pending(
             _PendingPresetReading(
@@ -487,7 +522,8 @@ class DocentReadingsMixin(DocentBase):
                 name=name,
                 source_reading_preset_id=preset_id,
                 user_metadata=user_metadata,
-                dql_query=dql_query,
+                dql_query=None,
+                dql_step_alias=dql_step_alias,
                 cache_mode=cache_mode,
             )
         )
@@ -507,7 +543,7 @@ class DocentReadingsMixin(DocentBase):
         Args:
             label: The group label.
         """
-        alias = self._next_alias("g")
+        alias = self._next_alias()
         self._pending.append(_PendingStepGroup(alias=alias, label=label))
         return StepGroupContext(self._pending, alias)
 
@@ -552,6 +588,7 @@ class DocentReadingsMixin(DocentBase):
                     prompt_template_segments=p.prompt_template_segments,
                     context_config=p.context_config,
                     dql_query=p.dql_query,
+                    dql_step_alias=p.dql_step_alias,
                     requests=[ScriptedRequest(**r) for r in p.requests] if p.requests else None,
                 )
                 entries.append(entry)
@@ -565,6 +602,7 @@ class DocentReadingsMixin(DocentBase):
                         source_reading_preset_id=p.source_reading_preset_id,
                         user_metadata=p.user_metadata,
                         dql_query=p.dql_query,
+                        dql_step_alias=p.dql_step_alias,
                         cache_mode=p.cache_mode,
                     )
                 )
@@ -675,6 +713,13 @@ class DocentReadingsMixin(DocentBase):
 
     _FLUSH_TIMEOUT_SECONDS = 600
 
+    @staticmethod
+    def _format_step_label(name: str | None, alias: str, default: str) -> str:
+        """Format a step label that always includes the alias."""
+        if name:
+            return f"{name} [${alias}]"
+        return f"{default} [${alias}]"
+
     def _preview_and_wait(
         self,
         *,
@@ -690,14 +735,17 @@ class DocentReadingsMixin(DocentBase):
         for es in submit_response.entry_statuses:
             if es.entry_type == "dql_only":
                 if es.status == "cached" and es.dql_preview is not None:
-                    self._log_dql_preview(pending_names.get(es.alias), es.dql_preview)
+                    self._log_dql_preview(pending_names.get(es.alias), es.alias, es.dql_preview)
                 elif es.status != "cached":
                     unsettled_dql_aliases[es.alias] = es
 
             elif es.entry_type == "reading":
                 if es.status == "cached":
                     self._log_reading_preview(
-                        pending_names.get(es.alias), es.result_count, es.result_preview
+                        pending_names.get(es.alias),
+                        es.alias,
+                        es.result_count,
+                        es.result_preview,
                     )
                 else:
                     unsettled_reading_aliases.add(es.alias)
@@ -776,11 +824,15 @@ class DocentReadingsMixin(DocentBase):
                                 collection_id,
                                 step.reading_id,
                                 pending_names.get(step.alias),
+                                step.alias,
                                 reading_handles.get(step.alias),
                             )
                     elif step.alias in pending and step.derived_status == "failed":
                         self._logger.warning(
-                            "Step %s failed", pending_names.get(step.alias) or step.alias
+                            "Step %s failed",
+                            self._format_step_label(
+                                pending_names.get(step.alias), step.alias, "Reading"
+                            ),
                         )
                         pending.discard(step.alias)
                 if not pending:
@@ -796,6 +848,7 @@ class DocentReadingsMixin(DocentBase):
                         collection_id,
                         event.reading_id,
                         pending_names.get(event.step_alias),
+                        event.step_alias,
                         reading_handles.get(event.step_alias),
                         result_count=event.result_count,
                     )
@@ -809,9 +862,11 @@ class DocentReadingsMixin(DocentBase):
                 )
 
             elif isinstance(event, PlanStepFailedEvent) and event.step_alias in pending:
-                name = pending_names.get(event.step_alias, event.step_alias)
+                label = self._format_step_label(
+                    pending_names.get(event.step_alias), event.step_alias, "Reading"
+                )
                 msg = event.error.message if event.error else "unknown error"
-                self._logger.warning("Step %s failed: %s", name or event.step_alias, msg)
+                self._logger.warning("Step %s failed: %s", label, msg)
                 pending.discard(event.step_alias)
 
             elif isinstance(event, PlanJobCancelledEvent):
@@ -873,7 +928,7 @@ class DocentReadingsMixin(DocentBase):
                                 truncated=result.get("truncated", False),
                                 row_count=result.get("row_count", 0),
                             )
-                            self._log_dql_preview(name, preview)
+                            self._log_dql_preview(name, alias, preview)
                             return result
                     break
         except Exception:
@@ -885,11 +940,12 @@ class DocentReadingsMixin(DocentBase):
         collection_id: str,
         reading_id: str | None,
         name: str | None,
+        alias: str,
         handle: Reading | None,
         result_count: int | None = None,
     ) -> None:
         """Fetch results for a just-completed step, log preview, populate handle."""
-        label = name or "Reading"
+        label = self._format_step_label(name, alias, "Reading")
         if reading_id is None:
             self._logger.info("%s: completed", label)
             return
@@ -913,14 +969,14 @@ class DocentReadingsMixin(DocentBase):
         else:
             self._logger.info("%s: completed%s", label, count_str)
 
-    def _log_dql_preview(self, name: str | None, dql_preview: Any) -> None:
+    def _log_dql_preview(self, name: str | None, alias: str, dql_preview: Any) -> None:
         """Log a DQL result preview to stdout."""
         from docent.data_models.reading import DqlPreview
 
         if isinstance(dql_preview, dict):
             dql_preview = DqlPreview.model_validate(dql_preview)
 
-        label = name or "DQL"
+        label = self._format_step_label(name, alias, "DQL")
         cols = dql_preview.columns
         rows = dql_preview.rows
         truncated = dql_preview.truncated
@@ -963,11 +1019,12 @@ class DocentReadingsMixin(DocentBase):
     def _log_reading_preview(
         self,
         name: str | None,
+        alias: str,
         result_count: int | None,
         result_preview: list[Any] | None,
     ) -> None:
         """Log a reading result preview to stdout."""
-        label = name or "Reading"
+        label = self._format_step_label(name, alias, "Reading")
         count_str = f" ({result_count} results)" if result_count is not None else ""
         self._logger.info("%s: cached%s", label, count_str)
         if result_preview:

{docent_python-0.1.60a0 → docent_python-0.1.61a0}/docent/sdk/reading.py

@@ -76,11 +76,16 @@ class QueryResult:
     """Lazy handle for a DQL query, returned by client.query().
 
     Attribute access returns ColumnRef objects for use in prompt templates.
+    Each QueryResult is bound to a dql-only step in the plan (identified by
+    `_plan_alias`); when a ColumnRef backed by this result is used in a
+    reading's prompt_template, that reading's submission references the
+    dql-only step via `dql_step_alias` rather than embedding the DQL directly.
     """
 
-    def __init__(self, collection_id: str, dql: str) -> None:
+    def __init__(self, collection_id: str, dql: str, *, plan_alias: str | None = None) -> None:
         self._collection_id = collection_id
         self._dql = dql
+        self._plan_alias = plan_alias
 
     @property
     def collection_id(self) -> str:
@@ -90,6 +95,10 @@ class QueryResult:
     def dql(self) -> str:
         return self._dql
 
+    @property
+    def plan_alias(self) -> str | None:
+        return self._plan_alias
+
     def __getattr__(self, name: str) -> ColumnRef:
         if name.startswith("_"):
             raise AttributeError(name)
@@ -204,6 +213,7 @@ class _PendingReading:
         prompt_template_segments: list[Any] | None,
         context_config: dict[str, ParameterContextConfig] | None,
         dql_query: str | None,
+        dql_step_alias: str | None = None,
         # Scripted path
         requests: list[dict[str, Any]] | None,
     ) -> None:
@@ -220,6 +230,7 @@ class _PendingReading:
         self.prompt_template_segments = prompt_template_segments
         self.context_config = context_config
         self.dql_query = dql_query
+        self.dql_step_alias = dql_step_alias
         self.requests = requests
 
 
@@ -248,6 +259,7 @@ class _PendingPresetReading:
         source_reading_preset_id: str,
         user_metadata: dict[str, Any] | None,
         dql_query: str | None,
+        dql_step_alias: str | None = None,
         cache_mode: ReadingCacheMode = "reading",
     ) -> None:
         self.alias = alias
@@ -257,6 +269,7 @@ class _PendingPresetReading:
         self.source_reading_preset_id = source_reading_preset_id
         self.user_metadata = user_metadata
         self.dql_query = dql_query
+        self.dql_step_alias = dql_step_alias
         self.cache_mode: ReadingCacheMode = cache_mode
 
 

{docent_python-0.1.60a0 → docent_python-0.1.61a0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "docent-python"
 description = "Docent SDK"
-version = "0.1.60-alpha"
+version = "0.1.61-alpha"
 authors = [
   { name="Transluce", email="info@transluce.org" },
 ]

{docent_python-0.1.60a0 → docent_python-0.1.61a0}/uv.lock

@@ -553,7 +553,7 @@ wheels = [
 
 [[package]]
 name = "docent-python"
-version = "0.1.60a0"
+version = "0.1.61a0"
 source = { editable = "." }
 dependencies = [
     { name = "anthropic" },