passageway 0.3.0__tar.gz

passageway-0.3.0/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "passageway",
+  "description": "Claude Code plugin: write connectors for passageway.",
+  "owner": {
+    "name": "Marcel Bruckner (Marceltov)"
+  },
+  "plugins": [
+    {
+      "name": "passageway",
+      "source": "./",
+      "description": "Skills for passageway: create a connector that feeds a source into passageway's index."
+    }
+  ]
+}

passageway-0.3.0/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "passageway",
+  "version": "0.3.0",
+  "description": "Retrieval for Claude over MCP: connectors feed passages, a relevance gate keeps it quiet when nothing fits. Ships the prompt hook and the skills /passageway (a general guide), /passageway-install (install and run it as a service), /passageway-connect (link Claude Code to a server), /passageway-add-source (index a source), /passageway-status (is it fine, and what to do), /passageway-evaluate (measure retrieval quality on the user's questions) and /create-passageway-connector (write a connector).",
+  "author": {
+    "name": "Marcel Bruckner"
+  },
+  "homepage": "https://passageway.marceltov.de/",
+  "repository": "https://github.com/getpassageway/passageway",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "keywords": [
+    "mcp",
+    "retrieval",
+    "rag",
+    "connectors",
+    "skills"
+  ]
+}

passageway-0.3.0/.dockerignore

@@ -0,0 +1,17 @@
+.git
+.github
+.venv
+**/.venv
+**/__pycache__
+**/.pytest_cache
+site
+docs
+corpus
+tests
+**/tests
+skills
+hooks
+scripts
+.claude-plugin
+CLAUDE.md
+CHANGELOG.md

passageway-0.3.0/.gitattributes

@@ -0,0 +1,2 @@
+corpus/en/** linguist-generated=true
+corpus/de/** linguist-generated=true

passageway-0.3.0/.github/dependabot.yml

@@ -0,0 +1,62 @@
+# Dependency bumps as pull requests with CI run. Security updates (switched on in the repository's settings) come at once and skip
+# the cooldown; everything else waits two weeks after a release and comes grouped on Monday mornings. Patch and minor bumps merge by
+# themselves once the required checks are green (.github/workflows/dependabot-automerge.yml); majors wait for review.
+version: 2
+
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "05:00"
+      timezone: Europe/Berlin
+    cooldown:
+      default-days: 14
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: Dependencies
+    labels: [dependencies]
+    groups:
+      minor-and-patch:
+        update-types: [minor, patch]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "05:00"
+      timezone: Europe/Berlin
+    cooldown:
+      default-days: 14
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: Dependencies
+    labels: [dependencies]
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "05:00"
+      timezone: Europe/Berlin
+    cooldown:
+      default-days: 14
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: Dependencies
+    labels: [dependencies]
+    # the builder, model and runtime stages must share one Python minor: a new minor is a change to review
+    ignore:
+      - dependency-name: "python"
+        update-types: ["version-update:semver-major", "version-update:semver-minor"]
+      - dependency-name: "ghcr.io/astral-sh/uv"
+        update-types: ["version-update:semver-major", "version-update:semver-minor"]
+    groups:
+      minor-and-patch:
+        update-types: [minor, patch]

passageway-0.3.0/.github/workflows/audit.yml

@@ -0,0 +1,25 @@
+name: Audit
+
+# Known vulnerabilities in what is shipped: the locked runtime dependencies of the core and of every connector package.
+# A scheduled run, because an advisory appears without a commit. A red run means: upgrade the dependency. Dependabot security
+# updates (.github/dependabot.yml) open the pull request for a fixed version as soon as an advisory is known; this run is the net
+# for what it misses.
+on:
+  schedule:
+    - cron: "17 5 * * *"
+  workflow_dispatch:
+  pull_request:
+    paths: [.github/workflows/audit.yml]
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+      # The locked versions of what runs in production: no dev group, none of the workspace's own packages.
+      - run: uv export -q --frozen --all-packages --no-dev --no-emit-workspace --no-hashes -o requirements-audit.txt
+      - run: uvx pip-audit -r requirements-audit.txt --no-deps --disable-pip

passageway-0.3.0/.github/workflows/checks.yml

@@ -0,0 +1,120 @@
+name: Checks
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  # Which jobs a change needs. A job skipped here counts as passed for the ruleset; a change to this file runs everything.
+  # The test suite reads the docs, the skills and the workflows (tests/test_docs.py, tests/test_agent_files.py), so it runs
+  # for nearly everything: only files no test and no build reads leave it out.
+  changes:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      test: ${{ steps.filter.outputs.test }}
+      docs: ${{ steps.filter.outputs.docs }}
+      image: ${{ steps.filter.outputs.image }}
+      plugin: ${{ steps.filter.outputs.plugin }}
+    steps:
+      - uses: actions/checkout@v7
+      - id: filter
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            test:
+              - '**'
+              - '!LICENSE'
+              - '!.gitignore'
+              - '!.github/workflows/pages.yml'
+              - '!.github/workflows/audit.yml'
+              - '!.github/workflows/dependabot-automerge.yml'
+            docs:
+              - '.github/workflows/checks.yml'
+              - 'docs/**'
+              - 'docs_hooks/**'
+              - 'mkdocs.yml'
+              - 'README.md'
+              - 'connectors/*/README.md'
+              - 'embedders/*/README.md'
+              - 'sdk/README.md'
+              - 'skills/**'
+              - 'scripts/publish-skills.sh'
+              - 'corpus/**'
+            image:
+              - '.github/workflows/checks.yml'
+              - 'Dockerfile'
+              - '.dockerignore'
+              - 'pyproject.toml'
+              - 'uv.lock'
+              - 'README.md'
+              - 'passageway/**'
+              - 'sdk/**'
+              - 'connectors/**'
+              - 'embedders/**'
+            plugin:
+              - '.github/workflows/checks.yml'
+              - '.claude-plugin/**'
+              - 'skills/**'
+              - 'hooks/**'
+              - 'scripts/recall-hook.sh'
+              - 'scripts/test-recall-hook.sh'
+  test:
+    needs: changes
+    if: needs.changes.outputs.test == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+      - run: uv sync --frozen --all-packages
+      - run: uv run pytest -q
+  docs:
+    needs: changes
+    if: needs.changes.outputs.docs == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+      # mkdocs<2: Material 9 isn't compatible with MkDocs 2.0. --strict fails on broken links.
+      - run: uvx --with mkdocs-material==9.7.7 --with mkdocs-llmstxt==0.5.1 --with 'mkdocs<2' mkdocs build --strict
+      - name: The agent files are in the site
+        run: |
+          scripts/publish-skills.sh site
+          test -s site/llms.txt && test -s site/llms-full.txt
+          test -s site/SKILL.md && test -s site/skills/create-passageway-connector/SKILL.md && test -s site/skills/passageway-add-source/SKILL.md && test -s site/skills/passageway-install/SKILL.md
+          grep -q "Write a connector" site/llms-full.txt && grep -q "CATEGORY_DEPTH" site/llms-full.txt   # the Wikipedia include made it in
+          grep -q "pw-timeline" site/roadmap/index.html && grep -q "Markdown connector" site/llms-full.txt   # the roadmap timeline
+          grep -q "pw-header-links" site/index.html && grep -q "passageway.marceltov.de/llms-full.txt" site/index.html   # the header links
+  # The plugin manifest, the skills and the hook, checked the way Claude Code loads them.
+  plugin:
+    needs: changes
+    if: needs.changes.outputs.plugin == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+      - run: npm install -g @anthropic-ai/claude-code
+      - run: claude plugin validate .
+      - run: bash scripts/test-recall-hook.sh
+  image:
+    needs: changes
+    if: needs.changes.outputs.image == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build the sidecar image
+        run: docker build -t passageway:ci .
+      - name: Start it with one fake source and ask it something
+        run: |
+          mkdir -p ci-config
+          echo '[{"id": "a", "title": "Lighthouses", "url": "http://x/a", "version": "1", "sections": [{"heading": null, "text": "Lighthouses guide ships safely into the harbour at night."}]}]' > ci-config/items.json
+          printf '[[connector]]\nname = "fake"\ncommand = ["python", "-m", "passageway.testing.fake_connector"]\nenv = { FAKE_ITEMS = "/config/items.json" }\n' > ci-config/passageway.toml
+          docker run -d --name pw -e PASSAGEWAY_LOGIN_PASSWORD=ci-only -p 8082:8082 -v "$PWD/ci-config:/config:ro" passageway:ci
+          for i in $(seq 1 60); do curl -s http://localhost:8082/health | grep -qE '"status": ?"ok"' && break; sleep 2; done
+          curl -s http://localhost:8082/health | grep -qE '"status": ?"ok"' || { docker logs pw; exit 1; }
+          curl -sf -H "Authorization: Bearer ci-only" -H "Content-Type: application/json" \
+            -d '{"prompt": "which lighthouses guide ships into the harbour at night"}' http://localhost:8082/recall | grep -q Lighthouses \
+            || { docker logs pw; exit 1; }
+          docker rm -f pw

passageway-0.3.0/.github/workflows/cla.yml

@@ -0,0 +1,30 @@
+name: CLA
+
+# A pull request from outside waits until its author has accepted CLA.md by comment; signatures live on the cla-signatures branch, because
+# the main ruleset keeps the action from writing to main. The maintainer, Claude (the co-author on commits made with it) and Dependabot need no agreement.
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, closed, synchronize]
+
+permissions:
+  actions: write
+  contents: write
+  pull-requests: write
+  statuses: write
+
+jobs:
+  cla:
+    if: github.event_name == 'pull_request_target' || github.event.issue.pull_request
+    runs-on: ubuntu-latest
+    steps:
+      - uses: contributor-assistant/github-action@v2.6.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          path-to-document: https://github.com/getpassageway/passageway/blob/main/CLA.md
+          path-to-signatures: signatures.json
+          branch: cla-signatures
+          allowlist: Marceltov,claude,dependabot[bot]
+          custom-pr-sign-comment: I have read the CLA and I agree to it.

passageway-0.3.0/.github/workflows/dependabot-automerge.yml

@@ -0,0 +1,22 @@
+name: Dependabot auto-merge
+
+# Dependabot's patch and minor bumps (security updates included) merge by themselves once the checks the main ruleset requires are
+# green; majors wait for a person. `--auto` only waits because main requires those checks: without the ruleset it would merge at once.
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  automerge:
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - id: meta
+        uses: dependabot/fetch-metadata@v3
+      - if: steps.meta.outputs.update-type == 'version-update:semver-patch' || steps.meta.outputs.update-type == 'version-update:semver-minor'
+        run: gh pr merge --auto --merge "$PR"
+        env:
+          PR: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

passageway-0.3.0/.github/workflows/pages.yml

@@ -0,0 +1,43 @@
+name: Publish docs
+
+# Build the documentation site from docs/ with Material for MkDocs and publish it
+# to GitHub Pages. --strict fails the build on broken internal links.
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**", "mkdocs.yml", "skills/**", "connectors/**/README.md", ".github/workflows/pages.yml", "scripts/publish-skills.sh"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+      # mkdocs<2: Material 9 isn't compatible with MkDocs 2.0.
+      - run: uvx --with mkdocs-material==9.7.7 --with mkdocs-llmstxt==0.5.1 --with 'mkdocs<2' mkdocs build --strict
+      # MkDocs only builds docs/; the skills live in skills/, and an agent wants them as raw files.
+      - run: scripts/publish-skills.sh site
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

passageway-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,141 @@
+name: Release
+
+# A v* tag creates a GitHub release, posts its notes to notefeed (once per tag), publishes every package to PyPI and builds the image.
+#
+#   git tag -a v0.2.0 -m "A one-line headline for the release"
+#   git push origin v0.2.0
+#
+# The tag must equal the version in pyproject.toml (scripts/check-version.sh) and the tests must pass.
+# The notes are the annotated tag's message, the pull requests merged since the previous release and
+# install instructions (scripts/release-notes.sh). Without the NOTEFEED_FEED secret (forks) nothing is posted.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "An existing tag to publish again, for example v0.2.0"
+        required: true
+
+concurrency:
+  group: release-${{ inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      TAG: ${{ inputs.tag || github.ref_name }}
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: refs/tags/${{ inputs.tag || github.ref_name }}
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Tag matches the project version
+        run: scripts/check-version.sh "$TAG"
+
+      - uses: astral-sh/setup-uv@v10.3.3
+      - name: Tests
+        run: |
+          uv sync --frozen --all-packages
+          uv run pytest -q
+
+      - name: Assemble the release notes
+        run: scripts/release-notes.sh "$TAG" > notes.md
+
+      - name: Create or update the release
+        run: |
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release edit "$TAG" --title "$TAG" --notes-file notes.md
+          else
+            gh release create "$TAG" --title "$TAG" --notes-file notes.md --verify-tag
+          fi
+
+      # Posts the notes of the release as published, plus a link to it. A re-run does not post twice. A failure here is
+      # shown but does not hold back the image.
+      - name: Post the notes to notefeed
+        continue-on-error: true
+        env:
+          NOTEFEED_FEED: ${{ secrets.NOTEFEED_FEED }}
+          NOTEFEED_FEED_PASSWORD: ${{ secrets.NOTEFEED_FEED_PASSWORD }}
+        run: |
+          gh release view "$TAG" --json body,url --jq '.body + "\n\n[The release on GitHub](" + .url + ")\n"' > notefeed.md
+          scripts/post-to-notefeed.sh "$TAG" notefeed.md
+
+  publish:
+    # Every package to PyPI at the tag's version (by token for the first release, then trusted publishing): the SDK first because the others depend on
+    # it, the core last because its extras pin the others. --check-url skips what is already on PyPI, so a re-run after a half-failed
+    # release carries on instead of failing. A published version can never be replaced, only yanked.
+    runs-on: ubuntu-latest
+    needs: release
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      TAG: ${{ inputs.tag || github.ref_name }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: refs/tags/${{ inputs.tag || github.ref_name }}
+      - uses: astral-sh/setup-uv@v10.3.3
+      - name: Build every package
+        run: uv build --all-packages
+      - name: Check the metadata
+        run: uvx twine check dist/*
+      - name: Publish
+        # The first release creates the nine projects with an account token, because a project must exist before PyPI accepts a
+        # trusted publisher for it. The follow-up removes this env block and the secret and goes back to trusted publishing.
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          packages="passageway-sdk passageway-connector-confluence passageway-connector-llmstxt passageway-connector-markdown passageway-connector-sitemap passageway-connector-trilium passageway-connector-wikipedia passageway-embedder-openai passageway"
+          # An old tag run again by hand builds an old tree whose versions differ: refuse before the first upload, because
+          # a half-published release (the SDK up, the rest missing) cannot be repaired.
+          for package in $packages; do
+            [ "$(compgen -G "dist/${package//-/_}-${TAG#v}*" | wc -l)" -eq 2 ] || { echo "dist/ has no wheel and sdist of $package at ${TAG#v}" >&2; exit 1; }
+          done
+          for package in $packages; do
+            uv publish --check-url https://pypi.org/simple/ "dist/${package//-/_}-${TAG#v}"*
+          done
+
+  image:
+    # The sidecar image for amd64 and arm64, tagged with the version; latest moves only on a pushed version tag.
+    runs-on: ubuntu-latest
+    needs: release
+    permissions:
+      contents: read
+      packages: write
+    env:
+      TAG: ${{ inputs.tag || github.ref_name }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: refs/tags/${{ inputs.tag || github.ref_name }}
+      - uses: docker/setup-qemu-action@v4
+      - uses: docker/setup-buildx-action@v4
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and push
+        run: |
+          image=$(echo "ghcr.io/${{ github.repository_owner }}/passageway" | tr '[:upper:]' '[:lower:]')
+          tags="-t $image:${TAG#v}"
+          if [ "${{ github.event_name }}" = "push" ]; then tags="$tags -t $image:latest"; fi
+          docker buildx build --platform linux/amd64,linux/arm64 --build-arg APP_VERSION="${TAG#v}" $tags --push .
+      - name: Build and push the variant with a browser
+        # For the sitemap connector's RENDER: the same image plus Chromium, tagged <version>-browser and, on a pushed tag, browser.
+        run: |
+          image=$(echo "ghcr.io/${{ github.repository_owner }}/passageway" | tr '[:upper:]' '[:lower:]')
+          tags="-t $image:${TAG#v}-browser"
+          if [ "${{ github.event_name }}" = "push" ]; then tags="$tags -t $image:browser"; fi
+          docker buildx build --platform linux/amd64,linux/arm64 --build-arg APP_VERSION="${TAG#v}" --build-arg WITH_BROWSER=1 $tags --push .

passageway-0.3.0/.gitignore

@@ -0,0 +1,11 @@
+docs/superpowers/
+.superpowers/
+.env
+.DS_Store
+.venv/
+__pycache__/
+.pytest_cache/
+.models/
+dist/
+site/
+.playwright-mcp/

passageway-0.3.0/CLA.md

@@ -0,0 +1,29 @@
+# Contributor License Agreement
+
+Adapted from the Apache Software Foundation's Individual Contributor License Agreement V2.2, with "the Foundation" replaced by "the Maintainer" (Marcel Bruckner, who owns and manages passageway). The Apache text is the standard one; the changes are the party, the removed nonprofit clause, and how you accept it.
+
+passageway is licensed under the PolyForm Noncommercial License 1.0.0 and sold to companies under a separate licence, so the Maintainer must be able to license every line. This agreement is for your protection as a Contributor as well as the Maintainer's. It does not change your rights to use your own Contributions for any other purpose.
+
+**How to accept:** comment `I have read the CLA and I agree to it.` on your first pull request. That comment, under your GitHub account, is your signature; nothing else is collected. Accepting once covers your present and future Contributions. A contributor who works for a company needs that company's permission first (section 4).
+
+You accept and agree to the following terms and conditions for Your Contributions (present and future) that you submit to the Maintainer. Except for the license granted herein to the Maintainer and to recipients of software distributed by the Maintainer, You reserve all right, title, and interest in and to Your Contributions.
+
+1. Definitions.
+
+   "You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement with the Maintainer. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to the Maintainer for inclusion in, or documentation of, any of the products owned or managed by the Maintainer (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Maintainer or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Maintainer for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
+
+2. Grant of Copyright License. Subject to the terms and conditions of this Agreement, You hereby grant to the Maintainer and to recipients of software distributed by the Maintainer a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.
+
+3. Grant of Patent License. Subject to the terms and conditions of this Agreement, You hereby grant to the Maintainer and to recipients of software distributed by the Maintainer a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed.
+
+4. You represent that you are legally entitled to grant the above license. If your employer(s) has rights to intellectual property that you create that includes your Contributions, you represent that you have received permission to make Contributions on behalf of that employer, or that your employer has waived such rights for your Contributions to the Maintainer.
+
+5. You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). You represent that Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which you are personally aware and which are associated with any part of Your Contributions.
+
+6. You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+7. Should You wish to submit work that is not Your original creation, You may submit it to the Maintainer separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [named here]".
+
+8. You agree to notify the Maintainer of any facts or circumstances of which you become aware that would make these representations inaccurate in any respect.

passageway-0.3.0/CLAUDE.md

@@ -0,0 +1,29 @@
+# passageway
+
+Retrieval for Claude over MCP: connectors (out-of-process programs speaking JSON Lines) feed passages to a core that indexes and ranks them. Documentation: https://passageway.marceltov.de/ (the pages are in `docs/`).
+
+## Commands
+
+```bash
+uv sync                                   # the core and every connector package
+uv run pytest -q                          # the whole suite, offline
+uvx --with mkdocs-material==9.7.7 --with mkdocs-llmstxt==0.5.1 --with 'mkdocs<2' mkdocs build --strict   # the docs, as CI builds them
+PASSAGEWAY_LIVE=1 uv run pytest connectors/wikipedia/tests/test_wikipedia_live.py   # opt-in, hits Wikipedia
+```
+
+## Working in this repository
+
+- Every change is judged against `docs/values.md`, what passageway stands for; a review names the point it touches ("this breaks V2"). A change to that page needs my approval and says why.
+- Every change starts from an issue. Branches, commits and pull request titles carry `PASSAGEWAY #<issue>:` (the `/ccp:ship-pr` flow). Dependabot's carry `Dependencies:` instead.
+- Tests first: write the failing test, watch it fail, then the code. `tests/test_docs.py` keeps the docs in step with the code.
+- CI is the gate, and I decide when a branch is finished and when it is merged. A `/ccp:ship-pr` request is the go-ahead for push and PR only, not for the merge. Merge only when I say "merge". The one exception: Dependabot's patch and minor bumps merge by themselves once CI is green (`.github/workflows/dependabot-automerge.yml`); its majors wait for me like any other PR.
+- Every HTTPS client verifies against the operating system's trust store: `verify=` (httpx) or `context=` (urllib) is `truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)`, and `tests/test_trust.py` lists the client.
+- Never print or write a secret into a file, a log or a commit. Credentials live in 1Password; GitHub secrets are set by piping from there.
+
+## Roadmap
+
+The plan for where passageway is going, and for how trilium-recall folds into it, is `docs/roadmap.yml`, rendered as the timeline on the Roadmap page (`docs/roadmap.md`, `docs_hooks/roadmap.py`). Keep it true: mark a step done in the pull request that finishes it, and change the file in the pull request that changes the plan.
+
+## Releases
+
+A `vX.Y.Z` tag is a release and must equal the version in `pyproject.toml`. The Release workflow creates the GitHub release and posts its notes to the notefeed feed; see `docs/development.md`.

passageway-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# Contributing
+
+Every change starts from an issue; see `docs/development.md` for the gates and `docs/values.md` for what a change is judged against.
+
+passageway is licensed under the PolyForm Noncommercial License 1.0.0 and sold to companies under a separate licence, so the maintainer must be able to license every line. **A pull request from outside is merged only after its author accepts the [contributor licence agreement](CLA.md)** (a comment on the pull request; it is the standard Apache one, with the Maintainer as the party). Open an issue to discuss the change first, or write a connector or embedder of your own: the protocols and the SDK are MIT, and a connector in your own repository needs no agreement.

passageway-0.3.0/Dockerfile

@@ -0,0 +1,61 @@
+# passageway as a sidecar container: the server, the bundled connectors and embedders, and the default model baked in.
+#
+# Multi-stage: resolve the workspace into a venv with uv, fetch the pinned model and verify its checksums, then ship
+# only the venv, the model and the code on python-slim.
+#
+#   docker build -t passageway .          (add --build-arg WITH_BROWSER=1 for the sitemap connector's RENDER)
+#   docker run -p 8082:8082 -v passageway-data:/data -v ./passageway.toml:/config/passageway.toml \
+#     -e PASSAGEWAY_LOGIN_PASSWORD=... passageway
+
+# ---- builder: the venv with every workspace package ----
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
+ENV UV_PYTHON_PREFERENCE=only-system \
+    UV_PYTHON_DOWNLOADS=never
+WORKDIR /app
+COPY pyproject.toml uv.lock README.md ./
+COPY passageway/ passageway/
+COPY sdk/ sdk/
+COPY connectors/ connectors/
+COPY embedders/ embedders/
+ARG WITH_BROWSER=0
+RUN uv sync --frozen --no-dev --all-packages $([ "$WITH_BROWSER" = 1 ] && echo --all-extras)
+
+# ---- model: the default preset, pinned to a revision, every file verified by checksum ----
+FROM python:3.12-slim-bookworm AS model
+COPY --from=builder /app /app
+RUN /app/.venv/bin/passageway model download --model-dir /models/e5-small
+
+# ---- runtime ----
+FROM python:3.12-slim-bookworm
+# curl is used by the container healthcheck.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY --from=builder /app /app
+COPY --from=model /models /models
+# --build-arg WITH_BROWSER=1: Chromium for the sitemap connector's RENDER (about 400 MB more).
+ARG WITH_BROWSER=0
+ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
+RUN if [ "$WITH_BROWSER" = 1 ]; then /app/.venv/bin/playwright install --with-deps chromium && chmod -R a+rX /ms-playwright; fi
+RUN useradd --system --create-home --uid 1000 passageway && mkdir -p /data /config && chown passageway /data
+LABEL org.opencontainers.image.source="https://github.com/getpassageway/passageway" \
+      org.opencontainers.image.licenses="PolyForm-Noncommercial-1.0.0"
+USER passageway
+
+ARG APP_VERSION=dev
+# glibc keeps freed embedding buffers otherwise: these hold a full build at about 300 MB instead of 400.
+ENV PATH="/app/.venv/bin:$PATH" \
+    APP_VERSION=$APP_VERSION \
+    MALLOC_ARENA_MAX=2 \
+    MALLOC_TRIM_THRESHOLD_=65536 \
+    PASSAGEWAY_MODEL_DIR=/models/e5-small \
+    PASSAGEWAY_DATA_DIR=/data \
+    PASSAGEWAY_CONFIG=/config/passageway.toml \
+    PASSAGEWAY_HOST=0.0.0.0
+
+VOLUME /data
+EXPOSE 8082
+HEALTHCHECK --interval=60s --timeout=5s --start-period=120s --retries=3 \
+  CMD curl -sf -o /dev/null http://localhost:8082/health || exit 1
+CMD ["passageway"]