squackit 0.8.4__tar.gz → 0.9.0__tar.gz

{squackit-0.8.4 → squackit-0.9.0}/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.9.0
+
+### Added — structured output for programmatic callers (#18)
+
+Every tool accepts `as_json=true` and returns one envelope:
+
+    {"rows": [...], "columns": [...], "omitted": <int>}
+
+squackit renders for a human reader — markdown tables and newline-joined text.
+That is right for an agent reading a briefing and close to useless to a program
+composing calls. Measured by a session driving four local models through
+lackpy: **0/24 correct while 17/24 called the correct tool**. `len()` on
+`find_names`' newline-joined string gives 67 (characters) where the answer is
+8; on `find`'s table it gives 2239.
+
+The structure was never lost, only discarded at the last step: the executors
+already return DuckDB relations and View objects, and the CLI already had
+`--json`. This exposes that over MCP, on both the macro and pluckit wrappers.
+
+Deliberate choices:
+
+- **One envelope for every tool**, so a caller learns the shape once.
+- **`omitted` rather than a bare array.** A truncated array is
+  indistinguishable from a complete one, and shipping silent truncation on the
+  programmatic path would reproduce the defect this mode exists to fix.
+- **The shape is stated in every tool's description.** The cost of the
+  envelope is that `len()` of it is 3, not the row count — the same misread
+  that produced the 0/24 — so it is named beside the signature rather than left
+  to be inferred.
+- **An empty result is `[]`**, not the prose `(no results)`.
+- **The default is unchanged.** Existing callers see exactly what they saw
+  before; `as_json` is opt-in, so this is additive rather than a migration.
+
+The `compact_columns` projection and `verbose` still apply, so a JSON caller
+sees the same columns a markdown caller would unless it asks for more.
+
+
 ## 0.8.4
 
 A review of 0.8.1–0.8.3 found both fixes had reached the macro-tool layer and

{squackit-0.8.4 → squackit-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: squackit
-Version: 0.8.4
+Version: 0.9.0
 Summary: Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents.
 Project-URL: Homepage, https://github.com/teaguesterling/squackit
 Project-URL: Documentation, https://squackit.readthedocs.io

{squackit-0.8.4 → squackit-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "squackit"
-version = "0.8.4"
+version = "0.9.0"
 description = "Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents."
 readme = "README.md"
 license = "Apache-2.0"

{squackit-0.8.4 → squackit-0.9.0}/squackit/server.py

@@ -21,6 +21,7 @@ Usage::
 from __future__ import annotations
 
 import inspect
+import json as _json
 import threading
 from collections import OrderedDict
 from pathlib import Path
@@ -246,6 +247,8 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
             elif v is not None:
                 verbose = bool(v)
 
+        as_json = _as_json_requested(kwargs)
+
         filtered = {k: v for k, v in kwargs.items() if v is not None}
 
         try:
@@ -259,6 +262,16 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
         # View -> markdown (truncate by blocks if too many)
         if hasattr(result, 'markdown') and hasattr(result, 'blocks'):
             blocks = result.blocks
+            if as_json:
+                tabular = getattr(result, "tabular", None)
+                if tabular is not None:
+                    vcols, vrows = tabular
+                    kept, omitted = _limit_rows(list(vrows), max_limit)
+                    return _json_envelope(
+                        [dict(zip(vcols, r)) for r in kept], vcols, omitted)
+                kept, omitted = _limit_rows(list(blocks), max_limit)
+                return _json_envelope(
+                    [b.markdown for b in kept if b.markdown], (), omitted)
             if max_limit > 0 and len(blocks) > max_limit:
                 kept = blocks[:max_limit]
                 omitted = len(blocks) - max_limit
@@ -269,6 +282,13 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
         if hasattr(result, 'columns') and hasattr(result, 'fetchall'):
             cols = result.columns
             rows = result.fetchall()
+            if as_json:
+                # Projection still applies, so a JSON caller gets the same
+                # columns a markdown caller would unless it asks for verbose.
+                jcols, jrows = _project(cols, rows, presentation, verbose)
+                kept, omitted = _limit_rows(jrows, max_limit)
+                return _json_envelope(
+                    [dict(zip(jcols, r)) for r in kept], jcols, omitted)
             if not rows:
                 return "(no results)"
             omission = None
@@ -312,6 +332,9 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
             return text
         # list -> joined (truncate)
         if isinstance(result, list):
+            if as_json:
+                kept, omitted = _limit_rows(list(result), max_limit)
+                return _json_envelope(kept, (), omitted)
             if not result:
                 return "(no results)"
             if max_limit > 0 and len(result) > max_limit:
@@ -324,7 +347,7 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
 
     tool_fn.__name__ = tool_name
     tool_fn.__qualname__ = tool_name
-    tool_fn.__doc__ = description
+    tool_fn.__doc__ = description + _AS_JSON_NOTE
 
     required_set = set(presentation.required)
     annotations = {}
@@ -354,6 +377,13 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
             "verbose", inspect.Parameter.KEYWORD_ONLY,
             default=None, annotation=Optional[bool],
         ))
+    # Every one of these tools returns data, so the structured mode is offered
+    # unconditionally rather than per-tool.
+    annotations["as_json"] = Optional[bool]
+    sig_params.append(inspect.Parameter(
+        "as_json", inspect.Parameter.KEYWORD_ONLY,
+        default=None, annotation=Optional[bool],
+    ))
     tool_fn.__annotations__ = {**annotations, "return": str}
     tool_fn.__signature__ = inspect.Signature(
         sig_params, return_annotation=str,
@@ -448,6 +478,76 @@ def _fts_con_for_root(mcp, root: str):
         return con
 
 
+#: Appended to every tool's description. A caller that has to GUESS the return
+#: shape guesses wrong: measured at 0/24 correct while calling the right tool
+#: 17/24 times, because `len()` on a rendered table counts characters. Naming
+#: the shape beside the signature is the cheapest fix for that, and it is the
+#: reason the envelope is a stable object rather than a bare array.
+_AS_JSON_NOTE = (
+    "\n\nPass as_json=true for structured output: "
+    '{"rows": [...], "columns": [...], "omitted": <int>}. '
+    "`omitted` is how many rows the limit dropped — it is 0 when the result is "
+    "complete, so a truncated result can never be mistaken for a whole one."
+)
+
+
+def _limit_rows(rows, max_limit):
+    """Apply the presentation limit, returning (kept, omitted_count)."""
+    if max_limit and max_limit > 0 and len(rows) > max_limit:
+        return rows[:max_limit], len(rows) - max_limit
+    return rows, 0
+
+
+def _project(cols, rows, presentation, verbose):
+    """Apply the compact_columns projection, if the tool declares one.
+
+    Shared so JSON and markdown callers see the same columns; a caller opts
+    out of both with verbose=True.
+    """
+    if not presentation.compact_columns or verbose:
+        return list(cols), list(rows)
+    keep_idx = [i for i, name in enumerate(cols)
+                if name in presentation.compact_columns]
+    order = {name: pos for pos, name in enumerate(presentation.compact_columns)}
+    keep_idx.sort(key=lambda i: order.get(cols[i], len(order)))
+    if not keep_idx:
+        return list(cols), list(rows)
+    return ([cols[i] for i in keep_idx],
+            [tuple(row[i] for i in keep_idx) for row in rows])
+
+
+def _json_envelope(rows, columns=(), omitted: int = 0) -> str:
+    """The one shape every tool returns under `as_json=True`.
+
+        {"rows": [...], "columns": [...], "omitted": <int>}
+
+    One envelope for every tool, so a caller learns the shape once instead of
+    per tool. `omitted` exists so truncation stays REPRESENTABLE: a bare array
+    that had been cut is indistinguishable from a complete one, and shipping
+    silent truncation on the programmatic path would reproduce the exact defect
+    this output mode was added to fix.
+
+    The trade is that `len()` of the envelope is 3, not the row count — which
+    is the misread that motivated this ("0/24 correct while 17/24 called the
+    right tool"). That is why the shape is stated in the tool description
+    rather than left to be guessed.
+    """
+    return _json.dumps(
+        {"rows": list(rows), "columns": list(columns), "omitted": int(omitted)},
+        indent=2, default=str,
+    )
+
+
+def _as_json_requested(kwargs) -> bool:
+    """Pop `as_json`, accepting the string forms MCP clients send."""
+    if "as_json" not in kwargs:
+        return False
+    v = kwargs.pop("as_json")
+    if isinstance(v, str):
+        return v.lower() in ("true", "1", "yes")
+    return bool(v) if v is not None else False
+
+
 def _register_tool(
     mcp,  # FastMCP type annotation removed to avoid import at module level
     con,
@@ -510,6 +610,10 @@ def _register_tool(
             max_rows = 0
 
         # Remove None values; coerce known numeric params to int.
+        # Pop before building macro args: `as_json` is a presentation choice,
+        # not a macro parameter, and passing it through raises a binder error.
+        as_json = _as_json_requested(kwargs)
+
         # Only numeric_params are coerced — blanket isdigit() would
         # break git SHAs like "1234567".
         filtered = {}
@@ -587,10 +691,18 @@ def _register_tool(
             elapsed = (_time.time() - t0) * 1000
             access_log.record(tool_name, cache_args, 0,
                               cached=False, elapsed_ms=elapsed)
-            return _empty_msg()
+            # A program needs an empty list it can iterate, not a sentence.
+            return _json_envelope([], cols, 0) if as_json else _empty_msg()
 
         total_rows = len(rows)
 
+        if as_json:
+            # Structured callers get every row the limit allows plus an
+            # explicit count of what was dropped — never a quietly short list.
+            kept, omitted = _limit_rows(list(rows), max_rows if limit_param else 0)
+            return _json_envelope([dict(zip(cols, r)) for r in kept],
+                                  cols, omitted)
+
         # Apply truncation
         omission = None
         if limit_param and max_rows > 0:
@@ -669,7 +781,7 @@ def _register_tool(
             "DIFFERENT repository, pass `root=<repository directory>` (an absolute path) — the "
             "repo is indexed on first use and cached."
         )
-    tool_fn.__doc__ = description
+    tool_fn.__doc__ = description + _AS_JSON_NOTE
 
     # Build parameter annotations for FastMCP schema generation.
     # All params get default=None so FastMCP validation passes even when
@@ -697,6 +809,13 @@ def _register_tool(
             "root", inspect.Parameter.KEYWORD_ONLY, default=None,
             annotation=Optional[str],
         ))
+    # Every one of these tools returns data, so the structured mode is offered
+    # unconditionally rather than per-tool.
+    annotations["as_json"] = Optional[bool]
+    sig_params.append(inspect.Parameter(
+        "as_json", inspect.Parameter.KEYWORD_ONLY,
+        default=None, annotation=Optional[bool],
+    ))
     tool_fn.__annotations__ = {**annotations, "return": str}
 
     tool_fn.__signature__ = inspect.Signature(

squackit-0.9.0/tests/test_structured_output.py

@@ -0,0 +1,191 @@
+"""Tools can return structured data instead of rendered prose.
+
+squackit's tools render for a human reader: tabular results become markdown
+tables, line-oriented ones become newline-joined text. That is right for an
+agent reading a briefing and close to useless to a program composing calls.
+
+Measured by a session running local models against the suite through lackpy,
+which generates one restricted-Python program per intent:
+
+    0/24 correct while 17/24 called the correct tool
+
+The models picked the right tool and misread the return shape. `len()` on
+`find_names`' newline-joined string gives 67 (characters) where the answer is
+8; on `find`'s markdown table it gives 2239. A wrong guess still validates,
+still runs, and answers confidently.
+
+The structure is not lost — it is discarded at the last step. The executors
+already return DuckDB relations and View objects, and the CLI already has
+`--json` using the same formatter. This exposes that over MCP.
+
+## The shape
+
+`as_json=True` returns ONE envelope for every tool:
+
+    {"rows": [...], "columns": [...], "omitted": <int>}
+
+Chosen deliberately over a bare array:
+
+* it is the same shape for every tool, so a caller learns it once
+* `omitted` makes truncation REPRESENTABLE. A bare array that had been cut
+  would be indistinguishable from a complete one — silent truncation is the
+  defect this suite has been chasing all week, and returning it in the
+  programmatic path would be a poor joke.
+* `columns` means a caller does not have to guess key names
+
+The cost is that `len(result)` on the envelope is 3, not the row count — the
+same trap that produced the 0/24. That is why the shape is stated in the tool
+description rather than left to be inferred.
+"""
+
+import json
+
+import pytest
+
+from squackit.defaults import ProjectDefaults
+
+try:
+    import fastmcp  # noqa: F401
+    HAS_FASTMCP = True
+except ImportError:
+    HAS_FASTMCP = False
+
+requires_fastmcp = pytest.mark.skipif(
+    not HAS_FASTMCP, reason="fastmcp not installed"
+)
+
+import asyncio
+import subprocess
+
+
+def _run_async(coro):
+    loop = asyncio.new_event_loop()
+    try:
+        return loop.run_until_complete(coro)
+    finally:
+        loop.close()
+
+
+@pytest.fixture(scope="module")
+def repo(tmp_path_factory):
+    """Eight functions, so a count is unambiguous."""
+    root = tmp_path_factory.mktemp("structured") / "proj"
+    (root / "src").mkdir(parents=True)
+    body = "\n".join(f"def fn_{i}(a):\n    return {i}\n" for i in range(8))
+    (root / "src" / "mod.py").write_text(body)
+    (root / "docs").mkdir()
+    (root / "docs" / "guide.md").write_text("# Guide\n\n## Section\n\ntext\n")
+    subprocess.run(["git", "init", "-q"], cwd=root, check=True)
+    subprocess.run(["git", "add", "-A"], cwd=root, check=True)
+    subprocess.run(["git", "-c", "user.email=t@e", "-c", "user.name=t",
+                    "commit", "-qm", "initial"], cwd=root, check=True)
+    # Absolute: a relative source roots at the process cwd by design (0.8.2),
+    # which is not the served corpus. A caller addressing a served repo names
+    # it in full, and that is the shape worth testing.
+    global SRC
+    SRC = str(root / "src" / "mod.py")
+    return root
+
+
+SRC = None  # set by the repo fixture: an ABSOLUTE source path.
+
+
+@pytest.fixture
+def mcp(repo):
+    from squackit.server import create_server
+    return create_server(root=str(repo), init=False)
+
+
+def _call(mcp, tool, args):
+    return _run_async(mcp.call_tool(tool, args)).content[0].text
+
+
+@requires_fastmcp
+class TestFindNamesJson:
+    """The sharpest measured case: a count that was 67 instead of 8."""
+
+    def test_default_is_unchanged(self, mcp):
+        """Existing callers must see exactly what they saw before."""
+        text = _call(mcp, "find_names", {"source": SRC,
+                                         "selector": ".function"})
+        assert not text.lstrip().startswith("{")
+        assert "fn_0" in text
+
+    def test_as_json_parses(self, mcp):
+        payload = json.loads(_call(mcp, "find_names", {
+            "source": SRC, "selector": ".function", "as_json": True}))
+        assert isinstance(payload, dict)
+
+    def test_len_of_rows_is_the_answer(self, mcp):
+        """This is the number the models got wrong."""
+        payload = json.loads(_call(mcp, "find_names", {
+            "source": SRC, "selector": ".function", "as_json": True}))
+        assert len(payload["rows"]) == 8, payload
+
+    def test_rows_are_the_names_themselves(self, mcp):
+        payload = json.loads(_call(mcp, "find_names", {
+            "source": SRC, "selector": ".function", "as_json": True}))
+        assert "fn_0" in payload["rows"]
+
+
+@requires_fastmcp
+class TestRelationToolsJson:
+
+    def test_find_returns_rows_of_objects(self, mcp):
+        payload = json.loads(_call(mcp, "find", {
+            "source": SRC, "selector": ".function", "as_json": True}))
+        assert len(payload["rows"]) == 8
+        assert isinstance(payload["rows"][0], dict)
+
+    def test_columns_are_declared(self, mcp):
+        payload = json.loads(_call(mcp, "find", {
+            "source": SRC, "selector": ".function", "as_json": True}))
+        assert "name" in payload["columns"]
+        assert set(payload["rows"][0]) <= set(payload["columns"])
+
+    def test_a_macro_tool_also_supports_it(self, mcp):
+        """Not just the pluckit tools — both wrappers."""
+        payload = json.loads(_call(mcp, "doc_outline", {"as_json": True}))
+        assert isinstance(payload["rows"], list)
+        assert isinstance(payload["columns"], list)
+
+    def test_default_markdown_is_unchanged(self, mcp):
+        text = _call(mcp, "find", {"source": SRC,
+                                   "selector": ".function"})
+        assert text.lstrip().startswith("|")
+
+
+@requires_fastmcp
+class TestTruncationStaysVisible:
+    """A cut array that looks complete is the defect, not the feature."""
+
+    def test_omitted_is_reported(self, mcp):
+        payload = json.loads(_call(mcp, "find", {
+            "source": SRC, "selector": ".function",
+            "max_results": 3, "as_json": True}))
+        assert len(payload["rows"]) == 3
+        assert payload["omitted"] == 5, payload
+
+    def test_omitted_is_zero_when_complete(self, mcp):
+        payload = json.loads(_call(mcp, "find", {
+            "source": SRC, "selector": ".function", "as_json": True}))
+        assert payload["omitted"] == 0
+
+    def test_no_markdown_omission_line_leaks_into_json(self, mcp):
+        """Appending '--- omitted N rows ---' to JSON would break parsing."""
+        raw = _call(mcp, "find", {"source": SRC,
+                                  "selector": ".function",
+                                  "max_results": 3, "as_json": True})
+        assert "---" not in raw
+        json.loads(raw)  # must not raise
+
+
+@requires_fastmcp
+class TestEmptyAndErrorCases:
+
+    def test_an_empty_result_is_an_empty_array_not_a_message(self, mcp):
+        """`(no results)` is prose; a program needs [] it can iterate."""
+        payload = json.loads(_call(mcp, "find_names", {
+            "source": SRC, "selector": ".class", "as_json": True}))
+        assert payload["rows"] == []
+        assert payload["omitted"] == 0