tcr-explorer 0.1.0__tar.gz

tcr_explorer-0.1.0/LICENSE

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

tcr_explorer-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: tcr-explorer
+Version: 0.1.0
+Summary: Federated TCR analysis: records retrieval, germline allele assignment, reconstruction, dossiers, and similarity, over a web UI, REST API, and MCP server
+Author: Kilian Maire
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KilianMaire/tcr-explorer
+Project-URL: Issues, https://github.com/KilianMaire/tcr-explorer/issues
+Keywords: TCR,T-cell-receptor,immunology,AIRR,VDJ,germline,IMGT,VDJdb,IEDB,McPAS,bioinformatics,MCP,immune-repertoire,epitope
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: starlette<0.48,>=0.40
+Requires-Dist: fastapi==0.116.1
+Requires-Dist: uvicorn[standard]==0.35.0
+Requires-Dist: pydantic==2.11.7
+Requires-Dist: python-multipart==0.0.20
+Requires-Dist: httpx==0.28.1
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pyarrow>=15.0.0
+Requires-Dist: biopython==1.85
+Requires-Dist: tidytcells>=2.0.0
+Requires-Dist: platformdirs>=4
+Requires-Dist: stitchr>=1.3
+Provides-Extra: ui-legacy
+Requires-Dist: streamlit>=1.35.0; extra == "ui-legacy"
+Dynamic: license-file
+
+# TCR Explorer
+
+A federated tool for T cell receptor analysis. It retrieves known TCR records (VDJdb, IEDB, McPAS, TCR3d), assigns germline V and J genes down to the allele level, reconstructs full membrane bound chains, builds per receptor dossiers, and finds similar receptors. The same pure functions back a web UI, a REST API, and an MCP server, so an assistant can drive the whole tool.
+
+## How the data works
+
+The package ships the IMGT germline (bundled under CC BY 4.0) but **no record datasets**. On first use you run `tcr-explorer-refresh` once. It downloads the four record datasets (VDJdb, IEDB, McPAS, TCR3d) from each source's own official endpoint into a local folder, then harmonizes them into a single records index. After that, everything runs in one process against that local index, offline, until you refresh again to pull fresh data.
+
+This means the tool never redistributes the record datasets (their licenses vary): each user fetches those directly from the source under that source's own terms. The germline is different: IMGT is CC BY 4.0, which permits redistribution with attribution, so it is bundled and germline features work offline out of the box. To pull a newer IMGT germline yourself, run `tcr-explorer-refresh --germline`. See [Data sources](#data-sources).
+
+## Requirements
+
+- Python 3.11 or newer.
+- Internet access for the initial `tcr-explorer-refresh` (a few minutes, roughly 60 MB). Offline afterward until you refresh.
+
+## Install
+
+```bash
+pip install tcr-explorer
+```
+
+Or from a checkout:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+## First run
+
+```bash
+tcr-explorer-refresh
+```
+
+This downloads the four record datasets and builds the index into a local data folder (a platform specific user data directory, or wherever `TCR_EXPLORER_DATA` points). The IMGT germline is already bundled, so this step does not touch IMGT. Re-run it any time to update the records. If a tool is used before the first refresh, it returns a clear message asking you to run this command.
+
+To pull a fresher IMGT germline than the bundled one, run `tcr-explorer-refresh --germline` (needs IMGT/GENE-DB reachable). It writes into the local data folder, which the tool prefers over the bundled copy.
+
+## Use it
+
+Two front doors, both a single process.
+
+### As an MCP server (recommended)
+
+Point your own assistant at TCR Explorer over MCP and ask questions in plain language. This targets Claude Desktop and Claude Code, which run a local stdio MCP server. ChatGPT does not run local stdio MCP servers the same way, so use Claude for the paste and go flow. See [Connect your assistant](#connect-your-assistant).
+
+### As a web app and REST API
+
+```bash
+PYTHONPATH=src uvicorn tcr_explorer.api:app --port 8000
+```
+
+Open the query box at <http://localhost:8000/ui>, or call the REST API directly. Health check:
+
+```bash
+curl http://localhost:8000/health   # {"status":"ok"}
+```
+
+## Connect your assistant
+
+TCR Explorer ships an MCP server (console entry point `tcr-explorer-mcp`). Add this to your assistant's MCP configuration:
+
+```json
+{"mcpServers":{"tcr-explorer":{"command":"uvx","args":["--from","tcr-explorer","tcr-explorer-mcp"]}}}
+```
+
+Or paste this prompt into Claude to have it set the connection up for you:
+
+```
+Set up the TCR Explorer MCP server so you can answer T cell receptor questions against real immunology databases. First install it (pip install tcr-explorer, or use uvx --from tcr-explorer), then run tcr-explorer-refresh once in a terminal to download the datasets into a local folder (a few minutes). Then add an MCP server named tcr-explorer that runs `uvx --from tcr-explorer tcr-explorer-mcp` (if uvx is unavailable, run python -m tcr_explorer.mcp_server). It exposes these read only tools: retrieve_tcr_records, assign_tcr_alleles, get_tcr_dossier, find_similar_tcrs, align_tcr_genes, and ask_tcr. If a tool reports the data is not downloaded yet, tell me to run tcr-explorer-refresh. After adding it, confirm the connection and suggest three example questions I can ask.
+```
+
+Until the package is on PyPI, the git form works: `uvx --from git+<your-repo-url> tcr-explorer-mcp`.
+
+The read only MCP tools are `retrieve_tcr_records`, `assign_tcr_alleles`, `get_tcr_dossier`, `find_similar_tcrs`, `align_tcr_genes`, and `ask_tcr`.
+
+## REST API
+
+All of these run in process against the local index.
+
+### Unified query box
+
+**POST** `/v1/tcr/query` routes a single input (a CDR3, a full chain, a gene name, a record id, or a phrase) to the right tool.
+
+```bash
+curl -s -X POST http://localhost:8000/v1/tcr/query \
+  -H "Content-Type: application/json" \
+  -d '{"query":"CASSLGGAGGTDTQYF","species":"human"}'
+```
+
+### Germline assignment
+
+**POST** `/v1/tcr/assign` assigns a TCR sequence (nucleotide or amino acid, CDR3, region, or full chain) to V and J alleles, with per region identity, co optimal ties, CDR3 extraction, and an honest refusal to call a V allele from a bare CDR3.
+
+```bash
+curl -s -X POST http://localhost:8000/v1/tcr/assign \
+  -H "Content-Type: application/json" \
+  -d '{"sequence":"CASSLGGAGGTDTQYF","species":"human"}'
+```
+
+### Records retrieval
+
+**POST** `/v1/tcr/records` searches the harmonized records index.
+
+```bash
+curl -s -X POST http://localhost:8000/v1/tcr/records \
+  -H "Content-Type: application/json" \
+  -d '{"cdr3":"CASSLGGAGGTDTQYF","species":"human","limit":20}'
+```
+
+### Chain reconstruction
+
+**POST** `/reconstruct` builds a full membrane bound chain. Provide V, J, and CDR3, or a CDR3 alone (V and J are inferred from the records that carry the same CDR3).
+
+```bash
+curl -s -X POST http://localhost:8000/reconstruct \
+  -H "Content-Type: application/json" \
+  -d '{"cdr3_aa":"CASSLGGAGGTDTQYF","species":"human"}'
+```
+
+### CDR1 and CDR2 prediction
+
+**GET** `/predict/cdr` returns germline CDR1 and CDR2 for a TCR V gene from IMGT germline data.
+
+```bash
+curl "http://localhost:8000/predict/cdr?v_gene=TRBV12-3&species=human"
+```
+
+## Optional: MHC allele sequences
+
+The records index does not contain MHC allele sequences. If you want live lookup of those from EBI IMGT/HLA and IPD-MHC, start the optional hla and mhc proxies with one command:
+
+```bash
+docker-compose up
+```
+
+The `/search` endpoint is scoped to these two sources: `{"source": "hla"}` or `{"source": "mhc"}`. Any other source returns HTTP 400 pointing at `/v1/tcr/records`, which is where TCR record search lives.
+
+## Environment variables
+
+All optional.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TCR_EXPLORER_DATA` | platform user data dir | Local folder where `tcr-explorer-refresh` downloads datasets and builds the index |
+| `TCR_EXPLORER_MAX_AGE_DAYS` | `30` | Age after which the local index is flagged stale (a refresh is suggested in query warnings, never forced) |
+| `RECORDS_INDEX_PATH` | `<data dir>/records_index.parquet` | Override the records index path directly |
+| `HLA_SERVER_URL` | `http://127.0.0.1:8101` | HLA allele sequence proxy (optional) |
+| `MHC_SERVER_URL` | `http://127.0.0.1:8105` | IPD-MHC allele sequence proxy (optional) |
+| `LLM_BASE_URL` | *(empty)* | OpenAI compatible endpoint for the free text `ask` path (falls back to a heuristic parser when unset) |
+| `LLM_MODEL` | `local-model` | Model id for the `ask` path |
+
+## Data sources
+
+TCR Explorer cites the following. The four record datasets are downloaded on your machine from their official endpoints and are not redistributed; the IMGT germline is bundled with the package under CC BY 4.0. Please cite the ones you use.
+
+- **VDJdb** (downloaded). Goncharov M. et al. VDJdb in the pandemic era: a compendium of T cell receptors specific for SARS-CoV-2. Nature Methods, 2022. <https://github.com/antigenomics/vdjdb-db>
+- **IEDB** (downloaded, CC BY 4.0). Vita R. et al. The Immune Epitope Database (IEDB): 2024 update. Nucleic Acids Research, 2025. <https://www.iedb.org>
+- **McPAS-TCR** (downloaded). Tickotsky N. et al. McPAS-TCR: a manually curated catalogue of pathology associated T cell receptor sequences. Bioinformatics, 2017. <https://friedmanlab.weizmann.ac.il/McPAS-TCR/>
+- **TCR3d** (downloaded). Lin V. et al. TCR3d 2.0: expanding the T cell receptor structure database. Nucleic Acids Research, 2025. <https://tcr3d.ibbr.umd.edu>
+- **IMGT germline** (bundled, CC BY 4.0, release 20268-7). Lefranc M-P. et al. IMGT, the international ImMunoGeneTics information system. Reformatted via stitchr and IMGTgeneDL (MIT). See `src/tcr_explorer/data/germline/ATTRIBUTION.md`. <https://www.imgt.org>
+
+## Run tests
+
+```bash
+PYTHONPATH=src pytest tests/ -v
+```
+
+## Architecture
+
+The core is a set of single source pure functions (records retrieval, germline assignment, reconstruction, dossiers, similarity) that read from the locally downloaded index. The REST API, the MCP server, and the web query box all call these same functions in one process.
+
+```
+        MCP server        REST API + /ui query box
+             \                    /
+              \                  /
+        single source pure functions
+        (records, assign, reconstruct,
+         dossier, similar)
+                   |
+        local index (built by tcr-explorer-refresh
+        from the downloaded records) + bundled IMGT germline
+```
+
+IMGT (IMGT/HLA, IMGT/GENE-DB, IMGT germline, IMGT numbering) is a data source cited throughout. TCR Explorer is an independent tool and is not affiliated with IMGT.

tcr_explorer-0.1.0/README.md

@@ -0,0 +1,186 @@
+# TCR Explorer
+
+A federated tool for T cell receptor analysis. It retrieves known TCR records (VDJdb, IEDB, McPAS, TCR3d), assigns germline V and J genes down to the allele level, reconstructs full membrane bound chains, builds per receptor dossiers, and finds similar receptors. The same pure functions back a web UI, a REST API, and an MCP server, so an assistant can drive the whole tool.
+
+## How the data works
+
+The package ships the IMGT germline (bundled under CC BY 4.0) but **no record datasets**. On first use you run `tcr-explorer-refresh` once. It downloads the four record datasets (VDJdb, IEDB, McPAS, TCR3d) from each source's own official endpoint into a local folder, then harmonizes them into a single records index. After that, everything runs in one process against that local index, offline, until you refresh again to pull fresh data.
+
+This means the tool never redistributes the record datasets (their licenses vary): each user fetches those directly from the source under that source's own terms. The germline is different: IMGT is CC BY 4.0, which permits redistribution with attribution, so it is bundled and germline features work offline out of the box. To pull a newer IMGT germline yourself, run `tcr-explorer-refresh --germline`. See [Data sources](#data-sources).
+
+## Requirements
+
+- Python 3.11 or newer.
+- Internet access for the initial `tcr-explorer-refresh` (a few minutes, roughly 60 MB). Offline afterward until you refresh.
+
+## Install
+
+```bash
+pip install tcr-explorer
+```
+
+Or from a checkout:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+## First run
+
+```bash
+tcr-explorer-refresh
+```
+
+This downloads the four record datasets and builds the index into a local data folder (a platform specific user data directory, or wherever `TCR_EXPLORER_DATA` points). The IMGT germline is already bundled, so this step does not touch IMGT. Re-run it any time to update the records. If a tool is used before the first refresh, it returns a clear message asking you to run this command.
+
+To pull a fresher IMGT germline than the bundled one, run `tcr-explorer-refresh --germline` (needs IMGT/GENE-DB reachable). It writes into the local data folder, which the tool prefers over the bundled copy.
+
+## Use it
+
+Two front doors, both a single process.
+
+### As an MCP server (recommended)
+
+Point your own assistant at TCR Explorer over MCP and ask questions in plain language. This targets Claude Desktop and Claude Code, which run a local stdio MCP server. ChatGPT does not run local stdio MCP servers the same way, so use Claude for the paste and go flow. See [Connect your assistant](#connect-your-assistant).
+
+### As a web app and REST API
+
+```bash
+PYTHONPATH=src uvicorn tcr_explorer.api:app --port 8000
+```
+
+Open the query box at <http://localhost:8000/ui>, or call the REST API directly. Health check:
+
+```bash
+curl http://localhost:8000/health   # {"status":"ok"}
+```
+
+## Connect your assistant
+
+TCR Explorer ships an MCP server (console entry point `tcr-explorer-mcp`). Add this to your assistant's MCP configuration:
+
+```json
+{"mcpServers":{"tcr-explorer":{"command":"uvx","args":["--from","tcr-explorer","tcr-explorer-mcp"]}}}
+```
+
+Or paste this prompt into Claude to have it set the connection up for you:
+
+```
+Set up the TCR Explorer MCP server so you can answer T cell receptor questions against real immunology databases. First install it (pip install tcr-explorer, or use uvx --from tcr-explorer), then run tcr-explorer-refresh once in a terminal to download the datasets into a local folder (a few minutes). Then add an MCP server named tcr-explorer that runs `uvx --from tcr-explorer tcr-explorer-mcp` (if uvx is unavailable, run python -m tcr_explorer.mcp_server). It exposes these read only tools: retrieve_tcr_records, assign_tcr_alleles, get_tcr_dossier, find_similar_tcrs, align_tcr_genes, and ask_tcr. If a tool reports the data is not downloaded yet, tell me to run tcr-explorer-refresh. After adding it, confirm the connection and suggest three example questions I can ask.
+```
+
+Until the package is on PyPI, the git form works: `uvx --from git+<your-repo-url> tcr-explorer-mcp`.
+
+The read only MCP tools are `retrieve_tcr_records`, `assign_tcr_alleles`, `get_tcr_dossier`, `find_similar_tcrs`, `align_tcr_genes`, and `ask_tcr`.
+
+## REST API
+
+All of these run in process against the local index.
+
+### Unified query box
+
+**POST** `/v1/tcr/query` routes a single input (a CDR3, a full chain, a gene name, a record id, or a phrase) to the right tool.
+
+```bash
+curl -s -X POST http://localhost:8000/v1/tcr/query \
+  -H "Content-Type: application/json" \
+  -d '{"query":"CASSLGGAGGTDTQYF","species":"human"}'
+```
+
+### Germline assignment
+
+**POST** `/v1/tcr/assign` assigns a TCR sequence (nucleotide or amino acid, CDR3, region, or full chain) to V and J alleles, with per region identity, co optimal ties, CDR3 extraction, and an honest refusal to call a V allele from a bare CDR3.
+
+```bash
+curl -s -X POST http://localhost:8000/v1/tcr/assign \
+  -H "Content-Type: application/json" \
+  -d '{"sequence":"CASSLGGAGGTDTQYF","species":"human"}'
+```
+
+### Records retrieval
+
+**POST** `/v1/tcr/records` searches the harmonized records index.
+
+```bash
+curl -s -X POST http://localhost:8000/v1/tcr/records \
+  -H "Content-Type: application/json" \
+  -d '{"cdr3":"CASSLGGAGGTDTQYF","species":"human","limit":20}'
+```
+
+### Chain reconstruction
+
+**POST** `/reconstruct` builds a full membrane bound chain. Provide V, J, and CDR3, or a CDR3 alone (V and J are inferred from the records that carry the same CDR3).
+
+```bash
+curl -s -X POST http://localhost:8000/reconstruct \
+  -H "Content-Type: application/json" \
+  -d '{"cdr3_aa":"CASSLGGAGGTDTQYF","species":"human"}'
+```
+
+### CDR1 and CDR2 prediction
+
+**GET** `/predict/cdr` returns germline CDR1 and CDR2 for a TCR V gene from IMGT germline data.
+
+```bash
+curl "http://localhost:8000/predict/cdr?v_gene=TRBV12-3&species=human"
+```
+
+## Optional: MHC allele sequences
+
+The records index does not contain MHC allele sequences. If you want live lookup of those from EBI IMGT/HLA and IPD-MHC, start the optional hla and mhc proxies with one command:
+
+```bash
+docker-compose up
+```
+
+The `/search` endpoint is scoped to these two sources: `{"source": "hla"}` or `{"source": "mhc"}`. Any other source returns HTTP 400 pointing at `/v1/tcr/records`, which is where TCR record search lives.
+
+## Environment variables
+
+All optional.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TCR_EXPLORER_DATA` | platform user data dir | Local folder where `tcr-explorer-refresh` downloads datasets and builds the index |
+| `TCR_EXPLORER_MAX_AGE_DAYS` | `30` | Age after which the local index is flagged stale (a refresh is suggested in query warnings, never forced) |
+| `RECORDS_INDEX_PATH` | `<data dir>/records_index.parquet` | Override the records index path directly |
+| `HLA_SERVER_URL` | `http://127.0.0.1:8101` | HLA allele sequence proxy (optional) |
+| `MHC_SERVER_URL` | `http://127.0.0.1:8105` | IPD-MHC allele sequence proxy (optional) |
+| `LLM_BASE_URL` | *(empty)* | OpenAI compatible endpoint for the free text `ask` path (falls back to a heuristic parser when unset) |
+| `LLM_MODEL` | `local-model` | Model id for the `ask` path |
+
+## Data sources
+
+TCR Explorer cites the following. The four record datasets are downloaded on your machine from their official endpoints and are not redistributed; the IMGT germline is bundled with the package under CC BY 4.0. Please cite the ones you use.
+
+- **VDJdb** (downloaded). Goncharov M. et al. VDJdb in the pandemic era: a compendium of T cell receptors specific for SARS-CoV-2. Nature Methods, 2022. <https://github.com/antigenomics/vdjdb-db>
+- **IEDB** (downloaded, CC BY 4.0). Vita R. et al. The Immune Epitope Database (IEDB): 2024 update. Nucleic Acids Research, 2025. <https://www.iedb.org>
+- **McPAS-TCR** (downloaded). Tickotsky N. et al. McPAS-TCR: a manually curated catalogue of pathology associated T cell receptor sequences. Bioinformatics, 2017. <https://friedmanlab.weizmann.ac.il/McPAS-TCR/>
+- **TCR3d** (downloaded). Lin V. et al. TCR3d 2.0: expanding the T cell receptor structure database. Nucleic Acids Research, 2025. <https://tcr3d.ibbr.umd.edu>
+- **IMGT germline** (bundled, CC BY 4.0, release 20268-7). Lefranc M-P. et al. IMGT, the international ImMunoGeneTics information system. Reformatted via stitchr and IMGTgeneDL (MIT). See `src/tcr_explorer/data/germline/ATTRIBUTION.md`. <https://www.imgt.org>
+
+## Run tests
+
+```bash
+PYTHONPATH=src pytest tests/ -v
+```
+
+## Architecture
+
+The core is a set of single source pure functions (records retrieval, germline assignment, reconstruction, dossiers, similarity) that read from the locally downloaded index. The REST API, the MCP server, and the web query box all call these same functions in one process.
+
+```
+        MCP server        REST API + /ui query box
+             \                    /
+              \                  /
+        single source pure functions
+        (records, assign, reconstruct,
+         dossier, similar)
+                   |
+        local index (built by tcr-explorer-refresh
+        from the downloaded records) + bundled IMGT germline
+```
+
+IMGT (IMGT/HLA, IMGT/GENE-DB, IMGT germline, IMGT numbering) is a data source cited throughout. TCR Explorer is an independent tool and is not affiliated with IMGT.

tcr_explorer-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tcr-explorer"
+version = "0.1.0"
+description = "Federated TCR analysis: records retrieval, germline allele assignment, reconstruction, dossiers, and similarity, over a web UI, REST API, and MCP server"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kilian Maire" }]
+keywords = [
+    "TCR", "T-cell-receptor", "immunology", "AIRR", "VDJ", "germline",
+    "IMGT", "VDJdb", "IEDB", "McPAS", "bioinformatics", "MCP",
+    "immune-repertoire", "epitope",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "mcp>=1.0.0,<2",
+    "starlette>=0.40,<0.48",
+    "fastapi==0.116.1",
+    "uvicorn[standard]==0.35.0",
+    "pydantic==2.11.7",
+    "python-multipart==0.0.20",
+    "httpx==0.28.1",
+    "pandas>=2.0.0",
+    "pyarrow>=15.0.0",
+    "biopython==1.85",
+    "tidytcells>=2.0.0",
+    "platformdirs>=4",
+    "stitchr>=1.3",
+]
+
+[project.optional-dependencies]
+ui-legacy = ["streamlit>=1.35.0"]
+
+[project.scripts]
+tcr-explorer-mcp = "tcr_explorer.mcp_server:main"
+tcr-explorer-refresh = "tcr_explorer.bootstrap:main"
+
+[project.urls]
+Homepage = "https://github.com/KilianMaire/tcr-explorer"
+Issues = "https://github.com/KilianMaire/tcr-explorer/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tcr_explorer = [
+    "py.typed",
+    "data/*.json",
+    "data/germline/*.md",
+    "data/germline/*/*.fasta",
+    "data/germline/*/*.tsv",
+    "data/germline/*/*.txt",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "."]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

tcr_explorer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tcr_explorer-0.1.0/src/tcr_explorer/__init__.py

@@ -0,0 +1 @@
+__all__ = []

tcr_explorer-0.1.0/src/tcr_explorer/annotator.py

@@ -0,0 +1,66 @@
+"""
+Annotator interface: selects between IgBLAST (authoritative, deferred) and the
+always-available k-mer aligner fallback (Task 3).
+
+Selection rule: IgBLAST is only attempted when mode=="full", the input is
+nucleotide (not protein), and the `igblastn` binary is present on PATH. The
+actual subprocess invocation is deferred (`_run_igblast` is a stub returning
+None), so this module currently always falls through to the k-mer backend;
+the point of this module is the selection/fallback logic and the
+`igblast_unavailable` warning, not the IgBLAST call itself.
+"""
+from __future__ import annotations
+import shutil
+from dataclasses import dataclass, field
+from typing import Optional
+from .kmer_aligner import annotate_sequence, KmerAnnotation
+
+
+@dataclass
+class Annotation:
+    v_call: Optional[str] = None
+    j_call: Optional[str] = None
+    d_call: Optional[str] = None
+    v_score: Optional[float] = None
+    j_score: Optional[float] = None
+    chain: str = "unknown"
+    source: str = "kmer_align"
+    confidence: str = "low"
+    warnings: list[tuple[str, str]] = field(default_factory=list)
+
+
+def igblast_available() -> bool:
+    return shutil.which("igblastn") is not None
+
+
+def _run_igblast(seq: str, species: str) -> Optional[Annotation]:
+    # Deferred: real igblastn -outfmt 19 invocation + AIRR TSV parse.
+    # Returning None signals "not implemented / failed" so callers fall back.
+    return None
+
+
+def _from_kmer(k: KmerAnnotation, source: str, confidence: str) -> Annotation:
+    return Annotation(
+        v_call=k.v_call, j_call=k.j_call, d_call=k.d_call,
+        v_score=k.v_score, j_score=k.j_score, chain=k.chain,
+        source=source, confidence=confidence, warnings=list(k.warnings),
+    )
+
+
+def annotate(seq: str, species: str, is_protein: bool, mode: str) -> Annotation:
+    use_igblast = (mode == "full") and (not is_protein) and igblast_available()
+    if use_igblast:
+        res = _run_igblast(seq, species)
+        if res is not None:
+            res.source, res.confidence = "igblast", "high"
+            return res
+        # fell through: igblast present but failed
+
+    k = annotate_sequence(seq, species, is_protein)
+    ann = _from_kmer(k, "kmer_align", "medium" if not is_protein else "low")
+    if mode == "full" and not is_protein and not igblast_available():
+        ann.warnings.append((
+            "igblast_unavailable",
+            "igblastn not found on PATH; used the k-mer backend",
+        ))
+    return ann