ehrextract 0.2.0__tar.gz

ehrextract-0.2.0/LICENSE

@@ -0,0 +1,205 @@
+Copyright (c) 2026 Chen Zhang, Yibing Xia, Sanjay Mahant, Nathan Taback,
+The Hospital for Sick Children, and the University of Toronto.
+All rights reserved.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. 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.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor 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
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You 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 the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You 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 such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its 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. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ehrextract-0.2.0/NOTICE

@@ -0,0 +1,185 @@
+ehrextract
+Copyright (c) 2026 Chen Zhang, Yibing Xia, Sanjay Mahant, Nathan Taback,
+The Hospital for Sick Children, and the University of Toronto.
+All rights reserved.
+
+This product is licensed under the Apache License, Version 2.0 (the
+"License"). You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+The following terms supplement, but do not override, the License.
+
+================================================================
+1. Authors and institutions
+================================================================
+
+ehrextract was created by:
+
+    Chen Zhang (lead author)
+    Yibing Xia (co-author)
+    Sanjay Mahant, MD (supervisor; The Hospital for Sick Children)
+    Nathan Taback, PhD (supervisor; University of Toronto)
+
+at:
+
+    The Hospital for Sick Children (SickKids), Toronto, Canada
+    University of Toronto, Toronto, Canada
+
+================================================================
+2. Trademark and endorsement
+================================================================
+
+Neither the names "The Hospital for Sick Children", "SickKids",
+"University of Toronto", "U of T", nor the names of any of the authors
+listed above may be used to endorse or promote products derived from
+this Software, or to imply institutional review, approval, or
+validation of any derivative work, without prior written permission
+from the relevant institution or individual.
+
+The presence of these names in copyright notices, attribution
+documentation, and citations is permitted and required by the License;
+endorsement of derivative products is not.
+
+================================================================
+3. Not a medical device
+================================================================
+
+ehrextract IS NOT A MEDICAL DEVICE. It has not been cleared, certified,
+or approved by:
+
+    - the U.S. Food and Drug Administration (FDA),
+    - Health Canada,
+    - the European Medicines Agency (EMA), or
+    - any other regulatory body.
+
+It has not been validated for use in clinical decision-making, patient
+diagnosis, treatment planning, triage, prognostic assessment, or any
+other application that affects patient care. Users who deploy
+ehrextract in any setting where its outputs may influence clinical
+decisions do so entirely at their own risk and assume sole
+responsibility for any harm that results.
+
+================================================================
+4. Privacy, PHI, and regulatory compliance
+================================================================
+
+ehrextract does not detect Protected Health Information (PHI). The
+egress-warning mechanism (consent.py) is informational only -- it is
+NOT a privacy compliance control and MUST NOT be relied upon as such.
+
+Users are solely responsible for ensuring that their use of ehrextract
+complies with all applicable privacy, data-protection, and
+data-residency laws, including but not limited to:
+
+    - the Health Insurance Portability and Accountability Act (HIPAA),
+    - the Personal Health Information Protection Act (PHIPA, Ontario),
+    - the Personal Information Protection and Electronic Documents
+      Act (PIPEDA, Canada),
+    - the General Data Protection Regulation (GDPR, EU),
+
+and with the policies of any institutional Research Ethics Board (REB)
+or Institutional Review Board (IRB) governing the data they process.
+
+Routing PHI through any third-party API requires, at minimum, a signed
+Business Associate Agreement (or local equivalent) and Zero-Data-
+Retention enrollment with that provider. Users must verify these
+arrangements independently; the listing of a provider in ehrextract's
+documentation is not a representation of compliance.
+
+================================================================
+5. Acceptable-use restrictions
+================================================================
+
+The authors and institutions named above expressly disclaim and do not
+license use of ehrextract for any of the following purposes:
+
+    - re-identification of de-identified or pseudonymized records;
+    - mass surveillance of patient populations or individuals;
+    - insurance underwriting, eligibility determination, or claims
+      adjudication;
+    - employment or admissions decisions;
+    - immigration or border-screening decisions;
+    - law-enforcement intelligence-gathering;
+    - any application that produces or supports decisions of legal,
+      financial, or material consequence to an identified individual
+      without that individual's informed consent.
+
+This list is non-exhaustive. Any use that could reasonably be expected
+to cause disparate harm to individuals or groups is outside the scope
+of the authors' and institutions' intent.
+
+================================================================
+6. Research use and output validation
+================================================================
+
+ehrextract uses large language models that may produce hallucinated,
+incomplete, or systematically biased outputs. The "parse_success"
+column in ehrextract output indicates that the model's response was
+syntactically valid against the schema; it does NOT indicate that the
+extracted values are correct.
+
+Any use of ehrextract output as research data requires human review of
+every row before that data is treated as observed fact. Publications,
+posters, abstracts, or reports that present ehrextract output as
+ground-truth without per-row human validation are misuses of the
+software and are not endorsed by the authors or institutions.
+
+================================================================
+7. Bias and fairness
+================================================================
+
+ehrextract has not been audited for demographic, linguistic, or
+clinical-context bias. The underlying language models are known to
+exhibit disparate performance across populations defined by race,
+ethnicity, gender, primary language, age, socioeconomic status, and
+condition prevalence.
+
+ehrextract MUST NOT be used in triage, resource allocation, eligibility
+determination, or any other setting where disparate model performance
+across demographic subgroups could cause unequal access to care or
+disparate harm.
+
+================================================================
+8. Third-party adapters and models
+================================================================
+
+ehrextract supports loading external LoRA adapters via the --adapter
+flag and external model weights via --model. The authors and
+institutions do NOT host, vet, validate, or vouch for any third-party
+adapter or model. Use of an adapter does not imply that the adapter's
+training data, license, or output behaviour has been reviewed.
+
+Distributors of LoRA adapters or fine-tuned weights that advertise
+compatibility with ehrextract are responsible for the licensing and
+data-handling claims they make about their own artifacts.
+
+================================================================
+9. Maintenance and security
+================================================================
+
+ehrextract is research-grade software released as a public-good
+artifact. The authors make NO commitment to:
+
+    - respond to issues or pull requests within any timeframe,
+    - provide security patches for reported vulnerabilities,
+    - maintain compatibility with future versions of dependencies,
+    - support deployment in production environments, or
+    - continue development beyond the published version.
+
+Operators who deploy ehrextract are solely responsible for monitoring
+its dependencies, patching vulnerabilities, and assessing fitness for
+their environment.
+
+================================================================
+10. No warranty
+================================================================
+
+EHREXTRACT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED. SEE SECTIONS 7 AND 8 OF THE APACHE LICENSE 2.0 FOR THE
+FULL DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY.
+
+================================================================
+
+For questions about acceptable use or institutional permission, contact
+the corresponding author through the project repository.

ehrextract-0.2.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: ehrextract
+Version: 0.2.0
+Summary: Structured feature extraction from clinical notes
+Author: Chen Zhang, Yibing Xia, Sanjay Mahant, Nathan Taback
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/shifosss/ehrextract
+Project-URL: Repository, https://github.com/shifosss/ehrextract
+Project-URL: Issues, https://github.com/shifosss/ehrextract/issues
+Project-URL: Changelog, https://github.com/shifosss/ehrextract/blob/main/CHANGELOG.md
+Keywords: clinical,nlp,extraction,llm,structured-output
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: hf
+Requires-Dist: torch>=2.0; extra == "hf"
+Requires-Dist: transformers>=4.56; extra == "hf"
+Requires-Dist: peft>=0.10; extra == "hf"
+Requires-Dist: accelerate>=0.30; extra == "hf"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == "anthropic"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Dynamic: license-file
+
+# ehrextract
+
+Structured feature extraction from clinical notes. Three steps:
+
+1. **Bring your notes** — CSV, JSONL, JSON, XLSX, plain text, or a pandas
+   DataFrame.
+2. **Pick a task** — a built-in task (`comorbidity`, `clinical_vars`, `full`)
+   or your own YAML file with your own fields and prompt.
+3. **Pick a model** — a fine-tuned LoRA adapter on a local base model, your
+   own local HuggingFace weights, or an API model (OpenAI-compatible or
+   Anthropic).
+
+One command (or one function call) later you have a results table —
+CSV, JSONL, JSON, XLSX, or Parquet — with one column per extracted field.
+
+> **Important — read before use.**
+> ehrextract is **research-grade software**. It is **NOT a medical device**,
+> is **NOT FDA-cleared / Health Canada-approved**, and **MUST NOT** be used
+> for clinical decision-making, patient triage, eligibility determination,
+> re-identification, surveillance, or any setting where its outputs affect
+> a person's access to care, insurance, employment, or legal status.
+> Outputs may hallucinate; any research use requires per-row human review.
+> The egress-warning system is informational, not a privacy compliance
+> control. **Users are solely responsible for HIPAA / PHIPA / PIPEDA / GDPR
+> / REB compliance.** See [`NOTICE`](https://github.com/shifosss/ehrextract/blob/main/NOTICE) for the
+> full acceptable-use scope.
+
+## Install
+
+Until the PyPI release, install from source (**current method**):
+
+```bash
+git clone https://github.com/shifosss/ehrextract
+pip install './ehrextract[hf]'          # or [openai], [anthropic]
+```
+
+Once published to PyPI:
+
+```bash
+pip install ehrextract                  # core (~50 MB)
+pip install 'ehrextract[hf]'            # + torch + transformers + peft (~3 GB)
+pip install 'ehrextract[openai]'        # + openai SDK
+pip install 'ehrextract[anthropic]'     # + anthropic SDK
+```
+
+## 30-second example
+
+```bash
+ehrextract \
+  --task comorbidity \
+  --model Qwen/Qwen3.5-27B --adapter /path/to/adapter \
+  --input notes.csv --output results.csv
+```
+
+or, as a library:
+
+```python
+from pathlib import Path
+from ehrextract import extract
+
+df = extract(
+    Path("notes.csv"),
+    "comorbidity",
+    model="Qwen/Qwen3.5-27B",
+    adapter="/path/to/adapter",
+    output="results.csv",
+)
+```
+
+The input needs a `note_text` column (configurable via `--text-column`); a
+`note_id` column is added automatically when absent. The output has one
+column per task field plus `parse_success`, `validation_errors`,
+`raw_response`, `finish_reason`, and token counts.
+
+## Built-in tasks
+
+| Task | Fields | What it extracts |
+|---|---|---|
+| `comorbidity` | 17 | Free-text diagnosis list + 16 Y/N comorbidity categories |
+| `clinical_vars` | 4 | Feeding and neurologic variables (tube/oral feeding, aspiration risk, NI trajectory) |
+| `full` | 20 | Joint task: the 16 comorbidity categories + the 4 clinical variables |
+
+Built-in tasks ship inside the package; `--task <name>` works without any
+extra files. Define your own task in YAML — see
+[`schema-reference.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/schema-reference.md).
+
+> **Note on the `full` task.** The research pipeline that produced the
+> published evaluation numbers for the joint 20-field task used constrained
+> JSON decoding to force the output shape. ehrextract v0.2.0 does **not**
+> constrain decoding (planned as a future feature), so `full`-task outputs
+> can diverge from the published numbers on hard notes — watch the
+> `parse_success` and `validation_errors` columns.
+
+## Data handling
+
+If your input may contain PHI, read [`data-handling.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/data-handling.md)
+BEFORE running with any API provider. The package writes a data-egress
+notice to stderr (once per process per destination) on API use; it never
+blocks, and it does not (and cannot) guarantee compliance for you. The
+local HuggingFace provider keeps all data on your machine.
+
+## Documentation
+
+- [`quickstart.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/quickstart.md) — fine-tuned adapters, custom tasks, API providers
+- [`schema-reference.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/schema-reference.md) — the task-file YAML reference
+- [`data-handling.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/data-handling.md) — PHI, egress notice, BAA-eligible providers
+- [`extending-providers.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/extending-providers.md) — plug in a custom provider
+
+## Authors and institutions
+
+ehrextract was developed by:
+
+- **Chen Zhang** (lead author)
+- **Yibing Xia** (co-author)
+- **Sanjay Mahant, MD** -- supervisor, The Hospital for Sick Children (SickKids)
+- **Nathan Taback, PhD** -- supervisor, University of Toronto
+
+at **The Hospital for Sick Children** (Toronto, Canada) and the
+**University of Toronto** (Toronto, Canada). Please cite the project if
+you use it in published work.
+
+## License
+
+Licensed under the Apache License, Version 2.0. See [`LICENSE`](https://github.com/shifosss/ehrextract/blob/main/LICENSE)
+for the full license text and [`NOTICE`](https://github.com/shifosss/ehrextract/blob/main/NOTICE) for
+attribution, the no-endorsement clause, the clinical-use disclaimer, and the
+acceptable-use restrictions that supplement (but do not override) the License.

ehrextract-0.2.0/README.md

@@ -0,0 +1,127 @@
+# ehrextract
+
+Structured feature extraction from clinical notes. Three steps:
+
+1. **Bring your notes** — CSV, JSONL, JSON, XLSX, plain text, or a pandas
+   DataFrame.
+2. **Pick a task** — a built-in task (`comorbidity`, `clinical_vars`, `full`)
+   or your own YAML file with your own fields and prompt.
+3. **Pick a model** — a fine-tuned LoRA adapter on a local base model, your
+   own local HuggingFace weights, or an API model (OpenAI-compatible or
+   Anthropic).
+
+One command (or one function call) later you have a results table —
+CSV, JSONL, JSON, XLSX, or Parquet — with one column per extracted field.
+
+> **Important — read before use.**
+> ehrextract is **research-grade software**. It is **NOT a medical device**,
+> is **NOT FDA-cleared / Health Canada-approved**, and **MUST NOT** be used
+> for clinical decision-making, patient triage, eligibility determination,
+> re-identification, surveillance, or any setting where its outputs affect
+> a person's access to care, insurance, employment, or legal status.
+> Outputs may hallucinate; any research use requires per-row human review.
+> The egress-warning system is informational, not a privacy compliance
+> control. **Users are solely responsible for HIPAA / PHIPA / PIPEDA / GDPR
+> / REB compliance.** See [`NOTICE`](https://github.com/shifosss/ehrextract/blob/main/NOTICE) for the
+> full acceptable-use scope.
+
+## Install
+
+Until the PyPI release, install from source (**current method**):
+
+```bash
+git clone https://github.com/shifosss/ehrextract
+pip install './ehrextract[hf]'          # or [openai], [anthropic]
+```
+
+Once published to PyPI:
+
+```bash
+pip install ehrextract                  # core (~50 MB)
+pip install 'ehrextract[hf]'            # + torch + transformers + peft (~3 GB)
+pip install 'ehrextract[openai]'        # + openai SDK
+pip install 'ehrextract[anthropic]'     # + anthropic SDK
+```
+
+## 30-second example
+
+```bash
+ehrextract \
+  --task comorbidity \
+  --model Qwen/Qwen3.5-27B --adapter /path/to/adapter \
+  --input notes.csv --output results.csv
+```
+
+or, as a library:
+
+```python
+from pathlib import Path
+from ehrextract import extract
+
+df = extract(
+    Path("notes.csv"),
+    "comorbidity",
+    model="Qwen/Qwen3.5-27B",
+    adapter="/path/to/adapter",
+    output="results.csv",
+)
+```
+
+The input needs a `note_text` column (configurable via `--text-column`); a
+`note_id` column is added automatically when absent. The output has one
+column per task field plus `parse_success`, `validation_errors`,
+`raw_response`, `finish_reason`, and token counts.
+
+## Built-in tasks
+
+| Task | Fields | What it extracts |
+|---|---|---|
+| `comorbidity` | 17 | Free-text diagnosis list + 16 Y/N comorbidity categories |
+| `clinical_vars` | 4 | Feeding and neurologic variables (tube/oral feeding, aspiration risk, NI trajectory) |
+| `full` | 20 | Joint task: the 16 comorbidity categories + the 4 clinical variables |
+
+Built-in tasks ship inside the package; `--task <name>` works without any
+extra files. Define your own task in YAML — see
+[`schema-reference.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/schema-reference.md).
+
+> **Note on the `full` task.** The research pipeline that produced the
+> published evaluation numbers for the joint 20-field task used constrained
+> JSON decoding to force the output shape. ehrextract v0.2.0 does **not**
+> constrain decoding (planned as a future feature), so `full`-task outputs
+> can diverge from the published numbers on hard notes — watch the
+> `parse_success` and `validation_errors` columns.
+
+## Data handling
+
+If your input may contain PHI, read [`data-handling.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/data-handling.md)
+BEFORE running with any API provider. The package writes a data-egress
+notice to stderr (once per process per destination) on API use; it never
+blocks, and it does not (and cannot) guarantee compliance for you. The
+local HuggingFace provider keeps all data on your machine.
+
+## Documentation
+
+- [`quickstart.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/quickstart.md) — fine-tuned adapters, custom tasks, API providers
+- [`schema-reference.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/schema-reference.md) — the task-file YAML reference
+- [`data-handling.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/data-handling.md) — PHI, egress notice, BAA-eligible providers
+- [`extending-providers.md`](https://github.com/shifosss/ehrextract/blob/main/docs/ehrextract/extending-providers.md) — plug in a custom provider
+
+## Authors and institutions
+
+ehrextract was developed by:
+
+- **Chen Zhang** (lead author)
+- **Yibing Xia** (co-author)
+- **Sanjay Mahant, MD** -- supervisor, The Hospital for Sick Children (SickKids)
+- **Nathan Taback, PhD** -- supervisor, University of Toronto
+
+at **The Hospital for Sick Children** (Toronto, Canada) and the
+**University of Toronto** (Toronto, Canada). Please cite the project if
+you use it in published work.
+
+## License
+
+Licensed under the Apache License, Version 2.0. See [`LICENSE`](https://github.com/shifosss/ehrextract/blob/main/LICENSE)
+for the full license text and [`NOTICE`](https://github.com/shifosss/ehrextract/blob/main/NOTICE) for
+attribution, the no-endorsement clause, the clinical-use disclaimer, and the
+acceptable-use restrictions that supplement (but do not override) the License.