semql-prompt 0.3.0__tar.gz

semql_prompt-0.3.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Nikhil Pallamreddy
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

semql_prompt-0.3.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: semql-prompt
+Version: 0.3.0
+Summary: LLM-facing prompt rendering for a semql Catalog: the four-role planner/router/presenter/drilldown fragments, cacheable prompt segments, tool-description projection, and prompt-token budgeting.
+Author: Nikhil Pallamreddy
+Author-email: Nikhil Pallamreddy <nikhil.pallamreddy+git@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: semql>=0.3.0,<0.4
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/npalladium/semql
+Project-URL: Repository, https://github.com/npalladium/semql
+Project-URL: Issues, https://github.com/npalladium/semql/issues
+Description-Content-Type: text/markdown
+
+# semql-prompt
+
+LLM-facing prompt rendering for a [semql](https://github.com/npalladium/semql)
+`Catalog`.
+
+`semql`'s compiler is pure — it turns a `SemanticQuery` into SQL and never
+renders a prompt. This package is the rendering layer on top:
+
+- **Four-role prompt fragments** — `build_planner_prompt_fragment`,
+  `build_router_prompt_fragment`, `build_presenter_prompt_fragment`,
+  `build_drilldown_prompt_fragment`, `build_query_generator_prompt_fragment`.
+- **Cacheable segments** — `CatalogPrompt` (viewer-invariant `static` +
+  per-viewer `overlay`) for prompt-cache breakpoints, plus `prompt_hash`.
+- **Tool-description projection** — `to_openai_tools` / `to_langchain_tools`
+  / `to_openai_function` for function-calling clients.
+- **Prompt-token budgeting** — `PromptBudget`, `apply_budget`,
+  `estimate_tokens`.
+
+## Install
+
+```sh
+pip install semql-prompt
+```
+
+## Quick start
+
+The catalog-level conveniences take the catalog as their first argument:
+
+```python
+from semql import Catalog
+from semql_prompt import planner_prompt, planner_prompt_segments, prompt_hash, to_openai_tools
+
+text = planner_prompt(catalog, viewer=viewer)
+segs = planner_prompt_segments(catalog)
+key  = prompt_hash(catalog)
+tools = to_openai_tools(catalog, viewer=viewer)
+```
+
+For the lower-level per-role fragment builders, see
+[API reference](../../docs/api/semql_prompt.md).
+
+## License
+
+BSD-3-Clause.

semql_prompt-0.3.0/README.md

@@ -0,0 +1,44 @@
+# semql-prompt
+
+LLM-facing prompt rendering for a [semql](https://github.com/npalladium/semql)
+`Catalog`.
+
+`semql`'s compiler is pure — it turns a `SemanticQuery` into SQL and never
+renders a prompt. This package is the rendering layer on top:
+
+- **Four-role prompt fragments** — `build_planner_prompt_fragment`,
+  `build_router_prompt_fragment`, `build_presenter_prompt_fragment`,
+  `build_drilldown_prompt_fragment`, `build_query_generator_prompt_fragment`.
+- **Cacheable segments** — `CatalogPrompt` (viewer-invariant `static` +
+  per-viewer `overlay`) for prompt-cache breakpoints, plus `prompt_hash`.
+- **Tool-description projection** — `to_openai_tools` / `to_langchain_tools`
+  / `to_openai_function` for function-calling clients.
+- **Prompt-token budgeting** — `PromptBudget`, `apply_budget`,
+  `estimate_tokens`.
+
+## Install
+
+```sh
+pip install semql-prompt
+```
+
+## Quick start
+
+The catalog-level conveniences take the catalog as their first argument:
+
+```python
+from semql import Catalog
+from semql_prompt import planner_prompt, planner_prompt_segments, prompt_hash, to_openai_tools
+
+text = planner_prompt(catalog, viewer=viewer)
+segs = planner_prompt_segments(catalog)
+key  = prompt_hash(catalog)
+tools = to_openai_tools(catalog, viewer=viewer)
+```
+
+For the lower-level per-role fragment builders, see
+[API reference](../../docs/api/semql_prompt.md).
+
+## License
+
+BSD-3-Clause.

semql_prompt-0.3.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "semql-prompt"
+version = "0.3.0"
+description = "LLM-facing prompt rendering for a semql Catalog: the four-role planner/router/presenter/drilldown fragments, cacheable prompt segments, tool-description projection, and prompt-token budgeting."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Nikhil Pallamreddy", email = "nikhil.pallamreddy+git@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "semql>=0.3.0,<0.4",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/npalladium/semql"
+Repository = "https://github.com/npalladium/semql"
+Issues = "https://github.com/npalladium/semql/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+semql = { workspace = true, editable = true }

semql_prompt-0.3.0/src/semql_prompt/__init__.py

@@ -0,0 +1,78 @@
+"""Public surface of the semql-prompt package.
+
+The LLM-facing rendering layer for a semql ``Catalog``: the typed
+four-role planner / router / presenter / drilldown prompt fragments, the
+cacheable two-segment ``CatalogPrompt``, tool-description projection
+(OpenAI / LangChain), and prompt-token budgeting.
+
+The ``semql`` compiler emits SQL and never renders a prompt; that lives
+here. Catalog-level conveniences (``planner_prompt`` /
+``planner_prompt_segments`` / ``prompt_hash`` / ``to_openai_tools`` /
+``to_langchain_tools``) are functions taking the catalog as their first
+argument.
+"""
+
+from __future__ import annotations
+
+from semql_prompt.catalog_tools import (
+    planner_prompt,
+    planner_prompt_segments,
+    prompt_hash,
+    to_langchain_tools,
+    to_openai_tools,
+)
+from semql_prompt.prompt import (
+    CatalogPrompt,
+    ToolDescriptionProjection,
+    build_drilldown_prompt_fragment,
+    build_planner_prompt_fragment,
+    build_planner_prompt_segments,
+    build_presenter_prompt_fragment,
+    build_query_generator_prompt_fragment,
+    build_router_prompt_fragment,
+    catalog_prompt_hash,
+    filter_tool_descriptions,
+    project_tool_descriptions,
+    render_catalog_block,
+    render_catalog_segments,
+    render_saved_query_tool_description,
+    render_tool_description,
+    to_openai_function,
+)
+from semql_prompt.prompt_budget import (
+    BudgetResult,
+    PromptBudget,
+    apply_budget,
+    estimate_tokens,
+)
+
+__all__ = [
+    # prompt fragments + rendering
+    "CatalogPrompt",
+    "ToolDescriptionProjection",
+    "build_drilldown_prompt_fragment",
+    "build_planner_prompt_fragment",
+    "build_planner_prompt_segments",
+    "build_presenter_prompt_fragment",
+    "build_query_generator_prompt_fragment",
+    "build_router_prompt_fragment",
+    "catalog_prompt_hash",
+    "filter_tool_descriptions",
+    "project_tool_descriptions",
+    "render_catalog_block",
+    "render_catalog_segments",
+    "render_saved_query_tool_description",
+    "render_tool_description",
+    "to_openai_function",
+    # token budgeting
+    "BudgetResult",
+    "PromptBudget",
+    "apply_budget",
+    "estimate_tokens",
+    # catalog-level conveniences
+    "planner_prompt",
+    "planner_prompt_segments",
+    "prompt_hash",
+    "to_langchain_tools",
+    "to_openai_tools",
+]

semql_prompt-0.3.0/src/semql_prompt/catalog_tools.py

@@ -0,0 +1,257 @@
+"""Catalog-level prompt conveniences.
+
+Each takes the catalog as its first argument and reads it through the
+public surface (``catalog.as_dict()``, ``catalog.policy``,
+``catalog.views`` / ``.lookups`` / ``.glossary`` / ``.relations`` /
+``.saved_queries``)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from semql.model import AuthContext, ResolutionContext
+
+from semql_prompt.prompt import (
+    CatalogPrompt,
+    build_planner_prompt_segments,
+    catalog_prompt_hash,
+    project_tool_descriptions,
+    render_saved_query_tool_description,
+    render_tool_description,
+    to_openai_function,
+)
+
+if TYPE_CHECKING:
+    from semql import Catalog
+    from semql.hooks import CubePromptHook
+    from semql.model import Cube
+    from semql.retrieve import Retriever
+    from semql.spec import SavedQuery
+
+
+def planner_prompt(
+    catalog: Catalog,
+    *,
+    only_exposed: bool = True,
+    include_introspection: bool = False,
+    viewer: AuthContext | None = None,
+    ctx: ResolutionContext | None = None,
+    user_query: str | None = None,
+    retriever: Retriever | None = None,
+    top_k: int = 10,
+    retrieval_threshold: int = 50,
+    current_date: str | None = None,
+    retrieved_snippets: list[str] | None = None,
+    extra: str | None = None,
+    cube_prompt_hooks: list[CubePromptHook] | None = None,
+) -> str:
+    """Render the planner prompt fragment for ``catalog``.
+
+    When ``viewer`` is provided, the catalog block shrinks to the cubes
+    the viewer is allowed to see. ``ctx`` is the resolution context for
+    dimension-value lookups. Retrieval mode narrows the block to the
+    top-``top_k`` cubes when ``user_query`` + ``retriever`` are set and the
+    catalog exceeds ``retrieval_threshold`` questions."""
+    segments = build_planner_prompt_segments(
+        catalog.as_dict(),
+        only_exposed=only_exposed,
+        include_introspection=include_introspection,
+        views=catalog.views,
+        viewer=viewer,
+        policy=catalog.policy,
+        lookups=catalog.lookups,
+        ctx=ctx,
+        glossary=catalog.glossary,
+        relations=catalog.relations,
+        user_query=user_query,
+        retriever=retriever,
+        top_k=top_k,
+        retrieval_threshold=retrieval_threshold,
+        saved_queries=list(catalog.saved_queries.values()),
+        cube_prompt_hooks=cube_prompt_hooks,
+    )
+    return segments.full(
+        current_date=current_date,
+        retrieved_snippets=retrieved_snippets,
+        extra=extra,
+    )
+
+
+def planner_prompt_segments(
+    catalog: Catalog,
+    *,
+    only_exposed: bool = True,
+    include_introspection: bool = False,
+    viewer: AuthContext | None = None,
+    ctx: ResolutionContext | None = None,
+    user_query: str | None = None,
+    retriever: Retriever | None = None,
+    top_k: int = 10,
+    retrieval_threshold: int = 50,
+) -> CatalogPrompt:
+    """Render the planner prompt as a cacheable two-segment object — a
+    viewer-invariant ``static`` segment plus a per-viewer ``overlay``."""
+    return build_planner_prompt_segments(
+        catalog.as_dict(),
+        only_exposed=only_exposed,
+        include_introspection=include_introspection,
+        views=catalog.views,
+        viewer=viewer,
+        policy=catalog.policy,
+        lookups=catalog.lookups,
+        ctx=ctx,
+        glossary=catalog.glossary,
+        relations=catalog.relations,
+        user_query=user_query,
+        retriever=retriever,
+        top_k=top_k,
+        retrieval_threshold=retrieval_threshold,
+        saved_queries=list(catalog.saved_queries.values()),
+    )
+
+
+def prompt_hash(
+    catalog: Catalog,
+    *,
+    only_exposed: bool = True,
+    ctx: ResolutionContext | None = None,
+) -> str:
+    """SHA256 hex digest of the static (viewer-invariant) prompt segment —
+    stable across viewer changes, so it keys a prompt-fragment cache that a
+    catalog mutation invalidates."""
+    return catalog_prompt_hash(
+        catalog.as_dict(),
+        only_exposed=only_exposed,
+        lookups=catalog.lookups,
+        ctx=ctx,
+        glossary=catalog.glossary,
+        relations=catalog.relations,
+    )
+
+
+def _visible_tool_targets(
+    catalog: Catalog,
+    *,
+    viewer: AuthContext | None,
+    only_exposed: bool,
+) -> tuple[list[Cube], list[SavedQuery]]:
+    """The cubes + saved queries a viewer may expose as tools.
+
+    The single visibility decision both :func:`to_openai_tools` and
+    :func:`to_langchain_tools` consume, so the two exporters can't drift:
+    cube gating runs through ``project_tool_descriptions`` (policy- and
+    role-aware), saved-query gating through ``required_roles`` (ANY-match,
+    the same rule the MCP server applies)."""
+    from semql.introspect import iter_cubes
+
+    by_name = catalog.as_dict()
+    proj = project_tool_descriptions(
+        by_name,
+        only_exposed=only_exposed,
+        viewer=viewer,
+        policy=catalog.policy,
+    )
+    visible_cubes = {**proj.invariant, **proj.viewer_gated}
+    cubes = [
+        c
+        for c in iter_cubes(
+            by_name,
+            include_meta=False,
+            only_exposed=only_exposed,
+            viewer=None,  # proj already determined visibility
+            policy=None,
+        )
+        if c.name in visible_cubes
+    ]
+    saved = [
+        sq
+        for sq in catalog.saved_queries.values()
+        if not sq.required_roles
+        or (viewer is not None and any(r in viewer.roles for r in sq.required_roles))
+    ]
+    return cubes, saved
+
+
+def to_openai_tools(
+    catalog: Catalog,
+    *,
+    viewer: AuthContext | None = None,
+    only_exposed: bool = True,
+) -> list[dict[str, Any]]:
+    """One OpenAI-format tool dict per visible cube + saved query.
+    Role-gated cubes / saved queries are excluded unless ``viewer`` holds a
+    matching role."""
+    from semql.spec import SemanticQuery
+
+    cubes, saved = _visible_tool_targets(catalog, viewer=viewer, only_exposed=only_exposed)
+    tools: list[dict[str, Any]] = [to_openai_function(c) for c in cubes]
+    for sq in saved:
+        tools.append(
+            {
+                "type": "function",
+                "function": {
+                    "name": f"saved_{sq.name}",
+                    "description": render_saved_query_tool_description(sq),
+                    "parameters": SemanticQuery.model_json_schema(),
+                },
+            }
+        )
+    return tools
+
+
+def to_langchain_tools(
+    catalog: Catalog,
+    *,
+    viewer: AuthContext | None = None,
+    only_exposed: bool = True,
+) -> list[object]:
+    """One LangChain ``StructuredTool`` per visible cube + saved query.
+    Requires ``langchain-core``. Cube tools compile a caller-supplied
+    ``SemanticQuery``; saved-query tools are zero-arg and run the baked
+    query — matching the cube/saved-query split of :func:`to_openai_tools`
+    via the shared :func:`_visible_tool_targets`."""
+    from typing import cast
+
+    try:
+        from langchain_core.tools import StructuredTool  # type: ignore[import-not-found]
+    except ImportError:
+        raise ImportError(
+            "langchain-core is required for to_langchain_tools(). "
+            "Install it with: pip install langchain-core"
+        ) from None
+    structured_tool_cls = cast(Any, StructuredTool)
+
+    from semql.spec import SemanticQuery
+
+    cubes, saved = _visible_tool_targets(catalog, viewer=viewer, only_exposed=only_exposed)
+    tools: list[object] = []
+    for cube in cubes:
+        _cube_ref = cube
+
+        def _run(query: SemanticQuery, *, _c: object = _cube_ref) -> dict[str, object]:
+            compiled = catalog.compile(query, viewer=viewer)
+            return {"sql": compiled.sql, "params": compiled.params}
+
+        tools.append(
+            structured_tool_cls.from_function(
+                func=_run,
+                name=f"query_{cube.name}",
+                description=render_tool_description(cube),
+                args_schema=SemanticQuery,
+            )
+        )
+    for sq in saved:
+        _sq_ref = sq
+
+        def _run_saved(*, _q: SavedQuery = _sq_ref) -> dict[str, object]:
+            compiled = catalog.compile(_q.query, viewer=viewer)
+            return {"sql": compiled.sql, "params": compiled.params}
+
+        tools.append(
+            structured_tool_cls.from_function(
+                func=_run_saved,
+                name=f"saved_{sq.name}",
+                description=render_saved_query_tool_description(sq),
+            )
+        )
+    return tools