arango-query-core 0.2.6__tar.gz → 0.2.8__tar.gz

arango_query_core-0.2.8/.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh run *)",
+      "Bash(git worktree *)"
+    ]
+  }
+}

arango_query_core-0.2.8/.claude/skills/pr-review/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: pr-review
+description: Review an open arango-query-core pull request end to end — independently verify mergeability and the full CI gate (pytest, ruff, mypy) in an isolated worktree, trace the diff for correctness, and report a clear merge/no-merge recommendation. Use when asked to look at, review, or check a PR in this repo, or before merging one.
+---
+
+# PR review (arango-query-core)
+
+## Invocation
+`/pr-review <PR number>` — or just ask to look at / review a PR.
+
+## Purpose
+Don't trust GitHub's green checkmark or a skim of the diff alone. Independently
+rebuild the PR's test/lint/type gate in a scratch worktree, trace the tricky
+logic by hand against the new tests, and only then recommend merging. This repo
+has hit real, silent failure modes (see **Gotchas** below) that a surface-level
+review misses.
+
+## Repo shape (read this first)
+- **Primary repo:** `arango-solutions-org/arango-query-core` — PRs and issues
+  live here. **Secondary/mirror:** `ArthurKeen/arango-query-core` — code-only,
+  kept in sync by a dual-push `origin` remote; it does not carry its own PRs.
+  Always run `gh pr` / `gh issue` commands against the primary unless told
+  otherwise. (Confirm which is primary — it has changed before.)
+- **Release gate:** PyPI publishing is pinned-artifact (CC-9): every merge to
+  `main` is a potential version bump. If the PR's `CHANGELOG.md` entry lands
+  under a version header that's already tagged and published, that's a bug in
+  the PR (or in a prior release) worth flagging, not something to wave through.
+
+## Protocol
+
+### 1. Pull the PR's shape
+```bash
+gh pr view <N> --repo arango-solutions-org/arango-query-core \
+  --json title,body,author,headRefName,baseRefName,commits,additions,deletions,changedFiles,mergeable,statusCheckRollup
+gh pr diff <N> --repo arango-solutions-org/arango-query-core
+```
+Read the PR body as the author's own claim about scope and evidence (eval
+numbers, measured deltas) — you're about to check whether the code backs it up.
+
+### 2. Independently verify mergeability
+Don't trust the `mergeable` field alone — it can read `UNKNOWN` right after a
+push, and (per the gotchas below) a corrupted commit graph can make GitHub
+report `CONFLICTING` even when the content is actually fine, or vice versa.
+Cross-check with a real history-aware merge:
+```bash
+git fetch origin
+git merge-tree --write-tree origin/main origin/<head-branch>
+echo "exit: $?"   # 0 and a single tree id = clean; conflict markers = real conflict
+```
+Use the **modern 3-ref-aware form** (`--write-tree`), never the bare legacy
+`git merge-tree <a> <b>` — it ignores actual commit ancestry and reports false
+conflicts for a branch that already contains `main`.
+
+### 3. Rebuild the CI gate in an isolated worktree
+Never run this against your own working tree (it may have unrelated local
+changes, and installing a PR's deps into your main venv is how versions
+drift). Mirror `.github/workflows/ci.yml` exactly:
+```bash
+git worktree add /tmp/pr<N>-check origin/<head-branch> --detach
+cd /tmp/pr<N>-check
+python3 -m venv .venv-check && source .venv-check/bin/activate
+pip install -q -e ".[dev]"
+
+pytest -q                    # mirrors: pytest -q --tb=short
+ruff check .
+ruff format --check .
+mypy                          # mirrors: mypy (files = ["arango_query_core"])
+```
+All four must be clean. Note the test count and compare it to `main`'s —
+a PR that doesn't grow the count for a new feature is under-tested.
+
+Clean up when done:
+```bash
+cd /Users/arthurkeen/code/arango-query-core
+git worktree remove /tmp/pr<N>-check --force
+```
+
+### 4. Trace the diff, don't just skim it
+For anything touching control flow (retry loops, fallback logic, ordering
+rules), hand-trace at least the two or three trickiest test cases against the
+actual code — don't assume the tests passing proves the stated semantics.
+Specifically check:
+- **Scope honesty** — does the PR body list what's *not* included? A PR that
+  quietly expands scope beyond its own description is a flag, not a bonus.
+- **Protocol/seam changes** — `QueryLanguageAdapter` seams are called
+  *unconditionally* by `NLQueryEngine` (no `hasattr` guard). A new seam means
+  every existing `FakeAdapter` in the test suite needs a stub for it, or the
+  merged tree will crash at prompt-build time. Grep for adapter classes in
+  `tests/` and confirm each implements every current seam.
+- **CHANGELOG placement** — does the entry land under a version header that's
+  already tagged (`git tag -l`) and already on PyPI? If so, the version is
+  effectively lying about its own contents (see Repo shape above) — flag it
+  even though it's not this PR's fault to fix.
+
+### 5. Report
+State plainly: what the PR does, the hand-traced correctness notes, the
+independent verification results (test count, ruff, mypy, merge-tree exit
+code, CI check conclusions), any scope/changelog issues found, and an explicit
+recommend-or-not. Don't hedge if everything checks out — say so and recommend
+merging.
+
+### 6. If asked to merge
+```bash
+gh pr merge <N> --repo arango-solutions-org/arango-query-core --merge --delete-branch
+```
+Re-check `mergeable`/CI immediately before merging — state can change between
+review and merge. After merging, **sync manually** — merging on GitHub does
+not update your local clone or the mirror:
+```bash
+git fetch origin && git checkout main && git merge --ff-only origin/main
+git push origin main   # dual-push: lands on both primary and mirror
+```
+`--delete-branch` only deletes the branch on the repo the PR lives in
+(primary). If the branch was ever pushed to the mirror too, delete it there
+explicitly: `git push https://github.com/ArthurKeen/arango-query-core.git --delete <branch>`.
+
+## Gotchas (hard-won, don't re-learn these)
+
+- **Never `git stash` mid-merge-conflict-resolution**, even for an unrelated
+  side-check (like "did this formatting issue pre-exist on main?"). Stashing
+  while `MERGE_HEAD` is set but conflicts are already resolved-and-staged
+  silently drops the merge state — the commit you make afterward looks fine
+  (correct file content) but has only **one parent**, so Git and GitHub don't
+  actually see it as containing `main`. Symptom: `mergeable` stays
+  `CONFLICTING` after a resolution that looks complete. Fix: check
+  `git log --format='%H %P' <commit>` — a merge commit must show two parents.
+  If it shows one, `git reset --hard` to before the merge and redo it cleanly
+  with no stash in between, then verify parent count *before* pushing.
+- **A clean-looking commit can still get zero CI runs.** Twice now, a push
+  (once a corrupted single-parent "merge", once a plain version-bump commit
+  plus its tag) registered **no check-suite at all** — not even third-party
+  apps like GitGuardian. This isn't a code problem; it's GitHub event-delivery
+  flakiness. Verify with
+  `gh api repos/<repo>/commits/<sha>/check-suites --jq '.check_suites'`
+  before concluding anything is broken. A delete-and-recreate of a tag
+  sometimes forces redelivery; it isn't guaranteed to. Don't block a release
+  on it — fall back to the proven manual path (below) rather than debug
+  GitHub's webhook plumbing indefinitely.
+- **PyPI publish fallback.** The `publish.yml` workflow uses trusted
+  publishing (OIDC, no token) gated to `github.repository ==
+  'ArthurKeen/arango-query-core'` and only fires on a `v*` tag push. If it
+  doesn't fire (see above) or you need to publish immediately: build and
+  check locally, then upload with the token in the gitignored `.env`:
+  ```bash
+  python -m build --outdir <scratch>/dist
+  twine check <scratch>/dist/*
+  TWINE_USERNAME=__token__ TWINE_PASSWORD=$(grep '^PYPI_TOKEN=' .env | cut -d= -f2) \
+    twine upload --non-interactive <scratch>/dist/*
+  ```
+  If the workflow does fire later for a version already manually published,
+  it will just hit a harmless `400 File already exists` on the duplicate
+  filename — not a problem, and actually confirms trusted publishing works.
+- **PyPI's project JSON can lag a few seconds after upload** — `info.version`
+  may show the previous release momentarily. Re-check, or check
+  `'<version>' in releases` / hit the version's own release-page URL directly,
+  before concluding an upload failed.

{arango_query_core-0.2.6 → arango_query_core-0.2.8}/CHANGELOG.md

@@ -6,6 +6,53 @@ exact versions (contextual-data-fabric CC-9) and re-run their golden /
 eval suites on every bump — pre-1.0, **minor** bumps may break the API
 and this file must say so explicitly.
 
+## [0.2.7] - 2026-11-06
+
+### Added
+
+- **Host extensions** (`arango_query_core.nl.host`). A host whose engine
+  accepts more than the target language can now say so without rewriting
+  the adapter's grammar section. `HostExtensions` declares:
+  - `predicates`: `HostPredicate`, a predicate the host's engine accepts
+    (such as a registered text match), the `Class.property` names it may be
+    used on, what not to write instead, and where the engine refuses it;
+  - `rules`: the host's own limits that are not about one property, one
+    sentence each;
+  - `properties`: `PropertyFact`, per-property facts (`type`, `required`,
+    `orderable`, `description`; names follow `PropertyInfo`).
+
+  `host_prompt_section()` renders them as one section that adds to the
+  grammar and says that everything the grammar forbids stays forbidden.
+  Host prose is collapsed to one line, capped at 600 characters, and has
+  runs of `#` collapsed, so it cannot open a prompt section or carry the
+  `## Examples` cache marker. Names are validated when built. All four
+  names are exported from `arango_query_core.nl`.
+- **`NLQueryEngine.host_extensions`**, `None` by default. The section goes
+  straight after the grammar section, inside the cacheable prefix, before
+  `## Examples`. With `None`, or a declaration that renders nothing, the
+  system prompt is byte-identical to 0.2.6's.
+
+### Fixed
+
+- The engine comment and the `nl.postconditions` docstrings claimed that
+  postcondition prompt sections stay inside the cacheable prefix. They are
+  appended last, so when a `## Examples` section is present they fall after
+  `split_system_for_anthropic_cache`'s split. Comments only; behaviour is
+  unchanged.
+
+## [0.2.8] - 2026-11-09
+
+### Added
+
+- **`NLQueryEngine.generate(context=...)`**, `""` by default. A fact about one
+  request that the answer depends on, such as the date that "this quarter" or
+  "the last 30 days" is counted from. It follows the question in the user
+  message of **every** attempt, repairs included, where `user_hint` reaches the
+  first attempt only. It is cleaned by the host-prose rule (one line, runs of
+  `#` collapsed, at most 600 characters) and never reaches the system prompt,
+  retrieval or `PostconditionContext.question`. Empty, or empty once cleaned,
+  every request is byte-identical to before.
+
 ## [0.2.6] - 2026-10-29
 
 ### Added

{arango_query_core-0.2.6 → arango_query_core-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arango-query-core
-Version: 0.2.6
+Version: 0.2.8
 Summary: Shared conceptual-model and NL substrate for ArangoDB query transpilers (arango-cypher-py, arango-sparql-py)
 Project-URL: Repository, https://github.com/ArthurKeen/arango-query-core
 Project-URL: Changelog, https://github.com/ArthurKeen/arango-query-core/blob/main/CHANGELOG.md
@@ -81,6 +81,7 @@ fabric pin one artifact instead of forking the same code three ways.
 | `arango_query_core.nl` | Language-agnostic NL→query engine: LLM providers (OpenAI / OpenRouter / Anthropic with prompt caching), BM25/dense few-shot retrieval, caller-supplied semantic postconditions, and the generate→validate→repair loop |
 | `arango_query_core.nl.seams` | `QueryLanguageAdapter` — the eight language-specific seams an adapter implements (grammar prompt, corpus, validator, repair rules, guardrails, entity/predicate/path grounding) |
 | `arango_query_core.nl.grounding` / `pathindex` | Entity, predicate, and relationship-path grounding retrieval (seams 6-8) — inject known IDs, schema conventions, and navigation hints into the prompt |
+| `arango_query_core.nl.host` | `HostExtensions` — what the host's engine accepts beyond the target language (registered predicates, per-property facts, its own limits), rendered after the grammar section via `NLQueryEngine(host_extensions=...)` |
 | `arango_query_core.nl.postconditions` | Caller-supplied semantic invariants enforced through the same generate→validate→retry budget, failing closed on exhaustion |
 | `arango_query_core.nl.synthbank` | Ontology-agnostic query-shape template catalog for synthetic few-shot bank generation |
 

{arango_query_core-0.2.6 → arango_query_core-0.2.8}/README.md

@@ -20,6 +20,7 @@ fabric pin one artifact instead of forking the same code three ways.
 | `arango_query_core.nl` | Language-agnostic NL→query engine: LLM providers (OpenAI / OpenRouter / Anthropic with prompt caching), BM25/dense few-shot retrieval, caller-supplied semantic postconditions, and the generate→validate→repair loop |
 | `arango_query_core.nl.seams` | `QueryLanguageAdapter` — the eight language-specific seams an adapter implements (grammar prompt, corpus, validator, repair rules, guardrails, entity/predicate/path grounding) |
 | `arango_query_core.nl.grounding` / `pathindex` | Entity, predicate, and relationship-path grounding retrieval (seams 6-8) — inject known IDs, schema conventions, and navigation hints into the prompt |
+| `arango_query_core.nl.host` | `HostExtensions` — what the host's engine accepts beyond the target language (registered predicates, per-property facts, its own limits), rendered after the grammar section via `NLQueryEngine(host_extensions=...)` |
 | `arango_query_core.nl.postconditions` | Caller-supplied semantic invariants enforced through the same generate→validate→retry budget, failing closed on exhaustion |
 | `arango_query_core.nl.synthbank` | Ontology-agnostic query-shape template catalog for synthetic few-shot bank generation |
 

{arango_query_core-0.2.6 → arango_query_core-0.2.8}/arango_query_core/nl/__init__.py

@@ -9,6 +9,7 @@ enters exclusively through :class:`~arango_query_core.nl.seams.QueryLanguageAdap
 from .engine import NLQueryEngine, NLResult
 from .fewshot import BM25Retriever, DenseRetriever, FewShotIndex, Retriever, cached_few_shot_index
 from .grounding import GroundedEntity, GroundedPredicate, LabelIndex, PredicateIndex
+from .host import HostExtensions, HostPredicate, PropertyFact, host_prompt_section
 from .pathindex import ClassPath, ClassPathIndex
 from .postconditions import (
     Postcondition,
@@ -38,6 +39,8 @@ __all__ = [
     "GroundedEntity",
     "GroundedPredicate",
     "GuardrailVerdict",
+    "HostExtensions",
+    "HostPredicate",
     "LabelIndex",
     "LLMProvider",
     "NLQueryEngine",
@@ -48,6 +51,7 @@ __all__ = [
     "PostconditionContext",
     "PostconditionViolation",
     "PredicateIndex",
+    "PropertyFact",
     "QueryLanguageAdapter",
     "Retriever",
     "SHAPE_CATALOG",
@@ -55,6 +59,7 @@ __all__ = [
     "ValidationResult",
     "cached_few_shot_index",
     "get_llm_provider",
+    "host_prompt_section",
     "postcondition_prompt_sections",
     "run_postconditions",
     "split_system_for_anthropic_cache",

{arango_query_core-0.2.6 → arango_query_core-0.2.8}/arango_query_core/nl/engine.py

@@ -23,6 +23,7 @@ from collections.abc import Sequence
 from dataclasses import dataclass, field
 from typing import Any
 
+from .host import HostExtensions, _clean, host_prompt_section
 from .postconditions import (
     Postcondition,
     PostconditionContext,
@@ -85,6 +86,11 @@ class NLQueryEngine:
     adapter's path index (seam 8) and rendered AFTER the predicate
     section — same post-cache-boundary discipline; the adapter resolves
     the anchor/target identifiers from its own seam-6/7 state (D-02).
+
+    ``host_extensions`` (:mod:`~arango_query_core.nl.host`) is rendered straight
+    after the grammar section, before ``## Examples``, so it is part of the
+    cacheable prefix. Caller postconditions' prompt sections come last; when a
+    ``## Examples`` section is present they therefore fall after the cache split.
     """
 
     provider: LLMProvider
@@ -103,8 +109,20 @@ class NLQueryEngine:
     on :attr:`NLResult.provider_errors`. If no attempt ever returned a
     response, the last exception is re-raised. False (the default) lets the
     first exception propagate, as before."""
+    host_extensions: HostExtensions | None = None
+    """What the host's engine accepts beyond the target language (:mod:`.host`),
+    rendered straight after the grammar section, inside the cacheable prefix.
+    ``None`` or a declaration that renders nothing leaves the system prompt
+    byte-identical."""
 
-    def generate(self, question: str, *, schema_context: str = "", user_hint: str = "") -> NLResult:
+    def generate(
+        self,
+        question: str,
+        *,
+        schema_context: str = "",
+        user_hint: str = "",
+        context: str = "",
+    ) -> NLResult:
         """Generate a query for *question*.
 
         *user_hint* is appended to the **first** attempt's user message only —
@@ -112,10 +130,21 @@ class NLQueryEngine:
         failure. It leaves the system prompt (the cacheable prefix), few-shot
         retrieval and postcondition context untouched; retries carry their own
         "previous query was rejected" text.
+
+        *context* follows the question on **every** attempt, repairs included: a
+        fact about this request that the answer depends on, such as the date that
+        relative words ("this quarter", "the last 30 days") are counted from. It is
+        reduced to one line of at most 600 characters by the rule :mod:`.host`
+        applies to host prose, and it never reaches the system prompt, retrieval
+        or :attr:`PostconditionContext.question`, so a check that reads the
+        asker's words never reads it. The engine gives it no meaning. Empty, or
+        empty once cleaned, means a byte-identical request.
         """
         result = NLResult()
         system = self._system_prompt(question, schema_context)
-        user = f"{question}\n\n{user_hint}" if user_hint else question
+        note = _clean(context)
+        asked = f"{question}\n\n{note}" if note else question
+        user = f"{asked}\n\n{user_hint}" if user_hint else asked
         last_provider_error: Exception | None = None
         failure: ValidationResult | None = None
         violation: PostconditionViolation | None = None
@@ -134,7 +163,7 @@ class NLQueryEngine:
                     assert failure is not None
                     hint = self.adapter.repair_hint(candidate, failure) or failure.error
                 user = (
-                    f"{question}\n\n"
+                    f"{asked}\n\n"
                     f"Your previous {self.adapter.language} query was rejected:\n"
                     f"```{self.adapter.language}\n{candidate}\n```\n"
                     f"Problem: {hint}\n"
@@ -232,6 +261,9 @@ class NLQueryEngine:
 
     def _system_prompt(self, question: str, schema_context: str) -> str:
         sections = [self.adapter.grammar_prompt_section(schema_context)]
+        # Static per engine, so it sits with the grammar, before the ``## Examples``
+        # cache boundary. ``""`` when nothing is declared, and the join drops it.
+        sections.append(host_prompt_section(self.host_extensions))
         index = self.adapter.few_shot_index()
         if index is not None:
             examples = index.format_prompt_section(
@@ -255,9 +287,10 @@ class NLQueryEngine:
             if path_block:
                 sections.append(path_block)
         # Caller postconditions announce their invariants up front so the model
-        # aims to satisfy them, not just get corrected after breaking one. These
-        # are static per call (no per-question content), so they stay inside the
-        # cacheable prefix rather than after the few-shot cache boundary.
+        # aims to satisfy them, not just get corrected after breaking one. They are
+        # static per call but appended last: when an ``## Examples`` section is
+        # present, split_system_for_anthropic_cache splits there and these land in
+        # the uncached suffix; without one, the whole prompt is a single cached block.
         sections.extend(postcondition_prompt_sections(self.postconditions))
         return "\n\n".join(s for s in sections if s)
 

arango_query_core-0.2.8/arango_query_core/nl/host.py

@@ -0,0 +1,223 @@
+"""What a host's engine accepts beyond the target language, told to the NL engine.
+
+A host may run the generated query on an engine that accepts more than the language
+the adapter teaches: a registered predicate such as a text match, per-property facts
+(a datatype, whether it may be sorted, whether it is always present), and limits of
+its own. Seam 1 (``grammar_prompt_section``) is adapter-owned and whole, so without
+this module the only way to say any of that is to rewrite the grammar.
+
+* :class:`HostPredicate` — a predicate the host's engine accepts in addition to the
+  language, with the properties it may be used on and what not to write instead.
+* :class:`PropertyFact` — facts about one property that change which queries succeed.
+  Field names follow :class:`arango_query_core.mapping.PropertyInfo`.
+* :class:`HostExtensions` — the declaration: predicates, rules (the host's limits that
+  are not about one property, one sentence each) and property facts.
+* :func:`host_prompt_section` — the system-prompt section; ``""`` when nothing is
+  declared. :class:`~arango_query_core.nl.engine.NLQueryEngine` renders it straight
+  after the grammar section, inside the cacheable prefix, when its
+  ``host_extensions`` field is set.
+
+Rules this module holds:
+
+* **Nothing supplied, nothing changed.** ``None``, an empty declaration, a predicate
+  offered on no property, a fact that declares nothing and a blank rule all render
+  ``""``, and the engine's system prompt is then byte-identical to one built without
+  the field.
+* **It adds to the grammar and never lifts its rules.** One fixed sentence,
+  :data:`HOST_RULE`, says so in the section itself.
+* **Host strings cannot open a prompt section.** Every piece of host prose is
+  collapsed to one line, capped at :data:`LINE_MAX` characters, and has its runs of
+  ``#`` collapsed to one, so it can neither start a heading nor carry the
+  ``## Examples`` marker that
+  :func:`~arango_query_core.nl.providers.split_system_for_anthropic_cache` splits at.
+* **Names are validated when built.** Predicate names, namespaces and
+  ``Class.property`` entries that are not plain names raise :class:`ValueError`, so
+  they never reach the prompt.
+
+Checking that the model *used* a declared predicate is language-specific and stays
+with the adapter or a host :class:`~arango_query_core.nl.postconditions.Postcondition`.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .grounding import _CONTROL_CHARS_RE, _WHITESPACE_RUN_RE
+
+__all__ = [
+    "FACTS_HEADER",
+    "HOST_HEADER",
+    "HOST_RULE",
+    "LINE_MAX",
+    "RULES_HEADER",
+    "HostExtensions",
+    "HostPredicate",
+    "PropertyFact",
+    "host_prompt_section",
+]
+
+HOST_HEADER = "## What this engine accepts beyond the rules above"
+HOST_RULE = (
+    "These predicates are allowed in addition to the rules above, and only on the "
+    "properties listed for each. Everything the rules above forbid stays forbidden."
+)
+"""The one fixed sentence: the section adds to the grammar, never overrides it."""
+RULES_HEADER = "## Limits this engine adds to the rules above"
+FACTS_HEADER = "## Facts about properties"
+
+LINE_MAX = 600
+"""Cap on one piece of host prose. Host prose is a sentence or two, so the cap is
+larger than a grounding label's (200), which cut a predicate's meaning short."""
+
+_NAME_RE = re.compile(r"^[A-Za-z_][\w-]*(?::[A-Za-z_][\w-]*)?$")
+"""A plain or prefixed name, e.g. ``ex:textMatch``."""
+_PROPERTY_RE = re.compile(r"^[A-Za-z_][\w-]*\.[A-Za-z_][\w-]*$")
+"""A ``Class.property`` name."""
+_IRI_FORBIDDEN = frozenset('<>"{}|^`\\ \t\r\n')
+_HASH_RUN_RE = re.compile(r"#{2,}")
+
+
+def _clean(text: str) -> str:
+    """One line of host prose that cannot open a prompt section.
+
+    Control characters and whitespace runs collapse to one space (the rule
+    ``grounding._sanitize_label`` applies to labels), runs of ``#`` collapse to one
+    so no heading or ``## Examples`` marker survives, and the result is capped at
+    :data:`LINE_MAX`. Clean single-line prose without ``##`` passes through unchanged.
+    """
+    cleaned = _WHITESPACE_RUN_RE.sub(" ", _CONTROL_CHARS_RE.sub(" ", text))
+    return _HASH_RUN_RE.sub("#", cleaned).strip()[:LINE_MAX].rstrip()
+
+
+@dataclass(frozen=True)
+class HostPredicate:
+    """A predicate the host's engine accepts in addition to the language."""
+
+    name: str
+    """As the model writes it, e.g. ``ex:textMatch``."""
+    iri: str
+    """The namespace the name's prefix stands for, for the PREFIX line; ``""`` when the
+    name has no prefix."""
+    meaning: str
+    """One sentence, in the host's words."""
+    usage: str
+    """One example in the target language. It may span lines; each line is cleaned."""
+    applies_to: tuple[str, ...] = ()
+    """``Class.property`` names it may be used on. Empty means it is offered nowhere,
+    and a predicate offered nowhere is left out of the prompt."""
+    instead_of: str = ""
+    """What not to write instead, e.g. "an exact = comparison on these properties"."""
+    restrictions: tuple[str, ...] = ()
+    """Where the host's engine refuses it, one short clause each, e.g. "inside OPTIONAL"."""
+
+    def __post_init__(self) -> None:
+        if not _NAME_RE.match(self.name):
+            raise ValueError(f"host predicate name {self.name!r} is not a plain or prefixed name")
+        if ":" in self.name and not self.iri:
+            raise ValueError(f"host predicate {self.name!r} has a prefix but no namespace iri")
+        if any(ch in _IRI_FORBIDDEN for ch in self.iri):
+            raise ValueError(f"host predicate {self.name!r}: namespace iri {self.iri!r} is malformed")
+        bad = [p for p in self.applies_to if not _PROPERTY_RE.match(p)]
+        if bad:
+            raise ValueError(f"host predicate {self.name!r}: not Class.property names: {bad}")
+        if not _clean(self.meaning) or not _clean(self.usage):
+            raise ValueError(f"host predicate {self.name!r} needs a meaning and a usage example")
+
+    def prompt_lines(self) -> list[str]:
+        """The predicate's lines in the section."""
+        prefix = self.name.split(":", 1)[0] if ":" in self.name else ""
+        lines = [f"- {self.name} — {_clean(self.meaning)}"]
+        if prefix:
+            lines.append(f"  Declare it with: PREFIX {prefix}: <{self.iri}>")
+        lines.append(f"  Use it only on: {', '.join(self.applies_to)}")
+        instead_of = _clean(self.instead_of)
+        if instead_of:
+            lines.append(f"  On those properties use it instead of {instead_of}.")
+        restrictions = [r for r in map(_clean, self.restrictions) if r]
+        if restrictions:
+            lines.append("  Refused: " + "; ".join(restrictions) + ".")
+        lines.append("  Example:")
+        lines += [f"    {row}" for row in map(_clean, self.usage.splitlines()) if row]
+        return lines
+
+
+@dataclass(frozen=True)
+class PropertyFact:
+    """Facts about one property. ``None`` or ``""`` means "not declared" and renders nothing."""
+
+    entity: str
+    property: str
+    type: str = ""
+    """The value's datatype in the host's words, e.g. ``date``."""
+    required: bool | None = None
+    """Whether every entity has the property."""
+    description: str = ""
+    """What the property means."""
+    orderable: bool | None = None
+    """Whether the host's engine may sort or deduplicate on it."""
+
+    def __post_init__(self) -> None:
+        if not _PROPERTY_RE.match(f"{self.entity}.{self.property}"):
+            raise ValueError(f"property fact {self.entity!r}.{self.property!r} is not a Class.property name")
+
+    def line(self) -> str:
+        """The fact's line in the section; ``""`` when it declares nothing."""
+        parts = []
+        type_ = _clean(self.type)
+        if type_:
+            parts.append(f"type {type_}")
+        if self.required is not None:
+            parts.append("always present" if self.required else "may be missing")
+        if self.orderable is not None:
+            parts.append(
+                "may be sorted or deduplicated" if self.orderable else "may not be sorted or deduplicated"
+            )
+        description = _clean(self.description)
+        if description:
+            parts.append(description)
+        return f"- {self.entity}.{self.property}: " + "; ".join(parts) if parts else ""
+
+
+@dataclass(frozen=True)
+class HostExtensions:
+    """What the host's engine accepts beyond the target language."""
+
+    predicates: tuple[HostPredicate, ...] = ()
+    properties: tuple[PropertyFact, ...] = ()
+    rules: tuple[str, ...] = ()
+    """Limits the host's engine adds that are not about one property, one sentence each."""
+
+    @property
+    def empty(self) -> bool:
+        """True when nothing would render."""
+        return (
+            not any(p.applies_to for p in self.predicates)
+            and not any(f.line() for f in self.properties)
+            and not any(_clean(r) for r in self.rules)
+        )
+
+
+def host_prompt_section(ext: HostExtensions | None) -> str:
+    """The system-prompt section for *ext*; ``""`` when it declares nothing that renders.
+
+    Blocks, each present only when it has content: the offered predicates under
+    :data:`HOST_HEADER` with :data:`HOST_RULE`, then the rules under
+    :data:`RULES_HEADER`, then the property facts under :data:`FACTS_HEADER`.
+    """
+    if ext is None or ext.empty:
+        return ""
+    blocks: list[str] = []
+    offered = [p for p in ext.predicates if p.applies_to]
+    if offered:
+        lines = [HOST_HEADER, HOST_RULE]
+        for pred in offered:
+            lines += pred.prompt_lines()
+        blocks.append("\n".join(lines))
+    rules = [f"- {r}" for r in map(_clean, ext.rules) if r]
+    if rules:
+        blocks.append("\n".join([RULES_HEADER, *rules]))
+    facts = [line for line in (f.line() for f in ext.properties) if line]
+    if facts:
+        blocks.append("\n".join([FACTS_HEADER, *facts]))
+    return "\n\n".join(blocks)

{arango_query_core-0.2.6 → arango_query_core-0.2.8}/arango_query_core/nl/postconditions.py

@@ -12,8 +12,8 @@ a required filter. No syntactic check sees it and no human sees it in a demo.
 
 A postcondition is a caller-supplied invariant. It rides the *same* retry
 budget as parse and translate: the model is told the rule up front (via
-:meth:`Postcondition.prompt_section`, rendered once into the cacheable system
-prefix), and a violation is fed back into the next prompt exactly like a
+:meth:`Postcondition.prompt_section`, rendered once at the end of the system
+prompt), and a violation is fed back into the next prompt exactly like a
 validation failure — so the loop gets a chance to *correct* the query rather
 than just reject it, and fails closed when the budget is spent — unless a
 candidate drew only a *soft* violation (``PostconditionViolation.soft``), in
@@ -167,9 +167,11 @@ def postcondition_prompt_sections(
 ) -> list[str]:
     """Collect non-empty ``prompt_section()`` output, in caller order.
 
-    Rendered once into the cacheable system prefix by the engine, so a check
-    that raises here (a broken ``prompt_section``) is skipped rather than
-    aborting the whole generation.
+    Rendered once, at the end of the system prompt, by the engine. When the
+    prompt has an ``## Examples`` section the sections fall after
+    :func:`~arango_query_core.nl.providers.split_system_for_anthropic_cache`'s
+    split, in the uncached suffix. A check that raises here (a broken
+    ``prompt_section``) is skipped rather than aborting the whole generation.
     """
     if not postconditions:
         return []

{arango_query_core-0.2.6 → arango_query_core-0.2.8}/docs/PRD.md

@@ -122,10 +122,11 @@ to prevent a three-way fork.
 | `exec` | `AqlExecutor` protocol, `safe_execute` (bind-var reference checking), `explain_aql` |
 | `extensions` | `ExtensionRegistry` / `ExtensionPolicy` for `arango.*` extension functions |
 | `errors` | `CoreError` shared base |
-| `nl.engine` | `NLQueryEngine` — prompt assembly, few-shot retrieval, provider call, generate→validate→repair loop; `NLResult`. The query is the first fenced block anywhere in a response (prose around it is ignored), else the bare response. An adapter's optional `normalize` seam repairs each candidate before validation. `generate(user_hint=...)` appends a caller hint to the first user message only, leaving the cacheable system prefix alone. With `retry_provider_errors=True`, a provider call that raises uses one attempt of the budget (`NLResult.provider_errors`), and the last error is re-raised only if no attempt returned a response; the default propagates the first error. |
+| `nl.engine` | `NLQueryEngine` — prompt assembly, few-shot retrieval, provider call, generate→validate→repair loop; `NLResult`. The query is the first fenced block anywhere in a response (prose around it is ignored), else the bare response. An adapter's optional `normalize` seam repairs each candidate before validation. `generate(user_hint=...)` appends a caller hint to the first user message only, leaving the cacheable system prefix alone. `generate(context=...)` places a per-request fact (such as the date relative words are counted from) after the question on every attempt, repairs included, cleaned to one line of at most 600 characters; it never reaches the system prompt, retrieval or postconditions, and empty means a byte-identical request. With `retry_provider_errors=True`, a provider call that raises uses one attempt of the budget (`NLResult.provider_errors`), and the last error is re-raised only if no attempt returned a response; the default propagates the first error. An optional `host_extensions` renders `nl.host`'s section straight after the grammar section, inside the cacheable prefix; unset or empty, the system prompt is unchanged. |
 | `nl.providers` | `LLMProvider` protocol; OpenAI / OpenRouter / Anthropic implementations (Anthropic with prompt-cache system-block splitting); env-driven `get_llm_provider` |
 | `nl.fewshot` | `FewShotIndex` over `(question, query)` pairs (legacy corpus keys accepted); `BM25Retriever` (rank_bm25, `nl` extra) and `DenseRetriever` (sentence-transformers, `dense` extra), selected via `mode="bm25"\|"dense"\|"auto"`; `cached_few_shot_index` memoizes the expensive dense build |
 | `nl.grounding` | Seam 6/7 retrieval: `LabelIndex`/`GroundedEntity` (entity grounding) and `PredicateIndex`/`GroundedPredicate` (predicate/schema-convention grounding, renders IRI local names not labels), sharing one token-substring scorer |
+| `nl.host` | `HostExtensions` (`HostPredicate`, `PropertyFact`, `rules`) and `host_prompt_section` — what a host's engine accepts beyond the target language (a registered predicate, per-property facts, its own limits), rendered as one system-prompt section that adds to the grammar and never lifts its rules. Host prose is one line, capped, and cannot open a section or carry the `## Examples` cache marker |
 | `nl.pathindex` | Seam 8: `ClassPathIndex`/`ClassPath` — bounded shortest predicate paths between two seam-6/7-anchored classes over the TBox's class-connectivity graph |
 | `nl.postconditions` | Caller-supplied semantic invariants (`Postcondition`, `PostconditionContext`, `PostconditionViolation`, `run_postconditions`) enforced through the engine's own retry budget; fails closed on exhaustion, unless a valid candidate drew only a soft violation (`PostconditionViolation.soft`); the first such candidate is returned, with the violation on `NLResult.postcondition` |
 | `nl.synthbank` | `SHAPE_CATALOG`/`ShapeTemplate` — 9 ontology-agnostic compositional query-shape templates for synthetic few-shot bank generation |

{arango_query_core-0.2.6 → arango_query_core-0.2.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arango-query-core"
-version = "0.2.6"
+version = "0.2.8"
 description = "Shared conceptual-model and NL substrate for ArangoDB query transpilers (arango-cypher-py, arango-sparql-py)"
 readme = "README.md"
 license = { file = "LICENSE" }