schemabrain 0.1.0a1__tar.gz

schemabrain-0.1.0a1/.env.example

@@ -0,0 +1,18 @@
+# Postgres connection string for the database to index
+# Example: postgresql://user:password@localhost:5432/mydb
+SCHEMABRAIN_DATABASE_URL=
+
+# Anthropic API key for LLM-powered semantic enrichment
+# Get one at https://console.anthropic.com/
+ANTHROPIC_API_KEY=
+
+# Path to the local Schema Brain SQLite store
+# Defaults to ./schemabrain.db if unset
+SCHEMABRAIN_STORE_PATH=./schemabrain.db
+
+# Hard cap on LLM spend per `index` run, in USD.
+# The run aborts if estimated cost exceeds this. Default 10.
+SCHEMABRAIN_MAX_COST_USD=10
+
+# Logging level: DEBUG, INFO, WARNING, ERROR
+SCHEMABRAIN_LOG_LEVEL=INFO

schemabrain-0.1.0a1/.github/CODEOWNERS

@@ -0,0 +1,12 @@
+# Schema Brain code owners.
+#
+# GitHub uses this file to auto-request review from the listed owners on
+# every PR that touches matching paths. Keep the list small and current —
+# stale owners create noise; missing owners create silent gaps.
+#
+# Today the project is single-maintainer (pre-alpha). When new maintainers
+# join, add them here per-area rather than as a global owner so review
+# load can be shared rather than bottlenecked.
+
+# Catch-all: every PR auto-requests Arun until subject-matter owners exist.
+*    @Arun-kc

schemabrain-0.1.0a1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,91 @@
+name: Bug report
+description: Something is broken or behaves unexpectedly.
+title: "[bug] "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report. The fields below
+        are required so we can reproduce and triage. Please don't strip
+        them — incomplete reports get closed with a request to re-open.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of what you saw vs what you expected.
+      placeholder: |
+        Ran `schemabrain index $POSTGRES_URL` and got X. Expected Y.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: |
+        Exact commands and inputs we can run to see the bug ourselves.
+        For schema-related bugs, the output of `pg_dump --schema-only`
+        for the affected tables is usually enough. Strip secrets first.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Full traceback (if applicable)
+      description: Paste the full error output, not just the last line.
+      render: shell
+    validations:
+      required: false
+
+  - type: input
+    id: schemabrain-version
+    attributes:
+      label: Schema Brain version
+      description: Output of `pip show schemabrain | grep -i version` or the commit SHA.
+      placeholder: "0.0.0 / commit ee9e357"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: Output of `python --version`.
+      placeholder: "3.11.15"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux x86_64
+        - Linux aarch64
+        - macOS arm64 (Apple Silicon)
+        - macOS x86_64 (Intel)
+        - Windows
+        - Other (specify in "What happened?")
+    validations:
+      required: true
+
+  - type: input
+    id: database
+    attributes:
+      label: Database engine and version
+      description: e.g. `Postgres 16.2`, `SQLite 3.45.0`. Output of `SELECT version();` is fine.
+      placeholder: "Postgres 16.2"
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: Workarounds you tried, related issues, anything that helps triage.
+    validations:
+      required: false

schemabrain-0.1.0a1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,7 @@
+# Disable blank issues — every issue must use a structured template so
+# triage gets the info it needs without a back-and-forth round trip.
+blank_issues_enabled: false
+
+# No external contact links yet (no Discord, no community forum). Add
+# them here once they exist; until then, the issue templates are the
+# only entry points.

schemabrain-0.1.0a1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,65 @@
+name: Feature request
+description: Suggest something Schema Brain should do that it doesn't.
+title: "[feat] "
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Schema Brain has a deliberately small surface — most "missing"
+        features are deferred on purpose, not forgotten. Please describe
+        the underlying problem first; the maintainer will propose the
+        smallest fix rather than implementing the requested change verbatim.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: |
+        Describe the situation, not the solution. "I can't write SQL
+        against my warehouse without knowing which tables to JOIN" is
+        better than "Add a `suggest_joins` MCP tool" — the second
+        forecloses on alternative fixes.
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: Current workaround (if any)
+      description: How are you working around the limitation today?
+    validations:
+      required: false
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: |
+        Optional. If you have a specific design in mind, describe it.
+        Treat this as a starting point for discussion, not a spec.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: who-uses-it
+    attributes:
+      label: Who would use this?
+      options:
+        - Just me
+        - My team / organization
+        - I think it's broadly useful
+        - Not sure
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      description: "Schema Brain v0 stays small on purpose. Please confirm:"
+      options:
+        - label: I've checked the README's "Roadmap" section to see if this is already planned.
+          required: true
+        - label: I've checked open and closed issues for similar requests.
+          required: true

schemabrain-0.1.0a1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,43 @@
+<!--
+Thanks for sending a PR. Please fill in the sections below — the bullets
+are optional removable scaffolding, not required boilerplate. The goal
+is a description that makes review fast and a permanent record that
+makes the commit history readable a year from now.
+-->
+
+## Summary
+
+<!-- One or two sentences: what does this change do, and why now? -->
+
+## Context
+
+<!--
+What problem does this solve? What was the old behavior?
+Link related issues with `Closes #N` or `Refs #N`.
+-->
+
+## Changes
+
+<!--
+Bullet list of the meaningful changes (not every file touched). For
+larger PRs, group by area (`mcp/`, `core/`, `eval/`, etc).
+-->
+
+-
+
+## Test plan
+
+<!--
+- [ ] Unit tests added/updated and passing
+- [ ] Integration tests added/updated and passing (if behavior changed)
+- [ ] Coverage holds (`uv run pytest --cov=schemabrain --cov-branch`)
+- [ ] Lint and format clean (`uv run ruff check && uv run ruff format --check`)
+- [ ] Manual verification (commands run, screenshots, etc) if applicable
+-->
+
+## Tradeoffs / open questions
+
+<!--
+What did you consider and reject? What's deferred? What should the
+reviewer push back on if they disagree?
+-->

schemabrain-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+# GitHub Actions CI for Schema Brain.
+#
+# Two jobs run on every push to `main` and every pull request:
+#   - lint-and-unit: ruff + pytest unit tests across Python 3.11 + 3.12.
+#                    Fast (target: under 60s warm cache); blocks merge.
+#   - integration:   pytest integration tests (Docker / testcontainers
+#                    Postgres). Single Python (3.11) since the integration
+#                    surface is dialect-driven, not interpreter-driven.
+#                    Slower (~2-3 min, dominated by container boot); also
+#                    blocks merge so we don't ship regressions in the
+#                    Postgres connector or profiler.
+#
+# Both jobs use `uv` for env management — same tool the dev workflow uses,
+# so CI failures reproduce locally with `uv sync --extra dev && uv run pytest`.
+#
+# OS matrix: ubuntu-latest only at v0. macOS is documented as supported
+# for local dev on Python 3.11, but `onnxruntime` (a fastembed transitive
+# dep) has no wheel for macOS arm64 + Python 3.12 today, so adding macOS
+# to CI would either drop a Python version or fail the macOS+3.12 cell.
+# Revisit when onnxruntime ships the missing wheel.
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel in-flight runs for the same PR / branch when a new push lands —
+# saves CI minutes on rapid iteration without losing any signal.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-unit:
+    name: Lint + unit (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff check)
+        run: uv run --python ${{ matrix.python-version }} ruff check schemabrain tests
+
+      - name: Format check (ruff format --check)
+        run: uv run --python ${{ matrix.python-version }} ruff format --check schemabrain tests
+
+      - name: Unit tests
+        # No coverage gate here — unit-only runs miss code paths
+        # exercised by integration tests (Postgres connector, profiler).
+        # The 99% line+branch gate runs in the `integration` job, which
+        # sees the full suite. This job is the fast PR-feedback signal.
+        run: uv run --python ${{ matrix.python-version }} pytest -m "not integration"
+
+  integration:
+    name: Integration (Docker / Postgres)
+    runs-on: ubuntu-latest
+    # Run after lint-and-unit so a syntax error doesn't waste 3 min on
+    # container boot. Either lint-and-unit cell green is enough — we don't
+    # need both Python versions to pass before integration starts.
+    needs: lint-and-unit
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --extra dev --python 3.11
+
+      - name: Pre-pull Postgres image (warm testcontainers cache)
+        run: docker pull postgres:16-alpine
+
+      - name: Full suite with coverage gate
+        # Runs BOTH unit and integration tests together so the coverage
+        # report sees every path. The 99% gate is a one-percentage-point
+        # buffer below the project's 100% line+branch target — flags
+        # genuine regressions without thrashing on minor edge cases.
+        run: |
+          uv run --python 3.11 pytest \
+            --cov=schemabrain \
+            --cov-branch \
+            --cov-report=term-missing \
+            --cov-fail-under=99

schemabrain-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,94 @@
+# Publishes Schema Brain to TestPyPI or PyPI via Trusted Publishers (OIDC).
+#
+# No long-lived API tokens. PyPI/TestPyPI verify the workflow's OIDC token
+# against a pending-or-existing Trusted Publisher configured on each index.
+#
+# Manual-dispatch only for v0.1.0a1: every publish requires going to the
+# GitHub Actions UI and explicitly picking `testpypi` or `pypi`. No tag
+# push auto-triggers a release. Trade-off: more clicks per release. Why:
+#
+#   1. Free-plan private repos cannot set Required-Reviewer protection on
+#      GitHub Environments, so a tag-triggered chain has no human gate
+#      between TestPyPI and PyPI.
+#   2. First publishes are the highest-risk moment — once a version like
+#      `0.1.0a1` is on PyPI it is immutable forever. Manual dispatch makes
+#      every publish an intentional act.
+#
+# Once the package is established and the pipeline is proven, this can
+# convert to a tag-triggered or release-triggered design.
+
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+        default: testpypi
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Show built artifacts
+        run: ls -la dist/
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to ${{ inputs.target }}
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      # Environment binding is what scopes the OIDC token claim that
+      # PyPI/TestPyPI verify against their Trusted Publisher config.
+      # The environment names must match what was registered on each
+      # index: `testpypi` on test.pypi.org, `pypi` on pypi.org.
+      name: ${{ inputs.target }}
+      url: ${{ inputs.target == 'pypi' && 'https://pypi.org/p/schemabrain' || 'https://test.pypi.org/p/schemabrain' }}
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        if: inputs.target == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+      - name: Publish to PyPI
+        if: inputs.target == 'pypi'
+        uses: pypa/gh-action-pypi-publish@release/v1

schemabrain-0.1.0a1/.gitignore

@@ -0,0 +1,89 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.env.*
+!.env.example
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Editors / IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# Ruff
+.ruff_cache/
+
+# Schema Brain local artifacts
+schemabrain.db
+schemabrain.db-journal
+schemabrain.db-wal
+schemabrain.db-shm
+*.schemabrain.db
+.schemabrain/
+.fastembed_cache/
+
+# Logs
+*.log
+logs/
+
+# Claude
+.claude/

schemabrain-0.1.0a1/.python-version

@@ -0,0 +1 @@
+3.11