pretensor 0.1.0__tar.gz

pretensor-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+uv.lock linguist-generated=true

pretensor-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for all files
+* @tensorcarlos

pretensor-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,110 @@
+name: Bug report
+description: Report a reproducible problem with Pretensor.
+title: "bug: <short summary>"
+labels:
+  - bug
+  - triage
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report. Please fill out the fields below so we can reproduce the issue quickly.
+
+        **Security vulnerabilities must not be filed as public issues.** See [SECURITY.md](https://github.com/pretensor-ai/pretensor/blob/main/SECURITY.md) and report privately via [GitHub Security Advisories](https://github.com/pretensor-ai/pretensor/security/advisories/new).
+
+  - type: input
+    id: pretensor-version
+    attributes:
+      label: Pretensor version
+      description: Output of `pretensor --version`.
+      placeholder: "0.1.0aN"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: Output of `python --version`.
+      placeholder: "3.11.x or 3.12.x"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux
+        - macOS
+        - Windows
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: backend
+    attributes:
+      label: Database backend
+      description: Which connector were you using when the bug occurred?
+      options:
+        - PostgreSQL
+        - Snowflake
+        - BigQuery
+        - Not applicable
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: extras
+    attributes:
+      label: Installed extras
+      description: Which pip extras did you install? e.g. `[dev]`, `[snowflake]`, `[bigquery]`, `[e2e]`.
+      placeholder: "[dev]"
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: A minimal, self-contained reproduction. Include the exact commands or code.
+      placeholder: |
+        1. Install with `pip install -e ".[dev]"`
+        2. Run `pretensor index ...`
+        3. Observe ...
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Include full tracebacks and error messages.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Additional logs or context
+      description: Any relevant logs, MCP transcripts, or schema snippets. Redact secrets and personally identifiable data.
+      render: shell
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-submission checks
+      options:
+        - label: I searched existing issues and did not find a duplicate.
+          required: true
+        - label: I confirmed this is not a security vulnerability (those go through Security Advisories).
+          required: true

pretensor-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/pretensor-ai/pretensor/security/advisories/new
+    about: Please report security issues privately through GitHub Security Advisories, not as public issues. See SECURITY.md for details.
+  - name: Ask a question or start a discussion
+    url: https://github.com/pretensor-ai/pretensor/discussions
+    about: Questions, ideas, and general discussion belong in Discussions.

pretensor-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,57 @@
+name: Feature request
+description: Suggest a new capability or enhancement for Pretensor.
+title: "feat: <short summary>"
+labels:
+  - enhancement
+  - triage
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for proposing an improvement. Please describe the problem you're trying to solve before the solution — that lets us evaluate alternatives we may not have considered.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to accomplish, and what's blocking you today? Include concrete use cases where helpful.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the change you have in mind. Include expected CLI, MCP, or API behavior if relevant.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you evaluated and why you discarded them. Leave blank if none.
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      description: Which subsystem does this primarily affect?
+      options:
+        - CLI
+        - MCP server
+        - Connectors (Postgres / Snowflake / BigQuery)
+        - Graph / intelligence
+        - Docs
+        - Build / release
+        - Not sure
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-submission checks
+      options:
+        - label: I searched existing issues and did not find a duplicate.
+          required: true

pretensor-0.1.0/.github/ISSUE_TEMPLATE/schema_report.yml

@@ -0,0 +1,122 @@
+name: Schema doesn't match my database
+description: The knowledge graph is missing or misrepresenting tables, columns, keys, or relationships from your database.
+title: "schema: <what's missing or wrong>"
+labels:
+  - bug
+  - triage
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form when Pretensor indexed your database but the resulting graph is **wrong or incomplete** — a table or column is missing, a foreign key or inferred join is wrong, or MCP tools return schema context that doesn't match reality. For crashes and errors, use the bug report form instead.
+
+        **Security vulnerabilities must not be filed as public issues.** See [SECURITY.md](https://github.com/pretensor-ai/pretensor/blob/main/SECURITY.md) and report privately via [GitHub Security Advisories](https://github.com/pretensor-ai/pretensor/security/advisories/new).
+
+  - type: input
+    id: pretensor-version
+    attributes:
+      label: Pretensor version
+      description: Output of `pretensor --version`.
+      placeholder: "0.1.0aN"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: backend
+    attributes:
+      label: Database backend
+      options:
+        - PostgreSQL
+        - MySQL
+        - Snowflake
+        - BigQuery
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: backend-version
+    attributes:
+      label: Database version
+      description: e.g. `PostgreSQL 16.3`, `Snowflake 8.x`.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: problem-kind
+    attributes:
+      label: What is wrong in the graph?
+      options:
+        - Table missing
+        - Column missing
+        - Foreign key missing or wrong
+        - Inferred join / relationship wrong
+        - Wrong metadata (types, row counts, comments)
+        - Search / context returns the wrong schema objects
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Where do you see it?
+      description: The surface where the wrong output shows up.
+      options:
+        - CLI (`pretensor list` / `validate` / `export`)
+        - MCP tool response (`schema`, `context`, `traverse`, ...)
+        - Both
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What the database actually contains
+      description: |
+        The relevant schema as it exists in your database — a sanitized DDL
+        snippet (`CREATE TABLE ...`), an information-schema query result, or a
+        prose description. Redact table/column names if needed, but keep the
+        structure (keys, references) intact.
+      render: sql
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What Pretensor produced instead
+      description: The wrong or missing output — CLI output, MCP tool response JSON, or `pretensor export` fragment.
+      render: shell
+    validations:
+      required: true
+
+  - type: dropdown
+    id: reindex
+    attributes:
+      label: Does a fresh index reproduce it?
+      description: Whether the problem survives a full `pretensor index` (not just `reindex`) into a clean state directory.
+      options:
+        - Yes — reproduced after a fresh full index
+        - No — a fresh index fixed it
+        - Not tried
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Index/reindex logs or additional context
+      description: Output of the indexing run (add `--log-level debug` if possible). Redact secrets, DSNs, and personally identifiable data.
+      render: shell
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-submission checks
+      options:
+        - label: I searched existing issues and did not find a duplicate.
+          required: true
+        - label: I redacted credentials and sensitive schema details from all snippets.
+          required: true

pretensor-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Summary
+
+<!-- What changed and why (1-3 sentences). -->
+
+## Checklist
+
+- [ ] Tests pass (`python -m pytest tests/`)
+- [ ] Linting passes (`ruff check src/ tests/`)
+- [ ] Type checking passes (`pyright src/`)
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` (or noted as not user-facing)
+- [ ] All commits signed off per the [Developer Certificate of Origin](https://developercertificate.org/) (`git commit -s`)
+
+## Notes
+
+<!-- Optional: risks, follow-ups, screenshots. -->

pretensor-0.1.0/.github/workflows/bench.yml

@@ -0,0 +1,155 @@
+name: Bench
+
+on:
+  # No paths-ignore: the bench lane runs on every PR (including doc-only)
+  # so the dry-run AC is satisfiable and the lane never silently no-ops.
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      l3_model:
+        description: "L3 model id (defaults to claude-haiku-4-5)"
+        required: false
+        type: string
+        default: "claude-haiku-4-5"
+  # L3 runs weekly (Monday 04:00 UTC) for trend watching, on release-tag
+  # pushes for the release-being-announced snapshot, and on manual dispatch
+  # for ad-hoc runs.
+  schedule:
+    - cron: '0 4 * * 1'
+  push:
+    tags: ['v*.*.*']
+
+concurrency:
+  group: bench-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  pr-bench:
+    name: ${{ matrix.level }} (${{ matrix.dataset }}, ${{ matrix.extras_label }})
+    if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        level: [l1, l2]
+        dataset: [pagila, adventureworks, tpch]
+        extras: [dev, dev-embeddings]
+        include:
+          - extras: dev
+            extras_args: "--extra dev"
+            extras_label: "dev"
+          - extras: dev-embeddings
+            extras_args: "--extra dev --extra embeddings"
+            extras_label: "dev,embeddings"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --locked ${{ matrix.extras_args }}
+      - name: Cache HuggingFace embedding model
+        if: matrix.extras == 'dev-embeddings'
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface
+          key: hf-arctic-embed-xs-${{ hashFiles('src/pretensor/intelligence/embeddings.py') }}
+      - name: Pre-warm embedding model (retry on Hub rate limits)
+        if: matrix.extras == 'dev-embeddings'
+        env:
+          # Optional repo secret; anonymous Hub downloads from shared
+          # runner IPs are frequently 429-rate-limited. huggingface_hub
+          # picks the token up from the environment automatically; an
+          # empty value is a no-op.
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          for attempt in 1 2 3 4 5; do
+            if uv run python -c "from pretensor.intelligence.embeddings import get_default_embedding_client; get_default_embedding_client().embed(['warm'])"; then
+              echo "model ready (attempt $attempt)"
+              exit 0
+            fi
+            sleep $((30 + attempt * 15 + RANDOM % 30))
+          done
+          echo "::error::embedding model download kept failing (HF Hub rate limit?). Add an HF_TOKEN repo secret or retry the run."
+          exit 1
+      - name: Run benchmark
+        # The embeddings lane passes --embeddings and compares against
+        # lane-specific baselines: L2 measures real cosine retrieval for
+        # semantic_search + the hybrid rerank; L1 measures blind join
+        # discovery with the embedding relationship scorer registered at
+        # its documented typical threshold (see L1_EMBEDDING_JOIN_THRESHOLD).
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          BENCH_FLAG=""
+          SUFFIX=""
+          if [ "${{ matrix.extras }}" = "dev-embeddings" ]; then
+            BENCH_FLAG="--embeddings"
+            SUFFIX="-embeddings"
+          fi
+          echo "BASELINE_SUFFIX=$SUFFIX" >> "$GITHUB_ENV"
+          uv run pretensor benchmark ${{ matrix.level }} --dataset ${{ matrix.dataset }} $BENCH_FLAG --out current.json
+      - name: Compare against baseline
+        run: |
+          uv run pretensor benchmark compare \
+            --baseline tests/benchmark/baselines/${{ matrix.dataset }}-${{ matrix.level }}${BASELINE_SUFFIX}.json \
+            --current current.json
+      - name: Upload current result on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.level }}-${{ matrix.dataset }}-${{ matrix.extras }}-current
+          path: current.json
+          retention-days: 14
+          if-no-files-found: warn
+
+  l3:
+    name: L3 (${{ matrix.dataset }}, ${{ matrix.runner }})
+    # L3 is dormant until the per-dataset Postgres fixtures and DSN env
+    # vars are wired into CI. Set the repo variable
+    # `L3_ENV_PROVISIONED=true` once that work lands; until then,
+    # scheduled / tag-push / manual triggers no-op cleanly instead of
+    # producing six failed jobs that drown out the L1+L2 signal.
+    if: vars.L3_ENV_PROVISIONED == 'true' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule')
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    continue-on-error: true
+    strategy:
+      fail-fast: false
+      matrix:
+        dataset: [pagila, adventureworks, tpch]
+        runner: [baseline, pretensor]
+    env:
+      ANTHROPIC_API_KEY: ${{ secrets.BENCH_ANTHROPIC_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --locked --extra dev --extra embeddings
+      - name: Run L3
+        run: |
+          model="${{ inputs.l3_model || 'claude-haiku-4-5' }}"
+          uv run pretensor benchmark l3 \
+            --dataset ${{ matrix.dataset }} \
+            --runner ${{ matrix.runner }} \
+            --model "$model" \
+            --out results.json
+      - name: Upload result
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: l3-${{ matrix.dataset }}-${{ matrix.runner }}-${{ github.run_id }}
+          path: results.json
+          retention-days: 90
+          if-no-files-found: warn

pretensor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,198 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master, 'publish/**']
+    paths-ignore:
+      - 'docs/**'
+      - '**.md'
+      - '.github/ISSUE_TEMPLATE/**'
+  pull_request:
+    paths-ignore:
+      - 'docs/**'
+      - '**.md'
+      - '.github/ISSUE_TEMPLATE/**'
+  schedule:
+    # Nightly slow lane (real-model embedding smoke + future heavy fixtures).
+    # Daily at 03:17 UTC.
+    - cron: '17 3 * * *'
+  workflow_dispatch:
+    inputs:
+      run_slow:
+        description: 'Run the slow opt-in test lane (real model downloads).'
+        type: boolean
+        required: false
+        default: false
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --locked --extra dev
+      - name: Ruff check
+        run: uv run ruff check src tests
+
+  lockfile:
+    name: Lockfile up to date
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: "3.12"
+      - name: Verify uv.lock matches pyproject.toml
+        # Fails if the committed lock would be re-resolved — keeps the reviewed
+        # pins identical to what every other job installs with `uv sync --locked`.
+        run: uv lock --check
+
+  typecheck:
+    name: Typecheck (pyright)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --locked --extra dev
+      - name: Pyright
+        run: uv run pyright
+
+  test:
+    name: Test (pytest, py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --locked --extra dev
+      - name: Pytest
+        env:
+          PYTHONPATH: src
+        run: uv run pytest tests/
+
+  build-verify:
+    name: Build wheel & verify packaging
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Verify wheel ships every tracked subpackage
+        # Guard against .gitignore (or any other exclude) silently dropping a
+        # package directory from the built wheel. Every `__init__.py` tracked
+        # under `src/pretensor/` must land at the matching path inside the wheel.
+        run: |
+          uv run python <<'PY'
+          import glob, subprocess, sys, zipfile
+
+          whls = sorted(glob.glob("dist/pretensor-*-py3-none-any.whl"))
+          if len(whls) != 1:
+              sys.exit(
+                  f"expected exactly one wheel in dist/, found {len(whls)}: {whls}"
+              )
+          whl = whls[0]
+
+          with zipfile.ZipFile(whl) as z:
+              names = set(z.namelist())
+
+          tracked = subprocess.check_output(
+              ["git", "ls-files", "src/pretensor/"], text=True
+          ).splitlines()
+          expected = sorted(
+              f.removeprefix("src/") for f in tracked if f.endswith("/__init__.py")
+          )
+
+          missing = [e for e in expected if e not in names]
+          if missing:
+              print(f"MISSING from {whl}:", file=sys.stderr)
+              for m in missing:
+                  print(f"  - {m}", file=sys.stderr)
+              sys.exit(1)
+          print(f"OK: {whl} contains all {len(expected)} tracked __init__.py files")
+          PY
+      - name: Smoke-test the installed wheel
+        # Install the freshly built wheel into an isolated env and boot the
+        # CLI. `pretensor --help` imports every subcommand module at startup
+        # (typer registration), which transitively imports
+        # `pretensor.skills.generator` from `cli/commands/index.py`. A missing
+        # subpackage would surface here as ModuleNotFoundError — the exact
+        # failure mode the published 0.1.0a1 wheel had.
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          wheels=(dist/pretensor-*-py3-none-any.whl)
+          if [ "${#wheels[@]}" -ne 1 ]; then
+            echo "expected exactly one wheel in dist/, found ${#wheels[@]}" >&2
+            exit 1
+          fi
+          uvx --from "${wheels[0]}" pretensor --help > /dev/null
+
+  slow-tests:
+    name: Slow tests (opt-in real model)
+    if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.run_slow)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: "3.12"
+      - name: Install dependencies (with embeddings extra)
+        run: uv sync --locked --extra dev --extra embeddings
+      - name: Cache HuggingFace embedding model
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface
+          key: hf-arctic-embed-xs-${{ hashFiles('src/pretensor/intelligence/embeddings.py') }}
+      - name: Pre-warm embedding model (retry on Hub rate limits)
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          for attempt in 1 2 3 4 5; do
+            if uv run python -c "from pretensor.intelligence.embeddings import get_default_embedding_client; get_default_embedding_client().embed(['warm'])"; then
+              echo "model ready (attempt $attempt)"
+              exit 0
+            fi
+            sleep $((30 + attempt * 15 + RANDOM % 30))
+          done
+          echo "::error::embedding model download kept failing (HF Hub rate limit?). Add an HF_TOKEN repo secret or retry the run."
+          exit 1
+      - name: Pytest -m slow
+        env:
+          PYTHONPATH: src
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: uv run pytest -m slow tests/