tide2 1.1.0__tar.gz

tide2-1.1.0/.gitignore

@@ -0,0 +1,81 @@
+# Python
+__pycache__/
+*.egg-info/
+tide2.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# Buildx cache
+.buildx-cache/
+.buildx-cache-cpu/
+.buildx-cache-gpu/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# IDE & OS
+.DS_Store
+.ipynb_checkpoints/
+
+# Environment & secrets
+.env
+.env.local
+keys/
+
+# IDE
+.vscode/
+
+# Logs
+*.log
+logs/
+
+# Local data & temp files
+data/
+local/
+tmp/
+
+# Cryptographic key material
+notebooks/sample_data/pipeline_output/salt.bin
+notebooks/sample_data/pipeline_output/key.bin
+
+# Coverage artifacts (regenerate in CI)
+coverage-badge.svg
+coverage.xml
+
+# Project-specific sample data & outputs
+notebooks/sample_data/sample_output/*
+notebooks/sample_data/sample_output_multi_gpu/*
+notebooks/sample_data/multi_gpu_output/*
+notebooks/sample_data/output_ray/*
+notebooks/sample_data/stanford/*
+notebooks/sample_data/aimi_v1_output/*
+notebooks/sample_data/biomodern_bert_output/*
+notebooks/sample_data_i2b2/*
+notebooks/evaluation/phi_evaluation_results_files/*
+examples/
+notebooks/sample_data/pipeline_output
+notebooks/sample_data/pipeline_output_mac_test
+notebooks/sample_data/pipeline_output_cpu_test
+
+# Docs (generated)
+docs/
+
+# Test fixtures
+tests/cluster/fixtures/create_fixtures.py
+tests/cluster/smoke_test/*
+
+# Misc
+TODO.md
+
+/model/**
+
+# Versioning is automatically handled
+src/tide2/_version.py
+
+temp/**

tide2-1.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.0.0 (2026-06-12)
+
+_This release is published under the MIT License._
+
+### Bug Fixes
+
+- Fetch base SHA before pre-commit diff on PRs
+  ([#14](https://github.com/susom/tide2-core/pull/14),
+  [`3a4e4d2`](https://github.com/susom/tide2-core/commit/3a4e4d23da60ae120beb5aa40f44ab9b8738455d))
+
+- **anonymizer**: Resolve patient_uid name collision causing silent 0-row output
+  ([`34e0619`](https://github.com/susom/tide2-core/commit/34e0619c1644f8fbf7b895482d993bd2dbf32c59))
+
+### Documentation
+
+- Correct README and runner docstrings to match code
+  ([`f4b09b3`](https://github.com/susom/tide2-core/commit/f4b09b35655d80cc68d6cbe5b878b0e47ede2644))
+
+- Remove pre-release private/do-not-publish notice
+  ([`fabef8f`](https://github.com/susom/tide2-core/commit/fabef8f4d6cbcb405b7351fb8e20b5ba752416e1))
+
+- Update clone URL and venv path to tide2-core
+  ([`d440c40`](https://github.com/susom/tide2-core/commit/d440c40719afafb93f821e70739de574c651a677))
+
+### Features
+
+- Add OSSF Scorecard support (score 9.1/10)
+  ([#11](https://github.com/susom/tide2-core/pull/11),
+  [`6ff5249`](https://github.com/susom/tide2-core/commit/6ff5249dc8c0f7bcef803089d36f70a12d6bae87))
+
+- Add tide2-core PHI de-identification pipeline
+  ([`f165b26`](https://github.com/susom/tide2-core/commit/f165b26bbd849c2eb4a13c3cd5ffd884cad15530))
+
+### Performance Improvements
+
+- **pipeline**: Auto-tune CPU resource allocation for Mac/CPU runs
+  ([`c96ec32`](https://github.com/susom/tide2-core/commit/c96ec32b1ee614c5d90550743355a604eed3260d))

tide2-1.1.0/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TIDE 2.0 Team
+
+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.

tide2-1.1.0/PKG-INFO

@@ -0,0 +1,432 @@
+Metadata-Version: 2.4
+Name: tide2
+Version: 1.1.0
+Summary: An advanced data de-identification and anonymization toolkit combining multiple strategies with cryptographic techniques and ML-based entity recognition
+Project-URL: Homepage, https://github.com/susom/tide2-core
+Project-URL: Repository, https://github.com/susom/tide2-core
+Project-URL: Issues, https://github.com/susom/tide2-core/issues
+Project-URL: Documentation, https://susom.github.io/tide2-core/
+Author: TIDE 2.0 Team
+License-Expression: MIT
+License-File: LICENSE-MIT
+Keywords: anonymization,data-protection,de-identification,healthcare,nlp,pii,presidio,privacy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: <3.13,>=3.12
+Requires-Dist: aiohttp>=3.14.0
+Requires-Dist: db-dtypes
+Requires-Dist: faker
+Requires-Dist: ff3
+Requires-Dist: google-cloud-bigquery
+Requires-Dist: google-cloud-storage
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: intervaltree>=3.1.0
+Requires-Dist: numpy
+Requires-Dist: orjson>=3.10.0
+Requires-Dist: pandas
+Requires-Dist: presidio-analyzer
+Requires-Dist: presidio-anonymizer
+Requires-Dist: psutil
+Requires-Dist: pyahocorasick
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: ray[data,default]>=2.54.0
+Requires-Dist: spacy>=3.8.0
+Requires-Dist: starlette>=1.0.1
+Requires-Dist: streamlit
+Requires-Dist: tenacity
+Requires-Dist: torch
+Requires-Dist: transformers>=5.0.0
+Requires-Dist: usaddress
+Provides-Extra: dev
+Requires-Dist: cython; extra == 'dev'
+Requires-Dist: ipykernel; extra == 'dev'
+Requires-Dist: jupyter; extra == 'dev'
+Requires-Dist: keyring>=25.6.0; extra == 'dev'
+Requires-Dist: keyrings-google-artifactregistry-auth>=1.1.2; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.3.2.250926; extra == 'dev'
+Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: python-semantic-release>=10.5.3; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: scikit-learn>=1.8.0; extra == 'dev'
+Requires-Dist: scipy>=1.12.0; extra == 'dev'
+Requires-Dist: tqdm>=4.67.1; extra == 'dev'
+Requires-Dist: ty>=0.0.28; extra == 'dev'
+Requires-Dist: types-tqdm>=4.67.0.20250809; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: pdoc>=14.0; extra == 'docs'
+Provides-Extra: evaluation
+Requires-Dist: scikit-learn>=1.8.0; extra == 'evaluation'
+Requires-Dist: scipy>=1.12.0; extra == 'evaluation'
+Requires-Dist: tqdm>=4.67.1; extra == 'evaluation'
+Provides-Extra: llm
+Requires-Dist: anthropic; extra == 'llm'
+Requires-Dist: google-cloud-aiplatform; extra == 'llm'
+Requires-Dist: google-genai; extra == 'llm'
+Requires-Dist: openai; extra == 'llm'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
+Requires-Dist: pytest>=7.4.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# TIDE 2.0
+
+A data de-identification and anonymization toolkit that combines multiple anonymization strategies with cryptographic techniques and machine learning-based entity recognition.
+
+## Get Started
+
+### Dev Container (recommended)
+
+The repository includes a [Dev Container](https://containers.dev/) configuration that sets up
+the full development environment automatically: Python 3.12, `uv`, all dependencies (including
+GPU group), pre-commit hooks.
+
+**Prerequisites:**
+- [Docker](https://docs.docker.com/get-docker/)
+- [VS Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+**Steps:**
+
+1. Clone the repository and open it in VS Code:
+   ```bash
+   git clone https://github.com/susom/tide2-core.git
+   cd tide2
+   ```
+2. When VS Code detects `.devcontainer/devcontainer.json`, click **Reopen in Container**
+   (or run the command **Dev Containers: Reopen in Container** from the command palette).
+3. The virtual environment at `/opt/tide2-core/.venv` is activated by default in all terminals.
+
+The Dev Container includes these VS Code extensions pre-installed: Python, Ruff, Jupyter,
+Docker, and TOML support.
+
+### Local Installation (without Dev Container)
+
+If you prefer to develop outside the Dev Container:
+
+```bash
+# Install uv (https://docs.astral.sh/uv/getting-started/installation/)
+# macOS and Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Clone and install
+git clone https://github.com/susom/tide2.git
+cd tide2
+
+uv python install 3.12.8
+uv sync
+
+# Activate the virtual environment before running any Python commands
+source .venv/bin/activate          # macOS / Linux
+# .venv\Scripts\activate           # Windows (PowerShell)
+```
+
+### Quick Start: Interactive Tutorial
+
+The tutorial notebook walks you through the de-identification pipeline step by step.
+
+**In the Dev Container (or local VS Code):**
+
+1. Open `notebooks/tide2_pipeline.ipynb` (the Jupyter extension is pre-installed in the Dev Container)
+2. When prompted for a kernel, select the `.venv (Python 3.12)` environment
+
+**Jupyter in the browser (local installation):**
+
+```bash
+uv sync --group dev              # Install Jupyter (dev dependency group)
+source .venv/bin/activate
+jupyter notebook notebooks/tide2_pipeline.ipynb
+```
+
+View the notebook on GitHub: [TIDE 2.0 Pipeline Tutorial](https://github.com/susom/tide2/blob/main/notebooks/tide2_pipeline.ipynb)
+
+**Troubleshooting:**
+- **Run from the repo root** — launch Jupyter from the `tide2/` directory so that relative paths resolve correctly.
+- **GCP credentials are not required** — the notebook downloads the transformer model from HuggingFace Hub by default. Set `project_id` and `bucket_name` in the Configuration cell only if you want to use GCS-hosted weights.
+- **Kernel crashes** — if the Jupyter kernel crashes repeatedly, restart Jupyter (`Ctrl+C`, then re-launch) and run the cells from the top.
+
+### Visualizer Preview
+
+TIDE 2.0 includes a Streamlit visualizer for comparing original and de-identified text side by side:
+
+![TIDE 2.0 Visualizer](notebooks/images/visualizer_screenshot.png)
+
+Launch it with:
+```bash
+tide2-visualizer
+```
+
+To stop the visualizer, press `Ctrl+C` in the terminal (works on macOS, Linux, and Windows).
+
+---
+
+## Overview
+
+TIDE 2.0 is a Python package for anonymizing sensitive data in healthcare and research contexts. It identifies and anonymizes personally identifiable information (PII) while maintaining data utility for analysis and research.
+
+## Features
+
+### Entity Recognition
+- **Transformer-based NER**: HuggingFace transformer models with direct batch inference (bypasses HF pipeline), BIO token aggregation, and chunk-to-document reassembly
+- **Regex recognizers**: Phone, URL/IP, Email, SSN, Address — replacements for Presidio defaults (10-100x faster)
+- **Healthcare-specific**: MRN, Accession Number, HAR code recognizers
+- **Known values detection**: Aho-Corasick based matching against patient databases
+- **Specialized**: Base64 image detection, genetic sequence detection, LLM-based JSON recognizer
+- **Cached results**: Pre-computed NER results from GPU batch processing via `CachedResultsTransformerRecognizer`
+- **Presidio Integration**: Built on Microsoft's Presidio framework
+
+### Anonymization Strategies
+- **HIPS (Healthcare Identity Protection System)**: Cryptographic deterministic anonymization for names, locations, and alphanumeric identifiers
+- **Accession number hashing**: SHA256-based, compatible with BigQuery UDF
+- **Faker Integration**: Realistic fake data generation
+- **Date Jittering**: Deterministic, privacy-preserving date shifts derived from patient keys
+- **Age Grouping**: Age range categorization
+
+### Cryptographic Protection
+- **Format-Preserving Encryption (FPE)**: Maintains data format during encryption
+- **Key Management**: Key generation, storage, and derivation utilities
+- **Deterministic date jitter**: Batch-capable date shift derivation from cryptographic keys
+- **String Selection**: HMAC-based cached string selection
+
+### Ray-based Batch Processing
+- **Runner module**: Single-node job runner with local and VM modes via `tide2-runner` CLI
+- **Ray actors**: `RecognizerActor`, `AnonymizerActor`, `TransformerInferenceActor`, `BIOAggregationActor`, `ReassemblyActor` for `ray.data.map_batches`
+- **Two-stage GPU/CPU pipeline**: GPU inference returns raw BIO tokens; CPU actors aggregate them concurrently via Ray Data streaming
+- **Direct inference**: Bypasses HuggingFace pipeline dispatch loop with batch tokenize → single GPU forward pass → offset-based extraction
+- **Adaptive GPU batching**: Auto-computes batch size from model config and free GPU memory; adjusts based on text lengths with VRAM-aware budgets (override via `--short-seq-budget`)
+- **OOM recovery**: Automatic batch splitting on CUDA out-of-memory errors
+- **Fault tolerance**: Actor restarts, task retries, graceful shutdown
+- **YAML config**: All CLI arguments can be specified in a YAML config file (`--config`)
+
+### Utilities
+- **Text processing**: Text chunking, BIO aggregation, span reconstruction, deduplication
+- **String parsers**: Name parsing/classification, address parsing, format detection
+- **Span metrics**: Gold vs ML evaluation, O(n log n) conflict resolution
+- **GCS cache**: Auto-download models from GCS to `~/.cache/tide2/`
+- **Model compilation**: `torch.compile` with mega-cache support for faster inference startup
+
+### Command Line Tools
+- **`tide2-runner`**: Ray-based single-node job runner with six job types: `recognizer`, `anonymizer`, `transformer`, `reassembly`, `pipeline` (full end-to-end), and `llm-recognizer`. Supports YAML config files (`--config`) and dry-run mode (`--dry-run`).
+- **`tide2-visualizer`**: Streamlit app for side-by-side PHI comparison and entity editing.
+
+
+### Cloud Integration
+- **GCS**: input/output I/O and model caching.
+- **BigQuery**: input/output of notes and recognizer/anonymizer results (e.g. via `ARRAY_AGG`-grouped chunk columns) for the runner and visualizer.
+- **Automatic Caching**: Download and cache models from GCS automatically (`$TIDE_CACHE_DIR`).
+
+## CLI Usage
+
+### Runner CLI (Ray-based processing)
+
+```bash
+# Run recognition locally
+tide2-runner run recognizer -i ./data/input -o ./data/output
+
+# Run with more resources (e.g. on a large VM), reading/writing from GCS
+tide2-runner run recognizer -i gs://bucket/input -o gs://bucket/output \
+    --num-cpus 224 --num-actors 200
+
+# Run transformer NER on GPU
+tide2-runner run transformer -i ./data/input -o ./data/transformer_output \
+    --model StanfordAIMI/stanford-deidentifier-v2 --batch-size 2048
+
+# Run transformer with YAML config
+tide2-runner run transformer --config config.yaml
+
+# Run the full pipeline (transformer -> recognizer -> anonymizer)
+tide2-runner run pipeline -i ./data/input.parquet -o ./data/output \
+    --model StanfordAIMI/stanford-deidentifier-v2
+
+# If you are running on Mac, you can use --object-store-gb option to set
+tide2-runner run pipeline -i ./data/input.parquet -o ./data/output \
+     --model StanfordAIMI/stanford-deidentifier-v2  --object-store-gb 2
+
+# Run anonymization
+tide2-runner run anonymizer -i ./data/recognized -o ./data/anonymized \
+    --salt /path/to/salt.bin --key /path/to/key.bin
+```
+
+
+### Interactive Visualizer
+
+```bash
+# Launch the Streamlit PHI visualizer
+tide2-visualizer
+```
+
+## Docker Images
+
+Several targets are built from a single multi-stage `Dockerfile`:
+
+- `production-cpu` — slim CPU-only image (no CUDA, no `gpu` dependency group). Used by recognizer, anonymizer, and BigQuery tasks.
+- `production-gpu` — GPU image based on `nvidia/cuda:13.0.2-cudnn-runtime-ubuntu24.04`, includes the `gpu` dependency group (`torch`, `transformers`, `spacy`). Used by transformer inference.
+- `development` — Dev Container target with `git`, `gcloud`, build tools, and the full dev environment.
+- `test` — extends `development` and runs the test suite (used by `make test-docker`).
+
+Build and push the GPU image (requires `DOCKER_REGISTRY` and `DOCKER_IMAGE_GPU` in `.env`):
+
+```bash
+make docker         # build + push the GPU image (alias for docker-gpu)
+make docker-gpu     # build + push the GPU image
+make test-docker    # build the test target and run the suite in Docker
+```
+
+## Dependency Groups
+
+- **`llm`**: LLM provider SDKs for the optional LLM-based recognizer (`anthropic`, `openai`, `google-genai`, `google-cloud-aiplatform`)
+- **`dev`**: Development tools (`pytest`, `pytest-cov`, `ty`, `ruff`, `pre-commit`), Jupyter, and the `evaluation` libraries (`scikit-learn`, `scipy`, `tqdm`)
+- **`evaluation`**: Evaluation/analysis libraries (`scikit-learn`, `scipy`, `tqdm`)
+- **`test`**: Minimal test dependencies (`pytest`, `pytest-cov`)
+- **`docs`**: API documentation generation (`pdoc`)
+
+Install an optional group as an extra with `uv sync --extra <name>`, or all extras with `uv sync --all-extras`. (These same sets are also defined as `[dependency-groups]`, usable with `uv sync --group <name>`.)
+
+Note: The full ML inference stack (`torch`, `transformers`, `spacy`) ships in the main package by default — it is required, since no model can run without it. The `llm` extra is only needed for the optional LLM-based recognizer.
+
+## Architecture
+
+```
+tide2/
+├── recognizers/              # PII detection (Presidio EntityRecognizer subclasses)
+├── anonymizers/              # PII replacement (Presidio Operator subclasses)
+├── transformers/             # Core NER inference engine (TransformerCore)
+│   ├── core.py              # Model loading, direct inference, BIO aggregation
+│   └── config.py            # Model configuration management
+├── actors/                   # Ray actors for distributed batch processing
+│   ├── transformer.py       # GPU inference actor + CPU BIO aggregation actor
+│   ├── recognizer.py        # CPU recognizer actor
+│   ├── anonymizer.py        # CPU anonymizer actor
+│   ├── reassembly.py        # Chunk-to-document reassembly actor
+│   └── llm_recognizer.py    # LLM-based recognizer actor
+├── cryptographic/            # FPE, key management, date jitter derivation
+├── string_parsers/           # Name/address parsing, format detection
+├── runner/                   # Ray-based single-node job runner + CLI
+│   ├── local_runner.py      # LocalJobRunner: transformer/recognizer/anonymizer/reassembly/pipeline/llm
+│   ├── cli.py               # tide2-runner CLI with YAML config support
+│   ├── transformer.py       # Document chunking and reassembly logic
+│   ├── fault_tolerance.py   # Actor restarts, graceful shutdown
+│   └── utils.py             # Runner utilities
+├── cli/                      # Streamlit visualizer
+├── utils/
+│   ├── gcs_resource_manager.py  # GCS auto-download and caching
+│   ├── gcs_connector.py        # GCS file I/O
+│   ├── span_metrics.py         # Evaluation metrics and conflict resolution
+│   ├── text_processing.py      # Chunking, BIO aggregation, span reconstruction
+│   ├── serialization.py        # RecognizerResult <-> dict conversions
+│   ├── llm_model.py            # LLM client utilities
+│   ├── batch_columns.py        # Batch column constants
+│   ├── constants.py            # Shared constants
+│   └── resource_utils.py       # Resource path helpers
+└── resources/                # Config files (model configs, name lists, etc.)
+```
+
+## Testing
+
+```bash
+# Run all unit tests (coverage report prints automatically)
+uv run pytest
+
+# Run without coverage (faster, useful when debugging)
+uv run pytest --no-cov
+
+# Run a specific test file
+uv run pytest tests/test_masking_anonymizer.py
+
+# Skip slow integration tests
+uv run pytest -m "not integration"
+```
+
+Coverage is configured in `pyproject.toml` and runs automatically with `pytest`. Three reports are generated on each run:
+
+- **Terminal**: line-by-line missing coverage printed to stdout
+- **HTML**: detailed report at `htmlcov/index.html`
+- **XML**: `coverage.xml` (Cobertura format)
+
+## Documentation
+
+### API Reference
+
+API documentation is hosted via GitHub Pages: [https://susom.github.io/tide2/](https://susom.github.io/tide2/)
+
+To build or preview docs locally (generated with [pdoc](https://pdoc.dev/)):
+
+```bash
+# Install docs dependencies (pdoc); the ML stack ships in the base install,
+# so all modules import without an extra
+uv sync --extra docs
+
+# Live preview (opens a local server with hot reload)
+make docs-serve
+
+# Generate static HTML to docs/
+make docs
+```
+
+Deployment to GitHub Pages is automated: the [`.github/workflows/docs.yml`](.github/workflows/docs.yml)
+workflow runs `make docs` on every push to `main` and publishes the `docs/` directory as a
+Pages artifact.
+
+### Other Resources
+
+- **Examples**: Check the `notebooks/` directory for usage examples
+- **Tests**: Test suite in `tests/` directory
+
+## Requirements
+
+- **Dev Container**: Recommended — provides the full environment with no manual setup (requires Docker and VS Code with the Dev Containers extension)
+- **Python**: 3.12 (required, `>=3.12,<3.13`) — constrained to 3.12 for compatibility with the `spacy`/`thinc` C-extension stack and other pinned dependencies.
+- **Package Manager**: uv (not pip or poetry)
+- **Virtual Environment**: `.venv/` (activated automatically in the Dev Container; must be activated manually for local installs)
+- **Core Dependencies**: Presidio, Ray (`>=2.54`), Cryptography, Faker, Google Cloud libraries, and the ML inference stack (`torch`, `transformers>=5.0`, `spacy`) — all required and shipped in the base install
+
+## Security Considerations
+
+- Cryptographic operations use standard libraries (cryptography, pyca/cryptography)
+- Format-preserving encryption maintains data format during encryption
+- Key management supports generation, storage, and rotation
+- Anonymization strategies are designed to prevent re-identification
+
+## Contributing
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, branching
+model, commit-message conventions, and the pull request checklist. The
+[Dev Container setup](#dev-container-recommended) above provisions the full
+development environment (including pre-commit hooks) automatically.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE-MIT](LICENSE-MIT) file for details.
+
+## Citation
+
+If you use TIDE 2.0 in your research, please cite:
+
+```bibtex
+@software{tide2,
+  title={TIDE 2.0: Data De-identification and Anonymization Toolkit},
+  author={TIDE 2.0 Team},
+  year={2025},
+  url={https://github.com/susom/tide2}
+}
+```
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/susom/tide2/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/susom/tide2/discussions)
+- **Development**: See the Contributing section above
+
+---
+
+**Synthetic Data Notice**: All sample data included in this repository (under `notebooks/sample_data/`) is entirely synthetic and fabricated. No real patient data is included. See [`notebooks/sample_data/README.md`](notebooks/sample_data/README.md) for details.
+
+**Note**: This toolkit is designed for research and development purposes. Please ensure compliance with relevant privacy laws and regulations (HIPAA, GDPR, etc.) when using in production environments.