silkroute 0.1.0__tar.gz

silkroute-0.1.0/.github/workflows/pre-commit.yml

@@ -0,0 +1,17 @@
+name: pre-commit
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  prek:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --extra dev --extra tests
+      - uses: j178/prek-action@v2

silkroute-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,68 @@
+name: publish-pypi
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.12"
+
+      # The version is dynamic (hatch reads silkroute/__init__.py), so a tag can
+      # disagree with the package. Catch that before anything reaches PyPI, where
+      # a filename is permanent.
+      - name: Check the tag matches __version__
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          version="$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' silkroute/__init__.py)"
+          if [ -z "$version" ]; then
+            echo "::error::could not read __version__ from silkroute/__init__.py"
+            exit 1
+          fi
+          if [ "$TAG" != "v$version" ]; then
+            echo "::error::tag $TAG does not match silkroute.__version__ ($version)"
+            exit 1
+          fi
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/silkroute
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

silkroute-0.1.0/.github/workflows/refresh-fixtures.yml

@@ -0,0 +1,167 @@
+name: refresh-fixtures
+
+# Re-captures the frozen API fixtures in tests/fixtures/ from the live APIs twice
+# a month. Clean drift (offline suite still green) is committed straight to `dev`;
+# breaking drift goes to a PR against `dev` for a human to reconcile. Never runs
+# on push/PR: the offline test suite must stay offline.
+#
+# This file must live on the default branch for `schedule` to fire at all, but the
+# capture itself always runs against `dev` (see the checkout `ref` below).
+on:
+  schedule:
+    # 06:00 UTC on the 1st and the 15th.
+    - cron: "0 6 1,15 * *"
+  workflow_dispatch:
+    inputs:
+      apis:
+        description: "Space-separated API names to capture (empty = all)"
+        required: false
+        default: ""
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: refresh-fixtures
+  cancel-in-progress: false
+
+env:
+  TARGET: dev
+  PR_BRANCH: chore/refresh-fixtures
+
+jobs:
+  capture:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: dev
+
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra tests
+
+      - name: Validate api selection
+        env:
+          APIS: ${{ inputs.apis }}
+        run: |
+          if [ -n "$APIS" ] && ! printf '%s' "$APIS" | grep -qE '^[a-z0-9 ]+$'; then
+            echo "::error::invalid apis input: $APIS"
+            exit 1
+          fi
+
+      # Credentialed captures (biogrid, refseq, brenda) skip themselves with a log
+      # line when their secret is absent, so unset secrets are not an error.
+      - name: Capture fixtures
+        id: capture
+        continue-on-error: true
+        env:
+          SILKROUTE_CAPTURE: "1"
+          APIS: ${{ inputs.apis }}
+          SILKROUTE_BIOGRID_API_KEY: ${{ secrets.SILKROUTE_BIOGRID_API_KEY }}
+          SILKROUTE_REFSEQ_EMAIL: ${{ secrets.SILKROUTE_REFSEQ_EMAIL }}
+          SILKROUTE_BRENDA_EMAIL: ${{ secrets.SILKROUTE_BRENDA_EMAIL }}
+          SILKROUTE_BRENDA_PASSWORD: ${{ secrets.SILKROUTE_BRENDA_PASSWORD }}
+        run: |
+          # shellcheck disable=SC2086  # intentional word splitting: APIS is a list
+          uv run python -m tests._capture.capture $APIS 2>&1 | tee capture.log
+
+      - name: Detect drift
+        id: drift
+        run: |
+          if [ -n "$(git status --porcelain tests/fixtures)" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            git --no-pager diff --stat tests/fixtures
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Run offline test suite against the new fixtures
+        id: tests
+        if: steps.drift.outputs.changed == 'true'
+        continue-on-error: true
+        run: uv run pytest -q 2>&1 | tail -n 60 | tee pytest.log
+
+      - name: Configure git
+        if: steps.drift.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      # Suite still green on the fresh fixtures -> nothing for a human to decide.
+      - name: Commit to dev
+        if: steps.drift.outputs.changed == 'true' && steps.tests.outcome == 'success'
+        run: |
+          set -euo pipefail
+          git add tests/fixtures
+          git commit -m "test: refresh API fixtures from live APIs"
+          # Rebase onto whatever landed on dev while the capture was running; the
+          # commit only touches tests/fixtures so a conflict here is a real one.
+          git pull --rebase origin "$TARGET"
+          git push origin "HEAD:$TARGET"
+
+      # Suite broke -> an API changed shape. Park it on a branch and let a human
+      # reconcile the assertions.
+      - name: Open pull request
+        if: steps.drift.outputs.changed == 'true' && steps.tests.outcome != 'success'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CAPTURE_OUTCOME: ${{ steps.capture.outcome }}
+          TESTS_OUTCOME: ${{ steps.tests.outcome }}
+        run: |
+          set -euo pipefail
+          git switch -c "$PR_BRANCH"
+          git add tests/fixtures
+          git commit -m "test: refresh API fixtures from live APIs"
+          git push --force origin "$PR_BRANCH"
+
+          {
+            echo "Automated re-capture of \`tests/fixtures/\` from the live APIs."
+            echo
+            echo "- capture step: **$CAPTURE_OUTCOME**"
+            echo "- offline suite on the new fixtures: **$TESTS_OUTCOME**"
+            echo
+            echo "The suite no longer passes on the fresh fixtures, so this drift was"
+            echo "**not** committed to \`$TARGET\` directly. An API changed shape: update"
+            echo "the affected assertions on this branch (and re-run"
+            echo "\`REGEN_FIELD_BASELINE=1 uv run pytest\` if the field-coverage baseline"
+            echo "moved) before merging."
+            echo
+            echo "<details><summary>capture log</summary>"
+            echo
+            echo '```'
+            tail -n 60 capture.log
+            echo '```'
+            echo
+            echo "</details>"
+            if [ -f pytest.log ]; then
+              echo
+              echo "<details><summary>pytest tail</summary>"
+              echo
+              echo '```'
+              cat pytest.log
+              echo '```'
+              echo
+              echo "</details>"
+            fi
+          } > pr-body.md
+
+          if [ -n "$(gh pr list --head "$PR_BRANCH" --state open --json number --jq '.[].number')" ]; then
+            gh pr edit "$PR_BRANCH" --body-file pr-body.md
+          else
+            gh pr create \
+              --head "$PR_BRANCH" \
+              --base "$TARGET" \
+              --title "test: refresh API fixtures (suite needs reconciling)" \
+              --body-file pr-body.md
+          fi
+
+      - name: Report capture failures
+        if: steps.capture.outcome == 'failure'
+        run: |
+          echo "::error::capture exited non-zero; see the capture log for the failing APIs"
+          exit 1

silkroute-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,34 @@
+name: tests
+
+on:
+  push:
+    paths:
+      - "silkroute/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/tests.yml"
+  pull_request:
+    paths:
+      - "silkroute/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/tests.yml"
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --extra dev --extra tests --extra gui
+      - name: Run tests
+        run: uv run pytest -q

silkroute-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+.ipynb_checkpoints/
+
+# 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
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs / Editors
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+
+
+# Custom directories and files
+input/
+src/db
+output/
+tmp/
+results/
+src/.alphafold_cache/
+src/.pdb_cache/
+
+*.json
+*.csv
+*.cif
+*.pdb
+*.html
+*.log
+*.backup
+*.parquet
+.env
+
+!examples/data/*.csv
+
+# Test fixtures must be tracked despite the global *.json / *.csv rules above
+!tests/**/*.json
+!tests/**/*.csv
+!tests/**/

silkroute-0.1.0/AGENTS.md

@@ -0,0 +1,69 @@
+# AGENTS.md
+
+This file provides guidance to AI agents when working with code in this repository.
+
+## Project Overview
+
+**SilkRoute** is a Python library and CLI to download and integrate biological
+data from many web APIs (UniProt, AlphaFold, BioGRID, KEGG, ChEMBL, Reactome, etc.).
+It is part of the Kren AI Lab ecosystem alongside **Sylphy** (sequence encoders /
+embeddings) and **Roxy** (classical descriptors).
+
+Input: identifiers / queries per database. Output: parsed records as
+`polars.DataFrame` / JSON / XML, with on-disk caching.
+
+## Package Layout
+
+```
+silkroute/
+  __init__.py             # public API (lazy via __getattr__) + __version__
+  cli/
+    main.py               # Typer root app
+    interfaces/           # per-database CLI sub-apps
+  constants/              # per-database constants + DBConfig instances (databases.py)
+  core/
+    interfaces/
+      base.py             # BaseAPIInterface (fetch_single/fetch_batch/cache/parse)
+      <db>.py             # one client per database, subclass of BaseAPIInterface
+    utils/                # query builders, parsing helpers, BLAST
+    workflow/             # multi-step download workflows
+    cache.py, export.py, dbconfig.py, interfacesconfig.py
+  logging/                # get_logger, unified setup
+tests/                    # mirrors source tree, offline
+examples/                 # standalone demo scripts
+```
+
+## Development Commands
+
+This project uses `uv` and `taskipy`.
+
+```bash
+uv sync --extra dev --extra tests
+uv run task test          # pytest -q
+uv run task lint          # ruff check
+uv run task lint-fix
+uv run task format
+uv run task ty            # ty check
+uv run task pyrefly
+uv run silkroute --help
+```
+
+## Architecture Notes
+
+- New API clients inherit from `BaseAPIInterface` and declare their `DBConfig`
+  (URL + cache/config dirs) from `constants/databases.py`.
+- `fetch_single` / `fetch_batch` handle caching, optional parsing, and output
+  format conversion (json / dataframe / xml). `parse` + `fetch` are abstract.
+- Per-database field extraction is config-driven (YAML in the config dir).
+
+## Key Invariants
+
+- No import side effects: the top-level public API is lazy (`__getattr__`); importing
+  `silkroute` must not pull heavy deps (e.g. `zeep` for BRENDA).
+- Use `logging` (`get_logger`), never `print`.
+- A `fetch` override returns the empty of its own success type (a list endpoint
+  returns `[]`, an object endpoint `{}`); never `None`. The error-vs-empty reason
+  is recorded in `metadata.failed` (`request_error` / `empty_result`), not the
+  return value. (`chebi`/`pubchem` are genuinely method-polymorphic and return `{}`.)
+- Tests run offline: HTTP is mocked (`niquests_mock`) behind `conftest` fixtures.
+- Tests mirror the source layout.

silkroute-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

silkroute-0.1.0/DEVELOPMENT.md

@@ -0,0 +1,196 @@
+# Development
+
+This guide covers local setup, day-to-day commands, and the code structure behind
+SilkRoute.
+
+## Local Setup
+
+SilkRoute uses `uv` for environment management and `taskipy` for common developer
+commands.
+
+Install development dependencies:
+
+```bash
+uv sync --extra dev --extra tests
+```
+
+Editable install with `pip` also works:
+
+```bash
+pip install -e ".[dev,tests]"
+```
+
+## Common Commands
+
+Run tests:
+
+```bash
+uv run task test
+uv run task test-v
+uv run task test-cov
+uv run pytest tests/core/interfaces/test_reactome.py -v
+```
+
+Lint, format, and type-check:
+
+```bash
+uv run task lint
+uv run task lint-fix
+uv run task format
+uv run task sort-imports
+uv run task ty
+uv run task pyrefly
+```
+
+Build the package:
+
+```bash
+uv build
+```
+
+Smoke-test the CLI:
+
+```bash
+uv run silkroute --help
+```
+
+## Project Layout
+
+```text
+silkroute/
+├── cli/                  # Typer commands (root in cli/main.py)
+│   └── interfaces/       # Per-database CLI sub-apps
+├── constants/            # Per-database constants and DBConfig values
+├── core/
+│   ├── interfaces/       # BaseAPIInterface + per-database API clients
+│   ├── utils/            # Shared helpers (query builders, parsing, BLAST)
+│   ├── workflow/         # Multi-step download workflows
+│   ├── cache.py          # Cache helpers
+│   └── export.py         # Output/export helpers
+├── logging/              # Unified logging setup
+└── __init__.py           # Public API (lazy) + __version__
+
+tests/                    # Mirrors the source tree
+examples/                 # Scripts for manual exploration
+```
+
+## Design Rules
+
+- Avoid side effects on import (public top-level API is lazy via `__getattr__`).
+- Use logging instead of `print`.
+- New interfaces inherit from `BaseAPIInterface` and declare their `DBConfig`.
+- Keep the public API small and explicit.
+
+## Testing Notes
+
+The test suite is designed to run offline.
+
+- HTTP interactions are mocked (`niquests_mock`), isolated behind `conftest` fixtures.
+- Test layout mirrors the source layout.
+- New features should ship with focused unit tests and CLI coverage when applicable.
+
+### Offline interface suite and fixtures
+
+Every API interface has an offline test module under
+`tests/core/interfaces/test_<api>.py`. Each one replays a frozen API response
+from `tests/fixtures/<api>/<case>.json` and asserts three things:
+
+- **fetch** builds the right URL/params and unwraps the body as expected;
+- **parse** returns the expected keys/shape (not exact values);
+- **fetch_single** round-trips through the cache (1 request on the first call,
+  0 on the second).
+
+Non-HTTP / credentialed clients are mocked at the client boundary instead of via
+`niquests_mock`: BRENDA (zeep SOAP `Client`), RefSeq (`Bio.Entrez`), BioGRID (API key
+supplied explicitly), and the standalone UniProt id-mapping flow
+(submit → status → details → results).
+
+Fixtures are loaded with the helpers in `tests/_helpers.py`
+(`load_fixture` / `load_fixture_text`). They are committed despite the global
+`*.json` gitignore rule thanks to the `!tests/**/*.json` exception.
+
+### Regenerating fixtures (network-gated)
+
+`tests/_capture/capture.py` regenerates the fixtures from the real APIs. It is
+**never** run by the test suite (and never on push / pull request) and refuses to
+do anything unless `SILKROUTE_CAPTURE=1` is set:
+
+```bash
+SILKROUTE_CAPTURE=1 uv run python -m tests._capture.capture          # all APIs
+SILKROUTE_CAPTURE=1 uv run python -m tests._capture.capture rhea chebi
+```
+
+Each capture drives the real interface, so the request (URL, params, method,
+body) matches production exactly, and records the raw HTTP body the interface
+receives — the same payload the offline tests register with `niquests_mock`.
+
+Credentialed / non-HTTP APIs are captured only when their env vars are present
+(`SILKROUTE_BIOGRID_API_KEY`, `SILKROUTE_REFSEQ_EMAIL`,
+`SILKROUTE_BRENDA_EMAIL`/`SILKROUTE_BRENDA_PASSWORD`); otherwise they are skipped
+with a log line. These read from a gitignored `.env` at the repo root, loaded
+automatically by the capture script.
+
+Because fixtures are real bodies, re-capturing can change response shape and
+require updating the affected test assertions — that is expected and the point:
+the tests then reflect what the APIs actually return.
+
+### Scheduled re-capture (`refresh-fixtures` workflow)
+
+`.github/workflows/refresh-fixtures.yml` runs the capture script on the 1st and
+15th of every month at 06:00 UTC (also on `workflow_dispatch`, with an optional
+space-separated `apis` input). It always checks out and targets `dev`, never `main`
+— the file only lives on the default branch because that is where GitHub fires
+`schedule` from.
+
+What happens next depends on the offline suite, run in-job against the fresh
+fixtures:
+
+| fixtures changed | `pytest -q` | outcome |
+| --- | --- | --- |
+| no | not run | nothing; job green |
+| yes | passes | committed straight to `dev` |
+| yes | fails | pushed to `chore/refresh-fixtures`, PR opened against `dev` |
+
+So a PR appearing means an API changed shape and the assertions need reconciling:
+fix them on the branch, and re-run `REGEN_FIELD_BASELINE=1 uv run pytest` if the
+field-coverage baseline moved. The PR body carries the capture log and the tail of
+the failing run. A re-run reuses the same branch and PR rather than stacking new
+ones.
+
+The job itself goes red only when the capture script exits non-zero, so a dead or
+renamed endpoint is visible in the Actions tab. That is independent of the commit
+decision: a partial capture whose fixtures still pass is committed to `dev` (the
+APIs that answered gave valid bodies) *and* leaves the run red for the one that
+did not.
+
+Credentialed captures need repository secrets with the same names as the env vars
+above (`SILKROUTE_BIOGRID_API_KEY`, `SILKROUTE_REFSEQ_EMAIL`,
+`SILKROUTE_BRENDA_EMAIL`, `SILKROUTE_BRENDA_PASSWORD`); without them those three
+APIs skip themselves and their fixtures stay frozen.
+
+## Releasing
+
+`.github/workflows/publish-pypi.yml` builds with `uv build` and publishes to PyPI
+via [trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC, no API
+token stored in the repo). It triggers on any `v*` tag, and on `workflow_dispatch`
+for a build-only dry run — the `publish` job is gated on `startsWith(github.ref,
+'refs/tags/v')`, so a manual run only produces artifacts.
+
+The version is dynamic: hatch reads `__version__` from `silkroute/__init__.py`. To
+cut a release, bump it, commit, then tag the same number:
+
+```bash
+git tag v0.2.0 && git push origin v0.2.0
+```
+
+The build job refuses to continue when the tag and `__version__` disagree, because
+a filename on PyPI cannot be reused after upload.
+
+One-time setup on PyPI: add a trusted publisher for project `silkroute` with owner
+`kren-ai-lab`, repository `silk-route`, workflow `publish-pypi.yml`, environment
+`pypi`. The `pypi` GitHub environment is where any release approvals or reviewers
+would go.
+
+## Additional Context
+
+For more architecture detail, see [AGENTS.md](AGENTS.md).

silkroute-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kren AI Lab
+
+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.