28 improve code structure

.claude/rules/docs.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "docs/**"
+  - "mkdocs.yml"
+---
+
+# Documentation Rules
+
+- Write docs in Markdown with clear headings and code examples.
+- Update `mkdocs.yml` navigation when adding new docs.
+- Keep `README.md` concise, and move long explanations to `/docs`.
+- Use Python code fences (```python … ```) in examples.

.claude/rules/git-workflow.md

@@ -0,0 +1,6 @@
+# Git Workflow
+
+- Do not call `git commit`.
+- Staging and inspection commands (`git status`, `git diff`, `git log`) are fine.
+- Prefix commits with `uv run` so pre-commit hooks use the correct environment, e.g.
+  `uv run git commit -m "message"`.

.claude/rules/pydantic-usage.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Pydantic Rules
+
+- Use `pydantic.BaseModel` for request/response schemas.
+- For configuration, use `pydantic_settings.BaseSettings` (v2).
+- Always provide default values or use `...` for required fields.
+- Use model validators (`@field_validator`, `@model_validator`) instead of custom init logic.
+- Keep models small and focused on one purpose.

.claude/rules/python-run.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "**/*.py"
+  - "run/**"
+---
+
+# Running Python code
+
+- **Do not** run `python3 -c` directly.
+- Always invoke Python code using `uv run python <script>` or `uv run <module>` when
+  executing project scripts.
+- Use the `uv` environment so that dependencies from `uv.lock` are respected.
+- This applies to both interactive code execution and testing.

.claude/rules/python-style.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Python Coding Rules
+
+- Use python 3.12 conventions: use `type | None` instead of `Optional` etc
+- Use type hints everywhere (PEP 484).
+- Use snake_case for functions and variables, PascalCase for classes.
+- Avoid unused imports.
+- Use `async`/`await` where appropriate.
+- Always keep functions small and composable.
+- Avoid using hasattr at all costs, it's not safe

.claude/rules/tests.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - "test/**/*.py"
+---
+
+# Testing Guidelines
+
+- Use `pytest` with descriptive test function names.
+- Prefer fixtures over global state.
+- For async code, use `pytest-asyncio`.
+- Ensure test coverage for:
+  - Pydantic model validation
+  - Env config via `BaseSettings`
+  - Error cases and edge cases
+- Run tests with `uv run pytest test`.

.claude/rules/uv-deps.md

@@ -0,0 +1,10 @@
+---
+paths:
+  - "pyproject.toml"
+  - "uv.lock"
+---
+
+# Dependency Management
+
+- Pin versions in `pyproject.toml` for reproducibility.
+- Run `uv pip check` to validate the dependency tree.

.cursorignore

@@ -0,0 +1,25 @@
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.egg-info/
+site/
+dist/
+build/
+
+# Trained artifacts and large outputs
+models/
+reports/
+nbs/
+debug/
+*.pth
+*.bin
+*.pt
+*.pkl
+*.joblib
+*.parquet
+*.gz
+
+# HuggingFace / spaCy caches (outside repo but common nearby)
+.cache/

.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+
+updates:
+-   package-ecosystem: uv
+    directory: /
+    schedule:
+        interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+        python-minor-patch:
+            update-types:
+            -   minor
+            -   patch
+
+-   package-ecosystem: github-actions
+    directory: /
+    schedule:
+        interval: weekly
+    open-pull-requests-limit: 5

.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: test
+
+on:
+    pull_request:
+    push:
+        branches: [main]
+
+jobs:
+    pytest:
+        runs-on: ubuntu-latest
+        timeout-minutes: 60
+        steps:
+        -   uses: actions/checkout@v5
+        -   name: Install uv
+            uses: astral-sh/setup-uv@v7
+            with:
+                version: "0.10.12"
+                enable-cache: true
+
+        # The dev extra pins en_core_web_lg, so the tests covering tokenization, span
+        # mapping and the HF embedding path actually run here. They skip themselves when
+        # the model is absent, which is how a removed transformers API once reached main.
+        -   name: Install dependencies (including dev)
+            run: uv sync --extra dev
+
+        -   name: Cache Hugging Face weights
+            uses: actions/cache@v4
+            with:
+                path: ~/.cache/huggingface
+                key: hf-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+                restore-keys: hf-${{ runner.os }}-
+
+        -   name: Run tests
+            run: uv run pytest test

.gitignore

@@ -165,6 +165,16 @@ cython_debug/
 nbs/
 debug/
 
-reports/
-paper/
+# Anchored: measurement output at the repo root. Unanchored, this also matched the
+# package source directory pelinker/reports/, which then never reached the repository.
+/reports/
+models/
+**/models/
+*.pth
+*.bin
+*.pt
+*.pkl
+*.joblib
 pelinker/store/*gz
+
+.env*