autoicd 0.2.0__tar.gz

autoicd-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/

autoicd-0.2.0/CLAUDE.md

@@ -0,0 +1,85 @@
+# AutoICD Python SDK
+
+Public SDK for **AutoICD API** (autoicdapi.com). Published as `autoicd` on PyPI.
+GitHub: `github.com/fcggamou/autoicd-python`
+
+## Quick Reference
+
+```bash
+pip install -e ".[dev]"  # Install in dev mode with test deps
+pytest                   # Run tests
+ruff check src/ tests/   # Lint
+ruff format src/ tests/  # Format
+```
+
+## Architecture
+
+```
+src/autoicd/
+├── __init__.py   — Public exports (re-exports client, types, errors)
+├── client.py     — AutoICD class + Codes sub-resource + HTTP internals
+├── types.py      — All request/response dataclasses
+└── errors.py     — AutoICDError hierarchy (401, 404, 429)
+tests/
+└── test_client.py — Unit tests with mocked httpx transport
+```
+
+- **Single dependency** — `httpx` for HTTP (timeout, headers, mock transport for tests)
+- Uses `src/` layout with hatchling build backend
+- Target: Python 3.10+
+- All types are dataclasses — no Pydantic dependency
+
+## API Surface
+
+```python
+client = AutoICD(api_key="sk_...")
+
+client.code(text, options?)       # POST /api/v1/code — clinical text → ICD-10 codes
+client.anonymize(text)            # POST /api/v1/anonymize — PHI de-identification
+client.codes.search(query, opts?) # GET  /api/v1/codes/search — search ICD-10 codes
+client.codes.get(code)            # GET  /api/v1/codes/:code — code details
+client.codes.terms(code)          # GET  /api/v1/codes/:code/terms — index terms
+client.last_rate_limit            # Rate limit info from last response
+```
+
+## Conventions
+
+- All names use **snake_case** (Python convention matches API response format)
+- Options are passed as dataclass instances (e.g., `CodeOptions(top_k=3)`)
+- `None` option values are stripped from request bodies before sending
+- API responses use **snake_case** — dataclasses mirror the raw API shapes, no transformation
+- Error classes: `AutoICDError` (base), `AuthenticationError` (401), `NotFoundError` (404), `RateLimitError` (429)
+- Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
+- API keys start with `sk_`
+- Base URL defaults to `https://autoicdapi.com`, no trailing slash
+- All HTTP goes through the private `_request()` method — single place for auth, timeout, error handling, rate limit parsing
+- Client supports context manager (`with AutoICD(...) as client:`)
+
+## This Is a Marketing Asset
+
+The README, pyproject.toml description, and keywords are **SEO-optimized** to drive traffic to autoicdapi.com. When editing:
+
+- Keep the README rich with examples, use cases, and links back to autoicdapi.com
+- Maintain keyword density in pyproject.toml (icd-10, medical-coding, clinical-nlp, etc.)
+- Use real-looking clinical examples in code samples (they appear in search results)
+- Brand name is **AutoICD API** — always capitalize correctly
+
+## Git Identity
+
+This is a **public repo**. All commits MUST be authored by the AutoICD brand — never use personal or work identities.
+
+Before committing, always use repo-local git config:
+```bash
+git -C /Users/fede/repos/autoicd/sdk-py commit --author="AutoICD <info@autoicdapi.com>"
+```
+
+If creating commits via the CLI, always pass `--author="AutoICD <info@autoicdapi.com>"`.
+
+## Sync with API
+
+The SDK calls the Next.js API routes at `api/src/app/api/v1/`. Any changes to API request/response shapes must be reflected here:
+
+- Route changes → update paths in `client.py`
+- Response shape changes → update dataclasses in `types.py`
+- New endpoints → add method to `AutoICD` or `Codes` class, export types from `__init__.py`
+- Test against live API or local dev server (port 3000) with `base_url="http://localhost:3000"`

autoicd-0.2.0/LICENSE

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

autoicd-0.2.0/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: autoicd
+Version: 0.2.0
+Summary: Official Python SDK for the AutoICD API — clinical text to ICD-10-CM diagnosis codes, powered by AI and medical NLP
+Project-URL: Homepage, https://autoicdapi.com
+Project-URL: Documentation, https://autoicdapi.com/docs
+Project-URL: Repository, https://github.com/fcggamou/autoicd-python
+Project-URL: Issues, https://github.com/fcggamou/autoicd-python/issues
+Author-email: AutoICD <info@autoicdapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: autoicd,clinical-decision-support,clinical-nlp,diagnosis-codes,ehr,emr,health-tech,hipaa,icd-10,icd-10-cm,medical-billing,medical-coding,medical-nlp,phi-deidentification,revenue-cycle-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AutoICD API — Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/autoicd.svg)](https://pypi.org/project/autoicd/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
+
+Official Python SDK for the [AutoICD API](https://autoicdapi.com) — clinical text to ICD-10-CM diagnosis codes, powered by AI and medical NLP.
+
+Single dependency (`httpx`). Works in **Python 3.10+**.
+
+> Built for EHR integrations, health-tech platforms, medical billing, clinical decision support, and revenue cycle management.
+
+---
+
+## Why AutoICD API
+
+| | |
+|---|---|
+| **AI-Powered ICD-10 Coding** | Clinical NLP extracts diagnoses from free-text notes and maps them to ICD-10-CM codes — no manual lookup required |
+| **74,000+ ICD-10-CM Codes** | Full 2025 code set enriched with SNOMED CT synonyms for comprehensive matching |
+| **Negation & Context Detection** | Knows the difference between "patient has diabetes" and "patient denies diabetes" — flags negated, historical, uncertain, and family-history mentions |
+| **PHI De-identification** | HIPAA-compliant anonymization of names, dates, SSNs, phone numbers, emails, addresses, MRNs, and ages |
+| **Confidence Scoring** | Every code match includes a similarity score and confidence level so you can set your own acceptance thresholds |
+| **Spell Correction** | Handles misspellings in clinical text — "diabeties" still maps to the right code |
+| **Fully Typed** | Complete type annotations for all requests and responses |
+
+---
+
+## Install
+
+```bash
+pip install autoicd
+```
+
+<details>
+<summary>uv / poetry / pdm</summary>
+
+```bash
+uv add autoicd
+poetry add autoicd
+pdm add autoicd
+```
+
+</details>
+
+---
+
+## Quick Start
+
+```python
+from autoicd import AutoICD
+
+client = AutoICD(api_key="sk_...")
+
+result = client.code(
+    "Patient has type 2 diabetes and essential hypertension"
+)
+
+for entity in result.entities:
+    print(entity.entity_text, "→", entity.codes[0].code)
+# "type 2 diabetes"       → "E11.9"
+# "essential hypertension" → "I10"
+```
+
+---
+
+## Features
+
+### Automated ICD-10 Medical Coding
+
+Extract diagnosis entities from clinical notes and map them to ICD-10-CM codes. Each entity includes ranked candidates with confidence scores, negation status, and context flags.
+
+```python
+result = client.code(
+    "History of severe COPD with acute exacerbation. Patient denies chest pain."
+)
+
+for entity in result.entities:
+    print(entity.entity_text)
+    print(f"  Negated: {entity.negated}")
+    print(f"  Historical: {entity.historical}")
+    for match in entity.codes:
+        print(
+            f"  {match.code} — {match.description} "
+            f"({match.confidence}, {match.similarity * 100:.1f}%)"
+        )
+```
+
+Fine-tune results with coding options:
+
+```python
+from autoicd import CodeOptions
+
+result = client.code(
+    "Patient presents with acute bronchitis and chest pain",
+    options=CodeOptions(
+        top_k=3,               # Top 3 ICD-10 candidates per entity (default: 5)
+        strategy="merged",     # "individual" or "merged" entity strategy
+        include_negated=False, # Exclude negated conditions from results
+    ),
+)
+```
+
+### ICD-10 Code Search
+
+Search the full ICD-10-CM 2025 code set by description. Perfect for building code lookup UIs, autocomplete fields, and validation workflows.
+
+```python
+results = client.codes.search("diabetes mellitus")
+# results.codes → [CodeDetail(code="E11.9", short_description="...", ...), ...]
+
+from autoicd import SearchOptions
+results = client.codes.search("heart failure", options=SearchOptions(limit=5))
+```
+
+### ICD-10 Code Details
+
+Get full details for any ICD-10-CM code — descriptions, billable status, and indexed terms.
+
+```python
+detail = client.codes.get("E11.9")
+print(detail.code)              # "E11.9"
+print(detail.long_description)  # "Type 2 diabetes mellitus without complications"
+print(detail.is_billable)       # True
+```
+
+### ICD-10 Code Terms & Synonyms
+
+Retrieve all indexed terms and synonyms for a code — includes SNOMED CT mappings and clinical variants.
+
+```python
+terms = client.codes.terms("E11.9")
+for t in terms:
+    print(t.term, f"({t.term_type})")
+# "Type 2 diabetes mellitus without complications" (long_desc)
+# "adult onset diabetes" (synonym)
+# ...
+```
+
+### PHI De-identification
+
+Strip protected health information from clinical notes before storage or analysis. HIPAA-compliant de-identification for names, dates, SSNs, phone numbers, emails, addresses, MRNs, and ages.
+
+```python
+result = client.anonymize(
+    "John Smith, DOB 01/15/1980, MRN 123456, has COPD"
+)
+
+print(result.anonymized_text)
+# "[NAME], DOB [DATE], MRN [MRN], has COPD"
+
+print(result.pii_count)     # 3
+print(result.pii_entities)  # [PIIEntity(text="John Smith", label="NAME", ...), ...]
+```
+
+---
+
+## Use Cases
+
+- **EHR / EMR Integration** — Auto-code clinical notes as providers type, reducing manual coding burden
+- **Medical Billing & RCM** — Accelerate claim submission with accurate ICD-10 codes
+- **Clinical Decision Support** — Map patient conditions to standardized codes for analytics and alerts
+- **Health-Tech SaaS** — Add ICD-10 coding to your platform without building ML infrastructure
+- **Clinical Research** — Extract and standardize diagnoses from unstructured medical records
+- **Insurance & Payer Systems** — Validate and suggest diagnosis codes during claims processing
+- **Telehealth Platforms** — Generate diagnosis codes from visit notes and transcriptions
+
+---
+
+## Error Handling
+
+```python
+from autoicd import (
+    AutoICD,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+)
+
+try:
+    result = client.code("...")
+except AuthenticationError:
+    # Invalid or revoked API key (401)
+    ...
+except RateLimitError as e:
+    # Request limit exceeded (429)
+    print(e.rate_limit.remaining, e.rate_limit.reset_at)
+except NotFoundError:
+    # ICD-10 code not found (404)
+    ...
+```
+
+Rate limit info is available after every request:
+
+```python
+client.code("...")
+print(client.last_rate_limit)
+# RateLimit(limit=1000, remaining=987, reset_at=datetime(...))
+```
+
+---
+
+## Configuration
+
+```python
+client = AutoICD(
+    api_key="sk_...",                   # Required — get yours at https://autoicdapi.com
+    base_url="https://...",             # Default: https://autoicdapi.com
+    timeout=60.0,                       # Default: 30.0 seconds
+    http_client=httpx.Client(...),      # Custom httpx client (for proxies, mTLS, etc.)
+)
+```
+
+Use as a context manager for automatic cleanup:
+
+```python
+with AutoICD(api_key="sk_...") as client:
+    result = client.code("Patient has diabetes")
+```
+
+---
+
+## API Reference
+
+Full REST API documentation at [autoicdapi.com/docs](https://autoicdapi.com/docs).
+
+| Method | Description |
+|--------|-------------|
+| `client.code(text, options?)` | Code clinical text to ICD-10-CM diagnoses |
+| `client.anonymize(text)` | De-identify PHI/PII in clinical text |
+| `client.codes.search(query, options?)` | Search ICD-10-CM codes by description |
+| `client.codes.get(code)` | Get details for an ICD-10-CM code |
+| `client.codes.terms(code)` | Get indexed terms/synonyms for a code |
+
+---
+
+## Types
+
+All request and response types are exported:
+
+```python
+from autoicd import (
+    CodingResponse,
+    CodingEntity,
+    CodeMatch,
+    CodeOptions,
+    CodeDetail,
+    CodeSearchResponse,
+    CodeTermInfo,
+    AnonymizeResponse,
+    PIIEntity,
+    RateLimit,
+    SearchOptions,
+)
+```
+
+---
+
+## Requirements
+
+- **Python 3.10+**
+- An API key from [autoicdapi.com](https://autoicdapi.com)
+
+---
+
+## Links
+
+- [AutoICD API](https://autoicdapi.com) — Homepage and API key management
+- [API Documentation](https://autoicdapi.com/docs) — Full REST API reference
+- [TypeScript SDK](https://www.npmjs.com/package/autoicd) — `npm install autoicd`
+- [ICD-10-CM 2025 Code Set](https://www.cms.gov/medicare/coding-billing/icd-10-codes) — Official CMS reference
+
+---
+
+## License
+
+MIT

autoicd-0.2.0/README.md

@@ -0,0 +1,277 @@
+# AutoICD API — Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/autoicd.svg)](https://pypi.org/project/autoicd/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
+
+Official Python SDK for the [AutoICD API](https://autoicdapi.com) — clinical text to ICD-10-CM diagnosis codes, powered by AI and medical NLP.
+
+Single dependency (`httpx`). Works in **Python 3.10+**.
+
+> Built for EHR integrations, health-tech platforms, medical billing, clinical decision support, and revenue cycle management.
+
+---
+
+## Why AutoICD API
+
+| | |
+|---|---|
+| **AI-Powered ICD-10 Coding** | Clinical NLP extracts diagnoses from free-text notes and maps them to ICD-10-CM codes — no manual lookup required |
+| **74,000+ ICD-10-CM Codes** | Full 2025 code set enriched with SNOMED CT synonyms for comprehensive matching |
+| **Negation & Context Detection** | Knows the difference between "patient has diabetes" and "patient denies diabetes" — flags negated, historical, uncertain, and family-history mentions |
+| **PHI De-identification** | HIPAA-compliant anonymization of names, dates, SSNs, phone numbers, emails, addresses, MRNs, and ages |
+| **Confidence Scoring** | Every code match includes a similarity score and confidence level so you can set your own acceptance thresholds |
+| **Spell Correction** | Handles misspellings in clinical text — "diabeties" still maps to the right code |
+| **Fully Typed** | Complete type annotations for all requests and responses |
+
+---
+
+## Install
+
+```bash
+pip install autoicd
+```
+
+<details>
+<summary>uv / poetry / pdm</summary>
+
+```bash
+uv add autoicd
+poetry add autoicd
+pdm add autoicd
+```
+
+</details>
+
+---
+
+## Quick Start
+
+```python
+from autoicd import AutoICD
+
+client = AutoICD(api_key="sk_...")
+
+result = client.code(
+    "Patient has type 2 diabetes and essential hypertension"
+)
+
+for entity in result.entities:
+    print(entity.entity_text, "→", entity.codes[0].code)
+# "type 2 diabetes"       → "E11.9"
+# "essential hypertension" → "I10"
+```
+
+---
+
+## Features
+
+### Automated ICD-10 Medical Coding
+
+Extract diagnosis entities from clinical notes and map them to ICD-10-CM codes. Each entity includes ranked candidates with confidence scores, negation status, and context flags.
+
+```python
+result = client.code(
+    "History of severe COPD with acute exacerbation. Patient denies chest pain."
+)
+
+for entity in result.entities:
+    print(entity.entity_text)
+    print(f"  Negated: {entity.negated}")
+    print(f"  Historical: {entity.historical}")
+    for match in entity.codes:
+        print(
+            f"  {match.code} — {match.description} "
+            f"({match.confidence}, {match.similarity * 100:.1f}%)"
+        )
+```
+
+Fine-tune results with coding options:
+
+```python
+from autoicd import CodeOptions
+
+result = client.code(
+    "Patient presents with acute bronchitis and chest pain",
+    options=CodeOptions(
+        top_k=3,               # Top 3 ICD-10 candidates per entity (default: 5)
+        strategy="merged",     # "individual" or "merged" entity strategy
+        include_negated=False, # Exclude negated conditions from results
+    ),
+)
+```
+
+### ICD-10 Code Search
+
+Search the full ICD-10-CM 2025 code set by description. Perfect for building code lookup UIs, autocomplete fields, and validation workflows.
+
+```python
+results = client.codes.search("diabetes mellitus")
+# results.codes → [CodeDetail(code="E11.9", short_description="...", ...), ...]
+
+from autoicd import SearchOptions
+results = client.codes.search("heart failure", options=SearchOptions(limit=5))
+```
+
+### ICD-10 Code Details
+
+Get full details for any ICD-10-CM code — descriptions, billable status, and indexed terms.
+
+```python
+detail = client.codes.get("E11.9")
+print(detail.code)              # "E11.9"
+print(detail.long_description)  # "Type 2 diabetes mellitus without complications"
+print(detail.is_billable)       # True
+```
+
+### ICD-10 Code Terms & Synonyms
+
+Retrieve all indexed terms and synonyms for a code — includes SNOMED CT mappings and clinical variants.
+
+```python
+terms = client.codes.terms("E11.9")
+for t in terms:
+    print(t.term, f"({t.term_type})")
+# "Type 2 diabetes mellitus without complications" (long_desc)
+# "adult onset diabetes" (synonym)
+# ...
+```
+
+### PHI De-identification
+
+Strip protected health information from clinical notes before storage or analysis. HIPAA-compliant de-identification for names, dates, SSNs, phone numbers, emails, addresses, MRNs, and ages.
+
+```python
+result = client.anonymize(
+    "John Smith, DOB 01/15/1980, MRN 123456, has COPD"
+)
+
+print(result.anonymized_text)
+# "[NAME], DOB [DATE], MRN [MRN], has COPD"
+
+print(result.pii_count)     # 3
+print(result.pii_entities)  # [PIIEntity(text="John Smith", label="NAME", ...), ...]
+```
+
+---
+
+## Use Cases
+
+- **EHR / EMR Integration** — Auto-code clinical notes as providers type, reducing manual coding burden
+- **Medical Billing & RCM** — Accelerate claim submission with accurate ICD-10 codes
+- **Clinical Decision Support** — Map patient conditions to standardized codes for analytics and alerts
+- **Health-Tech SaaS** — Add ICD-10 coding to your platform without building ML infrastructure
+- **Clinical Research** — Extract and standardize diagnoses from unstructured medical records
+- **Insurance & Payer Systems** — Validate and suggest diagnosis codes during claims processing
+- **Telehealth Platforms** — Generate diagnosis codes from visit notes and transcriptions
+
+---
+
+## Error Handling
+
+```python
+from autoicd import (
+    AutoICD,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+)
+
+try:
+    result = client.code("...")
+except AuthenticationError:
+    # Invalid or revoked API key (401)
+    ...
+except RateLimitError as e:
+    # Request limit exceeded (429)
+    print(e.rate_limit.remaining, e.rate_limit.reset_at)
+except NotFoundError:
+    # ICD-10 code not found (404)
+    ...
+```
+
+Rate limit info is available after every request:
+
+```python
+client.code("...")
+print(client.last_rate_limit)
+# RateLimit(limit=1000, remaining=987, reset_at=datetime(...))
+```
+
+---
+
+## Configuration
+
+```python
+client = AutoICD(
+    api_key="sk_...",                   # Required — get yours at https://autoicdapi.com
+    base_url="https://...",             # Default: https://autoicdapi.com
+    timeout=60.0,                       # Default: 30.0 seconds
+    http_client=httpx.Client(...),      # Custom httpx client (for proxies, mTLS, etc.)
+)
+```
+
+Use as a context manager for automatic cleanup:
+
+```python
+with AutoICD(api_key="sk_...") as client:
+    result = client.code("Patient has diabetes")
+```
+
+---
+
+## API Reference
+
+Full REST API documentation at [autoicdapi.com/docs](https://autoicdapi.com/docs).
+
+| Method | Description |
+|--------|-------------|
+| `client.code(text, options?)` | Code clinical text to ICD-10-CM diagnoses |
+| `client.anonymize(text)` | De-identify PHI/PII in clinical text |
+| `client.codes.search(query, options?)` | Search ICD-10-CM codes by description |
+| `client.codes.get(code)` | Get details for an ICD-10-CM code |
+| `client.codes.terms(code)` | Get indexed terms/synonyms for a code |
+
+---
+
+## Types
+
+All request and response types are exported:
+
+```python
+from autoicd import (
+    CodingResponse,
+    CodingEntity,
+    CodeMatch,
+    CodeOptions,
+    CodeDetail,
+    CodeSearchResponse,
+    CodeTermInfo,
+    AnonymizeResponse,
+    PIIEntity,
+    RateLimit,
+    SearchOptions,
+)
+```
+
+---
+
+## Requirements
+
+- **Python 3.10+**
+- An API key from [autoicdapi.com](https://autoicdapi.com)
+
+---
+
+## Links
+
+- [AutoICD API](https://autoicdapi.com) — Homepage and API key management
+- [API Documentation](https://autoicdapi.com/docs) — Full REST API reference
+- [TypeScript SDK](https://www.npmjs.com/package/autoicd) — `npm install autoicd`
+- [ICD-10-CM 2025 Code Set](https://www.cms.gov/medicare/coding-billing/icd-10-codes) — Official CMS reference
+
+---
+
+## License
+
+MIT