Rules Engine SDK

The SDK bridges the gap between TwinFyRx's suspecting rules (structured JSON logic) and your existing claims data warehouse. It ships two core components:

The SDK is delivered as a Python package during onboarding. No external dependencies are required beyond the standard library.

from twinfyrx_sdk import RuleExecutor, SchemaConfig

Map your claims schema to TwinFyRx's canonical model. Every table and column name is overridable — the SDK rewrites generated SQL to match your naming conventions.

from twinfyrx_sdk import SchemaConfig

config = SchemaConfig(
    # Table names
    rx_claims_table="pharmacy_claims",
    members_table="member_enrollment",
    providers_table="provider_directory",
    medical_claims_table="medical_claims",
    ndc_atc_table="ndc_atc_crosswalk",

    # Rx claims columns
    rx_claim_id="claim_id",
    rx_member_id="member_id",
    rx_ndc="ndc_code",
    rx_fill_date="date_of_service",
    rx_prescriber_npi="prescriber_npi",

    # Member columns
    mb_member_id="member_id",
    mb_gender="sex",
    mb_age="current_age",

    # Provider columns
    pr_npi="npi",
    pr_specialty="taxonomy_description",

    # Medical claims columns
    mc_member_id="member_id",
    mc_icd10_code="diagnosis_code",
    mc_procedure_code="cpt_code",
    mc_service_date="service_date",

    # NDC-ATC crosswalk columns
    na_ndc="ndc",
    na_atc_code="atc_code",
)

The core execution engine. Takes structured rule logic (JSON) from the TwinFyRx API and produces either executable SQL or in-memory evaluation results.

from twinfyrx_sdk import RuleExecutor, SchemaConfig

executor = RuleExecutor(schema=SchemaConfig(...))

# Fetch rules from the API
import requests
resp = requests.get(
    "https://api.twinfyrx.com/v1/drugs/617314/suspecting-rules",
    headers={"X-API-Key": "your_key"}
)
rules = resp.json()["rules"]

# Generate SQL for each rule
for rule in rules:
    sql = executor.generate_sql(
        rule_id=rule["rule_id"],
        icd10_code=rule["icd10_code"],
        rule_logic=rule["rule_logic"],
        rule_strength=rule["rule_strength"],
        confidence=rule["confidence"],
        drug_rxcui=617314,
        drug_ndcs=["00071015523", "00071015540"],
    )
    if sql:
        print(sql)

Each rule produces a SELECT statement that returns one row per qualifying rx claim. The output schema is consistent across all rule categories.

Output Columns

Rule Categories & SQL Patterns

For real-time or streaming scenarios, evaluate rules directly against a claim context dictionary without generating SQL.

result = executor.evaluate(
    rule_logic={
        "type": "prescriber_specialty",
        "specialty_pattern": "Endocrinology"
    },
    context={
        "gender": "M",
        "age": 58,
        "prescriber_specialty": "Endocrinology",
        "concurrent_atc": ["A10BA02", "C10AA05"],
        "prior_icd10": ["E11.9", "I10"],
        "prior_cpt": [],
    }
)

print(result)  # True — prescriber is an endocrinologist

When multiple rules fire for the same member × diagnosis, the SDK aggregates confidence scores using noisy-OR probability combination. This prevents double-counting while allowing multiple weak signals to compound into strong ones.

The SDK ships with a synthetic claims generator for testing rule execution before connecting to production data. Generate realistic claims data with controlled demographics and prescribing patterns.

from twinfyrx_sdk.synthetic_claims_generator import generate_claims

# Generate synthetic claims for a drug
claims_df = generate_claims(
    drug_rxcui=617314,
    drug_ndcs=["00071015523", "00071015540"],
    n_members=500,
)

# claims_df contains:
#   - rx_claims: pharmacy claims with fill dates, NDCs, prescriber NPIs
#   - members: member demographics (age, gender)
#   - providers: prescriber specialties
#   - medical_claims: diagnosis and procedure history
#   - ndc_atc: NDC-to-ATC crosswalk for concurrent Rx detection

Run the full end-to-end pipeline against synthetic data to validate rule coverage, confidence distributions, and output format before deploying against your claims warehouse.