labqoat 0.2.76__tar.gz → 0.2.78__tar.gz

{labqoat-0.2.76 → labqoat-0.2.78}/.venv-harbor/lib/python3.13/site-packages/labqoat/compute/images/runtime_metadata/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "labqoat"
-version = "0.2.76"
+version = "0.2.78"
 description = "Typed Python SDK and lab command-line client for the Labqoat platform"
 readme = "README.md"
 requires-python = ">=3.11"

{labqoat-0.2.76 → labqoat-0.2.78}/.venv-harbor/lib/python3.13/site-packages/labqoat/compute/images/runtime_metadata/uv.lock

@@ -1605,7 +1605,7 @@ wheels = [
 
 [[package]]
 name = "labqoat"
-version = "0.2.76"
+version = "0.2.78"
 source = { editable = "." }
 dependencies = [
     { name = "certifi" },

{labqoat-0.2.76 → labqoat-0.2.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labqoat
-Version: 0.2.76
+Version: 0.2.78
 Summary: Typed Python SDK and lab command-line client for the Labqoat platform
 Author: Labqoat
 License: MIT

{labqoat-0.2.76 → labqoat-0.2.78}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "labqoat"
-version = "0.2.76"
+version = "0.2.78"
 description = "Typed Python SDK and lab command-line client for the Labqoat platform"
 readme = "README.md"
 requires-python = ">=3.11"

{labqoat-0.2.76 → labqoat-0.2.78}/src/labqoat/__init__.py

@@ -27,7 +27,7 @@ if TYPE_CHECKING:
     from labqoat.runs.run_handle import RunHandle
     from labqoat.sandbox.sandbox import Sandbox
 
-__version__ = "0.2.76"
+__version__ = "0.2.78"
 
 _EXPORTS = {
     "Client": ("labqoat.client", "Client"),

labqoat-0.2.78/src/labqoat/cli/analytics_failure.py

@@ -0,0 +1,28 @@
+"""Report a failed analytics query with the reason its receipt records."""
+
+import re
+from typing import ClassVar
+
+from labqoat.cli.output.cli_failure import CliFailure
+from labqoat.json_document import JsonDocument
+
+
+class AnalyticsFailure:
+    """Turn a terminal failed query into a failure that says why and what to try."""
+
+    HINTS: ClassVar[dict[str, str]] = {
+        "query_timeout": "it ran past the query time limit; filter it, select fewer fields, or read the rows in a run",
+        "overloaded": "the query service is busy; send it again shortly",
+    }
+
+    @staticmethod
+    def raise_for(final: JsonDocument) -> None:
+        """Raise when the query failed; a succeeded query passes."""
+        if final["status"] != "failed":
+            return
+        receipt = final.get("receipt")
+        error = str(receipt.get("error", "")) if isinstance(receipt, dict) else ""
+        reason = error.lstrip(":") if re.fullmatch(r":?[a-z][a-z0-9_]{0,63}", error) else ""
+        detail = AnalyticsFailure.HINTS.get(reason, reason)
+        message = f"analytics query {final['id']} failed" + (f": {detail}" if detail else "")
+        raise CliFailure(message, 1, resource_id=str(final["id"]))

{labqoat-0.2.76 → labqoat-0.2.78}/src/labqoat/cli/analytics_payload_command.py

@@ -7,8 +7,8 @@ from collections.abc import Sequence
 import click
 from labqoat.cli.mutation_spec import MutationSpec
 
+from labqoat.cli.analytics_failure import AnalyticsFailure
 from labqoat.cli.analytics_waiter import AnalyticsWaiter
-from labqoat.cli.output.cli_failure import CliFailure
 from labqoat.cli.output.result_writer import ResultWriter
 from labqoat.cli.payload_command import PayloadCommand
 from labqoat.cli.observation_deadline import ObservationDeadline
@@ -38,6 +38,5 @@ class AnalyticsPayloadCommand(PayloadCommand):
         """Wait independently of the submission response connection."""
         with ObservationDeadline.current(str(response["id"])).watching():
             final = AnalyticsWaiter.wait(client, response)
-        if final["status"] == "failed":
-            raise CliFailure(f"analytics query {final['id']} failed", 1, resource_id=str(final["id"]))
+        AnalyticsFailure.raise_for(final)
         ResultWriter().write_dict(final)

{labqoat-0.2.76 → labqoat-0.2.78}/src/labqoat/cli/commands/authored/parameter_type.py

@@ -7,6 +7,7 @@ import typing
 import click
 
 from labqoat.cli.commands.authored.reference_parameter import ReferenceParameter
+from labqoat.cli.commands.authored.structured_parameter import StructuredParameter
 
 
 class ParameterType:
@@ -23,7 +24,7 @@ class ParameterType:
 
     @staticmethod
     def resolve(annotation: object) -> click.ParamType[object]:
-        """Use ordinary shell scalars and annotation-owned literal choices."""
+        """Use shell scalars, literal choices and catalog references; anything else the SDK transports is JSON."""
         annotation = ParameterType.unwrap(annotation)
         scalars = {str: click.STRING, int: click.INT, float: click.FLOAT, bool: click.BOOL}
         if annotation in scalars:
@@ -34,7 +35,7 @@ class ParameterType:
             values = get_args(annotation)
             if values and (all(type(value) is str for value in values) or all(type(value) is int for value in values)):
                 return click.Choice(values)
-        raise click.UsageError(
-            f"Unsupported CLI parameter type {annotation!r}. "
-            "Use scalars, Dataset[T], Artifact, Checkpoint, or a local entrypoint to construct structured inputs."
-        )
+        try:
+            return StructuredParameter(annotation)
+        except TypeError as error:
+            raise click.UsageError(f"Unsupported CLI parameter type {annotation!r}: {error}") from error

labqoat-0.2.78/src/labqoat/cli/commands/authored/structured_parameter.py

@@ -0,0 +1,52 @@
+"""A dataclass, list or mapping parameter given on the command line as JSON."""
+
+import json
+from pathlib import Path
+from typing import cast
+
+import click
+
+from labqoat.compute.value_codec import ValueCodec
+from labqoat.json_document import JsonValue
+
+
+class StructuredParameter(click.ParamType[object]):
+    """Read JSON text, or ``@path`` to a JSON file, and rebuild the declared Python value from it.
+
+    The value is decoded exactly as a Python caller's argument would be, so dataclasses come back with their
+    nested artifacts, datasets and checkpoints as typed inputs the platform authorizes. A run's result printed
+    by ``lab --json run result`` can be passed on as it is.
+    """
+
+    name = "json"
+
+    def __init__(self, annotation: object) -> None:
+        """Bind the declared type; raises TypeError when the type has no transport."""
+        self.annotation = annotation
+        self.codec = ValueCodec(cast("type[object]", annotation))
+        self.codec.schema()
+
+    def convert(self, value: object, param: click.Parameter | None, ctx: click.Context | None) -> object:
+        """Parse and decode, naming what was wrong when the text does not fit the type."""
+        if not isinstance(value, str):
+            return value
+        document = self.parse(value, param, ctx)
+        try:
+            return self.codec.decode(document)
+        except (TypeError, ValueError) as error:
+            self.fail(f"does not match {self.describe()}: {error}", param, ctx)
+
+    def parse(self, value: str, param: click.Parameter | None, ctx: click.Context | None) -> JsonValue:
+        """The JSON document in the text, or in the file ``@path`` names."""
+        try:
+            text = Path(value[1:]).read_text(encoding="utf-8") if value.startswith("@") else value
+        except OSError as error:
+            self.fail(f"cannot read {value[1:]!r}: {error.strerror}", param, ctx)
+        try:
+            return cast("JsonValue", json.loads(text))
+        except ValueError as error:
+            self.fail(f"not JSON for {self.describe()}: {error}", param, ctx)
+
+    def describe(self) -> str:
+        """The declared type as a reader recognizes it."""
+        return getattr(self.annotation, "__name__", None) or str(self.annotation).replace("typing.", "")

{labqoat-0.2.76 → labqoat-0.2.78}/src/labqoat/cli/dataset_query_command.py

@@ -6,10 +6,10 @@ import json
 
 import click
 
+from labqoat.cli.analytics_failure import AnalyticsFailure
 from labqoat.cli.analytics_waiter import AnalyticsWaiter
 from labqoat.cli.context_accessor import ContextAccessor
 from labqoat.cli.output.error_reporter import ErrorReporter
-from labqoat.cli.output.cli_failure import CliFailure
 from labqoat.cli.output.result_writer import ResultWriter
 from labqoat.cli.strict_command import StrictCommand
 from labqoat.json_document import JsonDocument
@@ -37,8 +37,7 @@ class DatasetQueryCommand(StrictCommand):
             submitted = client.post("/api/v1/analytics-queries", query, payload)
             with ObservationDeadline.current(str(submitted["id"])).watching():
                 final = AnalyticsWaiter.wait(client, submitted)
-            if final["status"] == "failed":
-                raise CliFailure(f"analytics query {final['id']} failed", 1, resource_id=str(final["id"]))
+            AnalyticsFailure.raise_for(final)
             ResultWriter().write_dict(final)
         except Exception as error:
             ErrorReporter.report(error)

{labqoat-0.2.76 → labqoat-0.2.78}/src/labqoat/cli/init/project_scaffold.py

@@ -1,5 +1,6 @@
 """Local setup of one project directory through uv and git."""
 
+import re
 from collections.abc import Sequence
 from pathlib import Path
 from typing import ClassVar
@@ -13,7 +14,7 @@ from labqoat.json_document import JsonDocument
 class ProjectScaffold:
     """Create only what a directory is missing; never overwrite a file or touch a repository it did not create."""
 
-    tracked: ClassVar[tuple[str, ...]] = ("pyproject.toml", ".agents/skills", ".claude/skills")
+    tracked: ClassVar[tuple[str, ...]] = ("pyproject.toml", "uv.lock", ".agents/skills", ".claude/skills")
     baseline: ClassVar[str] = "baseline-1"
 
     def __init__(self, directory: Path, name: str, runner: ProcessRunner) -> None:
@@ -32,6 +33,19 @@ class ProjectScaffold:
             return self.step("pyproject", "failed", f"uv init: {result.diagnostic()}")
         return self.step("pyproject", "done", "created by uv init")
 
+    def sdk(self, version: str) -> JsonDocument:
+        """Make `import labqoat` work in the project's own environment, so local tests run without PYTHONPATH."""
+        pyproject = self.directory / "pyproject.toml"
+        text = pyproject.read_text(encoding="utf-8") if pyproject.exists() else ""
+        if re.search(r"""["']labqoat(?=[\s<>=!~\[;,"'])""", text):
+            return self.step("sdk", "kept", "pyproject.toml already depends on labqoat")
+        requirement = f"labqoat=={version}"
+        result = self.run(["uv", "add", "--dev", "--directory", str(self.directory), requirement])
+        if not result.ok:
+            detail = f"uv add: {result.diagnostic()}; run `uv add --dev {requirement}` when online"
+            return self.step("sdk", "skipped", detail)
+        return self.step("sdk", "done", f"{requirement} in the dev group: `uv run pytest` can import labqoat")
+
     def sources(self) -> JsonDocument:
         """Write each starter file that does not exist yet."""
         written = [path for path, content in ProjectTemplate.documents(self.name).items() if self.place(path, content)]

{labqoat-0.2.76 → labqoat-0.2.78}/src/labqoat/cli/init_command.py

@@ -13,6 +13,7 @@ from labqoat.cli.output.result_writer import ResultWriter
 from labqoat.cli.skills.skill_bundle import SkillBundle
 from labqoat.cli.skills.skill_installer import SkillInstaller
 from labqoat.cli.strict_command import StrictCommand
+from labqoat.cli.version_info import VersionInfo
 from labqoat.errors.api_error import ApiError
 from labqoat.json_document import JsonDocument, JsonValue
 from labqoat.projects.project_names import ProjectNames
@@ -27,7 +28,8 @@ class InitCommand(StrictCommand):
         super().__init__(
             "init",
             help=(
-                "Set up a project here, or in a new directory NAME: a uv project, typed starter files, git with "
+                "Set up a project here, or in a new directory NAME: a uv project depending on this SDK for local "
+                "tests, typed starter files, git with "
                 "pre-commit checks, agent skills, and the Labqoat project pinned for the directory. Existing files "
                 "are kept."
             ),
@@ -39,6 +41,7 @@ class InitCommand(StrictCommand):
         directory, name = InitCommand.target(ctx.params["name"])
         scaffold = ProjectScaffold(directory, name, ProcessRunner(timeout_seconds=120.0))
         steps = [scaffold.python_project(), scaffold.sources(), InitCommand.pin(directory, name)]
+        steps.append(scaffold.sdk(VersionInfo.installed_version()))
         steps += [InitCommand.skills(directory, agent) for agent in SkillInstaller.directories]
         steps += [scaffold.repository(), InitCommand.remote(name)]
         passed = all(step["status"] != "failed" for step in steps)

{labqoat-0.2.76 → labqoat-0.2.78}/src/labqoat/cli/memory_document_catalog.py

@@ -26,7 +26,14 @@ class MemoryDocumentCatalog:
             "Pass the same --agent you write with: it records what you read and reports what you missed.",
             params=[
                 click.Option(["--all", "include_all"], is_flag=True),
-                click.Option(["--max-bytes"], type=click.IntRange(16384, 262144), default=65536),
+                click.Option(
+                    ["--limit"], type=click.IntRange(1, 100), help="Rows per section; the server default is 8."
+                ),
+                click.Option(
+                    ["--max-bytes"],
+                    type=click.IntRange(8192, 262144),
+                    help="Byte ceiling; the server default is 24 KiB.",
+                ),
                 click.Option(["--agent"], envvar="LABQOAT_AGENT", help="Reader label, such as root or scout-2."),
             ],
         )
@@ -57,14 +64,18 @@ class MemoryDocumentCatalog:
         return group
 
     @staticmethod
-    def read(include_all: bool, max_bytes: int, agent: str | None) -> None:
+    def read(include_all: bool, limit: int | None, max_bytes: int | None, agent: str | None) -> None:
         """Render the default brief unless a subcommand was chosen, remembering the version read."""
         if click.get_current_context().invoked_subcommand is not None:
             return
         context = ContextAccessor.current()
         client = context.management(agent=agent)
         try:
-            query = {"all": str(include_all).lower(), "max_bytes": max_bytes}
+            chosen = {"limit": limit, "max_bytes": max_bytes}
+            query = {
+                "all": str(include_all).lower(),
+                **{key: value for key, value in chosen.items() if value is not None},
+            }
             document = client.get("/api/v1/memory/brief", query)
             project = context.selection().name
             key = MemoryBriefReads.key(context.profile.base_url, context.profile.environment, project, agent)

{labqoat-0.2.76 → labqoat-0.2.78}/src/labqoat/compute/child_admissions.py

@@ -6,19 +6,11 @@ from dataclasses import dataclass, field
 
 from labqoat.json_document import JsonDocument, JsonValue
 from labqoat.worker.worker_api import WorkerApi
+from labqoat.worker.rejection_advice import RejectionAdvice
 from labqoat.worker.worker_api_error import WorkerApiError
 from labqoat.worker.replay_request import ReplayRequest
 
 
-_ADVICE = {
-    "child_input_not_authorized": (
-        ". A child run may receive only the artifacts, datasets and checkpoints its parent received as arguments or "
-        "produced itself, and only functions published with the parent. To reuse an earlier run's output, pass it "
-        "to this run as an Artifact, Dataset or Checkpoint argument and hand it on."
-    ),
-}
-
-
 @dataclass
 class ChildAdmissions:
     """Own bounded request batches; cancelling one caller never cancels another child's acceptance."""
@@ -99,6 +91,8 @@ class ChildAdmissions:
             return
         if "error" in receipt:
             reason = str(receipt["error"])
-            future.set_exception(WorkerApiError(f"Child submission rejected: {reason}{_ADVICE.get(reason, '')}", 409))
+            future.set_exception(
+                WorkerApiError(f"Child submission rejected: {reason}{RejectionAdvice.explain(reason)}", 409)
+            )
         else:
             future.set_result(receipt)

{labqoat-0.2.76 → labqoat-0.2.78}/src/labqoat/memory_client.py

@@ -90,9 +90,16 @@ class MemoryClient(BaseClient):
         path = f"/api/v1/memory/changes?{urlencode({'after': after, 'limit': limit})}"
         return self.decode(self.send("GET", path), path, KnowledgeView.from_dict)
 
-    def brief(self, *, include_all: bool = False, max_bytes: int = 65_536) -> KnowledgeBrief:
-        """Read the shared brief, hypotheses by status, results, open work and disagreements."""
-        path = f"/api/v1/memory/brief?{urlencode({'all': str(include_all).lower(), 'max_bytes': max_bytes})}"
+    def brief(
+        self, *, include_all: bool = False, limit: int | None = None, max_bytes: int | None = None
+    ) -> KnowledgeBrief:
+        """Read the shared brief, hypotheses by status, results, open work and disagreements.
+
+        The server bounds it to 8 rows a section within 24 KiB unless ``limit`` or ``max_bytes`` asks for more.
+        """
+        chosen = {"limit": limit, "max_bytes": max_bytes}
+        query = {"all": str(include_all).lower(), **{key: value for key, value in chosen.items() if value is not None}}
+        path = f"/api/v1/memory/brief?{urlencode(query)}"
         return self.decode(self.send("GET", path), path, KnowledgeBrief.from_dict)
 
     def edit_brief(self, request: NewKnowledgeBrief) -> KnowledgeReceipt:

labqoat-0.2.78/src/labqoat/worker/rejection_advice.py

@@ -0,0 +1,20 @@
+"""What to do about a worker command the platform refused, by its reason code."""
+
+from typing import ClassVar
+
+
+class RejectionAdvice:
+    """One sentence per refusal whose fix is not obvious from its code."""
+
+    ADVICE: ClassVar[dict[str, str]] = {
+        "child_input_not_authorized": (
+            ". A child run may receive only the artifacts, datasets and checkpoints its parent received as arguments "
+            "or produced itself, and only functions published with the parent. To reuse an earlier run's output, "
+            "pass it to this run as an Artifact, Dataset or Checkpoint argument and hand it on."
+        ),
+    }
+
+    @staticmethod
+    def explain(reason: str | None) -> str:
+        """The advice to append to a refusal's message, or nothing for a self-explanatory code."""
+        return RejectionAdvice.ADVICE.get(reason or "", "")

{labqoat-0.2.76 → labqoat-0.2.78}/src/labqoat/worker/session/session_bridge.py

@@ -98,7 +98,9 @@ class SessionBridge:
             else:
                 await self._emit(target, await self._execute(request))
         except WorkerApiError as error:
-            await self._emit(target, JsonDocument(error="session_command_rejected", status=error.status or 503))
+            await self._emit(
+                target, JsonDocument(error=error.code or "session_command_rejected", status=error.status or 503)
+            )
         except (KeyError, TypeError, ValueError):
             await self._emit(target, JsonDocument(error="invalid_session_command", status=400))
 
@@ -127,6 +129,6 @@ class SessionBridge:
             data = JsonDocument.expect_dict(request["data"])
             return JsonDocument(data=await self.session.request(op, attempt, data))
         except WorkerApiError as error:
-            return JsonDocument(error="session_command_rejected", status=error.status or 503)
+            return JsonDocument(error=error.code or "session_command_rejected", status=error.status or 503)
         except (KeyError, ValueError, TypeError):
             return JsonDocument(error="invalid_session_command", status=400)

{labqoat-0.2.76 → labqoat-0.2.78}/src/labqoat/worker/session/session_frames.py

@@ -5,6 +5,7 @@ from collections.abc import Mapping
 from typing import ClassVar
 
 from labqoat.json_document import JsonDocument, JsonValue
+from labqoat.worker.rejection_advice import RejectionAdvice
 from labqoat.worker.worker_api_error import WorkerApiError
 
 
@@ -36,5 +37,6 @@ class SessionFrames:
         """Interpret a durable receipt without exposing server exception details."""
         if "error" in frame:
             status = JsonDocument.expect_scalar(frame.get("status", 409), int)
-            raise WorkerApiError.coded("Worker session command was rejected", status, frame["error"])
+            error = WorkerApiError.coded("Worker session command was rejected", status, frame["error"])
+            raise WorkerApiError(f"{error}{RejectionAdvice.explain(error.code)}", status, error.code)
         return JsonDocument.expect_dict(frame["data"])

{labqoat-0.2.76 → labqoat-0.2.78}/uv.lock

@@ -1605,7 +1605,7 @@ wheels = [
 
 [[package]]
 name = "labqoat"
-version = "0.2.76"
+version = "0.2.78"
 source = { editable = "." }
 dependencies = [
     { name = "certifi" },