commons 0.1.0.dev1__py3-none-any.whl

commons/__init__.py

@@ -0,0 +1,8 @@
+"""Build trustworthy data agents.
+
+Give an LLM data, semantic, and context layers to work with, tools for
+querying them, and A/B/C provenance semantics so every answer carries a
+classification as to how much it can be trusted.
+"""
+
+__all__: list[str] = []

commons/_citations.py

@@ -0,0 +1,69 @@
+"""Verifying a quoted citation against a trusted corpus.
+
+The normalization rules and the matching verdicts are a cross-language contract
+pinned by ``tests/shared/citations.json``; change that fixture, not just this
+file. ``pkg-r/R/citations.R`` implements the same contract for R.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+__all__ = ["CorpusEntry", "match_citation", "normalize_citation"]
+
+# The minimum length is a guard, not a tuning knob: a fragment this short can
+# appear in a trusted source by coincidence and must not promote an answer.
+MIN_NORMALIZED_LENGTH = 10
+
+_WHITESPACE = re.compile(r"\s+")
+_EMPHASIS = re.compile(r"[*_`]")
+_SINGLE_QUOTES = re.compile("[\u2018\u2019]")
+_DOUBLE_QUOTES = re.compile("[\u201c\u201d]")
+_DASHES = re.compile("[\u2013\u2014]")
+
+CitationKind = Literal["prose", "definition", "schema"]
+
+
+@dataclass(frozen=True)
+class CorpusEntry:
+    """One trusted passage a citation can be verified against.
+
+    ``label`` is reader-facing and appears in the rendered aside.
+    """
+
+    label: str
+    kind: CitationKind
+    text: str
+
+
+def normalize_citation(text: str) -> str:
+    """Fold the ways a faithful quote can still drift from its source.
+
+    Strips markdown emphasis, folds typographic quotes and dashes to ASCII, and
+    collapses runs of whitespace. Case is deliberately preserved, because
+    matching is case-sensitive.
+    """
+    text = _EMPHASIS.sub("", text)
+    text = _SINGLE_QUOTES.sub("'", text)
+    text = _DOUBLE_QUOTES.sub('"', text)
+    text = _DASHES.sub("-", text)
+    return _WHITESPACE.sub(" ", text).strip()
+
+
+def match_citation(quote: str, corpus: Sequence[CorpusEntry]) -> CorpusEntry | None:
+    """Find the first corpus entry that contains the quote, or None.
+
+    Only the quote is ever verified; a model's explanation of it is not passed
+    here. Corpus order is meaningful, running specific before general, so the
+    first match wins rather than the best one.
+    """
+    needle = normalize_citation(quote)
+    if len(needle) < MIN_NORMALIZED_LENGTH:
+        return None
+    return next(
+        (entry for entry in corpus if needle in normalize_citation(entry.text)),
+        None,
+    )

commons/_provenance.py

@@ -0,0 +1,81 @@
+"""A/B/C provenance: how much an answer can be trusted.
+
+The truth table and the display copy are a cross-language contract pinned by
+``tests/shared/provenance.json``; change that fixture, not just this file.
+``pkg-r/R/provenance.R`` implements the same contract for R.
+"""
+
+from __future__ import annotations
+
+import enum
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+__all__ = ["PROVENANCE_DISPLAY", "ProvenanceDisplay", "Tag", "derive_provenance_tag"]
+
+
+class Tag(enum.StrEnum):
+    """How an answer was produced.
+
+    A and B are set by tools on their results. C is only ever derived: it is
+    what a B becomes when its citation does not verify.
+
+    StrEnum rather than a plain `str, Enum` mixin, which formats as "Tag.A".
+    The tag is written to the commons.provenance.tag span attribute, where R
+    writes the bare letter and a mismatch would corrupt traces silently.
+    """
+
+    A = "A"
+    B = "B"
+    C = "C"
+
+
+@dataclass(frozen=True)
+class ProvenanceDisplay:
+    """The words and styling one tag's pill renders with."""
+
+    label: str
+    icon: str | None
+    body: str
+    pill_class: str
+
+
+PROVENANCE_DISPLAY: dict[Tag, ProvenanceDisplay] = {
+    Tag.A: ProvenanceDisplay(
+        label="Verified answer",
+        icon="trusted-icon.svg",
+        body=(
+            "This answer comes from a governed calculation defined by your data team."
+        ),
+        pill_class="trusted",
+    ),
+    Tag.B: ProvenanceDisplay(
+        label="Cited",
+        icon=None,
+        body="This answer includes supporting text verified against a trusted source.",
+        pill_class="cited",
+    ),
+    Tag.C: ProvenanceDisplay(
+        label="Untrusted",
+        icon="warning-icon.svg",
+        body=(
+            "This answer was not produced by a governed calculation and has "
+            "no verified supporting citation. AI can be wrong."
+        ),
+        pill_class="caution",
+    ),
+}
+
+
+def derive_provenance_tag(tags: Sequence[Tag], verified: bool) -> Tag | None:
+    """Classify one exchange from the tags its tools set.
+
+    A fallback claim remains fallback even when its answer also uses a governed
+    calculation, so its citation verdict takes precedence ("B beats A").
+    Returns ``None`` when no data tool ran, which shows no pill at all.
+    """
+    if Tag.B in tags:
+        return Tag.B if verified else Tag.C
+    if Tag.A in tags:
+        return Tag.A
+    return None

commons-0.1.0.dev1.dist-info/METADATA

@@ -0,0 +1,31 @@
+Metadata-Version: 2.5
+Name: commons
+Version: 0.1.0.dev1
+Summary: AI Agents for Data Analysis
+Project-URL: Homepage, https://github.com/posit-dev/commons
+Project-URL: Issues, https://github.com/posit-dev/commons/issues
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 2 - Pre-Alpha
+Requires-Python: <3.14,>=3.11
+Requires-Dist: chatlas>=0.21.2
+Requires-Dist: duckdb>=1.0
+Requires-Dist: jinja2>=3
+Requires-Dist: pyarrow>=17
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Requires-Dist: raghilda>=0.2
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: tracing
+Requires-Dist: httpx>=0.27; extra == 'tracing'
+Requires-Dist: opentelemetry-exporter-otlp-json-file; extra == 'tracing'
+Requires-Dist: opentelemetry-sdk>=1.39; extra == 'tracing'
+Description-Content-Type: text/markdown
+
+# commons
+
+`commons` is a constructor for trustworthy data agents. Once implemented, this package will give an LLM data, semantic, and context layers to work with, tools for querying them, and A/B/C provenance tags so every answer carries a classification as to its trustworthiness.
+
+**Status: pre-alpha.** The package installs, imports, lints, type-checks, and tests, but exports nothing yet: `commons.__all__` is empty and there is no public API. Python 3.11 or later is required.
+
+Behavior that both implementations must agree on belongs in [`tests/shared/`](https://github.com/posit-dev/commons/tree/main/tests/shared) at the repository root, which that directory's README defines as the authority. The provenance tag rules and display copy are the first behavior governed that way; both suites run those cases.

commons-0.1.0.dev1.dist-info/RECORD

@@ -0,0 +1,8 @@
+commons/__init__.py,sha256=ClGErzI1C7jkP4Dyr0N0u4QM6yyrfljPy6L3P-0MHHI,256
+commons/_citations.py,sha256=oSzcXVxGo4SMLfuARKJs0Q4LMt4-fhdk82Ec62IsdK0,2268
+commons/_provenance.py,sha256=5HqR1Ky8ILP59ltIMC0YYT0bjQTSiqyV_gIpokGEXxU,2423
+commons/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+commons-0.1.0.dev1.dist-info/METADATA,sha256=CW3l-RdvIQ0B9ukRT6k-rUhB5rEloyOW76IbUO46xAQ,1627
+commons-0.1.0.dev1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+commons-0.1.0.dev1.dist-info/licenses/LICENSE.md,sha256=cXVvzpR07jRZuWPH_VAvnN2LOaOEJxI4yrbU0Nl_1fM,1078
+commons-0.1.0.dev1.dist-info/RECORD,,

commons-0.1.0.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

commons-0.1.0.dev1.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Posit Software, PBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.