xp-libs-analytics 0.4.0__tar.gz

xp_libs_analytics-0.4.0/.coveragerc

@@ -0,0 +1,6 @@
+[run]
+branch = True
+source = xp_libs_analytics
+
+[report]
+show_missing = True

xp_libs_analytics-0.4.0/.dockerignore

@@ -0,0 +1,11 @@
+.venv*
+.git
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.hypothesis
+__pycache__
+dist
+build
+docs/evidence
+evals/agent_skill/reports

xp_libs_analytics-0.4.0/.github/CODEOWNERS.template

@@ -0,0 +1,7 @@
+# Rename to .github/CODEOWNERS and replace @ORG/TEAM with real authorized users/teams.
+# Do not leave a fake owner file in the active CODEOWNERS path.
+/src/xp_libs_analytics/engine/ @ORG/TEAM
+/src/xp_libs_analytics/policy/ @ORG/TEAM
+/src/xp_libs_analytics/errors/catalog.json @ORG/TEAM
+/.github/workflows/ @ORG/TEAM
+/pyproject.toml @ORG/TEAM

xp_libs_analytics-0.4.0/.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    # Refresh the Inspect AI storage stack together. Keep security updates eligible.
+    ignore:
+      - dependency-name: aiobotocore
+        update-types: ['version-update:semver-major', 'version-update:semver-minor', 'version-update:semver-patch']
+      - dependency-name: boto3
+        update-types: ['version-update:semver-major', 'version-update:semver-minor', 'version-update:semver-patch']
+      - dependency-name: botocore
+        update-types: ['version-update:semver-major', 'version-update:semver-minor', 'version-update:semver-patch']
+      - dependency-name: fsspec
+        update-types: ['version-update:semver-major', 'version-update:semver-minor', 'version-update:semver-patch']
+      - dependency-name: python-dateutil
+        update-types: ['version-update:semver-major', 'version-update:semver-minor', 'version-update:semver-patch']
+      - dependency-name: s3fs
+        update-types: ['version-update:semver-major', 'version-update:semver-minor', 'version-update:semver-patch']
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      codeql:
+        patterns: ['github/codeql-action*']
+      artifacts:
+        patterns: ['actions/upload-artifact', 'actions/download-artifact']

xp_libs_analytics-0.4.0/.github/pull_request_template.md

@@ -0,0 +1,26 @@
+## Description and motivation
+
+## Affected contracts / V1 operators / public API
+- [ ] Updated `QUERY_LANGUAGE_V1.md` / semantic version decision if applicable
+- [ ] New/changed error codes and catalog parity (single `catalog.json`)
+- [ ] Updated agent skill and machine-valid examples if behavior changed
+
+## Safety and threat model
+- [ ] No unsafe SQL/Python/UDF/network/file access introduced
+- [ ] Authorization and handle ownership unchanged or explicitly reviewed
+- [ ] Resource budgets and input/output leakage considered
+- [ ] No real records/secrets in fixtures, logs or artifacts
+
+## Testing evidence (actual)
+- [ ] Positive and negative cases
+- [ ] Penetration/security regression for affected boundary
+- [ ] Property/fuzz invariants
+- [ ] FastMCP client tests if MCP changed
+- [ ] Line and branch coverage thresholds
+- [ ] Fresh wheel install/import/skill/catalog smoke
+
+## Performance and operational impact
+
+## Backward compatibility / migration
+
+## Reviewer notes / release risk

xp_libs_analytics-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches: [main]
+  merge_group:
+permissions:
+  contents: read
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  quality:
+    name: lint-and-type
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -c requirements-lock.txt -e '.[dev,mcp,agent-eval]'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy src/xp_libs_analytics
+  tests:
+    name: tests (${{ matrix.os }}, ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -c requirements-lock.txt -e '.[dev,mcp,agent-eval]'
+      - run: python -m pytest --cov=xp_libs_analytics --cov=evals.agent_skill --cov-branch --cov-report=json --cov-report=xml --cov-fail-under=90 --junitxml=junit.xml
+      - run: python scripts/check_critical_coverage.py coverage.json
+      - run: python examples/run_examples.py --lint-only
+      - run: python examples/run_examples.py --all
+      - run: python scripts/resource_probe.py
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: evidence-${{ matrix.os }}-${{ matrix.python }}
+          path: |
+            junit.xml
+            coverage.json
+            coverage.xml
+            docs/evidence/resource-probes.json
+          retention-days: 7
+  package:
+    name: build-smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -c requirements-lock.txt build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - run: python scripts/verify_dist.py
+  benchmark:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -c requirements-lock.txt -e '.[dev]'
+      - run: python scripts/benchmark.py
+      - run: python scripts/benchmark_matching.py --trusted-in-process
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: benchmarks
+          path: |
+            docs/evidence/benchmarks.json
+            docs/evidence/matching-benchmarks-v0.4.json
+          retention-days: 7

xp_libs_analytics-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,91 @@
+name: Release
+on:
+  push:
+    tags: ['v*']
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: '3.12'
+      - name: Verify version tag
+        run: |
+          python - <<'PY'
+          import os, tomllib
+          from pathlib import Path
+          version = tomllib.loads(Path('pyproject.toml').read_text())['project']['version']
+          assert version != '0.0.0' and os.environ['GITHUB_REF_NAME'] == f'v{version}'
+          PY
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -c requirements-lock.txt -e '.[dev,mcp,agent-eval]'
+      - run: ruff check . && ruff format --check . && mypy src/xp_libs_analytics
+      - run: python -m pytest --cov=xp_libs_analytics --cov=evals.agent_skill --cov-branch --cov-report=json --cov-fail-under=90
+      - run: python scripts/check_critical_coverage.py coverage.json
+      - run: python -m pip_audit
+      - run: python scripts/inventory.py
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - run: python scripts/verify_dist.py
+      - run: sha256sum dist/* > SHA256SUMS
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: release-artifacts
+          path: |
+            dist/*
+            SHA256SUMS
+            scripts/smoke.py
+            docs/evidence/sbom.json
+          retention-days: 30
+  testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release-artifacts
+      - run: sha256sum -c SHA256SUMS
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+  verify-testpypi:
+    needs: testpypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release-artifacts
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: '3.12'
+      - run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          python -m pip download --no-deps --index-url https://test.pypi.org/simple "xp-libs-analytics==$VERSION" --dest fetched
+          cmp dist/*.whl fetched/*.whl
+          sha256sum -c SHA256SUMS
+          python -m venv smoke
+          smoke/bin/python -m pip install fetched/*.whl
+          smoke/bin/python scripts/smoke.py
+          smoke/bin/xp-libs-analytics --help
+  pypi:
+    needs: verify-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release-artifacts
+      - run: sha256sum -c SHA256SUMS
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1

xp_libs_analytics-0.4.0/.github/workflows/security.yml

@@ -0,0 +1,49 @@
+name: Security
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: '17 8 * * 1'
+permissions:
+  contents: read
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: '3.12'
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -c requirements-lock.txt -e '.[dev,mcp,agent-eval]'
+      - run: python -m pip_audit
+  codeql:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066 # v4
+        with:
+          languages: python
+      - uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066 # v4
+  dependency-review:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
+        with:
+          fail-on-severity: high

xp_libs_analytics-0.4.0/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.hypothesis/
+.coverage*
+!.coveragerc
+coverage.xml
+coverage.json
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+.venv-smoke/
+evals/agent_skill/reports/*
+!evals/agent_skill/reports/.gitignore
+*.log
+.env
+.env.*
+!.env.example
+docs/evidence/*.xml
+docs/evidence/*.txt

xp_libs_analytics-0.4.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+
+## 0.4.0 — Bounded string and fuzzy query matching
+
+- Extend analytics.query/v1 with explicit Unicode/trim/casefold normalization, not_contains, Unicode word boundaries, LIKE/ILIKE, Rust regex and exhaustive RapidFuzz ratio/wratio/token_sort predicates.
+- Add strict disjoint multi-field match nodes shared by filters and every conditional aggregate; preserve typed datetime/numeric comparisons, all 20 aggregates, grouping/HAVING/ordering and temporal semantics.
+- Prevalidate Rust syntax with Polars, enforce authorized fields and candidate/comparison/normalization/expanded-AST budgets, and use native Polars membership without Python row UDFs or persistent value caches.
+- Default regex/fuzzy/diagnostics to OS-limited workers. Rank optional privacy-cleared matching evidence independently of aggregates; raw values require explicit host and field disclosure policy.
+- Add 11 MATCH_* canonical error distinctions (73 total), preserve catalog-only messages, and explicitly reject entity/alias/identity inference.
+- Add 11 runnable YAML examples (28 total), a full matching resource/skill, deterministic security/property/integration tests and 11 optional agent evaluation recipes (116 total). Live model ID and endpoint are runtime-only.
+- Require MIT-licensed RapidFuzz >=3.14.6,<3.15; preserve optional FastMCP/Inspect separation. Keep the 0.3.0 named registry API, without reintroducing legacy dataset handles or a search prerequisite.
+
+
+## 0.3.0 — Named context-local dataset sources (breaking)
+
+- Replace dataset.handle with dataset.name and query_yaml(handle, text) with query_yaml(text). No handle-based compatibility API remains.
+- Add DatasetRegistry, explicit register_records(name, records), atomic replace_records, list_datasets, unregister_dataset, independent create_context namespaces and safe closure.
+- Keep opaque IDs internal; snapshot leases retain running queries through replacement/removal and keep retired storage charged until safe reclamation. Revisions do not repeat within a context; expected_revision rejects stale writes.
+- MCP adds analytics_list_datasets, requires names for describe/uploads/unregister, removes analytics_release_dataset, and supports trusted context_resolver. Authenticated policy changes retain namespace identity while rechecking permissions.
+- Replace DATA_HANDLE_UNKNOWN / DATA_HANDLE_EXPIRED / RESOURCE_HANDLES_LIMIT with DATASET_NAME_UNKNOWN / DATASET_SNAPSHOT_STALE / RESOURCE_DATASETS_LIMIT. Add DATASET_NAME_DUPLICATE and DATASET_NAME_INVALID: 62 canonical codes total.
+- Update every YAML example, schema, product skill, evaluator and developer reference. Reserve register_stream with explicit unsupported-feature rejection; no streaming implementation.
+
+## 0.2.0 — local build
+
+- Rename the distribution/CLI to `xp-libs-analytics` and imports to `xp_libs_analytics`.
+- Preserve the independently usable YAML/analytics core and optional FastMCP adapter; add a bring-your-own-MCP example and import-isolation regression test.
+- Add optional Inspect AI agent evaluations, deterministic scenario/oracle contracts, real MCP recovery seeding, semantic/result scorers, memory-only Inspect logs, sanitized reporting and skill/baseline comparison.
+- Add 105 synthetic scenarios and offline/live test separation. Live results are recorded separately from deterministic test evidence.
+
+## 0.1.0 — local build
+
+- Implement JSON/NDJSON/mapping admission, full-snapshot discovery, immutable owner-scoped handles, field visibility and shared quotas.
+- Implement restricted YAML, strict discriminated Pydantic models, semantic authorization, immutable cost plans, and fixed Polars compilation.
+- Support all 19 predicate/logical operators and 20 aggregates, UTC ranges, tumbling/sliding windows, HAVING, stable sorting, and quality evidence.
+- Preserve the 60-code canonical catalog; include structured errors and YAML locations.
+- Add optional standalone FastMCP tools, upload policy, launcher/authenticated-host identity, and packaged skill/examples.
+- Add independent oracle, property/security/agent-workflow tests, real MCP/stdio integration, OS-limited workers, benchmarks, distribution smoke and release workflows.
+- Public GitHub/TestPyPI/PyPI release is not configured or performed.

xp_libs_analytics-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Use Python 3.12+ and install `-c requirements-lock.txt -e '.[dev,mcp]'`. Run the verification commands in README before submitting a PR. Tests use synthetic fixtures and an independent Python oracle. Every YAML example must execute through the restricted parser, strict AST, semantic planner and backend.
+
+Preserve the [language](docs/query-language.md), [parser boundary](docs/yaml-security.md), and [error contract](docs/errors.md). Messages live exclusively in `src/xp_libs_analytics/errors/catalog.json`; code additions require enum, tests, and changelog changes. Semantic changes require schema/fixture review and a version decision.
+
+PR CI enforces lint, format, strict mypy, >=90% aggregate coverage and >=95% branch coverage for each critical module. Branchless critical modules require >=95% statement coverage. Run security and actual FastMCP-client integration tests.
+
+Original contributions are MIT licensed. Preserve third-party notices. Never put credentials, real private records, or sensitive schemas in code, issues, fixtures, logs or CI artifacts. See SECURITY.md for disclosure and docs/releasing.md for protected OIDC publishing.

xp_libs_analytics-0.4.0/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.12-slim
+ENV PYTHONUNBUFFERED=1 POLARS_MAX_THREADS=2
+WORKDIR /app
+COPY . /app
+RUN python -m pip install --no-cache-dir --upgrade 'pip>=26.3' && python -m pip install --no-cache-dir -c requirements-lock.txt '.[mcp]' && useradd --uid 10001 --create-home analytics
+USER 10001
+ENTRYPOINT ["xp-libs-analytics"]

xp_libs_analytics-0.4.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Rodrigo Alves
+Copyright (c) 2026 Generic In-Memory Analytics contributors
+
+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.

xp_libs_analytics-0.4.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: xp-libs-analytics
+Version: 0.4.0
+Summary: Schema-on-read, in-memory analytics for agent-generated YAML queries
+Project-URL: Source, https://github.com/rrodrigoa/xp-libs-analytics
+Project-URL: Issues, https://github.com/rrodrigoa/xp-libs-analytics/issues
+Project-URL: Documentation, https://github.com/rrodrigoa/xp-libs-analytics/blob/main/README.md
+Author: Generic In-Memory Analytics contributors
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Keywords: agents,analytics,in-memory,json,mcp,polars,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.12
+Requires-Dist: polars<2.2,>=2.1
+Requires-Dist: pydantic<3,>=2.14
+Requires-Dist: pyyaml<7,>=6.0.2
+Requires-Dist: rapidfuzz<3.15,>=3.14.6
+Requires-Dist: tzdata>=2025.2; sys_platform == 'win32'
+Provides-Extra: agent-eval
+Requires-Dist: fastmcp<4.2,>=4.1.6; extra == 'agent-eval'
+Requires-Dist: inspect-ai==0.3.287; extra == 'agent-eval'
+Requires-Dist: openai==3.46.0; extra == 'agent-eval'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: mypy>=1.15; extra == 'dev'
+Requires-Dist: pip-audit>=2.8; extra == 'dev'
+Requires-Dist: psutil>=7; extra == 'dev'
+Requires-Dist: pytest-asyncio<3,>=1; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp<4.2,>=4.1.6; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# XP Libs Analytics
+
+A Python library for bounded, in-memory snapshot analytics over JSON records with unknown, heterogeneous schemas. Queries are restricted YAML, validated with strict Pydantic models and compiled to fixed Polars expressions. The optional standalone FastMCP adapter supplies tools, an agent skill, and 28 read-only query examples.
+
+Python 3.12+ · MIT · Import: `xp_libs_analytics` · Distribution: `xp-libs-analytics`
+
+The distribution uses hyphens for package indexes and `pip`; Python imports use underscores because hyphens are not valid identifiers. The previous `agent_analytics` import and `agent-analytics-mcp` distribution/command have been replaced.
+
+## Install and run
+
+From this checkout:
+
+```sh
+python -m pip install .
+python -m pip install '.[mcp]'    # optional MCP adapter
+```
+
+```python
+from xp_libs_analytics import AnalyticsEngine
+
+engine = AnalyticsEngine()
+my_data = [{"value": 10}, {"value": 20}, {"value": None}, {}]
+engine.register_records(name="observations", records=my_data)
+engine.register_records("events", [{"kind": "created"}])
+print(engine.list_datasets())
+
+query_yaml = """version: analytics.query/v1
+dataset:
+  name: observations
+aggregations:
+  - {op: count, as: records}
+  - {op: avg, field: /value, as: mean}
+  - {op: missing_count, field: /value, as: missing}
+"""
+result = engine.query_yaml(query_yaml)
+print(result["rows"])  # [{"records": 4, "mean": 15.0, "missing": 1}]
+
+# Atomic publication: future queries resolve the new snapshot.
+engine.replace_records("observations", [{"value": 30}])
+engine.unregister_dataset("events")
+```
+
+Logical dataset names are symbolic references, independent of Python variable names, paths and opaque internal snapshot IDs. Registering a duplicate name fails; use `replace_records` to update it. Each query resolves exactly one immutable snapshot. Running queries retain their resolved snapshot through replacement, unregister or context closure; storage remains charged until their leases are released. Result metadata reports the logical name and resolved revision. Revisions increase within a context and can have gaps; re-registering a removed name never reuses an old revision. Optional `expected_revision` on replacement/unregister rejects stale updates.
+
+For independent namespaces in one application:
+
+```python
+with engine.create_context() as ctx:
+    ctx.register_records("observations", [{"value": 7}])
+    print(ctx.query_yaml(query_yaml)["rows"])
+# ctx closes and removes its bindings; engine's observations remain independent.
+```
+
+Names use 1–64 ASCII letters, digits, underscores or hyphens, starting with a letter. Unknown names return `DATASET_NAME_UNKNOWN` without revealing other contexts. Expired snapshots and stale expected revisions return `DATASET_SNAPSHOT_STALE`. Expired bindings are omitted from discovery; replace or unregister them to reuse resources. `register_stream(name, source)` is reserved and always rejects with `QUERY_UNSUPPORTED_FEATURE`; streaming is not implemented.
+
+Input accepts JSON objects, arrays of objects, NDJSON, or Python iterables of JSON mappings. Admission copies records into immutable owner-scoped snapshots. Schema discovery examines every admitted record and returns no raw samples. Fields use RFC 6901 pointers; `/a~1b` addresses key `a/b`. Arrays remain opaque.
+
+## Query features
+
+| Feature | Supported V1 behavior |
+|---|---|
+| Predicates | 22 typed leaf operators; nested `and`, `or`, `not`; multi-field `match`; three-valued null logic |
+| Aggregates | 20 count, distinct, numeric, linear quantile, sample variance, and conditional operations |
+| Grouping | Up to four scalar dimensions; missing and explicit null groups remain separate |
+| Time | Explicit RFC3339/epoch casts, absolute or relative UTC ranges, epoch-aligned tumbling/sliding windows |
+| Results | HAVING, stable sorting, limit/truncation, strict JSON and quality/provenance evidence |
+| Errors | 73 catalog codes, one canonical packaged message catalog, safe diagnostic locations |
+
+See the [query language](docs/query-language.md), [examples](examples/README.md), and [agent skill](skills/generic-analytics/SKILL.md). `NO_DATA` reports absent matching observations. `INSUFFICIENT_DATA` applies the host's minimum sample policy. Unknown sampling cadence yields `coverage: UNKNOWN`; counts do not imply duration.
+
+Mixed scalar types require explicit casts. Boolean values are never numeric. Null/missing values are excluded from numeric samples; cast failures configured as null are counted and warned. Integer sums detect overflow. Float statistics reject integer samples beyond exact float64 integer precision. V1 does not offer exact decimal analytics. String matching defaults to case-sensitive literal semantics, with explicit Unicode/case normalization, word, LIKE/ILIKE, bounded Rust regex and RapidFuzz similarity options. See the [matching contract](docs/string-matching.md).
+
+## Matching observed values
+
+```yaml
+version: analytics.query/v1
+dataset: {name: observations}
+filters:
+  - match:
+      fields: [/actor/name, /actor/email]
+      patterns:
+        - {op: word, value: Peter}
+        - {op: fuzzy, value: Pter, algorithm: ratio, min_score: 85}
+      normalization: {case_sensitive: false, unicode: nfkc, trim: true}
+      mode: any
+aggregations:
+  - {op: count, as: matching_records}
+options:
+  matching_details: {include: true, top_values: 5, include_raw_values: false}
+```
+
+Discover paths before authoring this query. Every eligible distinct fuzzy candidate is evaluated within host budgets; limit/top_values never approximate an aggregate. A record contributes once even when multiple fields/rules match. Diagnostics are redacted by default; raw display requires host and field permissions. Similarity does not infer identities, merge people or expand nicknames. All new predicates also work in conditional aggregates and with existing grouping, HAVING and windows. Examples 18–28 are runnable against synthetic matching data. RapidFuzz is a required MIT-licensed core dependency; FastMCP and Inspect AI remain optional.
+
+Regex/fuzzy and requested matching diagnostics automatically use the bounded worker by default. Keep the documented Windows __main__ guard. Trusted benchmarking can explicitly disable force_matching_isolation; untrusted hosts should retain it. No search API or separate matching tools are needed.
+
+## Bounds and deployment
+
+Defaults are declared in `Limits` and returned by `engine.capabilities()`: 8 MiB input, 100,000 rows, 256 paths, depth 12, 128 KiB per record, eight named bindings per context and eight active snapshots per principal in a shared store, 64 MiB admitted storage per store, 900-second leases, 64 KiB YAML, 10,000 groups/windows/distinct values, overlap at most 12, 500 result rows and 1 MiB results. Queries share owner quotas within a store (120/minute, two concurrent executions). Hosts may tighten limits; requests cannot change them.
+
+The default SDK runs inside a **trusted host process**. Use `AnalyticsEngine(isolated=True)` for untrusted execution: a fresh worker has a 15-second wall deadline, CPU ceiling and 1 GiB absolute memory ceiling (POSIX address-space rlimits / Windows Job Object commit limits). Linux Polars needs native virtual mappings beyond 512 MiB even for small numeric queries; measured additional RSS is much lower. Use a `__main__` guard around executable application entry points on Windows. Parsing and bounded snapshot admission remain in the host process. Containers additionally control network/filesystem privileges; see [security](SECURITY.md) and [architecture](docs/architecture.md).
+
+V1 evaluates one snapshot per query. It rejects joins, unions, continuous queries, external sources/sinks, SQL, UDFs, unbounded regex and executable expressions. Dense windows are supported only without grouping, with a bounded grid. In-flight executions keep their admitted snapshot; unregister blocks subsequent name resolution. Foreign-context names and unknown names receive the same unknown-name error. Scope failures receive ACCESS_DENIED.
+
+## MCP
+
+The YAML parser, typed query models, semantic planner and execution engine belong to the core library. They do not import FastMCP or Inspect AI. A developer can expose the SDK using any MCP implementation or another transport:
+
+```python
+from xp_libs_analytics import AnalyticsEngine
+
+# Construct per trusted application principal; do not accept identity from agent arguments.
+analytics = AnalyticsEngine()
+analytics.register_records("observations", [{"value": 2}, {"value": 4}])
+
+
+def query_tool(query_yaml: str) -> dict:
+    return analytics.query_yaml(query_yaml)
+
+
+def validation_tool(query_yaml: str) -> dict:
+    return analytics.validate_query(query_yaml)
+```
+
+Register those callables with your chosen server. Select the authorized execution context and identity in the host, enforce transport authentication, and use `isolated=True` for untrusted execution. The bundled FastMCP adapter is an optional convenience layer.
+
+```sh
+xp-libs-analytics --help
+xp-libs-analytics                 # stdio; uploads disabled
+xp-libs-analytics --allow-uploads # bounded local uploads
+```
+
+Tools: `analytics_capabilities`, `analytics_list_datasets`, `analytics_load_json`, `analytics_describe`, `analytics_validate_query`, `analytics_explain_query`, `analytics_query`, `analytics_unregister_dataset`, `analytics_error_info`. Query tools accept `query_yaml: str`. Core imports do not load FastMCP.
+
+The local stdio server inherits its launcher's authority; one process is one local context. The default backend uses isolated workers. HTTP access fails closed unless a host supplies an authenticated `principal_resolver` and configures FastMCP transport authentication. A host-supplied `engine` deliberately selects that engine's context for local use. Hosted sessions can supply `context_resolver`, a trusted callable returning their authorized engine/context. No tool accepts a context ID or principal. The identity resolver creates distinct namespaces per authenticated principal and reapplies current field/scopes policy per request. The adapter caps cached principal contexts at 128; restarting clears local state. It is not a turnkey public multi-tenant service.
+
+## Development and evidence
+
+Optional real-model evaluations use Inspect AI and the actual MCP adapter. From this checkout, install `python -m pip install -e '.[dev,mcp,agent-eval]'`, then run `python -m evals.agent_skill.cli validate`. Live evaluation accepts the model connection only at execution time; see [evaluation usage](evals/agent_skill/README.md). Normal CI runs offline evaluator tests and excludes live model tests.
+
+```sh
+python -m pip install -c requirements-lock.txt -e '.[dev,mcp,agent-eval]'
+ruff check .
+ruff format --check .
+mypy src/xp_libs_analytics
+pytest --cov=xp_libs_analytics --cov=evals.agent_skill --cov-branch --cov-report=json --cov-report=xml --cov-fail-under=90
+python scripts/check_critical_coverage.py coverage.json
+python examples/run_examples.py --all
+python scripts/resource_probe.py
+python scripts/benchmark.py
+python -m build
+python -m twine check dist/*
+```
+
+[Verification evidence](docs/evidence/verification.md) records actual local tests, coverage, benchmarks, audit and build hashes. GitHub checks, protected environments and TestPyPI/PyPI publication require maintainer configuration; this checkout makes no publication claim. See [releasing](docs/releasing.md).