Metadata-Version: 2.4
Name: carevalue-claims-ml
Version: 0.3.1
Summary: Open Source Healthcare ML Models for Cost Reduction and Outcome Improvement
Author: Amol Kodan
License-Expression: MIT
Project-URL: Homepage, https://github.com/amolkodan/value-based-care-machine-learning-models
Project-URL: Documentation, https://github.com/amolkodan/value-based-care-machine-learning-models#readme
Project-URL: Repository, https://github.com/amolkodan/value-based-care-machine-learning-models
Project-URL: Issues, https://github.com/amolkodan/value-based-care-machine-learning-models/issues
Project-URL: Changelog, https://github.com/amolkodan/value-based-care-machine-learning-models/blob/main/CHANGELOG.md
Keywords: healthcare,value-based-care,machine-learning,claims-analytics,bundled-payments,episode-of-care,patient-journey,pharmacy-benefits,risk-modeling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: psycopg2-binary>=2.9
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: joblib>=1.3
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: ruff>=0.1.7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: core
Provides-Extra: episodes
Provides-Extra: policy
Provides-Extra: benchmarks
Provides-Extra: careops
Dynamic: license-file

# Open Source Healthcare ML Models for Cost Reduction and Outcome Improvement

**VBC Intelligence OS** (distributed as `carevalue-claims-ml`) is an open-source machine learning platform built for healthcare organizations that need to reduce cost of care and improve patient outcomes across value-based and bundled payment contracts.

It is also a cloud-agnostic analytics stack for clinically interpretable signals derived from **longitudinal medical, institutional, and pharmacy claims**, unified into a coherent **patient journey** view for risk, cost, utilization pattern detection, and governance-ready model artifacts.

The platform targets payer actuarial and VBC operations teams, health system analytics, and care-management programs that require member-month feature stores, multi-model prediction (risk, cost, temporal behavior, uplift proxies), **episode-level financial and clinical-density scoring**, policy simulation, and agentic recommendation orchestration with audit trails.

## Healthcare claims ontology and glossary

- **Eligibility month**: covered member period used as denominator for PMPM analytics.
- **Claim header**: bundled treatment packages claim envelope including claim type, servicing provider, and aggregate allowed amount.
- **Claim line**: service-level granularity (CPT/HCPCS, revenue code, POS) used for utilization signatures.
- **ICD-10 diagnosis**: coded condition context used for morbidity proxies.
- **PMPM**: per member per month spend benchmark.
- **Attribution**: assignment of member responsibility to clinician group.
- **Risk stratification**: prospective identification of high-cost/high-need cohorts.
- **Care gap intervention**: operational outreach action (navigation, pharmacy follow-up, digital nudge).
- **Episode of care / bundled episode**: a time-bounded cluster of services (often anchored on an anchor procedure or admission) used for **episode-based payment** (e.g., BPCI, commercial bundles, specialty surgical episodes).
- **CPT / HCPCS**: procedure and supply codes on professional and outpatient claims; used for **procedural intensity** and bundle eligibility.
- **NDC**: National Drug Code on **pharmacy claims**; distinct NDC counts support **polypharmacy** and **medication therapy complexity** proxies.
- **Place of service (POS)**: setting of care on claim lines; supports site-of-care and **avoidable acute** utilization patterning when combined with diagnosis context.
- **Revenue codes**: institutional claim-line revenue centers; useful for **inpatient vs ancillary** intensity within an admission episode.
- **HCC-adjacent signals**: ICD-10-driven **comorbidity breadth** is a structural input to risk-adjustment-style analytics (this repository does not compute CMS-HCC coefficients; it exposes **condition count and trajectory** features for modeling).
- **Care fragmentation**: patterns of many small encounters or cross-modality spikes; member-month velocity features help ML detect **acceleration** in utilization.

## Integrated patient journey, patterns, and predictive signals

The ML pipeline is designed to **discover patterns** across modalities and time:

- **Claims + diagnosis + pharmacy**: merge professional/institutional lines with pharmacy fills (`journey merge`, `merge_medical_and_pharmacy_claims`) so models see **one longitudinal timeline** per member.
- **Utilization velocity**: member-month claim volume and allowed spend (`journey monthly-features`, `monthly_utilization_features`) surface **trend breaks**, seasonality, and post-acute ramps.
- **Pharmacy signals**: distinct NDC counts per member (`distinct_ndc_count_by_member`) support **polypharmacy risk** and MTM-style prioritization features.
- **Clinical and procedural density**: distinct ICD-10 and CPT/HCPCS counts (`diagnosis_morbidity_breadth_by_member`, `procedure_intensity_by_member`) enrich **episode scoring** and risk models.
- **Bundled episodes**: gap-based episode construction and scoring (`episodes build` / `score`) produce **episode allowed**, span, **financial intensity**, optional **ICD/CPT breadth**, and **within-cohort severity percentiles** for contract and CMMI-style analytics.
- **ML bundled episode engine**: train **multi-label** episode-family attribution on unified medical and pharmacy lines using **ICD-10**, **CPT/HCPCS**, **NDC**, **care_domain**, and spend buckets; emit **multi-attribution** (one claim line can attach to several episode families with calibrated probabilities); **materialize** time-bounded episode instances per family with gap rules; roll up **rendering NPI** (`rendering_npi`) to episodes by allowed amount. Industry episode groupers increasingly combine rule-based logic with ML over high-dimensional coding vocabularies ([Certilytics overview](https://www.certilytics.com/news-insights/ml-and-clinical-episode-grouping/)); this module ships a transparent **sklearn** baseline you can train on your own bundled history and extend.

These features feed the existing **model suite** (risk, cost, temporal, uplift, anomaly, ranking) so teams can predict **high-cost probability**, **expected spend bands**, **behavior shifts**, and **intervention ROI proxies** while preserving subgroup fairness and model-card documentation.

## End-to-end architecture

```mermaid
flowchart LR
claimsRaw[MedicalAndInstitutionalClaims] --> journeyMerge[JourneyUnification]
pharmacyRaw[PharmacyClaims] --> journeyMerge
diagRaw[DiagnosisLines] --> memberMonth[MemberMonthETL]
journeyMerge --> episodeBuild[BundledEpisodeBuilder]
journeyMerge --> memberMonth
memberMonth --> featureStore[FeatureAndLabelBuilder]
episodeBuild --> featureStore
featureStore --> modelSuite[RiskCostTemporalUpliftModels]
modelSuite --> evalHub[EvaluationFairnessLeaderboard]
modelSuite --> policySim[PolicySimulation]
modelSuite --> agentOrch[AgenticOrchestrator]
agentOrch --> auditTrail[RecommendationAuditTrail]
agentOrch --> contractJson[DeterministicJSONContracts]
evalHub --> reports[ReportsAndModelCards]
policySim --> reports
auditTrail --> reports
reports --> databricksTrack[OptionalDatabricksLakehouseTrack]
```

## Data model and synthetic benchmark generation

### Core data assets

- `data/sample/claims_header.csv`
- `data/sample/claims_line.csv`
- `data/sample/diagnosis.csv`
- `data/sample/eligibility.csv`
- `data/sample/member_context.csv`
- `data/sample/interventions.csv`

### Synthetic design assumptions

- High-risk cohorts are injected with heavier claim intensity and cost burden.
- Temporal drift is introduced into benchmark trend factors for realistic backtesting stress.
- SDoH and dual-status proxy features provide equity/fairness analysis surfaces.
- Intervention propensity and engagement response fields support uplift and policy simulation.

Synthetic data is for benchmarking and reproducibility, not epidemiologic prevalence estimation.

## Feature and label specification

- **Feature windows**: rolling utilization and spend signatures over trailing months.
- **Lag features**: prior month allowed amount and utilization indicators.
- **Label horizon**: future allowed sum over configured months.
- **High-cost label**: quantile-based thresholding on future allowed sum for risk stratification.
- **Leakage controls**: temporal split semantics in temporal model variants and rolling feature construction.

## Model portfolio

### Risk intelligence
- Baseline calibrated high-cost risk model.
- Advanced stacked risk ensemble with uncertainty-aware triage scoring.
- Temporal risk model with time-series cross-validation.
- Risk trajectory segmentation model for cohort planning.
- Fairness-aware risk calibration variant for protected-population review.

### Cost intelligence
- Baseline cost regression.
- Quantile interval model (q10, q50, q90) for uncertainty-aware forecasting.
- Anomaly-based cost spike detector for outlier surveillance.
- Contract-sensitive ranking model for payer intervention sequencing.

### Intervention intelligence
- Uplift proxy model for outreach prioritization.
- Stronger uplift variant for treatment-response stratification.
- Contract impact projection including expected PMPM delta and shared-savings proxy.

### Policy intelligence
- Budget-constrained policy simulation for outreach allocation.
- Safety envelope with abstain and max outreach logic.
- Insurance contract scenario simulation (`optimistic`, `base`, `stress`).
- Policy constraint enforcement for shared-savings, downside caps, and risk corridor behavior.

## Real-World Insurance Use Cases

These examples show how payer analytics and value-based care operations teams can apply the current stack in real workflows.

### 1) Prospective high-cost member stratification for case management
- **Business problem**: Identify members likely to become high-cost in the next horizon before avoidable spend accelerates.
- **How this repo supports it**: High-cost risk models plus temporal validation (`models train-suite` and risk outputs).
- **Operational output**: Ranked member risk scores and model leaderboard artifacts.
- **Expected KPI impact**: Better risk capture precision, lower avoidable PMPM growth, improved care manager targeting yield.

### 2) Outreach queue optimization under fixed nurse capacity
- **Business problem**: Care teams cannot contact every flagged member each month.
- **How this repo supports it**: Policy simulation and recommendation guardrails (`policy simulate`, agent max outreach logic).
- **Operational output**: Capacity-constrained intervention list with abstain paths for overflow.
- **Expected KPI impact**: Higher interventions per FTE and stronger budget adherence.

### 3) Intervention prioritization using uplift-style targeting
- **Business problem**: Not all high-risk members respond equally to outreach.
- **How this repo supports it**: Uplift proxy model and `careGapAgent` eligibility gating.
- **Operational output**: Action-specific recommendations (`care_navigation_call`, `pharmacy_followup`, `digital_nudge`, abstain).
- **Expected KPI impact**: Higher intervention precision and improved ROI of care-management spend.

### 4) PMPM trend surveillance and contract early warning
- **Business problem**: Payers need early signal when PMPM trend drifts above target in shared-risk contracts.
- **How this repo supports it**: Benchmarks + summary reporting + contract impact agent outputs.
- **Operational output**: PMPM and trend outputs with expected contract delta projections.
- **Expected KPI impact**: Faster variance mitigation and improved forecastability of year-end performance.

### 5) Shared-savings and downside-risk forecasting
- **Business problem**: Finance and actuarial teams need scenario-level visibility into savings likelihood.
- **How this repo supports it**: Contract scoring, cost forecasts, and policy simulation outputs.
- **Operational output**: Expected PMPM delta and shared-savings impact proxies by recommended action cohort.
- **Expected KPI impact**: Better reserve planning and improved contracting strategy decisions.

### 6) Fairness-aware triage for vulnerable populations
- **Business problem**: Risk models can under-serve vulnerable groups without explicit equity checks.
- **How this repo supports it**: Subgroup fairness slicing and vulnerable-member protection rules in orchestration.
- **Operational output**: Slice-level evaluation plus adjusted recommendation behavior for protected cohorts.
- **Expected KPI impact**: Reduced fairness deltas and stronger compliance posture.

### 7) Data quality gating before model-driven operations
- **Business problem**: Bad upstream data can produce unstable intervention queues.
- **How this repo supports it**: `dataQualityAgent` drift/missingness/schema anomaly checks.
- **Operational output**: Quality alerts and auditable gate status before recommendations are consumed.
- **Expected KPI impact**: Fewer operational misfires caused by data defects.

### 8) Utilization management signal enrichment
- **Business problem**: UM teams need member-level risk context to prioritize outreach or review workflows.
- **How this repo supports it**: Risk + cost + temporal model stack and member-month feature lineage.
- **Operational output**: Structured risk and expected cost signals aligned to member-month records.
- **Expected KPI impact**: Earlier high-risk intervention opportunity and better alignment between UM and care management.

### 9) Pharmacy and chronic condition follow-up planning
- **Business problem**: Medication adherence and chronic burden patterns need proactive outreach stratification.
- **How this repo supports it**: Synthetic member context fields, intervention history, and `careGapAgent` action mapping.
- **Operational output**: Follow-up queues for pharmacy and care-navigation actions with rationale traces.
- **Expected KPI impact**: Better chronic population engagement and reduced acute utilization leakage.

### 10) Audit-ready recommendation governance for payer operations
- **Business problem**: Clinical operations and compliance teams need traceability for each recommendation.
- **How this repo supports it**: Deterministic JSON contracts, recommendation-only mode, and `why`/`why_not` audit logs.
- **Operational output**: Reproducible handoff artifacts and audit CSV outputs for governance review.
- **Expected KPI impact**: Improved model governance readiness and lower operational risk.

### 11) Contract-specific cohort strategy design
- **Business problem**: Different payer contracts require different intervention thresholds and action mixes.
- **How this repo supports it**: Configurable thresholds and scoring workflows with contract-aware reporting context.
- **Operational output**: Cohort-specific recommendation sets and benchmark comparisons per contract frame.
- **Expected KPI impact**: Better contract-level strategy fit and stronger medical cost containment.

### 12) Human-in-the-loop decision support for care operations
- **Business problem**: Teams need AI support without autonomous clinical action.
- **How this repo supports it**: Recommendation-only guardrails, abstain behavior, and optional deterministic LLM post-processing.
- **Operational output**: Decision-support recommendations for coordinator review, not autonomous execution.
- **Expected KPI impact**: Faster operational triage while preserving clinical governance controls.

### 13) Value-based care cost reduction optimizer
- **Business problem**: Prioritize members where interventions are most likely to reduce total cost of care under contract constraints.
- **How this repo supports it**: `vbc_cost_optimizer` family and contract policy enforcement/scenario simulation.
- **Operational output**: `reports/recommendations_policy_enforced.csv`, `reports/policy_scenarios.json`.
- **Expected KPI impact**: Higher cost containment efficiency and improved shared-savings potential.

### 14) Outcome improvement optimizer
- **Business problem**: Improve outcomes while balancing cost by targeting members with greatest expected intervention benefit.
- **How this repo supports it**: `outcome_improvement_optimizer` and blended cost-outcome policy metrics.
- **Operational output**: recommendation set with outcome deltas and scenario-level tradeoff scores.
- **Expected KPI impact**: Better quality proxy performance without uncontrolled spend growth.

### 15) Claims behavior prediction from longitudinal claims
- **Business problem**: Detect utilization behavior shifts early (e.g., rising avoidable ED/IP patterns).
- **How this repo supports it**: `claims_behavior_predictor` and temporal claims behavior features.
- **Operational output**: behavior-sensitive risk scores and trend-aware ranking outputs.
- **Expected KPI impact**: Earlier interventions and reduced avoidable utilization.

### 16) Provider advisory action model
- **Business problem**: Translate member predictions into actionable provider guidance.
- **How this repo supports it**: `provider_advisory_ranker` plus provider advisory fields in agentic outputs.
- **Operational output**: provider advisory action + rationale fields in recommendation and audit outputs.
- **Expected KPI impact**: Improved provider engagement and measurable actionability of predictive analytics.

### Use Case to Artifact Map

- High-cost stratification -> `reports/leaderboard.csv`, model artifact metadata JSON
- Outreach prioritization -> `reports/agent_recommendations.csv`
- Audit and compliance review -> `reports/agent_audit.csv`, `reports/agent_handoff_contract.json`
- Policy scenario planning -> `reports/policy_scenarios.json`
- Contract-constrained recommendation output -> `reports/recommendations_policy_enforced.csv`
- Cost reduction optimizer -> `models/*vbc_cost_optimizer*`, `reports/policy_scenarios.json`
- Outcome improvement optimizer -> `models/*outcome_improvement_optimizer*`, `reports/agent_recommendations.csv`
- Claims behavior predictor -> `models/*claims_behavior_predictor*`, `reports/leaderboard.csv`
- Provider advisory actions -> `reports/agent_recommendations.csv`, `reports/agent_audit.csv`

## Agentic decision orchestration

### Specialized healthcare agents

- `riskTriageAgent`: risk + uncertainty + fairness-aware triage priority.
- `careGapAgent`: intervention recommendation with uplift and eligibility gates.
- `contractImpactAgent`: PMPM and shared-savings impact projection.
- `dataQualityAgent`: drift, missingness, and schema anomaly checks.

### Stage narrative (operational flow)

1. `dataQualityAgent` checks schema and missingness before decisions.
2. `riskTriageAgent` creates risk-priority cohorts with uncertainty weighting.
3. `careGapAgent` proposes intervention classes with eligibility and uplift constraints.
4. `contractImpactAgent` estimates PMPM and shared-savings deltas.
5. Guardrails enforce recommendation-only behavior and abstain paths.
6. Deterministic contracts and audit traces are emitted for governance review.

### Safety guardrails

- Recommendation-only mode enabled by default.
- No autonomous clinical action pathways.
- Low-confidence abstain behavior.
- Outreach cap enforcement.
- Vulnerable member protection rules.

### Memory, contracts, and auditability

- Shared context store for quality metrics and guardrail state.
- Deterministic JSON handoff contracts between orchestration stages.
- Audit logs with `why` and `why_not` rationale fields per recommendation.

## Evaluation and governance

- Ranking metrics: ROC-AUC, average precision.
- Cost proxy metrics: MAE-aligned utility checks.
- Fairness slices: age bands, sex proxy, dual-status proxy.
- Artifact outputs:
  - leaderboard CSV
  - model card JSON
  - agent audit CSV
  - policy simulation JSON

## CLI command matrix

```bash
# Core data and feature workflows
carevalue-ml db init
carevalue-ml data generate --output data/generated
carevalue-ml data load --input-dir data/generated
carevalue-ml features build

# Modeling workflows
carevalue-ml models train
carevalue-ml models train-suite --suite maximal
carevalue-ml models train-use-cases
carevalue-ml models evaluate reports/predictions.csv
carevalue-ml models leaderboard reports/predictions.csv --model-name risk_v2 --run-id run_2026

# Policy and agentic workflows
carevalue-ml policy simulate reports/predictions.csv --budget 100
carevalue-ml policy scenario reports/agent_recommendations.csv
carevalue-ml policy enforce reports/agent_recommendations.csv --outreach-budget 100
carevalue-ml agents run reports/predictions.csv --output-path reports/agent_recommendations.csv
carevalue-ml agents validate-contract reports/agent_handoff_contract.json
carevalue-ml agents evaluate reports/agent_recommendations.csv reports/agent_recommendations_baseline.csv --budget 100

# Patient journey and episode analytics (unify medical + optional pharmacy, then engineer features)
carevalue-ml journey merge data/sample/claims_header.csv reports/journey_unified.csv
# With pharmacy file: add --pharmacy-path your_rx_claims.csv (same member_id, service_date, allowed_amount columns)
carevalue-ml journey monthly-features reports/journey_unified.csv
carevalue-ml episodes build reports/journey_unified.csv --archetype orthopedic --output-path reports/episodes.csv
carevalue-ml episodes score reports/episodes.csv --diagnosis-code-col diagnosis_code --procedure-code-col procedure_code

# ML episode definitions + multi-label attribution + materialized episodes (see section below)
carevalue-ml episodes ml-prep-training-from-gaps reports/journey_unified.csv --output-path reports/claims_labeled_bootstrap.csv
carevalue-ml episodes ml-learn-definitions reports/claims_labeled_bootstrap.csv --episode-family-col episode_family --output-path reports/episode_ml_definitions.json
carevalue-ml episodes ml-train reports/claims_labeled_bootstrap.csv --episode-labels-col episode_family --output-path models/bundled_episode_attribution.joblib
carevalue-ml episodes ml-run reports/journey_unified.csv models/bundled_episode_attribution.joblib --output-dir reports/episodes_ml
```

### Example insurer workflows

```bash
# Flow A: Risk + cost intelligence for actuarial review
carevalue-ml models train-suite --suite maximal
carevalue-ml models leaderboard reports/predictions.csv --model-name actuarial_suite --run-id r2026q1

# Flow B: Capacity-constrained care operations
carevalue-ml agents run reports/predictions.csv --run-id r2026q1 --contract-id DEMO
carevalue-ml policy enforce reports/agent_recommendations.csv --outreach-budget 120

# Flow C: Contract scenario planning
carevalue-ml policy scenario reports/agent_recommendations.csv
carevalue-ml agents evaluate reports/agent_recommendations.csv reports/agent_recommendations_baseline.csv --budget 120

# Flow D: Cost reduction + outcome improvement use-case pack
carevalue-ml models train-use-cases
carevalue-ml policy enforce reports/agent_recommendations.csv --outreach-budget 120
carevalue-ml policy scenario reports/agent_recommendations.csv
```

## Databricks-optional deployment track

The runtime remains vendor-neutral. Optional templates in `config/databricks` provide:

- bronze/silver/gold lakehouse mapping
- MLflow-compatible run tagging strategy
- agent-run lineage conventions and scalable simulation guidance

## Reproducibility and open-source operations

- Deterministic synthetic generation via seeded configs.
- Model artifacts include metadata sidecars with run ID, task, cohort, and feature hash.
- CI includes lint and test validation.
- Contribution and governance docs:
  - `CONTRIBUTING.md`
  - `MODEL_CARDS.md`
  - `ROADMAP.md`
  - `SECURITY.md`

## Clinical safety and scope boundary

- This repository supports analytics and decision support research workflows.
- It does not deliver autonomous clinical diagnosis or treatment.
- Keep human-in-the-loop review before operational intervention workflows.
- Use synthetic or de-identified data only in development/test contexts.

## License

MIT

## Multi-PyPI Expansion (Additive Roadmap)

This repository can publish multiple focused Python libraries while keeping the same codebase and preserving backward compatibility.

### 1) `carevalue-core-ml`
- **What it does**: trains and scores risk, cost, temporal, and uplift models on member-month features.
- **Who uses it**: payer/provider data science teams and analytics engineering teams.
- **Why it helps adoption**: creates a clean entry point for organizations that only need core ML without policy or agent complexity.

### 2) `carevalue-episodes`
- **What it does**: builds bundled episodes from claims and predicts episode-level cost, quality risk, and variance.
- **Who uses it**: bundled-payment programs, contracting teams, actuarial analysts.
- **Why it helps adoption**: supports one of the fastest-growing VBC payment motions with episode-native ML workflows.

### 3) `carevalue-policy-sim`
- **What it does**: simulates shared-savings, downside-risk, and bundled-payment outcomes from model outputs.
- **Who uses it**: finance strategy teams, value transformation leaders, contracting operations.
- **Why it helps adoption**: translates model scores into contract-ready decisions and financial planning scenarios.

### 4) `carevalue-benchmarks`
- **What it does**: ships national benchmark packs with synthetic population archetypes and standardized KPI reports.
- **Who uses it**: public-sector pilots, researchers, implementation partners, health plans evaluating tools.
- **Why it helps adoption**: enables apples-to-apples evaluation and easier procurement/comparison conversations.

### 5) `carevalue-agentic-care`
- **What it does**: orchestrates explainable triage and intervention recommendations with governance guardrails and audit logs.
- **Who uses it**: care management operations and platform engineering teams.
- **Why it helps adoption**: provides implementation-ready, human-in-the-loop operational pathways.


## How People Will Use These Libraries

### Typical workflow
1. Install `carevalue-core-ml` and train baseline/advanced models.
2. Add `carevalue-episodes` for bundled episode construction and forecasting.
3. Add `carevalue-policy-sim` to run budget and contract scenarios.
4. Add `carevalue-benchmarks` to compare against national synthetic archetypes.
5. Add `carevalue-agentic-care` for operational triage recommendations and auditable handoffs.

### Minimal install examples
```bash
pip install carevalue-core-ml
pip install carevalue-episodes
pip install carevalue-policy-sim
pip install carevalue-benchmarks
pip install carevalue-agentic-care
```

### Example usage shape (target API direction)
```python
from carevalue_core_ml import train_suite, score_population
from carevalue_episodes import build_episodes, score_episodes
from carevalue_policy_sim import run_contract_scenarios

models = train_suite(claims_df, eligibility_df, suite="maximal")
member_scores = score_population(models, member_month_df)
episodes = build_episodes(claims_df, archetype="orthopedic")
episode_scores = score_episodes(episodes)
scenario_report = run_contract_scenarios(member_scores, episode_scores, profile="bundled_base")
```

## ML bundled episode engine (train, define, attribute, multi-assign)

This ships in the main package as `carevalue_claims_ml.bundled_episode_engine` and in `vbc_intel_episodes` for the umbrella namespace.

### How it works

1. **Labels**: Provide claim-level rows with an `episode_family` (or semicolon-separated `episode_labels` for true multi-label training). If you only have raw claims, `training_frame_from_gap_bundles` / CLI `episodes ml-prep-training-from-gaps` adds `episode_id` and `episode_family` from the existing deterministic gap bundler so you can bootstrap a first model, then refine labels from analyst or grouper exports.
2. **Definitions**: `learn_episode_definitions_from_labels` summarizes frequent **ICD prefixes**, **CPT/HCPCS prefixes**, and **NDC prefixes** per episode family — a contract-friendly companion to the ML weights (JSON via `EpisodeCodeDefinitions.save`).
3. **Model**: `fit_bundled_episode_attribution_model` builds a **HashingVectorizer** over per-line feature text (domain, full codes, prefixes, log-bucketed allowed amount) plus **OneVsRest(LogisticRegression)** for multi-label episode families. Save/load with `BundledEpisodeAttributionModel.save` / `.load` (joblib).
4. **Scoring**: `predict_multi_attribution` returns a **long** table: each qualifying `(claim_row_index, episode_family, attribution_probability)` above `min_probability`, so one line can appear in several episode families (**multi-attribution**).
5. **Episode instances**: `materialize_gap_episodes_per_family` applies a **gap day** rule separately within each `(member_id, episode_family)` trajectory so you get concrete `episode_instance_id` rows and claim lines tagged to those instances. **Attributed NPI** is the rendering NPI with the largest summed allowed amount on lines in that instance (column `rendering_npi` when present).

### Python example

```python
from pathlib import Path

import pandas as pd
from carevalue_claims_ml.journey_signals import merge_medical_and_pharmacy_claims
from carevalue_claims_ml.bundled_episode_engine import (
    learn_episode_definitions_from_labels,
    fit_bundled_episode_attribution_model,
    run_bundled_episode_engine,
    training_frame_from_gap_bundles,
)

medical = pd.read_csv("medical_claim_lines.csv")   # member_id, service_date, allowed_amount, diagnosis_code, procedure_code, …
pharmacy = pd.read_csv("pharmacy_claim_lines.csv")  # member_id, service_date, allowed_amount, ndc, …
unified = merge_medical_and_pharmacy_claims(medical, pharmacy)

# Optional bootstrap labels from gap episodes, then replace with grouper-labeled data when available
labeled = training_frame_from_gap_bundles(unified, archetype="orthopedic", window_days=90)
defs = learn_episode_definitions_from_labels(labeled, episode_family_col="episode_family")
defs.save(Path("reports/episode_ml_definitions.json"))

model = fit_bundled_episode_attribution_model(
    labeled,
    episode_labels_col="episode_family",  # or episode_labels_list_col="episode_labels" for "ortho;chf" style cells
)
model.save(Path("models/bundled_episode_attribution.joblib"))

out = run_bundled_episode_engine(unified, model, min_probability=0.12, window_days=90)
# out["claim_episode_attribution"]  — multi-attribution long file
# out["episodes"]                     — episode_instance_id rollups with attributed_npi
# out["claims_in_episodes"]          — line-level rows tied to episode_instance_id
```

### What you can do with it

- **Train on historical bundles** (BPCI-style windows, commercial bundles, or internal episode grouper output) and reuse the model to **score new claims** before final grouper runs.
- **Publish code-episode definition tables** for actuarial and contracting stakeholders alongside the model artifact.
- **Multi-attribution reporting** for comorbid or overlapping episodes (same claim line above threshold for more than one family).
- **Provider episode attribution** for episodes that mix professional, institutional, and pharmacy lines when `rendering_npi` is populated on medical rows.

### Column expectations

Training and scoring expect at least `member_id`, `service_date`, `allowed_amount`. Stronger signal when you include optional `care_domain`, `diagnosis_code`, `procedure_code`, `ndc`, and `rendering_npi` (names configurable via `claim_row_to_feature_text` / `claim_row_to_feature_text_kwargs` in code).

## First MVP Packaging Sequence

To move toward publication safely and additively:

1. Extend `pyproject.toml` metadata and extras for package boundaries.
2. Stabilize public exports in `src/carevalue_claims_ml/__init__.py`.
3. Add grouped CLI commands in `src/carevalue_claims_ml/cli.py` for core/episodes/policy/benchmarks/agents.
4. Publish multi-package usage docs in this `README.md`.
5. Add release-grade checks in `.github/workflows/ci.yml` for build, wheel validation, and smoke tests.

## VBC Intelligence OS Namespace (Implemented Scaffold)

The repository now includes a branded umbrella with additive sublibrary namespaces while preserving existing imports and CLI behavior.

### Umbrella
- **VBC Intelligence OS**

### Sublibrary import namespaces
- `vbc_intel_core`
- `vbc_intel_episodes`
- `vbc_intel_policy`
- `vbc_intel_benchmarks`
- `vbc_intel_careops`

### Quick import examples
```python
from vbc_intel_core import (
    merge_medical_and_pharmacy_claims,
    monthly_utilization_features,
    train_model_suite,
)
from vbc_intel_episodes import (
    EPISODE_ARCHETYPES,
    BundledEpisodeAttributionModel,
    build_bundled_episodes,
    fit_bundled_episode_attribution_model,
    learn_episode_definitions_from_labels,
    run_bundled_episode_engine,
    score_episode_risk,
)
from vbc_intel_policy import run_policy_scenarios, simulate_policy
from vbc_intel_benchmarks import calculate_pmpm
from vbc_intel_careops import run_agentic_pipeline
```

### CLI discovery
```bash
carevalue-ml libraries
carevalue-ml episodes --help
carevalue-ml journey --help
carevalue-ml benchmarks --help
carevalue-ml careops --help
```

## Publish to PyPI

Step-by-step instructions (Trusted Publishing, manual `twine`, versioning): see [`PUBLISHING.md`](PUBLISHING.md).

After release: `pip install carevalue-claims-ml`
